@lordierclaw/bluenote-term 0.4.1

package/dist/entry-9xj9qt6a.js

@@ -0,0 +1,1060 @@
+import {
+  AppError,
+  CodexAuthClientError,
+  CodexProviderSetupRequiredError,
+  CodexTextGenerationClientError,
+  EditorLaunchError,
+  UsageError,
+  archiveNote,
+  clipboardy_default,
+  createAiConfigRepository,
+  createAiTextGenerationClient,
+  createCodexAuthClient,
+  createCodexAuthRepository,
+  createNote,
+  createNoteDescription,
+  createNoteRepository,
+  deleteNote,
+  dropDescribeNoteJobIfNoteMissing,
+  enqueueDescribeNoteIfAiEnabled,
+  ensureManagedRoot,
+  formatCodexAuthStatus,
+  generateNoteDescription,
+  initRoot,
+  isValidationOrDataError,
+  listNotes,
+  listPendingAiJobs,
+  listRetryableAiJobs,
+  markDescribeNoteJobFailedIfContentHashMatches,
+  maskApiKey,
+  parsePlainNote,
+  rebuildIndexes,
+  renameNote,
+  resolveBlueNoteRoot,
+  runTuiCli,
+  sanitizeAiErrorMessage,
+  sanitizeCodexAuthErrorMessage,
+  searchNotes,
+  selectNote,
+  showNote,
+  systemClock
+} from "./command-efmr44ky.js";
+import"./command-0v6na3yp.js";
+
+// packages/term/src/core/edit-note.ts
+import path from "node:path";
+
+// packages/term/src/platform/editor.ts
+import { spawnSync } from "node:child_process";
+function resolveEditorCommand(env = process.env) {
+  const editor = env.EDITOR?.trim();
+  if (!editor) {
+    throw new EditorLaunchError("EDITOR is not set.", {
+      hint: "Set EDITOR to a command like 'vim' or 'nano' and retry."
+    });
+  }
+  return editor;
+}
+function parseEditorCommand(editor) {
+  const parts = editor.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  return parts.map((part) => {
+    if (part.startsWith('"') && part.endsWith('"') || part.startsWith("'") && part.endsWith("'")) {
+      return part.slice(1, -1);
+    }
+    return part;
+  });
+}
+function defaultLauncher(command) {
+  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+  if (result.error) {
+    throw new EditorLaunchError(`Could not launch editor '${command[0]}'.`, {
+      hint: "Ensure EDITOR points to an installed executable.",
+      cause: result.error
+    });
+  }
+  return {
+    exitCode: result.status ?? 1
+  };
+}
+function launchEditor(notePath, options = {}) {
+  const editor = resolveEditorCommand(options.env);
+  const launcher = options.launcher ?? defaultLauncher;
+  const command = [...parseEditorCommand(editor), notePath];
+  const result = launcher(command);
+  if (result.exitCode !== 0) {
+    throw new EditorLaunchError(`Editor '${editor}' exited with code ${result.exitCode}.`, {
+      hint: "Fix the editor command or exit the editor successfully, then retry."
+    });
+  }
+}
+
+// packages/term/src/core/edit-note.ts
+function extractEditedTitle(body, fallbackTitle) {
+  const firstMeaningfulLine = body.split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0);
+  if (firstMeaningfulLine && /^#\s+.+$/u.test(firstMeaningfulLine)) {
+    return firstMeaningfulLine.replace(/^#\s+/u, "").trim();
+  }
+  return fallbackTitle;
+}
+function enqueueAiDescriptionAfterEdit(rootPath, input) {
+  enqueueDescribeNoteIfAiEnabled(rootPath, {
+    key: input.key,
+    relativePath: input.relativePath,
+    title: input.title,
+    body: input.body,
+    currentDescription: input.description,
+    replaceKey: input.replaceKey
+  }, { clock: input.clock, warn: (message) => console.warn(message) });
+}
+function editNote(options) {
+  const rootPath = resolveBlueNoteRoot(options);
+  const repository = createNoteRepository(rootPath);
+  const selected = selectNote({ repository, selector: options.selector, visibility: options.visibility });
+  const notePath = path.join(rootPath, selected.sourcePath);
+  const clock = options.clock ?? systemClock;
+  launchEditor(notePath, options);
+  const editedRaw = repository.readRaw(notePath);
+  const edited = parsePlainNote(editedRaw, selected.sourcePath);
+  const title = extractEditedTitle(edited.body, selected.frontmatter.title);
+  const updatedAt = clock.now().toISOString();
+  const titleChanged = title !== selected.frontmatter.title;
+  const bodyChanged = edited.body !== selected.body;
+  if (titleChanged) {
+    const renamed = renameNote({
+      override: rootPath,
+      selector: options.selector,
+      title,
+      body: edited.body,
+      updatedAt,
+      visibility: options.visibility,
+      randomSource: options.randomSource
+    });
+    rebuildIndexes({ override: rootPath });
+    enqueueAiDescriptionAfterEdit(rootPath, {
+      key: renamed.key,
+      title,
+      body: edited.body,
+      description: createNoteDescription(edited.body),
+      relativePath: renamed.relativePath,
+      clock,
+      replaceKey: renamed.previousKey
+    });
+    return {
+      rootPath,
+      notePath: renamed.notePath,
+      relativePath: renamed.relativePath,
+      previousKey: renamed.previousKey,
+      key: renamed.key
+    };
+  }
+  const synced = repository.syncEditedNote(notePath, {
+    title,
+    body: edited.body,
+    updatedAt
+  });
+  rebuildIndexes({ override: rootPath });
+  if (bodyChanged) {
+    enqueueAiDescriptionAfterEdit(rootPath, {
+      key: selected.frontmatter.id,
+      title,
+      body: edited.body,
+      description: createNoteDescription(edited.body),
+      relativePath: synced.relativePath,
+      clock
+    });
+  }
+  return {
+    rootPath,
+    notePath: synced.notePath,
+    relativePath: synced.relativePath,
+    previousKey: selected.frontmatter.id,
+    key: selected.frontmatter.id
+  };
+}
+
+// packages/term/src/platform/clipboard.ts
+var desktopClipboard = {
+  readText() {
+    return clipboardy_default.readSync();
+  }
+};
+
+// packages/term/src/cli/ai.ts
+var PLAINTEXT_WARNING = [
+  "Warning: API key is stored in plaintext under .data/ai/config.json.",
+  "Do not commit or share your BlueNote managed root if it contains secrets."
+].join(`
+`);
+function formatAiHelp() {
+  return [
+    "Opt-in AI description generation for BlueNote notes.",
+    "",
+    "Usage:",
+    "  bn ai <command> [options]",
+    "",
+    "Commands:",
+    "  config set     [--provider openai-compatible] --base-url <url> --api-key <key> --model <model> [--max-attempts <n>] [--output-language <text>]  Configure OpenAI-compatible AI",
+    "  config set     --provider codex --model <model> [--max-attempts <n>] [--output-language <text>]  Configure Codex AI model selection",
+    "  config show    Show configured provider settings with the API key masked",
+    "  codex auth login   Authenticate Codex with device-code OAuth",
+    "  codex auth status  Show Codex auth status without secrets",
+    "  codex auth logout  Remove stored Codex auth while keeping AI config",
+    "  describe       <key|path>  Generate and automatically apply a note description",
+    "  queue          Show pending AI description jobs",
+    "  process-queue  [--limit <n>]  Process queued description refreshes",
+    "",
+    "AI is disabled until configured. Core BlueNote commands work offline; AI provider calls require network access."
+  ].join(`
+`) + `
+`;
+}
+function readFlagValue(args, flagName) {
+  const flagIndex = args.indexOf(flagName);
+  if (flagIndex === -1) {
+    return;
+  }
+  const value = args[flagIndex + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new UsageError(`Missing value for ${flagName}.`, {
+      hint: `Pass ${flagName} "...".`
+    });
+  }
+  return value;
+}
+function requireFlag(args, flagName, hint) {
+  const value = readFlagValue(args, flagName);
+  if (!value) {
+    throw new UsageError(`Missing required ${flagName} for AI config.`, { hint });
+  }
+  return value;
+}
+function parseLimit(args) {
+  const raw = readFlagValue(args, "--limit");
+  if (raw === undefined) {
+    return;
+  }
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new UsageError("Invalid --limit for AI queue processing.", {
+      hint: "Run bn ai process-queue --limit <positive-integer>."
+    });
+  }
+  return limit;
+}
+function parsePositiveIntegerFlag(args, flagName) {
+  const raw = readFlagValue(args, flagName);
+  if (raw === undefined) {
+    return;
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > 10) {
+    throw new UsageError(`Invalid ${flagName} for AI config.`, {
+      hint: `Run bn ai config set ${flagName} <integer-from-1-to-10>.`
+    });
+  }
+  return value;
+}
+function readOptionalOutputLanguage(args) {
+  const value = readFlagValue(args, "--output-language");
+  if (value === undefined)
+    return;
+  if (value.trim() === "") {
+    throw new UsageError("Invalid --output-language for AI config.", {
+      hint: "Pass a non-empty language preference string."
+    });
+  }
+  return value;
+}
+var DEFAULT_AI_LOGGING = {
+  usage: true,
+  conversations: false,
+  results: true
+};
+function createDefaultConfig(input) {
+  const existingOpenAiConfig = input.existing?.provider === "openai-compatible" ? input.existing : null;
+  return {
+    version: 1,
+    enabled: existingOpenAiConfig?.enabled ?? true,
+    provider: "openai-compatible",
+    baseUrl: input.baseUrl,
+    apiKey: input.apiKey,
+    model: input.model,
+    logging: existingOpenAiConfig?.logging ?? DEFAULT_AI_LOGGING,
+    maxAttempts: input.maxAttempts ?? input.existing?.maxAttempts ?? 3,
+    outputLanguage: input.outputLanguage ?? input.existing?.outputLanguage ?? "English"
+  };
+}
+function createCodexConfig(input) {
+  const existingCodexConfig = input.existing?.provider === "codex" ? input.existing : null;
+  return {
+    version: 1,
+    enabled: existingCodexConfig?.enabled ?? true,
+    provider: "codex",
+    model: input.model,
+    logging: existingCodexConfig?.logging ?? DEFAULT_AI_LOGGING,
+    maxAttempts: input.maxAttempts ?? input.existing?.maxAttempts ?? 3,
+    outputLanguage: input.outputLanguage ?? input.existing?.outputLanguage ?? "English"
+  };
+}
+function getConfiguredRootPath() {
+  return ensureManagedRoot(resolveBlueNoteRoot());
+}
+function requireAiConfig(rootPath) {
+  if (!createAiConfigRepository(rootPath).exists()) {
+    throw new UsageError("AI is not configured.", {
+      hint: "Run bn ai config set --base-url <url> --api-key <key> --model <model>. For Codex, run bn ai config set --provider codex --model <model>."
+    });
+  }
+}
+function requireCodexConfig(rootPath) {
+  requireAiConfig(rootPath);
+  const config = createAiConfigRepository(rootPath).read();
+  if (config.provider !== "codex") {
+    throw new UsageError("Codex is not the configured AI provider.", {
+      hint: "Run bn ai config set --provider codex --model <model> before Codex auth commands."
+    });
+  }
+  return config;
+}
+function getAiClient(config, runtime) {
+  if (runtime.aiClient) {
+    return runtime.aiClient;
+  }
+  if (config.provider === "codex") {
+    const rootPath = getConfiguredRootPath();
+    const repository = createCodexAuthRepository(rootPath, runtime.codexAuth);
+    const authClient = createCodexAuthClient({
+      ...runtime.codexAuth,
+      fetch: runtime.fetch ?? fetch,
+      repository
+    });
+    return createAiTextGenerationClient(config, {
+      fetch: runtime.fetch ?? fetch,
+      codexAuth: {
+        hasAuth: () => repository.exists(),
+        async getAuth() {
+          return repository.exists() ? repository.read() : null;
+        },
+        async refreshAuth(auth) {
+          const refreshed = await authClient.refreshAuth(auth);
+          repository.write(refreshed);
+          return refreshed;
+        }
+      }
+    });
+  }
+  return createAiTextGenerationClient(config, { fetch: runtime.fetch ?? fetch });
+}
+function formatConfig(config) {
+  return [
+    "AI config:",
+    `  enabled: ${config.enabled}`,
+    `  provider: ${config.provider}`,
+    `  model: ${config.model}`,
+    ...config.provider === "openai-compatible" ? [
+      `  baseUrl: ${config.baseUrl}`,
+      `  apiKey: ${maskApiKey(config.apiKey)}`
+    ] : [],
+    `  logging.usage: ${config.logging.usage}`,
+    `  logging.conversations: ${config.logging.conversations}`,
+    `  logging.results: ${config.logging.results}`,
+    `  maxAttempts: ${config.maxAttempts ?? 3}`,
+    `  outputLanguage: ${config.outputLanguage ?? "English"}`
+  ].join(`
+`) + `
+`;
+}
+function formatPendingJobs(jobs) {
+  if (jobs.length === 0) {
+    return `Pending AI jobs: 0
+`;
+  }
+  return [
+    `Pending AI jobs: ${jobs.length}`,
+    ...jobs.map((job) => `${job.kind}	${job.key}	${job.relativePath}	attempts=${job.attempts}`)
+  ].join(`
+`) + `
+`;
+}
+function markJobFailed(rootPath, job, error, secrets = []) {
+  const message = sanitizeAiErrorMessage(error, secrets);
+  return markDescribeNoteJobFailedIfContentHashMatches({
+    rootPath,
+    key: job.key,
+    contentHash: job.contentHash,
+    lastError: message
+  });
+}
+function describeOutput(result) {
+  if (result.status === "applied" && result.description) {
+    return {
+      exitCode: 0,
+      stdout: `Updated AI description for ${result.key}
+Description: ${result.description}
+`,
+      stderr: ""
+    };
+  }
+  if (result.status === "stale") {
+    throw new UsageError(`AI description result was stale: ${result.error ?? "note changed while AI description was generating"}.`, {
+      hint: "The existing note description was left unchanged. Run bn ai describe again to refresh it."
+    });
+  }
+  throw new UsageError(result.error ?? "Provider returned an invalid description.", {
+    hint: "The existing note description was left unchanged."
+  });
+}
+function providerFailureError(error, secrets = []) {
+  return new UsageError(`AI provider request failed: ${sanitizeAiErrorMessage(error, secrets)}`, {
+    hint: "The existing note description was left unchanged."
+  });
+}
+function isCodexProviderSetupBlocked(error) {
+  if (error instanceof CodexProviderSetupRequiredError) {
+    return true;
+  }
+  if (!(error instanceof CodexTextGenerationClientError)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("codex auth setup is required") || message.includes("codex auth refresh failed") || message.includes("codex auth is expired") || message.includes("run bn ai codex auth login");
+}
+async function runConfigCommand(args) {
+  const [subcommand, ...subcommandArgs] = args;
+  const rootPath = getConfiguredRootPath();
+  const repository = createAiConfigRepository(rootPath);
+  if (subcommand === "set") {
+    const existingConfig = repository.exists() ? repository.read() : null;
+    const provider = readFlagValue(subcommandArgs, "--provider") ?? existingConfig?.provider ?? "openai-compatible";
+    if (provider !== "openai-compatible" && provider !== "codex") {
+      throw new UsageError("Invalid AI provider.", {
+        hint: "Use --provider openai-compatible or --provider codex."
+      });
+    }
+    const maxAttempts = parsePositiveIntegerFlag(subcommandArgs, "--max-attempts");
+    const outputLanguage = readOptionalOutputLanguage(subcommandArgs);
+    const config = provider === "codex" ? createCodexConfig({
+      model: readFlagValue(subcommandArgs, "--model") ?? (existingConfig?.provider === "codex" ? existingConfig.model : undefined) ?? requireFlag(subcommandArgs, "--model", "Run bn ai config set --provider codex --model <model>."),
+      maxAttempts,
+      outputLanguage,
+      existing: existingConfig
+    }) : createDefaultConfig({
+      baseUrl: readFlagValue(subcommandArgs, "--base-url") ?? (existingConfig?.provider === "openai-compatible" ? existingConfig.baseUrl : undefined) ?? requireFlag(subcommandArgs, "--base-url", "Run bn ai config set --base-url <url> --api-key <key> --model <model>."),
+      apiKey: readFlagValue(subcommandArgs, "--api-key") ?? (existingConfig?.provider === "openai-compatible" ? existingConfig.apiKey : undefined) ?? requireFlag(subcommandArgs, "--api-key", "Run bn ai config set --base-url <url> --api-key <key> --model <model>."),
+      model: readFlagValue(subcommandArgs, "--model") ?? (existingConfig?.provider === "openai-compatible" ? existingConfig.model : undefined) ?? requireFlag(subcommandArgs, "--model", "Run bn ai config set --base-url <url> --api-key <key> --model <model>."),
+      maxAttempts,
+      outputLanguage,
+      existing: existingConfig
+    });
+    repository.write(config);
+    return {
+      exitCode: 0,
+      stdout: config.provider === "codex" ? `AI Codex config saved. Run bn ai codex auth login before Codex generation.
+` : `AI config saved.
+${PLAINTEXT_WARNING}
+`,
+      stderr: ""
+    };
+  }
+  if (subcommand === "show") {
+    requireAiConfig(rootPath);
+    return { exitCode: 0, stdout: formatConfig(repository.read()), stderr: "" };
+  }
+  throw new UsageError(`Unknown AI config command: ${subcommand ?? ""}`.trim(), {
+    hint: "Run bn ai config set ... or bn ai config show."
+  });
+}
+function assertNoExtraArgs(args, command) {
+  if (args.length > 0) {
+    throw new UsageError(`Unexpected arguments for ${command}.`, {
+      hint: `Run ${command}.`
+    });
+  }
+}
+async function runCodexAuthCommand(args, runtime) {
+  const [subcommand, ...subcommandArgs] = args;
+  const rootPath = getConfiguredRootPath();
+  const config = requireCodexConfig(rootPath);
+  const repository = createCodexAuthRepository(rootPath, runtime.codexAuth);
+  if (subcommand === "status") {
+    assertNoExtraArgs(subcommandArgs, "bn ai codex auth status");
+    return {
+      exitCode: 0,
+      stdout: `${formatCodexAuthStatus(repository.getStatus({ provider: config.provider }))}
+`,
+      stderr: ""
+    };
+  }
+  if (subcommand === "login") {
+    assertNoExtraArgs(subcommandArgs, "bn ai codex auth login");
+    const outputLines = [];
+    const shouldStream = runtime.writeStdout !== undefined || runtime.fetch === undefined && runtime.codexAuth === undefined && runtime.aiClient === undefined;
+    const writeInteractive = (line) => {
+      if (shouldStream) {
+        (runtime.writeStdout ?? process.stdout.write.bind(process.stdout))(`${line}
+`);
+        return;
+      }
+      outputLines.push(line);
+    };
+    const client = createCodexAuthClient({
+      ...runtime.codexAuth,
+      fetch: runtime.fetch ?? fetch,
+      repository
+    });
+    try {
+      await client.login({
+        onDeviceFlow(flow) {
+          writeInteractive(`Open ${flow.verificationUrl} and enter code ${flow.userCode}.`);
+          writeInteractive("Waiting for Codex authentication to complete...");
+        }
+      });
+    } catch (error) {
+      const message = error instanceof CodexAuthClientError ? sanitizeCodexAuthErrorMessage(error) : sanitizeCodexAuthErrorMessage(error);
+      throw new UsageError(`Codex auth login failed: ${message}`, {
+        hint: "Check network access and retry bn ai codex auth login."
+      });
+    }
+    const completeLine = "Codex auth login complete.";
+    outputLines.push(completeLine);
+    return { exitCode: 0, stdout: `${outputLines.join(`
+`)}
+`, stderr: "" };
+  }
+  if (subcommand === "logout") {
+    assertNoExtraArgs(subcommandArgs, "bn ai codex auth logout");
+    repository.delete();
+    return { exitCode: 0, stdout: `Codex auth removed. Codex AI config was kept.
+`, stderr: "" };
+  }
+  throw new UsageError("Unknown AI Codex auth command.", {
+    hint: "Run bn ai codex auth login, bn ai codex auth status, or bn ai codex auth logout."
+  });
+}
+async function runAiCli(args, runtime = {}) {
+  const [subcommand, ...subcommandArgs] = args;
+  if (!subcommand || subcommand === "--help" || subcommand === "help") {
+    return { exitCode: 0, stdout: formatAiHelp(), stderr: "" };
+  }
+  if (subcommand === "config") {
+    return runConfigCommand(subcommandArgs);
+  }
+  if (subcommand === "codex") {
+    if (subcommandArgs[0] === "auth") {
+      return runCodexAuthCommand(subcommandArgs.slice(1), runtime);
+    }
+    throw new UsageError("Unknown AI Codex command.", {
+      hint: "Run bn ai codex auth login, bn ai codex auth status, or bn ai codex auth logout."
+    });
+  }
+  if (subcommand === "queue") {
+    const rootPath = getConfiguredRootPath();
+    return { exitCode: 0, stdout: formatPendingJobs(listPendingAiJobs(rootPath)), stderr: "" };
+  }
+  if (subcommand === "describe") {
+    const selector = subcommandArgs[0];
+    if (!selector) {
+      throw new UsageError("Missing required selector for AI describe.", {
+        hint: "Run bn ai describe <key|path>."
+      });
+    }
+    const rootPath = getConfiguredRootPath();
+    requireAiConfig(rootPath);
+    const config = createAiConfigRepository(rootPath).read();
+    if (!config.enabled) {
+      throw new UsageError("AI description generation is disabled.", {
+        hint: "Enable AI in .data/ai/config.json before generating note descriptions."
+      });
+    }
+    const secrets = config.provider === "openai-compatible" ? [config.apiKey] : [];
+    try {
+      return describeOutput(await generateNoteDescription({ rootPath, selector, client: getAiClient(config, runtime) }));
+    } catch (error) {
+      if (error instanceof UsageError) {
+        throw error;
+      }
+      throw providerFailureError(error, secrets);
+    }
+  }
+  if (subcommand === "process-queue") {
+    const rootPath = getConfiguredRootPath();
+    requireAiConfig(rootPath);
+    const config = createAiConfigRepository(rootPath).read();
+    const limit = parseLimit(subcommandArgs);
+    if (!config.enabled) {
+      const remaining2 = listPendingAiJobs(rootPath).length;
+      return {
+        exitCode: remaining2 > 0 ? 1 : 0,
+        stdout: `Processed AI queue: 0 applied, 0 failed, ${remaining2} remaining.
+`,
+        stderr: ""
+      };
+    }
+    const secrets = config.provider === "openai-compatible" ? [config.apiKey] : [];
+    const jobs = listRetryableAiJobs(rootPath, config.maxAttempts ?? 3);
+    const selectedJobs = jobs.slice(0, limit ?? jobs.length);
+    let applied = 0;
+    let failed = 0;
+    let setupBlocked = false;
+    for (const job of selectedJobs) {
+      try {
+        if (dropDescribeNoteJobIfNoteMissing(rootPath, job)) {
+          continue;
+        }
+        const result = await generateNoteDescription({ rootPath, selector: job.key, client: getAiClient(config, runtime) });
+        if (result.status === "applied") {
+          applied += 1;
+        } else if (result.status === "stale") {} else {
+          if (markJobFailed(rootPath, job, result.error ?? "invalid description", secrets)) {
+            failed += 1;
+          }
+        }
+      } catch (error) {
+        if (isCodexProviderSetupBlocked(error)) {
+          setupBlocked = true;
+          continue;
+        }
+        if (markJobFailed(rootPath, job, error, secrets)) {
+          failed += 1;
+        }
+      }
+    }
+    const remaining = listPendingAiJobs(rootPath).length;
+    return {
+      exitCode: failed > 0 || setupBlocked ? 1 : 0,
+      stdout: `Processed AI queue: ${applied} applied, ${failed} failed, ${remaining} remaining.
+`,
+      stderr: ""
+    };
+  }
+  throw new UsageError(`Unknown AI command: ${subcommand ?? ""}`.trim(), {
+    hint: "Run bn ai config set, bn ai config show, bn ai describe, bn ai queue, or bn ai process-queue."
+  });
+}
+
+// packages/term/src/cli/entry.ts
+function formatCliError(error) {
+  const messageLines = [error.message];
+  if (error.hint) {
+    messageLines.push(`Hint: ${error.hint}`);
+  }
+  return {
+    exitCode: isValidationOrDataError(error) ? 2 : 1,
+    stdout: "",
+    stderr: `${messageLines.join(`
+`)}
+`
+  };
+}
+function parseVisibilityArgs(args) {
+  let visibility = "normal";
+  let index = 0;
+  for (;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--drafts") {
+      if (visibility === "all") {
+        throw new UsageError("Choose either --drafts or --all, not both.", {
+          hint: "Use --drafts for normal + draft notes, or --all to include archived notes."
+        });
+      }
+      visibility = "drafts";
+      continue;
+    }
+    if (arg === "--all") {
+      if (visibility === "drafts") {
+        throw new UsageError("Choose either --drafts or --all, not both.", {
+          hint: "Use --drafts for normal + draft notes, or --all to include archived notes."
+        });
+      }
+      visibility = "all";
+      continue;
+    }
+    break;
+  }
+  return { args: args.slice(index), visibility };
+}
+function parseSelectorArgs(command, args, options = {}) {
+  const selectors = [];
+  let force = false;
+  let visibility = "normal";
+  for (const arg of args) {
+    if (arg === "--drafts") {
+      if (visibility === "all") {
+        throw new UsageError("Choose either --drafts or --all, not both.", {
+          hint: "Use --drafts for normal + draft notes, or --all to include archived notes."
+        });
+      }
+      visibility = "drafts";
+      continue;
+    }
+    if (arg === "--all") {
+      if (visibility === "drafts") {
+        throw new UsageError("Choose either --drafts or --all, not both.", {
+          hint: "Use --drafts for normal + draft notes, or --all to include archived notes."
+        });
+      }
+      visibility = "all";
+      continue;
+    }
+    if (arg === "--force") {
+      if (!options.requireForce) {
+        throw new UsageError(`${command} does not accept --force.`, {
+          hint: `Run bn ${command} <key|path>.`
+        });
+      }
+      force = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new UsageError(`Unknown option for ${command}: ${arg}.`, {
+        hint: `Run bn ${command} <key|path>${options.requireForce ? " --force" : ""}.`
+      });
+    }
+    selectors.push(arg);
+  }
+  if (selectors.length === 0) {
+    throw new UsageError(`Missing required selector for ${command}.`, {
+      hint: `Run bn ${command} <key|path>${options.requireForce ? " --force" : ""}.`
+    });
+  }
+  if (selectors.length > 1) {
+    throw new UsageError(`Too many selectors for ${command}.`, {
+      hint: `Run bn ${command} <key|path>${options.requireForce ? " --force" : ""}.`
+    });
+  }
+  return { selector: selectors[0], force, visibility };
+}
+function parseNewArgs(args) {
+  const positional = [];
+  let title;
+  let destinationPath;
+  let useClipboard = false;
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--title" || arg === "-t") {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("-")) {
+        throw new UsageError(`Missing value for ${arg}.`, { hint: 'Pass --title "..." or -t "...".' });
+      }
+      title = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--path") {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new UsageError("Missing value for --path.", { hint: "Pass --path note/<folder>." });
+      }
+      destinationPath = value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--clipboard") {
+      useClipboard = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new UsageError(`Unknown option for new note: ${arg}.`, {
+        hint: "Run bn new --help for available new-note options."
+      });
+    }
+    positional.push(arg);
+  }
+  if (positional.length > 1) {
+    throw new UsageError("Too many positional body arguments for new note.", {
+      hint: 'Quote the note body as one argument, e.g. bn new "Body text".'
+    });
+  }
+  return { title, path: destinationPath, useClipboard, body: positional[0] };
+}
+function readNewNoteBody(parsed, runtime) {
+  const hasPositionalBody = parsed.body !== undefined;
+  if (hasPositionalBody && parsed.useClipboard) {
+    throw new UsageError("Choose either positional body or --clipboard, not both.", {
+      hint: 'Run bn new "Body text" or bn new --clipboard.'
+    });
+  }
+  if (!hasPositionalBody && !parsed.useClipboard) {
+    throw new UsageError("Missing note body for new note.", {
+      hint: 'Pass a positional body or use --clipboard, e.g. bn new "Body text".'
+    });
+  }
+  if (hasPositionalBody) {
+    return parsed.body ?? "";
+  }
+  try {
+    const clipboardBody = (runtime.clipboard ?? desktopClipboard).readText();
+    if (clipboardBody.length === 0) {
+      throw new UsageError("Clipboard is empty or unavailable.", {
+        hint: 'Copy note text first, or pass a body directly with bn new "Body text".'
+      });
+    }
+    return clipboardBody;
+  } catch (error) {
+    if (error instanceof UsageError)
+      throw error;
+    throw new UsageError("Clipboard is empty or unavailable.", {
+      hint: 'Copy note text first, or pass a body directly with bn new "Body text".',
+      cause: error
+    });
+  }
+}
+function assertNewNotePathIsAllowed(destinationPath, title) {
+  if (destinationPath === undefined) {
+    return;
+  }
+  if (title === undefined || title.trim().length === 0) {
+    throw new UsageError("--path requires --title for normal note creation.", {
+      hint: 'Run bn new --path note/<folder> --title "Title" "Body text".'
+    });
+  }
+  if (destinationPath !== "note" && !destinationPath.startsWith("note/")) {
+    throw new UsageError("--path must point to an existing folder under note/.", {
+      hint: "Use --path note or an existing note/<folder> destination."
+    });
+  }
+}
+function formatHelp(version) {
+  return [
+    `BlueNote v${version}`,
+    "Local-first terminal notes for plain-note storage and selector-friendly workflows",
+    "",
+    "Usage:",
+    "  bn <command> [options]",
+    "",
+    "Commands:",
+    "  --help       Show this message",
+    "  --version    Print the current version",
+    "  init         Initialize the managed BlueNote root",
+    "  new          [--title <title>] [--path note/<folder>] [--clipboard] <body>",
+    "               Create a draft from body text or clipboard; --path creates a normal note",
+    "  list         [--drafts|--all]  List notes as title, key, description, and path",
+    "  show         [--drafts|--all] <key|path>  Print a matching note summary and body",
+    "  search       [--drafts|--all] <query>  Search indexed notes",
+    "  edit         [--drafts|--all] <key|path>  Open a matching note in $EDITOR",
+    "  archive      [--drafts|--all] <key|path>  Archive a matching normal note",
+    "  delete       [--drafts|--all] <key|path> --force  Permanently remove a matching note and sidecar",
+    "  rebuild      Rebuild derived metadata and search indexes",
+    "  tui          Launch the terminal UI workspace",
+    "  ai           Configure and run opt-in AI description generation"
+  ].join(`
+`) + `
+`;
+}
+function formatNewHelp() {
+  return [
+    "Usage:",
+    "  bn new [--title <title>] [--path note/<folder>] [--clipboard] <body>",
+    "",
+    "Creates a new note from quoted body text or clipboard text.",
+    "Without --path, creates a draft under draft/.",
+    "With --path note/<folder> and --title, creates a normal note under an existing note folder.",
+    "",
+    "Options:",
+    "  --title, -t <title>  Set the note title",
+    "  --path <folder>     Existing note/<folder> destination for a normal note",
+    "  --clipboard         Read note body from the clipboard"
+  ].join(`
+`) + `
+`;
+}
+async function runCliAsync(args, version, runtime = {}) {
+  try {
+    if (args[0] === "ai") {
+      return await runAiCli(args.slice(1), runtime.ai);
+    }
+    return runCli(args, version, runtime);
+  } catch (error) {
+    if (error instanceof AppError) {
+      return formatCliError(error);
+    }
+    throw error;
+  }
+}
+function formatSearchMatches(query, matches) {
+  if (matches.length === 0) {
+    return `No notes matched "${query}".
+`;
+  }
+  return matches.map((match) => {
+    const lines = [
+      match.title,
+      `  key: ${match.key}`,
+      `  path: ${match.relativePath}`,
+      `  match: ${match.match.label}`
+    ];
+    if (match.match.excerpt) {
+      lines.push("  excerpt:");
+      lines.push(`    ${match.match.excerpt}`);
+    }
+    return lines.join(`
+`);
+  }).join(`
+
+`) + `
+`;
+}
+function runCli(args, version, runtime = {}) {
+  try {
+    const [command, ...commandArgs] = args;
+    if (!command || command === "--help" || command === "help") {
+      return { exitCode: 0, stdout: formatHelp(version), stderr: "" };
+    }
+    if (command === "--version" || command === "version") {
+      return { exitCode: 0, stdout: `${version}
+`, stderr: "" };
+    }
+    if (command === "init") {
+      const summary = initRoot();
+      return {
+        exitCode: 0,
+        stdout: `Initialized BlueNote root: ${summary.rootPath}
+`,
+        stderr: ""
+      };
+    }
+    if (command === "tui") {
+      return (runtime.tuiRunner ?? runTuiCli)();
+    }
+    if (command === "new") {
+      if (commandArgs.length === 1 && commandArgs[0] === "--help") {
+        return { exitCode: 0, stdout: formatNewHelp(), stderr: "" };
+      }
+      const parsed = parseNewArgs(commandArgs);
+      const body = readNewNoteBody(parsed, runtime);
+      assertNewNotePathIsAllowed(parsed.path, parsed.title);
+      const summary = createNote({
+        title: parsed.title,
+        body,
+        type: parsed.path === undefined ? "draft" : "normal",
+        ...parsed.path === undefined ? {} : { destinationFolder: parsed.path },
+        ...runtime.createNoteOptions
+      });
+      return {
+        exitCode: 0,
+        stdout: `Created note
+Key: ${summary.key}
+Path: ${summary.relativePath}
+`,
+        stderr: ""
+      };
+    }
+    if (command === "edit") {
+      const { selector, visibility } = parseSelectorArgs("edit", commandArgs);
+      const summary = editNote({ selector, visibility });
+      const renameLine = summary.previousKey !== undefined && summary.key !== undefined && summary.previousKey !== summary.key ? `Renamed key: ${summary.previousKey} -> ${summary.key}
+` : "";
+      return {
+        exitCode: 0,
+        stdout: `Edited note: ${summary.relativePath}
+${renameLine}`,
+        stderr: ""
+      };
+    }
+    if (command === "archive") {
+      const { selector, visibility } = parseSelectorArgs("archive", commandArgs);
+      const summary = archiveNote({ selector, visibility });
+      return {
+        exitCode: 0,
+        stdout: `Archived note: ${summary.relativePath}
+`,
+        stderr: ""
+      };
+    }
+    if (command === "delete") {
+      const { selector, force, visibility } = parseSelectorArgs("delete", commandArgs, { requireForce: true });
+      const summary = deleteNote({
+        selector,
+        force,
+        visibility
+      });
+      return {
+        exitCode: 0,
+        stdout: `Deleted note: ${summary.relativePath}
+`,
+        stderr: ""
+      };
+    }
+    if (command === "list") {
+      const parsedVisibility = parseVisibilityArgs(commandArgs);
+      if (parsedVisibility.args.length > 0) {
+        throw new UsageError(`Unknown option for list: ${parsedVisibility.args[0]}.`, {
+          hint: "Run bn list [--drafts|--all]."
+        });
+      }
+      const summaries = listNotes({ visibility: parsedVisibility.visibility });
+      const stdout = summaries.map((summary) => `${summary.title}	${summary.key}	${summary.description}	${summary.relativePath}`).join(`
+`);
+      return {
+        exitCode: 0,
+        stdout: stdout === "" ? "" : `${stdout}
+`,
+        stderr: ""
+      };
+    }
+    if (command === "search") {
+      const parsedVisibility = parseVisibilityArgs(commandArgs);
+      const query = parsedVisibility.args.join(" ").trim();
+      if (query === "") {
+        throw new UsageError("Missing required query for search.", {
+          hint: 'Run bn search [--drafts|--all] "keywords".'
+        });
+      }
+      const matches = searchNotes(query, { visibility: parsedVisibility.visibility });
+      return {
+        exitCode: 0,
+        stdout: formatSearchMatches(query, matches),
+        stderr: ""
+      };
+    }
+    if (command === "show") {
+      const { selector, visibility } = parseSelectorArgs("show", commandArgs);
+      const shown = showNote({ selector, visibility });
+      return {
+        exitCode: 0,
+        stdout: `Title: ${shown.title}
+Key: ${shown.key}
+Path: ${shown.relativePath}
+Description: ${shown.description}
+
+${shown.body}`,
+        stderr: ""
+      };
+    }
+    if (command === "rebuild") {
+      const summary = rebuildIndexes(runtime.rebuildIndexesOptions);
+      if (summary.validationErrors.length > 0) {
+        return {
+          exitCode: 2,
+          stdout: "",
+          stderr: `Validation failed while rebuilding indexes.
+${summary.validationErrors.join(`
+`)}
+`
+        };
+      }
+      return {
+        exitCode: 0,
+        stdout: `Rebuilt indexes for ${summary.noteCount} note(s).
+`,
+        stderr: ""
+      };
+    }
+    return formatCliError(new UsageError(`Unknown command: ${command}`, {
+      hint: "Use --help to see available commands."
+    }));
+  } catch (error) {
+    if (error instanceof AppError) {
+      return formatCliError(error);
+    }
+    throw error;
+  }
+}
+export {
+  runCliAsync,
+  runCli,
+  formatSearchMatches,
+  formatNewHelp,
+  formatHelp,
+  formatCliError
+};