@celilo/cli 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -53,7 +53,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
     "@celilo/capabilities": "^0.1.10",
-    "@celilo/cli-display": "^0.1.8",
+    "@celilo/cli-display": "^0.1.9",
     "@celilo/event-bus": "^0.1.4",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",

package/src/cli/command-registry.ts

@@ -66,6 +66,18 @@ export const COMMANDS: CommandDef[] = [
     name: 'status',
     description: 'Show system and module status',
   },
+  {
+    name: 'doctor',
+    description: 'Diagnose @celilo/* version drift between the running CLI and the workspace',
+    flags: [
+      {
+        name: 'fix',
+        description:
+          'Repair drift by `bun link`-ing each drifted @celilo/* package from the workspace',
+        takesValue: false,
+      },
+    ],
+  },
   {
     name: 'audit',
     description: 'Top-level alias for `system audit`',

package/src/cli/commands/doctor.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test';
+import { compareVersions } from './doctor';
+
+describe('compareVersions', () => {
+  test('detects ascending major/minor/patch', () => {
+    expect(compareVersions('1.0.0', '2.0.0')).toBe(-1);
+    expect(compareVersions('1.0.0', '1.1.0')).toBe(-1);
+    expect(compareVersions('1.0.0', '1.0.1')).toBe(-1);
+  });
+
+  test('detects descending major/minor/patch', () => {
+    expect(compareVersions('2.0.0', '1.0.0')).toBe(1);
+    expect(compareVersions('1.1.0', '1.0.0')).toBe(1);
+    expect(compareVersions('1.0.1', '1.0.0')).toBe(1);
+  });
+
+  test('treats equal versions as equal', () => {
+    expect(compareVersions('1.2.3', '1.2.3')).toBe(0);
+    expect(compareVersions('0.1.9', '0.1.9')).toBe(0);
+  });
+
+  test('catches the canonical drift case (loaded < workspace)', () => {
+    // The case that triggered #2 in the first place: globally-installed
+    // 0.1.8 vs. workspace 0.1.9.
+    expect(compareVersions('0.1.8', '0.1.9')).toBe(-1);
+  });
+
+  test('treats missing trailing segments as zeros', () => {
+    expect(compareVersions('1.0', '1.0.0')).toBe(0);
+    expect(compareVersions('1.0', '1.0.1')).toBe(-1);
+  });
+
+  test('strips a leading v prefix', () => {
+    expect(compareVersions('v1.2.3', '1.2.3')).toBe(0);
+  });
+});

package/src/cli/commands/doctor.ts

@@ -0,0 +1,385 @@
+/**
+ * `celilo doctor` — diagnose @celilo/* version drift between the running CLI
+ * and the surrounding workspace (if any).
+ *
+ * Catches the canonical "I edited the workspace but my global celilo is
+ * still running an older published version" failure mode.
+ *
+ * Resolution strategy:
+ *   - The running CLI's package.json comes from a relative import — that
+ *     anchors us to whatever copy of `@celilo/cli` is actually executing
+ *     (workspace TS source or globally-installed node_modules tree).
+ *   - For each `@celilo/*` dependency, we ask the runtime where it
+ *     resolves the package's `package.json` and read the version there.
+ *   - If we can find a workspace root by walking up from `process.cwd()`,
+ *     we read each `packages/*\/package.json` and flag anything where the
+ *     loaded version is older than the workspace.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import cliPkg from '../../../package.json' with { type: 'json' };
+import type { CommandResult } from '../types';
+
+interface CeliloPkgInfo {
+  name: string;
+  declaredRange: string;
+  loadedVersion: string | null;
+  loadedFrom: string | null;
+  resolveError: string | null;
+}
+
+interface WorkspaceVersion {
+  name: string;
+  version: string;
+  path: string;
+}
+
+const ANSI = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+/**
+ * Discover every `@celilo/*` entry in the running CLI's package.json
+ * dependencies and resolve where each one is actually loaded from.
+ */
+function inspectCeliloDeps(): CeliloPkgInfo[] {
+  const deps: Record<string, string> = {
+    ...((cliPkg as { dependencies?: Record<string, string> }).dependencies ?? {}),
+  };
+  const celiloDeps = Object.entries(deps)
+    .filter(([name]) => name.startsWith('@celilo/'))
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const require = createRequire(import.meta.url);
+
+  return celiloDeps.map(([name, declaredRange]) => {
+    try {
+      const pkgJsonPath = require.resolve(`${name}/package.json`);
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { version: string };
+      return {
+        name,
+        declaredRange,
+        loadedVersion: pkg.version,
+        loadedFrom: dirname(pkgJsonPath),
+        resolveError: null,
+      };
+    } catch (err) {
+      return {
+        name,
+        declaredRange,
+        loadedVersion: null,
+        loadedFrom: null,
+        resolveError: err instanceof Error ? err.message : String(err),
+      };
+    }
+  });
+}
+
+/**
+ * Walk up from `start` until we find a `package.json` whose `workspaces`
+ * key is non-empty. Returns the directory containing that file or null.
+ */
+function findWorkspaceRoot(start: string): string | null {
+  let dir = resolve(start);
+  while (true) {
+    const candidate = join(dir, 'package.json');
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, 'utf-8')) as {
+          workspaces?: string[] | { packages?: string[] };
+        };
+        const workspaces = Array.isArray(pkg.workspaces)
+          ? pkg.workspaces
+          : (pkg.workspaces?.packages ?? []);
+        if (workspaces.length > 0) return dir;
+      } catch {
+        /* malformed package.json — keep walking */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Read every `@celilo/*` package.json in the workspace and return the
+ * version each one declares. Used to compare against what the running
+ * CLI actually loaded.
+ */
+function collectWorkspaceVersions(workspaceRoot: string): WorkspaceVersion[] {
+  const out: WorkspaceVersion[] = [];
+  // Hard-code the two glob roots used in this monorepo to avoid pulling
+  // in a glob library. Both directories are scanned the same way: read
+  // each immediate child, look for a package.json that names a @celilo/*
+  // package.
+  for (const dir of ['packages', 'apps']) {
+    const root = join(workspaceRoot, dir);
+    if (!existsSync(root)) continue;
+    for (const entry of readSubdirs(root)) {
+      const pkgJsonPath = join(root, entry, 'package.json');
+      if (!existsSync(pkgJsonPath)) continue;
+      try {
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as {
+          name?: string;
+          version?: string;
+        };
+        if (pkg.name?.startsWith('@celilo/') && pkg.version) {
+          out.push({ name: pkg.name, version: pkg.version, path: join(root, entry) });
+        }
+      } catch {
+        /* skip malformed */
+      }
+    }
+  }
+  return out;
+}
+
+function readSubdirs(dir: string): string[] {
+  // node:fs readdirSync — keep stdlib, no extra deps.
+  // Hidden dirs filtered out.
+  try {
+    const fs = require('node:fs') as typeof import('node:fs');
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Compare two semver-ish version strings. Returns -1 if a < b, 0 if
+ * equal, 1 if a > b. Tolerates non-numeric prerelease tags by comparing
+ * them as strings after the numeric segments.
+ *
+ * Exported for unit testing.
+ */
+export function compareVersions(a: string, b: string): number {
+  const split = (v: string) => v.replace(/^[v=]+/, '').split(/[.+-]/);
+  const aParts = split(a);
+  const bParts = split(b);
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    const ap = aParts[i] ?? '0';
+    const bp = bParts[i] ?? '0';
+    const an = Number(ap);
+    const bn = Number(bp);
+    if (!Number.isNaN(an) && !Number.isNaN(bn)) {
+      if (an !== bn) return an < bn ? -1 : 1;
+    } else if (ap !== bp) {
+      return ap < bp ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+interface DriftedDep {
+  name: string;
+  loadedVersion: string;
+  workspaceVersion: string;
+  workspacePath: string;
+}
+
+/**
+ * Run a command, capture stdout/stderr, return whether it succeeded.
+ * Used for the `bun link` calls that --fix orchestrates.
+ */
+function runCommand(
+  cmd: string,
+  args: string[],
+  cwd: string,
+): { ok: boolean; stdout: string; stderr: string } {
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8' });
+  return {
+    ok: r.status === 0,
+    stdout: (r.stdout ?? '').trim(),
+    stderr: (r.stderr ?? '').trim(),
+  };
+}
+
+/**
+ * Repair drift by `bun link`-ing each drifted package from the
+ * workspace into the running CLI's package directory.
+ *
+ * Two-step bun link workflow:
+ *   1. From each workspace package dir: `bun link` registers it
+ *      globally under its package name.
+ *   2. From the running CLI's package dir: `bun link <pkgname>`
+ *      replaces the resolved copy with the symlink to the workspace.
+ *
+ * `bun unlink` reverses both steps if the user wants to revert.
+ *
+ * Only safe to run when running from a globally-installed CLI; from
+ * a workspace TS-source invocation there's nothing to repair.
+ */
+function applyFix(drifted: DriftedDep[], cliRoot: string): string[] {
+  const lines: string[] = [];
+  for (const d of drifted) {
+    lines.push(`  ${d.name}: linking ${d.workspaceVersion} from ${d.workspacePath}`);
+
+    const reg = runCommand('bun', ['link'], d.workspacePath);
+    if (!reg.ok) {
+      lines.push(
+        `    ${ANSI.red}✗${ANSI.reset} register failed: ${reg.stderr || reg.stdout || 'no output'}`,
+      );
+      continue;
+    }
+
+    const link = runCommand('bun', ['link', d.name], cliRoot);
+    if (!link.ok) {
+      lines.push(
+        `    ${ANSI.red}✗${ANSI.reset} link failed: ${link.stderr || link.stdout || 'no output'}`,
+      );
+      continue;
+    }
+
+    lines.push(`    ${ANSI.green}✔${ANSI.reset} linked`);
+  }
+  return lines;
+}
+
+export async function handleDoctor(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const lines: string[] = [];
+
+  const cliVersion = (cliPkg as { version: string }).version;
+  const cliName = (cliPkg as { name: string }).name;
+  // Where is *this* file loaded from? Anchors the "running from" line.
+  const cliRoot = resolve(dirname(new URL(import.meta.url).pathname), '../../..');
+  lines.push(`${cliName} ${cliVersion}`);
+  lines.push(`${ANSI.dim}running from ${cliRoot}${ANSI.reset}`);
+  lines.push('');
+
+  const workspaceRoot = findWorkspaceRoot(process.cwd());
+  const workspaceVersions = workspaceRoot ? collectWorkspaceVersions(workspaceRoot) : [];
+  const workspaceMap = new Map(workspaceVersions.map((w) => [w.name, w]));
+
+  if (workspaceRoot) {
+    lines.push(`workspace: ${workspaceRoot}`);
+  } else {
+    lines.push(`${ANSI.dim}no workspace detected from ${process.cwd()}${ANSI.reset}`);
+  }
+  lines.push('');
+
+  const deps = inspectCeliloDeps();
+  // Track whether anything is amiss so we can summarize and exit non-zero.
+  let driftCount = 0;
+  let unresolvedCount = 0;
+  const drifted: DriftedDep[] = [];
+
+  // Compute column widths for a clean table.
+  const nameCol = Math.max(...deps.map((d) => d.name.length), 12);
+  const declCol = Math.max(...deps.map((d) => d.declaredRange.length), 8);
+  const loadedCol = Math.max(...deps.map((d) => (d.loadedVersion ?? '?').length), 8);
+
+  lines.push(
+    `  ${'package'.padEnd(nameCol)}  ${'declares'.padEnd(declCol)}  ${'loaded'.padEnd(loadedCol)}  notes`,
+  );
+  lines.push(`  ${'-'.repeat(nameCol)}  ${'-'.repeat(declCol)}  ${'-'.repeat(loadedCol)}  -----`);
+
+  for (const dep of deps) {
+    const loaded = dep.loadedVersion ?? '?';
+    const notes: string[] = [];
+    let glyph = `${ANSI.green}✔${ANSI.reset}`;
+
+    if (dep.resolveError) {
+      glyph = `${ANSI.red}✗${ANSI.reset}`;
+      notes.push(`unresolved: ${dep.resolveError.split('\n')[0]}`);
+      unresolvedCount++;
+    } else if (dep.loadedVersion) {
+      const ws = workspaceMap.get(dep.name);
+      if (ws) {
+        const cmp = compareVersions(dep.loadedVersion, ws.version);
+        if (cmp < 0) {
+          glyph = `${ANSI.yellow}⚠${ANSI.reset}`;
+          notes.push(`workspace has ${ws.version} — running CLI is behind`);
+          driftCount++;
+          drifted.push({
+            name: dep.name,
+            loadedVersion: dep.loadedVersion,
+            workspaceVersion: ws.version,
+            workspacePath: ws.path,
+          });
+        } else if (cmp > 0) {
+          notes.push(`workspace has ${ws.version} (older — unpublished bump?)`);
+        }
+      }
+      if (dep.loadedFrom) {
+        const shortPath = dep.loadedFrom.replace(process.env.HOME ?? '', '~');
+        notes.push(`from ${shortPath}`);
+      }
+    }
+
+    lines.push(
+      `${glyph} ${dep.name.padEnd(nameCol)}  ${dep.declaredRange.padEnd(declCol)}  ${loaded.padEnd(loadedCol)}  ${ANSI.dim}${notes.join('; ')}${ANSI.reset}`,
+    );
+  }
+
+  // Workspace packages that the CLI doesn't depend on — surface them so
+  // the operator sees the full set of @celilo/* in play.
+  const declaredNames = new Set(deps.map((d) => d.name));
+  const extras = workspaceVersions.filter((w) => !declaredNames.has(w.name));
+  if (extras.length > 0) {
+    lines.push('');
+    lines.push(`${ANSI.dim}other workspace packages (not depended on by this CLI):${ANSI.reset}`);
+    for (const w of extras) {
+      lines.push(`  ${w.name} ${w.version}  ${ANSI.dim}${w.path}${ANSI.reset}`);
+    }
+  }
+
+  lines.push('');
+
+  const fix = flags.fix === true;
+
+  if (fix && drifted.length > 0) {
+    lines.push(`Repairing ${drifted.length} drifted package(s) with \`bun link\`:`);
+    lines.push(...applyFix(drifted, cliRoot));
+    lines.push('');
+    lines.push(
+      `${ANSI.dim}Re-run \`celilo doctor\` to verify; \`bun unlink\` from each workspace dir reverses.${ANSI.reset}`,
+    );
+    return {
+      success: true,
+      message: lines.join('\n'),
+      rawOutput: true,
+    };
+  }
+
+  if (fix && drifted.length === 0) {
+    lines.push(`${ANSI.dim}--fix: nothing to repair.${ANSI.reset}`);
+  }
+
+  if (driftCount > 0 || unresolvedCount > 0) {
+    const summary: string[] = [];
+    if (driftCount > 0) summary.push(`${driftCount} package(s) behind workspace`);
+    if (unresolvedCount > 0) summary.push(`${unresolvedCount} unresolved`);
+    if (drifted.length > 0) {
+      lines.push(
+        `${ANSI.dim}Run \`celilo doctor --fix\` to bun-link drifted packages from the workspace.${ANSI.reset}`,
+      );
+    }
+    return {
+      success: false,
+      error: `Drift detected: ${summary.join(', ')}`,
+      details: lines.join('\n'),
+    };
+  }
+
+  lines.push(`${ANSI.green}OK${ANSI.reset} — no drift detected`);
+  return {
+    success: true,
+    message: lines.join('\n'),
+    rawOutput: true,
+  };
+}

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

@@ -133,7 +133,43 @@ export async function handleModuleGenerate(
   const moduleSecretsMissing = await validateModuleSecrets(moduleId, db);
 
   if (moduleSecretsMissing.length > 0) {
-    // Always try to interview for missing secrets
+    // interviewForMissingSecrets fires `secret.required.*` bus events for
+    // user_provided secrets and waits forever for a responder. In a
+    // non-interactive context (no TTY, no piped responder), that's a
+    // silent hang. Probe the bus first; if nothing answers, fail fast
+    // with an actionable error instead of stalling indefinitely.
+    //
+    // Auto-generated secrets (manifest `generate:` field or schema
+    // source: 'generated') don't go through the bus, so missing-but-
+    // auto-generatable doesn't need a responder. Filter those out
+    // before deciding whether to probe.
+    if (!process.stdin.isTTY) {
+      const { getSecretMetadata } = await import('../../services/secret-schema-loader');
+      const promptable: typeof moduleSecretsMissing = [];
+      for (const s of moduleSecretsMissing) {
+        if (s.generate) continue; // manifest-declared auto-generate
+        const meta = await getSecretMetadata(moduleId, s.name, db);
+        if (meta?.source === 'generated') continue; // schema-declared auto-generate
+        promptable.push(s);
+      }
+
+      if (promptable.length > 0) {
+        const { probeForResponder } = await import('../../services/responder-probe');
+        const { getEventBusPath } = await import('../../config/paths');
+        const responderAvailable = await probeForResponder(getEventBusPath());
+        if (!responderAvailable) {
+          const names = promptable.map((s) => s.name).join(', ');
+          const setCommands = promptable
+            .map((s) => `       celilo module secret set ${moduleId} ${s.name} <value>`)
+            .join('\n');
+          return {
+            success: false,
+            error: `Missing required secret(s): ${names}\n\nNo responder is running and stdin isn't a TTY, so module generate can't prompt for them. Either:\n  1. Run interactively (in a terminal)\n  2. Pre-set the secrets:\n${setCommands}\n  3. Run a responder in another shell:\n       celilo events respond --values values.json`,
+          };
+        }
+      }
+    }
+
     // Auto-generated secrets work in non-interactive mode
     const result = await interviewForMissingSecrets(moduleId, moduleSecretsMissing, db);
     if (!result.success) {

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

@@ -221,11 +221,22 @@ export async function handleModuleRemove(
     log.success('Infrastructure destroyed');
   }
 
-  // Remove DNS record (if dns_internal is available)
+  // Remove DNS record (if dns_internal is available). Wrapped in a
+  // FuelGauge with a gauge logger so the dns_internal capability calls
+  // inside (`deleteRecord`, etc.) nest as sub-events rather than
+  // leaking to scrollback as unindented top-level lines via
+  // cli/prompts.log.instantEvent (which pops every pending step).
+  const dnsGauge = new FuelGauge(`Removing ${moduleId} from DNS`, {
+    skipAnimation: !process.stdout.isTTY,
+  });
+  dnsGauge.start();
   try {
+    const dnsLogger = createGaugeLogger(dnsGauge, moduleId, 'auto_deregister_dns');
     const { autoDeregisterDns } = await import('../../services/dns-auto-register');
-    await autoDeregisterDns(moduleId, db, log);
+    await autoDeregisterDns(moduleId, db, dnsLogger);
+    dnsGauge.stop(true);
   } catch {
+    dnsGauge.stop(false);
     // Non-fatal -- continue with removal
   }
 

package/src/cli/completion.ts

@@ -28,20 +28,22 @@ export async function getCompletions(words: string[], current: number): Promise<
   // currentIndex === 0 means we're completing the first word (the command)
   if (currentIndex === 0) {
     const commands = [
+      'audit',
       'backup',
       'capability',
+      'completion',
+      'doctor',
+      'events',
       'help',
       'hook',
-      'package',
+      'ipam',
+      'machine',
       'module',
+      'package',
       'service',
+      'status',
       'storage',
-      'machine',
       'system',
-      'ipam',
-      'completion',
-      'status',
-      'audit',
       'version',
     ];
     return filterSuggestions(commands, args[0] || '');
@@ -66,6 +68,28 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(capabilityNames, args[2] || '');
   }
 
+  // Events subcommands — keep this list in sync with command-registry.ts.
+  if (command === 'events' && currentIndex === 1) {
+    const subcommands = [
+      'status',
+      'tail',
+      'list-subscribers',
+      'list-pending',
+      'drain',
+      'run',
+      'emit',
+      'ack',
+      'fail',
+      'repair',
+      'resume',
+      'respond',
+      'install-daemon',
+      'uninstall-daemon',
+      'show-daemon',
+    ];
+    return filterSuggestions(subcommands, args[1] || '');
+  }
+
   // Hook subcommands
   if (command === 'hook' && currentIndex === 1) {
     const subcommands = ['run'];

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
+import { handleDoctor } from './commands/doctor';
 import {
   handleEventsAck,
   handleEventsDrain,
@@ -147,7 +148,9 @@ Usage:
 
 Commands:
   status                   Show system and module status
+  doctor                   Diagnose @celilo/* version drift between the running CLI and the workspace
   audit                    Top-level alias for 'system audit'
+  events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
   package                  Create distributable .netapp packages from module source
   module                   Manage modules (import, list, configure, build, generate)
@@ -900,6 +903,11 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleStatus();
   }
 
+  // Handle doctor command
+  if (parsed.command === 'doctor') {
+    return handleDoctor(parsed.args, parsed.flags);
+  }
+
   // Top-level alias: `celilo audit` → `celilo system audit`
   if (parsed.command === 'audit') {
     return handleSystemAudit(parsed.args, parsed.flags);

package/src/config/paths.ts

@@ -4,38 +4,22 @@ import { join } from 'node:path';
 /**
  * Get the module storage path based on environment and platform
  *
- * Priority:
- * 1. CELILO_DATA_DIR environment variable (explicit override)
- * 2. ENVIRONMENT=dev uses ./celilo-data/modules/ (for testing)
- * 3. Platform defaults:
- *    - macOS: ~/Library/Application Support/celilo/modules/
- *    - Linux: /var/lib/celilo/modules/
- *
  * @returns Absolute path to module storage directory
  */
 export function getModuleStoragePath(): string {
-  // Explicit override
-  if (process.env.CELILO_DATA_DIR) {
-    return join(process.env.CELILO_DATA_DIR, 'modules');
-  }
-
-  // Development mode
-  if (process.env.ENVIRONMENT === 'dev') {
-    return join(process.cwd(), 'celilo-data', 'modules');
-  }
-
-  // Platform defaults
-  if (platform() === 'darwin') {
-    return join(homedir(), 'Library', 'Application Support', 'celilo', 'modules');
-  }
-
-  // Linux/other
-  return '/var/lib/celilo/modules';
+  return join(getDataDir(), 'modules');
 }
 
 /**
  * Get the base data directory for Celilo
  *
+ * Priority:
+ * 1. CELILO_DATA_DIR environment variable (explicit override)
+ * 2. ENVIRONMENT=dev uses ./celilo-data/ (for testing)
+ * 3. Platform defaults — always user-scoped so the CLI works without root:
+ *    - macOS: ~/Library/Application Support/celilo/
+ *    - Linux: $XDG_DATA_HOME/celilo/ (defaults to ~/.local/share/celilo/)
+ *
  * @returns Absolute path to base data directory
  */
 export function getDataDir(): string {
@@ -49,13 +33,15 @@ export function getDataDir(): string {
     return join(process.cwd(), 'celilo-data');
   }
 
-  // Platform defaults
+  // macOS
   if (platform() === 'darwin') {
     return join(homedir(), 'Library', 'Application Support', 'celilo');
   }
 
-  // Linux/other
-  return '/var/lib/celilo';
+  // Linux/other — XDG Base Directory spec, user-scoped (no sudo needed).
+  // System-wide installs can opt in via CELILO_DATA_DIR=/var/lib/celilo.
+  const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+  return join(xdgDataHome, 'celilo');
 }
 
 /**