@celilo/cli 0.3.30 → 0.4.0-alpha.0

package/src/cli/commands/restore.ts

@@ -0,0 +1,126 @@
+/**
+ * Top-level `celilo restore` command.
+ *
+ * Wraps the file-direct restore service for the fresh-bootstrap
+ * ergonomics path:
+ *
+ *   curl -fsSL https://celilo.computer/bootstrap.sh | bash
+ *   celilo restore --from <file> [--force]
+ *
+ * Refuses to run when the target already holds celilo state (modules
+ * in DB or terraform state on disk) unless --force is passed.
+ * Calls restoreFromArtifactFile, then runs Drizzle migrations on the
+ * restored DB so a backup from an older celilo still opens cleanly.
+ *
+ * Phase 4 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { migrateRestoredDb, restoreFromArtifactFile } from '../../services/restore-from-file';
+import {
+  NonEmptyRestoreTargetError,
+  assertRestoreTargetEmpty,
+} from '../../services/restore-preflight';
+import { getArg, hasFlag } from '../parser';
+import { log } from '../prompts';
+import type { CommandResult } from '../types';
+
+export async function handleRestore(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
+  // --from is required; we don't infer it.
+  const fromFlag = flags.from;
+  const fromPositional = getArg(args, 0);
+  const fromRaw = typeof fromFlag === 'string' ? fromFlag : fromPositional;
+
+  if (!fromRaw || typeof fromRaw !== 'string') {
+    return {
+      success: false,
+      error: [
+        'celilo restore: missing --from <file>',
+        '',
+        'Usage:',
+        '  celilo restore --from <path-to-artifact> [--force]',
+        '',
+        'The artifact is a .backup file produced by `celilo module backup celilo-mgmt`.',
+      ].join('\n'),
+    };
+  }
+
+  const filePath = resolve(fromRaw);
+  if (!existsSync(filePath)) {
+    return {
+      success: false,
+      error: `Artifact not found: ${filePath}`,
+    };
+  }
+
+  const force = hasFlag(flags, 'force');
+
+  // Pre-flight: refuse non-empty target unless --force.
+  if (!force) {
+    try {
+      assertRestoreTargetEmpty();
+    } catch (err) {
+      if (err instanceof NonEmptyRestoreTargetError) {
+        return { success: false, error: err.message };
+      }
+      throw err;
+    }
+  } else {
+    log.warn('--force set; non-destructive pre-flight skipped.');
+  }
+
+  log.info(`Restoring from ${filePath}...`);
+  const result = await restoreFromArtifactFile(filePath, { force });
+
+  if (!result.success) {
+    return { success: false, error: result.error ?? 'restore failed' };
+  }
+
+  // Run Drizzle migrations on the restored DB so a backup from an
+  // older celilo opens cleanly. No-op if the DB schema is already
+  // current. Best-effort: if migrations fail (e.g., a destructive
+  // backward migration would be needed), surface the error but the
+  // restore itself already landed.
+  try {
+    await migrateRestoredDb();
+  } catch (err) {
+    log.warn(
+      `Restore complete but migrations failed: ${err instanceof Error ? err.message : String(err)}. The restored DB may need manual migration.`,
+    );
+  }
+
+  // Build the success message.
+  const lines: string[] = ['Restore complete.'];
+  if (result.systemDbApplied) lines.push('  • celilo.db swapped into place');
+  if (result.masterKeyApplied) lines.push('  • master.key swapped into place');
+  if (result.sshKeyApplied) lines.push('  • fleet SSH key restored to <data-dir>/.ssh/');
+  if (result.crossModuleApplied && result.crossModuleApplied.length > 0) {
+    lines.push(
+      `  • terraform state restored for ${result.crossModuleApplied.length} module(s): ${result.crossModuleApplied.join(', ')}`,
+    );
+  }
+  lines.push('');
+  lines.push('Next steps:');
+  lines.push('  • Verify with `celilo module list` and `celilo status`.');
+  lines.push("  • Run `terraform plan` in each module's generated/ dir to confirm no drift.");
+  // The restore swapped the DB file; the CLI's own connection was closed
+  // and reopens fresh, but a long-running event-bus dispatcher (if you
+  // installed one via `celilo events install-daemon`) still holds the old
+  // DB. Tell the operator to bounce it — celilo doesn't manage that user
+  // unit's lifecycle from here.
+  lines.push(
+    '  • If you run the event-bus daemon (`celilo events install-daemon`), restart it so it',
+  );
+  lines.push(
+    '    picks up the restored DB:  systemctl --user restart celilo-events.service  (Linux).',
+  );
+
+  return {
+    success: true,
+    message: lines.join('\n'),
+  };
+}

package/src/cli/commands/storage-add-local.ts

@@ -160,7 +160,7 @@ export async function handleStorageAddLocal(
     }
 
     celiloOutro(
-      `Storage '${storage.storageId}' (${name}) added and verified!\n\nStorage ID: ${storage.storageId}\nPath: ${resolvedPath}\n\nNext steps:\n  celilo backup create              Create a backup\n  celilo storage list               List storage destinations`,
+      `Storage '${storage.storageId}' (${name}) added and verified!\n\nStorage ID: ${storage.storageId}\nPath: ${resolvedPath}\n\nNext steps:\n  celilo module backup <module-id>  Create a backup\n  celilo storage list               List storage destinations`,
     );
 
     return { success: true, message: `Added local storage: ${storage.storageId}` };

package/src/cli/commands/storage-add-s3.ts

@@ -101,7 +101,7 @@ export async function handleStorageAddS3(
     }
 
     celiloOutro(
-      `Storage '${storage.storageId}' (${name}) added and verified!\n\nStorage ID: ${storage.storageId}\nBucket: ${bucket}\nEndpoint: ${endpoint}\n\nNext steps:\n  celilo backup create              Create a backup\n  celilo storage list               List storage destinations`,
+      `Storage '${storage.storageId}' (${name}) added and verified!\n\nStorage ID: ${storage.storageId}\nBucket: ${bucket}\nEndpoint: ${endpoint}\n\nNext steps:\n  celilo module backup <module-id>  Create a backup\n  celilo storage list               List storage destinations`,
     );
 
     return { success: true, message: `Added S3 storage: ${storage.storageId}` };

package/src/cli/commands/subscribers-add.ts

@@ -0,0 +1,68 @@
+/**
+ * `celilo subscribers add <url> --secret <s> [--name <n>] [--registry <r>] [--tag <t>] [--package-pattern <p>]`
+ *
+ * Append (or replace, on URL collision) a subscriber in the static
+ * subscriber-config file. The secret is required — there's no way
+ * to add an unsigned subscriber. Match fields are all optional;
+ * omitting them means "match every event."
+ */
+
+import type { Subscriber } from '@celilo/event-bus/build-bus';
+import { addSubscriber, subscriberStorePath } from '../../services/build-bus';
+import type { CommandResult } from '../types';
+
+export function handleSubscribersAdd(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): CommandResult {
+  const url = args[0];
+  if (!url) {
+    return {
+      success: false,
+      error:
+        'Subscriber URL required.\n\nUsage:\n  celilo subscribers add <url> --secret <secret> [options]',
+    };
+  }
+  const secret = flags.secret;
+  if (typeof secret !== 'string' || !secret) {
+    return {
+      success: false,
+      error: '--secret <hmac-secret> is required.',
+    };
+  }
+
+  if (!/^https?:\/\//.test(url)) {
+    return {
+      success: false,
+      error: `Subscriber URL must start with http:// or https:// (got "${url}").`,
+    };
+  }
+
+  const subscriber: Subscriber = {
+    url,
+    secret,
+    match: {},
+  };
+  if (typeof flags.name === 'string') subscriber.name = flags.name;
+  if (typeof flags.registry === 'string') subscriber.match.registry = flags.registry;
+  if (typeof flags.tag === 'string') subscriber.match.tag = flags.tag;
+  if (typeof flags['package-pattern'] === 'string') {
+    subscriber.match.packagePattern = flags['package-pattern'];
+  }
+
+  let result: ReturnType<typeof addSubscriber>;
+  try {
+    result = addSubscriber(subscriber);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Could not save subscriber: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const verb = result.replaced ? 'Updated' : 'Added';
+  return {
+    success: true,
+    message: `${verb} subscriber ${subscriber.name ?? subscriber.url}.\n\nStore: ${subscriberStorePath()}`,
+  };
+}

package/src/cli/commands/subscribers-list.ts

@@ -0,0 +1,48 @@
+/**
+ * `celilo subscribers list` — show registered build-bus subscribers.
+ *
+ * Reads the static-config subscriber list ([[v2/BUILD_BUS.md]] Phase
+ * 2-lite — registry-server switchboard is deferred). Doesn't print
+ * the HMAC secret in cleartext — only a truncated hash so operators
+ * can disambiguate subscribers without leaking credentials into
+ * terminal history.
+ */
+
+import { createHash } from 'node:crypto';
+import { loadSubscribers, subscriberStorePath } from '../../services/build-bus';
+import type { CommandResult } from '../types';
+
+export function handleSubscribersList(): CommandResult {
+  let subscribers: ReturnType<typeof loadSubscribers>;
+  try {
+    subscribers = loadSubscribers();
+  } catch (err) {
+    return {
+      success: false,
+      error: `Could not load subscribers: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (subscribers.length === 0) {
+    return {
+      success: true,
+      message: `No subscribers configured.\n\nStore: ${subscriberStorePath()}\nAdd one with: celilo subscribers add <url> --secret <secret>`,
+    };
+  }
+
+  const lines: string[] = [`Subscribers (${subscribers.length}) — ${subscriberStorePath()}`, ''];
+  for (const s of subscribers) {
+    const fingerprint = createHash('sha256').update(s.secret).digest('hex').slice(0, 8);
+    const label = s.name ? `${s.name} <${s.url}>` : s.url;
+    lines.push(`  ${label}`);
+    lines.push(`    secret fingerprint: ${fingerprint}…`);
+    const matchParts: string[] = [];
+    if (s.match.registry) matchParts.push(`registry=${s.match.registry}`);
+    if (s.match.tag) matchParts.push(`tag=${s.match.tag}`);
+    if (s.match.packagePattern) matchParts.push(`pkg=${s.match.packagePattern}`);
+    lines.push(`    match: ${matchParts.length > 0 ? matchParts.join(', ') : '(any event)'}`);
+    lines.push('');
+  }
+
+  return { success: true, message: lines.join('\n').trim() };
+}

package/src/cli/commands/subscribers-remove.ts

@@ -0,0 +1,38 @@
+/**
+ * `celilo subscribers remove <url>` — remove a subscriber by URL.
+ */
+
+import { removeSubscriberByUrl, subscriberStorePath } from '../../services/build-bus';
+import type { CommandResult } from '../types';
+
+export function handleSubscribersRemove(args: string[]): CommandResult {
+  const url = args[0];
+  if (!url) {
+    return {
+      success: false,
+      error: 'Subscriber URL required.\n\nUsage:\n  celilo subscribers remove <url>',
+    };
+  }
+
+  let removed: ReturnType<typeof removeSubscriberByUrl>;
+  try {
+    removed = removeSubscriberByUrl(url);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Could not update subscriber store: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (!removed) {
+    return {
+      success: false,
+      error: `No subscriber found with URL "${url}".\n\nStore: ${subscriberStorePath()}\nList current subscribers with: celilo subscribers list`,
+    };
+  }
+
+  return {
+    success: true,
+    message: `Removed subscriber ${removed.name ?? removed.url}.`,
+  };
+}

package/src/cli/commands/subscribers-serve.ts

@@ -0,0 +1,77 @@
+/**
+ * `celilo subscribers serve --port <p> --secret <s>` — long-running
+ * HTTP receiver for build-bus webhooks.
+ *
+ * Verifies signed envelopes against the configured shared secret
+ * and emits a `build-bus.publish` event onto the local SQLite bus
+ * for every verified delivery. Phase 4's hook dispatcher (also
+ * started by this command when --dispatch is set) picks up those
+ * local events and runs module-side `on_upstream_publish` hooks.
+ *
+ * Designed to run under systemd / launchd; blocks indefinitely
+ * until killed.
+ */
+
+import { startHookDispatcher } from '../../services/build-bus/hook-dispatcher';
+import { startReceiverServer } from '../../services/build-bus/receiver-server';
+import type { CommandResult } from '../types';
+
+export async function handleSubscribersServe(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const port = typeof flags.port === 'string' ? Number.parseInt(flags.port, 10) : 8123;
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    return {
+      success: false,
+      error: `Invalid --port value: ${flags.port}. Must be 1–65535.`,
+    };
+  }
+  const secret = flags.secret;
+  if (typeof secret !== 'string' || !secret) {
+    return {
+      success: false,
+      error: '--secret <shared-hmac-secret> is required.',
+    };
+  }
+
+  // When --dispatch is set (default), this process also runs the
+  // hook dispatcher on the same bus. Operators can pass --no-dispatch
+  // to run the receiver alone (e.g. when the dispatcher already runs
+  // in another process).
+  const wantsDispatch = flags['no-dispatch'] !== true;
+
+  const dispatcher = wantsDispatch ? await startHookDispatcher() : null;
+  const server = startReceiverServer({
+    port,
+    secret,
+    onEvent: dispatcher
+      ? async (envelope) => {
+          // handleEvent returns HookRunResult[]; the receiver's
+          // onEvent contract is void | Promise<void>. Discard the
+          // array — the dispatcher logs its own outcomes.
+          await dispatcher.handleEvent(envelope.event);
+        }
+      : undefined,
+  });
+
+  console.log(`✓ build-bus receiver listening on ${server.url}`);
+  console.log(`  dispatch: ${wantsDispatch ? 'enabled' : 'disabled'}`);
+  console.log(`  events emit to local bus as "build-bus.publish"`);
+  console.log('Ctrl-C to stop.');
+
+  // Graceful shutdown.
+  const stop = async (signal: string) => {
+    console.log(`\nReceived ${signal}; shutting down…`);
+    await server.stop();
+    if (dispatcher) await dispatcher.stop();
+    process.exit(0);
+  };
+  process.on('SIGINT', () => void stop('SIGINT'));
+  process.on('SIGTERM', () => void stop('SIGTERM'));
+
+  // Block indefinitely. The signal handlers exit the process.
+  await new Promise(() => {});
+  // Unreachable, but TypeScript wants a return.
+  return { success: true, message: '' };
+}

package/src/cli/commands/subscribers-status.ts

@@ -0,0 +1,33 @@
+/**
+ * `celilo subscribers status` — per-subscriber delivery summary.
+ *
+ * Reads recent `webhook.delivered` / `webhook.failed` events from
+ * the local SQLite bus, groups by subscriber URL, surfaces totals
+ * + success rate + last delivery + recent failures. Use after a
+ * publish run to see whether webhooks actually landed, or as the
+ * first stop when investigating a stuck propagation.
+ */
+
+import { formatStatus, loadSubscriberStatus } from '../../services/build-bus';
+import type { CommandResult } from '../types';
+
+export function handleSubscribersStatus(): CommandResult {
+  let items: ReturnType<typeof loadSubscriberStatus>;
+  try {
+    items = loadSubscriberStatus();
+  } catch (err) {
+    return {
+      success: false,
+      error: `Could not load subscriber status: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  if (items.length === 0) {
+    return {
+      success: true,
+      message:
+        'No subscribers configured.\n\nAdd one with: celilo subscribers add <url> --secret <secret>',
+    };
+  }
+  const header = `Subscriber status (${items.length})`;
+  return { success: true, message: `${header}\n\n${formatStatus(items)}` };
+}

package/src/cli/commands/subscribers-test.ts

@@ -0,0 +1,71 @@
+/**
+ * `celilo subscribers test <url>` — fire a synthetic build-bus event
+ * at the named subscriber, report delivery outcome.
+ *
+ * Useful for verifying that a freshly-added subscriber's secret +
+ * URL line up with what the receiver expects, without waiting for
+ * a real publish to fire the webhook.
+ */
+
+import {
+  eventsForPublished,
+  fanOut,
+  formatDeliveryResult,
+  loadSubscribers,
+} from '../../services/build-bus';
+import type { CommandResult } from '../types';
+
+export async function handleSubscribersTest(args: string[]): Promise<CommandResult> {
+  const url = args[0];
+  if (!url) {
+    return {
+      success: false,
+      error: 'Subscriber URL required.\n\nUsage:\n  celilo subscribers test <url>',
+    };
+  }
+
+  const subscribers = loadSubscribers();
+  const target = subscribers.find((s) => s.url === url);
+  if (!target) {
+    return {
+      success: false,
+      error: `No subscriber found with URL "${url}". List with: celilo subscribers list`,
+    };
+  }
+
+  // Synthetic event — uses a fixed test-token name so receivers can
+  // distinguish a probe from a real publish in their logs. Registry
+  // + tag match the target's expected filter when possible (so the
+  // event is actually delivered rather than getting filtered out).
+  const events = eventsForPublished({
+    published: [{ name: '@celilo-test/probe', version: '0.0.0' }],
+    tag: (target.match.tag as 'alpha' | 'latest' | undefined) ?? 'latest',
+    registry: target.match.registry ?? 'npm',
+  });
+
+  // We bypass the global subscriber list and deliver only to the
+  // chosen target — the test should always exercise the operator's
+  // exact subscriber, regardless of match filters.
+  const event = events[0];
+  const results = await fanOut(event, [{ ...target, match: {} }]);
+
+  const lines: string[] = [
+    'Synthetic event fired:',
+    '  package: @celilo-test/probe@0.0.0',
+    `  registry: ${event.registry}`,
+    `  tag: ${event.tag}`,
+    `  event-id: ${event.eventId}`,
+    '',
+    'Result:',
+    `  ${formatDeliveryResult(results[0])}`,
+  ];
+
+  return {
+    success: results[0].ok,
+    message: lines.join('\n'),
+    // CommandResult is success | error; we shoehorn the failure case
+    // into success: false with the same message. The CLI surface
+    // doesn't distinguish here — the test PRINTED its outcome.
+    error: results[0].ok ? undefined : `Delivery failed: ${results[0].error}`,
+  } as CommandResult;
+}

package/src/cli/commands/system-apply-config-equivalence.test.ts

@@ -0,0 +1,108 @@
+/**
+ * End-to-end equivalence test for v2/MANAGEMENT_AS_NETAPP.md Phase 2.
+ *
+ * The spec calls for "celilo system apply-config" to write the same
+ * systemConfig state that the legacy `celilo system init` produces,
+ * just without the operator-facing framing. This test runs both
+ * paths against a pair of isolated DBs and asserts the resulting
+ * systemConfig rows match.
+ *
+ * Catches the bug class where a future change to system-init (e.g.
+ * adding a side-effect or gateway computation) drifts away from
+ * what apply-config writes.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getDb } from '../../db/client';
+import { loadExistingConfiguration } from '../../services/system-init';
+import { handleSystemApplyConfig } from './system-apply-config';
+import { handleSystemInit } from './system-init';
+
+describe('system apply-config equivalence with system init --accept-defaults', () => {
+  let tmpDir: string;
+  let savedDbPath: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'celilo-apply-config-test-'));
+    savedDbPath = process.env.CELILO_DB_PATH;
+  });
+
+  afterEach(() => {
+    if (savedDbPath !== undefined) {
+      process.env.CELILO_DB_PATH = savedDbPath;
+    } else {
+      process.env.CELILO_DB_PATH = undefined;
+    }
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('apply-config writes the same systemConfig keys as system init --accept-defaults', async () => {
+    const overrides = [
+      'network.dmz.subnet=10.99.10.0/24',
+      'network.app.subnet=10.99.20.0/24',
+      'network.secure.subnet=10.99.30.0/24',
+      'network.internal.subnet=192.168.99.0/24',
+      'dns.primary=9.9.9.9',
+      'dns.fallback=1.1.1.1 8.8.8.8',
+      'ssh.public_key=ssh-ed25519 AAAA== test@equivalence',
+    ];
+
+    // Path A: legacy system init --accept-defaults.
+    process.env.CELILO_DB_PATH = join(tmpDir, 'a.db');
+    const aResult = await handleSystemInit(overrides, { 'accept-defaults': true });
+    expect(aResult.success).toBe(true);
+    const aSnapshot = loadExistingConfiguration(getDb());
+
+    // Path B: new apply-config.
+    process.env.CELILO_DB_PATH = join(tmpDir, 'b.db');
+    const bResult = await handleSystemApplyConfig(overrides);
+    expect(bResult.success).toBe(true);
+    const bSnapshot = loadExistingConfiguration(getDb());
+
+    // The two paths should write the same set of keys (gateways are
+    // auto-computed from subnets in both, since both go through
+    // initializeSystem) and the same values.
+    expect(Object.keys(bSnapshot).sort()).toEqual(Object.keys(aSnapshot).sort());
+    for (const key of Object.keys(aSnapshot)) {
+      expect({ key, value: bSnapshot[key] }).toEqual({ key, value: aSnapshot[key] });
+    }
+  });
+
+  test('apply-config refuses to run with no overrides (unlike init which has defaults)', async () => {
+    process.env.CELILO_DB_PATH = join(tmpDir, 'empty.db');
+    const result = await handleSystemApplyConfig([]);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('No config values supplied');
+    }
+  });
+
+  test('apply-config reports malformed positional args clearly', async () => {
+    process.env.CELILO_DB_PATH = join(tmpDir, 'bad.db');
+    const result = await handleSystemApplyConfig(['not-a-pair', 'dns.primary=1.1.1.1']);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('Expected key=value');
+      expect(result.error).toContain('not-a-pair');
+    }
+  });
+
+  test('apply-config writes report the number of values applied', async () => {
+    process.env.CELILO_DB_PATH = join(tmpDir, 'count.db');
+    const result = await handleSystemApplyConfig([
+      'dns.primary=1.1.1.1',
+      'network.dmz.subnet=10.0.10.0/24',
+    ]);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      // initializeSystem() merges with defaults + computed gateways,
+      // so the reported count is the FULL config size — not just our
+      // two overrides. The exact count depends on getDefaultConfiguration
+      // and any auto-computed gateways; assert it's at least 2.
+      expect(result.message).toMatch(/Applied \d+ config value\(s\)/);
+    }
+  });
+});

package/src/cli/commands/system-apply-config.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Unit tests for `celilo system apply-config`.
+ *
+ * The parser is pure (key=value handling); we test it directly. The
+ * actual DB write goes through `initializeSystem` which is already
+ * covered by system-init's tests — we just confirm apply-config's
+ * thin wrapper hands the right shape to it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { parseKeyValueArgs } from './system-apply-config';
+
+describe('parseKeyValueArgs', () => {
+  test('empty args → empty overrides + no errors', () => {
+    expect(parseKeyValueArgs([])).toEqual({ overrides: {}, errors: [] });
+  });
+
+  test('parses a single key=value', () => {
+    expect(parseKeyValueArgs(['network.dmz.subnet=10.0.10.0/24'])).toEqual({
+      overrides: { 'network.dmz.subnet': '10.0.10.0/24' },
+      errors: [],
+    });
+  });
+
+  test('parses multiple key=value pairs', () => {
+    const result = parseKeyValueArgs([
+      'network.dmz.subnet=10.0.10.0/24',
+      'dns.primary=1.1.1.1',
+      'dns.fallback=8.8.8.8 1.1.1.1',
+    ]);
+    expect(result.overrides).toEqual({
+      'network.dmz.subnet': '10.0.10.0/24',
+      'dns.primary': '1.1.1.1',
+      'dns.fallback': '8.8.8.8 1.1.1.1',
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  test('records error for positional without "="', () => {
+    const result = parseKeyValueArgs(['not-a-pair']);
+    expect(result.overrides).toEqual({});
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain('Expected key=value');
+  });
+
+  test('only-equal at index 0 is rejected (empty key)', () => {
+    // `=value` has eqIndex 0, which the parser rejects so we don't
+    // accept anonymous keys.
+    const result = parseKeyValueArgs(['=orphan']);
+    expect(result.errors).toHaveLength(1);
+  });
+
+  test('preserves values containing "=" (splits on first "=" only)', () => {
+    // SSH public keys end with `user@host`, but trailing `=` characters
+    // appear in base64-encoded key bodies. Make sure those survive.
+    const sshKey = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIA== user@host';
+    const result = parseKeyValueArgs([`ssh.public_key=${sshKey}`]);
+    expect(result.overrides['ssh.public_key']).toBe(sshKey);
+  });
+
+  test('keys can contain dots (system config convention)', () => {
+    const result = parseKeyValueArgs(['network.dmz.subnet=10.0.10.0/24']);
+    expect(result.overrides['network.dmz.subnet']).toBe('10.0.10.0/24');
+  });
+
+  test('later occurrences of a key overwrite earlier ones', () => {
+    const result = parseKeyValueArgs(['dns.primary=1.1.1.1', 'dns.primary=8.8.8.8']);
+    expect(result.overrides['dns.primary']).toBe('8.8.8.8');
+  });
+});