@hiai-gg/docsmint 0.3.0

package/packages/cli/src/commands/delete.ts

@@ -0,0 +1,37 @@
+/**
+ * `hiai-docs delete <id>` — soft confirmation before issuing DELETE.
+ *
+ * The backend has no soft-delete; this is irreversible, so we
+ * prompt unless the user passes `--yes` (or `-y`). The prompt is
+ * skipped automatically when stdin isn't a TTY (e.g. piping from
+ * CI) so the command remains scriptable.
+ */
+
+import type { Command } from "commander";
+import { isatty } from "node:tty";
+import { client, type HiaiDocsClient } from "../client.js";
+import { confirm, formatError, green } from "../format.js";
+
+export function registerDelete(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("delete <id>")
+		.description("Delete a document (irreversible)")
+		.option("-y, --yes", "Skip confirmation prompt")
+		.action(async (id: string, opts: { yes?: boolean }) => {
+			try {
+				const interactive = isatty(0) && isatty(1);
+				if (interactive && !opts.yes) {
+					const ok = await confirm(`Delete document ${id}? This cannot be undone.`);
+					if (!ok) {
+						process.stdout.write("Cancelled.\n");
+						return;
+					}
+				}
+				await client.deleteDocument(id);
+				process.stdout.write(`${green("✓")} Deleted ${id}\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/export.ts

@@ -0,0 +1,36 @@
+/**
+ * `hiai-docs export <id>` — write a document's markdown body.
+ *
+ * Defaults to stdout for piping. `--output <file>` writes to a
+ * file; the existing file is overwritten silently.
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, green } from "../format.js";
+
+export function registerExport(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("export <id>")
+		.description("Export a document's markdown")
+		.option("-o, --output <file>", "Write to file (default: stdout)")
+		.action(async (id: string, opts: { output?: string }) => {
+			try {
+				const md = await client.exportDocument(id);
+				if (opts.output) {
+					if (existsSync(opts.output)) {
+						// Confirm before clobbering — but stay scriptable.
+						process.stderr.write(`Overwriting ${opts.output}\n`);
+					}
+					writeFileSync(opts.output, md, "utf-8");
+					process.stdout.write(`${green("✓")} Wrote ${opts.output}\n`);
+				} else {
+					process.stdout.write(md);
+				}
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/folders.ts

@@ -0,0 +1,88 @@
+/**
+ * `hiai-docs folders` — render a folder tree.
+ *
+ * The backend exposes a flat "children of parent" listing; to render
+ * the full tree we walk recursively from each root and recurse into
+ * children. Output uses ASCII glyphs so it stays readable when piped
+ * to files/logs without a TTY.
+ *
+ * Also registers `folder-create` — a separate subcommand per the
+ * spec, since `folders` is a read-only listing.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, green, renderFolderTree } from "../format.js";
+
+export function registerFolders(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("folders")
+		.description("List folders (tree)")
+		.option("-p, --parent <uuid>", "Show children of a specific folder")
+		.action(async (opts: { parent?: string }) => {
+			try {
+				// The root listing returns folders with parentId IS NULL.
+				// To render a tree we fetch the full set once and walk in-memory.
+				// Backend doesn't have a "list all folders" endpoint — `folders`
+				// is keyed by parentId — so we fetch root + recurse.
+				const root = await client.listFolders({
+					parentId: opts.parent === undefined ? undefined : opts.parent,
+				});
+				if (root.length === 0) {
+					process.stdout.write("No folders.\n");
+					return;
+				}
+				// Gather everything for tree rendering when listing from root.
+				let all = root;
+				if (opts.parent === undefined) {
+					all = await collectAllFolders(root);
+				}
+				const tree = renderFolderTree(all, {
+					parentId: opts.parent ?? null,
+				});
+				process.stdout.write(`${tree}\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+
+	program
+		.command("folder-create")
+		.description("Create a new folder")
+		.requiredOption("-n, --name <name>", "Folder name (1-255 chars)")
+		.option("-p, --parent <uuid>", "Parent folder id")
+		.action(async (opts: { name: string; parent?: string }) => {
+			try {
+				const folder = await client.createFolder({
+					name: opts.name,
+					parentId: opts.parent,
+				});
+				process.stdout.write(`${folder.id}\n`);
+				process.stdout.write(`${green("✓")} Created folder "${folder.name}"\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}
+
+async function collectAllFolders(
+	initial: Awaited<ReturnType<typeof client.listFolders>>,
+): Promise<Awaited<ReturnType<typeof client.listFolders>>> {
+	const seen = new Map<string, (typeof initial)[number]>();
+	for (const f of initial) seen.set(f.id, f);
+	const queue: string[] = initial.map((f) => f.id);
+	while (queue.length > 0) {
+		const id = queue.shift();
+		if (!id) break;
+		const children = await client.listFolders({ parentId: id });
+		for (const child of children) {
+			if (!seen.has(child.id)) {
+				seen.set(child.id, child);
+				queue.push(child.id);
+			}
+		}
+	}
+	return Array.from(seen.values());
+}

package/packages/cli/src/commands/history.ts

@@ -0,0 +1,55 @@
+/**
+ * `hiai-docs history <id>` — list versions/snapshots for a document.
+ *
+ * Default behavior is to show everything (snapshots + auto-saved
+ * versions). `--snapshots-only` narrows to named snapshots, which
+ * is what most users care about.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, renderTable } from "../format.js";
+
+export function registerHistory(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("history <id>")
+		.description("List a document's version history")
+		.option("-s, --snapshots-only", "Only show named snapshots")
+		.action(async (id: string, opts: { snapshotsOnly?: boolean }) => {
+			try {
+				const rows = await client.listVersions(id, opts.snapshotsOnly);
+				if (rows.length === 0) {
+					process.stdout.write("No history.\n");
+					return;
+				}
+				const table = renderTable(rows, [
+					{ header: "ID", width: 36, get: (r) => r.id },
+					{
+						header: "TYPE",
+						width: 12,
+						get: (r) => (r.isSnapshot ? "snapshot" : "auto"),
+					},
+					{
+						header: "LABEL",
+						width: 30,
+						get: (r) => r.label ?? "-",
+					},
+					{
+						header: "CREATED",
+						width: 22,
+						get: (r) => r.createdAt,
+					},
+					{
+						header: "RESTORED FROM",
+						width: 36,
+						get: (r) => r.restoredFrom ?? "-",
+					},
+				]);
+				process.stdout.write(`${table}\n`);
+				process.stdout.write(`\n${rows.length} version(s)\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/list.ts

@@ -0,0 +1,61 @@
+/**
+ * `hiai-docs list` — paginated document listing.
+ *
+ * Calls GET /api/documents with optional folder/tag filters and prints
+ * a table with title, updated timestamp, and folder id.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, renderTable } from "../format.js";
+
+export function registerList(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("list")
+		.description("List documents (paginated)")
+		.option("-f, --folder <uuid>", "Filter by folder id")
+		.option("-t, --tag <uuid>", "Filter by tag id")
+		.option("-p, --page <n>", "Page number", (v) => Number.parseInt(v, 10))
+		.option("-l, --limit <n>", "Items per page (1-100)", (v) => Number.parseInt(v, 10))
+		.action(
+			async (opts: { folder?: string; tag?: string; page?: number; limit?: number }) => {
+				try {
+					const res = await client.listDocuments({
+						folderId: opts.folder,
+						tag: opts.tag,
+						page: opts.page,
+						limit: opts.limit,
+					});
+					if (res.items.length === 0) {
+						process.stdout.write("No documents.\n");
+						return;
+					}
+					const table = renderTable(res.items, [
+						{ header: "ID", width: 36, get: (r) => r.id },
+						{ header: "TITLE", width: 50, get: (r) => r.title },
+						{ header: "UPDATED", width: 22, get: (r) => formatDate(r.updatedAt) },
+						{ header: "FOLDER", width: 36, get: (r) => r.folderId ?? "-" },
+					]);
+					process.stdout.write(`${table}\n`);
+					process.stdout.write(
+						`\nPage ${res.page} — ${res.items.length} of ${res.total} document(s)\n`,
+					);
+				} catch (err) {
+					process.stderr.write(`${formatError(err)}\n`);
+					process.exitCode = 1;
+				}
+			},
+		);
+}
+
+function formatDate(iso: string): string {
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return iso;
+	// YYYY-MM-DD HH:MM — short, sortable, no locale surprises.
+	const yyyy = d.getUTCFullYear();
+	const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+	const dd = String(d.getUTCDate()).padStart(2, "0");
+	const hh = String(d.getUTCHours()).padStart(2, "0");
+	const mi = String(d.getUTCMinutes()).padStart(2, "0");
+	return `${yyyy}-${mm}-${dd} ${hh}:${mi}`;
+}

package/packages/cli/src/commands/read.ts

@@ -0,0 +1,38 @@
+/**
+ * `hiai-docs read <id>` — fetch a single document and print its body.
+ *
+ * Title + metadata block first, then the raw markdown body to stdout.
+ * Pipe-friendly: emitting markdown only would force callers to either
+ * parse the metadata out or accept the whole blob.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { dim, formatError } from "../format.js";
+
+export function registerRead(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("read <id>")
+		.description("Read a document (title + markdown body)")
+		.action(async (id: string) => {
+			try {
+				const doc = await client.getDocument(id);
+				const tagList = (doc.tags ?? [])
+					.map((t) => t.name)
+					.join(", ");
+				const meta = [
+					`id: ${doc.id}`,
+					`updated: ${doc.updatedAt}`,
+					doc.folderId ? `folder: ${doc.folderId}` : null,
+					tagList ? `tags: ${tagList}` : null,
+				]
+					.filter(Boolean)
+					.join("\n");
+				process.stdout.write(`# ${doc.title}\n\n${dim(meta)}\n\n`);
+				process.stdout.write(`${doc.content ?? ""}\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/restore.ts

@@ -0,0 +1,30 @@
+/**
+ * `hiai-docs restore <id> --version <vid>` — restore a prior version.
+ *
+ * The backend saves an auto-backup of the current content before
+ * overwriting, so this command is always reversible. The CLI doesn't
+ * add a confirmation prompt: the server-side auto-backup is the
+ * safety net.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, green } from "../format.js";
+
+export function registerRestore(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("restore <id>")
+		.description("Restore a prior version (auto-backup is taken first)")
+		.requiredOption("-v, --version <vid>", "Version id to restore")
+		.action(async (id: string, opts: { version: string }) => {
+			try {
+				await client.restoreVersion(id, opts.version);
+				process.stdout.write(
+					`${green("✓")} Restored ${id} to version ${opts.version}\n`,
+				);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/search.ts

@@ -0,0 +1,56 @@
+/**
+ * `hiai-docs search <query>` — hybrid full-text + semantic search.
+ *
+ * Calls GET /api/search with optional folder/tags/limit filters and
+ * prints a score-ranked table.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, renderTable } from "../format.js";
+
+export function registerSearch(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("search <query>")
+		.description("Search documents (hybrid full-text + semantic)")
+		.option("-l, --limit <n>", "Max results (1-100)", (v) => Number.parseInt(v, 10))
+		.option("-f, --folder <uuid>", "Restrict to a folder")
+		.option("-t, --tags <list>", "Comma-separated tag names")
+		.action(async (query: string, opts: { limit?: number; folder?: string; tags?: string }) => {
+			try {
+				const tags = opts.tags
+					? opts.tags
+							.split(",")
+							.map((t) => t.trim())
+							.filter(Boolean)
+					: undefined;
+				const res = await client.search({
+					query,
+					folder: opts.folder,
+					tags,
+					limit: opts.limit,
+				});
+				if (res.items.length === 0) {
+					process.stdout.write("No matches.\n");
+					return;
+				}
+				const table = renderTable(res.items, [
+					{ header: "ID", width: 36, get: (r) => r.id },
+					{ header: "TITLE", width: 40, get: (r) => r.title },
+					{ header: "SCORE", width: 7, get: (r) => r.score.toFixed(3), align: "right" },
+					{ header: "SNIPPET", width: 60, get: (r) => oneLineForCli(r.snippet) },
+				]);
+				process.stdout.write(`${table}\n`);
+				process.stdout.write(`\n${res.items.length} of ${res.total} result(s)\n`);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}
+
+// Local helper to avoid pulling in format.ts just for oneLine.
+function oneLineForCli(value: string): string {
+	const flat = value.replace(/\s+/g, " ").trim();
+	return flat.length > 60 ? `${flat.slice(0, 59)}…` : flat;
+}

package/packages/cli/src/commands/snapshot.ts

@@ -0,0 +1,35 @@
+/**
+ * `hiai-docs snapshot <id>` — create a named, immutable snapshot of
+ * the document's current state.
+ *
+ * Snapshots are stored as `versions` rows with `isSnapshot=true`
+ * (see backend/src/api/routes/versions.ts). They survive the
+ * auto-prune that keeps ordinary auto-saved versions bounded.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, green } from "../format.js";
+
+export function registerSnapshot(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("snapshot <id>")
+		.description("Create a named snapshot of a document")
+		.requiredOption("-n, --name <label>", "Snapshot label (1-200 chars)")
+		.option("-d, --description <text>", "Snapshot description")
+		.action(async (id: string, opts: { name: string; description?: string }) => {
+			try {
+				const snap = await client.createSnapshot(id, {
+					label: opts.name,
+					description: opts.description,
+				});
+				process.stdout.write(`${snap.id} (${snap.label})\n`);
+				process.stdout.write(
+					`${green("✓")} Snapshot created for ${id}\n`,
+				);
+			} catch (err) {
+				process.stderr.write(`${formatError(err)}\n`);
+				process.exitCode = 1;
+			}
+		});
+}

package/packages/cli/src/commands/update.ts

@@ -0,0 +1,54 @@
+/**
+ * `hiai-docs update <id>` — patch a document's title and/or content.
+ *
+ * Empty body is rejected by the backend; the CLI mirrors that
+ * constraint early to avoid a wasted round trip.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError, green } from "../format.js";
+
+export function registerUpdate(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("update <id>")
+		.description("Update a document's title and/or content")
+		.option("--title <title>", "New title")
+		.option("-c, --content <markdown>", "New content")
+		.option("-f, --folder <uuid>", "Move to folder (use '' to clear)")
+		.action(
+			async (
+				id: string,
+				opts: { title?: string; content?: string; folder?: string },
+			) => {
+				try {
+					if (
+						opts.title === undefined &&
+						opts.content === undefined &&
+						opts.folder === undefined
+					) {
+						process.stderr.write(
+							"At least one of --title, --content, or --folder is required.\n",
+						);
+						process.exitCode = 1;
+						return;
+					}
+					const folder =
+						opts.folder === undefined
+							? undefined
+							: opts.folder === ""
+								? null
+								: opts.folder;
+					await client.updateDocument(id, {
+						title: opts.title,
+						content: opts.content,
+						folderId: folder,
+					});
+					process.stdout.write(`${green("✓")} Updated ${id}\n`);
+				} catch (err) {
+					process.stderr.write(`${formatError(err)}\n`);
+					process.exitCode = 1;
+				}
+			},
+		);
+}

package/packages/cli/src/config.ts

@@ -0,0 +1,83 @@
+/**
+ * Config loader for the hiai-docs CLI.
+ *
+ * Resolution order (highest priority first):
+ *   1. Environment variables (HIAI_DOCS_URL, HIAI_DOCS_API_KEY)
+ *   2. JSON file at ~/.hiai-docs/config.json
+ *   3. Built-in defaults
+ *
+ * The file config persists across invocations, so users can run
+ * `hiai-docs config --url <url> --key <key>` once and reuse the
+ * values. Env vars are intended for CI/ephemeral contexts where
+ * writing to disk is undesirable.
+ */
+
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface Config {
+	url: string;
+	apiKey: string;
+}
+
+const CONFIG_DIR = join(homedir(), ".hiai-docs");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const DEFAULT_URL = "http://localhost:50700";
+
+/** Enforce owner-only access for a config directory and its optional file. */
+export function enforceConfigPermissions(
+	configDir: string,
+	configFile: string,
+): void {
+	if (process.platform === "win32") return;
+	if (existsSync(configDir)) chmodSync(configDir, 0o700);
+	if (existsSync(configFile)) chmodSync(configFile, 0o600);
+}
+
+export function loadConfig(): Config {
+	enforceConfigPermissions(CONFIG_DIR, CONFIG_FILE);
+	const envUrl = process.env.HIAI_DOCS_URL;
+	const envKey = process.env.HIAI_DOCS_API_KEY;
+
+	let file: Partial<Config> = {};
+	if (existsSync(CONFIG_FILE)) {
+		try {
+			const raw = readFileSync(CONFIG_FILE, "utf-8");
+			const parsed = JSON.parse(raw) as unknown;
+			if (parsed && typeof parsed === "object") {
+				file = parsed as Partial<Config>;
+			}
+		} catch {
+			// Corrupted config — fall back to defaults/env. Don't throw:
+			// the user should still be able to run `config` to repair it.
+			file = {};
+		}
+	}
+
+	return {
+		url: envUrl ?? file.url ?? DEFAULT_URL,
+		apiKey: envKey ?? file.apiKey ?? "",
+	};
+}
+
+export function saveConfig(cfg: Config): void {
+	if (!existsSync(CONFIG_DIR)) {
+		mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+	}
+	enforceConfigPermissions(CONFIG_DIR, CONFIG_FILE);
+	writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+	// writeFileSync preserves the mode of an existing file, so correct it after
+	// every write as well as before reading it.
+	enforceConfigPermissions(CONFIG_DIR, CONFIG_FILE);
+}
+
+export function configFilePath(): string {
+	return CONFIG_FILE;
+}