release-skill 0.6.2 → 0.7.0

package/schemas/release-run.schema.json

@@ -43,7 +43,8 @@
         "PARTIAL",
         "BLOCKED",
         "DISTRIBUTING",
-        "DISTRIBUTED"
+        "DISTRIBUTED",
+        "NEEDS_INPUT"
       ],
       "description": "Current status of the run"
     },
@@ -55,7 +56,8 @@
         "publish",
         "reconcile",
         "verify",
-        "distribute"
+        "distribute",
+        "postverify"
       ],
       "description": "The command that initiated this run"
     },
@@ -133,7 +135,8 @@
               "codebuddy-marketplace-install",
               "set-default-branch",
               "distribute-probe",
-              "distribute-mirror"
+              "distribute-mirror",
+              "postpublish-hook"
             ],
             "description": "Type of external action"
           },
@@ -149,9 +152,10 @@
               "PASSED_AUTOMATIC",
               "PASSED_MANUAL",
               "NOT_REQUIRED_UNCHANGED",
-              "NO_CHANGE"
+              "NO_CHANGE",
+              "AWAITING_APPROVAL"
             ],
-            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push)"
+            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push; AWAITING_APPROVAL = requiresApproval postPublish hook 尚无 checkpoint 批准，v0.6.3 R1)"
           },
           "preObserve": {
             "type": "string",
@@ -621,7 +625,8 @@
             "enum": [
               "reconcile",
               "verify",
-              "distribute"
+              "distribute",
+              "postverify"
             ]
           }
         },

package/src/adapters/distribute-git.mjs

@@ -50,6 +50,12 @@ import {
   createResult,
 } from './contract.mjs';
 import { ReleaseError, GATE_FAILED, REMOTE_CONFLICT, REMOTE_UNAVAILABLE } from '../core/errors.mjs';
+import {
+  checkGitRemoteUrl,
+  describeGitRemoteUrlFailure,
+  isAllowedGitRemoteUrl,
+  redactUrlCredentialsIfPresent,
+} from '../core/git-url-policy.mjs';
 
 const execFile = promisify(execFileCb);
 
@@ -59,8 +65,6 @@ const GIT_TIMEOUT_MS = 120_000;
 const TRANSFER_TIMEOUT_MS = 300_000;
 const TMP_PREFIX = 'release-skill-distribute-';
 
-/** Remote URL pattern: http(s) or file (test transport), .git-suffixed. */
-const SAFE_REMOTE_URL_RE = /^(?:https?|file):\/\/.+\.git$/;
 /** Branch pattern (leading alphanumeric blocks option-like names). */
 const SAFE_BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 /** Safe tag characters (belt + braces; prepare already rendered the tag). */
@@ -164,8 +168,8 @@ export function renderMarketplaceIndex(marketplace, params = {}) {
       ...(sha ? { sha } : {}),
     };
   } else {
-    if (typeof dependencyUrl !== 'string' || !SAFE_REMOTE_URL_RE.test(dependencyUrl)) {
-      fail('url form requires the payload-mirror dependency remoteUrl', { dependencyUrl });
+    if (typeof dependencyUrl !== 'string' || !isAllowedGitRemoteUrl(dependencyUrl)) {
+      fail('url form requires the payload-mirror dependency remoteUrl', {});
     }
     source = {
       source: 'url',
@@ -187,11 +191,12 @@ function hasControlChars(value) {
 }
 
 function assertSafeRemoteUrl(remoteUrl) {
-  if (typeof remoteUrl !== 'string' || !SAFE_REMOTE_URL_RE.test(remoteUrl) || hasControlChars(remoteUrl)) {
+  const verdict = checkGitRemoteUrl(remoteUrl);
+  if (!verdict.ok) {
     throw new ReleaseError(
       GATE_FAILED,
-      'distribute remoteUrl must be an http(s)/file URL ending in .git',
-      { remoteUrl },
+      `distribute remoteUrl ${describeGitRemoteUrlFailure(verdict.reason)}`,
+      { reason: verdict.reason },
     );
   }
 }
@@ -302,9 +307,10 @@ export function createDistributeGitAdapter(deps = {}) {
   function probeFailureResult(action, error) {
     const classification = classifyProbeFailure(stderrText(error));
     const code = classification === 'auth' ? REMOTE_CONFLICT : REMOTE_UNAVAILABLE;
+    const safeRemoteUrl = redactUrlCredentialsIfPresent(action.remoteUrl);
     const message = classification === 'auth'
-      ? `remote refused authentication for ${action.remoteUrl}; distribute reuses the host keychain credential and never prompts, reads, or retries credentials`
-      : `cannot reach ${action.remoteUrl} — start VPN / check network; distribute fails closed and never retries with credentials`;
+      ? `remote refused authentication for ${safeRemoteUrl}; distribute reuses the host keychain credential and never prompts, reads, or retries credentials`
+      : `cannot reach ${safeRemoteUrl} — start VPN / check network; distribute fails closed and never retries with credentials`;
     return createResult({
       actionType: action.actionType,
       status: ActionStatus.PREFLIGHT_FAILED,
@@ -312,7 +318,7 @@ export function createDistributeGitAdapter(deps = {}) {
       details: {
         code,
         classification,
-        remoteUrl: action.remoteUrl,
+        remoteUrl: safeRemoteUrl,
         stderrTail: stderrTail(error),
       },
     });
@@ -468,7 +474,7 @@ export function createDistributeGitAdapter(deps = {}) {
       if (existingTag) {
         throw new ReleaseError(
           REMOTE_CONFLICT,
-          `target ${action.remoteUrl} already carries tag ${action.tag} and the content differs; moving an existing tag would be force-equivalent — human decision required`,
+          `target ${redactUrlCredentialsIfPresent(action.remoteUrl)} already carries tag ${action.tag} and the content differs; moving an existing tag would be force-equivalent — human decision required`,
           { targetId: action.targetId, tag: action.tag },
         );
       }

package/src/commands/approve.mjs

@@ -25,7 +25,13 @@ import {
   validatePlanActionCompleteness,
 } from '../core/plan.mjs';
 import { ReleaseError, PLAN_DIGEST_MISMATCH, GATE_FAILED } from '../core/errors.mjs';
-import { computeApprovalDigest, validateApprovalRecordSchema } from '../core/approval.mjs';
+import {
+  computeApprovalDigest,
+  validateApprovalRecordSchema,
+  MAX_APPROVAL_MS,
+} from '../core/approval.mjs';
+import { validatePostPublishApproval, derivePostPublishApprovalAuthorityPath } from '../core/postpublish-approval.mjs';
+import { normalizePostPublishHook, effectiveHookRequiresApproval } from '../core/postpublish.mjs';
 import { WORKSPACE_DIGEST_ALGORITHM } from '../core/baseline.mjs';
 
 // ---------------------------------------------------------------------------
@@ -280,3 +286,159 @@ export async function approvePlan(options) {
     latestApprovalPath: writePath,
   });
 }
+
+/**
+ * Approve a requiresApproval postPublish hook (checkpoint-level approval,
+ * v0.6.3 R1, design §2.7 ruling 2).
+ *
+ * The record binds (planDigest, hookId) — the plan-level approval schema is
+ * untouched. Hook config changes change the plan digest, so approvals
+ * invalidate naturally with the plan. The result carries the approved hook's
+ * normalized entry summary (review N-6) so the checkpoint approval interface
+ * can display exactly what was approved.
+ *
+ * @param {Object} options
+ * @param {string} options.planPath - Absolute path to the frozen release plan.
+ * @param {string} options.hookId - id of the declared hook to approve.
+ * @param {string} options.actor - Identity of the approver.
+ * @param {number} [options.expiresInMs] - Validity window in ms (default and max 24h).
+ * @param {() => string} [options.clock] - Clock function returning ISO-8601 strings.
+ * @param {string} [options.runId] - Audit-only distribute run id (never a binding).
+ *
+ * @returns {Promise<object>} { planDigest, hookId, actor, approvedAt,
+ *   expiresAt, approvalDigest, approvalPath, hookSummary }.
+ *
+ * @throws {ReleaseError} GATE_FAILED when the hook is undeclared, does not
+ *   require approval, or the window exceeds 24h.
+ */
+export async function approvePostPublishHook(options) {
+  const {
+    planPath,
+    hookId,
+    actor,
+    expiresInMs = MAX_APPROVAL_MS,
+    clock,
+    runId,
+  } = options ?? {};
+
+  const clockFn = typeof clock === 'function' ? clock : defaultClock;
+
+  if (!planPath || typeof planPath !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'planPath must be a non-empty string');
+  }
+  if (!hookId || typeof hookId !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'hookId must be a non-empty string');
+  }
+  if (!actor || typeof actor !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'actor must be a non-empty string');
+  }
+  if (typeof expiresInMs !== 'number' || !Number.isFinite(expiresInMs) || expiresInMs <= 0) {
+    throw new ReleaseError(GATE_FAILED, 'expiresInMs must be a positive finite number', { expiresInMs });
+  }
+  if (expiresInMs > MAX_APPROVAL_MS) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `expiresInMs must not exceed 24 hours (${MAX_APPROVAL_MS}ms), got ${expiresInMs}ms`,
+      { expiresInMs },
+    );
+  }
+
+  // --- Load and validate the frozen plan ---
+  let planRaw;
+  try {
+    planRaw = await readFile(planPath, 'utf8');
+  } catch (err) {
+    throw new ReleaseError(GATE_FAILED, `cannot read release plan: ${err.message}`, { planPath, cause: err.code });
+  }
+  let plan;
+  try {
+    plan = JSON.parse(planRaw);
+  } catch (err) {
+    throw new ReleaseError(GATE_FAILED, `release plan is not valid JSON: ${err.message}`, { planPath });
+  }
+  const actualDigest = computePlanDigest(plan);
+  assertImmutablePlanAuthority(planPath, plan);
+  validatePlan(plan);
+
+  // --- Locate the declared hook (fail-closed) ---
+  const hooks = plan.postPublish?.hooks ?? [];
+  const hook = hooks.find((entry) => entry.id === hookId);
+  if (!hook) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `hook "${hookId}" is not declared in the frozen plan's postPublish hooks`,
+      { hookId, declaredHookIds: hooks.map((entry) => entry.id) },
+    );
+  }
+  // Effective requiresApproval (§2.6 grading, R4 review M-1): preset hooks
+  // may inherit the preset-declared default (proposal-inbox git-push,
+  // declared OR inferred from a remoteUrl address -> true) without an
+  // explicit declaration. Grading by the literal value here would refuse to
+  // mint approvals for exactly the hooks the runtime gates — the mint and
+  // validatePostPublishApproval must agree on the effective value.
+  const effectiveRequiresApproval = effectiveHookRequiresApproval(hook);
+  if (effectiveRequiresApproval !== true) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `hook "${hookId}" does not require approval (effective requiresApproval is not true)`,
+      { hookId, requiresApproval: effectiveRequiresApproval },
+    );
+  }
+
+  // --- Build the checkpoint approval record ---
+  const approvedAt = clockFn();
+  const approvedAtDate = new Date(approvedAt);
+  if (Number.isNaN(approvedAtDate.getTime())) {
+    throw new ReleaseError(GATE_FAILED, `invalid approvedAt timestamp: "${approvedAt}"`, { approvedAt });
+  }
+  const expiresAt = new Date(approvedAtDate.getTime() + expiresInMs).toISOString();
+
+  const approvalRecord = {
+    planDigest: actualDigest,
+    hookId,
+    actor,
+    approvedAt,
+    expiresAt,
+    ...(runId ? { runId } : {}),
+  };
+
+  // Full fail-closed re-validation (schema + bindings + time window).
+  validatePostPublishApproval(plan, approvalRecord, { clock: clockFn });
+
+  // --- Write the digest-addressed authority ---
+  const json = JSON.stringify(approvalRecord, null, 2);
+  const approvalDigest = computeApprovalDigest(json);
+  // Single authority-layout source (core/postpublish-approval.mjs): the
+  // consumer-side assertion derives the exact same path fail-closed.
+  const { authorityPath: immutableApprovalPath } = derivePostPublishApprovalAuthorityPath(
+    planPath,
+    actualDigest,
+    approvalDigest,
+  );
+  await prepareAuthorityDirectory(dirname(immutableApprovalPath));
+  await assertAuthorityFileTarget(immutableApprovalPath);
+  try {
+    await writeFile(immutableApprovalPath, json, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const existing = await readFile(immutableApprovalPath, 'utf8');
+    if (existing !== json) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'postpublish approval authority digest collision: existing bytes differ',
+        { planDigest: actualDigest, approvalDigest, immutableApprovalPath },
+      );
+    }
+  }
+
+  // Review N-6: the normalized entry summary is the display surface of the
+  // checkpoint approval interface (defaults applied, digest-bound).
+  const hookSummary = normalizePostPublishHook(hook);
+
+  return Object.freeze({
+    ...approvalRecord,
+    approvalDigest,
+    approvalPath: immutableApprovalPath,
+    hookSummary,
+  });
+}