@llmkb/claude-code 0.1.0

package/lib/output.ts

@@ -0,0 +1,130 @@
+/** Output formatting for sync and query commands.
+
+Auto-detects TTY vs pipe output. In TTY mode, renders progress bars
+using ``cli-progress`` and colored output. In pipe/JSON mode, writes
+structured JSON.
+*/
+
+import { stdout } from "node:process";
+import cliProgress from "cli-progress";
+import { success, error, warning, info, muted, label as colorLabel } from "./color.js";
+
+// ---------------------------------------------------------------------------
+// TTY detection
+// ---------------------------------------------------------------------------
+
+/** Whether the current output stream is a TTY (interactive terminal). */
+export function isTTY(): boolean {
+  return stdout.isTTY ?? false;
+}
+
+// ---------------------------------------------------------------------------
+// Progress bar (TTY mode)
+// ---------------------------------------------------------------------------
+
+export interface ProgressBarOptions {
+  /** Total number of items to process. */
+  total: number;
+  /** Label shown in the progress bar. */
+  label?: string;
+}
+
+/** A thin wrapper around cli-progress for sync operations. */
+export class ProgressBar {
+  private bar: cliProgress.SingleBar | null = null;
+  private label: string;
+
+  constructor(opts: ProgressBarOptions) {
+    this.label = opts.label ?? "Progress";
+    if (isTTY()) {
+      this.bar = new cliProgress.SingleBar(
+        {
+          format:
+            `{label} [{bar}] {percentage}% | {value}/{total} | {eta_formatted}`,
+          barCompleteChar: "█",
+          barIncompleteChar: "░",
+          hideCursor: true,
+        },
+        cliProgress.Presets.shades_classic,
+      );
+      this.bar.start(opts.total, 0, { label: this.label });
+    }
+  }
+
+  /** Advance the progress bar by one step. */
+  increment(): void {
+    if (this.bar) this.bar.increment();
+  }
+
+  /** Set the current value directly. */
+  update(value: number): void {
+    if (this.bar) this.bar.update(value);
+  }
+
+  /** Finalise the progress bar. */
+  stop(): void {
+    if (this.bar) this.bar.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON output mode
+// ---------------------------------------------------------------------------
+
+/** A stable schema for ``--json`` output from sync and query commands. */
+export interface JsonResult {
+  command: string;
+  success: boolean;
+  data: unknown;
+  meta?: {
+    durationMs: number;
+    totalItems?: number;
+    processedItems?: number;
+    skippedItems?: number;
+    renamedItems?: number;
+  };
+  error?: string;
+}
+
+/** Write a JSON result to stdout (used in ``--json`` mode). */
+export function writeJson(result: JsonResult): void {
+  stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Line output (TTY mode)
+// ---------------------------------------------------------------------------
+
+/** Write a status line with optional icon (auto-colored by icon type). */
+export function writeLine(message: string, icon?: string): void {
+  if (icon) {
+    stdout.write(`${colorLabel(icon, message)}\n`);
+  } else {
+    stdout.write(`${message}\n`);
+  }
+}
+
+/** Write an indented detail line (dimmed for visual hierarchy). */
+export function writeDetail(message: string): void {
+  stdout.write(`  ${muted(message)}\n`);
+}
+
+/** Write a success line with green checkmark. */
+export function writeSuccess(message: string): void {
+  stdout.write(`${success("✔")} ${success(message)}\n`);
+}
+
+/** Write an error line with red cross. */
+export function writeError(message: string): void {
+  stdout.write(`${error("✖")} ${error(message)}\n`);
+}
+
+/** Write a warning line with yellow warning sign. */
+export function writeWarning(message: string): void {
+  stdout.write(`${warning("⚠")} ${warning(message)}\n`);
+}
+
+/** Write an info line with cyan info symbol. */
+export function writeInfo(message: string): void {
+  stdout.write(`${info("ℹ")} ${info(message)}\n`);
+}

package/lib/parser.ts

@@ -0,0 +1,274 @@
+/** YAML config reader/writer for .llmkb configuration files.
+
+Provides typed, comment-preserving read/write for ``spaces.yml``
+and ``config.yml``, plus a project-root discovery utility.
+
+Uses the ``yaml`` package (eemeli/yaml) which preserves comments,
+formatting, and line positions on round-trip via ``parseDocument``.
+*/
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { parse, stringify, parseDocument } from "yaml";
+import type { SpaceConfig, PluginConfig, ProjectSpaceDef, SpaceDef } from "./types.js";
+import { PACKAGE_VERSION } from "./types.js";
+import { writeFile as writeVersion } from "node:fs/promises";
+
+// ---------------------------------------------------------------------------
+// Project Root Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up from ``startDir`` looking for a ``.llmkb/`` directory.
+ * Returns the first ancestor directory that contains ``.llmkb/``,
+ * or ``null`` if none is found before the filesystem root.
+ */
+export function findProjectRoot(startDir: string = process.cwd()): string | null {
+  let current = resolve(startDir);
+
+  // Safety: stop at filesystem root
+  while (current !== dirname(current)) {
+    if (existsSync(join(current, ".llmkb"))) {
+      return current;
+    }
+    current = dirname(current);
+  }
+  // Check root too (edge case)
+  if (existsSync(join(current, ".llmkb"))) {
+    return current;
+  }
+  return null;
+}
+
+/** Shortcut to get the ``.llmkb/`` directory path from the project root. */
+export function llmkbDir(projectDir: string): string {
+  return join(projectDir, ".llmkb");
+}
+
+// ---------------------------------------------------------------------------
+// Space Config
+// ---------------------------------------------------------------------------
+
+/** Read and parse ``spaces.yml`` from the given project root.
+ *
+ * Automatically migrates old-format files (pre-0.1.0 with ``active`` and
+ * ``spaces[{name, label, access, endpoint, token_env}]``) to the new format
+ * (``project_space`` + ``spaces[{id, name}]``).
+ */
+export async function readSpaceConfig(projectDir: string): Promise<SpaceConfig | null> {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const raw = parse(content) as Record<string, unknown> | null;
+
+    // Comment-only YAML files parse to null — treat as empty config
+    if (raw === null) {
+      return {};
+    }
+
+    // Detect old format: has "active" field or uses name-based SpaceDef
+    if (raw.active !== undefined || isOldSpaceFormat(raw)) {
+      const migrated = migrateOldSpaceConfig(raw);
+      // Write migrated config back and bump version stamp
+      await writeSpaceConfig(projectDir, migrated);
+      await writeVersion(
+        join(projectDir, ".llmkb", ".llmkb-version"),
+        PACKAGE_VERSION + "\n",
+        "utf-8",
+      );
+      return migrated;
+    }
+
+    return raw as SpaceConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** Detect whether a parsed config uses the old space-definition format. */
+function isOldSpaceFormat(raw: Record<string, unknown>): boolean {
+  if (!raw.spaces || !Array.isArray(raw.spaces)) return false;
+  return raw.spaces.length > 0 && typeof raw.spaces[0] === "object" &&
+    raw.spaces[0] !== null && "name" in (raw.spaces[0] as Record<string, unknown>) &&
+    !("id" in (raw.spaces[0] as Record<string, unknown>));
+}
+
+/** Migrate old-format SpaceConfig to new format.
+ *
+ * Old format:
+ *   spaces: [{name, label, access, endpoint, token_env}]
+ *   active: "my-space"
+ *   token_groups: {...}
+ *
+ * New format:
+ *   project_space: [{id, name, dirs}]
+ *   spaces: [{id, name}]
+ */
+function migrateOldSpaceConfig(old: Record<string, unknown>): SpaceConfig {
+  const result: SpaceConfig = {};
+
+  const oldSpaces = (old.spaces as Array<Record<string, unknown>>) ?? [];
+  const activeName = (old.active as string) ?? oldSpaces[0]?.name;
+
+  if (oldSpaces.length > 0) {
+    // If there was an active space, promote it to project_space
+    if (activeName) {
+      const activeDef = oldSpaces.find((s) => s.name === activeName);
+      const projectEntry: ProjectSpaceDef = {
+        id: String(activeDef?.name ?? activeName),
+        name: String(activeDef?.label ?? activeName),
+      };
+      result.project_space = [projectEntry];
+    }
+
+    // All spaces become id-based references
+    result.spaces = oldSpaces.map((s) => ({
+      id: String(s.name),
+      name: s.label ? String(s.label) : String(s.name),
+    }));
+  }
+
+  return result;
+}
+
+/**
+ * Write ``spaces.yml`` from a typed object.
+ * Uses the YAML stringifier for clean output.
+ */
+export async function writeSpaceConfig(
+  projectDir: string,
+  config: SpaceConfig,
+): Promise<void> {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  const yaml = stringify(config, { lineWidth: 120 });
+  await writeFile(filePath, yaml + "\n", "utf-8");
+}
+
+/**
+ * Append a space entry to the ``spaces`` list in ``spaces.yml``.
+ */
+export async function addSpaceEntry(
+  projectDir: string,
+  spaceId: string,
+  spaceName?: string,
+): Promise<boolean> {
+  let config = await readSpaceConfig(projectDir);
+  // Initialize empty config for template/empty YAML
+  if (!config) config = {};
+  if (!config.spaces) config.spaces = [];
+  // Avoid duplicates
+  if (!config.spaces.some((s) => s.id === spaceId)) {
+    config.spaces.push({ id: spaceId, name: spaceName });
+  }
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+
+/**
+ * Remove a space entry from the ``spaces`` list in ``spaces.yml`` by id.
+ */
+export async function removeSpaceEntry(
+  projectDir: string,
+  spaceId: string,
+): Promise<boolean> {
+  const config = await readSpaceConfig(projectDir);
+  if (!config?.spaces) return false;
+  const idx = config.spaces.findIndex((s) => s.id === spaceId);
+  if (idx === -1) return false;
+  config.spaces.splice(idx, 1);
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+
+/**
+ * Update the project_space ID in ``spaces.yml``.
+ */
+export async function updateProjectSpace(
+  projectDir: string,
+  spaceId: string,
+): Promise<boolean> {
+  const config = await readSpaceConfig(projectDir);
+  if (!config) return false;
+  if (!config.project_space || config.project_space.length === 0) {
+    config.project_space = [{ id: spaceId }];
+  } else {
+    config.project_space[0]!.id = spaceId;
+  }
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+
+/**
+ * Delete all space entries from ``spaces.yml``, keeping project_space.
+ */
+export async function deleteAllSpaces(projectDir: string): Promise<boolean> {
+  const config = await readSpaceConfig(projectDir);
+  if (!config) return false;
+  config.spaces = [];
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+
+/**
+ * Update a single field in ``spaces.yml`` while preserving comments.
+ * Uses ``parseDocument`` for comment-safe round-trip.
+ * Returns ``true`` if the field was found and updated.
+ *
+ * Note: In the new data model, the ``active`` field no longer exists.
+ * Use ``updateProjectSpace()`` to update the project space instead.
+ */
+export async function updateSpaceConfigField<T extends keyof SpaceConfig>(
+  projectDir: string,
+  field: T,
+  value: SpaceConfig[T],
+): Promise<boolean> {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  if (!existsSync(filePath)) return false;
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const doc = parseDocument(content);
+    doc.set(field, value);
+    await writeFile(filePath, String(doc) + "\n", "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Config (config.yml)
+// ---------------------------------------------------------------------------
+
+/** Read and parse ``config.yml`` from the given project root. */
+export async function readPluginConfig(projectDir: string): Promise<PluginConfig | null> {
+  const filePath = join(projectDir, ".llmkb", "config.yml");
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return parse(content) as PluginConfig;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Version Stamp
+// ---------------------------------------------------------------------------
+
+/** Read the version stamp from ``.llmkb/.llmkb-version``. */
+export async function readVersionStamp(projectDir: string): Promise<string | null> {
+  const filePath = join(projectDir, ".llmkb", ".llmkb-version");
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return content.trim();
+  } catch {
+    return null;
+  }
+}