@celilo/cli 0.1.5 → 0.1.7

package/src/services/update/orchestrator.ts

@@ -0,0 +1,359 @@
+/**
+ * System update orchestrator (CELILO_UPDATE Phase 4).
+ *
+ * Walks the dependency graph in topological order (providers first)
+ * and drives each drifting module through:
+ *
+ *     pending → backup → upgrade → deploy → health → done | failed | skipped
+ *
+ * Failure handling per D3: when a provider fails, downstream consumers
+ * are checked against the *running* provider's `provides[X].version`
+ * — if the consumer's new manifest can be satisfied by the running
+ * version, the consumer proceeds; otherwise it's skipped with a
+ * clear "blocked by old provider X@<v>" reason.
+ *
+ * Every operation that can fail or take time is dependency-injected
+ * (backup, upgrade, deploy, health). The orchestrator stays a pure
+ * state machine the unit tests can drive without touching disk or
+ * the network.
+ */
+
+import { runAudit } from '../audit';
+import type { AuditDeps, SystemAuditReport } from '../audit';
+import {
+  type ModuleGraph,
+  type ModuleId,
+  topologicalOrder,
+  transitiveConsumers,
+} from './dep-graph';
+import type { ProgressEmitter } from './progress';
+import type { SelfUpdateDeps } from './self-update';
+import { performSelfUpdate } from './self-update';
+import type { ModuleUpdateState, SelfUpdateResult, SystemUpdateResult, UpdateStep } from './types';
+
+export interface ModuleSnapshot {
+  id: string;
+  /** Currently installed version (from DB). */
+  installedVersion: string;
+  /** Latest version available in the registry (or null if not in registry). */
+  latestVersion: string | null;
+  /**
+   * Capability versions the *currently installed* manifest provides,
+   * keyed by capability name. Used by the version-aware skip logic.
+   */
+  installedProvides: Record<string, string>;
+  /**
+   * Capability versions the *new* manifest (latest registry version)
+   * requires. Used by the version-aware skip logic.
+   */
+  pendingRequires: Record<string, string>;
+}
+
+export interface OrchestratorOps {
+  /** Take a pre-update backup for a module. Returns ok/error. */
+  backup: (moduleId: string, updateId: string) => Promise<{ ok: boolean; error?: string }>;
+  /** Pull a newer version from the registry, write code/manifest, preserve state. */
+  upgrade: (moduleId: string) => Promise<{ ok: boolean; error?: string }>;
+  /** Re-converge the deployed instance (terraform apply + ansible). */
+  deploy: (moduleId: string) => Promise<{ ok: boolean; error?: string }>;
+  /** Run the module's health_check hook, report status. */
+  health: (moduleId: string) => Promise<{
+    status: 'healthy' | 'degraded' | 'unhealthy' | 'no-checks' | 'error';
+    detail?: string;
+  }>;
+  /** Read the celilo DB into a single-file snapshot — the framework-state half of D7. */
+  snapshotCeliloDb: (updateId: string) => Promise<{ ok: boolean; error?: string }>;
+}
+
+export interface RunUpdateDeps {
+  audit: AuditDeps;
+  graph: ModuleGraph;
+  /** Map of moduleId → ModuleSnapshot for every module the orchestrator might touch. */
+  snapshots: Map<ModuleId, ModuleSnapshot>;
+  ops: OrchestratorOps;
+  selfUpdate: SelfUpdateDeps;
+  /** ID generator — defaults to crypto.randomUUID. Tests inject a fixed value. */
+  idGen?: () => string;
+  /** Clock — defaults to `() => new Date()`. */
+  now?: () => Date;
+  /** Progress callback for live UI / test capture. */
+  progress: ProgressEmitter;
+  /** When true, skip backups and the celilo-db snapshot. Confirmed at the CLI layer. */
+  noBackup?: boolean;
+  /** When true, allow destructive terraform plans through (D6). */
+  allowDestructive?: boolean;
+  /** Restrict the run to one module + its dependencies. */
+  onlyModule?: string;
+}
+
+const VERSION_MAJOR_RE = /^v?(\d+)/;
+
+function majorOf(version: string): number {
+  const m = version.match(VERSION_MAJOR_RE);
+  return m ? Number.parseInt(m[1], 10) : 0;
+}
+
+/**
+ * Decide whether a consumer's pending upgrade can proceed given the
+ * provider's current (still-installed) version.
+ *
+ * Returns null if compatible (proceed); otherwise returns the reason
+ * the consumer should be skipped.
+ */
+export function consumerSkipReason(
+  consumer: ModuleSnapshot,
+  failedProvider: ModuleSnapshot,
+  graph: ModuleGraph,
+): string | null {
+  // Find which capabilities the consumer requires from the failed provider.
+  const sharedCaps: string[] = [];
+  for (const [cap, requiredVersion] of Object.entries(consumer.pendingRequires)) {
+    const providerCurrentVersion = failedProvider.installedProvides[cap];
+    if (providerCurrentVersion === undefined) continue; // not a shared cap
+    sharedCaps.push(cap);
+
+    const requiredMajor = majorOf(requiredVersion);
+    const providerMajor = majorOf(providerCurrentVersion);
+    if (requiredMajor !== providerMajor) {
+      return `blocked by ${failedProvider.id}@${failedProvider.installedVersion}: ${cap}@${providerCurrentVersion} doesn't satisfy ${cap}@${requiredVersion}`;
+    }
+  }
+
+  // No shared capability between this consumer and the failed provider —
+  // the dep-graph has them connected for some other capability that
+  // didn't appear in `pendingRequires`. Be conservative: skip.
+  if (sharedCaps.length === 0) {
+    // We only got here because the dep-graph said `consumer → provider`,
+    // so SOMETHING ties them. If pendingRequires doesn't include that
+    // capability, treat as blocked (we can't reason about compatibility).
+    void graph;
+    return `blocked by ${failedProvider.id}: cannot verify compatibility`;
+  }
+
+  return null; // compatible; consumer can proceed against still-installed provider
+}
+
+/**
+ * Drive a single module through the state machine. Stops at the first
+ * failed step.
+ */
+async function runModule(
+  moduleId: string,
+  snap: ModuleSnapshot,
+  deps: RunUpdateDeps,
+  updateId: string,
+): Promise<ModuleUpdateState> {
+  const startedAt = (deps.now ?? (() => new Date()))().toISOString();
+  const fromVersion = snap.installedVersion;
+  const toVersion = snap.latestVersion ?? fromVersion;
+
+  deps.progress.emit({ kind: 'module-start', moduleId, fromVersion, toVersion });
+
+  const finishWith = (
+    step: UpdateStep,
+    extra: { error?: string; skipReason?: string } = {},
+  ): ModuleUpdateState => {
+    const finishedAt = (deps.now ?? (() => new Date()))().toISOString();
+    const state: ModuleUpdateState = {
+      moduleId,
+      fromVersion,
+      toVersion,
+      step,
+      startedAt,
+      finishedAt,
+      ...extra,
+    };
+    if (step === 'failed') deps.progress.emit({ kind: 'module-failed', state });
+    else if (step === 'skipped') deps.progress.emit({ kind: 'module-skipped', state });
+    else deps.progress.emit({ kind: 'module-done', state });
+    return state;
+  };
+
+  // 1. backup (per-module)
+  if (!deps.noBackup) {
+    deps.progress.emit({ kind: 'module-step', moduleId, step: 'backup' });
+    const r = await deps.ops.backup(moduleId, updateId);
+    if (!r.ok) {
+      return finishWith('failed', { error: `backup: ${r.error ?? 'unknown'}` });
+    }
+  }
+
+  // 2. upgrade
+  if (snap.latestVersion && snap.latestVersion !== snap.installedVersion) {
+    deps.progress.emit({ kind: 'module-step', moduleId, step: 'upgrade' });
+    const r = await deps.ops.upgrade(moduleId);
+    if (!r.ok) {
+      return finishWith('failed', { error: `upgrade: ${r.error ?? 'unknown'}` });
+    }
+  }
+
+  // 3. deploy
+  deps.progress.emit({ kind: 'module-step', moduleId, step: 'deploy' });
+  const dr = await deps.ops.deploy(moduleId);
+  if (!dr.ok) {
+    return finishWith('failed', { error: `deploy: ${dr.error ?? 'unknown'}` });
+  }
+
+  // 4. health
+  deps.progress.emit({ kind: 'module-step', moduleId, step: 'health' });
+  const hr = await deps.ops.health(moduleId);
+  if (hr.status === 'unhealthy' || hr.status === 'error') {
+    return finishWith('failed', {
+      error: `health: ${hr.status}${hr.detail ? ` (${hr.detail})` : ''}`,
+    });
+  }
+
+  return finishWith('done');
+}
+
+/**
+ * Top-level update flow.
+ */
+export async function runSystemUpdate(deps: RunUpdateDeps): Promise<SystemUpdateResult> {
+  const idGen = deps.idGen ?? (() => crypto.randomUUID());
+  const now = deps.now ?? (() => new Date());
+  const updateId = idGen();
+  const startedAt = now().toISOString();
+  const states: ModuleUpdateState[] = [];
+
+  deps.progress.emit({ kind: 'plan', modules: deps.snapshots.size });
+
+  // Audit first; bail if BLOCKED.
+  const audit: SystemAuditReport = await runAudit(deps.audit);
+  if (audit.verdict === 'BLOCKED') {
+    return {
+      version: 1,
+      updateId,
+      startedAt,
+      finishedAt: now().toISOString(),
+      audit,
+      selfUpdate: { performed: false, reason: 'no-network' },
+      backupsCreated: false,
+      modules: [],
+      ok: false,
+    };
+  }
+
+  // Self-update.
+  deps.progress.emit({ kind: 'self-update-start' });
+  let selfUpdate: SelfUpdateResult;
+  try {
+    selfUpdate = await performSelfUpdate(deps.selfUpdate);
+  } catch (err) {
+    deps.progress.emit({
+      kind: 'self-update-skipped',
+      reason: err instanceof Error ? err.message : String(err),
+    });
+    return {
+      version: 1,
+      updateId,
+      startedAt,
+      finishedAt: now().toISOString(),
+      audit,
+      selfUpdate: { performed: false, reason: 'no-network' },
+      backupsCreated: false,
+      modules: [],
+      ok: false,
+    };
+  }
+  if (selfUpdate.performed) {
+    deps.progress.emit({
+      kind: 'self-update-done',
+      from: selfUpdate.from,
+      to: selfUpdate.to,
+    });
+  } else {
+    deps.progress.emit({ kind: 'self-update-skipped', reason: selfUpdate.reason });
+  }
+
+  // celilo-db snapshot (D7).
+  let backupsCreated = false;
+  if (!deps.noBackup) {
+    const r = await deps.ops.snapshotCeliloDb(updateId);
+    if (!r.ok) {
+      // DB snapshot is the safety net for this whole run; if we can't
+      // take it, refuse to mutate.
+      return {
+        version: 1,
+        updateId,
+        startedAt,
+        finishedAt: now().toISOString(),
+        audit,
+        selfUpdate,
+        backupsCreated: false,
+        modules: [],
+        ok: false,
+      };
+    }
+    backupsCreated = true;
+  }
+
+  // Walk modules in topological order.
+  const order = topologicalOrder(deps.graph);
+  const failed = new Map<ModuleId, ModuleUpdateState>();
+
+  for (const moduleId of order) {
+    if (deps.onlyModule && deps.onlyModule !== moduleId) {
+      // Allow dependencies of `onlyModule` to be considered later if needed,
+      // but for V1 the simple case is "just this one module".
+      continue;
+    }
+
+    const snap = deps.snapshots.get(moduleId);
+    if (!snap) continue; // no snapshot → not currently installed → skip
+
+    // Check upstream failures first.
+    const upstreamProviders = [...(deps.graph.edges.get(moduleId) ?? [])];
+    const blockingProvider = upstreamProviders
+      .map((id) => failed.get(id))
+      .find((s): s is ModuleUpdateState => s !== undefined);
+
+    if (blockingProvider) {
+      const failedSnap = deps.snapshots.get(blockingProvider.moduleId);
+      const reason = failedSnap
+        ? consumerSkipReason(snap, failedSnap, deps.graph)
+        : `blocked by ${blockingProvider.moduleId}: snapshot missing`;
+      if (reason) {
+        const state: ModuleUpdateState = {
+          moduleId,
+          fromVersion: snap.installedVersion,
+          toVersion: snap.latestVersion ?? snap.installedVersion,
+          step: 'skipped',
+          skipReason: reason,
+          startedAt: now().toISOString(),
+          finishedAt: now().toISOString(),
+        };
+        deps.progress.emit({ kind: 'module-skipped', state });
+        states.push(state);
+        // Also propagate blockage to consumers of *this* skipped module.
+        for (const id of transitiveConsumers(deps.graph, moduleId)) {
+          if (!failed.has(id)) failed.set(id, state);
+        }
+        failed.set(moduleId, state);
+        continue;
+      }
+      // version-compatible: proceed.
+    }
+
+    const state = await runModule(moduleId, snap, deps, updateId);
+    states.push(state);
+    if (state.step === 'failed') {
+      failed.set(moduleId, state);
+    }
+  }
+
+  const ok = states.every((s) => s.step === 'done' || s.step === 'pending');
+  deps.progress.emit({ kind: 'run-done', ok });
+
+  return {
+    version: 1,
+    updateId,
+    startedAt,
+    finishedAt: now().toISOString(),
+    audit,
+    selfUpdate,
+    backupsCreated,
+    modules: states,
+    ok,
+  };
+}

package/src/services/update/progress.ts

@@ -0,0 +1,49 @@
+/**
+ * Progress emitter for the orchestrator.
+ *
+ * The CLI prints live status as the orchestrator walks each module
+ * through its state machine; tests use a capturing emitter to assert
+ * on exactly which events fired in which order. Same shape as the
+ * `[progress:start] / [progress:done]` pattern in
+ * `packages/e2e/src/runner.ts`.
+ */
+
+import type { ModuleUpdateState, UpdateStep } from './types';
+
+export type ProgressEvent =
+  | { kind: 'plan'; modules: number }
+  | { kind: 'self-update-start' }
+  | { kind: 'self-update-done'; from: string; to: string }
+  | { kind: 'self-update-skipped'; reason: string }
+  | { kind: 'backup-start'; moduleId: string }
+  | { kind: 'backup-done'; moduleId: string }
+  | { kind: 'module-start'; moduleId: string; fromVersion: string; toVersion: string }
+  | { kind: 'module-step'; moduleId: string; step: UpdateStep }
+  | { kind: 'module-done'; state: ModuleUpdateState }
+  | { kind: 'module-failed'; state: ModuleUpdateState }
+  | { kind: 'module-skipped'; state: ModuleUpdateState }
+  | { kind: 'run-done'; ok: boolean };
+
+export interface ProgressEmitter {
+  emit(event: ProgressEvent): void;
+}
+
+/** Default emitter — silent. Override for live console output. */
+export const silentProgress: ProgressEmitter = {
+  emit() {},
+};
+
+export interface CapturingEmitter extends ProgressEmitter {
+  events: ProgressEvent[];
+}
+
+/** Test helper: collect every event in `events` for later assertion. */
+export function capturingProgress(): CapturingEmitter {
+  const events: ProgressEvent[] = [];
+  return {
+    events,
+    emit(event) {
+      events.push(event);
+    },
+  };
+}

package/src/services/update/self-update.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+import { performSelfUpdate } from './self-update';
+
+const okUpdater = async () => ({ ok: true, stderr: '' });
+const failUpdater = async () => ({ ok: false, stderr: 'EACCES on /usr/local' });
+
+describe('performSelfUpdate', () => {
+  test('skips when devMode flag is set', async () => {
+    const result = await performSelfUpdate({
+      installedVersion: '0.0.1',
+      fetcher: async () => '99.0.0',
+      updater: okUpdater,
+      devMode: true,
+    });
+    expect(result).toEqual({ performed: false, reason: 'dev-mode' });
+  });
+
+  test('skips when fetcher returns null (no network)', async () => {
+    const result = await performSelfUpdate({
+      installedVersion: '0.1.5',
+      fetcher: async () => null,
+      updater: okUpdater,
+    });
+    expect(result).toEqual({ performed: false, reason: 'no-network' });
+  });
+
+  test('skips when running version >= latest', async () => {
+    const result = await performSelfUpdate({
+      installedVersion: '0.1.5',
+      fetcher: async () => '0.1.5',
+      updater: okUpdater,
+    });
+    expect(result).toEqual({ performed: false, reason: 'already-current' });
+  });
+
+  test('skips when running version is ahead of latest (dev build)', async () => {
+    const result = await performSelfUpdate({
+      installedVersion: '0.2.0',
+      fetcher: async () => '0.1.7',
+      updater: okUpdater,
+    });
+    expect(result).toEqual({ performed: false, reason: 'already-current' });
+  });
+
+  test('runs the updater and returns from/to when newer is available', async () => {
+    let updaterCalled = false;
+    const result = await performSelfUpdate({
+      installedVersion: '0.1.5',
+      fetcher: async () => '0.1.7',
+      updater: async () => {
+        updaterCalled = true;
+        return { ok: true, stderr: '' };
+      },
+    });
+    expect(updaterCalled).toBe(true);
+    expect(result).toEqual({ performed: true, from: '0.1.5', to: '0.1.7' });
+  });
+
+  test('throws with stderr when the updater fails', async () => {
+    await expect(
+      performSelfUpdate({
+        installedVersion: '0.1.5',
+        fetcher: async () => '0.1.7',
+        updater: failUpdater,
+      }),
+    ).rejects.toThrow(/bun update failed: EACCES on \/usr\/local/);
+  });
+});

package/src/services/update/self-update.ts

@@ -0,0 +1,57 @@
+/**
+ * CLI self-update — the first step of `celilo system update` per
+ * CELILO_UPDATE D2.
+ *
+ * Compares the running CLI version against the latest published
+ * `@celilo/cli` on npm and runs `bun update -g @celilo/cli` if newer.
+ * On success the caller re-execs with the new binary so subsequent
+ * module work uses the new code.
+ *
+ * Both the version-check and the bun-update invocation are
+ * dependency-injected so the orchestrator can be tested against
+ * canned responses without touching npm or the running shell.
+ */
+
+import { compareSemver } from '../audit/cli-version';
+import type { SelfUpdateResult } from './types';
+
+export type CliVersionFetcher = () => Promise<string | null>;
+export type CliUpdater = () => Promise<{ ok: boolean; stderr: string }>;
+
+export interface SelfUpdateDeps {
+  /** Currently running CLI version (read from package.json). */
+  installedVersion: string;
+  /** Resolves the latest @celilo/cli on npm; returns null on transport failure. */
+  fetcher: CliVersionFetcher;
+  /** Runs `bun update -g @celilo/cli` (or equivalent). */
+  updater: CliUpdater;
+  /**
+   * If true, skip self-update entirely. Set when `system update`
+   * detects the CLI is running from local source (cele2e dev loop)
+   * — there's nothing to update against and any npm install would
+   * step on the mounted source tree.
+   */
+  devMode?: boolean;
+}
+
+export async function performSelfUpdate(deps: SelfUpdateDeps): Promise<SelfUpdateResult> {
+  if (deps.devMode) {
+    return { performed: false, reason: 'dev-mode' };
+  }
+
+  const latest = await deps.fetcher();
+  if (latest === null) {
+    return { performed: false, reason: 'no-network' };
+  }
+
+  if (compareSemver(deps.installedVersion, latest) >= 0) {
+    return { performed: false, reason: 'already-current' };
+  }
+
+  const result = await deps.updater();
+  if (!result.ok) {
+    throw new Error(`bun update failed: ${result.stderr || 'unknown error'}`);
+  }
+
+  return { performed: true, from: deps.installedVersion, to: latest };
+}

package/src/services/update/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Types for the system update orchestrator (CELILO_UPDATE Phase 4).
+ *
+ * The orchestrator's job is to take a `SystemAuditReport` plus a
+ * dependency graph and walk every drifting module through a small
+ * state machine: backup → upgrade → deploy → health-check. Each
+ * module's outcome is recorded as a `ModuleUpdateState`; the
+ * aggregate is reported as a `SystemUpdateResult`.
+ *
+ * Stable JSON-friendly shapes — version-bumped if the schema
+ * changes incompatibly.
+ */
+
+import type { SystemAuditReport } from '../audit';
+
+/** Per-module step in the update state machine. */
+export type UpdateStep =
+  | 'pending'
+  | 'backup'
+  | 'upgrade'
+  | 'deploy'
+  | 'health'
+  | 'done'
+  | 'failed'
+  | 'skipped';
+
+export interface ModuleUpdateState {
+  moduleId: string;
+  /** Version installed at the start of the run. */
+  fromVersion: string;
+  /** Version we're attempting to upgrade to (may equal `fromVersion` if no version drift, but other drift triggered the update). */
+  toVersion: string;
+  /** Where the state machine stopped. */
+  step: UpdateStep;
+  /** Step-specific error message (if `step === 'failed'`). */
+  error?: string;
+  /** Reason for skip (if `step === 'skipped'`), e.g., "blocked by old provider X@Y". */
+  skipReason?: string;
+  /** ISO timestamp when this module's run started. */
+  startedAt?: string;
+  /** ISO timestamp when this module's run finished. */
+  finishedAt?: string;
+}
+
+export type SelfUpdateResult =
+  | { performed: false; reason: 'already-current' | 'dev-mode' | 'no-network' }
+  | { performed: true; from: string; to: string };
+
+export interface SystemUpdateResult {
+  version: 1;
+  /** Run identifier — same uuid that ties together all the pre-update backups. */
+  updateId: string;
+  startedAt: string;
+  finishedAt: string;
+  /** The audit that drove this run. Carried through so the JSON output is self-contained. */
+  audit: SystemAuditReport;
+  /** CLI self-update outcome. */
+  selfUpdate: SelfUpdateResult;
+  /**
+   * Whether per-module backups were created. False on `--no-backup` runs
+   * (the user accepted the rollback risk).
+   */
+  backupsCreated: boolean;
+  /** Per-module results, in the order the orchestrator walked them. */
+  modules: ModuleUpdateState[];
+  /** True iff every module reached `done` (or had nothing to do). */
+  ok: boolean;
+}
+
+/**
+ * Non-destructive preview produced by `system update --dry-run`.
+ * Describes what the orchestrator *would* do without running anything.
+ */
+export interface UpdatePlan {
+  version: 1;
+  updateId: string;
+  audit: SystemAuditReport;
+  /** Whether the CLI would self-update before module work. */
+  willSelfUpdate: boolean;
+  selfUpdateFromVersion?: string;
+  selfUpdateToVersion?: string;
+  /** Modules that will be upgraded, in topological order. */
+  modules: Array<{
+    moduleId: string;
+    fromVersion: string;
+    toVersion: string;
+    /** Capability provider this module depends on, for the tree rendering. */
+    dependsOn: string[];
+  }>;
+  /** Whether backups will be taken before mutations. */
+  willBackup: boolean;
+  /** Whether the destructive-terraform gate is in effect. */
+  destructiveTerraformBlocked: boolean;
+}

package/src/templates/generator.test.ts

@@ -565,7 +565,7 @@ resource "proxmox_lxc" "container" {
         expect(hostsIni).toContain('ansible_host=192.168.0.100'); // Machine IP
         expect(hostsIni).toContain('ansible_user=root'); // Machine SSH user
         expect(hostsIni).toContain('ansible_ssh_private_key_file='); // SSH key path
-        expect(hostsIni).toContain('/tmp/ansible-keys/machine-machine-1.key'); // Key filename
+        expect(hostsIni).toContain('celilo-ansible-keys/machine-machine-1.key'); // Key filename
       }
     });