@onebrain-ai/cli 2.0.0

package/src/internal/orphan-scan.test.ts

@@ -0,0 +1,271 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { runOrphanScan } from './orphan-scan.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function makeTmpDir(): Promise<string> {
+  return mkdtemp(join(tmpdir(), 'onebrain-os-test-'));
+}
+
+/**
+ * Build a checkpoint filename: YYYY-MM-DD-{token}-checkpoint-{NN}.md
+ */
+function checkpointName(date: string, token: string, nn: number): string {
+  return `${date}-${token}-checkpoint-${String(nn).padStart(2, '0')}.md`;
+}
+
+/**
+ * Build a session log filename: YYYY-MM-DD-session-{NN}.md
+ */
+function sessionLogName(date: string, nn: number): string {
+  return `${date}-session-${String(nn).padStart(2, '0')}.md`;
+}
+
+function checkpointFrontmatter(merged: boolean): string {
+  return `---\ntags: [checkpoint, session-log]\ndate: ${new Date().toISOString().slice(0, 10)}\ncheckpoint: 01\ntrigger: stop\nmerged: ${merged}\n---\n\n## What We Worked On\n\nTest content.`;
+}
+
+function sessionLogFrontmatter(autoSaved: boolean): string {
+  return `---\ntags: [session-log]\ndate: 2026-04-20\nauto-saved: ${autoSaved}\n---\n\n## Session\n\nTest.`;
+}
+
+/**
+ * Get current and previous month dirs as { thisYear, thisMonth, prevYear, prevMonth }
+ */
+function getMonthParts() {
+  const now = new Date();
+  const thisYear = String(now.getFullYear());
+  const thisMonth = String(now.getMonth() + 1).padStart(2, '0');
+  const prevDate = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+  const prevYear = String(prevDate.getFullYear());
+  const prevMonth = String(prevDate.getMonth() + 1).padStart(2, '0');
+  return { thisYear, thisMonth, prevYear, prevMonth };
+}
+
+async function makeMonthDir(logsDir: string, year: string, month: string): Promise<string> {
+  const dir = join(logsDir, year, month);
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('runOrphanScan', () => {
+  let tmpDir: string;
+  let logsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await makeTmpDir();
+    logsDir = join(tmpDir, '07-logs');
+    await mkdir(logsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns orphan_count: 0 when no checkpoint files exist', async () => {
+    const result = await runOrphanScan(logsDir, 'abc12345');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  // Update snapshots: bun test --update-snapshots
+  it('output shape matches snapshot { orphan_count: N }', async () => {
+    // Zero orphans — verifies the shape is { orphan_count: 0 }
+    const zeroResult = await runOrphanScan(logsDir, 'abc12345');
+    expect(zeroResult).toMatchSnapshot();
+
+    // One orphan — verifies the shape is { orphan_count: 1 }
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-01`;
+    await writeFile(
+      join(monthDir, `${pastDate}-snaptoken-checkpoint-01.md`),
+      '---\ntags: [checkpoint]\nmerged: false\n---\n\nContent.',
+      'utf8',
+    );
+    const oneResult = await runOrphanScan(logsDir, 'differenttoken');
+    expect(oneResult).toMatchSnapshot();
+  });
+
+  it('returns orphan_count: 0 when logs folder does not exist', async () => {
+    const result = await runOrphanScan(join(tmpDir, 'nonexistent'), 'abc12345');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it('skips checkpoint files with merged: true', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    // Use a past date so today-skip doesn't apply
+    const pastDate = `${thisYear}-${thisMonth}-01`;
+    const fname = checkpointName(pastDate, 'token11', 1);
+    await writeFile(join(monthDir, fname), checkpointFrontmatter(true), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it('skips checkpoint files with merged: "true" (quoted string in YAML)', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-01`;
+    const fname = checkpointName(pastDate, 'tokenStrTrue', 1);
+    // Write frontmatter with merged as a quoted string (YAML string "true", not boolean)
+    const content = `---\ntags: [checkpoint, session-log]\ndate: ${pastDate}\ncheckpoint: 01\ntrigger: stop\nmerged: "true"\n---\n\n## What We Worked On\n\nTest content.`;
+    await writeFile(join(monthDir, fname), content, 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it('skips checkpoint files matching current session token', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-01`;
+    const fname = checkpointName(pastDate, 'current99', 1);
+    await writeFile(join(monthDir, fname), checkpointFrontmatter(false), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it('skips checkpoint when a manual (non-auto-saved) session log exists for that date', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-02`;
+    // Write checkpoint (unmerged)
+    const cpName = checkpointName(pastDate, 'tokenAA', 1);
+    await writeFile(join(monthDir, cpName), checkpointFrontmatter(false), 'utf8');
+    // Write manual session log (auto-saved: false)
+    const logName = sessionLogName(pastDate, 1);
+    await writeFile(join(monthDir, logName), sessionLogFrontmatter(false), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it('does NOT skip when only auto-saved session log exists for that date', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-03`;
+    // Write checkpoint (unmerged)
+    const cpName = checkpointName(pastDate, 'tokenBB', 1);
+    await writeFile(join(monthDir, cpName), checkpointFrontmatter(false), 'utf8');
+    // Write auto-saved session log
+    const logName = sessionLogName(pastDate, 1);
+    await writeFile(join(monthDir, logName), sessionLogFrontmatter(true), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 1 });
+  });
+
+  it('counts unmerged orphan checkpoints from current month', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-04`;
+    // Two different tokens
+    for (const token of ['tokenCC', 'tokenDD']) {
+      const cpName = checkpointName(pastDate, token, 1);
+      await writeFile(join(monthDir, cpName), checkpointFrontmatter(false), 'utf8');
+    }
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 2 });
+  });
+
+  it('counts orphans from previous month dir', async () => {
+    const { prevYear, prevMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, prevYear, prevMonth);
+    const pastDate = `${prevYear}-${prevMonth}-15`;
+    const cpName = checkpointName(pastDate, 'tokenEE', 1);
+    await writeFile(join(monthDir, cpName), checkpointFrontmatter(false), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 1 });
+  });
+
+  it('multiple checkpoints for same token in same month count as one orphan session', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-05`;
+    // Same token, two checkpoint files
+    for (let i = 1; i <= 2; i++) {
+      const cpName = checkpointName(pastDate, 'tokenFF', i);
+      await writeFile(join(monthDir, cpName), checkpointFrontmatter(false), 'utf8');
+    }
+    const result = await runOrphanScan(logsDir, 'current99');
+    // One token = one orphan session
+    expect(result).toEqual({ orphan_count: 1 });
+  });
+
+  it('handles files with missing frontmatter gracefully (counts as orphan)', async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const pastDate = `${thisYear}-${thisMonth}-06`;
+    const cpName = checkpointName(pastDate, 'tokenGG', 1);
+    await writeFile(join(monthDir, cpName), '# No frontmatter here\n\nContent.', 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 1 });
+  });
+
+  it("creates a checkpoint file with today's actual date → orphan_count: 0 (today boundary skipped)", async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const todayStr = `${thisYear}-${thisMonth}-${String(new Date().getDate()).padStart(2, '0')}`;
+    const fname = checkpointName(todayStr, 'todaytoken', 1);
+    await writeFile(join(monthDir, fname), checkpointFrontmatter(false), 'utf8');
+    const result = await runOrphanScan(logsDir, 'current99');
+    // Today's checkpoints must be skipped — not orphans yet
+    expect(result).toEqual({ orphan_count: 0 });
+  });
+
+  it("today's file skipped but a past date in same month still counted", async () => {
+    const { thisYear, thisMonth } = getMonthParts();
+    const monthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const todayStr = `${thisYear}-${thisMonth}-${String(new Date().getDate()).padStart(2, '0')}`;
+    // Today: should be skipped
+    const todayFname = checkpointName(todayStr, 'todaytoken', 1);
+    await writeFile(join(monthDir, todayFname), checkpointFrontmatter(false), 'utf8');
+
+    // Past date in same month: day 01 (safe to use if today isn't day 01)
+    const todayDay = new Date().getDate();
+    if (todayDay !== 1) {
+      const pastDate = `${thisYear}-${thisMonth}-01`;
+      const pastFname = checkpointName(pastDate, 'pasttoken', 1);
+      await writeFile(join(monthDir, pastFname), checkpointFrontmatter(false), 'utf8');
+
+      const result = await runOrphanScan(logsDir, 'current99');
+      // today skipped, past counted
+      expect(result).toEqual({ orphan_count: 1 });
+    } else {
+      // If today IS day 01, just verify today is skipped
+      const result = await runOrphanScan(logsDir, 'current99');
+      expect(result).toEqual({ orphan_count: 0 });
+    }
+  });
+
+  it('combines orphans from both months in total count', async () => {
+    const { thisYear, thisMonth, prevYear, prevMonth } = getMonthParts();
+
+    const thisMonthDir = await makeMonthDir(logsDir, thisYear, thisMonth);
+    const prevMonthDir = await makeMonthDir(logsDir, prevYear, prevMonth);
+
+    const thisDate = `${thisYear}-${thisMonth}-07`;
+    const prevDate = `${prevYear}-${prevMonth}-20`;
+
+    await writeFile(
+      join(thisMonthDir, checkpointName(thisDate, 'tokenHH', 1)),
+      checkpointFrontmatter(false),
+      'utf8',
+    );
+    await writeFile(
+      join(prevMonthDir, checkpointName(prevDate, 'tokenII', 1)),
+      checkpointFrontmatter(false),
+      'utf8',
+    );
+
+    const result = await runOrphanScan(logsDir, 'current99');
+    expect(result).toEqual({ orphan_count: 2 });
+  });
+});

package/src/internal/orphan-scan.ts

@@ -0,0 +1,213 @@
+/**
+ * orphan-scan — internal command
+ *
+ * Scans the logs folder for unmerged checkpoint files (orphans).
+ * An orphan is a checkpoint whose session was never wrapped up via /wrapup.
+ *
+ * Output: JSON { orphan_count: N }
+ * Exit code always 0.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type OrphanScanResult = {
+  orphan_count: number;
+};
+
+// ---------------------------------------------------------------------------
+// Frontmatter helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract YAML frontmatter from markdown text.
+ * Returns parsed object or null if no valid frontmatter.
+ */
+function parseFrontmatter(rawText: string): Record<string, unknown> | null {
+  const text = rawText.replace(/\r\n/g, '\n');
+  if (!text.startsWith('---')) return null;
+  const endIdx = text.indexOf('\n---', 3);
+  if (endIdx === -1) return null;
+  const fm = text.slice(3, endIdx).trim();
+  try {
+    const parsed = parse(fm);
+    return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Month directory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get current and previous month as { thisYear, thisMonth, prevYear, prevMonth }
+ * All values are zero-padded strings.
+ */
+function getMonthParts(now: Date = new Date()): {
+  thisYear: string;
+  thisMonth: string;
+  prevYear: string;
+  prevMonth: string;
+} {
+  const thisYear = String(now.getFullYear());
+  const thisMonth = String(now.getMonth() + 1).padStart(2, '0');
+
+  const prevDate = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+  const prevYear = String(prevDate.getFullYear());
+  const prevMonth = String(prevDate.getMonth() + 1).padStart(2, '0');
+
+  return { thisYear, thisMonth, prevYear, prevMonth };
+}
+
+// ---------------------------------------------------------------------------
+// File listing helper
+// ---------------------------------------------------------------------------
+
+async function listMdFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir);
+    return entries.filter((e) => e.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core scan logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a given date has a manually-run session log (non-auto-saved).
+ * Returns true if such a log exists.
+ */
+async function hasManualSessionLog(monthDir: string, date: string): Promise<boolean> {
+  const files = await listMdFiles(monthDir);
+  const sessionLogs = files.filter(
+    (f) => f.startsWith(date) && !f.includes('-checkpoint-') && f.endsWith('.md'),
+  );
+
+  for (const logName of sessionLogs) {
+    try {
+      const content = await readFile(join(monthDir, logName), 'utf8');
+      const fm = parseFrontmatter(content);
+      // auto-saved: true → written by auto-summary, NOT a wrapup log → keep scanning
+      if (fm && (fm['auto-saved'] === true || fm['auto-saved'] === 'true')) continue;
+      // Either no frontmatter or auto-saved is false/absent → this is a manual wrapup log
+      return true;
+    } catch {
+      // Can't read — skip
+    }
+  }
+  return false;
+}
+
+/**
+ * Scan one month directory for orphan checkpoints.
+ * Returns a set of orphan session tokens (one per distinct session).
+ */
+async function scanMonthDir(
+  monthDir: string,
+  currentToken: string,
+  today: string,
+  seenTokens: Set<string>,
+): Promise<number> {
+  const files = await listMdFiles(monthDir);
+  const checkpoints = files.filter((f) => f.includes('-checkpoint-') && f.endsWith('.md'));
+
+  let count = 0;
+
+  for (const fname of checkpoints) {
+    // Filename format: YYYY-MM-DD-{token}-checkpoint-{NN}.md
+    const dateMatch = fname.match(/^(\d{4}-\d{2}-\d{2})-/);
+    if (!dateMatch) continue;
+    const fdate = dateMatch[1] ?? '';
+
+    // Extract token: everything between date- prefix and -checkpoint-
+    const afterDate = fname.slice(fdate.length + 1); // strip "YYYY-MM-DD-"
+    const cpIdx = afterDate.indexOf('-checkpoint-');
+    if (cpIdx === -1) continue;
+    const ftoken = afterDate.slice(0, cpIdx);
+    if (!ftoken) continue;
+
+    // Skip today's checkpoints — not orphans yet
+    if (fdate === today) continue;
+
+    // Skip current session's own checkpoints
+    if (ftoken === currentToken) continue;
+
+    // Skip tokens already counted (dedup across multiple checkpoint files per session)
+    if (seenTokens.has(ftoken)) continue;
+
+    // Skip if already merged (read frontmatter)
+    try {
+      const content = await readFile(join(monthDir, fname), 'utf8');
+      const fm = parseFrontmatter(content);
+      if (fm && (fm.merged === true || fm.merged === 'true')) continue;
+    } catch {
+      // Can't read frontmatter — treat as unmerged orphan
+    }
+
+    // Skip if a manual session log covers this date
+    if (await hasManualSessionLog(monthDir, fdate)) continue;
+
+    // Orphan confirmed
+    seenTokens.add(ftoken);
+    count++;
+  }
+
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// runOrphanScan (testable core)
+// ---------------------------------------------------------------------------
+
+/**
+ * Core logic for orphan-scan.
+ * @param logsFolder - absolute path to logs folder
+ * @param sessionToken - current session token to exclude
+ * @returns OrphanScanResult
+ */
+export async function runOrphanScan(
+  logsFolder: string,
+  sessionToken: string,
+): Promise<OrphanScanResult> {
+  const now = new Date();
+  const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  const { thisYear, thisMonth, prevYear, prevMonth } = getMonthParts();
+
+  const monthDirs: Array<{ year: string; month: string }> = [
+    { year: thisYear, month: thisMonth },
+    { year: prevYear, month: prevMonth },
+  ];
+
+  // Dedup tokens across both month dirs
+  const seenTokens = new Set<string>();
+  let totalOrphans = 0;
+
+  for (const { year, month } of monthDirs) {
+    const monthDir = join(logsFolder, year, month);
+    totalOrphans += await scanMonthDir(monthDir, sessionToken, today, seenTokens);
+  }
+
+  return { orphan_count: totalOrphans };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run orphan-scan as a CLI command: print JSON to stdout, always exit 0.
+ */
+export async function orphanScanCommand(logsFolder: string, sessionToken: string): Promise<void> {
+  const result = await runOrphanScan(logsFolder, sessionToken);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}

package/src/internal/qmd-reindex.test.ts

@@ -0,0 +1,117 @@
+/**
+ * qmd-reindex.test.ts — tests for qmd-reindex command
+ */
+
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { qmdReindexCommand } from './qmd-reindex.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function makeTmpDir(): Promise<string> {
+  const base = join(tmpdir(), `ob-qmd-test-${Math.random().toString(36).slice(2)}`);
+  await mkdir(base, { recursive: true });
+  return base;
+}
+
+const VAULT_YML_WITH_COLLECTION = `
+method: onebrain
+update_channel: stable
+qmd_collection: test-collection-123
+folders:
+  inbox: 00-inbox
+  logs: 07-logs
+`.trim();
+
+const VAULT_YML_WITHOUT_COLLECTION = `
+method: onebrain
+update_channel: stable
+folders:
+  inbox: 00-inbox
+  logs: 07-logs
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('qmdReindexCommand', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await makeTmpDir();
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('does not spawn when qmd_collection is absent in vault.yml', async () => {
+    await writeFile(join(tmpDir, 'vault.yml'), VAULT_YML_WITHOUT_COLLECTION, 'utf8');
+
+    const spawnSpy = spyOn(Bun, 'spawn');
+
+    await qmdReindexCommand(tmpDir);
+
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    spawnSpy.mockRestore();
+  });
+
+  it('does not spawn and resolves without throwing when vault.yml is missing', async () => {
+    // No vault.yml in tmpDir
+    const spawnSpy = spyOn(Bun, 'spawn');
+
+    await expect(qmdReindexCommand(tmpDir)).resolves.toBeUndefined();
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    spawnSpy.mockRestore();
+  });
+
+  it('spawns qmd update -c <collection> with detached options and calls unref()', async () => {
+    await writeFile(join(tmpDir, 'vault.yml'), VAULT_YML_WITH_COLLECTION, 'utf8');
+
+    const mockUnref = { called: false };
+    const fakeProc = {
+      unref: () => {
+        mockUnref.called = true;
+      },
+    };
+
+    const spawnSpy = spyOn(Bun, 'spawn').mockImplementation(
+      () => fakeProc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    await qmdReindexCommand(tmpDir);
+
+    expect(spawnSpy).toHaveBeenCalledTimes(1);
+    const [cmd, spawnOpts] = spawnSpy.mock.calls[0] as [string[], Record<string, unknown>];
+    expect(cmd).toEqual(['qmd', 'update', '-c', 'test-collection-123']);
+    expect(spawnOpts).toMatchObject({
+      detached: true,
+      stdin: 'ignore',
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+    expect(mockUnref.called).toBe(true);
+
+    spawnSpy.mockRestore();
+  });
+
+  it('resolves without throwing when Bun.spawn throws', async () => {
+    await writeFile(join(tmpDir, 'vault.yml'), VAULT_YML_WITH_COLLECTION, 'utf8');
+
+    const spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() => {
+      throw new Error('spawn failed');
+    });
+
+    await expect(qmdReindexCommand(tmpDir)).resolves.toBeUndefined();
+
+    spawnSpy.mockRestore();
+  });
+});

package/src/internal/qmd-reindex.ts

@@ -0,0 +1,44 @@
+/**
+ * qmd-reindex — internal command
+ *
+ * Spawns a detached background process to run `qmd update -c <collection>`.
+ * The process runs asynchronously without blocking the CLI.
+ *
+ * Exit behavior:
+ * - Always exits 0 (fire-and-forget)
+ * - Errors written to stderr, exit code always 0
+ * - No stdout output
+ */
+
+import { loadVaultConfig } from '@onebrain/core';
+
+/**
+ * Run qmd-reindex as a CLI command.
+ * Spawns detached background process, always exits 0.
+ */
+export async function qmdReindexCommand(vaultRoot: string): Promise<void> {
+  try {
+    // Load vault config
+    const config = await loadVaultConfig(vaultRoot);
+    const collection = config.qmd_collection;
+
+    // If qmd_collection not set, exit silently (no-op)
+    if (!collection) {
+      return;
+    }
+
+    // Spawn detached background process
+    const proc = Bun.spawn(['qmd', 'update', '-c', collection], {
+      detached: true,
+      stdin: 'ignore',
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+    proc.unref(); // release parent reference — CLI exits immediately
+
+    // Fire-and-forget: do NOT call proc.exited or await anything
+    // Process runs in the background
+  } catch (err) {
+    process.stderr.write(`qmd-reindex: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}