@celilo/cli 2.2.1 → 2.3.0

package/src/cli/flag-surface-gate.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Flag-surface gate (celilo#1327) and subcommand-surface gate (celilo#1337).
+ *
+ * A CLI flag lives in two places: the handler reads it off `flags.X`, and
+ * packages/core/src/command-registry.ts declares it so the parser accepts it.
+ * When only the first happens, the flag is fully implemented — often unit
+ * tested, because the test drives the handler directly and never consults
+ * validateFlags — and still rejected at the terminal with
+ * "Command 'X' does not accept any flags".
+ *
+ * Instances of exactly that shape: #1308 (doctor remediation arrows),
+ * #1316 (module deploy --keep), #1325 (system config set --force), and three
+ * handler reads found the first time this gate ran (module check --no-build
+ * and --strict, module changeset --bump — their subcommands were missing from
+ * the registry entirely, so validation was skipped, not failed).
+ *
+ * A subcommand drifts the opposite way: the registry declares it, dispatch
+ * runs it, and the hand-written help block never mentions it, so a user
+ * reading `celilo <command> --help` cannot learn the subcommand exists.
+ * #1337 measured ten such subcommands under `celilo module` (upgrade, audit,
+ * validate, changeset, status, where, operations, logs, journal, backup), and
+ * the first run of this scan found four more elsewhere (events
+ * list-unanswered, system migrate, ipam show, backup pull).
+ *
+ * All scans are deliberately coarse: a flag name must be declared SOMEWHERE
+ * in the registry, and a subcommand name must merely APPEAR SOMEWHERE in its
+ * command's help block — word-boundary match, not a parsed Subcommands:
+ * section, because help blocks vary in shape. A per-subcommand check would be
+ * tighter, but every known instance was declared nowhere / printed nowhere,
+ * and a coarse gate that runs beats a precise one nobody finishes.
+ *
+ * Reach floors: each scan asserts it walked a real surface (minimum distinct
+ * flag names / files / help blocks / commands). A scan that resolves no files
+ * exits 0 and proves nothing, so the gate fails loudly instead.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { COMMANDS } from '@celilo/core';
+
+const commandsDir = join(import.meta.dir, 'commands');
+const indexSource = readFileSync(join(import.meta.dir, 'index.ts'), 'utf8');
+
+/** Every flag name declared at any depth of the command registry. */
+function collectDeclaredFlags(): Set<string> {
+  const declared = new Set<string>();
+  function walk(defs: typeof COMMANDS): void {
+    for (const def of defs) {
+      for (const flag of def.flags ?? []) declared.add(flag.name);
+      if (def.subcommands) walk(def.subcommands);
+    }
+  }
+  walk(COMMANDS);
+  return declared;
+}
+
+const declaredFlags = collectDeclaredFlags();
+
+/**
+ * Flags accepted without a registry entry, each with the reason:
+ * - help/h: universal, added by validateFlags itself (parser.ts).
+ * - remote: top-level transport flag, intercepted at the top of runCli by
+ *   resolveRemote (packages/core/src/remote-client.ts) before any dispatch.
+ */
+const flagsOutsideTheRegistry = new Set(['help', 'h', 'remote']);
+
+interface HandlerScan {
+  byName: Map<string, string[]>;
+  fileCount: number;
+  totalReads: number;
+}
+
+/**
+ * Every flag literal a command handler reads via hasFlag(flags, 'x') or
+ * getFlag(flags, 'x'). Reads that pass a variable instead of a literal are
+ * invisible to this scan — accepted coarseness, see the header.
+ */
+function scanHandlerFlagReads(): HandlerScan {
+  const byName = new Map<string, string[]>();
+  const files = readdirSync(commandsDir).filter(
+    (f) => f.endsWith('.ts') && !f.endsWith('.test.ts'),
+  );
+  let totalReads = 0;
+
+  for (const file of files) {
+    const source = readFileSync(join(commandsDir, file), 'utf8');
+    const reads = source.matchAll(/(?:hasFlag|getFlag)\(\s*flags\s*,\s*'([^']+)'/g);
+    for (const read of reads) {
+      totalReads++;
+      const flagName = read[1];
+      if (!flagName) continue;
+      const holders = byName.get(flagName) ?? [];
+      holders.push(file);
+      byName.set(flagName, holders);
+    }
+  }
+
+  return { byName, fileCount: files.length, totalReads };
+}
+
+/**
+ * Source of each displayXxxHelp function in index.ts (the help-text blocks).
+ * Each block is bounded by the NEXT top-level declaration, not by the next
+ * display function and not by end-of-source. The original end-of-source bound
+ * let the last block swallow runCli's body, so --principal, --get-completions
+ * and --version were read out of dispatch code and reported as advertised.
+ */
+function extractHelpBlocks(source: string): string[] {
+  const fns = [...source.matchAll(/function display\w*Help\(\)/g)];
+  const topLevelDecl = /^(?:export )?(?:async )?function \w+|^export const \w+/gm;
+  const blocks: string[] = [];
+  for (const fn of fns) {
+    if (fn.index === undefined) continue;
+    const start = fn.index + fn[0].length;
+    topLevelDecl.lastIndex = start;
+    const next = topLevelDecl.exec(source);
+    const end = next?.index ?? source.length;
+    blocks.push(source.slice(start, end));
+  }
+  return blocks;
+}
+
+/** Distinct --flag names advertised across all help blocks. */
+function scanAdvertisedFlags(): { byName: Set<string>; blockCount: number } {
+  const byName = new Set<string>();
+  let blockCount = 0;
+
+  for (const block of extractHelpBlocks(indexSource)) {
+    // External-tool example lines (ansible-vault, ansible-playbook) carry the
+    // other tool's flags. Not celilo's surface. The flag often sits on the
+    // continuation line, so drop --vault-password-file by name as well as the
+    // ansible- command lines. // @psbanka - 2026-09
+    const celiloLines = block
+      .split('\n')
+      .filter((line) => !line.includes('ansible-'))
+      .filter((line) => !line.includes('vault-password-file'));
+    blockCount++;
+    for (const line of celiloLines) {
+      for (const match of line.matchAll(/--([a-zA-Z0-9][a-zA-Z0-9-]*)/g)) {
+        const flagName = match[1];
+        if (flagName) byName.add(flagName);
+      }
+    }
+  }
+
+  return { byName, blockCount };
+}
+
+/** `module` -> `Module`, `escalation-policy` -> `EscalationPolicy`. */
+function pascalCase(name: string): string {
+  return name.replace(/(^|-)([a-z])/g, (_match, prefix, char) => prefix + char.toUpperCase());
+}
+
+/**
+ * Help blocks keyed by the display function's name suffix: displayModuleHelp
+ * -> "Module". A command with subcommands but no dedicated display function
+ * (api, alerts, route, ...) is simply absent from the map and skipped by the
+ * subcommand scan — it has no help block to drift from.
+ */
+function extractNamedHelpBlocks(): Map<string, string> {
+  const byName = new Map<string, string>();
+  for (const match of indexSource.matchAll(/function display(\w*)Help\(\)/g)) {
+    if (match.index === undefined) continue;
+    const start = match.index + match[0].length;
+    const topLevelDecl = /^(?:export )?(?:async )?function \w+|^export const \w+/gm;
+    topLevelDecl.lastIndex = start;
+    const next = topLevelDecl.exec(indexSource);
+    byName.set(match[1], indexSource.slice(start, next?.index ?? indexSource.length));
+  }
+  return byName;
+}
+
+/**
+ * Registry subcommands that appear nowhere in their command's help block.
+ * Commands without a dedicated help block are skipped (nothing to diff).
+ */
+function scanSubcommandDrift(): {
+  missing: string[];
+  commandCount: number;
+  subcommandCount: number;
+} {
+  const helpBlocks = extractNamedHelpBlocks();
+  const missing: string[] = [];
+  let commandCount = 0;
+  let subcommandCount = 0;
+
+  for (const command of COMMANDS) {
+    if (!command.subcommands?.length) continue;
+    const name = pascalCase(command.name);
+    const block = helpBlocks.get(name);
+    if (block === undefined) continue;
+    commandCount++;
+    subcommandCount += command.subcommands.length;
+    for (const sub of command.subcommands) {
+      if (!new RegExp(`\\b${sub.name}\\b`).test(block)) {
+        missing.push(`celilo ${command.name} ${sub.name}`);
+      }
+    }
+  }
+
+  return { missing, commandCount, subcommandCount };
+}
+
+describe('subcommand-surface gate: help text vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanSubcommandDrift();
+    if (scan.commandCount < 14 || scan.subcommandCount < 60) {
+      throw new Error(
+        `Subcommand scan walked too little to prove anything: ${scan.commandCount} commands with help blocks, ${scan.subcommandCount} registry subcommands. Expected >= 14 commands, >= 60 subcommands. If the help-block surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.commandCount).toBeGreaterThanOrEqual(14);
+  });
+
+  it("every registry subcommand appears in its command's help block", () => {
+    const scan = scanSubcommandDrift();
+
+    if (scan.missing.length > 0) {
+      throw new Error(
+        `${scan.missing.length} registry subcommand(s) appear nowhere in their command's help text (scanned ${scan.commandCount} commands, ${scan.subcommandCount} subcommands):\n${scan.missing.map((entry) => `  ${entry}`).join('\n')}\nFix: add the subcommand to its displayXxxHelp block in apps/celilo/src/cli/index.ts, or remove it from packages/core/src/command-registry.ts if it is no longer dispatched.`,
+      );
+    }
+    expect(scan.missing).toEqual([]);
+  });
+});
+
+describe('flag-surface gate: handler reads vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanHandlerFlagReads();
+    if (scan.fileCount < 10 || scan.byName.size < 30 || scan.totalReads < 60) {
+      throw new Error(
+        `Handler scan walked too little to prove anything: ${scan.fileCount} files, ${scan.byName.size} distinct flags, ${scan.totalReads} reads. Expected >= 10 files, >= 30 distinct, >= 60 reads. If the handler surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.byName.size).toBeGreaterThanOrEqual(30);
+  });
+
+  it('every flag a handler reads is declared in the command registry', () => {
+    const scan = scanHandlerFlagReads();
+    const undeclared = [...scan.byName.entries()].filter(([name]) => !declaredFlags.has(name));
+
+    if (undeclared.length > 0) {
+      const detail = undeclared
+        .map(([name, files]) => `  --${name}  read by: ${[...new Set(files)].join(', ')}`)
+        .join('\n');
+      throw new Error(
+        `${undeclared.length} handler-read flag(s) are declared nowhere in COMMANDS (scanned ${scan.fileCount} handler files, ${scan.totalReads} reads, ${scan.byName.size} distinct flags):\n${detail}\nFix: declare each flag on its command in packages/core/src/command-registry.ts.`,
+      );
+    }
+    expect(undeclared).toEqual([]);
+  });
+});
+
+describe('flag-surface gate: help text vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanAdvertisedFlags();
+    if (scan.blockCount < 15 || scan.byName.size < 60) {
+      throw new Error(
+        `Help-text scan walked too little to prove anything: ${scan.blockCount} help blocks, ${scan.byName.size} distinct advertised flags. Expected >= 15 blocks, >= 60 distinct. If the help surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.byName.size).toBeGreaterThanOrEqual(60);
+  });
+
+  it('every flag advertised in help text is declared in the command registry', () => {
+    const scan = scanAdvertisedFlags();
+    const undeclared = [...scan.byName].filter(
+      (name) => !declaredFlags.has(name) && !flagsOutsideTheRegistry.has(name),
+    );
+
+    if (undeclared.length > 0) {
+      throw new Error(
+        `${undeclared.length} flag(s) advertised in index.ts help text are declared nowhere in COMMANDS (scanned ${scan.blockCount} help blocks, ${scan.byName.size} distinct advertised flags): ${undeclared.map((n) => `--${n}`).join(', ')}\nFix: declare each flag on its command in packages/core/src/command-registry.ts.`,
+      );
+    }
+    expect(undeclared).toEqual([]);
+  });
+});

package/src/cli/index.ts

@@ -80,6 +80,7 @@ import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
 import { handleModuleImport } from './commands/module-import';
+import { handleModuleJail } from './commands/module-jail';
 import { handleModuleJournal } from './commands/module-journal';
 import { handleModuleList } from './commands/module-list';
 import { handleModuleLogs } from './commands/module-logs';
@@ -315,6 +316,7 @@ Subcommands:
   resync-subscriptions         Rebuild subscribers from deployed modules' manifests (after a restore/migration)
   list-pending [--subscriber]  List pending deliveries
   list-failed [--subscriber]   List failed/abandoned deliveries with a true total
+  list-unanswered              List interview questions nobody has answered yet
   drain [--concurrency N]      Process pending deliveries once and return
   run [--poll-ms N]            Run the long-running dispatcher (foreground)
   emit <type> [<payload>]      Emit an event (operator/test path)
@@ -588,6 +590,32 @@ Subcommands:
       --auto-generate-secrets          Auto-generate all secrets without prompting
 
   list                                 List all installed modules
+    Options:
+      --json                           Output the module roster as stable JSON
+
+  status <id>                          Show detailed module status
+
+  where <id>                           Show which host(s) serve a module (host discovery)
+    Options:
+      --json                           Output host discovery as stable JSON
+
+  logs <id>                            Show deploy logs for a module
+    Options:
+      --tail <n>                       Show last N lines
+      --last                           Show only the most recent deploy run
+
+  journal <id>                         Tail a deployed module's runtime daemon journal on its host (no SSH)
+    Options:
+      --unit <glob>                    systemd unit or glob (default: <module-id>*)
+      --lines <n>                      Lines to return (default 100)
+      --since <window>                 Time window, e.g. '30 min ago'
+      --grep <text>                    Only lines containing this fixed string
+      --json                           Machine-readable JSON output
+
+  operations list|clear                Show or release in-flight module operations (the backup/restore lock)
+    Options:
+      --all                            With clear: also release operations that still look alive
+      --abandoned                      With list: also show abandoned rows (hidden by default)
 
   remove <id>                          Remove a module and all its data
 
@@ -605,8 +633,12 @@ Subcommands:
       --dry-run                        Print the ordered plan and change nothing
       --yes                            Skip the cascade confirmation
 
-  verify <id>                          Verify module integrity (signature + checksums)
-                                         (legacy alias: 'audit')
+  verify <id>                          Verify module integrity (signature + checksums) (legacy alias: 'audit')
+    Options:
+      --deep                           Deep verification (re-check all files)
+      --json                           Machine-readable JSON output
+
+  validate <id>                        Pre-flight check: validate module is ready for deployment
 
   config set <id> <key> <value>        Set module configuration value
   config get <id> [key]                Get module configuration value(s)
@@ -616,6 +648,11 @@ Subcommands:
   secret get <id> <key>                Get a decrypted module secret value
   secret list <id>                     List module secrets
 
+  jail <id> [policy]                   Get or set one module's hook jail policy (auto|off|required)
+    Options:
+      --clear                          Remove the module's policy; follow the system's hooks.jail_policy again
+      --force                          Skip the confirmation when the new policy is weaker than the system's
+
   show-config <id>                     Show all config including auto-derived values
   show-zone <id>                       Show module's network zone and config
 
@@ -647,6 +684,11 @@ Subcommands:
     Options:
       --registry <url>                  Use a custom registry (sweep mode only)
 
+  upgrade <id>                         Upgrade a module to its latest registry version (update, posture-gated backup, deploy, verify)
+    Options:
+      --poll                           Run the CD poll: upgrade every auto_upgrade module with a newer version
+      --registry <url>                 Registry URL (defaults to configured registry)
+
 Registry:
   search [query]                       Search the registry for modules
     Options:
@@ -662,6 +704,19 @@ Registry:
       --allow-dirty                    Permit publishing from a dirty git tree
       --allow-stale                    Skip the manifest-vs-src stale-check. Use sparingly.
 
+  changeset <module-dir>               Author a version changeset for a module (.changeset/<name>.md)
+    Options:
+      --bump <type>                    Version bump type: major, minor or patch (required)
+      --message <text>                 Changeset body text
+      --name <stem>                    Changeset filename stem (default: auto-generated slug)
+
+  backup <module-id>                   Create a backup of a module's data (invokes its on_backup hook)
+    Options:
+      --force                          Ignore schedule, back up now
+      --now                            Ignore schedule, back up now (alias for --force)
+      --storage <id>                   Storage destination ID
+      --no-interactive                 Non-interactive mode (for cron)
+
   check [path]                         Check a module for drift against the framework (default: .)
     Options:
       --no-build                       Skip the TypeScript build check
@@ -836,6 +891,12 @@ Subcommands:
       --storage <id>       Use specific storage destination
       --yes                Skip confirmation prompt
 
+  pull                      Download another box's backup artifact from a storage destination
+    Options:
+      --storage <name>     Storage destination name
+      --module <id>        Module ID whose backup to pull (default: system state)
+      --output <path>      Local path to write the artifact
+
 Description:
   Backups are encrypted with the master key and uploaded to a configured
   storage destination. System state backups capture the Celilo database.
@@ -1056,6 +1117,7 @@ Usage:
 Resources:
   vmid          Manage VMID reservations and allocations
   ip            Manage IP address reservations
+  show          Show comprehensive IPAM summary
   list-allocations    List all IPAM allocations (VMIDs and IPs)
 
 VMID Commands:
@@ -1140,6 +1202,8 @@ Subcommands:
   update [--module <id>] [--no-backup] [--allow-destructive] [--dry-run] [--json]
                                        Bring the system to the audit-determined READY state
 
+  migrate                              Apply pending database migrations (idempotent; safe to re-run)
+
   doctor [--fix]                       Diagnose system prerequisites and @celilo/* version drift
 
 Runbook:
@@ -1609,6 +1673,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleVersion(parsed.args, parsed.flags);
       case 'changeset':
         return handleModuleChangeset(parsed.args, parsed.flags);
+      case 'jail':
+        return handleModuleJail(parsed.args, parsed.flags);
       case 'audit':
         return moduleAudit(parsed.args, parsed.flags);
       case 'verify':

package/src/cli/parser.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from 'bun:test';
-import { getArg, getFlag, hasFlag, parseArguments, validateRequiredArgs } from './parser';
+import { COMMANDS } from '@celilo/core';
+import {
+  getArg,
+  getFlag,
+  hasFlag,
+  parseArguments,
+  validateFlags,
+  validateRequiredArgs,
+} from './parser';
 
 describe('CLI Parser', () => {
   describe('parseArguments', () => {
@@ -238,3 +246,31 @@ describe('CLI Parser', () => {
     });
   });
 });
+
+describe('a flag a handler reads is a flag the registry declares', () => {
+  // `handleSystemConfigSet` has read `flags.force` since the hooks.jail_policy
+  // interview gate landed, and its unit test drove the handler directly with
+  // `{ force: true }`. The registry declared no flags for `system config set`,
+  // so the parser answered `--force` with "does not accept any flags" and the
+  // escape hatch was tested and unreachable from a terminal. The suite could
+  // not see it, because nothing in it went through the parser.
+  const leaf = (path: readonly string[]) =>
+    path.slice(1).reduce<{ name: string; subcommands?: unknown[] } | undefined>(
+      (def, name) =>
+        (def as { subcommands?: { name: string }[] } | undefined)?.subcommands?.find(
+          (s) => s.name === name,
+        ),
+      COMMANDS.find((c) => c.name === path[0]),
+    );
+
+  test('system config set accepts --force through the real registry', () => {
+    const def = leaf(['system', 'config', 'set']);
+    expect(def).toBeDefined();
+    expect(validateFlags({ force: true }, def as never)).toBeNull();
+  });
+
+  test('and still refuses a flag nobody declared', () => {
+    const def = leaf(['system', 'config', 'set']);
+    expect(validateFlags({ frce: true }, def as never)).toContain('Unknown flag');
+  });
+});

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

@@ -34,9 +34,9 @@ describe('celilo restore', () => {
   afterEach(() => {
     closeDb();
     resetTestDbPath();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.CELILO_MASTER_KEY_PATH;
+    delete process.env.CELILO_SUPPRESS_DEPRECATION;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/restore-migration-failure.test.ts

@@ -99,8 +99,8 @@ describe('restore migration failure reporting (celilo#1269)', () => {
   afterEach(() => {
     closeDb();
     resetTestDbPath();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.CELILO_MASTER_KEY_PATH;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/tui/audit-state.ts

@@ -92,11 +92,13 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'interface_classification',
   'module_integrity',
   'detect_without_converge',
+  'jail_exemptions',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   module_integrity: 'Module integrity',
   detect_without_converge: 'Drift without converge',
+  jail_exemptions: 'Hook jail exemptions',
   interface_classification: 'Firewall interfaces',
   cli_version: 'CLI version',
   schema: 'Schema migrations',

package/src/config/paths.test.ts

@@ -21,14 +21,14 @@ describe('paths configuration', () => {
   describe('getModuleStoragePath', () => {
     it('returns custom path when CELILO_DATA_DIR is set', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getModuleStoragePath();
       expect(path).toBe('/custom/data/modules');
     });
 
     it('returns dev path when ENVIRONMENT=dev', () => {
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getModuleStoragePath();
@@ -38,8 +38,8 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns platform-specific path by default',
       () => {
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getModuleStoragePath();
 
@@ -63,14 +63,14 @@ describe('paths configuration', () => {
   describe('getDataDir', () => {
     it('returns custom path when CELILO_DATA_DIR is set', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDataDir();
       expect(path).toBe('/custom/data');
     });
 
     it('returns dev path when ENVIRONMENT=dev', () => {
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getDataDir();
@@ -80,8 +80,8 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns platform-specific path by default',
       () => {
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getDataDir();
 
@@ -103,7 +103,7 @@ describe('paths configuration', () => {
     });
 
     it('returns data dir + master.key when CELILO_MASTER_KEY_PATH not set', () => {
-      process.env.CELILO_MASTER_KEY_PATH = undefined;
+      delete process.env.CELILO_MASTER_KEY_PATH;
       process.env.CELILO_DATA_DIR = '/custom/data';
 
       const path = getMasterKeyPath();
@@ -113,9 +113,9 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'uses platform-specific data dir by default',
       () => {
-        process.env.CELILO_MASTER_KEY_PATH = undefined;
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_MASTER_KEY_PATH;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getMasterKeyPath();
 
@@ -131,8 +131,8 @@ describe('paths configuration', () => {
   describe('getDbPath', () => {
     it('returns custom path when CELILO_DB_PATH is set', () => {
       process.env.CELILO_DB_PATH = '/custom/path/celilo.db';
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.CELILO_DATA_DIR;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/custom/path/celilo.db');
@@ -142,8 +142,8 @@ describe('paths configuration', () => {
       'returns data dir + celilo.db on macOS in production',
       () => {
         delete process.env.CELILO_DB_PATH;
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getDbPath();
 
@@ -157,7 +157,7 @@ describe('paths configuration', () => {
 
     it('returns celilo-data/celilo.db in development mode', () => {
       delete process.env.CELILO_DB_PATH;
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getDbPath();
@@ -167,7 +167,7 @@ describe('paths configuration', () => {
     it('respects CELILO_DATA_DIR override', () => {
       delete process.env.CELILO_DB_PATH;
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/custom/data/celilo.db');
@@ -176,7 +176,7 @@ describe('paths configuration', () => {
     it('prioritizes CELILO_DB_PATH over CELILO_DATA_DIR', () => {
       process.env.CELILO_DB_PATH = '/explicit/db.db';
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/explicit/db.db');