@celilo/cli 0.11.0-alpha.0 → 0.12.0

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/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/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/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-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+/);
+    }
+  });
+});

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

@@ -0,0 +1,130 @@
+/**
+ * Module where command — host discovery: which system(s) serve a module.
+ *
+ * Answers "which host is providing services for <module>?" without an ssh
+ * scavenger hunt (ce-jje). Data source: the deployed-systems layer
+ * (module_systems) for the addressable hosts, reconciled live against Proxmox
+ * for the real node. Reachability is a role-based hint derived from the zone —
+ * never a hardcoded address (see CLAUDE.md network-model rules).
+ */
+
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import type { NetworkZone } from '../../db/schema';
+import { modules } from '../../db/schema';
+import { getModuleSystems } from '../../services/deployed-systems';
+import { formatPlacementLine, reconcilePlacement } from '../../services/placement-reconcile';
+import { getArg, hasFlag, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Role-based reachability hint for a zone. Says HOW to reach a host by the
+ * zone's firewall posture, not a literal address (subnets are operator config).
+ */
+export function reachabilityHint(zone: NetworkZone | string): string {
+  switch (zone) {
+    case 'internal':
+      return 'reachable directly from the internal/home LAN';
+    case 'external':
+      return 'public zone — reachable at its own address (cloud/VPS)';
+    case 'dmz':
+    case 'app':
+    case 'secure':
+      return `firewall-segmented (${zone}) — reach via the firewall's natIp DNAT, not routable directly from the LAN`;
+    default:
+      return `zone ${zone}`;
+  }
+}
+
+/**
+ * Handle module where command.
+ *
+ * Usage: celilo module where <id> [--json]
+ *
+ * @param args - Command arguments (module id)
+ * @param flags - Command flags (--json)
+ * @returns Command result
+ */
+export async function handleModuleWhere(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo module where <id> [--json]`,
+    };
+  }
+
+  const moduleId = getArg(args, 0);
+  if (!moduleId) {
+    return { success: false, error: 'Module ID is required' };
+  }
+
+  const db = getDb();
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+
+  if (!module) {
+    // CI/build infra (the celilo-builder VM, Forgejo runners) is NOT a module
+    // and is not in module_systems — point the operator at where that topology
+    // actually lives rather than a bare "not found".
+    return {
+      success: false,
+      error: `Module not found: ${moduleId}\n\nHost discovery covers deployed modules only. CI/build infrastructure (the celilo-builder VM, Forgejo CI runners) is not tracked here — see openspec/specs/forgejo-runner/spec.md and openspec/changes/build-bus-poll-cd/proposal.md for that topology.`,
+    };
+  }
+
+  const systems = getModuleSystems(moduleId, db);
+
+  if (systems.length === 0) {
+    const message = `Module '${moduleId}' has no deployed systems (API-only module, or not yet deployed).`;
+    if (hasFlag(flags, 'json')) {
+      return {
+        success: true,
+        message: JSON.stringify({ module: moduleId, systems: [] }, null, 2),
+        rawOutput: true,
+        data: { module: moduleId, systems: [] },
+      };
+    }
+    return { success: true, message };
+  }
+
+  // Reconcile the real node live from Proxmox (never throws; degrades to
+  // "node unknown" on outage) — same live-placement source as module status.
+  const placements = await reconcilePlacement(systems);
+
+  const data = placements.map(({ system, resolution }) => ({
+    name: system.name,
+    hostname: system.hostname,
+    ipv4_address: system.ipv4_address,
+    zone: system.zone,
+    vmid: system.infrastructure.vmid ?? null,
+    infra_type: system.infrastructure.type,
+    placement: formatPlacementLine(system, resolution),
+    reachability: reachabilityHint(system.zone),
+  }));
+
+  if (hasFlag(flags, 'json')) {
+    return {
+      success: true,
+      message: JSON.stringify({ module: moduleId, systems: data }, null, 2),
+      rawOutput: true,
+      data: { module: moduleId, systems: data },
+    };
+  }
+
+  const lines = [`Module '${moduleId}' is served by:`, ''];
+  for (const sys of data) {
+    lines.push(`  ${sys.hostname} (${sys.ipv4_address})`);
+    lines.push(`    placement: ${sys.placement}`);
+    lines.push(`    reachability: ${sys.reachability}`);
+    lines.push('');
+  }
+
+  return {
+    success: true,
+    message: lines.join('\n').trimEnd(),
+    data: { module: moduleId, systems: data },
+  };
+}

package/src/cli/commands/proxmox-node-list.ts

@@ -1,6 +1,6 @@
 /**
  * `celilo proxmox node list` — live per-node capacity from the Proxmox cluster
- * (ISS-0060, Phase 1 of v2/PROXMOX_CAPACITY_AND_LIFECYCLE.md).
+ * (ISS-0060, Phase 1 of openspec/changes/proxmox-capacity-lifecycle/proposal.md).
  *
  * Reads reality from the Proxmox API via `ProxmoxClient`, never a cached DB
  * value — the foundation for capacity-aware placement (ISS-0061) and

package/src/cli/commands/publish/alpha.test.ts

@@ -1,5 +1,5 @@
 /**
- * Alpha-helper tests — v2/PUBLILO_CLI.md Phase 3 payoff.
+ * Alpha-helper tests — openspec/changes/publilo-cli/proposal.md Phase 3 payoff.
  *
  * The pure functions in alpha.ts (parsePackageSpec, stripAlphaSuffix,
  * isAlphaVersion, pickNextAlphaN, decideAlphaSkip) need no I/O to

package/src/cli/commands/publish/alpha.ts

@@ -1,11 +1,11 @@
 /**
  * Alpha-tagging logic — `--alpha` publish + `--promote` graduation.
  *
- * The semantics live in `v2/FIRST_PUBLILO_ALPHA_TAGGING.md`; this
+ * The semantics live in `openspec/specs/alpha-publish-tagging/spec.md`; this
  * module is the implementation surface those flags drive. Per
- * v2/PUBLILO_CLI.md Phase 3, the alpha-specific helpers live here
+ * openspec/changes/publilo-cli/proposal.md Phase 3, the alpha-specific helpers live here
  * (not in helpers.ts) so it's clear where to look when extending the
- * model — e.g. to add `--beta` once `v2/BUILD_BUS.md`'s validation
+ * model — e.g. to add `--beta` once `openspec/changes/build-bus-poll-cd/proposal.md`'s validation
  * signal lands.
  *
  * Two-layer design for testability:

package/src/cli/commands/publish/changesets.ts

@@ -1,5 +1,5 @@
 /**
- * @changesets/cli integration — v2/PUBLILO_CLI.md Phase 4.
+ * @changesets/cli integration — openspec/changes/publilo-cli/proposal.md Phase 4.
  *
  * Changesets is the "what versions does this publish produce" piece
  * of the workflow. During dev, the operator runs `bun changeset` to

package/src/cli/commands/publish/global-install.ts

@@ -17,7 +17,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { PACKAGES, readGlobalInstalledVersion, readPkg } from './helpers';
+import { getPublishPackages, readGlobalInstalledVersion, readPkg } from './helpers';
 import type { GlobalUpdateItem, PackageJson } from './types';
 
 // ─── Planner ───────────────────────────────────────────────────────
@@ -97,7 +97,11 @@ export function planGlobalUpdate(input: PlanGlobalUpdateInput): GlobalUpdateItem
     return [];
   }
 
-  const ourNames = new Set(PACKAGES.map((p) => readPkg(p).name).filter((n): n is string => !!n));
+  const ourNames = new Set(
+    getPublishPackages()
+      .map((p) => readPkg(p).name)
+      .filter((n): n is string => !!n),
+  );
   const installed = Object.keys(globalPkg.dependencies ?? {}).filter((n) => ourNames.has(n));
 
   return decideGlobalUpdates({