@celilo/cli 1.7.0 → 1.8.0

package/src/policy/capability-shape-baseline.ts

@@ -0,0 +1,88 @@
+/**
+ * Expected shape hashes per capability — the fixture behind
+ * `capability-shape-drift.test.ts`.
+ *
+ * `CAPABILITY_CONTRACT_VERSIONS` is bumped BY HAND, so the whole scheme rests on
+ * a human remembering. `capability-contract.ts` used to claim that risk was
+ * "mitigated by a CI check that compares interface AST hashes against an
+ * expected fixture". No such check existed. It was designed in the retired
+ * `apps/celilo/designs/CELILO_UPDATE.md` and never built, and three design
+ * documents reasoned from it anyway (celilo#1042). This is that check.
+ *
+ * Changing a capability's interface OR its table declaration changes its hash.
+ * The test then fails until BOTH the contract version and the entry below move,
+ * in the same commit — which is the whole point, because the version is what
+ * `compareProviderToRuntime` and `celilo system audit` compare against.
+ *
+ * Comments and formatting do NOT change a hash. The interface is re-printed from
+ * its AST with comments removed before hashing, so a doc-only edit stays a patch
+ * (the bump rule `capability-contract.ts` already states).
+ *
+ * WHY THIS LIVES IN apps/celilo AND NOT NEXT TO THE CONTRACT. It needs the
+ * TypeScript compiler API to parse, and `db/schema.ts` to check a declaration
+ * against the real table. `@celilo/capabilities` is bundled into every module
+ * (celilo#173), so adding a `typescript` dependency there to serve a test would
+ * be paid for by every module on the fleet. apps/celilo already depends on both.
+ */
+
+export interface CapabilityShape {
+  /** The contract version this hash was recorded at. */
+  readonly version: string;
+  /** sha256 of the printed interface plus the capability's table declaration. */
+  readonly hash: string;
+}
+
+export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>> = {
+  public_web: {
+    version: '3.2.0',
+    hash: 'a353bf184552f1ed82e5d97c9b4609dc243718c20051a9446d8dc7174561db50',
+  },
+  idp: {
+    version: '1.2.0',
+    hash: '99eee190ed670f53595554335f23e1745b872e3226dc9ffdb1d0bf6397d6013a',
+  },
+  dns_registrar: {
+    version: '4.0.0',
+    hash: 'f5d02196a3394ec71d865beb45825160103800baf632293a769a6e72dc76236a',
+  },
+  firewall: {
+    version: '1.1.0',
+    hash: '564a83ebf8ca937faf955afc4f7bf4278fe9ed01694f0237bfbc38e2eff38408',
+  },
+  source_forge: {
+    version: '1.0.0',
+    hash: '3bc797cf8c2990c61723fb680299f6a1d4b99ac42fd0371dd9dc64d05c588991',
+  },
+  registry_publish: {
+    version: '1.0.0',
+    hash: '693e7d08e9f105acd90dd00f8f9282ab3508def16e48237b47bc0ccba7885679',
+  },
+  dhcp_server: {
+    version: '1.0.0',
+    hash: '291a247d98bc11b18ab34d40b520bec679b95a031cbd674d513b313559fa3288',
+  },
+  dns_internal: {
+    version: '1.1.0',
+    hash: 'af72e861a23f6c81fe9a1a679121b7d3ea87ac5e8167efa20d5d6323010e5fef',
+  },
+  external_web: {
+    version: '1.0.0',
+    hash: '7396028ace76938f4e892e6ef8a53450183cdbcf8dff3ce767724bd9b2276dae',
+  },
+  notification: {
+    version: '1.0.0',
+    hash: '40629722b397a314d65a448a618d600fc8560c4aae0767dd7324d497d4cc9d41',
+  },
+  control_plane_vpn: {
+    version: '1.0.0',
+    hash: '2f7f81d0b3ecb2ab6822dbc9bf837a933b25e0e157eb94d0b9b8e801417f8f14',
+  },
+  private_web: {
+    version: '1.0.0',
+    hash: '0eddb82f821fe3c7fbd503d55a24c3d5a22369af8b22de06570a371d5f485c03',
+  },
+  cross_module_read: {
+    version: '1.0.0',
+    hash: 'e152f0738c88a7105b6057037f350ce0bbcbfc5c4ccbccc3af60f1cf3f1904af',
+  },
+};

package/src/policy/capability-shape-drift.test.ts

@@ -0,0 +1,162 @@
+/**
+ * The gate `capability-contract.ts` claimed for months and did not have.
+ *
+ * Two independent failures are caught here, and they are different enough to be
+ * worth naming separately.
+ *
+ * SCAN A — a declaration that disagrees with the real table. This is the failure
+ * mode `openspec/changes/capability-owned-tables` design D4 warns is *worse than
+ * today's*: a capability whose declared shape does not match the database, where
+ * the version check still passes, "because versions live in files and the table
+ * lives in the database". A missing migration at least says `no such table`.
+ * Nothing else in the tree compares the two.
+ *
+ * SCAN B — an interface or declaration that changed with no version bump.
+ * `CAPABILITY_CONTRACT_VERSIONS` is hand-maintained, and `compareProviderToRuntime`
+ * plus `celilo system audit` both trust it. A silently-changed shape makes both
+ * of them confidently wrong. Comments and formatting are excluded, so a doc-only
+ * edit stays a patch.
+ *
+ * The subject list is DERIVED from `CapabilityRegistry` rather than written out,
+ * so a new capability is covered the day it is added rather than the day someone
+ * remembers to add it here.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { CAPABILITY_CONTRACT_VERSIONS } from '@celilo/capabilities';
+import { is } from 'drizzle-orm';
+import { SQLiteTable, getTableConfig } from 'drizzle-orm/sqlite-core';
+import * as dbSchema from '../db/schema';
+import { capabilitySubjects, shapeHash, tablesOf } from './capability-shape';
+import { CAPABILITY_SHAPE_BASELINE } from './capability-shape-baseline';
+
+/** Physical table name → the drizzle table the running code declares. */
+function drizzleTables(): Map<string, ReturnType<typeof getTableConfig>> {
+  const out = new Map<string, ReturnType<typeof getTableConfig>>();
+  for (const value of Object.values(dbSchema)) {
+    if (!is(value, SQLiteTable)) continue;
+    const config = getTableConfig(value);
+    out.set(config.name, config);
+  }
+  return out;
+}
+
+const DRIZZLE_TYPE_TO_DECLARED: Record<string, string> = {
+  SQLiteText: 'text',
+  SQLiteInteger: 'integer',
+  SQLiteBoolean: 'boolean',
+  SQLiteTimestamp: 'timestamp',
+};
+
+describe('Scan A — a declared table matches the real one', () => {
+  test('every declared table exists in db/schema.ts', async () => {
+    const tables = drizzleTables();
+    const missing: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        if (!tables.has(decl.table)) missing.push(`${capability}.${key} → ${decl.table}`);
+      }
+    }
+    expect(missing).toEqual([]);
+  });
+
+  test('every declared column exists on the real table, claim included', async () => {
+    const tables = drizzleTables();
+    const missing: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        const config = tables.get(decl.table);
+        if (!config) continue;
+        const present = new Set(config.columns.map((c) => c.name));
+        for (const column of [decl.claim.column, ...Object.keys(decl.columns)]) {
+          if (!present.has(column)) missing.push(`${capability}.${key}: ${decl.table}.${column}`);
+        }
+      }
+    }
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The half that catches a rename or a retype rather than an absence. A column
+   * declared `text` that is really an integer reads as present to the check
+   * above, and every consumer of the declaration would then be typed wrong.
+   */
+  test('every declared column has the declared type and nullability', async () => {
+    const tables = drizzleTables();
+    const wrong: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        const config = tables.get(decl.table);
+        if (!config) continue;
+        for (const [column, declared] of Object.entries(decl.columns)) {
+          const actual = config.columns.find((c) => c.name === column);
+          if (!actual) continue;
+          const base = DRIZZLE_TYPE_TO_DECLARED[actual.columnType] ?? actual.columnType;
+          const expected = declared.endsWith('?') ? declared.slice(0, -1) : declared;
+          const nullableDeclared = declared.endsWith('?');
+          if (base !== expected) {
+            wrong.push(
+              `${capability}.${key}: ${decl.table}.${column} is ${base}, declared ${expected}`,
+            );
+          }
+          if (nullableDeclared === actual.notNull) {
+            wrong.push(
+              `${capability}.${key}: ${decl.table}.${column} nullability disagrees (declared ${declared}, notNull=${actual.notNull})`,
+            );
+          }
+        }
+      }
+    }
+    expect(wrong).toEqual([]);
+  });
+});
+
+describe('Scan B — a shape change carries a version bump', () => {
+  test('every capability in the registry has a baseline entry', async () => {
+    const missing = [...capabilitySubjects().keys()].filter(
+      (name) => !(name in CAPABILITY_SHAPE_BASELINE),
+    );
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The fixture records the version its hash was taken at. If the contract has
+   * moved since, the baseline describes a shape nobody re-measured — which is
+   * how a bump lands without the regenerate that is supposed to accompany it.
+   *
+   * This does NOT catch the reverse (regenerating without bumping), and cannot:
+   * telling a deliberate shape change from an accidental one needs history the
+   * gate does not have. That case shows in review as a hash moving while a
+   * version stands still, which is why the generator reads versions from the
+   * contract rather than inventing them.
+   */
+  test('every baseline entry was taken at the CURRENT contract version', () => {
+    const versions = CAPABILITY_CONTRACT_VERSIONS as Record<string, string>;
+    const stale: string[] = [];
+    for (const capability of capabilitySubjects().keys()) {
+      const recorded = CAPABILITY_SHAPE_BASELINE[capability];
+      if (!recorded) continue;
+      if (recorded.version !== versions[capability]) {
+        stale.push(
+          `${capability}: baseline recorded at ${recorded.version}, contract is now ${versions[capability]}. Re-run bun run apps/celilo/scripts/regenerate-capability-shape-baseline.ts`,
+        );
+      }
+    }
+    expect(stale).toEqual([]);
+  });
+
+  test('no capability changed shape without moving its baseline', async () => {
+    const drifted: string[] = [];
+    for (const capability of capabilitySubjects().keys()) {
+      const recorded = CAPABILITY_SHAPE_BASELINE[capability];
+      if (!recorded) continue;
+      const actual = await shapeHash(capability);
+      if (actual !== recorded.hash) {
+        drifted.push(
+          `${capability}: shape changed. Bump CAPABILITY_CONTRACT_VERSIONS.${capability} (currently recorded at ${recorded.version}) and set its baseline hash to ${actual}.`,
+        );
+      }
+    }
+    expect(drifted).toEqual([]);
+  });
+});

package/src/policy/capability-shape.ts

@@ -0,0 +1,117 @@
+/**
+ * Reading a capability's SHAPE: its interface, and the tables it declares.
+ *
+ * Extracted from `capability-shape-drift.test.ts` so the gate and the tool that
+ * regenerates its fixture compute the same hash from the same code. Two
+ * implementations of "what is this capability's shape" would drift, and the one
+ * in the GENERATOR drifting is indistinguishable from the gate passing.
+ *
+ * Same split as `module-script-scan.ts` / `no-hand-built-ssh.test.ts` in this
+ * directory, for the same reason.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { CapabilityTableDeclaration, CapabilityTables } from '@celilo/capabilities';
+import ts from 'typescript';
+
+/** Walk up to the repo root (the dir holding both modules/ and apps/). */
+export 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 CAPABILITIES_SRC = join(repoRoot(), 'packages', 'capabilities', 'src');
+
+function parse(file: string): ts.SourceFile {
+  return ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true);
+}
+
+/**
+ * capability name → { interface type name, source file }, read out of
+ * `capability-registry.ts` itself.
+ */
+export function capabilitySubjects(): Map<string, { typeName: string; file: string }> {
+  const registryFile = join(CAPABILITIES_SRC, 'capability-registry.ts');
+  const source = parse(registryFile);
+
+  // `import type { XCapability } from './x'` → XCapability lives in ./x.ts
+  const fileOfType = new Map<string, string>();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    const specifier = (statement.moduleSpecifier as ts.StringLiteral).text;
+    for (const element of bindings.elements) {
+      fileOfType.set(
+        element.name.text,
+        join(CAPABILITIES_SRC, `${specifier.replace('./', '')}.ts`),
+      );
+    }
+  }
+
+  const subjects = new Map<string, { typeName: string; file: string }>();
+  for (const statement of source.statements) {
+    if (!ts.isInterfaceDeclaration(statement) || statement.name.text !== 'CapabilityRegistry') {
+      continue;
+    }
+    for (const member of statement.members) {
+      if (!ts.isPropertySignature(member) || !member.name || !member.type) continue;
+      const name = member.name.getText(source);
+      const typeName = member.type.getText(source);
+      const file = fileOfType.get(typeName);
+      if (file) subjects.set(name, { typeName, file });
+    }
+  }
+  return subjects;
+}
+
+/** The interface, re-printed from its AST with comments dropped. */
+function printedInterface(file: string, typeName: string): string {
+  const source = parse(file);
+  const printer = ts.createPrinter({ removeComments: true });
+  for (const statement of source.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) {
+      return printer.printNode(ts.EmitHint.Unspecified, statement, source);
+    }
+  }
+  throw new Error(`${typeName} not found in ${file}`);
+}
+
+/** Every `* satisfies CapabilityTables` const exported from a capability's module. */
+export async function tablesOf(file: string): Promise<CapabilityTables> {
+  const loaded = (await import(file)) as Record<string, unknown>;
+  const out: Record<string, CapabilityTableDeclaration> = {};
+  for (const [exportName, value] of Object.entries(loaded)) {
+    if (!exportName.endsWith('_TABLES') || typeof value !== 'object' || value === null) continue;
+    for (const [key, decl] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = decl as CapabilityTableDeclaration;
+    }
+  }
+  return out;
+}
+
+/** Order-independent so a reordered literal is not a shape change. */
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .map(([k, v]) => `${k}:${canonical(v)}`)
+      .sort();
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export async function shapeHash(capability: string): Promise<string> {
+  const subject = capabilitySubjects().get(capability);
+  if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
+  const iface = printedInterface(subject.file, subject.typeName);
+  const tables = canonical(await tablesOf(subject.file));
+  return createHash('sha256').update(`${iface}\n--tables--\n${tables}`).digest('hex');
+}

package/src/policy/dns-aspect-coverage.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The declared coverage and the aspect that does the covering must agree.
+ *
+ * `lxc-dns-at-birth` splits ownership: terraform owns birth DNS, the
+ * base-module aspect owns ongoing DNS. Terraform injects
+ * `lifecycle { ignore_changes = [nameserver] }`, so it can never correct the
+ * birth value — a zone the aspect does not cover has NO owner for ongoing DNS
+ * and its birth list is permanent. That is why the nameserver composition only
+ * strips the public resolvers for a zone the deployed provider's aspect covers
+ * (design D5d).
+ *
+ * Core reads that coverage from the provider's CAPABILITY DATA rather than
+ * looking up the provider's manifest, because core naming a capability to find
+ * its provider is what the module-business gate exists to stop. The cost of
+ * that choice is two lists in one manifest instead of one, and drift between
+ * them is not cosmetic: a zone listed as covered but absent from the aspect
+ * loses its public resolvers with nothing owning what replaces them.
+ *
+ * So this test is the thing that makes the choice safe. It is the reason the
+ * duplication is acceptable.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse } from 'yaml';
+
+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');
+}
+
+interface ProviderManifest {
+  provides?: {
+    capabilities?: { name: string; data?: { aspect?: { covered_zones?: string[] } } }[];
+  };
+  base_module_aspect?: { applicable_zones?: string[] };
+}
+
+/** Every module declaring a `dns_internal` capability, with its manifest. */
+function dnsInternalProviders(): { id: string; manifest: ProviderManifest }[] {
+  const modulesDir = join(repoRoot(), 'modules');
+  const found: { id: string; manifest: ProviderManifest }[] = [];
+  for (const id of readdirSync(modulesDir)) {
+    const path = join(modulesDir, id, 'manifest.yml');
+    if (!existsSync(path)) continue;
+    let manifest: ProviderManifest;
+    try {
+      manifest = parse(readFileSync(path, 'utf-8')) as ProviderManifest;
+    } catch {
+      continue;
+    }
+    if (manifest.provides?.capabilities?.some((c) => c.name === 'dns_internal')) {
+      found.push({ id, manifest });
+    }
+  }
+  return found;
+}
+
+describe('dns_internal providers declare the coverage their aspect actually has', () => {
+  const providers = dnsInternalProviders();
+
+  test('the scan found the providers (sanity — it actually ran)', () => {
+    // knot-unbound-internal and technitium. A scan that silently found nothing
+    // would make every assertion below vacuously true.
+    expect(providers.map((p) => p.id).sort()).toEqual(['knot-unbound-internal', 'technitium']);
+  });
+
+  test.each(dnsInternalProviders().map((p) => [p.id, p] as const))(
+    '%s: declared covered_zones equals base_module_aspect.applicable_zones',
+    (_id, provider) => {
+      const capability = provider.manifest.provides?.capabilities?.find(
+        (c) => c.name === 'dns_internal',
+      );
+      const declared = capability?.data?.aspect?.covered_zones;
+      const applicable = provider.manifest.base_module_aspect?.applicable_zones;
+
+      expect(declared, 'dns_internal.data.aspect.covered_zones is missing').toBeDefined();
+      expect(applicable, 'base_module_aspect.applicable_zones is missing').toBeDefined();
+      expect([...(declared ?? [])].sort()).toEqual([...(applicable ?? [])].sort());
+    },
+  );
+
+  test('no provider claims to cover `external`', () => {
+    // An `external` system is a cloud VPS outside the perimeter with no route
+    // to a dmz-resident resolver. Its public resolvers are the only working
+    // configuration, not a fallback that might mask a split-horizon error, so
+    // claiming coverage there would strip the only addresses it can reach.
+    for (const provider of providers) {
+      const declared =
+        provider.manifest.provides?.capabilities?.find((c) => c.name === 'dns_internal')?.data
+          ?.aspect?.covered_zones ?? [];
+      expect(declared, `${provider.id} claims to cover external`).not.toContain('external');
+    }
+  });
+});

package/src/policy/module-business-baseline.ts

@@ -33,21 +33,28 @@
  *     never go away.
  */
 
+import { allDeclaredTables } from '@celilo/capabilities';
+
 /**
  * Tables tagged `@owner capability:*` in `db/schema.ts`, and the capability
  * each belongs to. Scan A asserts the tagged set EQUALS this map — not that it
- * is empty. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
+ * is empty.
+ *
+ * DERIVED from the capability declarations, not hand-written
+ * (openspec/changes/capability-owned-tables task 2.7). It used to be a literal,
+ * which made `@owner capability:public_web` a comment checked against another
+ * comment. Now the tag is checked against the thing that actually governs the
+ * table, so a declared table that nobody tagged and a tagged table nobody
+ * declared BOTH fail, and the map cannot drift from the declarations because it
+ * no longer exists apart from them. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
  * nothing; an assertion that core holds none would be red the day it landed.
  *
  * Tracked by #939. Migrating them keeps the ownership CLAIM in core — dropping
  * it is the mistake that made `dns_registration_consumers` necessary (#626).
  */
-export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = {
-  web_routes: 'public_web',
-  port_forwards: 'firewall',
-  trusted_sources: 'firewall',
-  dns_internal_records: 'dns_internal',
-};
+export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = Object.fromEntries(
+  allDeclaredTables().map(({ capability, declaration }) => [declaration.table, capability]),
+);
 
 /** One `{file, capability}` pair and how many times core names it. */
 export interface CapabilityNameRow {
@@ -266,6 +273,24 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model) (#945)',
   },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'dns_internal',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'firewall',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'public_web',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'control_plane_vpn',