@celilo/cli 1.4.0 → 1.6.0

package/src/module/packaging/generated-plane.ts

@@ -0,0 +1,134 @@
+/**
+ * The second plane: is what we would deploy built from what we installed?
+ *
+ * A module exists in four places — the published package, the installed tree,
+ * the generated project, and the host — and celilo reported a version for the
+ * first as though it described the last. Between them sit three copies and two
+ * transformations, and nothing verified any of them against the one before it
+ * (openspec/changes/module-integrity-rigor, D3).
+ *
+ * Only VERBATIM assets have a meaningful expected digest. Ansible templates
+ * most of what it writes, and a `.j2` in `generated/` is supposed to differ
+ * from its source. `ansible/roles/<role>/files/` is the exception: it holds
+ * static assets — built binaries, certs, blobs — copied byte for byte because
+ * they need no variable resolution and may not survive utf-8 round-tripping.
+ *
+ * That is exactly where celilo#925 lived. `copyAnsibleRoleFilesDirs` skipped an
+ * existing destination on bun, so a module's built binary landed in
+ * `generated/` once, at first generate, and no later version replaced it.
+ * `cp` reported no error, Ansible copied that first binary forever and reported
+ * `ok`, and the module's version field advanced past code that was never
+ * shipped. This comparison is local, takes milliseconds, needs no SSH, and is
+ * the check that turns that silence into a refusal.
+ */
+
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { computeFileChecksum } from './checksum';
+
+export interface VerbatimAssetDifference {
+  /** Path relative to the module root, identical in both trees. */
+  relPath: string;
+  /** `missing`: generation never produced it. `stale`: it holds other bytes. */
+  reason: 'missing' | 'stale';
+  installedDigest: string;
+  generatedDigest: string | null;
+}
+
+/**
+ * Pure. Both sides are digest maps keyed by the same module-relative path.
+ *
+ * An asset present in `generated` but absent from `installed` is NOT reported.
+ * That is a role the module no longer has, whose old output nothing includes,
+ * and failing a deploy for it would refuse a correct module for a stale file
+ * Ansible never reads.
+ */
+export function compareVerbatimRoleAssets(
+  installed: ReadonlyMap<string, string>,
+  generated: ReadonlyMap<string, string>,
+): VerbatimAssetDifference[] {
+  const differences: VerbatimAssetDifference[] = [];
+  for (const [relPath, installedDigest] of installed) {
+    const generatedDigest = generated.get(relPath) ?? null;
+    if (generatedDigest === null) {
+      differences.push({ relPath, reason: 'missing', installedDigest, generatedDigest: null });
+    } else if (generatedDigest !== installedDigest) {
+      differences.push({ relPath, reason: 'stale', installedDigest, generatedDigest });
+    }
+  }
+  return differences;
+}
+
+/**
+ * Digest every `ansible/roles/<role>/files/**` asset under `root`, keyed by its
+ * path relative to `root`. The generated project mirrors that layout, so the
+ * two maps this produces are directly comparable.
+ */
+export async function readVerbatimRoleAssets(root: string): Promise<Map<string, string>> {
+  const assets = new Map<string, string>();
+  const rolesDir = join(root, 'ansible', 'roles');
+  if (!existsSync(rolesDir)) return assets;
+
+  for (const role of await readdir(rolesDir, { withFileTypes: true })) {
+    if (!role.isDirectory()) continue;
+    const filesDir = join(rolesDir, role.name, 'files');
+    if (!existsSync(filesDir)) continue;
+    for (const filePath of await listFiles(filesDir)) {
+      assets.set(relative(root, filePath), await computeFileChecksum(filePath));
+    }
+  }
+  return assets;
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+  const found: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...(await listFiles(full)));
+    } else if (entry.isFile()) {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+/**
+ * One line per difference, naming the file. celilo#925 took days partly because
+ * nothing anywhere named the file that had gone stale.
+ */
+export function describeVerbatimDifferences(differences: VerbatimAssetDifference[]): string[] {
+  return differences.map((d) =>
+    d.reason === 'missing'
+      ? `${d.relPath}: generation never produced it (installed ${d.installedDigest})`
+      : `${d.relPath}: generated holds ${d.generatedDigest}, installed is ${d.installedDigest}`,
+  );
+}
+
+/**
+ * The deploy pre-flight (D6). Returns the refusal message, or `null` to proceed.
+ *
+ * Local, milliseconds, no SSH, and it runs before anything contacts a system.
+ * It deliberately does NOT verify after the deploy: Ansible's `changed` is
+ * truthful about what Ansible did, and the lie in celilo#925 was upstream of
+ * Ansible.
+ */
+export async function refuseIfGeneratedIsStale(
+  moduleId: string,
+  modulePath: string,
+  generatedPath: string,
+): Promise<string | null> {
+  const differences = compareVerbatimRoleAssets(
+    await readVerbatimRoleAssets(modulePath),
+    await readVerbatimRoleAssets(generatedPath),
+  );
+  if (differences.length === 0) return null;
+  return [
+    `Refusing to deploy ${moduleId}: the generated project does not match the installed module.`,
+    `  ${differences.length} verbatim asset(s) differ:`,
+    ...describeVerbatimDifferences(differences).map((line) => `    ${line}`),
+    '',
+    `Deploying would ship these bytes and report success. Run 'celilo module generate ${moduleId}' and try again.`,
+  ].join('\n');
+}

package/src/module/packaging/host-plane.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ModuleManifest } from '../../manifest/schema';
+import { classifyHostRecap, verifyModuleOnHosts } from './host-plane';
+
+const recap = (over: Partial<Parameters<typeof classifyHostRecap>[0]> = {}) => ({
+  host: 'vpn-manager',
+  changed: 0,
+  unreachable: 0,
+  failed: 0,
+  skipped: 0,
+  ...over,
+});
+
+describe('classifyHostRecap', () => {
+  test('nothing would change → converged', () => {
+    expect(classifyHostRecap(recap(), 'm').state).toBe('converged');
+  });
+
+  test('something would change → drift, and never blocked', () => {
+    const finding = classifyHostRecap(recap({ changed: 3 }), 'wireguard-manager');
+    expect(finding.state).toBe('drift');
+    expect(finding.detail).toContain('celilo module deploy wireguard-manager');
+  });
+
+  test('unreachable → unmeasured, not converged', () => {
+    expect(classifyHostRecap(recap({ unreachable: 1 }), 'm').state).toBe('unmeasured');
+  });
+
+  test('failed → unmeasured', () => {
+    expect(classifyHostRecap(recap({ failed: 1 }), 'm').state).toBe('unmeasured');
+  });
+
+  test('THE case that must not read as converged: check mode skipped tasks', () => {
+    // Ansible does not evaluate a task it cannot support — it SKIPS it. A role
+    // of `command:` / `shell:` tasks can finish with changed=0 having never
+    // been applied to the host at all. Two states would call that converged.
+    const finding = classifyHostRecap(recap({ skipped: 4 }), 'm');
+    expect(finding.state).toBe('unmeasured');
+    expect(finding.detail).toContain('4 task(s)');
+  });
+
+  test('a skip outranks a change, because the run as a whole was not measured', () => {
+    expect(classifyHostRecap(recap({ skipped: 1, changed: 2 }), 'm').state).toBe('unmeasured');
+  });
+});
+
+describe('verifyModuleOnHosts', () => {
+  function generatedTreeWithPlaybook(): string {
+    const root = mkdtempSync(join(tmpdir(), 'celilo-hostplane-'));
+    mkdirSync(join(root, 'ansible'), { recursive: true });
+    writeFileSync(join(root, 'ansible', 'playbook.yml'), '---\n- hosts: all\n');
+    return root;
+  }
+
+  const manifest = { id: 'm', name: 'M', version: '1.0.0' } as unknown as ModuleManifest;
+
+  test('a manifest opt-out is carried back, not silently dropped', async () => {
+    const optedOut = {
+      ...manifest,
+      verify: { deep: false, reason: 'the role is command:-driven' },
+    } as unknown as ModuleManifest;
+
+    const result = await verifyModuleOnHosts({
+      moduleId: 'm',
+      manifest: optedOut,
+      generatedPath: '/nonexistent',
+      execute: async () => {
+        throw new Error('must not run ansible for an opted-out module');
+      },
+    });
+    expect(result.optedOut?.reason).toBe('the role is command:-driven');
+    expect(result.findings).toEqual([]);
+  });
+
+  test('no generated playbook is unmeasured, not clean', async () => {
+    const result = await verifyModuleOnHosts({
+      moduleId: 'm',
+      manifest,
+      generatedPath: '/nonexistent',
+      execute: async () => {
+        throw new Error('must not run ansible without a playbook');
+      },
+    });
+    expect(result.findings.map((f) => f.state)).toEqual(['unmeasured']);
+  });
+
+  test('a run producing no PLAY RECAP is unmeasured, not clean', async () => {
+    // celilo#951's shape in another comparator: nothing measured, rendered as
+    // nothing wrong.
+    const root = generatedTreeWithPlaybook();
+    try {
+      const result = await verifyModuleOnHosts({
+        moduleId: 'm',
+        manifest,
+        generatedPath: root,
+        execute: async () => ({ success: false, output: 'ssh: connect refused', error: 'boom' }),
+      });
+      expect(result.findings.map((f) => f.state)).toEqual(['unmeasured']);
+      expect(result.findings[0]?.detail).toContain('no PLAY RECAP');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('one finding per host in the recap', async () => {
+    const root = generatedTreeWithPlaybook();
+    try {
+      const result = await verifyModuleOnHosts({
+        moduleId: 'm',
+        manifest,
+        generatedPath: root,
+        execute: async () => ({
+          success: true,
+          output: [
+            'PLAY RECAP *********',
+            'vpn-manager : ok=10 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0',
+            'edge : ok=4 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0',
+          ].join('\n'),
+        }),
+      });
+      expect(result.findings).toEqual([
+        { hostname: 'vpn-manager', state: 'converged' },
+        expect.objectContaining({ hostname: 'edge', state: 'drift' }),
+      ]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/module/packaging/host-plane.ts

@@ -0,0 +1,135 @@
+/**
+ * The third plane: is the code running on the host the code we generated?
+ *
+ * Measured by asking Ansible, not by hashing files. celilo does not know where
+ * Ansible puts what it writes — the destination lives in the role's
+ * `tasks/main.yml` `dest:`, which celilo does not parse and should not start
+ * parsing. Ansible already computes exactly this, for every task, including
+ * templated files whose content celilo could not predict
+ * (openspec/changes/module-integrity-rigor, D4).
+ *
+ * This SSHes to every system the module deploys, so it is gated behind
+ * `--deep` and never runs in a default pass.
+ *
+ * The honest caveat, in the spec and not only in the code: check mode does not
+ * evaluate a task it cannot support — it SKIPS it — so a role built from
+ * `command:` / `shell:` tasks can finish a check run with `changed=0` having
+ * never been applied to the host at all. So a skip is `unmeasured`, never a
+ * pass, and a finding here is `drift`, never `blocked`. A check that cries wolf
+ * is the disease; shipping one here would be an unusually stupid way to catch
+ * it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ModuleManifest } from '../../manifest/schema';
+import { executeAnsible, parseAnsibleRecap } from '../../services/deploy-ansible';
+
+/**
+ * `unmeasured` is not a hedge and must never collapse into `converged`.
+ * Absence of a change is not evidence of convergence when nothing was assessed.
+ */
+export type HostPlaneState = 'converged' | 'drift' | 'unmeasured';
+
+export interface HostPlaneFinding {
+  hostname: string;
+  state: HostPlaneState;
+  /** Why, in operator-facing words. Always set for anything but `converged`. */
+  detail?: string;
+}
+
+export interface HostPlaneResult {
+  findings: HostPlaneFinding[];
+  /**
+   * Set when the module declared `verify.deep: false`. Carried so callers can
+   * PRINT the opt-out — an opt-out nobody sees is a check that quietly
+   * disappeared.
+   */
+  optedOut?: { reason: string };
+}
+
+/**
+ * Classify one Ansible `PLAY RECAP` line. Pure, so the interesting decisions
+ * are testable without an SSH round trip.
+ */
+export function classifyHostRecap(
+  recap: { host: string; changed: number; unreachable: number; failed: number; skipped: number },
+  moduleId: string,
+): HostPlaneFinding {
+  if (recap.unreachable > 0 || recap.failed > 0) {
+    return {
+      hostname: recap.host,
+      state: 'unmeasured',
+      detail: 'The host could not be evaluated — it did not answer, or the play errored on it.',
+    };
+  }
+  if (recap.skipped > 0) {
+    return {
+      hostname: recap.host,
+      state: 'unmeasured',
+      detail: `${recap.skipped} task(s) check mode cannot evaluate were skipped, so convergence was not measured. Prefer check-capable Ansible modules (copy, template, lineinfile, file, package, service), or give a command/shell task an honest changed_when:.`,
+    };
+  }
+  if (recap.changed > 0) {
+    return {
+      hostname: recap.host,
+      state: 'drift',
+      detail: `The playbook would change ${recap.changed} thing(s) on this host, so what is running is not what celilo generated. Run 'celilo module deploy ${moduleId}' to converge it.`,
+    };
+  }
+  return { hostname: recap.host, state: 'converged' };
+}
+
+/**
+ * Evaluate the module's generated playbook against its systems in check mode.
+ *
+ * `executeAnsible(..., { check: true })` is the existing plumbing and the only
+ * one — `--check` is one argument, not a second execution path.
+ */
+export async function verifyModuleOnHosts(args: {
+  moduleId: string;
+  manifest: ModuleManifest;
+  generatedPath: string;
+  /** Injected in tests, exactly as `verifyAspectCoverage` does it. */
+  execute?: typeof executeAnsible;
+}): Promise<HostPlaneResult> {
+  const { moduleId, manifest, generatedPath } = args;
+
+  if (manifest.verify?.deep === false) {
+    return { findings: [], optedOut: { reason: manifest.verify.reason } };
+  }
+
+  const playbookPath = join(generatedPath, 'ansible', 'playbook.yml');
+  if (!existsSync(playbookPath)) {
+    return {
+      findings: [
+        {
+          hostname: '(none)',
+          state: 'unmeasured',
+          detail: `No generated playbook at ${playbookPath}. Run 'celilo module generate ${moduleId}' first.`,
+        },
+      ],
+    };
+  }
+
+  const execute = args.execute ?? executeAnsible;
+  const result = await execute(generatedPath, { check: true, noInteractive: true });
+  const recaps = parseAnsibleRecap(result.output ?? '');
+
+  if (recaps.length === 0) {
+    // A run that produced no recap at all must not read as success. This is
+    // the shape celilo#951 got wrong in another comparator: nothing measured,
+    // rendered as nothing wrong.
+    return {
+      findings: [
+        {
+          hostname: '(none)',
+          state: 'unmeasured',
+          detail: `Ansible produced no PLAY RECAP, so nothing was measured.${result.error ? ` ${result.error}` : ''}`,
+        },
+      ],
+    };
+  }
+
+  return { findings: recaps.map((recap) => classifyHostRecap(recap, moduleId)) };
+}

package/src/module/packaging/package-rules.ts

@@ -42,3 +42,65 @@ export function includeNodeModulesPath(relPath: string): boolean {
   if (nmIdx + 2 >= segments.length) return true; // node_modules/@celilo dir itself
   return segments[nmIdx + 2] === 'capabilities';
 }
+
+/**
+ * What a module-relative path IS, for integrity purposes.
+ *
+ * - `package`  the module's own content. Belongs in `checksums.json` and must
+ *              match it. A mismatch is a real finding.
+ * - `derived`  celilo writes or rewrites the on-disk copy, so its content is
+ *              not a stable integrity claim. Never a finding.
+ * - `unknown`  neither. Never packaged, never installed, and the only kind of
+ *              `[EXTRA]` worth printing.
+ */
+export type ModulePathClass = 'package' | 'derived' | 'unknown';
+
+/**
+ * The one answer to "what belongs to a module", replacing the four divergent
+ * copies that used to decide it independently (`build.ts#shouldExclude`,
+ * `audit.ts#FRAMEWORK_OWNED_PATHS`, `extract.ts#scanDirectory`,
+ * `import.ts#copyModuleFiles`). Every disagreement between them became a
+ * `module verify` violation — 72 of them across two healthy modules.
+ *
+ * `scripts/node_modules/**` is the interesting case: it is `derived`, because
+ * `module import` runs `bun install` over it and the bytes on disk stop
+ * matching the package's. It is nonetheless SHIPPED, because a target may have
+ * no reachable registry (ISS-0046) — that carve-out lives in `build.ts`, which
+ * composes this function with `includeNodeModulesPath` rather than restating
+ * either rule.
+ */
+export function classifyModulePath(relPath: string): ModulePathClass {
+  const segments = relPath.split('/');
+  const name = segments[segments.length - 1] ?? '';
+
+  // The module's own e2e/ tree is tests plus their deps, including a
+  // node_modules of its own. Excluded whole, before anything below.
+  if (segments[0] === 'e2e') return 'unknown';
+
+  // Anything under a `node_modules` segment is decided by the canonical rule
+  // and by nothing else. Ordering matters: a vendored dependency ships files
+  // named `*.test.ts` (`@celilo/capabilities/src/remote.test.ts` is on the
+  // fleet right now) and those are the DEPENDENCY's, not the module's.
+  if (segments.includes('node_modules')) {
+    return includeNodeModulesPath(relPath) ? 'derived' : 'unknown';
+  }
+
+  // Source-tree noise. A module's git repo has it, a module's install never
+  // should, so on an installed tree it is a real finding.
+  if (segments.some((s) => s === '.git' || s === '.next' || s === '.cache')) return 'unknown';
+  if (name === '.DS_Store') return 'unknown';
+  // scripts/tsconfig.json exists so tsc can check hooks in CI. Nothing on a
+  // target ever runs tsc.
+  if (name === 'tsconfig.json') return 'unknown';
+  if (name.endsWith('.netapp') || name.endsWith('.test.ts')) return 'unknown';
+
+  // Celilo's own output under the module's install root.
+  if (segments[0] === 'generated' || segments[0] === 'screenshots') return 'derived';
+  // A checksum manifest cannot list itself, nor the signature over it.
+  if (relPath === 'checksums.json' || relPath === 'signature.sig') return 'derived';
+  // Regenerated by `module import` from the manifest (HOOK_API_V2 Phase 2).
+  if (relPath === 'celilo/types.d.ts') return 'derived';
+  if (relPath === 'cookies.json') return 'derived';
+
+  return 'package';
+}

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

@@ -0,0 +1,164 @@
+/**
+ * The scan rules themselves, and the proof that packaging refuses a module that
+ * breaks them.
+ *
+ * `no-hand-built-ssh.test.ts` asserts the CURRENT tree is clean, which is a
+ * different claim: it passes both when the rules work and when they match
+ * nothing. These tests are the ones that fail if a rule stops catching things.
+ */
+
+import { describe, expect, it } from 'bun:test';
+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';
+
+const rules = (src: string) => scanModuleScriptSource('f.ts', src).map((v) => v.rule);
+
+describe('module script scan — SSH rules', () => {
+  it('catches a hand-built ssh string', () => {
+    expect(rules("run(`ssh root@${ip} 'systemctl restart x'`);")).toContain(
+      'raw ssh invocation (ssh … root@)',
+    );
+  });
+
+  it('catches StrictHostKeyChecking however it is invoked', () => {
+    expect(rules("const c = 'ssh -o StrictHostKeyChecking=no host';")).toContain(
+      'raw ssh invocation (StrictHostKeyChecking)',
+    );
+  });
+
+  it('catches an ssh2 import', () => {
+    expect(rules("import { Client } from 'ssh2';")).toContain("'ssh2' import");
+  });
+
+  it('does not fire on ordinary module code', () => {
+    expect(rules('const x = probe(system, { kind: "systemd", unit: "caddy" }, run);')).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(
+      'unjustified raw-exec escape hatch',
+    );
+  });
+
+  it('flags runAppCommandWithSecret too', () => {
+    expect(rules('const r = runAppCommandWithSecret(system, cli, secret, run);')).toContain(
+      'unjustified raw-exec escape hatch',
+    );
+  });
+
+  it('accepts a call justified immediately above', () => {
+    const src = [
+      '// escape-hatch: forgejo admin user create is CLI-only, no HTTP API path.',
+      'const r = runAppCommand(system, cmd, run);',
+    ].join('\n');
+    expect(rules(src)).toEqual([]);
+  });
+
+  it('accepts a call wrapped in waitFor, justified above the enclosing statement', () => {
+    // The real shape in modules/caddy-internal — the justification sits above
+    // `const ready = await waitFor(`, a few lines up from the call itself.
+    const src = [
+      '// escape-hatch: the command output IS the payload; no API to ask.',
+      'const ready = await waitFor(',
+      '  () =>',
+      '    runAppCommand(target, CMD, run, {',
+      '      timeoutMs: 10_000,',
+      '    }).ok,',
+      ');',
+    ].join('\n');
+    expect(rules(src)).toEqual([]);
+  });
+
+  it('does not let a distant hatch launder a later call', () => {
+    const src = [
+      '// escape-hatch: justifies the call directly below it, and nothing else.',
+      'const a = runAppCommand(system, one, run);',
+      ...Array(12).fill('doSomethingElse();'),
+      'const b = runAppCommand(system, two, run);',
+    ].join('\n');
+    // Exactly one violation: the second call, which has no hatch in reach.
+    expect(rules(src)).toEqual(['unjustified raw-exec escape hatch']);
+  });
+
+  it('does not flag the import of runAppCommand', () => {
+    expect(rules("import { runAppCommand, probe } from '@celilo/capabilities';")).toEqual([]);
+  });
+});
+
+describe('module script scan — what it deliberately does not scan', () => {
+  let dir: string;
+
+  function write(rel: string, content: string): void {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+
+  it('ignores bundled node_modules and test files', () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-scan-test-'));
+    try {
+      write('manifest.yml', 'id: demo\n');
+      // @celilo/capabilities legitimately BUILDS the ssh string these rules ban.
+      // Scanning the bundled closure would fail every module in the fleet.
+      write(
+        'scripts/node_modules/@celilo/capabilities/src/remote.ts',
+        'const c = `ssh -o StrictHostKeyChecking=no root@${ip} ${cmd}`;',
+      );
+      write('scripts/setup.test.ts', "run('ssh root@host uptime');");
+      write('scripts/setup.ts', 'export const fine = 1;\n');
+      expect(scanModuleDirectory(dir)).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('packaging refuses a module that breaks the policy', () => {
+  let dir: string;
+
+  function write(rel: string, content: string): void {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+
+  it('fails the build, naming the file, line and rule', async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-package-policy-'));
+    try {
+      write('manifest.yml', 'id: demo\nversion: 0.1.0\n');
+      write(
+        'scripts/setup.ts',
+        ['export function bad(ip: string) {', '  return `ssh root@${ip} uptime`;', '}'].join('\n'),
+      );
+
+      const result = await buildModule({ sourceDir: dir });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('scripts/setup.ts:2');
+      expect(result.error).toContain('raw ssh invocation');
+      expect(result.error).toContain('MODULE_PRIMITIVES.md');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('fails the build for an unjustified escape hatch', async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-package-policy-'));
+    try {
+      write('manifest.yml', 'id: demo\nversion: 0.1.0\n');
+      write('scripts/setup.ts', 'const r = runAppCommand(system, "rm -rf /srv", run);\n');
+
+      const result = await buildModule({ sourceDir: dir });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('unjustified raw-exec escape hatch');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});