@celilo/cli 1.7.0 → 1.9.0

package/src/hooks/hook-timeout.test.ts

@@ -0,0 +1,103 @@
+/**
+ * celilo#1003: a hook that times out must be KILLED, not abandoned.
+ *
+ * `module-lifecycle`'s spec has always required this:
+ *
+ * > WHEN a hook produces no output for longer than the idle timeout
+ * > THEN celilo SHALL terminate it rather than hang indefinitely
+ *
+ * The old executor raced the hook's promise against a timer and cancelled
+ * nothing, because a promise cannot be cancelled. The existing suite asserted
+ * the rejection, which held, and the requirement did not.
+ *
+ * So these tests assert the harm rather than the rejection: a marker file the
+ * hook writes only after its bound has passed. Both of them fail against the
+ * in-process executor and neither says anything about how the kill is
+ * implemented.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { executeHookScript } from './executor';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const FIXTURES = join(__dirname, 'test-fixtures');
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function scratch(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-timeout-'));
+  dirs.push(dir);
+  return dir;
+}
+
+function contextFor(config: Record<string, unknown>): HookContext {
+  return {
+    config,
+    secrets: {},
+    systems: [],
+    logger: createCapturingLogger().logger,
+    debug: false,
+    screenshotDir: scratch(),
+    capabilities: {},
+  };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Hook processes still parented to this one. By ppid rather than by script
+ * name: matching the name picks up whatever shell has the filename in its own
+ * command line, which is a false positive that looks exactly like a real leak.
+ */
+function survivingHookProcesses(): string[] {
+  return execSync('ps -Ao ppid=,args=', { encoding: 'utf-8' })
+    .split('\n')
+    .filter(
+      (line) => Number.parseInt(line.trim(), 10) === process.pid && line.includes('hook-runner'),
+    );
+}
+
+describe('hook timeout is a kill, not a race', () => {
+  test('a hook that outruns its total timeout stops doing work', async () => {
+    const marker = join(scratch(), 'kept-running');
+
+    await expect(
+      executeHookScript(
+        join(FIXTURES, 'runaway-hook.ts'),
+        contextFor({ sleep_ms: 1500, marker_path: marker }),
+        400,
+        400,
+      ),
+    ).rejects.toThrow(/timeout/i);
+
+    // Past when the abandoned hook would have written it.
+    await sleep(2000);
+    expect(existsSync(marker)).toBe(false);
+    expect(survivingHookProcesses()).toEqual([]);
+  }, 15_000);
+
+  test('a hook that declines SIGTERM is killed anyway', async () => {
+    const marker = join(scratch(), 'survived');
+
+    await expect(
+      executeHookScript(
+        join(FIXTURES, 'sigterm-ignoring-hook.ts'),
+        contextFor({ sleep_ms: 6000, marker_path: marker }),
+        400,
+        400,
+      ),
+    ).rejects.toThrow(/timeout/i);
+
+    await sleep(6500);
+    expect(existsSync(marker)).toBe(false);
+    expect(survivingHookProcesses()).toEqual([]);
+  }, 20_000);
+});

package/src/hooks/hook-trespass.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The recurrence gate for openspec/changes/hook-process-boundary (celilo#1001).
+ *
+ * Runs `modules/hello-trespass`'s hook through `executeHookScript` and asserts
+ * exactly what the stage that has landed claims, and nothing more.
+ *
+ * **Stage 1 claims the environment. It does not claim the filesystem and it
+ * does not claim the network.** So this file asserts the sensitive environment
+ * is empty, and asserts the other three trespasses STILL SUCCEED. A gate that
+ * claimed more than its stage delivers would go green for the wrong reason and
+ * would have to be rewritten — quietly weakening it — the first time somebody
+ * noticed. Stage 2 flips the two filesystem rows and stage 3 flips the SSH row;
+ * each stage edits the assertion it earns.
+ *
+ * `HOME` is redirected to a scratch directory holding a planted master key and
+ * a planted SSH key, so the trespasses are deterministic and the operator's
+ * real key is never read (CLAUDE.md: never test against live data). `HOME` is
+ * on design D5's allow-list, so the child resolves the same planted paths the
+ * parent planted — which is the point of D5's own caveat: removing
+ * `CELILO_DATA_DIR` does not hide a path a hook can compute.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { executeHookScript, hookChildEnv } from './executor';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const TRESPASS_SCRIPT = resolve(
+  __dirname,
+  '../../../../modules/hello-trespass/scripts/trespass.ts',
+);
+
+interface TrespassOutcome {
+  attempted: boolean;
+  succeeded: boolean;
+  target: string;
+  detail: string;
+}
+
+interface TrespassReport {
+  master_key: TrespassOutcome;
+  sibling_write: TrespassOutcome;
+  ssh_key: TrespassOutcome;
+  remote_exec: TrespassOutcome;
+  sensitive_env: string[];
+}
+
+let scratchHome: string;
+let realHome: string | undefined;
+
+/**
+ * Install the fixture module's own dependencies if they are not there.
+ *
+ * A `modules/<id>/scripts` directory is a standalone package, deliberately
+ * outside the root workspace globs so that a module resolves the PUBLISHED
+ * `@celilo/capabilities` it will actually run on the fleet rather than the
+ * workspace copy. bun links workspace dependencies into each package's own
+ * `node_modules` and never into the repo root, so there is nothing here for
+ * the fixture to walk up to: with no install of its own the hook dies with
+ * `Cannot find module '@celilo/capabilities'`.
+ *
+ * `bun run setup` does this for every module, and CI does it in its
+ * check-modules step — which runs LAST on purpose, because twenty-two installs
+ * is the slowest thing in that job. This gate is the first test to reach into
+ * a module's script tree, so it prepares the one fixture it needs instead of
+ * making every PR pay for all of them up front.
+ *
+ * It installs rather than skipping. A gate that quietly does not run is the
+ * exact failure this whole change exists to make impossible.
+ */
+function ensureFixtureInstalled(): void {
+  const scriptsDir = dirname(TRESPASS_SCRIPT);
+  if (existsSync(join(scriptsDir, 'node_modules', '@celilo', 'capabilities'))) return;
+  // `process.execPath`, not `bun` on PATH: this is the bun already running the
+  // suite, so it works wherever the suite does.
+  execFileSync(process.execPath, ['install'], { cwd: scriptsDir, stdio: 'pipe' });
+}
+
+beforeAll(() => {
+  ensureFixtureInstalled();
+  scratchHome = mkdtempSync(join(tmpdir(), 'celilo-trespass-home-'));
+
+  // The master key at getMasterKeyPath()'s DEFAULT location for this platform.
+  // Both branches are planted rather than the current one only, so the fixture
+  // reads a planted key whichever host runs the suite.
+  for (const dir of [
+    join(scratchHome, 'Library', 'Application Support', 'celilo'),
+    join(scratchHome, '.local', 'share', 'celilo'),
+  ]) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'master.key'), 'not-the-real-key\n');
+  }
+
+  mkdirSync(join(scratchHome, '.ssh'), { recursive: true });
+  writeFileSync(join(scratchHome, '.ssh', 'id_ed25519'), 'not-a-real-key\n');
+
+  realHome = process.env.HOME;
+  process.env.HOME = scratchHome;
+});
+
+afterAll(() => {
+  if (realHome === undefined) delete process.env.HOME;
+  else process.env.HOME = realHome;
+  rmSync(scratchHome, { recursive: true, force: true });
+});
+
+async function runTrespass(): Promise<{ report: TrespassReport; lines: string[] }> {
+  const { logger, messages } = createCapturingLogger();
+  const context: HookContext = {
+    config: { sibling_module_id: 'hello-foo', other_system_ip: '' },
+    secrets: {},
+    systems: [],
+    logger,
+    debug: false,
+    screenshotDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    capabilities: {},
+  };
+
+  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, 60_000, 60_000);
+  return {
+    report: outputs as unknown as TrespassReport,
+    lines: messages.map((m) => m.message),
+  };
+}
+
+describe('the child environment is an allow-list', () => {
+  // The trespass gate below proves nothing sensitive gets through. This is the
+  // complement: the six things that MUST get through, because a hook with no
+  // `PATH` cannot spawn anything and one with no `HOME` breaks more than it
+  // protects.
+  test('forwards the allow-list and the channel, and nothing else', () => {
+    process.env.CELILO_TEST_SECRET = 'must-not-cross';
+    try {
+      const env = hookChildEnv('/tmp/celilo-hook-x/s');
+
+      expect(env.CELILO_HOOK_SOCKET).toBe('/tmp/celilo-hook-x/s');
+      expect(env.CELILO_HOOK_PROTOCOL_VERSION).toBe('1');
+      expect(env.PATH).toBe(process.env.PATH as string);
+      expect(env.HOME).toBe(process.env.HOME as string);
+      expect(env.CELILO_TEST_SECRET).toBeUndefined();
+
+      const allowed = new Set([
+        'PATH',
+        'HOME',
+        'LANG',
+        'TZ',
+        'TMPDIR',
+        'CELILO_DEBUG',
+        'CELILO_HOOK_SOCKET',
+        'CELILO_HOOK_PROTOCOL_VERSION',
+      ]);
+      expect(Object.keys(env).filter((name) => !allowed.has(name))).toEqual([]);
+    } finally {
+      delete process.env.CELILO_TEST_SECRET;
+    }
+  });
+
+  test('omits an allow-listed variable the parent does not have', () => {
+    const saved = process.env.TZ;
+    delete process.env.TZ;
+    try {
+      // Absent, not the string "undefined" — which is what a naive copy
+      // produces and what a shell then happily uses as a timezone.
+      expect('TZ' in hookChildEnv('/tmp/s')).toBe(false);
+    } finally {
+      if (saved !== undefined) process.env.TZ = saved;
+    }
+  });
+});
+
+describe('hook process boundary — hello-trespass gate', () => {
+  test('stage 1: the environment is clean, and nothing else has changed', async () => {
+    const { report, lines } = await runTrespass();
+
+    // The evidence, printed whether the assertions pass or fail. Without it a
+    // red run says which assertion broke and not what the hook actually saw.
+    console.log(['', 'hello-trespass:', ...lines.slice(1)].join('\n'));
+
+    // What stage 1 claims. Empty because the child's environment is an
+    // allow-list, not `...process.env` (design D5).
+    expect(report.sensitive_env).toEqual([]);
+
+    // What stage 1 deliberately does NOT claim. The master key is still
+    // readable, because the hook computes the default path rather than
+    // reading it out of the environment. Stage 2's mount set is what removes
+    // it, by not binding the data directory at all.
+    expect(report.master_key.succeeded).toBe(true);
+
+    // Nor the sibling's tree: the module store is still one `..` away.
+    expect(report.sibling_write.succeeded).toBe(true);
+
+    // Nor the SSH key, which is what scopes reachability in stage 3 (D12).
+    // `attempted: false` means the host has no private key at all — a bare CI
+    // runner — which is an absent precondition, not a refusal.
+    expect(report.ssh_key.attempted && !report.ssh_key.succeeded).toBe(false);
+  });
+});

package/src/hooks/injected-capabilities.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Every name the loader can put in `ctx.capabilities` must be a registered
+ * capability.
+ *
+ * This is the gate for the class of bug, not for its instances. Twice now a
+ * capability has been injected under a literal name that appeared in no
+ * registry and, in one case, had no declared type anywhere:
+ *
+ *   - `web_routes`, whose two methods were synchronous. The hook process
+ *     boundary's D2 measured the hook-facing surface as uniformly async by
+ *     reading `CapabilityRegistry`, so it never saw them. caddy's `on_install`
+ *     died on `{} is not iterable` when the async proxy handed it a Promise.
+ *   - `firewall_registry`, which had no `FirewallRegistryCapability` type, no
+ *     registry entry, and no contract version. It happens to be async, so it
+ *     broke nothing, which is exactly why nobody found it.
+ *
+ * `type-invariants.test.ts` proves every REGISTERED capability's methods are
+ * async. That proof is only worth as much as the registry's completeness, and
+ * completeness is what this file checks. Together they close the loop: the
+ * registry names everything injected, and everything named is async.
+ *
+ * It reads the loader's source because the property is about what the code can
+ * assign, not about what one run happens to produce. A runtime test would need
+ * every provider deployed in every combination to see all the branches.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+
+const LOADER = join(__dirname, 'capability-loader.ts');
+
+/**
+ * Literal names assigned into the capability map, e.g. `result.web_routes =`.
+ *
+ * Computed assignments (`result[capName] =`) are deliberately not matched:
+ * `capName` is already a registry name, since it comes from the capability
+ * table keyed by the same list.
+ */
+function injectedCapabilityNames(source: string): string[] {
+  const names = new Set<string>();
+  for (const match of source.matchAll(/^\s*result\.([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)) {
+    names.add(match[1]);
+  }
+  return [...names].sort();
+}
+
+describe('capabilities injected into the hook context', () => {
+  test('every literally-named injection is a registered capability', () => {
+    const injected = injectedCapabilityNames(readFileSync(LOADER, 'utf-8'));
+
+    // If this is empty the regex has drifted and the gate is checking nothing,
+    // which is the failure mode that makes a green test worse than no test.
+    expect(injected.length).toBeGreaterThan(0);
+
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injected.filter((name) => !known.includes(name));
+
+    expect(unregistered).toEqual([]);
+  });
+
+  test('PROVE IT FAILS: an unregistered name is caught', () => {
+    const withNewInjection = `
+      result.public_web = createPublicWeb({});
+      result.brand_new_view = somethingUndeclared;
+    `;
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injectedCapabilityNames(withNewInjection).filter(
+      (name) => !known.includes(name),
+    );
+
+    expect(unregistered).toEqual(['brand_new_view']);
+  });
+});

package/src/hooks/test-fixtures/capability-calling-hook.ts

@@ -0,0 +1,79 @@
+/**
+ * Test fixture: a hook that exercises every shape a capability call can take
+ * across the process boundary.
+ *
+ * One test per SHAPE rather than per method: the broker is generic, so a
+ * per-method suite would prove the same thing thirty-seven times and drift the
+ * moment a capability gained a method.
+ */
+
+import { defineHook, isMissingProviderInputError } from '@celilo/capabilities';
+
+interface DemoCapability {
+  providerModuleId?: string;
+  version?: string;
+  echo(request: Record<string, unknown>): Promise<unknown>;
+  boom(request: Record<string, unknown>): Promise<unknown>;
+  missingInput(request: Record<string, unknown>): Promise<unknown>;
+  returnsNothing(request: Record<string, unknown>): Promise<unknown>;
+  /** Never implemented by this provider — the absent-optional-method case. */
+  sometimesAbsent?(request: Record<string, unknown>): Promise<unknown>;
+}
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    // `demo` is a fixture capability, not a registry entry, so the typed
+    // capability map does not know it. The broker is generic and does not care.
+    const demo = (ctx.capabilities as unknown as Record<string, DemoCapability>).demo;
+    const outputs: Record<string, unknown> = {};
+
+    // Non-function properties are copied verbatim, which is what keeps
+    // `providerModuleId` readable — a hook names the provider in its errors.
+    outputs.providerModuleId = demo.providerModuleId;
+    outputs.version = demo.version;
+
+    // An optional method the provider did not implement must be ABSENT, not a
+    // proxy that throws, or `if (cap.registerTrustedSource)` answers wrongly.
+    outputs.optionalMethodAbsent = demo.sometimesAbsent === undefined;
+
+    outputs.returned = await demo.echo({ x: 1, nested: { y: [2, 3] } });
+    outputs.undefinedBecomesNull = await demo.returnsNothing({});
+
+    try {
+      await demo.boom({});
+      outputs.plainThrow = 'did not throw';
+    } catch (error) {
+      outputs.plainThrow = {
+        isError: error instanceof Error,
+        name: (error as Error).name,
+        message: (error as Error).message,
+        hasStack: typeof (error as Error).stack === 'string',
+      };
+    }
+
+    try {
+      await demo.missingInput({});
+      outputs.missingProviderInput = 'did not throw';
+    } catch (error) {
+      const e = error as Record<string, unknown>;
+      outputs.missingProviderInput = {
+        recognised: isMissingProviderInputError(error),
+        providerModuleId: e.providerModuleId,
+        ensureId: e.ensureId,
+        value: e.value,
+        humanContext: e.humanContext,
+      };
+    }
+
+    try {
+      await (demo as unknown as { nope(): Promise<unknown> }).nope();
+      outputs.unknownMethod = 'did not throw';
+    } catch (error) {
+      outputs.unknownMethod = (error as Error).message;
+    }
+
+    return outputs;
+  },
+});

package/src/hooks/test-fixtures/runaway-hook.ts

@@ -0,0 +1,26 @@
+/**
+ * Test fixture: a hook that outruns its total timeout and then writes a file.
+ *
+ * The marker is the harm, not the mechanism. `Promise.race` in the old
+ * executor rejected at the bound and cancelled nothing, so the hook kept its
+ * capability objects and went on doing work — registering DNS, opening ports —
+ * minutes after celilo reported the deploy failed. A test that only asserts
+ * the rejection cannot see that; it passed throughout (celilo#1003).
+ *
+ * The marker is written AFTER the sleep, so its existence after the bound is
+ * proof the hook was abandoned rather than killed.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    ctx.logger.info('runaway hook starting');
+    await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 2000)));
+    writeFileSync(String(ctx.config.marker_path), 'the hook kept running\n');
+    return {};
+  },
+});

package/src/hooks/test-fixtures/sigterm-ignoring-hook.ts

@@ -0,0 +1,22 @@
+/**
+ * Test fixture: a hook that traps SIGTERM and keeps going.
+ *
+ * SIGTERM is a request. This is the case that makes the grace period load
+ * bearing: without the SIGKILL that follows it, a hook can decline to die and
+ * the boundary buys nothing over the promise race it replaced.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    process.on('SIGTERM', () => ctx.logger.info('declining to die'));
+    ctx.logger.info('sigterm-ignoring hook starting');
+    await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 20_000)));
+    writeFileSync(String(ctx.config.marker_path), 'survived SIGTERM\n');
+    return {};
+  },
+});

package/src/manifest/template-validator.test.ts

@@ -258,4 +258,51 @@ resource "local_file" "test" {
       expect(errors[0]?.variable).toBe('$self:invalid_var');
     });
   });
+
+  /**
+   * The capability-secret gate at import consumes these, so what happens when
+   * templates cannot be read is a security property rather than a detail. It
+   * has to FAIL CLOSED: an unreadable tree must abort the import, never hand
+   * the gate an empty reference set that reads as "this module references no
+   * secrets". It was already true here — but true by inspection, which is the
+   * weakest way for a security property to be true.
+   */
+  describe('capability references, and failing closed', () => {
+    test('collects $capability: references from templates', async () => {
+      const dir = await mkdtemp(join(tmpdir(), 'celilo-tplrefs-'));
+      try {
+        await mkdir(join(dir, 'terraform'), { recursive: true });
+        await writeFile(
+          join(dir, 'terraform', 'main.tf.tpl'),
+          'acme_dns = "$capability:dns_internal.tsig_key"\nzone = "$capability:dns_internal.dns.domain"\n',
+        );
+        const manifest = createTestManifest({
+          requires: { capabilities: [{ name: 'dns_internal', version: '1.0.0' }] },
+        });
+
+        const result = await validateModuleTemplates(dir, manifest);
+
+        expect(result.capabilityReferences.sort()).toEqual([
+          'dns_internal.dns.domain',
+          'dns_internal.tsig_key',
+        ]);
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    });
+
+    test('an unreadable module tree fails, and yields no references', async () => {
+      // A path that does not exist stands in for any read failure. The PAIRING
+      // is the property: success:false travels WITH the empty array, and
+      // `import.ts` returns on !success before the access gate runs, so the
+      // empty set can never be mistaken for "nothing referenced".
+      const result = await validateModuleTemplates(
+        join(tmpdir(), 'celilo-no-such-module-tree-9f3a2b'),
+        createTestManifest(),
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.capabilityReferences).toEqual([]);
+    });
+  });
 });

package/src/manifest/template-validator.ts

@@ -19,6 +19,12 @@ export interface TemplateValidationError {
 export interface TemplateValidationResult {
   success: boolean;
   errors: TemplateValidationError[];
+  /**
+   * `<capability>.<path>` paths the templates reference. The capability-access
+   * check at import consumes these, so a secret referenced only from a template
+   * is refused at import rather than later at generation.
+   */
+  capabilityReferences: string[];
 }
 
 /**
@@ -277,10 +283,16 @@ export async function validateModuleTemplates(
     // Find all .tpl files
     const templateFiles = await findTemplateFiles(modulePath, modulePath);
 
-    // Validate each template file
+    // Validate each template file. Every one is parsed here anyway, so the
+    // capability references fall out of work already being done — no second
+    // walk of the module tree.
+    const capabilityReferences = new Set<string>();
     for (const relativePath of templateFiles) {
       const fullPath = join(modulePath, relativePath);
       const content = await readFile(fullPath, 'utf-8');
+      for (const variable of parseVariables(content)) {
+        if (variable.type === 'capability') capabilityReferences.add(variable.path);
+      }
       const errors = validateTemplateContent(content, manifest, relativePath);
       allErrors.push(...errors);
     }
@@ -288,6 +300,7 @@ export async function validateModuleTemplates(
     return {
       success: allErrors.length === 0,
       errors: allErrors,
+      capabilityReferences: [...capabilityReferences],
     };
   } catch (error) {
     return {
@@ -299,6 +312,10 @@ export async function validateModuleTemplates(
           error: `Failed to validate templates: ${error instanceof Error ? error.message : 'Unknown error'}`,
         },
       ],
+      // Unreadable templates cannot yield references, and import returns on
+      // !success before the access check runs, so this can never reach it as a
+      // silent pass.
+      capabilityReferences: [],
     };
   }
 }

package/src/manifest/validate-provider-views.test.ts

@@ -0,0 +1,61 @@
+/**
+ * A module may not declare a provider view.
+ *
+ * `web_routes` and `firewall_registry` are in `KNOWN_CAPABILITY_NAMES`, so the
+ * name check that asks only "is this known?" accepts them. celilo injects both
+ * into the hooks of the module that PROVIDES the paired capability and never
+ * to a consumer, so a module requiring one would validate, publish, deploy, and
+ * then find the capability simply absent at hook time — with a pre-flight error
+ * naming a missing provider that was never going to exist.
+ *
+ * Registering the two names (celilo#1007) is what created this opening. They
+ * were invisible to every check before that, which was its own, worse problem.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { PROVIDER_VIEW_CAPABILITIES } from '@celilo/capabilities';
+import type { ModuleManifest } from './schema';
+import { validateCapabilityNames } from './validate';
+
+function manifestRequiring(name: string): ModuleManifest {
+  return {
+    requires: { capabilities: [{ name, version: '1.0.0' }] },
+  } as unknown as ModuleManifest;
+}
+
+function manifestOptionally(name: string): ModuleManifest {
+  return {
+    requires: { capabilities: [] },
+    optional: { capabilities: [{ name, version: '1.0.0' }] },
+  } as unknown as ModuleManifest;
+}
+
+describe('provider views are not declarable', () => {
+  for (const view of PROVIDER_VIEW_CAPABILITIES) {
+    test(`requires.capabilities rejects '${view}'`, () => {
+      const result = validateCapabilityNames(manifestRequiring(view));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0].message).toContain('provider view');
+    });
+
+    test(`optional.capabilities rejects '${view}' too`, () => {
+      // The optional path is checked for the same reason the privileged-
+      // capability check covers it: otherwise the declaration is smuggled in
+      // through the soft-require door.
+      const result = validateCapabilityNames(manifestOptionally(view));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0].message).toContain('provider view');
+    });
+
+    test(`'${view}' is not offered in the suggestion list`, () => {
+      // The message for a genuine typo lists what an author CAN require, so a
+      // view must not appear there either.
+      const result = validateCapabilityNames(manifestRequiring('definitely_not_a_capability'));
+      expect(result?.errors[0].message).not.toContain(view);
+    });
+  }
+
+  test('a real capability still validates', () => {
+    expect(validateCapabilityNames(manifestRequiring('public_web'))).toBeNull();
+  });
+});