@celilo/cli 0.11.0 → 0.12.0

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({

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

@@ -13,19 +13,9 @@
 import { execSync, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { publishableSet, readWorkspace } from '../../../../../../scripts/workspace-graph';
 import type { PackageJson, WorkspaceVersionMap } from './types';
 
-// Publish in dependency order: leaves first, then consumers.
-// Exported so tests can construct a synthetic packages list against the
-// same shape; runtime always uses these in this exact order.
-export const PACKAGES = [
-  'packages/cli-display',
-  'packages/capabilities',
-  'packages/event-bus',
-  'apps/celilo',
-  'packages/e2e',
-] as const;
-
 // REPO_ROOT discovery — this file lives at
 // apps/celilo/src/cli/commands/publish/helpers.ts, six dirs deep.
 // Kept as a relative path (matches existing convention in
@@ -35,6 +25,23 @@ export const REPO_ROOT = resolve(import.meta.dir, '../../../../../..');
 
 export const ENV_FILE = join(REPO_ROOT, '.env');
 
+/**
+ * The publishable workspace packages (repo-relative dirs), topologically
+ * ordered leaves-first — the order the executor publishes in, so a dep is on
+ * npm before its dependent references it. DERIVED from the live workspace
+ * (every non-private @celilo/* package), never a hardcoded list: a hand-list is
+ * exactly what left @celilo/core/mcp/visualizer invisible to the driver and let
+ * npm-consumer-smoke rot (apps/celilo/designs/WORKSPACE_PACKAGE_GRAPH.md).
+ *
+ * A FUNCTION, not a module-load const: the publish command ships in the
+ * consumer @celilo/cli, and readWorkspace() against a consumer's non-monorepo
+ * install would throw at import — bricking the whole CLI. Deriving lazily means
+ * the disk read happens only when a publish actually runs (in the monorepo).
+ */
+export function getPublishPackages(): string[] {
+  return publishableSet(readWorkspace(REPO_ROOT)).map((p) => p.dir);
+}
+
 export function readPkg(dir: string): PackageJson {
   return JSON.parse(readFileSync(join(REPO_ROOT, dir, 'package.json'), 'utf-8'));
 }
@@ -76,7 +83,7 @@ export function isAncestor(maybeAncestor: string, descendant: string): boolean {
 
 export function buildWorkspaceVersionMap(): WorkspaceVersionMap {
   const m = new Map<string, string>();
-  for (const pkg of PACKAGES) {
+  for (const pkg of getPublishPackages()) {
     const { name, version } = readPkg(pkg);
     if (name && version) m.set(name, version);
   }
@@ -129,7 +136,7 @@ export function readExternalProjectPaths(): string[] {
  * Read `NPM_PUBLISH_TARGET` from .env — the registry URL `celilo publish`
  * points `bun publish --registry` at for @celilo/* packages (a deployed
  * npm-cache-node). Unset → publish to npmjs (current behavior). See
- * v2/NPM_CACHE_NODE.md Phase 3.1 / v2/PUBLILO_CLI.md decision 10.
+ * openspec/changes/private-npm-registry/proposal.md Phase 3.1 / openspec/changes/publilo-cli/proposal.md decision 10.
  */
 export function readNpmPublishTarget(): string | null {
   if (!existsSync(ENV_FILE)) return null;
@@ -230,7 +237,7 @@ export function readGlobalInstalledVersion(name: string): string | null {
  */
 export function fetchLatestVersions(): Map<string, string> {
   const out = new Map<string, string>();
-  for (const pkg of PACKAGES) {
+  for (const pkg of getPublishPackages()) {
     const { name } = readPkg(pkg);
     if (!name) continue;
     const r = spawnSync('npm', ['view', name, 'version'], {

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

@@ -1,6 +1,6 @@
 /**
  * `celilo publish` entry point — thin orchestration over the
- * planner/executor split (v2/PUBLILO_CLI.md Phase 2).
+ * planner/executor split (openspec/changes/publilo-cli/proposal.md Phase 2).
  *
  *   parse args  →  preflight  →  build plan  →  display  →  confirm  →  execute
  *
@@ -41,7 +41,7 @@ import {
   printPendingChangesets,
 } from './changesets';
 import { executePlan } from './execute';
-import { PACKAGES, REPO_ROOT, isPublished, readPkg } from './helpers';
+import { REPO_ROOT, getPublishPackages, isPublished, readPkg } from './helpers';
 import { displayPlan, planPublish } from './plan';
 import {
   applyReleaseTouch,
@@ -170,7 +170,7 @@ async function handleDryRun(opts: PublishOptions): Promise<never> {
 
   if (opts.mode.kind === 'alpha') {
     console.log('\nAlpha publish plan:');
-    for (const pkg of PACKAGES) {
+    for (const pkg of getPublishPackages()) {
       const { name, version } = readPkg(pkg);
       if (!name || !version) continue;
       const n = nextAlphaNumber(name, version);
@@ -294,7 +294,7 @@ export async function main(argv: string[]): Promise<void> {
     printPreflightReport(preflight);
   }
 
-  // Changesets — Phase 4 of v2/PUBLILO_CLI.md. Only applies in normal
+  // Changesets — Phase 4 of openspec/changes/publilo-cli/proposal.md. Only applies in normal
   // mode: alpha publishes are throwaway prereleases (applying changesets
   // would burn them on alpha publishes), and promote graduates an
   // existing alpha rather than producing a new version. The

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

@@ -2,7 +2,7 @@
  * Umbrella planner — composes the per-phase planners into a single
  * `PublishPlan`.
  *
- * The planner is the value-add of v2/PUBLILO_CLI.md Phase 2: it does
+ * The planner is the value-add of openspec/changes/publilo-cli/proposal.md Phase 2: it does
  * all the world-reads (npm view, git log, fs walks) and produces a
  * typed description of every side effect the executor will perform.
  * Dry-run prints the plan and exits; a real publish confirms the plan
@@ -14,7 +14,7 @@
 
 import { planConsumerPins } from './consumer-pins';
 import { planGlobalUpdate } from './global-install';
-import { PACKAGES, buildWorkspaceVersionMap, currentGitHead } from './helpers';
+import { buildWorkspaceVersionMap, currentGitHead, getPublishPackages } from './helpers';
 import { planModulePublish } from './module-registry';
 import { runPreflight } from './preflight';
 import type { PublishOptions, PublishPlan } from './types';
@@ -45,7 +45,7 @@ export function planPublish(opts: PublishOptions): PublishPlan {
 
   const workspaceResult = planWorkspace({
     mode: opts.mode,
-    packages: PACKAGES,
+    packages: getPublishPackages(),
     baseWorkspaceVersions,
     gitHead,
   });

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

@@ -17,8 +17,8 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { checkModuleStale } from '../../../services/module-validator/git-hygiene';
 import {
-  PACKAGES,
   REPO_ROOT,
+  getPublishPackages,
   isAncestor,
   isPublished,
   lastCommitTouching,
@@ -77,7 +77,7 @@ export function runPreflight(): PreflightReport {
   }).trim();
 
   const workspaceStale: StalenessIssue[] = [];
-  for (const pkg of PACKAGES) {
+  for (const pkg of getPublishPackages()) {
     const issue = checkStaleVersion(pkg);
     if (issue) workspaceStale.push(issue);
   }

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

@@ -1,6 +1,6 @@
 /**
  * Type definitions for `celilo publish` — the planner/executor split per
- * v2/PUBLILO_CLI.md Phase 2.
+ * openspec/changes/publilo-cli/proposal.md Phase 2.
  *
  * The umbrella `PublishPlan` enumerates everything a publish run intends
  * to do. It's produced by the pure planner (`plan.ts`) and consumed by
@@ -239,7 +239,7 @@ export interface ModuleItem {
 
 /**
  * Umbrella plan — the central data structure of Phase 2 of the publish
- * CLI refactor (v2/PUBLILO_CLI.md). One plan covers all four phases of
+ * CLI refactor (openspec/changes/publilo-cli/proposal.md). One plan covers all four phases of
  * a publish run; the executor consumes it top-to-bottom.
  */
 export interface PublishPlan {

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

@@ -1,5 +1,5 @@
 /**
- * Workspace planner tests — v2/PUBLILO_CLI.md Phase 2 payoff.
+ * Workspace planner tests — openspec/changes/publilo-cli/proposal.md Phase 2 payoff.
  *
  * The planner moved out of the monolithic runPublishPhase precisely so
  * these tests would be possible: no npm subprocesses, no bun publish

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

@@ -1,7 +1,7 @@
 /**
  * Workspace publish — Phase 1 of `celilo publish`.
  *
- * Planner/executor split per v2/PUBLILO_CLI.md Phase 2:
+ * Planner/executor split per openspec/changes/publilo-cli/proposal.md Phase 2:
  *
  *   planWorkspace(opts)  →  WorkspaceItem[]   // pure, no mutations
  *   executeWorkspace(plan, ...)               // mutates package.json,
@@ -325,7 +325,7 @@ export async function verifyPublishedDeps(
  * registry target is configured (a deployed npm-cache-node) AND the
  * package is @celilo/*-scoped, point bun at it via --registry; otherwise
  * publish to the default registry (npmjs — current behavior).
- * v2/NPM_CACHE_NODE.md Phase 3.1 / v2/PUBLILO_CLI.md decision 10.
+ * openspec/changes/private-npm-registry/proposal.md Phase 3.1 / openspec/changes/publilo-cli/proposal.md decision 10.
  */
 export function buildPublishArgs(
   item: Pick<WorkspaceItem, 'name' | 'tag'>,

package/src/cli/commands/registry-owner.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for `celilo registry owner list/show/set` (ce-1ch, SECURE_MODULE_PUBLISH.md D-C/D-E).
+ * The admin token is resolved from the local publish_tokens list; registry
+ * calls are stubbed so these stay hermetic.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import {
+  handleRegistryOwnerList,
+  handleRegistryOwnerSet,
+  handleRegistryOwnerShow,
+} from './registry-owner';
+import { handleRegistryTokenAdd } from './registry-token';
+
+const NO_FLAGS: Record<string, string | boolean> = {};
+
+describe('registry owner commands', () => {
+  let dataDir: string;
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'celilo-registry-owner-'));
+    process.env.CELILO_DATA_DIR = dataDir;
+    process.env.CELILO_DB_PATH = join(dataDir, 'celilo.db');
+    getDb()
+      .insert(modules)
+      .values({
+        id: 'celilo-registry',
+        name: 'Celilo Registry',
+        version: '1.0.0',
+        sourcePath: '/test',
+        manifestData: {},
+      })
+      .run();
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(async () => {
+    fetchSpy.mockRestore();
+    closeDb();
+    process.env.CELILO_DATA_DIR = undefined;
+    process.env.CELILO_DB_PATH = undefined;
+    if (existsSync(dataDir)) await rm(dataDir, { recursive: true, force: true });
+  });
+
+  test('list errors when no admin token is configured', async () => {
+    const result = await handleRegistryOwnerList(NO_FLAGS);
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.error).toContain('admin publish token');
+  });
+
+  test('list resolves the admin token and renders the owner table', async () => {
+    // Seed a scoped token first (ignored) then a bare admin token (used).
+    await handleRegistryTokenAdd(['cpt_scoped homebridge']);
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          owners: [
+            {
+              moduleName: 'homebridge',
+              ownerSub: 'alice',
+              claimedAt: 'T',
+              sourceGroup: 'celilo-authors',
+            },
+          ],
+        }),
+        { status: 200 },
+      ),
+    );
+
+    const result = await handleRegistryOwnerList(NO_FLAGS);
+    expect(result.success).toBe(true);
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    // The bare admin token is used, not the scoped one.
+    expect((init.headers as Record<string, string>).Authorization).toBe('admin-tok');
+    if (result.success) expect(result.message).toContain('homebridge');
+  });
+
+  test('list reports an empty table cleanly', async () => {
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ owners: [] }), { status: 200 }));
+    const result = await handleRegistryOwnerList(NO_FLAGS);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.message).toContain('No module ownerships');
+  });
+
+  test('show requires a module argument', async () => {
+    const result = await handleRegistryOwnerShow([], NO_FLAGS);
+    expect(result.success).toBe(false);
+  });
+
+  test('show reports an unclaimed name', async () => {
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+    const result = await handleRegistryOwnerShow(['never-claimed'], NO_FLAGS);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.message).toContain('unclaimed');
+  });
+
+  test('show renders the owner of a claimed name', async () => {
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          owner: {
+            moduleName: 'caddy',
+            ownerSub: 'bob',
+            claimedAt: 'T',
+            sourceGroup: 'celilo-admins',
+          },
+        }),
+        { status: 200 },
+      ),
+    );
+    const result = await handleRegistryOwnerShow(['caddy'], NO_FLAGS);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.message).toContain('bob');
+  });
+
+  test('set requires both module and owner-sub', async () => {
+    expect((await handleRegistryOwnerSet(['homebridge'], NO_FLAGS)).success).toBe(false);
+    expect((await handleRegistryOwnerSet([], NO_FLAGS)).success).toBe(false);
+  });
+
+  test('set POSTs the reassignment with the admin token', async () => {
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          owner: {
+            moduleName: 'homebridge',
+            ownerSub: 'carol',
+            claimedAt: 'T',
+            sourceGroup: 'admin-reassign',
+          },
+        }),
+        { status: 200 },
+      ),
+    );
+    const result = await handleRegistryOwnerSet(['homebridge', 'carol'], NO_FLAGS);
+    expect(result.success).toBe(true);
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain('/api/v1/modules/owners/homebridge');
+    expect(init.method).toBe('POST');
+    expect((init.headers as Record<string, string>).Authorization).toBe('admin-tok');
+    if (result.success) expect(result.message).toContain('carol');
+  });
+
+  test('surfaces a registry error detail', async () => {
+    await handleRegistryTokenAdd(['admin-tok']);
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'Unauthorized' }] }), { status: 401 }),
+    );
+    const result = await handleRegistryOwnerList(NO_FLAGS);
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.error).toContain('Unauthorized');
+  });
+});