@celilo/cli 0.5.0-alpha.0 → 0.5.0-alpha.2

package/drizzle/0009_dns_registrations.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `dns_registrations` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`provider_module_id` text NOT NULL,
+	`consumer_module_id` text NOT NULL,
+	`fqdn` text NOT NULL,
+	`ip` text,
+	`registered_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`refreshed_at` integer,
+	FOREIGN KEY (`provider_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`consumer_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `dns_registrations_provider_fqdn_idx` ON `dns_registrations` (`provider_module_id`,`fqdn`);

package/drizzle/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1781064000000,
       "tag": "0008_aspect_consent",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1781280898000,
+      "tag": "0009_dns_registrations",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.5.0-alpha.0",
+  "version": "0.5.0-alpha.2",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.3.0",
+    "@celilo/capabilities": "^0.4.0",
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.5",
+    "@celilo/event-bus": "^0.1.6",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/api-clients/proxmox.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+import { findNodeForVmid } from './proxmox';
+
+describe('findNodeForVmid (ISS-0090 — Proxmox is source of truth for current location)', () => {
+  // A trimmed /cluster/resources payload: guest rows carry a vmid; node/storage
+  // rows do not (only a node name).
+  const resources = [
+    { node: 'node2' }, // node row — no vmid
+    { node: 'node3' }, // storage row — no vmid
+    { vmid: 200, node: 'node2' }, // caddy
+    { vmid: 201, node: 'node3' }, // authentik
+  ];
+
+  test('returns the node a vmid currently lives on', () => {
+    expect(findNodeForVmid(resources, 200)).toBe('node2');
+    expect(findNodeForVmid(resources, 201)).toBe('node3');
+  });
+
+  test('returns null when the vmid is absent — container not created yet (first deploy)', () => {
+    expect(findNodeForVmid(resources, 999)).toBeNull();
+  });
+
+  test('never matches a node/storage row that has no vmid', () => {
+    expect(findNodeForVmid([{ node: 'node2' }, { node: 'node3' }], 200)).toBeNull();
+  });
+
+  test('returns null for an empty inventory', () => {
+    expect(findNodeForVmid([], 200)).toBeNull();
+  });
+});

package/src/api-clients/proxmox.ts

@@ -114,6 +114,18 @@ async function makeProxmoxRequest<T>(
         });
       });
 
+      // Fail fast instead of hanging on an unreachable host (no implicit timeout
+      // on https.request). Callers treat a failed result as "couldn't reach
+      // Proxmox" and fall back accordingly.
+      req.setTimeout(15_000, () => {
+        req.destroy();
+        resolve({
+          success: false,
+          message: 'Request timed out',
+          details: { timeoutMs: 15_000 },
+        });
+      });
+
       req.end();
     } catch (error) {
       resolve({
@@ -486,6 +498,51 @@ export async function listNodeStorage(
   return makeProxmoxRequest(credentials, `/nodes/${nodeName}/storage`);
 }
 
+/**
+ * Find which Proxmox node a given VMID currently lives on.
+ *
+ * Queries the cluster resource inventory (`/cluster/resources`), which lists
+ * every guest across all nodes with its current node, and matches by VMID
+ * (unique cluster-wide). Returns the node name, or `null` if the VMID isn't
+ * present — i.e. the container hasn't been created yet (a first deploy).
+ *
+ * ISS-0090: this is celilo's source of truth for WHERE a system currently is.
+ * A redeploy must target the node Proxmox reports here, NOT re-derive placement
+ * from the service's `default_target_node` (which only governs new placement) —
+ * otherwise a changed default tries to relocate every running container.
+ */
+export async function getNodeForVmid(
+  credentials: ProxmoxCredentials,
+  vmid: number,
+): Promise<ProxmoxResult<string | null>> {
+  // makeProxmoxRequest sends only url.pathname, so a `?type=vm` filter would be
+  // dropped — fetch the full inventory and match by vmid client-side instead.
+  const result = await makeProxmoxRequest<Array<{ vmid?: number; node?: string }>>(
+    credentials,
+    '/cluster/resources',
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  return { success: true, data: findNodeForVmid(result.data, vmid) };
+}
+
+/**
+ * Find the node a VMID lives on within a Proxmox cluster-resource list. Pure
+ * matching logic, split out from the network call for testability (Rule 10).
+ * Non-guest entries (storage/node rows) have no `vmid` and are skipped. Returns
+ * the node name, or `null` when the VMID isn't present.
+ */
+export function findNodeForVmid(
+  resources: Array<{ vmid?: number; node?: string }>,
+  vmid: number,
+): string | null {
+  const match = resources.find((r) => typeof r.vmid === 'number' && r.vmid === vmid);
+  return match?.node ?? null;
+}
+
 /**
  * List available LXC templates in storage
  */

package/src/cli/command-registry.ts

@@ -227,7 +227,7 @@ export const COMMANDS: CommandDef[] = [
       },
       {
         name: 'install-daemon',
-        description: 'Write a systemd/launchd user unit for the dispatcher',
+        description: 'Write a systemd/launchd unit for the dispatcher',
         flags: [
           {
             name: 'celilo-path',
@@ -237,15 +237,47 @@ export const COMMANDS: CommandDef[] = [
           },
           { name: 'poll-ms', description: 'Polling interval in ms', takesValue: true },
           { name: 'concurrency', description: 'Max parallel handlers', takesValue: true },
+          {
+            name: 'system',
+            description:
+              'System scope: /etc/systemd/system unit or /Library/LaunchDaemons plist, run as the celilo state-dir owner (management-plane shape)',
+            takesValue: false,
+          },
+          {
+            name: 'print',
+            description:
+              'Render the unit to stdout without writing it (used by the celilo-mgmt role)',
+            takesValue: false,
+          },
         ],
       },
       {
         name: 'uninstall-daemon',
         description: 'Remove the installed supervisor unit',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
       },
       {
         name: 'show-daemon',
         description: 'Print the currently installed unit file',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
+      },
+    ],
+  },
+  {
+    name: 'dns',
+    description: 'View DNS bookkeeping (registrations ledger)',
+    subcommands: [
+      {
+        name: 'registrations',
+        description: 'List the DNS registration ledger',
+        flags: [
+          {
+            name: 'provider',
+            description: 'Only show registrations owned by one provider module',
+            takesValue: true,
+            valueHint: 'module_ids',
+          },
+        ],
       },
     ],
   },

package/src/cli/commands/dns.ts

@@ -0,0 +1,57 @@
+/**
+ * `celilo dns` — operator views over celilo's DNS bookkeeping.
+ *
+ * `registrations` lists the dns_registrations ledger: every (provider,
+ * fqdn) the framework has registered via dns_registrar.registerHost,
+ * with the consumer that asked for it and when it was last re-asserted
+ * by the provider's refresh_registrations hook. Read-only; names only
+ * (module ids), never UUIDs. See
+ * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2b).
+ */
+
+import { getDb } from '../../db/client';
+import { listDnsRegistrations } from '../../services/dns-registrations';
+import type { CommandResult } from '../types';
+
+function formatAge(from: Date | null, now: Date): string {
+  if (!from) return 'never';
+  const mins = Math.floor((now.getTime() - from.getTime()) / 60_000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export async function handleDnsRegistrations(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const db = getDb();
+  const provider = typeof flags.provider === 'string' ? flags.provider : undefined;
+  const rows = listDnsRegistrations(db, { providerModuleId: provider });
+
+  if (rows.length === 0) {
+    const scope = provider ? ` for provider '${provider}'` : '';
+    return {
+      success: true,
+      message: `No DNS registrations recorded${scope}\n\nRegistrations are recorded when a module registers a hostname via the dns_registrar capability (e.g. during deploy).`,
+    };
+  }
+
+  const now = new Date();
+  const header = ['FQDN', 'IP', 'PROVIDER', 'CONSUMER', 'REGISTERED', 'REFRESHED'];
+  const table = rows.map((r) => [
+    r.fqdn,
+    r.ip ?? 'auto',
+    r.providerModuleId,
+    r.consumerModuleId,
+    formatAge(r.registeredAt, now),
+    formatAge(r.refreshedAt, now),
+  ]);
+  const widths = header.map((h, i) => Math.max(h.length, ...table.map((row) => row[i].length)));
+  const render = (row: string[]) => row.map((cell, i) => cell.padEnd(widths[i])).join('  ');
+
+  const lines = [render(header), ...table.map(render)];
+  return { success: true, message: lines.join('\n'), data: rows };
+}

package/src/cli/commands/events.ts

@@ -36,7 +36,12 @@ import { runNamedHook } from '../../hooks/run-named-hook';
 import type { HookName } from '../../hooks/types';
 import type { ModuleManifest } from '../../manifest/schema';
 import type { EnsureRequiredPayload } from '../../services/bus-interview';
-import { installDaemon, readInstalledUnit, uninstallDaemon } from '../../services/events-daemon';
+import {
+  installDaemon,
+  planDaemonInstall,
+  readInstalledUnit,
+  uninstallDaemon,
+} from '../../services/events-daemon';
 import { getArg, hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
@@ -778,27 +783,46 @@ function parseDurationMs(flag: string | boolean | undefined, defaultMs: number):
   }
 }
 
+function daemonScopeFrom(flags: Record<string, string | boolean>): 'user' | 'system' {
+  return flags.system ? 'system' : 'user';
+}
+
 /**
- * `celilo events install-daemon` — write a systemd user unit (Linux)
- * or launchd plist (macOS) that runs the dispatcher under supervision.
- * Writes the file but doesn't touch supervisor state — the operator
- * runs `systemctl --user enable --now ...` themselves so any change
- * is visible.
+ * `celilo events install-daemon` — write a systemd unit (Linux) or
+ * launchd plist (macOS) that runs the dispatcher under supervision.
+ * Default is a per-user unit; `--system` writes the system-scope unit
+ * (/etc/systemd/system, or a /Library/LaunchDaemons LaunchDaemon on
+ * macOS) that survives logout/reboot and runs as the celilo state-dir
+ * owner — the management-plane shape. Writes the file but doesn't
+ * touch supervisor state — the operator (or the celilo-mgmt Ansible
+ * role) runs the enable/bootstrap steps themselves so any change is
+ * visible.
  */
 export async function handleEventsInstallDaemon(
   _args: string[],
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
   try {
-    const result = installDaemon({
+    const options = {
       celiloPath: typeof flags['celilo-path'] === 'string' ? flags['celilo-path'] : undefined,
       pollMs: flags['poll-ms'] ? Number(flags['poll-ms']) : undefined,
       concurrency: flags.concurrency ? Number(flags.concurrency) : undefined,
-    });
+      scope: daemonScopeFrom(flags),
+    };
+    // --print: render-only, raw unit content on stdout. The celilo-mgmt
+    // Ansible role captures this and does the root-owned write itself
+    // (the deb wrapper runs celilo as the unprivileged celilo user, so
+    // a direct --system write would EACCES on /etc/systemd/system).
+    if (flags.print) {
+      const plan = planDaemonInstall(options);
+      return { success: true, message: plan.unitContent, rawOutput: true, data: plan };
+    }
+    const result = installDaemon(options);
     const lines = [
-      `Wrote ${result.platform} unit: ${shortenPath(result.unitPath)}`,
+      `Wrote ${result.platform} ${result.scope} unit: ${shortenPath(result.unitPath)}`,
       `  celilo:   ${shortenPath(result.celiloPath)}`,
       `  bus DB:   ${shortenPath(result.busDbPath)}`,
+      ...(result.runAsUser ? [`  runs as:  ${result.runAsUser}`] : []),
       '',
       'Next steps (run these yourself — install does not touch supervisor state):',
       ...result.nextSteps.map((s) => `  ${s}`),
@@ -813,13 +837,16 @@ export async function handleEventsInstallDaemon(
 }
 
 /**
- * `celilo events uninstall-daemon` — remove the supervisor unit file.
- * Symmetrical: prints the operator-facing disable steps, doesn't run
- * them.
+ * `celilo events uninstall-daemon` — remove the supervisor unit file
+ * (`--system` for the system-scope unit). Symmetrical: prints the
+ * operator-facing disable steps, doesn't run them.
  */
-export async function handleEventsUninstallDaemon(): Promise<CommandResult> {
+export async function handleEventsUninstallDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
   try {
-    const result = uninstallDaemon();
+    const result = uninstallDaemon({ scope: daemonScopeFrom(flags) });
     const lines = [
       result.removed
         ? `Removed unit: ${shortenPath(result.unitPath)}`
@@ -839,15 +866,20 @@ export async function handleEventsUninstallDaemon(): Promise<CommandResult> {
 
 /**
  * `celilo events show-daemon` — print whatever unit file is currently
- * installed so the operator can see exactly what the supervisor will
- * run, without grepping into platform-specific paths.
+ * installed (`--system` for the system-scope unit) so the operator can
+ * see exactly what the supervisor will run, without grepping into
+ * platform-specific paths.
  */
-export async function handleEventsShowDaemon(): Promise<CommandResult> {
-  const result = readInstalledUnit();
+export async function handleEventsShowDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const scope = daemonScopeFrom(flags);
+  const result = readInstalledUnit({ scope });
   if (!result.exists) {
     return {
       success: true,
-      message: `No supervisor unit installed at ${shortenPath(result.path)}\n\nRun \`celilo events install-daemon\` to create one.`,
+      message: `No supervisor unit installed at ${shortenPath(result.path)}\n\nRun \`celilo events install-daemon${scope === 'system' ? ' --system' : ''}\` to create one.`,
     };
   }
   return {

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

@@ -212,4 +212,41 @@ variables:
     expect(manifest.name).toBe('Test Module Renamed');
     expect(manifest.variables?.owns ?? []).toEqual([]);
   });
+
+  // Regression for ISS-0091: `module update` used to skip event-bus
+  // subscription registration (only `module import` did it), so a
+  // refreshed module silently lost its reconcile subscriptions — found
+  // live when caddy's reconcile_routes subscription vanished after a
+  // path-based update.
+  test('registers the new manifest subscriptions on the bus (ISS-0091)', async () => {
+    process.env.EVENT_BUS_DB = join(tempDir, 'events.db');
+    try {
+      writeFileSync(
+        join(srcDir, 'manifest.yml'),
+        `celilo_contract: "1.0"
+id: testmod
+name: Test Module
+version: 1.1.0
+description: fixture with subscriptions
+subscriptions:
+  - name: testmod-tick
+    pattern: timer.tick.15m
+    handler: "true"
+`,
+      );
+      const result = await upgradeOne(srcDir, db, {}, { quiet: true });
+      expect(result.status).toBe('success');
+
+      const { openBus, defineEvents } = await import('@celilo/event-bus');
+      const bus = openBus({ dbPath: join(tempDir, 'events.db'), events: defineEvents({}) });
+      try {
+        // Subscriber names are scoped `<module-id>.<sub-name>` on the bus.
+        expect(bus.getSubscriberByName('testmod.testmod-tick')).not.toBeNull();
+      } finally {
+        bus.close();
+      }
+    } finally {
+      process.env.EVENT_BUS_DB = undefined;
+    }
+  });
 });

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

@@ -293,6 +293,22 @@ export async function upgradeOne(
     }
   }
 
+  // (Re-)register event-bus subscriptions from the new manifest —
+  // mirrors import.ts (ISS-0091: update used to skip this, so a
+  // refreshed module silently lost its reconcile subscriptions).
+  // registerModuleSubscriptions is idempotent; best-effort like import:
+  // a bus problem shouldn't wedge the upgrade, but must be loud.
+  try {
+    const { registerModuleSubscriptions } = await import('../../services/module-subscriptions');
+    registerModuleSubscriptions(newManifest, installedPath);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.warn(`  ${moduleId}: failed to register event-bus subscriptions: ${msg}`);
+    log.warn(
+      '  Module upgraded, but reactive flows on the event bus will not fire until this is fixed.',
+    );
+  }
+
   if (!opts.quiet) {
     log.success(`Upgraded ${moduleId} (${previousVersion} → ${newVersion})`);
   }

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

@@ -14,6 +14,7 @@ import {
   isAlphaVersion,
   parsePackageSpec,
   pickNextAlphaN,
+  prereleaseDistTag,
   stripAlphaSuffix,
 } from './alpha';
 
@@ -80,6 +81,31 @@ describe('isAlphaVersion', () => {
   });
 });
 
+describe('prereleaseDistTag (ISS-0083)', () => {
+  test('stable versions get no override → @latest', () => {
+    expect(prereleaseDistTag('0.5.0')).toBeUndefined();
+    expect(prereleaseDistTag('1.0.0')).toBeUndefined();
+    expect(prereleaseDistTag('10.20.30')).toBeUndefined();
+  });
+
+  test('prerelease versions derive their dist-tag from the identifier', () => {
+    expect(prereleaseDistTag('0.5.0-alpha.0')).toBe('alpha');
+    expect(prereleaseDistTag('0.5.0-alpha.3')).toBe('alpha');
+    expect(prereleaseDistTag('1.0.0-beta.2')).toBe('beta');
+    expect(prereleaseDistTag('1.0.0-rc.1')).toBe('rc');
+  });
+
+  test('prerelease without a dotted counter still yields its identifier', () => {
+    expect(prereleaseDistTag('1.0.0-alpha')).toBe('alpha');
+    expect(prereleaseDistTag('1.0.0-next')).toBe('next');
+  });
+
+  test('a prerelease NEVER maps to latest', () => {
+    expect(prereleaseDistTag('0.5.0-alpha.0')).not.toBe('latest');
+    expect(prereleaseDistTag('0.5.0-alpha.0')).not.toBeUndefined();
+  });
+});
+
 describe('pickNextAlphaN', () => {
   test('returns 0 when no alphas exist for the target core', () => {
     expect(pickNextAlphaN([], '0.7.14')).toBe(0);

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

@@ -52,6 +52,29 @@ export function isAlphaVersion(version: string): boolean {
   return /-alpha\.\d+$/.test(version);
 }
 
+/**
+ * ISS-0083: the npm dist-tag a version must publish under, derived from
+ * its semver prerelease identifier. A prerelease (e.g. `0.5.0-alpha.0`,
+ * `1.0.0-beta.2`, `1.0.0-rc.1`) MUST be tagged with its prerelease name
+ * (`alpha`/`beta`/`rc`/…), NEVER `latest` — otherwise `npm install <pkg>`
+ * (no tag) pulls a prerelease, and the prerelease tag the .deb resolves
+ * (`@celilo/cli@alpha`) goes stale. A stable version returns undefined
+ * (publish defaults to `latest`, which is correct for stable).
+ *
+ * The tag is the FIRST dot-separated token of the prerelease component:
+ *   0.5.0-alpha.0   → "alpha"
+ *   1.0.0-beta.2    → "beta"
+ *   1.0.0-rc.1      → "rc"
+ *   1.0.0           → undefined (→ latest)
+ */
+export function prereleaseDistTag(version: string): string | undefined {
+  const dash = version.indexOf('-');
+  if (dash === -1) return undefined;
+  const prerelease = version.slice(dash + 1);
+  const identifier = prerelease.split('.')[0];
+  return identifier || undefined;
+}
+
 /**
  * Pure inner of `nextAlphaNumber`. Given the full list of versions
  * for a package (whatever `npm view <name> versions --json` returned)

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

@@ -166,8 +166,13 @@ export interface WorkspaceItem {
    * `X.Y.Z-alpha.N` for alpha mode, base-stripped for promote mode.
    */
   versionToPublish: string;
-  /** npm dist-tag override (only `'alpha'` for alpha mode; undefined → `@latest`). */
-  tag?: 'alpha';
+  /**
+   * npm dist-tag override. `'alpha'` for alpha mode; for normal mode a
+   * prerelease version (e.g. `0.5.0-alpha.0`) derives its tag from the
+   * prerelease identifier (ISS-0083) so it never lands on `@latest`.
+   * undefined → `@latest` (only for stable versions).
+   */
+  tag?: string;
   /**
    * Rewrite recipe applied to the package's package.json immediately
    * before `bun publish`. Restored from `originalPackageJson` after.

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

@@ -29,7 +29,13 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { join, relative } from 'node:path';
-import { ALPHA_TAG, alphaSkipDecision, nextAlphaNumber, stripAlphaSuffix } from './alpha';
+import {
+  ALPHA_TAG,
+  alphaSkipDecision,
+  nextAlphaNumber,
+  prereleaseDistTag,
+  stripAlphaSuffix,
+} from './alpha';
 import { REPO_ROOT, isPublished, readPkg } from './helpers';
 import type {
   PackageJson,
@@ -140,6 +146,10 @@ export function planWorkspace(opts: PlanWorkspaceInput): PlanWorkspaceOutput {
       workspaceVersions.set(name, versionToPublish);
     } else {
       versionToPublish = version;
+      // ISS-0083: a prerelease version in package.json (e.g. 0.5.0-alpha.0)
+      // must publish under its prerelease dist-tag, never `latest`. Only
+      // stable versions get `latest` (tag stays undefined).
+      tag = prereleaseDistTag(versionToPublish);
       if (isPublished(name, versionToPublish)) {
         skipReason = 'already published';
       }

package/src/cli/completion.ts

@@ -31,6 +31,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'audit',
       'backup',
       'capability',
+      'dns',
       'completion',
       'events',
       'help',
@@ -53,6 +54,11 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   const command = args[0];
 
+  // DNS subcommands
+  if (command === 'dns' && currentIndex === 1) {
+    return filterSuggestions(['registrations'], args[1] || '');
+  }
+
   // Capability subcommands
   if (command === 'capability' && currentIndex === 1) {
     const subcommands = ['list', 'info'];