@natjswenson/shipflow 0.2.4 → 0.2.5

package/SKILL.md

@@ -66,11 +66,11 @@ user; the CLI is the only thing that *does*.
    npx -y @natjswenson/shipflow apply --repo <path> --dry-run
    ```
 
-9. **Apply for real**, passing the `stateHash` from step 7's plan output as `--expect-state-hash` — this is the TOCTOU guard: if repo state drifted between the plan you showed the user and this call, `apply` refuses to mutate anything and tells you to re-plan.
+9. **Apply for real**, passing the `stateHash` from step 7's plan output as `--expect-state-hash` — this is the TOCTOU guard: if repo state drifted between the plan you showed the user and this call, `apply` refuses to mutate anything and tells you to re-plan. **`--expect-state-hash` is mandatory for a real (non-dry-run) apply** — omitting it is a hard CLI refusal, not a silent skip of the check; the only way around it is the explicitly-named `--skip-hash-check` escape hatch, which you should never reach for as a matter of course.
    ```
    npx -y @natjswenson/shipflow apply --repo <path> --expect-state-hash <hash-from-step-7>
    ```
-   If a `handEditDetected` entry was confirmed for override in step 7, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override).
+   If a `handEditDetected` entry was confirmed for override in step 7, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override) **and** `--force-reason "<short justification>"` — the CLI refuses any `--force` without an accompanying reason, and that reason is echoed back in the apply result for auditability. Write a real justification tied to the user's actual confirmation (e.g. `--force-reason "user confirmed hand-edit override for the branch-rename migration on 2026-07-15"`), never a placeholder string.
 
 10. **Report the result.** Read `applied`/`skipped`/`errors` from the response. A `skipped` entry can be a deliberate refusal (empty checks, hand-edit) or an environment limitation shipflow can't do anything about (e.g. a deletion-ruleset skipped because the repo is private and not on a paid GitHub tier) — read each `reason` and relay it plainly rather than treating every `skipped` entry the same. If `renderedTemplateHashes` is non-empty, update `.github/shipflow.json`'s `renderedTemplateHashes` field with those values and tell the user to commit the config change *and* the rendered workflow file **together, in the same commit** — a split commit is exactly what causes a false `handEditDetected` on a clean checkout later.
 
@@ -104,11 +104,14 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 
 ## Error handling
 
-- **Empty `requiredChecks`:** `apply` refuses to wire up auto-merge with zero required checks. Don't work around this by suggesting `--force allow-no-checks` unless the user has explicitly and knowingly accepted an unprotected merge — surface the refusal message plainly first.
+- **Empty `requiredChecks`:** `apply` refuses to wire up auto-merge with zero required checks. Don't work around this by suggesting `--force allow-no-checks` (plus the now-mandatory `--force-reason`) unless the user has explicitly and knowingly accepted an unprotected merge — surface the refusal message plainly first.
 - **`handEditDetected`:** a template file's on-disk content doesn't match what shipflow last rendered *or* what it would freshly render — someone hand-edited it. Never silently pass `--force` for this; always show the user what changed and get explicit confirmation per entry.
 - **TOCTOU abort:** if `apply` returns a `toctou` error, repo state changed between plan and apply — re-run the plan step, don't retry the same `--expect-state-hash`.
 - **`gh auth` failures:** surface these immediately; branch protection and rulesets need repo-admin scope. Don't proceed partway through a plan on missing auth.
 - **`release.releaseCredential` left as (or defaulted to) `GITHUB_TOKEN`:** auto-merge and the required-check gate still work, but `label-release-pending` will silently never run — a `GITHUB_TOKEN`-attributed auto-merge's `pull_request: closed` event never triggers it, so no promotion will ever surface via `shipflow releases`. This fails silently, not loudly — there's no error to catch it — so it must be caught at setup time (step 5) rather than discovered later. If a user reports "releases never show up," check this first.
+- **`--expect-state-hash is required` refusal:** a real apply was attempted with neither `--expect-state-hash` nor `--skip-hash-check`. Go back and get (or re-fetch via `plan`) the hash — don't reach for `--skip-hash-check` just to make the error go away; that flag exists for a deliberate, documented exception, not as a default workaround.
+- **`--force was passed without --force-reason` refusal:** a `--force` flag was about to be sent with no accompanying justification. Stop and get (or write) an explicit reason tied to what the user actually confirmed before retrying — never pass a placeholder string just to satisfy the flag.
+- **A `gh`/`git` call hangs or times out:** every subprocess call has a 30-second timeout (`ETIMEDOUT` surfaces in the error message). A timeout on `detect`/`plan` usually means a real GitHub outage or rate-limit — retry once, and if it persists, tell the user rather than looping silently.
 
 ## Security rules
 

package/bin/shipflow.js

@@ -106,10 +106,29 @@ function cmdApply(args) {
       config: { type: 'string' },
       'dry-run': { type: 'boolean', default: false },
       'expect-state-hash': { type: 'string' },
+      'skip-hash-check': { type: 'boolean', default: false },
       force: { type: 'string', multiple: true, default: [] },
+      'force-reason': { type: 'string' },
     },
   });
   if (!values.repo) return fail('apply: --repo is required');
+  if (values.force.length > 0 && !values['force-reason']) {
+    return fail(
+      'apply: --force was passed without --force-reason — every force override must carry a short, explicit human-readable justification (surfaced back in the apply result for auditability)'
+    );
+  }
+  // --expect-state-hash is the TOCTOU guard: without it, a real apply
+  // proceeds against whatever live state happens to exist at call time,
+  // with no confirmation that a human/agent actually reviewed that exact
+  // state via `plan` first. Omitting it silently used to just skip the
+  // check — now it's a hard refusal unless the caller explicitly opts out
+  // via --skip-hash-check (a named, greppable escape hatch, not a default).
+  // Found via a Siege security audit (2026-07-15, SIEGE-2026-07-15-003).
+  if (!values['dry-run'] && !values['expect-state-hash'] && !values['skip-hash-check']) {
+    return fail(
+      'apply: --expect-state-hash is required for a real apply — pass the stateHash a prior `plan` call returned, or --skip-hash-check to explicitly bypass the drift guard (not recommended)'
+    );
+  }
 
   const configPath = values.config ?? defaultConfigPath(values.repo);
   let config;
@@ -158,6 +177,7 @@ function cmdApply(args) {
     dryRun: values['dry-run'],
     currentStateHash: repoState.stateHash,
     force: values.force,
+    forceReason: values['force-reason'] ?? null,
     ownerRepo,
     repoPath: values.repo,
     config,
@@ -241,7 +261,7 @@ Usage: shipflow <command> [options]
 Commands:
   detect --repo <path> [--main <name>] [--dev <name>] [--release-credential <name>]
   plan --repo <path> [--config <path>]
-  apply --repo <path> [--config <path>] [--dry-run] [--expect-state-hash <hash>] [--force <id>]...
+  apply --repo <path> [--config <path>] [--dry-run] [--expect-state-hash <hash> | --skip-hash-check] [--force <id>]... [--force-reason <text>]
   releases --repo <path> [--config <path>]
   release-dispatch --repo <path> --pr <number> --workflow-file <file>... --ref <ref>
   rename-default-branch --repo <path> --branch <current-name> --to <new-name>

package/lib/apply.mjs

@@ -30,7 +30,7 @@ export function classifyRulesetError(stderr) {
 }
 
 export function applyPlan(plan, opts) {
-  const { dryRun, currentStateHash, force = [], ownerRepo, repoPath, config } = opts;
+  const { dryRun, currentStateHash, force = [], forceReason = null, ownerRepo, repoPath, config } = opts;
 
   // TOCTOU guard — refuse before making ANY mutating call if live state has
   // drifted since the plan was computed. Idempotency is the primary safety
@@ -88,7 +88,12 @@ export function applyPlan(plan, opts) {
 
     const result = applyOne(entry, { ownerRepo, repoPath, config });
     if (result.ok) {
-      applied.push({ id: entry.id, description: entry.description });
+      const wasForced = force.includes(entry.id) || (entry.id.startsWith('template:') && force.includes('allow-no-checks'));
+      applied.push({
+        id: entry.id,
+        description: entry.description,
+        ...(wasForced ? { forced: true, forceReason } : {}),
+      });
       if (entry.id.startsWith('template:') && entry.renderedHash) {
         renderedTemplateHashes[entry.path] = entry.renderedHash;
       }

package/lib/gh.mjs

@@ -18,16 +18,33 @@ export function readFileCapped(path, encoding = 'utf8') {
   return readFileSync(path, encoding);
 }
 
+// Every gh/git call crosses a network or filesystem-lock boundary shipflow
+// doesn't control (GitHub rate-limiting, a network partition, a stuck git
+// index lock) — with no timeout, a single stuck call hangs the whole
+// process indefinitely with no recovery. 30s is generous for any real gh
+// API call or local git operation this codebase makes. Found via a Siege
+// security audit (2026-07-15, SIEGE-2026-07-15-004).
+const DEFAULT_SUBPROCESS_TIMEOUT_MS = 30_000;
+
 // argv-style invocation; no shell, so user-supplied args cannot inject.
 // Returns { status, stdout, stderr } so callers can distinguish failure modes
 // (e.g. a 404 from gh vs. a network error) instead of collapsing to a boolean.
 export function spawnArgs(cmd, args, opts = {}) {
   try {
-    const r = spawnSync(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', ...opts });
+    const r = spawnSync(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: DEFAULT_SUBPROCESS_TIMEOUT_MS,
+      ...opts,
+    });
+    const stderr = (r.stderr || '').trim();
+    // spawnSync does not throw on timeout — it kills the child and sets
+    // r.error (code 'ETIMEDOUT') with r.status left null, so this must be
+    // surfaced explicitly rather than silently collapsing to a bare "1".
     return {
       status: r.status ?? 1,
       stdout: (r.stdout || '').trim(),
-      stderr: (r.stderr || '').trim(),
+      stderr: r.error ? [stderr, r.error.message].filter(Boolean).join(': ') : stderr,
     };
   } catch (e) {
     return { status: 1, stdout: '', stderr: String((e && e.message) || e) };

package/package.json

@@ -1,15 +1,30 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",
   "homepage": "https://github.com/natejswenson/shipflow",
-  "repository": { "type": "git", "url": "git+https://github.com/natejswenson/shipflow.git" },
-  "bugs": { "url": "https://github.com/natejswenson/shipflow/issues" },
-  "keywords": ["shipflow", "claude-code", "claude-skill", "git", "branching", "release-automation", "ci-cd"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natejswenson/shipflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/natejswenson/shipflow/issues"
+  },
+  "keywords": [
+    "shipflow",
+    "claude-code",
+    "claude-skill",
+    "git",
+    "branching",
+    "release-automation",
+    "ci-cd"
+  ],
   "type": "module",
-  "bin": { "shipflow": "bin/shipflow.js" },
+  "bin": {
+    "shipflow": "bin/shipflow.js"
+  },
   "files": [
     "bin/",
     "lib/",
@@ -21,10 +36,14 @@
     "README.md",
     "LICENSE"
   ],
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "test": "node --test \"tests/**/*.test.mjs\"",
     "audit": "npm audit --audit-level=moderate"
   },
-  "dependencies": {}
+  "devDependencies": {
+    "yaml": "^2.9.0"
+  }
 }

package/skill-invariants.json

@@ -65,6 +65,16 @@
       "id": "render-template-validates-substitutions",
       "pattern": "never assume a config field is pre-sanitized",
       "rationale": "Found by a Siege security audit (2026-07-15): renderTemplate did pure string substitution with zero escaping, so a repo-write-level (not admin-level) edit to .github/shipflow.json's branch names or release.releaseCredential could break out of the rendered YAML's quoting and make the auto-merge job's if: condition unconditionally true, or inject arbitrary new workflow steps — a privilege escalation via the credential the rendered workflow runs with."
+    },
+    {
+      "id": "expect-state-hash-mandatory",
+      "pattern": "is mandatory for a real \\(non-dry-run\\) apply",
+      "rationale": "Found by a Siege security audit (2026-07-15, SIEGE-2026-07-15-003): --expect-state-hash was optional, so a real apply could silently proceed with zero TOCTOU/drift protection if the caller simply omitted it. Now a hard CLI refusal unless the named --skip-hash-check escape hatch is passed explicitly."
+    },
+    {
+      "id": "force-requires-reason",
+      "pattern": "refuses any `--force` without an accompanying reason",
+      "rationale": "Found by a Siege security audit (2026-07-15, SIEGE-2026-07-15-002): --force had zero code-level friction beyond the flag itself, so a confused or prompt-injected agent could force through an unprotected merge or a tampered template with no audit trail. --force now requires --force-reason, echoed back in the apply result."
     }
   ],
   "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]