@celilo/cli 0.1.5 → 0.1.7

package/src/hooks/run-named-hook.ts

@@ -0,0 +1,128 @@
+/**
+ * Helper to load + invoke a single named hook on a module.
+ *
+ * Centralises the boilerplate that `module run-hook` and `module remove`
+ * (for `on_uninstall`) and `module deploy` (for `on_install`) all share:
+ * looking up the module + manifest, decrypting secrets, building the
+ * config map, loading the capability table, and calling `invokeHook`
+ * with the right logger.
+ *
+ * The helper is intentionally orchestration-only (Rule 10.1): it has no
+ * UI / progress concerns of its own — callers wrap the returned
+ * promise with FuelGauge or console output as fits the surface they're
+ * exposing.
+ */
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { modules, secrets } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
+import { decryptSecret } from '../secrets/encryption';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { loadCapabilityFunctions } from './capability-loader';
+import { invokeHook } from './executor';
+import { loadHookConfigMap } from './load-hook-config';
+import type { HookLogger, HookName, HookResult } from './types';
+
+export interface RunNamedHookOptions {
+  /** Stream hook stdio to console rather than capture for a gauge. */
+  debug?: boolean;
+  /** Hook inputs (key=value pairs from the CLI, etc.). Default: empty. */
+  inputs?: Record<string, unknown>;
+}
+
+export interface RunNamedHookResult extends HookResult {
+  /**
+   * True when the module's manifest does not declare a hook with this
+   * name. Distinguishes "the hook ran and returned success" from "no
+   * hook to run." Callers like `module remove` use this to skip
+   * gracefully when a module has no `on_uninstall` defined.
+   */
+  notDefined?: boolean;
+}
+
+/**
+ * Load the module's hook definition from its manifest and run it,
+ * returning the executor's result.
+ *
+ * @param moduleId - DB id of the module to run the hook on.
+ * @param hookName - Name of the hook (e.g. `on_install`, `on_uninstall`).
+ * @param db - Database client.
+ * @param logger - Hook logger; the caller chooses gauge vs. console.
+ * @param options - Optional inputs / debug toggle.
+ * @returns Hook result, with `notDefined: true` when the manifest has
+ *   no hook of that name.
+ */
+export async function runNamedHook(
+  moduleId: string,
+  hookName: HookName,
+  db: DbClient,
+  logger: HookLogger,
+  options: RunNamedHookOptions = {},
+): Promise<RunNamedHookResult> {
+  const startedAt = Date.now();
+
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return {
+      success: false,
+      outputs: {},
+      error: `Module not found: ${moduleId}`,
+      duration: Date.now() - startedAt,
+    };
+  }
+
+  const manifest = module.manifestData as ModuleManifest;
+  const hookDef = manifest.hooks?.[hookName as keyof typeof manifest.hooks];
+  if (!hookDef) {
+    return {
+      success: true,
+      outputs: {},
+      duration: Date.now() - startedAt,
+      notDefined: true,
+    };
+  }
+
+  const configMap = await loadHookConfigMap(moduleId, db);
+
+  // Decrypt secrets.
+  const secretRecords = db.select().from(secrets).where(eq(secrets.moduleId, moduleId)).all();
+  const masterKey = await getOrCreateMasterKey();
+  const secretMap: Record<string, string> = {};
+  for (const s of secretRecords) {
+    secretMap[s.name] = decryptSecret(
+      { encryptedValue: s.encryptedValue, iv: s.iv, authTag: s.authTag },
+      masterKey,
+    );
+  }
+
+  // Capability pre-flight check: enforce manifest.requires for hooks
+  // that mutate state (on_install, health_check, etc.); skip it for
+  // teardown-style hooks where we want best-effort cleanup. The hook's
+  // own `defineHook({ requires, optional })` declaration still governs
+  // what the script actually accesses — this only controls the
+  // framework-level pre-flight gate, which would otherwise refuse to
+  // run an `on_uninstall` whenever a provider is "imported but not
+  // deployed" (a state the test harness produces routinely, and that
+  // operators producing failed half-removed modules also hit).
+  const enforceRequires = hookName !== 'on_uninstall';
+  const requiredCapabilities = enforceRequires
+    ? manifest.requires.capabilities.map((c) => c.name)
+    : [];
+  const capabilityFunctions = await loadCapabilityFunctions(moduleId, db, logger);
+
+  return invokeHook(
+    module.sourcePath,
+    hookName,
+    manifest.celilo_contract,
+    hookDef,
+    options.inputs ?? {},
+    configMap,
+    secretMap,
+    logger,
+    {
+      debug: options.debug ?? false,
+      capabilities: capabilityFunctions,
+      requiredCapabilities,
+    },
+  );
+}

package/src/hooks/types.ts

@@ -53,6 +53,19 @@ export interface HookContext {
   [key: string]: unknown;
 }
 
+/**
+ * Surfaced by `invokeHook` when a capability call inside the hook threw
+ * a `MissingProviderInputError`. Callers (notably `module-deploy.ts`)
+ * use this to drive the cross-module ensure interview and retry the
+ * hook. See `apps/celilo/designs/CROSS_MODULE_CONFIG_INTERVIEW.md`.
+ */
+export interface MissingProviderInputDetails {
+  providerModuleId: string;
+  ensureId: string;
+  value: string;
+  humanContext?: string;
+}
+
 /**
  * Result returned from hook execution
  */
@@ -64,6 +77,12 @@ export interface HookResult {
   screenshotPath?: string;
   /** Duration in milliseconds */
   duration: number;
+  /**
+   * Set when the hook failed because a capability call needs the
+   * framework to extend another module's config. Mutually exclusive
+   * with `success: true`.
+   */
+  missingProviderInput?: MissingProviderInputDetails;
 }
 
 /**

package/src/manifest/ensure-schema.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+import { EnsureInputSchema, EnsureSchema } from './schema';
+
+describe('EnsureInputSchema', () => {
+  test('append_to_array with config target', () => {
+    const result = EnsureInputSchema.safeParse({
+      kind: 'append_to_array',
+      target: 'config.additional_domains',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('append_to_array with secret target', () => {
+    // `append_to_array` is allowed against either scope by schema; runtime
+    // currently only implements config but the schema is permissive so
+    // future modules can extend.
+    const result = EnsureInputSchema.safeParse({
+      kind: 'append_to_array',
+      target: 'secret.allowed_domains',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('append_to_array rejects an invalid target prefix', () => {
+    const result = EnsureInputSchema.safeParse({
+      kind: 'append_to_array',
+      target: 'output.domains',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test('set_in_object requires key and prompt', () => {
+    const ok = EnsureInputSchema.safeParse({
+      kind: 'set_in_object',
+      target: 'secret.passwords',
+      key: '{{value}}',
+      prompt: 'Password for {{value}}',
+    });
+    expect(ok.success).toBe(true);
+
+    const missingPrompt = EnsureInputSchema.safeParse({
+      kind: 'set_in_object',
+      target: 'secret.passwords',
+      key: '{{value}}',
+    });
+    expect(missingPrompt.success).toBe(false);
+  });
+
+  test('rejects unknown kinds', () => {
+    const result = EnsureInputSchema.safeParse({
+      kind: 'mutate_universe',
+      target: 'config.foo',
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('EnsureSchema', () => {
+  test('full ensure block round-trips', () => {
+    const result = EnsureSchema.safeParse({
+      id: 'managed_domain',
+      description: 'Add a domain.',
+      inputs: [
+        { kind: 'append_to_array', target: 'config.additional_domains' },
+        {
+          kind: 'set_in_object',
+          target: 'secret.additional_ddns_passwords',
+          key: '{{value}}',
+          prompt: 'Password for {{value}}',
+          hint: 'Find it in the panel',
+        },
+      ],
+      post: 'redeploy_self',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.id).toBe('managed_domain');
+      expect(result.data.inputs).toHaveLength(2);
+      expect(result.data.post).toBe('redeploy_self');
+    }
+  });
+
+  test('id must be snake_case', () => {
+    const bad = EnsureSchema.safeParse({
+      id: 'ManagedDomain',
+      inputs: [{ kind: 'append_to_array', target: 'config.x' }],
+    });
+    expect(bad.success).toBe(false);
+  });
+
+  test('inputs cannot be empty', () => {
+    const bad = EnsureSchema.safeParse({
+      id: 'foo',
+      inputs: [],
+    });
+    expect(bad.success).toBe(false);
+  });
+
+  test('post is optional', () => {
+    const ok = EnsureSchema.safeParse({
+      id: 'foo',
+      inputs: [{ kind: 'append_to_array', target: 'config.x' }],
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  test('rejects unknown post action', () => {
+    const bad = EnsureSchema.safeParse({
+      id: 'foo',
+      inputs: [{ kind: 'append_to_array', target: 'config.x' }],
+      post: 'restart_service',
+    });
+    expect(bad.success).toBe(false);
+  });
+});

package/src/manifest/schema.ts

@@ -127,6 +127,69 @@ export const CapabilitySecretSchema = z.object({
   secret_ref: z.string().optional(), // Reference to provider module's own secret (e.g., $secret:tsig_key)
 });
 
+/**
+ * Ensure-input declaration.
+ *
+ * Each `inputs` entry tells the framework how to apply one piece of the
+ * cross-module update. The `target:` prefix (`config.*` vs `secret.*`)
+ * disambiguates whether the framework should write to the module's
+ * config or its secrets — secret targets get the same masking and
+ * storage path as a regular `secrets:` declaration.
+ *
+ * Templates: `{{value}}` is replaced with the consumer-supplied value.
+ *
+ * Kinds:
+ * - `append_to_array`: read current config array, append `value` if not
+ *   already present, write back. Idempotent.
+ * - `set_in_object`: prompt for a string, set it under `key` (a template,
+ *   typically `"{{value}}"`) on a JSON-object config or secret.
+ */
+export const EnsureInputSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('append_to_array'),
+    /** `config.<name>` or `secret.<name>` — pointer to the array to append to. */
+    target: z.string().regex(/^(config|secret)\.[A-Za-z_][A-Za-z0-9_]*$/),
+  }),
+  z.object({
+    kind: z.literal('set_in_object'),
+    /** `config.<name>` or `secret.<name>` — pointer to a JSON-object value. */
+    target: z.string().regex(/^(config|secret)\.[A-Za-z_][A-Za-z0-9_]*$/),
+    /** Template for the object key. Typically `"{{value}}"`. */
+    key: z.string().min(1),
+    /** Prompt shown to the user when collecting the per-key value. */
+    prompt: z.string().min(1),
+    /** Optional supplemental hint shown under the prompt. */
+    hint: z.string().optional(),
+  }),
+]);
+
+export type EnsureInput = z.infer<typeof EnsureInputSchema>;
+
+/**
+ * Post-action vocabulary — what the framework should do after applying
+ * `inputs`. Phase 3 only handles `redeploy_self`. Future modules may
+ * want `restart_service`, `run_hook`, etc.; add when needed.
+ */
+export const EnsurePostSchema = z.enum(['redeploy_self']);
+
+/**
+ * Ensure block — declares how the framework can "ensure" a value is
+ * covered by this provider's config. Consumers reference these by `id`
+ * via `MissingProviderInputError(ensureId, value)`. See
+ * `apps/celilo/designs/CROSS_MODULE_CONFIG_INTERVIEW.md`.
+ */
+export const EnsureSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-z0-9_]*$/, 'Ensure id must be snake_case'),
+  description: z.string().optional(),
+  inputs: z.array(EnsureInputSchema).min(1),
+  post: EnsurePostSchema.optional(),
+});
+
+export type Ensure = z.infer<typeof EnsureSchema>;
+
 /**
  * Capability provider
  * Module provides this capability to other modules
@@ -139,6 +202,13 @@ export const CapabilityProviderSchema = z.object({
   functions: z.array(z.string()).optional(),
   /** Zones this capability applies to. Null/undefined = zone-agnostic. */
   zones: z.array(z.string()).optional(),
+  /**
+   * Cross-module ensure points. When a consumer's capability call detects
+   * a value isn't covered by this provider's config, the framework looks
+   * up an ensure here by id and runs the matching interview against this
+   * module's config/secrets.
+   */
+  ensures: z.array(EnsureSchema).optional(),
 });
 
 /**
@@ -348,6 +418,12 @@ export const ModuleManifestSchema = z
         collections: z.array(AnsibleCollectionSchema).default([]),
       })
       .optional(),
+
+    e2e: z
+      .object({
+        tests_dir: z.string().min(1),
+      })
+      .optional(),
   })
   .strict();
 

package/src/module/import.ts

@@ -441,18 +441,26 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
         }
       }
 
-      // Read checksums and signature for database storage
-      const checksumsJson = await readFile(join(tempDir, 'checksums.json'), 'utf-8');
-      const ChecksumsFileSchema = z.object({
-        files: z.record(z.string(), z.string()),
-      });
-      const checksumsData = parseJsonWithValidation(
-        checksumsJson,
-        ChecksumsFileSchema,
-        'package checksums.json',
-      );
-      checksums = checksumsData.files;
-      signature = await readFile(join(tempDir, 'signature.sig'), 'utf-8');
+      // Read checksums and signature for database storage (both optional with --skip-verify)
+      try {
+        const checksumsJson = await readFile(join(tempDir, 'checksums.json'), 'utf-8');
+        const ChecksumsFileSchema = z.object({
+          files: z.record(z.string(), z.string()),
+        });
+        const checksumsData = parseJsonWithValidation(
+          checksumsJson,
+          ChecksumsFileSchema,
+          'package checksums.json',
+        );
+        checksums = checksumsData.files;
+      } catch (err) {
+        if (!skipVerify) throw err;
+      }
+      try {
+        signature = await readFile(join(tempDir, 'signature.sig'), 'utf-8');
+      } catch (err) {
+        if (!skipVerify) throw err;
+      }
 
       // Use extracted directory as source
       actualSourcePath = tempDir;

package/src/module/packaging/build.ts

@@ -1,10 +1,11 @@
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join, relative } from 'node:path';
 import { create as tarCreate } from 'tar';
 import { parse as parseYaml } from 'yaml';
+import { log } from '../../cli/prompts';
 import { validateModuleDirectory } from '../import';
 import { computeFileChecksum } from './checksum';
 import { signChecksums } from './signature';
@@ -25,6 +26,14 @@ export interface ModuleBuildOptions {
   sourceDir: string;
   outputPath?: string;
   masterKeyPath?: string;
+  /**
+   * Optional release metadata to stamp into the package as `release.json`.
+   * `celilo module publish` collects this; `celilo module package` runs
+   * without it (no git/CLI context) and ships a package without
+   * release.json — that's fine; audit treats absent metadata as
+   * "unknown release info" rather than as an error.
+   */
+  releaseMetadata?: import('./release-metadata').ReleaseMetadata;
 }
 
 /**
@@ -37,13 +46,17 @@ export interface ModuleBuildResult {
 }
 
 /**
- * Files/directories to exclude from package
+ * Files/directories to exclude from package.
+ *
+ * `node_modules` is handled by `shouldExclude` directly (path-aware) so
+ * the framework's own `@celilo/*` packages can still be bundled — see
+ * the comment on shouldExclude for why.
  */
 const EXCLUDE_PATTERNS = [
   '.git',
-  'node_modules',
   '.DS_Store',
   '*.netapp',
+  '*.test.ts',
   'checksums.json',
   'signature.sig',
 ];
@@ -59,10 +72,38 @@ const EXCLUDE_PATTERNS = [
 const FRAMEWORK_OWNED_PATHS = new Set(['celilo/types.d.ts']);
 
 /**
- * Check if file should be excluded
+ * Check if a path inside the source dir should be excluded from the
+ * package.
+ *
+ * `node_modules` exclusion is path-aware: regular npm dependencies are
+ * skipped (size + bun re-installs them at module-import time), but the
+ * framework's own `@celilo/*` packages stay in. That captures the
+ * capabilities API the module was authored against, so a module's
+ * hooks aren't silently broken by a runtime that ships a different
+ * version of `@celilo/capabilities` than the one on npm.
  */
 function shouldExclude(filePath: string): boolean {
   if (FRAMEWORK_OWNED_PATHS.has(filePath)) return true;
+
+  const segments = filePath.split('/');
+
+  // Module's e2e/ directory at the source root is tests + their deps —
+  // not part of the deployed module.
+  if (segments[0] === 'e2e') return true;
+
+  const nmIdx = segments.indexOf('node_modules');
+  if (nmIdx >= 0) {
+    // `node_modules` itself: descend so we can pick out @celilo/capabilities.
+    // The capabilities scope is the only thing we ship — it's the framework
+    // SDK the module was authored against. Everything else is regular npm
+    // cruft we'd just re-install on the target (or test-only deps inside
+    // packages like `@celilo/e2e` we don't want to drag in).
+    if (nmIdx + 1 >= segments.length) return false; // node_modules dir itself
+    if (segments[nmIdx + 1] !== '@celilo') return true;
+    if (nmIdx + 2 >= segments.length) return false; // node_modules/@celilo dir itself
+    return segments[nmIdx + 2] !== 'capabilities';
+  }
+
   const name = basename(filePath);
   return EXCLUDE_PATTERNS.some((pattern) => {
     if (pattern.startsWith('*')) {
@@ -191,19 +232,38 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
     // Run build if manifest declares one
     const manifest = parseYaml(manifestContent);
     if (manifest.build?.command || manifest.build?.script) {
-      const buildCmd = manifest.build.command
-        ? `bash -c ${JSON.stringify(manifest.build.command)}`
-        : manifest.build.script.endsWith('.sh')
-          ? `bash ${manifest.build.script}`
-          : `ansible-playbook ${manifest.build.script}`;
-
-      console.log(`Building module (${manifest.build.command ? 'command' : 'script'})...`);
+      log.info(`Building module (${manifest.build.command ? 'command' : 'script'})...`);
+      // The build runs in a staged copy of the module (buildDir), so
+      // relative paths that reach outside the module (e.g. sibling packages
+      // in a monorepo) don't resolve. Expose the ORIGINAL unstaged source
+      // path so build commands can find siblings via e.g.
+      // `$CELILO_MODULE_SOURCE_DIR/../../packages/...`. celilo-registry
+      // uses this to compile packages/registry-server into a single-file
+      // binary and drop it into the staged ansible files/ dir.
+      //
+      // Use execFileSync (not execSync) so the command string goes straight
+      // to bash without a /bin/sh wrapping pass. Otherwise outer-shell
+      // variable expansion would strip shell-only bash variables like
+      // $STAGE before bash ever sees them.
+      const buildEnv = { ...process.env, CELILO_MODULE_SOURCE_DIR: sourceDir };
       try {
-        execSync(buildCmd, {
-          cwd: buildDir,
-          stdio: 'inherit',
-          timeout: 300_000,
-        });
+        if (manifest.build.command) {
+          execFileSync('bash', ['-c', manifest.build.command], {
+            cwd: buildDir,
+            stdio: 'inherit',
+            timeout: 300_000,
+            env: buildEnv,
+          });
+        } else {
+          const script = manifest.build.script as string;
+          const cmd = script.endsWith('.sh') ? 'bash' : 'ansible-playbook';
+          execFileSync(cmd, [script], {
+            cwd: buildDir,
+            stdio: 'inherit',
+            timeout: 300_000,
+            env: buildEnv,
+          });
+        }
       } catch (buildError) {
         const msg = buildError instanceof Error ? buildError.message : String(buildError);
         return { success: false, error: `Auto-build failed: Build exited with code ${msg}` };
@@ -223,6 +283,15 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
       }
     }
 
+    // Stamp release metadata into the build dir BEFORE computing
+    // checksums, so the metadata is part of the integrity-verified
+    // payload (a future restore can trust the SHA / version it sees).
+    if (options.releaseMetadata) {
+      const { RELEASE_METADATA_FILENAME } = await import('./release-metadata');
+      const metadataPath = join(buildDir, RELEASE_METADATA_FILENAME);
+      await writeFile(metadataPath, JSON.stringify(options.releaseMetadata, null, 2));
+    }
+
     // Compute checksums
     const checksumsData = await computeChecksums(buildDir);
     const checksumsJson = JSON.stringify(checksumsData, null, 2);

package/src/module/packaging/release-metadata.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test';
+import { type GitCommandRunner, buildReleaseMetadata, collectGitInfo } from './release-metadata';
+
+describe('buildReleaseMetadata', () => {
+  test('produces a stable shape from injected inputs', () => {
+    const meta = buildReleaseMetadata({
+      moduleId: 'caddy',
+      version: '1.2.0+3',
+      git: { sha: 'abc1234', branch: 'main', dirty: false },
+      cliVersion: '0.1.5',
+      message: 'Fix DNS race',
+      publishedAt: new Date('2026-04-25T18:30:00Z'),
+    });
+
+    expect(meta).toEqual({
+      module_id: 'caddy',
+      version: '1.2.0+3',
+      git_sha: 'abc1234',
+      git_branch: 'main',
+      git_dirty: false,
+      published_at: '2026-04-25T18:30:00.000Z',
+      published_by_cli_version: '0.1.5',
+      message: 'Fix DNS race',
+    });
+  });
+
+  test('null message is preserved (no defaulting to empty string)', () => {
+    const meta = buildReleaseMetadata({
+      moduleId: 'x',
+      version: '1.0.0+1',
+      git: { sha: null, branch: null, dirty: false },
+      cliVersion: '0.1.5',
+      message: null,
+      publishedAt: new Date('2026-04-25T00:00:00Z'),
+    });
+    expect(meta.message).toBeNull();
+  });
+
+  test('defaults publishedAt to now when omitted', () => {
+    const before = Date.now();
+    const meta = buildReleaseMetadata({
+      moduleId: 'x',
+      version: '1.0.0+1',
+      git: { sha: null, branch: null, dirty: false },
+      cliVersion: '0.1.5',
+      message: null,
+    });
+    const stamped = new Date(meta.published_at).getTime();
+    expect(stamped).toBeGreaterThanOrEqual(before);
+    expect(stamped).toBeLessThanOrEqual(Date.now());
+  });
+});
+
+describe('collectGitInfo', () => {
+  test('returns nulls + clean when not in a git checkout', () => {
+    const run: GitCommandRunner = () => null;
+    expect(collectGitInfo('/tmp/x', run)).toEqual({
+      sha: null,
+      branch: null,
+      dirty: false,
+    });
+  });
+
+  test('reads sha + branch + clean status', () => {
+    const calls: string[][] = [];
+    const run: GitCommandRunner = (args) => {
+      calls.push(args);
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'main';
+      if (args[0] === 'status') return '';
+      return null;
+    };
+
+    const info = collectGitInfo('/tmp/x', run);
+
+    expect(info).toEqual({ sha: 'abc1234', branch: 'main', dirty: false });
+    expect(calls).toEqual([
+      ['rev-parse', 'HEAD'],
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      ['status', '--porcelain'],
+    ]);
+  });
+
+  test('detached HEAD reports null branch', () => {
+    const run: GitCommandRunner = (args) => {
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'HEAD';
+      if (args[0] === 'status') return '';
+      return null;
+    };
+    expect(collectGitInfo('/tmp/x', run).branch).toBeNull();
+  });
+
+  test('non-empty status output → dirty=true', () => {
+    const run: GitCommandRunner = (args) => {
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'main';
+      if (args[0] === 'status') return ' M src/foo.ts\n?? new-file.txt';
+      return null;
+    };
+    expect(collectGitInfo('/tmp/x', run).dirty).toBe(true);
+  });
+});