release-skill 0.1.1

package/src/adapters/contract.mjs

@@ -0,0 +1,214 @@
+/**
+ * Adapter unified interface contract for release-skill.
+ *
+ * Every platform adapter (git-github, npm, plugin-marketplace) must implement
+ * the four lifecycle methods: preflight, execute, observe, verify.
+ *
+ * Adapters return structured observations and NEVER infer success from
+ * command exit codes alone. A checkpoint is successful only when `observe`
+ * matches the frozen expected commit/tag/version/digest in the release plan.
+ *
+ * All write methods MUST require `context.externalWritesAuthorized === true`.
+ *
+ * @module adapters/contract
+ */
+
+import { ReleaseError, AUTH_MISSING } from '../core/errors.mjs';
+
+/**
+ * Action status values in the action lifecycle.
+ * @enum {string}
+ */
+export const ActionStatus = Object.freeze({
+  PENDING: 'PENDING',
+  PREFLIGHT_PASSED: 'PREFLIGHT_PASSED',
+  PREFLIGHT_FAILED: 'PREFLIGHT_FAILED',
+  EXECUTING: 'EXECUTING',
+  EXECUTED: 'EXECUTED',
+  EXECUTE_FAILED: 'EXECUTE_FAILED',
+  OBSERVED: 'OBSERVED',
+  OBSERVE_MISMATCH: 'OBSERVE_MISMATCH',
+  VERIFIED: 'VERIFIED',
+  VERIFY_FAILED: 'VERIFY_FAILED',
+  SKIPPED: 'SKIPPED',
+});
+
+/**
+ * Standard action types across all adapters.
+ * @enum {string}
+ */
+export const ActionType = Object.freeze({
+  // git-github adapter
+  GIT_PUSH: 'git-push',
+  GIT_TAG: 'git-tag',
+  GITHUB_RELEASE: 'github-release',
+
+  // npm adapter
+  NPM_PACK: 'npm-pack',
+  NPM_PUBLISH: 'npm-publish',
+
+  // snapshot push
+  PUSH_SNAPSHOT: 'push-snapshot',
+
+  // plugin-marketplace adapter
+  PLUGIN_MANIFEST_VALIDATE: 'plugin-manifest-validate',
+  PLUGIN_INSTALL_CHECK: 'plugin-install-check',
+
+  // consumer marketplace install (production)
+  CLAUDE_MARKETPLACE_INSTALL: 'claude-marketplace-install',
+  CODEX_MARKETPLACE_INSTALL: 'codex-marketplace-install',
+});
+
+/**
+ * Create a structured adapter result object.
+ *
+ * @param {Object} params
+ * @param {string} params.actionType - The ActionType of the action.
+ * @param {string} params.status - One of ActionStatus values.
+ * @param {Object} [params.observation] - Observed remote state (commit, tag, version, digest, etc.).
+ * @param {string} [params.error] - Error message if status indicates failure.
+ * @param {Object} [params.details] - Additional machine-readable details.
+ * @returns {AdapterResult}
+ */
+export function createResult({ actionType, status, observation, error, details }) {
+  return Object.freeze({
+    actionType,
+    status,
+    observation: observation ?? null,
+    error: error ?? null,
+    details: details ?? null,
+  });
+}
+
+/**
+ * Check that external writes are authorized. Throws if not.
+ *
+ * @param {AdapterContext} context
+ * @param {string} actionType - The action being guarded.
+ * @throws {ReleaseError} AUTH_MISSING if not authorized.
+ */
+export function assertWritesAuthorized(context, actionType) {
+  if (context.externalWritesAuthorized !== true) {
+    throw new ReleaseError(
+      AUTH_MISSING,
+      `External write action '${actionType}' requires externalWritesAuthorized === true`,
+      { actionType }
+    );
+  }
+}
+
+/**
+ * Check that isolated consumer writes are authorized. Throws if not.
+ * Used by marketplace install adapters which only write to isolated
+ * consumer directories, not to remote services.
+ *
+ * @param {AdapterContext} context
+ * @param {string} actionType - The action being guarded.
+ * @throws {ReleaseError} AUTH_MISSING if not authorized.
+ */
+export function assertIsolatedConsumerWritesAuthorized(context, actionType) {
+  if (context.isolatedConsumerWritesAuthorized !== true) {
+    throw new ReleaseError(
+      AUTH_MISSING,
+      `Marketplace install action '${actionType}' requires isolatedConsumerWritesAuthorized === true`,
+      { actionType }
+    );
+  }
+}
+
+/**
+ * Validate that an observation matches the expected state from a frozen plan.
+ *
+ * The expected object comes from the release plan's externalActions[].expected.
+ * An observation matches when every key present in expected has the same value
+ * in observation. Extra keys in observation are allowed.
+ *
+ * @param {Object} expected - Expected state from the frozen plan.
+ * @param {Object} observation - Observed state from the remote.
+ * @returns {{ matches: boolean, mismatches: string[] }}
+ */
+export function matchObservation(expected, observation) {
+  if (!expected || !observation) {
+    return { matches: false, mismatches: ['missing expected or observation'] };
+  }
+
+  const mismatches = [];
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    if (observation[key] !== expectedValue) {
+      mismatches.push(`${key}: expected ${JSON.stringify(expectedValue)}, got ${JSON.stringify(observation[key])}`);
+    }
+  }
+
+  return { matches: mismatches.length === 0, mismatches };
+}
+
+/**
+ * Adapter interface type documentation (not enforced at runtime, but all
+ * adapters must follow this shape):
+ *
+ * @typedef {Object} AdapterResult
+ * @property {string} actionType - The action type.
+ * @property {string} status - ActionStatus value.
+ * @property {Object|null} observation - Observed remote state.
+ * @property {string|null} error - Error message if failed.
+ * @property {Object|null} details - Additional context.
+ *
+ * @typedef {Object} AdapterContext
+ * @property {boolean} externalWritesAuthorized - Must be true for remote write actions.
+ * @property {boolean} [isolatedConsumerWritesAuthorized] - Must be true for marketplace install actions.
+ * @property {Object} plan - The frozen release plan.
+ * @property {Object} baseline - The captured git baseline.
+ * @property {string} root - The project root directory.
+ * @property {string} [runDir] - The evidence run directory.
+ * @property {Object} [env] - Environment variables.
+ *
+ * @typedef {Object} Adapter
+ * @property {string} name - Adapter display name.
+ * @property {string[]} actionTypes - Supported ActionType values.
+ * @property {(action: Object, context: AdapterContext) => Promise<AdapterResult>} preflight
+ * @property {(action: Object, context: AdapterContext) => Promise<AdapterResult>} execute
+ * @property {(action: Object, context: AdapterContext) => Promise<AdapterResult>} observe
+ * @property {(action: Object, context: AdapterContext) => Promise<AdapterResult>} verify
+ */
+
+/**
+ * Create an adapter registry that maps action types to adapter instances.
+ *
+ * @param {Adapter[]} adapters - Array of adapter instances.
+ * @returns {{ getAdapter(actionType: string): Adapter, getAll(): Adapter[] }}
+ */
+export function createAdapterRegistry(adapters) {
+  const actionMap = new Map();
+
+  for (const adapter of adapters) {
+    for (const actionType of adapter.actionTypes) {
+      if (actionMap.has(actionType)) {
+        throw new Error(
+          `Duplicate action type '${actionType}' registered by both '${actionMap.get(actionType).name}' and '${adapter.name}'`
+        );
+      }
+      actionMap.set(actionType, adapter);
+    }
+  }
+
+  return Object.freeze({
+    /**
+     * Get the adapter responsible for a given action type.
+     * @param {string} actionType
+     * @returns {Adapter}
+     * @throws {Error} if no adapter handles this action type.
+     */
+    getAdapter(actionType) {
+      const adapter = actionMap.get(actionType);
+      if (!adapter) {
+        throw new Error(`No adapter registered for action type '${actionType}'`);
+      }
+      return adapter;
+    },
+
+    /** Get all registered adapters. */
+    getAll() {
+      return [...new Set(actionMap.values())];
+    },
+  });
+}

package/src/adapters/git-github.mjs

@@ -0,0 +1,214 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import {
+  ActionStatus,
+  ActionType,
+  assertWritesAuthorized,
+  createResult,
+  matchObservation,
+} from './contract.mjs';
+import { resolveFrozenPath, verifyFrozenDirectoryStructure } from '../snapshot/frozen.mjs';
+import { githubRepositoryUrl } from './push-snapshot.mjs';
+
+const execFile = promisify(execFileCb);
+const NAME = 'git-github';
+
+async function run(command, args, options = {}) {
+  return execFile(command, args, {
+    shell: false,
+    encoding: 'utf8',
+    timeout: 120_000,
+    ...options,
+  });
+}
+
+function isNotFound(error) {
+  const text = `${error?.stdout ?? ''}\n${error?.stderr ?? ''}\n${error?.message ?? ''}`;
+  return /(?:HTTP\s+404|\bstatus(?: code)?\s*[:=]?\s*404\b)/i.test(text);
+}
+
+function ghRepo(action) {
+  const host = action.githubHost ?? 'github.com';
+  githubRepositoryUrl(action.repo, host);
+  return host === 'github.com' ? action.repo : `${host}/${action.repo}`;
+}
+
+function validateOid(value) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{40,64}$/.test(value)) {
+    throw new Error('commit must be a full hexadecimal git object id');
+  }
+}
+
+async function validateTagAction(action, context, exec) {
+  if (!action.tag || !action.repo || !action.gitObjectDir) {
+    throw new Error('git-tag requires tag, repo, gitObjectDir, and commit');
+  }
+  validateOid(action.commit);
+  const gitDir = await resolveFrozenPath(context.root, action.gitObjectDir, 'frozen git object directory');
+  await verifyFrozenDirectoryStructure(gitDir, 'frozen git object directory');
+  await exec('git', ['check-ref-format', `refs/tags/${action.tag}`], { shell: false });
+  const { stdout: commitOut } = await exec('git', ['--git-dir', gitDir, 'rev-parse', action.commit], { shell: false });
+  if (commitOut.trim() !== action.commit) throw new Error('planned commit is missing from frozen git objects');
+  return { gitDir, remoteUrl: githubRepositoryUrl(action.repo, action.githubHost) };
+}
+
+async function readRemoteTag(action, remoteUrl, exec) {
+  const { stdout } = await exec(
+    'git',
+    ['ls-remote', '--tags', remoteUrl, `refs/tags/${action.tag}`],
+    { shell: false },
+  );
+  return stdout.trim().split(/\s+/)[0] ?? '';
+}
+
+export function createGitGithubAdapter(deps = {}) {
+  const exec = deps.exec ?? run;
+  return Object.freeze({
+    name: NAME,
+    actionTypes: Object.freeze([ActionType.GIT_PUSH, ActionType.GIT_TAG, ActionType.GITHUB_RELEASE]),
+
+    async preflight(action, context) {
+      try {
+        if (action.actionType === ActionType.GIT_PUSH) {
+          const { stdout } = await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: context.root, shell: false });
+          const expected = action.branch ?? context.plan?.baseline?.defaultBranch ?? 'main';
+          if (stdout.trim() !== expected) throw new Error(`current branch does not match ${expected}`);
+        } else if (action.actionType === ActionType.GIT_TAG) {
+          const { remoteUrl } = await validateTagAction(action, context, exec);
+          const existing = await readRemoteTag(action, remoteUrl, exec);
+          if (existing) throw new Error(`remote tag already exists: ${action.tag}; human intervention required`);
+        } else if (action.actionType === ActionType.GITHUB_RELEASE) {
+          if (!action.repo || !action.tag) throw new Error('github-release requires repo, tag, and commit');
+          validateOid(action.commit);
+          await exec('gh', ['auth', 'status'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
+          await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.id'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          }).catch((err) => {
+            throw new Error(`cannot access GitHub repository ${action.repo}: ${err.message}`);
+          });
+          try {
+            await exec('gh', ['api', `repos/${action.repo}/releases/tags/${action.tag}`], {
+              cwd: context.root,
+              shell: false,
+              env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+            });
+            throw new Error(`GitHub Release already exists for ${action.tag}; human intervention required`);
+          } catch (err) {
+            if (err.message?.includes('already exists')) throw err;
+            if (!isNotFound(err)) throw new Error(`cannot determine GitHub Release uniqueness: ${err.message}`);
+          }
+        } else {
+          throw new Error(`unsupported action type: ${action.actionType}`);
+        }
+        return createResult({ actionType: action.actionType, status: ActionStatus.PREFLIGHT_PASSED });
+      } catch (err) {
+        return createResult({ actionType: action.actionType, status: ActionStatus.PREFLIGHT_FAILED, error: err.message });
+      }
+    },
+
+    async execute(action, context) {
+      assertWritesAuthorized(context, action.actionType);
+      try {
+        if (action.actionType === ActionType.GIT_PUSH) {
+          await exec('git', ['push', action.remote ?? 'origin', action.branch ?? 'main'], {
+            cwd: context.root,
+            shell: false,
+          });
+        } else if (action.actionType === ActionType.GIT_TAG) {
+          const { gitDir, remoteUrl } = await validateTagAction(action, context, exec);
+          let localTag = '';
+          try {
+            const result = await exec('git', ['--git-dir', gitDir, 'rev-parse', `refs/tags/${action.tag}`], { shell: false });
+            localTag = result.stdout.trim();
+          } catch {
+            localTag = '';
+          }
+          if (localTag && localTag !== action.commit) throw new Error('local frozen tag conflicts with planned commit');
+          if (!localTag) {
+            await exec('git', ['--git-dir', gitDir, 'tag', action.tag, action.commit], { shell: false });
+          }
+          await exec('git', [
+            '--git-dir', gitDir,
+            'push',
+            `--force-with-lease=refs/tags/${action.tag}:`,
+            remoteUrl,
+            `refs/tags/${action.tag}`,
+          ], { shell: false });
+        } else if (action.actionType === ActionType.GITHUB_RELEASE) {
+          await exec('gh', [
+            'release', 'create', action.tag,
+            '--repo', ghRepo(action),
+            '--verify-tag',
+            '--title', action.name ?? `Release ${action.tag}`,
+            '--notes', action.notes ?? `Release ${action.tag}`,
+          ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+        } else {
+          throw new Error(`unsupported action type: ${action.actionType}`);
+        }
+        return createResult({ actionType: action.actionType, status: ActionStatus.EXECUTED });
+      } catch (err) {
+        return createResult({ actionType: action.actionType, status: ActionStatus.EXECUTE_FAILED, error: err.message });
+      }
+    },
+
+    async observe(action, context) {
+      try {
+        let observation;
+        if (action.actionType === ActionType.GIT_PUSH) {
+          const { stdout } = await exec('git', ['ls-remote', '--heads', action.remote ?? 'origin', action.branch ?? 'main'], {
+            cwd: context.root,
+            shell: false,
+          });
+          observation = { remoteCommit: stdout.trim().split(/\s+/)[0] ?? '' };
+        } else if (action.actionType === ActionType.GIT_TAG) {
+          const { remoteUrl } = await validateTagAction(action, context, exec);
+          observation = { tag: action.tag, commit: await readRemoteTag(action, remoteUrl, exec) };
+        } else if (action.actionType === ActionType.GITHUB_RELEASE) {
+          const { stdout } = await exec('gh', [
+            'release', 'view', action.tag,
+            '--repo', ghRepo(action),
+            '--json', 'tagName,url',
+          ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+          const release = JSON.parse(stdout);
+          const commitResult = await exec(
+            'gh',
+            ['api', `repos/${action.repo}/git/ref/tags/${action.tag}`, '--jq', '.object.sha'],
+            { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } },
+          );
+          observation = { tag: release.tagName, commit: commitResult.stdout.trim(), releaseUrl: release.url };
+        } else {
+          throw new Error(`unsupported action type: ${action.actionType}`);
+        }
+        return createResult({ actionType: action.actionType, status: ActionStatus.OBSERVED, observation });
+      } catch (err) {
+        if (action.actionType === ActionType.GITHUB_RELEASE && isNotFound(err)) {
+          return createResult({
+            actionType: action.actionType,
+            status: ActionStatus.OBSERVED,
+            observation: { exists: false },
+          });
+        }
+        return createResult({ actionType: action.actionType, status: ActionStatus.OBSERVED, observation: {}, error: err.message });
+      }
+    },
+
+    async verify(action, context) {
+      const observed = await this.observe(action, context);
+      if (observed.error) return createResult({ actionType: action.actionType, status: ActionStatus.VERIFY_FAILED, observation: observed.observation, error: observed.error });
+      const comparison = matchObservation(action.expected ?? {}, observed.observation);
+      return createResult({
+        actionType: action.actionType,
+        status: comparison.matches ? ActionStatus.VERIFIED : ActionStatus.VERIFY_FAILED,
+        observation: observed.observation,
+        error: comparison.matches ? null : comparison.mismatches.join('; '),
+      });
+    },
+  });
+}