@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/api-contracts/pull-requests.js

@@ -0,0 +1,323 @@
+'use strict';
+
+const { PR_ACTIONS } = require('../pr-action');
+const { EXECUTION_TARGET_IDS } = require('../pr-fix-target');
+const { PR_FIX_CAUSE } = require('../shared');
+
+const PR_REFERENCE_FORMATS = Object.freeze([
+  'GitHub PR URL',
+  'Azure DevOps PR URL',
+  'github:owner/repo#number',
+  'ado:org/project/repo#number',
+]);
+
+function negativeTest(seam) {
+  return [{
+    strategy: 'reject-invalid-input-before-side-effect',
+    expectedStatus: '4xx',
+    seam,
+  }];
+}
+
+function auditedBody(fields, options = {}) {
+  return {
+    audit: 'audited',
+    body: { policy: 'required', fields },
+    aliases: options.aliases || [],
+    constraints: options.constraints || [],
+    negativeTests: negativeTest(options.seam || 'handler'),
+  };
+}
+
+module.exports = {
+  owner: 'pull-requests',
+  routes: [
+    'GET /api/pull-requests',
+    'GET /api/prs/<id>',
+    'POST /api/pull-requests/link',
+    'POST /api/pr-action',
+    'POST /api/pr-action/fix',
+    'POST /api/pr-action/fix-target/forget',
+    'POST /api/pr-action/track',
+    'POST /api/pr-action/offer-create-pr',
+    'POST /api/pr-action/prepare-create-pr-worktree',
+    'POST /api/pr-action/cleanup-create-pr-worktree',
+    'POST /api/pull-requests/observe',
+    'POST /api/pull-requests/delete',
+    'POST /api/pull-requests/clear-paused-cause',
+    'POST /api/pull-requests/clear-build-fix-ineffective',
+    'POST /api/pull-requests/clear-worktree-held-pause',
+    'POST /api/issues/create',
+  ],
+  overrides: {
+    'GET /api/pull-requests': {
+      audit: 'audited',
+    },
+    'GET /api/prs/<id>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{
+          name: 'id',
+          type: 'string',
+          required: true,
+          semanticFormat: 'pr-reference',
+          allowedFormats: [
+            'positive bare number',
+            'github:owner/repo#number',
+            'ado:org/project/repo#number',
+          ],
+        }],
+      },
+      negativeTests: negativeTest('live PR fetch'),
+    },
+    'POST /api/pull-requests/link': auditedBody([
+      {
+        name: 'url',
+        type: 'pr-reference',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS,
+      },
+      { name: 'title', type: 'string', required: false, maxLength: 120 },
+      {
+        name: 'project',
+        type: 'string',
+        required: false,
+        allowedValuesSource: 'config.projects[].name',
+      },
+      { name: 'contextOnly', type: 'boolean', required: false },
+      { name: 'context', type: 'string|object', required: false, maxBytes: 16384 },
+      {
+        name: 'workItemId',
+        type: 'string',
+        required: false,
+        allowedValuesSource: 'tracked work_items.id',
+      },
+    ], {
+      seam: 'platform metadata fetch and tracked PR store',
+      constraints: [
+        {
+          kind: 'project-scope-match',
+          fields: ['url', 'project'],
+        },
+        {
+          kind: 'tracked-work-item-link',
+          fields: ['project', 'workItemId', 'context.workItemId'],
+          conflictStatus: 409,
+        },
+      ],
+    }),
+    'POST /api/pr-action': auditedBody([
+      {
+        name: 'url',
+        type: 'pr-reference',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS,
+      },
+      {
+        name: 'action',
+        type: 'string',
+        required: true,
+        allowedValues: PR_ACTIONS,
+        allowedValuesSource: 'engine/pr-action.PR_ACTIONS',
+      },
+      { name: 'execute', type: 'boolean', required: false, default: false },
+      { name: 'draftOnly', type: 'boolean', required: false, default: false },
+    ], {
+      seam: 'PR fetch, comment post, and direct LLM call',
+      constraints: [{
+        kind: 'requires-value',
+        when: { field: 'draftOnly', equals: true },
+        field: 'action',
+        value: 'comment',
+      }],
+    }),
+    'POST /api/pr-action/fix': auditedBody([
+      {
+        name: 'url',
+        type: 'pr-reference',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS,
+      },
+      {
+        name: 'target',
+        type: 'string',
+        required: false,
+        allowedValues: EXECUTION_TARGET_IDS,
+        allowedValuesSource: 'engine/pr-fix-target.EXECUTION_TARGET_IDS',
+      },
+      { name: 'remember', type: 'boolean', required: false, default: false },
+      { name: 'reprompt', type: 'boolean', required: false, default: false },
+    ], {
+      seam: 'execution-target preference store and executor routing',
+      constraints: [
+        { kind: 'requires-field', when: { field: 'remember', equals: true }, field: 'target' },
+        { kind: 'mutually-exclusive', fields: ['target', 'reprompt'] },
+      ],
+    }),
+    'POST /api/pr-action/fix-target/forget': auditedBody([
+      {
+        name: 'url',
+        type: 'pr-reference',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS,
+      },
+    ], { seam: 'execution-target preference store' }),
+    'POST /api/pr-action/track': auditedBody([
+      {
+        name: 'url',
+        type: 'pr-reference',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS,
+      },
+    ], { seam: 'tracked PR enrollment store' }),
+    'POST /api/pr-action/offer-create-pr': auditedBody([
+      {
+        name: 'project',
+        type: 'string',
+        required: true,
+        allowedValuesSource: 'config.projects[].name',
+      },
+      { name: 'branch', type: 'git-ref', required: false, maxLength: 256 },
+      { name: 'contextOnly', type: 'boolean', required: false, default: false },
+    ], { seam: 'git status' }),
+    'POST /api/pr-action/prepare-create-pr-worktree': auditedBody([
+      {
+        name: 'project',
+        type: 'string',
+        required: true,
+        allowedValuesSource: 'config.projects[].name',
+      },
+      { name: 'branch', type: 'git-ref', required: false, maxLength: 256 },
+    ], { seam: 'git fetch and worktree creation' }),
+    'POST /api/pr-action/cleanup-create-pr-worktree': auditedBody([
+      {
+        name: 'project',
+        type: 'string',
+        required: true,
+        allowedValuesSource: 'config.projects[].name',
+      },
+      {
+        name: 'worktreePath',
+        type: 'absolute-path',
+        required: true,
+        ownership: 'engine marker source=cc-create-pr and matching project',
+      },
+    ], { seam: 'worktree removal' }),
+    'POST /api/pull-requests/observe': auditedBody([
+      { name: 'host', type: 'string', required: true, allowedValues: ['github', 'ado'] },
+      {
+        name: 'slug',
+        type: 'string',
+        required: true,
+        shapeByHost: {
+          github: 'owner/repo',
+          ado: 'org/project/repo',
+        },
+      },
+      {
+        name: 'number',
+        type: 'integer',
+        required: true,
+        min: 1,
+        max: Number.MAX_SAFE_INTEGER,
+      },
+      { name: 'contextOnly', type: 'boolean', required: false },
+      { name: 'observe', type: 'boolean', required: false, deprecated: true },
+    ], {
+      seam: 'tracked PR store',
+      aliases: [{
+        name: 'observe',
+        canonical: 'contextOnly',
+        location: 'body',
+        transform: 'boolean-inverse',
+      }],
+      constraints: [{
+        kind: 'one-of',
+        fields: ['contextOnly', 'observe'],
+        minPresent: 1,
+        precedence: ['contextOnly', 'observe'],
+      }],
+    }),
+    'POST /api/pull-requests/delete': auditedBody([
+      {
+        name: 'id',
+        type: 'tracked-pr-reference',
+        required: true,
+        allowedFormats: [
+          'github:owner/repo#number',
+          'ado:org/project/repo#number',
+          'PR-number',
+          'positive bare number',
+        ],
+      },
+      {
+        name: 'project',
+        type: 'string',
+        required: false,
+        allowedValuesSource: 'config.projects[].name',
+      },
+    ], { seam: 'tracked PR tombstone store' }),
+    'POST /api/pull-requests/clear-paused-cause': auditedBody([
+      {
+        name: 'prId',
+        type: 'canonical-pr-id',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS.slice(2),
+      },
+      {
+        name: 'cause',
+        type: 'string',
+        required: true,
+        allowedValues: Object.values(PR_FIX_CAUSE),
+        allowedValuesSource: 'engine/shared.PR_FIX_CAUSE',
+      },
+    ], { seam: 'tracked PR pause store' }),
+    'POST /api/pull-requests/clear-build-fix-ineffective': auditedBody([
+      {
+        name: 'prId',
+        type: 'canonical-pr-id',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS.slice(2),
+      },
+      {
+        name: 'headSha',
+        type: 'hex-commit-id',
+        required: false,
+        minLength: 7,
+        maxLength: 64,
+      },
+    ], {
+      seam: 'tracked PR pause store',
+      constraints: [{
+        kind: 'optimistic-match',
+        field: 'headSha',
+        conflictStatus: 409,
+      }],
+    }),
+    'POST /api/pull-requests/clear-worktree-held-pause': auditedBody([
+      {
+        name: 'prId',
+        type: 'canonical-pr-id',
+        required: true,
+        allowedFormats: PR_REFERENCE_FORMATS.slice(2),
+      },
+    ], { seam: 'tracked PR pause store' }),
+    'POST /api/issues/create': auditedBody([
+      { name: 'title', type: 'string', required: true, minLength: 1, maxLength: 256 },
+      {
+        name: 'description',
+        type: 'string',
+        required: false,
+        maxLength: 65536,
+      },
+      {
+        name: 'labels',
+        type: 'string|string[]',
+        required: false,
+        maxItems: 20,
+        itemMaxLength: 50,
+      },
+    ], { seam: 'GitHub label fetch and issue post' }),
+  },
+};