feat(api): add branch reset functionality

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 20
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-030e47a1bfd79a657974f5beddd685940ec04b1aa1786c3b2cb0f4610ad2b42c.yml
-openapi_spec_hash: 33b337af28bcc1c9aa1a5218acf2a7fe
-config_hash: 6b235571b537b4814a33a1008b443e36
+configured_endpoints: 21
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-ec93b81b2d599edd19449bae3cb40bdb17890908d97cc867e36425a45e491c16.yml
+openapi_spec_hash: fe8b8fd7782670698fecfe2fcc05f693
+config_hash: 626376bcac885a796930ef32094b8387

api.md

@@ -34,6 +34,7 @@ Methods:
 - <code title="get /v0/projects/{project}/branches">client.projects.branches.<a href="./src/resources/projects/branches.ts">list</a>({ ...params }) -> BranchListResponsesPage</code>
 - <code title="delete /v0/projects/{project}/branches/{branch}">client.projects.branches.<a href="./src/resources/projects/branches.ts">delete</a>(branch, { ...params }) -> unknown</code>
 - <code title="put /v0/projects/{project}/branches/{branch}/rebase">client.projects.branches.<a href="./src/resources/projects/branches.ts">rebase</a>(branch, { ...params }) -> ProjectBranch</code>
+- <code title="put /v0/projects/{project}/branches/{branch}/reset">client.projects.branches.<a href="./src/resources/projects/branches.ts">reset</a>(branch, { ...params }) -> ProjectBranch</code>
 
 ## Configs
 

packages/mcp-server/README.md

@@ -278,6 +278,11 @@ The following tools are available in this MCP server.
   The branch is rebased onto the `base` branch or commit SHA, inheriting
   any config and custom code changes.
 
+- `reset_projects_branches` (`write`): Reset a project branch.
+
+  If `branch` === `main`, the branch is reset to `target_config_sha`. Otherwise, the
+  branch is reset to `main`.
+
 ### Resource `projects.configs`:
 
 - `retrieve_projects_configs` (`read`):

packages/mcp-server/src/code-tool-worker.ts

@@ -50,6 +50,7 @@ const fuse = new Fuse(
     'client.projects.branches.delete',
     'client.projects.branches.list',
     'client.projects.branches.rebase',
+    'client.projects.branches.reset',
     'client.projects.branches.retrieve',
     'client.projects.configs.guess',
     'client.projects.configs.retrieve',

packages/mcp-server/src/tools/index.ts

@@ -13,6 +13,7 @@ import retrieve_projects_branches from './projects/branches/retrieve-projects-br
 import list_projects_branches from './projects/branches/list-projects-branches';
 import delete_projects_branches from './projects/branches/delete-projects-branches';
 import rebase_projects_branches from './projects/branches/rebase-projects-branches';
+import reset_projects_branches from './projects/branches/reset-projects-branches';
 import retrieve_projects_configs from './projects/configs/retrieve-projects-configs';
 import guess_projects_configs from './projects/configs/guess-projects-configs';
 import create_builds from './builds/create-builds';
@@ -39,6 +40,7 @@ addEndpoint(retrieve_projects_branches);
 addEndpoint(list_projects_branches);
 addEndpoint(delete_projects_branches);
 addEndpoint(rebase_projects_branches);
+addEndpoint(reset_projects_branches);
 addEndpoint(retrieve_projects_configs);
 addEndpoint(guess_projects_configs);
 addEndpoint(create_builds);

packages/mcp-server/src/tools/projects/branches/reset-projects-branches.ts

@@ -0,0 +1,47 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@stainless-api/sdk-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Stainless from '@stainless-api/sdk';
+
+export const metadata: Metadata = {
+  resource: 'projects.branches',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'put',
+  httpPath: '/v0/projects/{project}/branches/{branch}/reset',
+};
+
+export const tool: Tool = {
+  name: 'reset_projects_branches',
+  description:
+    'Reset a project branch.\n\nIf `branch` === `main`, the branch is reset to `target_config_sha`. Otherwise, the\nbranch is reset to `main`.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      project: {
+        type: 'string',
+      },
+      branch: {
+        type: 'string',
+      },
+      target_config_sha: {
+        type: 'string',
+        description:
+          'The commit SHA to reset the main branch to. Required if resetting the main branch; disallowed otherwise.',
+      },
+    },
+    required: ['project', 'branch'],
+  },
+  annotations: {
+    idempotentHint: true,
+  },
+};
+
+export const handler = async (client: Stainless, args: Record<string, unknown> | undefined) => {
+  const { branch, ...body } = args as any;
+  return asTextContentResult(await client.projects.branches.reset(branch, body));
+};
+
+export default { metadata, tool, handler };

src/resources/projects/branches.ts

@@ -75,6 +75,24 @@ export class Branches extends APIResource {
       ...options,
     });
   }
+
+  /**
+   * Reset a project branch.
+   *
+   * If `branch` === `main`, the branch is reset to `target_config_sha`. Otherwise,
+   * the branch is reset to `main`.
+   */
+  reset(
+    branch: string,
+    params: BranchResetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ProjectBranch> {
+    const { project = this._client.project, target_config_sha } = params ?? {};
+    return this._client.put(path`/v0/projects/${project}/branches/${branch}/reset`, {
+      query: { target_config_sha },
+      ...options,
+    });
+  }
 }
 
 export type BranchListResponsesPage = Page<BranchListResponse>;
@@ -236,6 +254,19 @@ export interface BranchRebaseParams {
   base?: string;
 }
 
+export interface BranchResetParams {
+  /**
+   * Path param:
+   */
+  project?: string;
+
+  /**
+   * Query param: The commit SHA to reset the main branch to. Required if resetting
+   * the main branch; disallowed otherwise.
+   */
+  target_config_sha?: string;
+}
+
 export declare namespace Branches {
   export {
     type ProjectBranch as ProjectBranch,
@@ -247,5 +278,6 @@ export declare namespace Branches {
     type BranchListParams as BranchListParams,
     type BranchDeleteParams as BranchDeleteParams,
     type BranchRebaseParams as BranchRebaseParams,
+    type BranchResetParams as BranchResetParams,
   };
 }

src/resources/projects/index.ts

@@ -10,6 +10,7 @@ export {
   type BranchListParams,
   type BranchDeleteParams,
   type BranchRebaseParams,
+  type BranchResetParams,
   type BranchListResponsesPage,
 } from './branches';
 export {

src/resources/projects/projects.ts

@@ -11,6 +11,7 @@ import {
   BranchListResponse,
   BranchListResponsesPage,
   BranchRebaseParams,
+  BranchResetParams,
   BranchRetrieveParams,
   Branches,
   ProjectBranch,
@@ -164,6 +165,7 @@ export declare namespace Projects {
     type BranchListParams as BranchListParams,
     type BranchDeleteParams as BranchDeleteParams,
     type BranchRebaseParams as BranchRebaseParams,
+    type BranchResetParams as BranchResetParams,
   };
 
   export {

tests/api-resources/projects/branches.test.ts

@@ -101,4 +101,24 @@ describe('resource branches', () => {
   test.skip('rebase: required and optional params', async () => {
     const response = await client.projects.branches.rebase('branch', { project: 'project', base: 'base' });
   });
+
+  // Prism tests are disabled
+  test.skip('reset: only required params', async () => {
+    const responsePromise = client.projects.branches.reset('branch', { project: 'project' });
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('reset: required and optional params', async () => {
+    const response = await client.projects.branches.reset('branch', {
+      project: 'project',
+      target_config_sha: 'target_config_sha',
+    });
+  });
 });