@celilo/cli 2.0.0 → 2.2.0

package/src/policy/module-script-scan.test.ts

@@ -12,7 +12,11 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { buildModule } from '../module/packaging/build';
-import { scanModuleDirectory, scanModuleScriptSource } from './module-script-scan';
+import {
+  JAILED_CLI_SPAWN_RULE,
+  scanModuleDirectory,
+  scanModuleScriptSource,
+} from './module-script-scan';
 
 const rules = (src: string) => scanModuleScriptSource('f.ts', src).map((v) => v.rule);
 
@@ -60,6 +64,43 @@ describe('module script scan — namespace tools (hygiene, not a boundary)', ()
   });
 });
 
+describe('module script scan — jailed CLI spawn rule', () => {
+  // Each spawn spelling asserted separately. An alternation that loses a leg
+  // still passes a test that only exercises the first.
+  it.each([
+    [
+      "execFileSync('celilo', argv)",
+      "execFileSync('celilo', ['module', 'config', 'set', 'x', 'y']);",
+    ],
+    ['execFileSync("celilo", argv)', 'execFileSync("celilo", args);'],
+    ['execSync(`celilo …`)', 'execSync(`celilo module secret set x y`);'],
+    [
+      'exec(`celilo …`) after a shell prefix',
+      'exec(`cd /opt && sudo celilo system config get k`);',
+    ],
+    ["spawn('celilo', argv)", "const child = spawn('celilo', ['events', 'status']);"],
+  ])('catches %s', (_spelling, src) => {
+    expect(rules(src)).toContain(JAILED_CLI_SPAWN_RULE);
+  });
+
+  it('does not fire on operator prose that merely names the CLI', () => {
+    expect(rules('throw new Error("re-run `celilo module deploy x` to regenerate it");')).toEqual(
+      [],
+    );
+  });
+
+  // The `\w` after `celilo ` is what separates a CLI invocation from an
+  // argument that merely begins with the string, so the negative case has to
+  // be a hyphenated name, which would match a bare `\bcelilo\b`.
+  it('does not fire on a container argument named celilo-*', () => {
+    expect(rules('execSync(`docker exec celilo-mgr status`);')).toEqual([]);
+  });
+
+  it('does not fire on the celilo.db file name', () => {
+    expect(rules('execSync(`cp /var/lib/celilo/celilo.db /tmp/x`);')).toEqual([]);
+  });
+});
+
 describe('module script scan — raw-exec escape hatch', () => {
   it('flags a runAppCommand call with no justification', () => {
     expect(rules('const r = runAppCommand(system, "rm -f /tmp/x", run);')).toContain(

package/src/policy/module-script-scan.ts

@@ -26,7 +26,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 
 export interface ScanViolation {
   /** Path as the operator should see it — relative to the scanned root. */
@@ -52,7 +52,58 @@ export interface ScanViolation {
  */
 const ESCAPE_HATCH_LOOKBACK_LINES = 8;
 
+/**
+ * The rule name for a module script that reaches the `celilo` CLI as a child
+ * process. Exported because the debt list below and both test files key on it;
+ * a literal repeated in three places is the duplicate that drifts.
+ */
+export const JAILED_CLI_SPAWN_RULE = 'jailed hook spawns the celilo CLI';
+
+/**
+ * The rule name for a module script that catches a refused framework call and
+ * carries on with a value it invented (e2e-suite-recovery §4, spec delta
+ * `specs/module-lifecycle/spec.md`). Exported for the same reason as the spawn
+ * rule: the debt list below and the gate's test file key on it.
+ */
+export const SWALLOWED_REFUSAL_RULE = 'swallowed framework refusal';
+
+/**
+ * A framework-reaching call, spelled as this repo spells them today: one of
+ * the spawn-family calls naming the `celilo` CLI (the same shape the spawn
+ * rule above keys on — extracted here so the two rules cannot disagree about
+ * what reaches the framework), or a call through `runCelilo`, knot-unbound-
+ * internal's injected CLI runner (wired to `execFileSync('celilo', …)` where
+ * the hook is constructed; the debt list's own reason text names the
+ * "runCelilo wrapper").
+ *
+ * What it deliberately cannot see, same honesty class as every rule in this
+ * file: a wrapper under any other name, a binary path resolved into a
+ * variable, or a spawn reached through an indirection. A lint, not a boundary.
+ */
+const CLI_SPAWN_RE =
+  /\b(?:execSync|execFileSync|execFile|exec|spawnSync|spawn)\s*\(\s*(?:['"`]\s*celilo(?=\s|['"`])|`[^`]*\bcelilo(?=\s|`))/;
+const FRAMEWORK_CALL_RE = new RegExp(`${CLI_SPAWN_RE.source}|\\brunCelilo\\s*\\(`);
+
 const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
+  {
+    rule: JAILED_CLI_SPAWN_RULE,
+    // Same regex as CLI_SPAWN_RE below — one definition of "reaches the
+    // framework", used by both rules that key on it. Matches the CLI as
+    // argv[0] of a spawn-family call ('celilo' / "celilo"), or inside a shell
+    // string passed to one, where celilo is followed by a word (a subcommand)
+    // or the closing quote — so `docker exec celilo-mgr …`, a `celilo.db` file
+    // name, and prose that merely names the CLI do not fire. What it
+    // deliberately cannot see: a binary path resolved into a variable, or a
+    // spawn reached through an indirection. Same honesty class as the
+    // namespace rule — a lint, not a boundary.
+    re: CLI_SPAWN_RE,
+    hint:
+      'A jailed hook has no celilo binary and no shell, so this dies with ' +
+      '"Executable not found in $PATH" (celilo#1225). Replace the spawn with an ' +
+      'injected capability — context.secrets/context.config for self-config and ' +
+      'self-secrets (openspec/changes/hook-owned-state) — or move the operation ' +
+      'into the framework the way celilo-mgmt on_install did (5e0e624d).',
+  },
   {
     rule: 'raw ssh invocation (StrictHostKeyChecking)',
     re: /StrictHostKeyChecking/,
@@ -97,6 +148,45 @@ const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
   },
 ];
 
+/**
+ * How far below a framework-reaching call the `catch` clause may sit for the
+ * call to count as caught. Calibrated against the three real sites rather than
+ * guessed: the widest call-to-catch gap among them is four lines (on_backup's
+ * machine-pool snapshot parses between the call and the catch). Six covers
+ * those with headroom and cannot reach the next statement's catch in any
+ * module script in the tree.
+ */
+const SWALLOW_LOOKAHEAD_LINES = 6;
+
+/**
+ * How deep into a catch body the scan looks for a `throw` before concluding
+ * the catch swallows. A refusal that propagates (rethrow, wrapped throw) is
+ * correct handling and must not fire; a catch that returns a literal, logs and
+ * continues, or only comments must. Eight lines is beyond any catch body in
+ * the tree; a longer one hides from this scan the same way a renamed wrapper
+ * does.
+ */
+const SWALLOW_CATCH_BODY_LINES = 8;
+
+const CATCH_CLAUSE_RE = /\bcatch\b/;
+const THROW_RE = /\bthrow\b/;
+const CATCH_CLOSE_RE = /^\s*}\s*(?:catch|finally|else)?\s*;?\s*$/;
+
+/**
+ * The catch clause a framework-reaching call landed in swallows when its body
+ * contains no `throw` within the window: the refusal is absorbed and the hook
+ * carries on. Returns false (handled correctly) when the catch propagates the
+ * refusal, and true only for the swallowed shape.
+ */
+function catchSwallows(lines: string[], catchIdx: number): boolean {
+  const end = Math.min(catchIdx + SWALLOW_CATCH_BODY_LINES, lines.length - 1);
+  for (let k = catchIdx + 1; k <= end; k++) {
+    if (THROW_RE.test(lines[k])) return false;
+    if (k > catchIdx + 1 && CATCH_CLOSE_RE.test(lines[k])) break;
+  }
+  return true;
+}
+
 /** A `runAppCommand(` / `runAppCommandWithSecret(` CALL — not the import. */
 const RAW_EXEC_CALL = /\brunAppCommand(?:WithSecret)?\s*\(/;
 
@@ -131,6 +221,35 @@ export function scanModuleScriptSource(file: string, source: string): ScanViolat
     }
   });
 
+  // The swallowed-refusal pass: windowed, like the escape-hatch check above —
+  // a catch clause this far below a framework-reaching call is the call's
+  // catch. Reported on the CALL line, because that is the site an author fixes.
+  lines.forEach((text, i) => {
+    if (!FRAMEWORK_CALL_RE.test(text)) return;
+    const last = Math.min(i + SWALLOW_LOOKAHEAD_LINES, lines.length - 1);
+    for (let j = i + 1; j <= last; j++) {
+      if (CATCH_CLAUSE_RE.test(lines[j])) {
+        if (catchSwallows(lines, j)) {
+          violations.push({
+            file,
+            line: i + 1,
+            rule: SWALLOWED_REFUSAL_RULE,
+            hint:
+              'A refused framework call must fail, not continue with an answer it invented ' +
+              '(e2e-suite-recovery §4): a refusal and an absence are different facts. Let the ' +
+              'error propagate, or read through a surface that distinguishes them — an injected ' +
+              'typed-absent reader (openspec/changes/hook-owned-state) — rather than catching ' +
+              'and substituting.',
+          });
+        }
+        break;
+      }
+      // A blank line or a closing brace at statement level ends the call's
+      // statement; a catch further down belongs to something else.
+      if (lines[j].trim() === '' || /^[)}]/.test(lines[j])) break;
+    }
+  });
+
   return violations;
 }
 
@@ -164,12 +283,25 @@ export function moduleScriptFiles(scriptsDir: string): string[] {
 
 /**
  * Scan a module directory (the one holding `manifest.yml`). Returns every
- * violation in its `scripts/`, with paths relative to `moduleDir`.
+ * violation in its `scripts/`, with paths relative to `moduleDir`, minus the
+ * jailed-CLI-spawn sites on the debt list. The module id is the directory's
+ * basename — the same assumption `packaging/build.ts`'s refusal message makes.
  */
 export function scanModuleDirectory(moduleDir: string): ScanViolation[] {
-  return moduleScriptFiles(join(moduleDir, 'scripts')).flatMap((f) =>
-    scanModuleScriptSource(relative(moduleDir, f), readFileSync(f, 'utf-8')),
-  );
+  const moduleId = basename(moduleDir);
+  // One exemption set per rule, keyed the same way: a debt entry silences its
+  // own rule on its own file and nothing else.
+  const debtByRule: Record<string, Set<string>> = {
+    [JAILED_CLI_SPAWN_RULE]: new Set(
+      JAILED_CLI_SPAWN_DEBT.filter((e) => e.module === moduleId).map((e) => e.file),
+    ),
+    [SWALLOWED_REFUSAL_RULE]: new Set(
+      SWALLOWED_REFUSAL_DEBT.filter((e) => e.module === moduleId).map((e) => e.file),
+    ),
+  };
+  return moduleScriptFiles(join(moduleDir, 'scripts'))
+    .flatMap((f) => scanModuleScriptSource(relative(moduleDir, f), readFileSync(f, 'utf-8')))
+    .filter((v) => !(debtByRule[v.rule]?.has(v.file) ?? false));
 }
 
 /** Render violations for a test failure message or a refused publish. */
@@ -177,6 +309,144 @@ export function formatViolations(violations: ScanViolation[]): string {
   return violations.map((v) => `  ${v.file}:${v.line}\n    → ${v.rule}. ${v.hint}`).join('\n');
 }
 
+export interface PolicyDebtEntry {
+  /** Module directory name under `modules/`. */
+  module: string;
+  /** Script path relative to the module directory, e.g. `scripts/setup.ts`. */
+  file: string;
+  /** How many jailed-CLI spawns the file carries today. Pinned so a NEW spawn in an exempted file cannot hide behind the entry. */
+  matches: number;
+  /** Who converts this site, and into what. */
+  reason: string;
+}
+
+/**
+ * The known jailed-CLI spawns, exempted from the rule above until their
+ * conversion lands (hook-owned-state task 5.5; e2e-suite-recovery §3).
+ *
+ * These sites are tracked defects, not sanctioned forms: the jail kills every
+ * one of them the same way it killed celilo-mgmt's on_install (5e0e624d). The
+ * list exists so the rule can land RED-proof while the conversion — which
+ * needs the HookStore from hook-owned-state tasks 2 and 3 — is still at 0%.
+ * It is narrow on purpose (celilo#1014's lesson): one entry per file, each
+ * naming its owner, each pinning the exact number of spawns so a new call
+ * site cannot hide behind an existing entry.
+ *
+ * The debt test in `no-hand-built-ssh.test.ts` asserts every entry still
+ * matches its recorded count. When a conversion lands the count drops to zero,
+ * the test goes red, and the entry must be deleted in the same change.
+ */
+export const JAILED_CLI_SPAWN_DEBT: readonly PolicyDebtEntry[] = [
+  {
+    module: 'celilo-mgmt',
+    file: 'scripts/on_backup.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 / survey class G: machine list becomes a machine-pool read capability',
+  },
+  {
+    module: 'caddy-internal',
+    file: 'scripts/private-web-functions.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (routes, capability-owned-tables Group B1)',
+  },
+  {
+    module: 'dnsmasq-dhcp',
+    file: 'scripts/dhcp-server-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/on-consumer-removed.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (runner_registrations, Group B3)',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/setup.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (secret set)',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/source-forge-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'generic-cpanel-hosting-provider',
+    file: 'scripts/on-consumer-removed.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (publications, Group B4)',
+  },
+  {
+    module: 'generic-cpanel-hosting-provider',
+    file: 'scripts/publish-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/control-plane-vpn-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/health-check.ts',
+    matches: 1,
+    reason:
+      'survey class C: system config get becomes an injected read; not in hook-owned-state 5.5 — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/on_install.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 (registered_peers, Group B2); THE five-suite blocker per the wave-0 census',
+  },
+  {
+    module: 'wireguard-manager',
+    file: 'scripts/setup.ts',
+    matches: 3,
+    reason:
+      'hook-owned-state 5.5 (vpn_endpoint/vpn_server_public_key/client_pool, category 3; secret set)',
+  },
+];
+
+/**
+ * The known swallowed refusals, exempted from the rule above until their
+ * conversion lands (hook-owned-state 5.5; e2e-suite-recovery §4). Same
+ * mechanics and same narrowness as the spawn debt above — one entry per file,
+ * each naming its owner, each pinning the exact number of swallows — with the
+ * same guarded rot: when a site converts, the count drops, the debt test goes
+ * red, and the entry must be deleted in the same change.
+ *
+ * Converted on 2026-09-07 by ce-pvii: knot-unbound-internal/scripts/on-install.ts
+ * dropped its last swallow (the runCelilo wrapper), so the rule fires on
+ * exactly these two sites and nothing else in the tree.
+ */
+export const SWALLOWED_REFUSAL_DEBT: readonly PolicyDebtEntry[] = [
+  {
+    module: 'celilo-mgmt',
+    file: 'scripts/on_backup.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 / survey class G: machine list becomes a typed-absent machine-pool read',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/health-check.ts',
+    matches: 1,
+    reason: 'survey class C: system config get becomes an injected typed-absent read',
+  },
+];
+
 /**
  * The files inside `@celilo/capabilities` that implement the remote-exec
  * primitives themselves. `remote.ts` is the ONE sanctioned place the

package/src/policy/no-hand-built-ssh.test.ts

@@ -12,15 +12,18 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import {
+  JAILED_CLI_SPAWN_DEBT,
+  JAILED_CLI_SPAWN_RULE,
   REMOTE_PRIMITIVE_FILES,
   capabilityPackageSourceFiles,
   formatViolations,
   moduleScriptFiles,
   scanCapabilityPackageSource,
   scanModuleDirectory,
+  scanModuleScriptSource,
 } from './module-script-scan';
 
 /** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
@@ -56,6 +59,36 @@ describe('recurrence gate: modules never hand-build SSH', () => {
   });
 });
 
+describe('recurrence gate: the jailed-CLI-spawn debt list is honest', () => {
+  // The debt list in module-script-scan exempts real, tracked defects from the
+  // jailed-CLI-spawn rule so the rule can land green before hook-owned-state
+  // converts them. Three ways this list could silently rot, and this is the
+  // guard for each:
+  //   a site is converted  -> the file stops matching, the entry must go
+  //   a NEW site appears   -> the pinned count moves, the entry must be revisited
+  //   a file is deleted    -> the entry names a ghost and must go
+  test('every entry names an existing file carrying exactly its pinned spawn count', () => {
+    for (const entry of JAILED_CLI_SPAWN_DEBT) {
+      const f = join(repoRoot(), 'modules', entry.module, entry.file);
+      expect(
+        existsSync(f),
+        `${entry.module}/${entry.file} no longer exists — delete its debt entry`,
+      ).toBe(true);
+      const hits = scanModuleScriptSource(entry.file, readFileSync(f, 'utf-8')).filter(
+        (v) => v.rule === JAILED_CLI_SPAWN_RULE,
+      );
+      expect(
+        hits.length,
+        `${entry.module}/${entry.file} carries ${hits.length} jailed-CLI spawns, the debt entry pins ${entry.matches} (${entry.reason}) — convert or update the entry`,
+      ).toBe(entry.matches);
+    }
+  });
+
+  test('the debt list is non-trivial (the guard actually reached the entries)', () => {
+    expect(JAILED_CLI_SPAWN_DEBT.length).toBeGreaterThan(5);
+  });
+});
+
 describe('recurrence gate: @celilo/capabilities itself never hand-builds SSH', () => {
   // The workspace source — where the package is authored, and the only copy a
   // commit in this repo can fix. Each module's bundled copy is an npm snapshot