@celilo/cli 0.11.0 → 0.12.1

package/src/cli/commands/token.ts

@@ -0,0 +1,160 @@
+/**
+ * Contributor identity tokens (idp-issued, per-user)
+ *
+ * `celilo token obtain|list|revoke` mints, lists, and revokes per-user API
+ * tokens from the idp (authentik) so a module contributor authenticates
+ * publishes AS THEMSELVES — no admin/shared token ever reaches their machine
+ * (SECURE_MODULE_PUBLISH.md). The token consumed by `celilo author init`.
+ *
+ * Distinct from `celilo registry token add/rm`, which manages the raw
+ * bootstrap `publish_tokens` list — a different trust/storage model. Keep the
+ * two families separate.
+ *
+ * Runs on-mgr where the idp provider + bootstrap token live (same model as
+ * registry-token.ts). The token string is shown once at mint; the idp stores
+ * it hashed and celilo persists nothing.
+ */
+
+import type { IdpCapability } from '@celilo/capabilities';
+import { getDb } from '../../db/client';
+import { loadCapabilityFunctions } from '../../hooks/capability-loader';
+import { createCapturingLogger } from '../../hooks/logger';
+import { getArg, getFlag } from '../parser';
+import type { CommandError, CommandResult } from '../types';
+
+/** Default identifier for a contributor's publish token — stable per user so obtain is idempotent. */
+function defaultIdentifier(username: string): string {
+  return `celilo-publish-${username}`;
+}
+
+function isError(v: unknown): v is CommandError {
+  return typeof v === 'object' && v !== null && 'success' in v && v.success === false;
+}
+
+/**
+ * Load the idp capability. Runs where the idp provider (authentik) is
+ * deployed; errors clearly when it isn't. The capturing logger discards the
+ * capability's own progress markers so command output stays clean.
+ */
+async function loadIdp(): Promise<IdpCapability | CommandError> {
+  const db = getDb();
+  const { logger } = createCapturingLogger();
+  const caps = await loadCapabilityFunctions('celilo-token', db, logger);
+  const idp = caps.idp as IdpCapability | undefined;
+  if (!idp) {
+    return {
+      success: false,
+      error:
+        'No idp provider found. Run this on the host where the idp (authentik) is deployed (celilo-mgr).',
+    };
+  }
+  return idp;
+}
+
+/** Resolve the target username from `--user` (or first positional arg). */
+function resolveUser(args: string[], flags: Record<string, string | boolean>): string | undefined {
+  const flag = getFlag(flags, 'user').trim();
+  if (flag) return flag;
+  return getArg(args, 0)?.trim();
+}
+
+/**
+ * `celilo token obtain --user <username> [--identifier <id>] [--description <text>]`
+ * Mints (or returns the existing) per-user token. Idempotent on identifier.
+ */
+export async function handleTokenObtain(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const username = resolveUser(args, flags);
+  if (!username) {
+    return {
+      success: false,
+      error:
+        'Username required\n\nUsage: celilo token obtain --user <username> [--identifier <id>]',
+    };
+  }
+  const identifier = getFlag(flags, 'identifier').trim() || defaultIdentifier(username);
+  const description = getFlag(flags, 'description').trim() || undefined;
+
+  const idp = await loadIdp();
+  if (isError(idp)) return idp;
+
+  const result = await idp.create_token({ username, identifier, description });
+  const verb = result.created ? 'Minted new' : 'Returned existing';
+
+  return {
+    success: true,
+    message: `${verb} per-user token for '${username}' (identifier: ${identifier})
+
+  ${result.token}
+
+Treat as a secret — store it now (CELILO_PUBLISH_TOKEN, or \`celilo author init --token …\`).
+celilo persists nothing; the idp stores it hashed.
+Revoke with: celilo token revoke ${identifier}`,
+  };
+}
+
+/**
+ * `celilo token list --user <username>`
+ * Lists the user's API tokens (metadata only — never the bearer string).
+ */
+export async function handleTokenList(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const username = resolveUser(args, flags);
+  if (!username) {
+    return {
+      success: false,
+      error: 'Username required\n\nUsage: celilo token list --user <username>',
+    };
+  }
+
+  const idp = await loadIdp();
+  if (isError(idp)) return idp;
+
+  const tokens = await idp.list_tokens({ username });
+  if (tokens.length === 0) {
+    return { success: true, message: `No API tokens for '${username}'.` };
+  }
+
+  const lines = tokens.map((t) => {
+    const desc = t.description ? `  — ${t.description}` : '';
+    const exp = t.expiring && t.expires ? `  (expires ${t.expires})` : '';
+    return `  ${t.identifier}${desc}${exp}`;
+  });
+  return {
+    success: true,
+    message: `API tokens for '${username}':\n${lines.join('\n')}`,
+  };
+}
+
+/**
+ * `celilo token revoke <identifier>` (or `--identifier <id>`)
+ * Deletes a token at the idp; the next publish with it is denied.
+ */
+export async function handleTokenRevoke(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const identifier = getArg(args, 0)?.trim() || getFlag(flags, 'identifier').trim();
+  if (!identifier) {
+    return {
+      success: false,
+      error: 'Identifier required\n\nUsage: celilo token revoke <identifier>',
+    };
+  }
+
+  const idp = await loadIdp();
+  if (isError(idp)) return idp;
+
+  const { revoked } = await idp.revoke_token({ identifier });
+  if (!revoked) {
+    return { success: false, error: `No token with identifier '${identifier}' found.` };
+  }
+  return {
+    success: true,
+    message: `Revoked token '${identifier}'. The next publish using it will be denied.`,
+  };
+}

package/src/cli/completion.ts

@@ -30,9 +30,11 @@ export async function getCompletions(words: string[], current: number): Promise<
   if (currentIndex === 0) {
     const commands = [
       'api',
+      'apt-upgrade',
       'audit',
       'backup',
       'capability',
+      'commands',
       'dns',
       'completion',
       'events',
@@ -44,12 +46,14 @@ export async function getCompletions(words: string[], current: number): Promise<
       'package',
       'proxmox',
       'publish',
+      'registry',
       'restore',
       'service',
       'status',
       'storage',
       'subscribers',
       'system',
+      'token',
       'version',
     ];
     return filterSuggestions(commands, args[0] || '');
@@ -68,6 +72,22 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(subcommands, args[1] || '');
   }
 
+  // Registry subcommands
+  if (command === 'registry' && currentIndex === 1) {
+    return filterSuggestions(['token', 'owner'], args[1] || '');
+  }
+  if (command === 'registry' && args[1] === 'token' && currentIndex === 2) {
+    return filterSuggestions(['add', 'rm'], args[2] || '');
+  }
+  if (command === 'registry' && args[1] === 'owner' && currentIndex === 2) {
+    return filterSuggestions(['list', 'show', 'set'], args[2] || '');
+  }
+
+  // Token subcommands (contributor identity tokens)
+  if (command === 'token' && currentIndex === 1) {
+    return filterSuggestions(['obtain', 'list', 'revoke'], args[1] || '');
+  }
+
   // Capability info - complete with capability names
   if (command === 'capability' && args[1] === 'info' && currentIndex === 2) {
     const db = getDb();
@@ -159,6 +179,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'run-hook',
       'secret',
       'status',
+      'where',
       'terraform-unlock',
       'types',
       'validate',

package/src/cli/generate-zsh-completion.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
-import { COMMANDS } from './command-registry';
-import type { CommandDef } from './command-registry';
+import { COMMANDS } from '@celilo/core';
+import type { CommandDef } from '@celilo/core';
 import { generateRichZshCompletion } from './generate-zsh-completion';
 
 describe('Zsh Completion Generator', () => {
@@ -79,12 +79,15 @@ describe('Zsh Completion Generator', () => {
   });
 
   test('all subcommand descriptions are present', () => {
+    function escapeDesc(text: string): string {
+      return text.replace(/\\/g, '\\\\').replace(/:/g, '\\:').replace(/'/g, "'\\''");
+    }
     function checkDescriptions(commands: CommandDef[]): void {
       for (const cmd of commands) {
         if (cmd.subcommands) {
           for (const sub of cmd.subcommands) {
-            // Description should appear in the _commands function
-            expect(output).toContain(sub.description.replace(/:/g, '\\:'));
+            // Description should appear (escaped) in the _commands function
+            expect(output).toContain(escapeDesc(sub.description));
           }
           checkDescriptions(cmd.subcommands);
         }
@@ -92,4 +95,19 @@ describe('Zsh Completion Generator', () => {
     }
     checkDescriptions(COMMANDS);
   });
+
+  test('generated completion is valid zsh syntax', () => {
+    // Recurrence gate: any unescaped quote/redirect in a description breaks the
+    // whole file (an apostrophe in "account's" once did). zsh -n parses without
+    // executing. Skip cleanly where zsh is unavailable (minimal CI images).
+    let zsh: ReturnType<typeof Bun.spawnSync>;
+    try {
+      zsh = Bun.spawnSync(['zsh', '-nc', output]);
+    } catch {
+      return; // ponytail: no zsh here — nothing to check
+    }
+    if (zsh.exitCode === null) return;
+    expect(zsh.stderr?.toString() ?? '').toBe('');
+    expect(zsh.exitCode).toBe(0);
+  });
 });

package/src/cli/generate-zsh-completion.ts

@@ -9,14 +9,18 @@
  * should never be hand-edited.
  */
 
-import type { ArgDef, CommandDef, FlagDef } from './command-registry';
+import type { ArgDef, CommandDef, FlagDef } from '@celilo/core';
 
 /**
  * Escape a string for use in zsh completion descriptions.
- * Colons and backslashes need escaping in _describe arrays.
+ * Descriptions are emitted inside single-quoted zsh strings, so:
+ *  - backslash and colon need escaping in _describe / _arguments specs
+ *  - a literal apostrophe must close-quote, emit an escaped quote, and reopen
+ *    ('...'\''...') — otherwise it terminates the string early and the rest of
+ *    the file mis-parses (e.g. "account's" broke completion at the next `->`).
  */
 function escapeZshDescription(text: string): string {
-  return text.replace(/\\/g, '\\\\').replace(/:/g, '\\:');
+  return text.replace(/\\/g, '\\\\').replace(/:/g, '\\:').replace(/'/g, "'\\''");
 }
 
 /**

package/src/cli/index.ts

@@ -4,10 +4,9 @@
  * Orchestration function (Rule 10.1) - routes commands to handlers
  */
 
+import { COMMANDS, type CommandDef, resolveRemote, runRemoteClient } from '@celilo/core';
 import * as p from '@clack/prompts';
-import { resolveRemote, runRemoteClient } from '../api/remote-client';
 import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
-import { COMMANDS, type CommandDef } from './command-registry';
 import {
   handleApiAuthorizedKeys,
   handleApiGrant,
@@ -15,8 +14,10 @@ import {
   handleApiList,
   handleApiRevoke,
 } from './commands/api';
+import { handleAptUpgrade } from './commands/apt-upgrade';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
+import { handleCommands } from './commands/commands-json';
 import { handleCompletion } from './commands/completion';
 import { handleDnsRegistrations } from './commands/dns';
 import {
@@ -76,11 +77,11 @@ import { handleModuleUpdate } from './commands/module-update';
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
 import { handleModuleVersion } from './commands/module-version';
+import { handleModuleWhere } from './commands/module-where';
 import { handlePackage } from './commands/package';
 import { handleProxmoxInstanceList } from './commands/proxmox-instance-list';
 import { handleProxmoxInstanceResize } from './commands/proxmox-instance-resize';
 import { handleProxmoxNodeList } from './commands/proxmox-node-list';
-import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
 import { handleSecretSet } from './commands/secret-set';
 import { handleServiceAddDigitalOcean } from './commands/service-add-digitalocean';
@@ -188,12 +189,16 @@ Commands:
   restore                  Restore a celilo-mgmt backup from a local file (fresh-bootstrap path)
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
+  apt-upgrade              Upgrade the deb-installed celilo packages + apply migrations
   ipam                     Manage IP address and VMID allocations and reservations
   proxmox                  Proxmox cluster introspection (proxmox node list)
   publish                  Publish workspace packages to npm and modules to celilo.computer
+  registry                 Administer the module registry (append-safe publish-token management)
+  token                    Manage contributor identity tokens (idp-issued per-user publish tokens)
   subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
   api                      Manage remote-API access (principals, grants, authorized_keys)
   completion               Generate shell completion scripts (bash/zsh)
+  commands                 Print the CLI command registry as JSON (drives @celilo/mcp)
 
   help, --help, -h         Show this help message
 
@@ -298,7 +303,7 @@ Description:
   Modules declare \`subscriptions:\` in their manifests; \`celilo module deploy\`
   emits lifecycle events that subscribers react to.
 
-  See infra/design/SQLITE_EVENT_BUS.md for the full design.
+  See infra/openspec/specs/event-bus/spec.md for the full design.
 
 Examples:
   celilo events run                                      # foreground dispatcher
@@ -337,7 +342,7 @@ Description:
   package name glob). The publisher signs every event with the
   subscriber's secret; the receiver verifies before reacting.
 
-  This is the static-config first cut of v2/BUILD_BUS.md — operators
+  This is the static-config first cut of openspec/changes/build-bus-poll-cd/proposal.md — operators
   manage subscribers explicitly. Auto-discovery via the celilo
   registry switchboard is a follow-on.
 
@@ -430,6 +435,79 @@ Examples:
   return { success: true, message: helpText };
 }
 
+function displayRegistryHelp(): CommandResult {
+  const helpText = `
+Celilo - Module Registry Administration
+
+Usage:
+  celilo registry <subcommand> [args...]
+
+Subcommands:
+  token add <token>            Append a publish token (append-safe; never clobbers others)
+  token rm <token>             Remove one publish token, leaving the rest intact
+  owner list                   List the module-owner table (who may publish what)
+  owner show <module>          Show the owner of one module name
+  owner set <module> <sub>     Reassign a module name to a new owner (admin)
+
+Description:
+  The celilo-registry module's publish_tokens secret is a newline-separated list
+  of bootstrap/admin publish tokens. Editing it with 'module secret set' OVERWRITES
+  the whole list, clobbering every other holder. These commands read-modify-write
+  the list instead.
+
+  The module-owner table (owner *) gates which module NAMES a verified publisher
+  may publish: the first verified publisher of an unclaimed name owns it
+  (first-publish-claims); thereafter only that owner or an admin may publish it.
+  'owner set' is the admin reassignment. These read the admin token from the local
+  publish_tokens list; pass --registry to target a non-default registry.
+
+  Run on the host where celilo-registry is deployed (where the master key lives).
+
+Examples:
+  celilo registry token add ci-token-abc123
+  celilo registry owner list
+  celilo registry owner show homebridge
+  celilo registry owner set homebridge alice
+`;
+
+  return { success: true, message: helpText.trim() };
+}
+
+function displayTokenHelp(): CommandResult {
+  const helpText = `
+Celilo - Contributor Identity Tokens (idp-issued, per-user)
+
+Usage:
+  celilo token <subcommand> [args...]
+
+Subcommands:
+  obtain --user <username>    Mint (or return) a per-user API token for publishing
+  list   --user <username>    List a user's API tokens (metadata only, no secret)
+  revoke <identifier>         Revoke a token by identifier; next publish denied
+
+Options:
+  --user <username>           The idp user the token is bound to
+  --identifier <id>           Token identifier (default: celilo-publish-<user>)
+  --description <text>        Human-readable description (obtain only)
+
+Description:
+  Issues per-user API tokens from the idp (authentik) so a module contributor
+  authenticates publishes AS THEMSELVES — no admin/shared token on their machine.
+  The token is consumed by 'celilo author init'. Shown once at mint; the idp
+  stores it hashed and celilo persists nothing.
+
+  Distinct from 'celilo registry token add/rm', which manages the raw bootstrap
+  publish_tokens list. Run on the host where the idp is deployed (celilo-mgr).
+
+Examples:
+  celilo token obtain --user alice
+  celilo token list --user alice
+  celilo token revoke celilo-publish-alice
+`;
+
+  return { success: true, message: helpText.trim() };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -1096,11 +1174,20 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleStatus();
   }
 
+  // Handle commands command (serialize the registry; drives @celilo/mcp)
+  if (parsed.command === 'commands') {
+    return handleCommands(parsed.args, parsed.flags);
+  }
+
   // Top-level alias: `celilo audit` → `celilo system audit`
   if (parsed.command === 'audit') {
     return handleSystemAudit(parsed.args, parsed.flags);
   }
 
+  if (parsed.command === 'apt-upgrade') {
+    return handleAptUpgrade(parsed.args, parsed.flags);
+  }
+
   // Route commands
   if (parsed.command === 'package') {
     // Handle package --help
@@ -1194,6 +1281,71 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'registry') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayRegistryHelp();
+    }
+
+    const registryFlagError = checkFlags('registry', parsed.subcommand, parsed.flags, parsed.args);
+    if (registryFlagError) return registryFlagError;
+
+    if (parsed.subcommand === 'token') {
+      const action = parsed.args[0];
+      const tokenArgs = parsed.args.slice(1);
+      const { handleRegistryTokenAdd, handleRegistryTokenRm } = await import(
+        './commands/registry-token'
+      );
+      if (action === 'add') return handleRegistryTokenAdd(tokenArgs);
+      if (action === 'rm') return handleRegistryTokenRm(tokenArgs);
+      return {
+        success: false,
+        error:
+          'Token action required (add or rm)\n\nUsage:\n  celilo registry token add <token>\n  celilo registry token rm <token>',
+      };
+    }
+
+    if (parsed.subcommand === 'owner') {
+      const action = parsed.args[0];
+      const ownerArgs = parsed.args.slice(1);
+      const { handleRegistryOwnerList, handleRegistryOwnerShow, handleRegistryOwnerSet } =
+        await import('./commands/registry-owner');
+      if (action === 'list') return handleRegistryOwnerList(parsed.flags);
+      if (action === 'show') return handleRegistryOwnerShow(ownerArgs, parsed.flags);
+      if (action === 'set') return handleRegistryOwnerSet(ownerArgs, parsed.flags);
+      return {
+        success: false,
+        error:
+          'Owner action required (list, show, or set)\n\nUsage:\n  celilo registry owner list\n  celilo registry owner show <module>\n  celilo registry owner set <module> <owner-sub>',
+      };
+    }
+
+    return {
+      success: false,
+      error: `Unknown registry subcommand: ${parsed.subcommand}\n\nRun "celilo registry --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'token') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayTokenHelp();
+    }
+
+    const tokenFlagError = checkFlags('token', parsed.subcommand, parsed.flags, parsed.args);
+    if (tokenFlagError) return tokenFlagError;
+
+    const { handleTokenObtain, handleTokenList, handleTokenRevoke } = await import(
+      './commands/token'
+    );
+    if (parsed.subcommand === 'obtain') return handleTokenObtain(parsed.args, parsed.flags);
+    if (parsed.subcommand === 'list') return handleTokenList(parsed.args, parsed.flags);
+    if (parsed.subcommand === 'revoke') return handleTokenRevoke(parsed.args, parsed.flags);
+
+    return {
+      success: false,
+      error: `Unknown token subcommand: ${parsed.subcommand}\n\nRun "celilo token --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'publish') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayPublishHelp();
@@ -1206,6 +1358,15 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     // flag identity since the parser canonicalises those.
     const publishIdx = process.argv.indexOf('publish');
     const publishArgv = publishIdx >= 0 ? process.argv.slice(publishIdx + 1) : [...parsed.args];
+    // Lazy-load the publish command: it's monorepo-only release tooling whose
+    // transitive import chain reaches scripts/workspace-graph.ts, which does NOT
+    // ship in @celilo/cli's files[]. A static top-level import pulled that into
+    // EVERY command's load graph, so `celilo --version` in a consumer install
+    // crashed on the unresolvable module (WORKSPACE_PACKAGE_GRAPH.md — the D3
+    // failure, deeper than the module-load throw). Loading it only when the
+    // operator actually runs `celilo publish` (which only happens in the
+    // monorepo) keeps every other command free of the dependency.
+    const { main: runPublish } = await import('./commands/publish');
     await runPublish(publishArgv);
     // runPublish handles its own console output (multi-phase, multi-line);
     // returning an empty success message tells the outer CLI loop to skip
@@ -1291,9 +1452,11 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'import':
         return handleModuleImport(parsed.args, parsed.flags);
       case 'list':
-        return handleModuleList();
+        return handleModuleList(parsed.flags);
       case 'status':
         return handleModuleStatus(parsed.args);
+      case 'where':
+        return handleModuleWhere(parsed.args, parsed.flags);
       case 'logs':
         return handleModuleLogs(parsed.args, parsed.flags);
       case 'health':
@@ -1685,7 +1848,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
   }
 
   if (parsed.command === 'restore') {
-    // Phase 4 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md — top-level
+    // Phase 4 of openspec/specs/management-server-backup/spec.md — top-level
     // fresh-bootstrap restore. Distinct from `celilo backup restore
     // <id>` (which restores from a configured storage destination
     // using an existing backup record); this one takes a local file

package/src/cli/parser.ts

@@ -4,7 +4,7 @@
  * Policy functions (Rule 10.1) - parsing and validation only
  */
 
-import type { CommandDef } from './command-registry';
+import type { CommandDef } from '@celilo/core';
 import type { ParsedCommand } from './types';
 
 /**

package/src/cli/restore-command.test.ts

@@ -1,6 +1,6 @@
 /**
  * Tests for the `celilo restore` top-level command (Phase 4 of
- * v2/SYSTEM_BACKUP_TERRAFORM_STATE.md).
+ * openspec/specs/management-server-backup/spec.md).
  *
  * Covers the CLI surface: routing, argument parsing, pre-flight
  * gating, error propagation. The actual file-direct restore +

package/src/db/client.ts

@@ -92,7 +92,7 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   }
 
   // One-time upgrade backfill for the target_ip → module_systems refactor
-  // (v2/MODULE_SYSTEMS_ADDRESSING.md). migrate() above has ensured the
+  // (openspec/specs/module-systems-addressing/spec.md). migrate() above has ensured the
   // module_systems table exists (migration 0007). A deployment created before
   // the refactor has its host data only in module_configs /
   // ip_allocations / module_infrastructure and an EMPTY module_systems, so its