@celilo/cli 2.0.0 → 2.2.0

package/src/policy/no-swallowed-refusal.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Recurrence gate for openspec/changes/e2e-suite-recovery §4: **a hook whose
+ * framework call is refused fails, rather than continuing with an answer it
+ * invented** (spec delta `specs/module-lifecycle/spec.md`, scenario "The
+ * pattern cannot be reintroduced").
+ *
+ * The rule itself lives in `./module-script-scan`, because this is not the only
+ * place it runs — `.netapp` packaging applies the same scan at publish time.
+ * One definition, two callers.
+ *
+ * The two sites this gate exists for (e2e-suite-recovery tasks 4.1/4.2, all
+ * still in the tree on the swallow debt list; a third, knot-unbound-internal
+ * scripts/on-install.ts:69, converted on 2026-09-07 by ce-pvii and deleted
+ * from both debt lists in the same change):
+ *   modules/celilo-mgmt/scripts/on_backup.ts:52        catch { return [] }
+ *   modules/wireguard/scripts/health-check.ts:73       catch { return null }
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  SWALLOWED_REFUSAL_DEBT,
+  SWALLOWED_REFUSAL_RULE,
+  formatViolations,
+  moduleScriptFiles,
+  scanModuleDirectory,
+  scanModuleScriptSource,
+} from './module-script-scan';
+
+/** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
+function repoRoot(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'modules')) && existsSync(join(dir, 'apps'))) return dir;
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with modules/ + apps/)');
+}
+
+function moduleDirs(): string[] {
+  const modulesRoot = join(repoRoot(), 'modules');
+  return readdirSync(modulesRoot)
+    .map((m) => join(modulesRoot, m))
+    .filter((d) => statSync(d).isDirectory() && existsSync(join(d, 'scripts')));
+}
+
+/** Swallow-rule violations only — the other rules are different gates with their own tests. */
+function swallowRule(violations: ReturnType<typeof scanModuleScriptSource>) {
+  return violations.filter((v) => v.rule === SWALLOWED_REFUSAL_RULE);
+}
+
+describe('recurrence gate: a hook does not swallow a refused framework call', () => {
+  describe('the shapes it must reject', () => {
+    test('catch returning a literal below a spawned framework call (on_backup shape)', () => {
+      const source = [
+        'function snapshot(): unknown[] {',
+        '  try {',
+        "    const stdout = execSync('celilo machine list --json', { encoding: 'utf-8' });",
+        '    return JSON.parse(stdout);',
+        '  } catch {',
+        '    // older celilo, or no machines yet',
+        '    return [];',
+        '  }',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(3); // the framework-reaching call, not the catch
+    });
+
+    test('comment-only catch below an injected CLI-runner call (on_install shape)', () => {
+      const source = [
+        'function repoint(ip: string, runCelilo: (args: string[]) => string): void {',
+        '  let prior: string | undefined;',
+        '  try {',
+        "    prior = parse(runCelilo(['system', 'config', 'get', 'dns.primary']));",
+        '  } catch {',
+        '    // dns.primary not set yet — nothing to demote.',
+        '  }',
+        '  runCelilo(["system", "apply-config", `dns.primary=${ip}`]);',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(4);
+    });
+
+    test('catch returning null below execFileSync (health-check shape)', () => {
+      const source = [
+        'function read(key: string): string | null {',
+        '  try {',
+        "    const out = execFileSync('celilo', ['system', 'config', 'get', key], { encoding: 'utf-8' });",
+        '    return parse(key, out);',
+        '  } catch {',
+        '    return null;',
+        '  }',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(3);
+    });
+
+    test('log-and-continue catch below a spawned framework call', () => {
+      const source = [
+        'try {',
+        "  execSync('celilo system apply-config dns.primary=10.0.0.1');",
+        '} catch (err) {',
+        '  logger.warn(`repoint failed: ${err}`);',
+        '}',
+        'logger.success("dns.primary repointed");',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+    });
+  });
+
+  describe('the shapes it must accept', () => {
+    test('a typed-absent reader: no catch between the hook and the answer', () => {
+      const source = [
+        'export async function healthCheck(deps: HealthDeps): Promise<Output> {',
+        '  const { readConfig } = deps;',
+        '  const value = readConfig("server_public_key");',
+        '  if (!value.present) return { status: "absent", key: "server_public_key" };',
+        '  return { status: "ok", key: value.data };',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+
+    test('a catch that rethrows: the refusal propagates', () => {
+      const source = [
+        'try {',
+        "  execSync('celilo system apply-config dns.primary=10.0.0.1');",
+        '} catch (err) {',
+        '  throw new Error(`dns.primary repoint refused: ${String(err)}`);',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+
+    test('a catch below work that never reaches the framework', () => {
+      const source = [
+        'function parse(raw: string): unknown[] {',
+        '  try {',
+        '    const parsed: unknown = JSON.parse(raw);',
+        '    return Array.isArray(parsed) ? parsed : [];',
+        '  } catch {',
+        '    return [];',
+        '  }',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+  });
+
+  test('reach: the scan walks every scripts/ directory and flags every planted violation', () => {
+    // Mirror of the real layout (modules/<m>/scripts/**), planted per the
+    // reach rule: a violating hook in EVERY directory the scan should reach —
+    // the module scripts root and a nested subdirectory — plus a clean module
+    // the scan must come back empty on.
+    const root = join(repoRoot(), '.tmp-swallow-reach-fixture');
+    rmSync(root, { recursive: true, force: true });
+    const violating = (name: string) =>
+      [
+        `// ${name}`,
+        'export function run() {',
+        '  try {',
+        "    execSync('celilo system config get dns.primary');",
+        '  } catch {',
+        '    return null;',
+        '  }',
+        '}',
+      ].join('\n');
+    try {
+      const planted = [
+        'modules/alpha/scripts/one.ts',
+        'modules/alpha/scripts/nested/two.ts',
+        'modules/beta/scripts/three.ts',
+      ];
+      for (const p of planted) {
+        const f = join(root, p);
+        mkdirSync(resolve(f, '..'), { recursive: true });
+        writeFileSync(f, violating(p));
+      }
+      const cleanDir = join(root, 'modules/clean/scripts');
+      mkdirSync(cleanDir, { recursive: true });
+      writeFileSync(
+        join(cleanDir, 'clean.ts'),
+        'export function run(readConfig: (k: string) => { present: boolean }) {\n  return readConfig("k");\n}\n',
+      );
+
+      // Per-module expectation, in the module-relative paths the scan
+      // reports: every planted file came back exactly once, and the clean
+      // module contributed nothing.
+      const flagged = (m: string) =>
+        new Set(swallowRule(scanModuleDirectory(join(root, 'modules', m))).map((v) => v.file));
+      expect([...flagged('alpha')].sort()).toEqual(['scripts/nested/two.ts', 'scripts/one.ts']);
+      expect([...flagged('beta')]).toEqual(['scripts/three.ts']);
+      expect([...flagged('clean')]).toEqual([]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('today’s tree: the remaining known sites are flagged, and nothing else is', () => {
+    // Raw scan, deliberately NOT scanModuleDirectory: the debt list below
+    // exempts these same files so the merged gate stays green while
+    // hook-owned-state converts them, and this assertion has to outlive that
+    // exemption to prove the rule still reaches them.
+    const violations = moduleDirs().flatMap((d) =>
+      swallowRule(
+        moduleScriptFiles(join(d, 'scripts')).flatMap((f) =>
+          scanModuleScriptSource(f, readFileSync(f, 'utf-8')),
+        ),
+      ),
+    );
+    const sites = violations.map((v) => v.file.replace(`${repoRoot()}/`, '')).sort();
+    // Pinned to the exact sites from e2e-suite-recovery task 4.2, as measured
+    // on 2026-09-07 at on_backup.ts:52 and health-check.ts:73 (a third,
+    // on-install.ts:69, converted by ce-pvii the same day). A converted site
+    // drops out and the debt entry must go; a NEW site appearing here is the
+    // next instance this scan exists to stop.
+    expect(sites).toEqual([
+      'modules/celilo-mgmt/scripts/on_backup.ts',
+      'modules/wireguard/scripts/health-check.ts',
+    ]);
+  });
+});
+
+describe('recurrence gate: the swallow debt list is honest', () => {
+  // Same three ways this list could silently rot as the jailed-CLI-spawn debt
+  // guard, same guard for each.
+  test('every entry names an existing file carrying exactly its pinned swallow count', () => {
+    for (const entry of SWALLOWED_REFUSAL_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 === SWALLOWED_REFUSAL_RULE,
+      );
+      expect(
+        hits.length,
+        `${entry.module}/${entry.file} carries ${hits.length} swallowed refusals, 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)', () => {
+    // The list held three entries until ce-pvii converted the on-install.ts
+    // entry (2026-09-07); two remain, so the guard still proves engagement.
+    expect(SWALLOWED_REFUSAL_DEBT.length).toBeGreaterThan(1);
+  });
+});

package/src/policy/no-tar-shell-out-in-services.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Recurrence gate for celilo#1235: **services never shell out to `tar`; they
+ * use the `tar` package.**
+ *
+ * `tar@^7` is a declared dependency of @celilo/cli, but backup/restore built
+ * tar command lines and handed them to execSync. That made `tar` an undeclared
+ * runtime dependency on a host binary: Essential on Debian, so it never bit,
+ * but a container base image is where "always there" stops being true. The
+ * services now use the library (same shape the hook boundary is moving to via
+ * pack_directory), and this file keeps them there.
+ *
+ * Scoped to apps/celilo/src/services (the surface celilo#1235 covers). Test
+ * files are excluded — they legitimately drive the system tar to cross-check
+ * archives written by the library.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+function serviceSourceFiles(): string[] {
+  const dir = join(import.meta.dir, '../services');
+  const walk = (d: string): string[] =>
+    readdirSync(d).flatMap((name) => {
+      const path = join(d, name);
+      if (statSync(path).isDirectory()) return walk(path);
+      return name.endsWith('.ts') && !name.endsWith('.test.ts') ? [path] : [];
+    });
+  return walk(dir);
+}
+
+describe('recurrence gate: services never shell out to tar', () => {
+  test('scans a non-trivial set of service sources (sanity — the scan actually ran)', () => {
+    expect(serviceSourceFiles().length).toBeGreaterThan(10);
+  });
+
+  test('no service source passes a "tar ..." string to execSync', () => {
+    const offenders = serviceSourceFiles().filter((path) =>
+      /execSync\(\s*[`'"]tar /.test(readFileSync(path, 'utf-8')),
+    );
+    expect(offenders).toEqual([]);
+  });
+});

package/src/registry/client.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { createHash } from 'node:crypto';
 import type { IndexEntry } from './client';
 import { DEFAULT_REGISTRY, RegistryClient } from './client';
 
@@ -312,3 +313,151 @@ describe('RegistryClient owner methods', () => {
     );
   });
 });
+
+// ── get() retry ───────────────────────────────────────────────────────────────
+//
+// Every registry read goes through one private `get()`. It used to make exactly
+// one attempt, so a single transient — the shape the 15s→30s timeout bump was
+// already chasing — failed a module install outright. Measured 2026-09-04:
+// `module import iptables` failed twice with "Download failed: The operation
+// timed out" while the identical call had succeeded minutes earlier.
+
+describe('RegistryClient.get retry', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a transient network failure is retried and the download succeeds', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4]);
+    fetchSpy
+      .mockRejectedValueOnce(new DOMException('The operation timed out.', 'TimeoutError'))
+      .mockResolvedValueOnce(new Response(payload, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+
+    expect(new Uint8Array(data)).toEqual(payload);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 5xx is retried', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(null, { status: 503 }))
+      .mockResolvedValueOnce(new Response(new Uint8Array([9]), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4');
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 404 is NOT retried — it is an answer, not a transient', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('nope', '1.0.0')).rejects.toThrow('HTTP 404');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('gives up after a bounded number of attempts', async () => {
+    fetchSpy.mockRejectedValue(new DOMException('The operation timed out.', 'TimeoutError'));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const error = await client.download('iptables', '3.1.4').then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(Error);
+    // The exhaustion report is the event, not the last attempt (celilo#1264):
+    // the bare lastError read as an unretried first attempt, because that is
+    // exactly what the same string meant before the retry existed.
+    expect((error as Error).message).toMatch(/failed after 3 attempts over \d+(\.\d+)?s/);
+    expect((error as Error).message).toContain('The operation timed out.');
+    expect((error as { cause?: unknown }).cause).toBeInstanceOf(DOMException);
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+});
+
+// ── download integrity ────────────────────────────────────────────────────────
+//
+// `cksum` is computed at publish time, shipped in every index entry, and was
+// never checked on the consuming side. A short download was therefore accepted
+// and blew up later in gunzip as "zlib: unexpected end of file", which blames
+// the package rather than the transfer. Measured 2026-09-04 in the e2e rig.
+// Retrying cannot help a fault it cannot detect, so verification is what makes
+// the retry meaningful.
+
+describe('RegistryClient.download integrity', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+  const body = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+  // sha256 of the 8 bytes above, in the `sha256:<hex>` shape publish() writes.
+  const goodCksum = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a truncated payload is rejected and retried, then succeeds', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(body.slice(0, 3), { status: 200 })) // short
+      .mockResolvedValueOnce(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', goodCksum);
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a payload that never verifies fails with an error naming the integrity check', async () => {
+    // A fresh Response per call: one shared instance would be consumed by the
+    // first attempt and the retry would report "Body already used", hiding the
+    // integrity failure this test exists to assert.
+    fetchSpy.mockImplementation(() => new Response(body.slice(0, 3), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('iptables', '3.1.4', goodCksum)).rejects.toThrow(
+      /integrity check/i,
+    );
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+
+  test('a correct payload verifies on the first attempt', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4', goodCksum);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('no expected cksum still downloads — callers may not have one', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+    expect(new Uint8Array(data)).toEqual(body);
+  });
+
+  test('a non-digest cksum sentinel skips verification instead of failing', async () => {
+    // The registry's bootstrap path publishes `cksum: 'bootstrap'`
+    // (packages/registry-server/src/bootstrap.ts:114) because those modules are
+    // packaged on demand and have no stable digest. Treating a sentinel as a
+    // digest rejects a perfectly good 2.7MB package on every import.
+    fetchSpy.mockImplementation(() => new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', 'bootstrap');
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+});