@celilo/cli 1.1.0 → 1.2.0

package/src/policy/no-module-business-in-core.test.ts

@@ -0,0 +1,504 @@
+/**
+ * Recurrence gate for openspec/changes/module-business-barrier/inventory.md
+ * section 5: **celilo orchestrates modules; it does not know what they do.**
+ *
+ * Core may record who asked for what, who owns it, and when it dies. It may not
+ * model a provider's own configuration. The tell is a column, branch or literal
+ * that only makes sense once you know the implementation — `websocket`,
+ * `content_hash`, `iptables-save`, `/srv/www/<slug>`, port `9000`.
+ *
+ * Four scans, one baseline (`./module-business-baseline.ts`), one sanity test.
+ * The baseline may shrink freely and may only grow with a justification a
+ * reviewer sees, so the gate ratchets rather than demanding the migration land
+ * first — a gate that demanded that would be deleted before the migration
+ * arrived, which is how this pattern regrew the first time.
+ *
+ * Why a gate at all: the pattern regrew INSIDE the change that was removing it.
+ * `capability-loader.ts`'s capability-name branches went 6 -> 7 in `baf2c70d`,
+ * celilo#847 part 1, whose stated purpose was deleting the one hardcoded
+ * capability call from core. Nobody was careless. Each addition looks reasonable
+ * on its own, which is exactly why something mechanical has to stop it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+import {
+  CAPABILITY_NAME_BASELINE,
+  CAPABILITY_OWNED_TABLES,
+  PROVIDER_LITERAL_BASELINE,
+  SERVICE_FILENAME_BASELINE,
+} from './module-business-baseline';
+
+/** 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/)');
+}
+
+const ROOT = repoRoot();
+const SCHEMA_PATH = join(ROOT, 'apps/celilo/src/db/schema.ts');
+
+/**
+ * Roots that make up "core" for scans B and D: the celilo backend, and the
+ * shared package every module bundles.
+ */
+const CORE_ROOTS = ['apps/celilo/src', 'packages/capabilities/src'];
+
+/**
+ * Excluded from the name/literal scans, both load-bearing:
+ *
+ * - `capability-registry.ts` is where the names are SOURCED from. It contains
+ *   every name twice by construction (interface key + array entry) — 26 rows
+ *   that can never shrink because they are the definition, not the debt.
+ * - `src/policy/` is this gate. Its baseline necessarily names every capability
+ *   and every seed literal; without this the gate fails on itself.
+ */
+const SCAN_EXCLUSIONS = [
+  'packages/capabilities/src/capability-registry.ts',
+  'apps/celilo/src/policy',
+];
+
+/** Repo-relative POSIX path, so baseline entries are stable across checkouts. */
+function rel(absolute: string): string {
+  return relative(ROOT, absolute).split('\\').join('/');
+}
+
+function isExcluded(file: string): boolean {
+  const r = rel(file);
+  return SCAN_EXCLUSIONS.some((ex) => r === ex || r.startsWith(`${ex}/`));
+}
+
+/** Every production `.ts` under a root (excludes node_modules, tests, declarations). */
+function productionSources(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === 'node_modules') continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (p.endsWith('.ts') && !p.endsWith('.test.ts') && !p.endsWith('.d.ts')) out.push(p);
+    }
+  };
+  const abs = join(ROOT, root);
+  if (existsSync(abs)) walk(abs);
+  return out.filter((f) => !isExcluded(f));
+}
+
+/**
+ * Remove comments, keep string literals.
+ *
+ * Comments must not count: schema.ts and the loader both discuss capabilities in
+ * prose, and a gate that fires on an edited sentence gets deleted. Strings MUST
+ * count — `capName === 'firewall'` is the primary violation shape.
+ *
+ * Known limit: a regex literal containing `//` or `/*` would be mis-read as a
+ * comment. None exists in the scanned roots, and the failure direction is
+ * under-reporting, which the baseline's exact counts surface as a spurious
+ * "improvement" rather than a silent pass.
+ */
+function stripComments(src: string): string {
+  let out = '';
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (c === '/' && d === '/') {
+      while (i < n && src[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && d === '*') {
+      i += 2;
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      const quote = c;
+      out += c;
+      i++;
+      while (i < n) {
+        if (src[i] === '\\') {
+          out += src[i] + (src[i + 1] ?? '');
+          i += 2;
+          continue;
+        }
+        if (src[i] === quote) break;
+        out += src[i];
+        i++;
+      }
+      out += quote;
+      i++;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/**
+ * Compare a measured set against the baseline and describe the difference the
+ * way the reader needs to hear it.
+ *
+ * Growth is a violation. Shrinkage is an improvement and still fails, because a
+ * baseline that silently keeps headroom lets the count creep back up later — the
+ * ratchet only holds if the recorded number is the real one.
+ */
+function diffAgainstBaseline<T>(
+  measured: Map<string, T>,
+  baseline: Map<string, T>,
+  describe: (key: string, value: T) => string,
+  fix: string,
+): string[] {
+  const problems: string[] = [];
+  for (const [key, value] of measured) {
+    if (!baseline.has(key)) problems.push(`NEW      ${describe(key, value)}\n           ${fix}`);
+    else if (JSON.stringify(baseline.get(key)) !== JSON.stringify(value)) {
+      problems.push(
+        `CHANGED  ${describe(key, value)}\n           baseline says ${JSON.stringify(baseline.get(key))}, tree has ${JSON.stringify(value)}.\n           If you REMOVED some, lower the baseline — thank you. If you added some, ${fix}`,
+      );
+    }
+  }
+  for (const [key, value] of baseline) {
+    if (!measured.has(key)) {
+      problems.push(
+        `GONE     ${describe(key, value)}\n           Fixed — delete this row from module-business-baseline.ts.`,
+      );
+    }
+  }
+  return problems;
+}
+
+// ---------------------------------------------------------------------------
+// Scan A — every table declares an owner
+// ---------------------------------------------------------------------------
+
+interface TableDeclaration {
+  readonly name: string;
+  /** 1-based line of the `export const … = sqliteTable(` declaration. */
+  readonly line: number;
+  readonly owner: string | null;
+}
+
+/**
+ * Parse every `sqliteTable(` in schema.ts and resolve its owner tag.
+ *
+ * Anchors on the `sqliteTable(` token — the one thing definitionally present —
+ * and walks BACK to the declaration and then to the docblock. The obvious
+ * alternative, matching `^export const [A-Za-z]+ = sqliteTable\(`, is the regex
+ * that checks the audit's appendix and it must not be reused here: it needs
+ * column zero, `export`, and a letters-only const name. In a checker each miss
+ * fails loudly (a short count, a visible diff row); in a GATE the identical miss
+ * fails OPEN — an unmatched table is simply never required to carry a tag and
+ * nothing goes red. `export const oauth2Tokens = sqliteTable(` defeats it on the
+ * digit alone.
+ *
+ * So an unparseable declaration THROWS rather than being skipped: the gate must
+ * distinguish "nothing to check" from "could not check".
+ */
+function parseTableDeclarations(): TableDeclaration[] {
+  const lines = readFileSync(SCHEMA_PATH, 'utf-8').split('\n');
+  const tables: TableDeclaration[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes('sqliteTable(')) continue;
+
+    // 22 tables are single-line (`= sqliteTable('name', {`), 15 put the name on
+    // the following line. Both forms, no exceptions.
+    const name =
+      lines[i].match(/sqliteTable\(\s*'([a-z0-9_]+)'/)?.[1] ??
+      lines[i + 1]?.match(/^\s*'([a-z0-9_]+)',/)?.[1];
+    if (!name) {
+      throw new Error(
+        `schema.ts:${i + 1}: sqliteTable( whose table name could not be resolved.
+The gate cannot check a table it cannot name. Declare it in one of the two
+existing forms: sqliteTable('name', { … }) or the multi-line form with the name
+on the following line.`,
+      );
+    }
+
+    // Walk back to the docblock. Exported type aliases sit between docblock and
+    // table for module_builds, backup_storages, backups and module_operations —
+    // a naive "docblock immediately above" parser reports those four as missing
+    // a tag they carry, and the natural fix is to paste a second docblock.
+    let j = i - 1;
+    while (j >= 0 && !lines[j].trimEnd().endsWith('*/')) {
+      const text = lines[j].trim();
+      const skippable =
+        text === '' || text.startsWith('export type') || text.startsWith('|') || text.endsWith(';');
+      if (!skippable) break;
+      j--;
+    }
+
+    let owner: string | null = null;
+    if (j >= 0 && lines[j].trimEnd().endsWith('*/')) {
+      for (let k = j; k >= 0; k--) {
+        const tag = lines[k].match(/@owner\s+(\S+)/);
+        if (tag) {
+          owner = tag[1];
+          break;
+        }
+        if (lines[k].includes('/**')) break;
+      }
+    }
+
+    tables.push({ name, line: i + 1, owner });
+  }
+
+  return tables;
+}
+
+describe('recurrence gate: celilo core holds no module business — Scan A (table owners)', () => {
+  const tables = parseTableDeclarations();
+
+  test('scans every table in schema.ts (sanity — the scan actually ran)', () => {
+    expect(tables.length).toBeGreaterThan(30);
+  });
+
+  test('every sqliteTable declares an @owner', () => {
+    const untagged = tables
+      .filter((t) => t.owner === null)
+      .map(
+        (t) =>
+          `schema.ts:${t.line} '${t.name}' has no @owner tag.
+    Add one to its docblock: ' * @owner celilo — <why this is cross-module bookkeeping>'
+    or ' * @owner capability:<name> — <which provider's domain this models>'.
+    See openspec/changes/module-business-barrier/inventory.md section 5.`,
+      );
+    expect(untagged, `Tables missing an @owner tag:\n  ${untagged.join('\n  ')}`).toEqual([]);
+  });
+
+  test('@owner capability:<name> names a real capability', () => {
+    const known = new Set<string>(KNOWN_CAPABILITY_NAMES);
+    const bogus = tables
+      .filter((t) => t.owner?.startsWith('capability:'))
+      .filter((t) => !known.has(t.owner?.slice('capability:'.length) ?? ''))
+      .map(
+        (t) =>
+          `schema.ts:${t.line} '${t.name}' is tagged '${t.owner}', which is not in KNOWN_CAPABILITY_NAMES.`,
+      );
+    expect(bogus, `Unknown capability in an @owner tag:\n  ${bogus.join('\n  ')}`).toEqual([]);
+  });
+
+  test('the set of capability-owned tables equals the baseline', () => {
+    const measured = new Map(
+      tables
+        .filter((t) => t.owner?.startsWith('capability:'))
+        .map((t) => [t.name, t.owner?.slice('capability:'.length) ?? ''] as const),
+    );
+    const baseline = new Map(Object.entries(CAPABILITY_OWNED_TABLES));
+
+    const problems = diffAgainstBaseline(
+      measured,
+      baseline,
+      (table, capability) => `table '${table}' is owned by capability '${capability}'`,
+      "A new table modelling one capability's domain belongs in that provider's module_configs\n           (the wireguard-manager D2 precedent), not in core's schema. If core genuinely must\n           hold it, add it to CAPABILITY_OWNED_TABLES with the reason.",
+    );
+    expect(
+      problems,
+      `Scan A — capability-owned tables changed:\n  ${problems.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scan B — capability names in core
+// ---------------------------------------------------------------------------
+
+/**
+ * Three forms, stated as regex because "string literal or object key" is where
+ * an implementer silently guesses. Property access is not optional: audit row X3
+ * (`capabilitiesMap.dns_internal.server.ip`) is a violation the first two forms
+ * do not see.
+ */
+function capabilityNameOccurrences(code: string, capability: string): number {
+  const stringLiteral = `['"\`]${capability}['"\`]`; //            capName === 'firewall'
+  const objectKey = `(?<![A-Za-z0-9_$])${capability}\\s*:`; //     public_web: 'dmz'
+  const propertyAccess = `\\.${capability}`; //                    caps.dns_internal
+  const pattern = new RegExp(
+    `(?:${stringLiteral}|${objectKey}|${propertyAccess})(?![A-Za-z0-9_])`,
+    'g',
+  );
+  return (code.match(pattern) ?? []).length;
+}
+
+function scanCapabilityNames(): Map<string, number> {
+  const measured = new Map<string, number>();
+  for (const root of CORE_ROOTS) {
+    for (const file of productionSources(root)) {
+      const code = stripComments(readFileSync(file, 'utf-8'));
+      for (const capability of KNOWN_CAPABILITY_NAMES) {
+        const count = capabilityNameOccurrences(code, capability);
+        if (count > 0) measured.set(`${rel(file)}::${capability}`, count);
+      }
+    }
+  }
+  return measured;
+}
+
+describe('recurrence gate: celilo core holds no module business — Scan B (capability names)', () => {
+  const measured = scanCapabilityNames();
+
+  test('scans a non-trivial set of core sources (sanity — the scan actually ran)', () => {
+    const scanned = CORE_ROOTS.flatMap(productionSources);
+    expect(scanned.length).toBeGreaterThan(100);
+    expect(KNOWN_CAPABILITY_NAMES.length).toBeGreaterThan(5);
+  });
+
+  test('no new capability name appears in core', () => {
+    const baseline = new Map(
+      CAPABILITY_NAME_BASELINE.map((row) => [`${row.file}::${row.capability}`, row.count] as const),
+    );
+    const problems = diffAgainstBaseline(
+      measured,
+      baseline,
+      (key, count) => {
+        const [file, capability] = key.split('::');
+        return `${file} names '${capability}' ${count}x`;
+      },
+      'Core branching on a capability NAME is the pattern this gate exists to stop. Let the\n           provider declare the behaviour in its manifest instead. If it truly must land here,\n           add the row to CAPABILITY_NAME_BASELINE with a one-line justification.',
+    );
+    expect(problems, `Scan B — capability names in core:\n  ${problems.join('\n  ')}`).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scan C — service filenames
+// ---------------------------------------------------------------------------
+
+/** `public_web` -> `public-web`: capability names are snake_case, filenames kebab. */
+function kebab(capability: string): string {
+  return capability.split('_').join('-');
+}
+
+/**
+ * Recurses over `services/**` rather than naming `services/` + `services/audit/`.
+ * Non-recursive gives 4 hits and recursive 5, and the extra one
+ * (`alerting/notification-responder.ts`) is a false positive — but narrowing to
+ * dodge one baseline row would leave five subdirectories unwatched, including
+ * `alerting/`, which is precisely where a `notification`-capability leak lands.
+ */
+function scanServiceFilenames(): Map<string, string> {
+  const measured = new Map<string, string>();
+  for (const file of productionSources('apps/celilo/src/services')) {
+    const stem = (file.split('/').pop() ?? '').replace(/\.ts$/, '');
+    const segments = stem.split('-');
+    for (const capability of KNOWN_CAPABILITY_NAMES) {
+      const wanted = kebab(capability).split('-');
+      const present = segments.some((_, i) =>
+        wanted.every((part, offset) => segments[i + offset] === part),
+      );
+      if (present) measured.set(`${rel(file)}::${capability}`, capability);
+    }
+  }
+  return measured;
+}
+
+describe('recurrence gate: celilo core holds no module business — Scan C (service filenames)', () => {
+  const measured = scanServiceFilenames();
+
+  test('scans the whole services tree (sanity — the scan actually ran)', () => {
+    const scanned = productionSources('apps/celilo/src/services');
+    expect(scanned.length).toBeGreaterThan(50);
+    // Recursion is the point: subdirectories must be in the walk.
+    expect(scanned.some((f) => rel(f).includes('/services/audit/'))).toBe(true);
+    expect(scanned.some((f) => rel(f).includes('/services/alerting/'))).toBe(true);
+  });
+
+  test('no new service file is named after a capability', () => {
+    const baseline = new Map(
+      SERVICE_FILENAME_BASELINE.map(
+        (row) => [`${row.file}::${row.capability}`, row.capability] as const,
+      ),
+    );
+    const problems = diffAgainstBaseline(
+      measured,
+      baseline,
+      (key, capability) => `${key.split('::')[0]} is named after capability '${capability}'`,
+      "A core service named after one capability is core doing that provider's work. Name it for\n           the generic mechanism, or move it into the provider. If it must stay, baseline it.",
+    );
+    expect(
+      problems,
+      `Scan C — capability-named service files:\n  ${problems.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scan D — provider-implementation literals
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider knowledge does not always name the capability. Audit row X11 (core
+ * shelling `wg pubkey`) has zero capability-name hits, is not a table and is not
+ * a service file — it is invisible to A, B and C, so without this scan the gate
+ * covers 47 of 48 rows.
+ *
+ * A real gate, not a warning: three known-true seeds plus a baseline has no
+ * false-positive problem, and "a gate nobody has seen fail is not a gate"
+ * (Rule 7.6) is the argument section 5 makes everywhere else.
+ *
+ * Seeded from what the audit actually found. Grow it only with a literal someone
+ * has seen in a real violation — this is a ratchet, not a predictor.
+ */
+const PROVIDER_LITERALS = [
+  { literal: 'iptables-save', catches: "S8 — core parsing a firewall's live ruleset" },
+  { literal: 'wg pubkey', catches: "X11 — core shelling WireGuard's CLI" },
+  { literal: '/srv/www', catches: "X8/S2 — core knowing caddy's on-disk asset layout" },
+] as const;
+
+function scanProviderLiterals(): Map<string, number> {
+  const measured = new Map<string, number>();
+  for (const root of CORE_ROOTS) {
+    for (const file of productionSources(root)) {
+      const code = stripComments(readFileSync(file, 'utf-8'));
+      for (const { literal } of PROVIDER_LITERALS) {
+        const count = code.split(literal).length - 1;
+        if (count > 0) measured.set(`${rel(file)}::${literal}`, count);
+      }
+    }
+  }
+  return measured;
+}
+
+describe('recurrence gate: celilo core holds no module business — Scan D (provider literals)', () => {
+  const measured = scanProviderLiterals();
+
+  test('every seed literal is a known-true violation somewhere (sanity — the scan can fire)', () => {
+    // If a seed stops matching anywhere, either the violation was fixed (delete
+    // the seed) or the scan broke. Silence must not be mistaken for cleanliness.
+    for (const { literal } of PROVIDER_LITERALS) {
+      const hits = [...measured.keys()].filter((k) => k.endsWith(`::${literal}`));
+      expect(
+        hits.length,
+        `seed literal '${literal}' matches nothing — fix the scan or drop the seed`,
+      ).toBeGreaterThan(0);
+    }
+  });
+
+  test('no new provider-implementation literal appears in core', () => {
+    const baseline = new Map(
+      PROVIDER_LITERAL_BASELINE.map((row) => [`${row.file}::${row.literal}`, row.count] as const),
+    );
+    const problems = diffAgainstBaseline(
+      measured,
+      baseline,
+      (key, count) => {
+        const [file, literal] = key.split('::');
+        return `${file} contains '${literal}' ${count}x`;
+      },
+      "Core executing or hardcoding one provider's implementation detail belongs in that\n           provider's module. If it must stay, baseline it with the reason.",
+    );
+    expect(
+      problems,
+      `Scan D — provider-implementation literals in core:\n  ${problems.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});

package/src/services/alerting/keys.ts

@@ -174,6 +174,7 @@ export function failingKeysFromHealthItems(
   moduleId: string,
   items: HealthCheckItemLike[],
   monitorSeverity: AlertSeverity,
+  artifactPaths?: string[],
 ): FailingKey[] {
   const failing: FailingKey[] = [];
   for (const item of items) {
@@ -183,8 +184,27 @@ export function failingKeysFromHealthItems(
       key: moduleCheckAlertKey(moduleId, item.name),
       severity,
       message: item.message,
-      details: item.details,
+      details: withArtifacts(item.details, artifactPaths),
     });
   }
   return failing;
 }
+
+/**
+ * Append the run's artifact paths to an item's details.
+ *
+ * `details` is the field that reaches the operator through alerting, so
+ * this is the last link in the chain — collecting artifacts and carrying
+ * them on the result accomplishes nothing if they stop here.
+ *
+ * They go on EVERY failing item of the run rather than being attributed to
+ * one, because the framework collects per RUN and cannot know which check
+ * wrote which file. A consumer that wants a specific attribution already
+ * has one: it names the artifact in its own `details`, which is preserved
+ * above whatever the framework appends.
+ */
+function withArtifacts(details: string | undefined, artifactPaths?: string[]): string | undefined {
+  if (!artifactPaths || artifactPaths.length === 0) return details;
+  const rendered = `Artifacts:\n  ${artifactPaths.join('\n  ')}`;
+  return details ? `${details}\n\n${rendered}` : rendered;
+}

package/src/services/alerting/run-monitor.ts

@@ -77,7 +77,12 @@ async function runCheck(
     }
     return {
       outcome: 'success',
-      failingKeys: failingKeysFromHealthItems(monitor.target, result.checks, severity),
+      failingKeys: failingKeysFromHealthItems(
+        monitor.target,
+        result.checks,
+        severity,
+        result.artifactPaths,
+      ),
     };
   }