@celilo/cli 0.11.0 → 0.12.1

package/src/capabilities/public-web-publish.test.ts

@@ -489,3 +489,212 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
     }
   });
 });
+
+describe('register_route — public DNS wiring (D1/M1 #328)', () => {
+  beforeEach(() => {
+    execSyncSpy = spyOn(childProcess, 'execSync').mockReturnValue(Buffer.from(''));
+  });
+  afterEach(() => {
+    execSyncSpy.mockRestore();
+  });
+
+  function makeRegistrar(): {
+    registrar: {
+      registerHost: (r: { fqdn: string; ip?: string }) => Promise<{ success: boolean }>;
+    };
+    calls: Array<{ fqdn: string; ip?: string }>;
+  } {
+    const calls: Array<{ fqdn: string; ip?: string }> = [];
+    return {
+      calls,
+      registrar: {
+        async registerHost(r) {
+          calls.push(r);
+          return { success: true };
+        },
+      },
+    };
+  }
+
+  test('registers the public A record at externalIp for a NEW hostname', async () => {
+    const { ops } = makeRouteOps();
+    const { registrar, calls } = makeRegistrar();
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      externalIp: '100.100.0.100',
+    });
+
+    await cap.register_route({
+      type: 'static',
+      path: '/',
+      hostname: 'nexus.example.com',
+    });
+
+    expect(calls).toEqual([{ fqdn: 'nexus.example.com', ip: '100.100.0.100' }]);
+  });
+
+  test('skips the default hostname (caddy already registered it at install)', async () => {
+    const { ops } = makeRouteOps();
+    const { registrar, calls } = makeRegistrar();
+    const cap = createPublicWeb({
+      moduleId: 'root',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      externalIp: '100.100.0.100',
+    });
+
+    await cap.register_route({ type: 'static', path: '/', hostname: 'www.example.com' });
+
+    expect(calls).toHaveLength(0);
+  });
+
+  // D2 / ce-phz — reachability wiring is authoritative and LOUD: a new
+  // hostname that can't be wired FAILS the deploy instead of silently
+  // reporting success (the "served but unreachable" anti-pattern).
+
+  test('fails loudly when externalIp is unknown for a NEW hostname', async () => {
+    const { ops } = makeRouteOps();
+    const { registrar, calls } = makeRegistrar();
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      // externalIp omitted
+    });
+
+    await expect(
+      cap.register_route({ type: 'static', path: '/', hostname: 'nexus.example.com' }),
+    ).rejects.toThrow('no known external IP');
+    expect(calls).toHaveLength(0);
+  });
+
+  test('fails loudly when no dns_registrar is available for a NEW hostname', async () => {
+    const { ops } = makeRouteOps();
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // dnsRegistrar + externalIp both omitted
+      externalIp: '100.100.0.100',
+    });
+
+    await expect(
+      cap.register_route({ type: 'static', path: '/', hostname: 'nexus.example.com' }),
+    ).rejects.toThrow('no dns_registrar capability');
+  });
+
+  test('fails loudly when the registrar reports the public registration failed', async () => {
+    const { ops } = makeRouteOps();
+    const registrar = {
+      async registerHost() {
+        return { success: false, error: 'DDNS auth rejected' };
+      },
+    };
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      externalIp: '100.100.0.100',
+    });
+
+    await expect(
+      cap.register_route({ type: 'static', path: '/', hostname: 'nexus.example.com' }),
+    ).rejects.toThrow('DDNS auth rejected');
+  });
+
+  test('fails loudly when an internal resolver is present but has no target IP', async () => {
+    const { ops } = makeRouteOps();
+    const { registrar } = makeRegistrar();
+    const dnsInternal = {
+      async registerRecord() {},
+      async deleteRecord() {},
+    };
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      // No target_ip and no firewallNatIp → internalDnsIp is falsy.
+      config: {},
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      externalIp: '100.100.0.100',
+      // biome-ignore lint/suspicious/noExplicitAny: minimal dns_internal stub
+      dnsInternal: dnsInternal as any,
+    });
+
+    await expect(
+      cap.register_route({ type: 'static', path: '/', hostname: 'nexus.example.com' }),
+    ).rejects.toThrow('no internal DNS target IP');
+  });
+
+  test('wires internal DNS when a resolver is present and reachable', async () => {
+    const { ops } = makeRouteOps();
+    const { registrar } = makeRegistrar();
+    const internalCalls: Array<{ host: string; value: string }> = [];
+    const dnsInternal = {
+      async registerRecord(r: { host: string; value: string }) {
+        internalCalls.push({ host: r.host, value: r.value });
+      },
+      async deleteRecord() {},
+    };
+    const cap = createPublicWeb({
+      moduleId: 'nexus',
+      logger: noopLogger,
+      config: { target_ip: '10.0.10.20/24' },
+      secrets: {},
+      routeOps: ops,
+      hostnames: ['www.example.com'],
+      caddyModuleId: 'caddy',
+      dnsManagedDomains: ['example.com'],
+      // biome-ignore lint/suspicious/noExplicitAny: minimal registrar stub
+      dnsRegistrar: registrar as any,
+      externalIp: '100.100.0.100',
+      firewallNatIp: '192.168.0.253',
+      // biome-ignore lint/suspicious/noExplicitAny: minimal dns_internal stub
+      dnsInternal: dnsInternal as any,
+    });
+
+    await cap.register_route({ type: 'static', path: '/', hostname: 'nexus.example.com' });
+
+    expect(internalCalls).toEqual([{ host: 'nexus.example.com', value: '192.168.0.253' }]);
+  });
+});

package/src/capabilities/validation.test.ts

@@ -245,7 +245,7 @@ describe('Capability Access Validation', () => {
       // cross_module_read is a privilege (allow-listed to celilo-mgmt),
       // not a provider-backed capability. validateCapabilityAccess must
       // not demand a providing module for it — otherwise celilo-mgmt
-      // can't be imported (regression: v2/NETWORK_CONFIG_TO_FIREWALL.md).
+      // can't be imported (regression: openspec/specs/progressive-zone-disclosure/spec.md).
       const manifest: ModuleManifest = {
         celilo_contract: '1.0',
         id: 'celilo-mgmt',

package/src/capabilities/well-known.test.ts

@@ -177,7 +177,7 @@ describe('Well-Known Capabilities Registry', () => {
 
     test('the internal DNS resolver lives in the dmz (ISS-0156)', () => {
       // Moved out of `internal`: the resolver must see protected-zone query
-      // sources for source-based split-horizon views (v2/INTERNAL_DNS_ZONE_VIEWS.md).
+      // sources for source-based split-horizon views (openspec/specs/internal-dns-zone-views/spec.md).
       expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('dmz');
     });
   });

package/src/capabilities/well-known.ts

@@ -76,7 +76,7 @@ export const WELL_KNOWN_CAPABILITIES: Record<string, WellKnownCapability> = {
    * dns_internal - Internal DNS resolver
    * Example: Technitium / knot-unbound for split-horizon DNS
    * Security: a PROTECTED zone (dmz), NOT `internal` (ISS-0156,
-   * v2/INTERNAL_DNS_ZONE_VIEWS.md). The resolver must see each querying client's
+   * openspec/specs/internal-dns-zone-views/spec.md). The resolver must see each querying client's
    * real source IP to serve source-based split-horizon views; fw-main NATs
    * protected↔`internal`, so an `internal`-placed resolver sees every protected
    * query as fw-main's address and can't tell the zones apart. Placed in `dmz`
@@ -105,7 +105,7 @@ export const WELL_KNOWN_CAPABILITIES: Record<string, WellKnownCapability> = {
    * Security: MUST be in secure zone (handles authentication)
    *
    * Note: `oidc.issuer_url` is no longer derived here. Per the firm rule in
-   * design/TECHNICAL_DESIGN_MANIFEST_V2.md D9, well-known capability data
+   * openspec/changes/manifest-v2/proposal.md D9, well-known capability data
    * templates must not cross-reference other capabilities. The IDP-providing
    * module declares an explicit user-set `domain` field in its own manifest,
    * derives `auth_url` from `$self:domain`, and exposes it through

package/src/cli/command-tree-parser.ts

@@ -177,7 +177,9 @@ export class CommandTreeParser {
       'usage',
       'options',
       'examples',
-      'commands',
+      // NB: 'commands' is intentionally NOT excluded — it's a real command
+      // (`celilo commands`). The "Commands:" section header is filtered earlier
+      // by the section-header regex, so it never reaches this check.
       'description',
       'example',
       'for',

package/src/cli/commands/api.ts

@@ -2,7 +2,7 @@
  * `celilo api ...` — manage remote-API principals (Slice 2a).
  *
  * grant / list / revoke operate on the api_principals table; authorized-keys
- * renders the forced-command file for the API account. See v2/API_COMMUNICATION.md.
+ * renders the forced-command file for the API account. See openspec/changes/replace-ssh-cli-api/proposal.md.
  */
 
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';

package/src/cli/commands/apt-upgrade.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test';
+import { handleAptUpgrade } from './apt-upgrade';
+
+describe('handleAptUpgrade', () => {
+  test('runs the three steps in order when each succeeds', async () => {
+    const seen: string[][] = [];
+    const result = await handleAptUpgrade([], {}, (argv) => {
+      seen.push(argv);
+      return { status: 0 };
+    });
+
+    expect(result.success).toBe(true);
+    expect(seen).toEqual([
+      ['sudo', 'apt-get', 'update'],
+      ['sudo', 'apt-get', '-y', '--only-upgrade', 'install', 'celilo', 'celilo-bootstrap'],
+      ['/usr/local/bin/celilo', 'system', 'migrate'],
+    ]);
+  });
+
+  test('stops at the first failing step and does not run later ones', async () => {
+    const seen: string[][] = [];
+    const result = await handleAptUpgrade([], {}, (argv) => {
+      seen.push(argv);
+      // Fail the apt upgrade step (index 1).
+      return { status: argv.includes('install') ? 100 : 0 };
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.error).toContain('apt-get upgrade');
+    // update + install ran; migrate did NOT.
+    expect(seen).toHaveLength(2);
+  });
+});

package/src/cli/commands/apt-upgrade.ts

@@ -0,0 +1,63 @@
+/**
+ * `celilo apt-upgrade` — upgrade the deb-installed celilo packages and apply
+ * pending DB migrations. The management server (celilo-bootstrap) installs
+ * celilo via apt, so keeping it current means the apt chain, not `bun update -g`
+ * (that path is `system update`'s self-update, for npm-global installs).
+ *
+ * Steps (ISS-0100 — the postinst does NOT auto-apply migrations):
+ *   1. apt-get update
+ *   2. apt-get -y --only-upgrade install celilo celilo-bootstrap
+ *   3. a FRESH `celilo system migrate` — spawned as the just-installed binary so
+ *      the new version's migrations run, not the ones loaded in this process.
+ *
+ * This is the RW target behind the MCP's `celilo_apt_upgrade` tool. It runs as
+ * the celilo user (via api-serve); the apt steps sudo to root, gated by the
+ * scoped /etc/sudoers.d/celilo-apt-upgrade grant that celilo-bootstrap ships.
+ */
+
+import { spawnSync } from 'node:child_process';
+import type { CommandResult } from '../types';
+
+/** Wrapper the deb installs; the fresh migrate step runs the upgraded binary. */
+const CELILO_BIN = '/usr/local/bin/celilo';
+
+/** One command to run in the chain — argv plus a human label for output. */
+interface Step {
+  label: string;
+  argv: string[];
+}
+
+const STEPS: Step[] = [
+  { label: 'apt-get update', argv: ['sudo', 'apt-get', 'update'] },
+  {
+    label: 'apt-get upgrade celilo, celilo-bootstrap',
+    argv: ['sudo', 'apt-get', '-y', '--only-upgrade', 'install', 'celilo', 'celilo-bootstrap'],
+  },
+  { label: 'apply DB migrations', argv: [CELILO_BIN, 'system', 'migrate'] },
+];
+
+/** Run one argv, inheriting stdio so its output streams through api-serve. */
+export type StepRunner = (argv: string[]) => { status: number | null };
+
+const defaultRunner: StepRunner = (argv) => spawnSync(argv[0], argv.slice(1), { stdio: 'inherit' });
+
+export async function handleAptUpgrade(
+  _args: string[],
+  _flags: Record<string, string | boolean>,
+  runStep: StepRunner = defaultRunner,
+): Promise<CommandResult> {
+  for (const step of STEPS) {
+    process.stdout.write(`\n▸ ${step.label}\n`);
+    const { status } = runStep(step.argv);
+    if (status !== 0) {
+      return {
+        success: false,
+        error: `apt-upgrade failed at "${step.label}" (exit ${status ?? 'signal'}). Nothing further was run.`,
+      };
+    }
+  }
+  return {
+    success: true,
+    message: 'celilo apt packages upgraded and migrations applied.',
+  };
+}

package/src/cli/commands/backup-pull.ts

@@ -15,7 +15,7 @@
  *   celilo backup pull --storage <id> --module celilo-mgmt
  *   celilo restore --from <printed-path> --force
  *
- * Part of P5 (v2/CELILO_MGMT_MIGRATION.md), apps/celilo/designs/P5_MIGRATION_E2E.md.
+ * Part of P5 (openspec/specs/management-server-backup/spec.md), apps/celilo/designs/P5_MIGRATION_E2E.md.
  */
 
 import { tmpdir } from 'node:os';

package/src/cli/commands/commands-json.ts

@@ -0,0 +1,29 @@
+/**
+ * Commands Command
+ *
+ * Serializes the CLI command registry (`COMMANDS`) as JSON so an external
+ * consumer — `@celilo/mcp` above all — can fetch the *live* surface of whatever
+ * celilo version this server runs and generate its tool set from it, rather than
+ * compiling a copy that drifts (design D3). The registry is already structured
+ * data; this just prints it.
+ */
+
+import { COMMANDS } from '@celilo/core';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle `celilo commands [--json]`.
+ *
+ * The only useful output is the JSON tree, so we emit it whether or not `--json`
+ * is passed; the flag exists to make the intent explicit and completable.
+ */
+export async function handleCommands(
+  _args: string[],
+  _flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  return {
+    success: true,
+    message: JSON.stringify(COMMANDS),
+    rawOutput: true,
+  };
+}

package/src/cli/commands/completion.ts

@@ -3,7 +3,7 @@
  * Generate shell completion scripts for bash/zsh
  */
 
-import { COMMANDS } from '../command-registry';
+import { COMMANDS } from '@celilo/core';
 import { generateBashCompletion, generateFishCompletion } from '../completion';
 import { generateRichZshCompletion } from '../generate-zsh-completion';
 import { celiloIntro } from '../prompts';

package/src/cli/commands/events.ts

@@ -79,7 +79,7 @@ function snakeCaseKeys(obj: Record<string, unknown>): Record<string, unknown> {
 
 /**
  * `celilo events run-hook <module> <sub-name> [<event_id>]` — the generic
- * runner a `hook:` subscription resolves to (v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md).
+ * runner a `hook:` subscription resolves to (openspec/specs/event-driven-hook-subscriptions/spec.md).
  *
  * The dispatcher spawns this as a fault-isolated subprocess. It re-reads the
  * module's manifest to find the named subscription's `hook` + `hook_inputs`,

package/src/cli/commands/module-changeset.ts

@@ -1,6 +1,6 @@
 /**
  * `celilo module changeset [<module-dir>] --bump <major|minor|patch> [-m <msg>]`
- * — author a changeset for a module (ISS-0151 / v2/MODULE_VERSIONING.md).
+ * — author a changeset for a module (ISS-0151 / openspec/changes/module-version-semantics/proposal.md).
  *
  * Writes `.changeset/<name>.md` keyed by the MODULE id (Option A), the same
  * on-disk format `celilo module version` consumes. This is the thin authoring

package/src/cli/commands/module-import.ts

@@ -57,7 +57,7 @@ Examples:
  */
 /**
  * Run the base-module-aspect approval flow after a module's primary
- * import succeeds. Per v2/CELILO_BASE.md D2:
+ * import succeeds. Per openspec/specs/base-module-aspects/spec.md D2:
  *
  *   - Modules without a `base_module_aspect` block: no-op.
  *   - Re-imports of a version that's already been approved with the

package/src/cli/commands/module-list.ts

@@ -1,20 +1,34 @@
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
+import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
 /**
  * Handle module list command
  *
- * Usage: celilo module list
+ * Usage: celilo module list [--json]
  *
  * @returns Command result
  */
-export async function handleModuleList(): Promise<CommandResult> {
+export async function handleModuleList(
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
   const db = getDb();
 
   // Query all modules
   const moduleRows = db.select().from(modules).all();
 
+  // Stable machine-readable roster — the backbone the MCP composite
+  // troubleshooting tools correlate audit findings against (ce-77i.5).
+  if (hasFlag(flags, 'json')) {
+    return {
+      success: true,
+      message: JSON.stringify({ modules: moduleRows }, null, 2),
+      rawOutput: true,
+      data: moduleRows,
+    };
+  }
+
   if (moduleRows.length === 0) {
     return {
       success: true,

package/src/cli/commands/module-publish.ts

@@ -166,7 +166,7 @@ export async function publishOneModule(
   // Stale-check: src commits past the last manifest.yml commit. Only fires
   // when the dir is in git history; brand-new uncommitted modules pass.
   //
-  // Skipped for changeset/pin modules (ISS-0151 / v2/MODULE_VERSIONING.md): a
+  // Skipped for changeset/pin modules (ISS-0151 / openspec/changes/module-version-semantics/proposal.md): a
   // changeset module's version is authored via .changeset/ + `celilo module
   // version` and ordered by +N, so source-after-manifest is normal, not drift;
   // a pin module's version is checked against its upstream resolver. The gate

package/src/cli/commands/module-remove.ts

@@ -24,6 +24,7 @@ import {
 } from '../../services/celilo-events';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
 import { completeOperation, failOperation, startOperation } from '../../services/module-operations';
+import { cleanupWebRoutesForModule } from '../../services/web-route-cleanup';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
@@ -204,6 +205,30 @@ async function performModuleRemove(
     }
   }
 
+  // Reclaim public_web routes BEFORE terraform destroy, so the provider host
+  // is still reachable for the /srv/www cleanup. Runs after on_uninstall so a
+  // module that tears its own routes down still wins (this then no-ops).
+  //
+  // Without this, removal deleted the rows via the FK cascade on `modules.id`
+  // and emitted nothing, so the provider kept serving a route for a module that
+  // no longer existed. See services/web-route-cleanup.ts.
+  try {
+    const routeCleanup = await cleanupWebRoutesForModule({ moduleId, db });
+    if (routeCleanup.routesRemoved > 0) {
+      const reclaimed =
+        routeCleanup.assetDirsRemoved.length > 0
+          ? ` and reclaimed ${routeCleanup.assetDirsRemoved.join(', ')}`
+          : '';
+      log.info(`Removed ${routeCleanup.routesRemoved} web route(s) for ${moduleId}${reclaimed}`);
+    }
+    for (const warning of routeCleanup.warnings) {
+      log.warn(warning);
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.warn(`Web route cleanup failed (continuing): ${msg}`);
+  }
+
   // Check if module has infrastructure that needs to be destroyed
   const infra = db
     .select()
@@ -301,7 +326,7 @@ async function performModuleRemove(
     }
   })();
 
-  // Announce teardown on the bus (D5, v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md). A
+  // Announce teardown on the bus (D5, openspec/specs/event-driven-hook-subscriptions/spec.md). A
   // dns_internal provider's system.destroyed.* subscription runs its
   // on_system_event hook (op: deregister) to remove each host's records.
   if (removedSystems.length > 0) {

package/src/cli/commands/module-types.ts

@@ -6,7 +6,7 @@
  * manifest.yml. The generated file exposes a `<ModuleName>Config`
  * interface that hook scripts import via `defineHook<ConfigT, ...>`.
  *
- * See `design/TECHNICAL_DESIGN_HOOK_API_V2.md` D2 for the design rationale.
+ * See `openspec/changes/hook-api-v2/proposal.md` D2 for the design rationale.
  *
  * Subcommands:
  *   celilo module types generate <module-dir>  — write types.d.ts

package/src/cli/commands/module-upgrade.ts

@@ -1,6 +1,6 @@
 /**
  * `celilo module upgrade [name]` — the build-bus CD verb (ISS-0138) + the
- * registry-poll it drives (ISS-0139). v2/BUILD_BUS.md.
+ * registry-poll it drives (ISS-0139). openspec/changes/build-bus-poll-cd/proposal.md.
  *
  *   module upgrade <name>   one module: registry-latest → update → [backup,
  *                           posture-gated] → deploy → verify.

package/src/cli/commands/module-version.ts

@@ -1,6 +1,6 @@
 /**
  * `celilo module version [<module-dir>]` — stamp a changeset-kind module's
- * payload version into manifest.yml (ISS-0151 / v2/MODULE_VERSIONING.md).
+ * payload version into manifest.yml (ISS-0151 / openspec/changes/module-version-semantics/proposal.md).
  *
  * Reads `.changeset/*.md` (keyed by the MODULE id — Option A), computes the next
  * `manifest.yml#version`, prepends a CHANGELOG entry, and deletes the consumed

package/src/cli/commands/module-where.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test';
+import type { NetworkZone } from '../../db/schema';
+import { reachabilityHint } from './module-where';
+
+describe('reachabilityHint (ce-jje — role-based, never a literal address)', () => {
+  test('internal is reachable directly from the LAN', () => {
+    expect(reachabilityHint('internal')).toContain('directly from the internal/home LAN');
+  });
+
+  test('external is a public zone reachable at its own address', () => {
+    expect(reachabilityHint('external')).toContain('public');
+  });
+
+  test('firewall-segmented zones route via the natIp DNAT', () => {
+    for (const zone of ['dmz', 'app', 'secure'] as NetworkZone[]) {
+      expect(reachabilityHint(zone)).toContain('natIp DNAT');
+    }
+  });
+
+  test('no hint hardcodes an IP address (CLAUDE.md network-model rule)', () => {
+    const zones: NetworkZone[] = ['internal', 'dmz', 'app', 'secure', 'external'];
+    for (const zone of zones) {
+      expect(reachabilityHint(zone)).not.toMatch(/\d+\.\d+\.\d+\.\d+/);
+    }
+  });
+});