get-tbd 0.2.2 → 0.3.0

package/dist/doc-cache-CamtXfi4.mjs

@@ -0,0 +1,1035 @@
+import { d as updateLocalState, f as writeConfig, l as readLocalState, n as findTbdRoot, s as readConfig } from "./config-B1w3pAkY.mjs";
+import { F as gitSafeEnv, S as TBD_DOCS_DIR, a as CHARS_PER_TOKEN } from "./paths-C1DpnZJW.mjs";
+import { a as tryParseDocRef } from "./docref-C7g0sjvL.mjs";
+import matter from "gray-matter";
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { writeFile } from "atomically";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import prettyBytes from "pretty-bytes";
+import prettyMs from "pretty-ms";
+
+//#region src/file/github-fetch.ts
+/**
+* GitHub URL utilities and content fetching with `gh` CLI fallback.
+*
+* Consolidates all GitHub-specific URL handling and fetching logic:
+* - GitHub blob URL → raw URL conversion
+* - Direct HTTP fetch with timeout
+* - Fallback to `gh api` on 403 errors (common in restricted environments)
+*
+* This module is reusable across doc-sync, doc-add, and any future code
+* that needs to fetch content from GitHub.
+*/
+const execFileAsync = promisify(execFile);
+/**
+* Regular expression to match GitHub blob URLs.
+*
+* Matches patterns like:
+*   https://github.com/{owner}/{repo}/blob/{ref}/{path}
+*/
+const GITHUB_BLOB_RE = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
+/**
+* Regular expression to match raw.githubusercontent.com URLs.
+*
+* Matches patterns like:
+*   https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}
+*/
+const RAW_GITHUB_RE = /^https?:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/;
+/**
+* Convert a GitHub blob URL to a raw.githubusercontent.com URL.
+*
+* If the URL is already a raw URL or not a GitHub blob URL, returns it unchanged.
+*
+* @example
+* githubBlobToRawUrl('https://github.com/org/repo/blob/main/docs/file.md')
+* // => 'https://raw.githubusercontent.com/org/repo/main/docs/file.md'
+*
+* @example
+* githubBlobToRawUrl('https://raw.githubusercontent.com/org/repo/main/docs/file.md')
+* // => 'https://raw.githubusercontent.com/org/repo/main/docs/file.md' (unchanged)
+*/
+function githubBlobToRawUrl(url) {
+	const match = GITHUB_BLOB_RE.exec(url);
+	if (!match) return url;
+	const [, owner, repo, ref, path] = match;
+	return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path}`;
+}
+/**
+* Parse a raw.githubusercontent.com URL into its components.
+*
+* @returns The parsed components, or null if not a raw GitHub URL
+*/
+function parseRawGitHubUrl(url) {
+	const match = RAW_GITHUB_RE.exec(url);
+	if (!match) return null;
+	return {
+		owner: match[1],
+		repo: match[2],
+		ref: match[3],
+		path: match[4]
+	};
+}
+/** Default timeout for URL fetches in milliseconds */
+const DEFAULT_FETCH_TIMEOUT = 3e4;
+/**
+* Fetch content from a URL via direct HTTP.
+*
+* @throws If the request fails or returns a non-OK status
+*/
+async function directFetch(url, options) {
+	const timeout = options?.timeout ?? DEFAULT_FETCH_TIMEOUT;
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort();
+	}, timeout);
+	try {
+		const response = await fetch(url, {
+			signal: controller.signal,
+			headers: {
+				"User-Agent": "get-tbd/1.0",
+				Accept: "text/plain, text/markdown, */*"
+			}
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		return await response.text();
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Fetch content from a GitHub raw URL using `gh api`.
+*
+* Converts raw.githubusercontent.com URLs to GitHub API content endpoints
+* and decodes the base64-encoded response.
+*
+* @throws If the URL is not a GitHub URL or gh CLI fails
+*/
+async function ghCliFetch(rawUrl) {
+	const parsed = parseRawGitHubUrl(rawUrl);
+	if (parsed) try {
+		const { stdout } = await execFileAsync("gh", [
+			"api",
+			`/repos/${parsed.owner}/${parsed.repo}/contents/${parsed.path}?ref=${parsed.ref}`,
+			"--jq",
+			".content",
+			"-H",
+			"Accept: application/vnd.github.v3+json"
+		]);
+		const base64Content = stdout.trim();
+		return Buffer.from(base64Content, "base64").toString("utf-8");
+	} catch (error) {
+		throw new Error(`Failed to fetch via gh CLI: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	try {
+		const { stdout } = await execFileAsync("gh", ["api", rawUrl]);
+		return stdout;
+	} catch (error) {
+		throw new Error(`Failed to fetch via gh CLI: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Fetch content from a URL, falling back to `gh` CLI on 403 errors.
+*
+* GitHub.com and raw.githubusercontent.com may block requests from
+* certain environments (e.g., CI runners, corporate proxies). When
+* a 403 is received, we retry using `gh api` which authenticates
+* via the user's GitHub CLI token.
+*
+* This function also auto-converts GitHub blob URLs to raw URLs.
+*
+* @returns The fetched content and whether gh CLI was used
+* @throws If both direct fetch and gh CLI fallback fail
+*/
+async function fetchWithGhFallback(url, options) {
+	const rawUrl = githubBlobToRawUrl(url);
+	try {
+		return {
+			content: await directFetch(rawUrl, options),
+			usedGhCli: false
+		};
+	} catch (error) {
+		if (!(error instanceof Error && error.message.includes("HTTP 403"))) throw error;
+	}
+	return {
+		content: await ghCliFetch(rawUrl),
+		usedGhCli: true
+	};
+}
+/**
+* Resolve a git docref (github:o/r@ref//path, gitlab:...) to a raw-content URL.
+* The ref is required for sync determinism; callers enforce that.
+*/
+function gitDocRefToRawUrl(ref) {
+	const rev = ref.ref ?? "main";
+	if (ref.host === "gitlab") return `https://gitlab.com/${ref.owner}/${ref.repo}/-/raw/${rev}/${ref.path}`;
+	return `https://raw.githubusercontent.com/${ref.owner}/${ref.repo}/${rev}/${ref.path}`;
+}
+
+//#endregion
+//#region src/file/doc-sync.ts
+/**
+* DocSync - Sync documentation files from configured sources.
+*
+* Syncs docs from internal bundled sources and external URLs to .tbd/docs/.
+*
+* See: docs/project/specs/active/plan-2026-01-26-configurable-doc-cache-sync.md
+*/
+/**
+* Group docs_cache.files entries by source root: one group per git repo+ref
+* (so failures isolate per source and revisions are captured once), with
+* internal, local, and ad-hoc URL entries in origin-keyed groups.
+*/
+function groupSourceEntries(config) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const [destPath, sourceStr] of Object.entries(config)) {
+		let key = "url";
+		let gitSource;
+		if (sourceStr.startsWith("internal:")) key = "internal";
+		else {
+			const parsed = tryParseDocRef(sourceStr);
+			if (parsed?.kind === "git") {
+				key = `${parsed.host}:${parsed.owner}/${parsed.repo}@${parsed.ref ?? "main"}`;
+				gitSource = {
+					host: parsed.host,
+					owner: parsed.owner,
+					repo: parsed.repo,
+					ref: parsed.ref
+				};
+			} else if (parsed?.kind === "local") key = "local";
+			else try {
+				key = new URL(sourceStr).origin;
+			} catch {
+				key = "url";
+			}
+		}
+		let group = groups.get(key);
+		if (!group) {
+			group = {
+				key,
+				gitSource,
+				entries: []
+			};
+			groups.set(key, group);
+		}
+		group.entries.push([destPath, sourceStr]);
+	}
+	return [...groups.values()];
+}
+/**
+* Capture the current revision of a git source's ref (one ls-remote per
+* group), for provenance. Best-effort: offline or missing git returns null.
+*/
+async function captureGitRevision(src) {
+	const repoUrl = src.host === "gitlab" ? `https://gitlab.com/${src.owner}/${src.repo}.git` : `https://github.com/${src.owner}/${src.repo}.git`;
+	try {
+		const { execFile } = await import("node:child_process");
+		const { promisify } = await import("node:util");
+		const sha = (await promisify(execFile)("git", [
+			"ls-remote",
+			repoUrl,
+			src.ref ?? "HEAD"
+		], {
+			timeout: 1e4,
+			env: gitSafeEnv()
+		})).stdout.split("	")[0]?.trim();
+		return sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+	} catch {
+		return null;
+	}
+}
+/** Prefix for internal bundled doc sources */
+const INTERNAL_SOURCE_PREFIX = "internal:";
+/**
+* Syncs documentation files from configured sources.
+*
+* Supports:
+* - Internal bundled docs (using internal: prefix)
+* - External URLs (raw.githubusercontent.com, etc.)
+*/
+var DocSync = class {
+	docsDir;
+	/**
+	* Create a new DocSync instance.
+	*
+	* @param tbdRoot - The tbd project root directory (parent of .tbd/)
+	* @param config - The doc_cache configuration mapping dest paths to sources
+	*/
+	constructor(tbdRoot, config) {
+		this.tbdRoot = tbdRoot;
+		this.config = config;
+		this.docsDir = join(tbdRoot, TBD_DOCS_DIR);
+	}
+	/**
+	* Parse a source string into a DocSource.
+	*
+	* @example
+	* parseSource('internal:shortcuts/standard/code-review-and-commit.md')
+	* // => { type: 'internal', location: 'shortcuts/standard/code-review-and-commit.md' }
+	*
+	* @example
+	* parseSource('https://raw.githubusercontent.com/org/repo/main/file.md')
+	* // => { type: 'url', location: 'https://...' }
+	*/
+	parseSource(source) {
+		if (source.startsWith(INTERNAL_SOURCE_PREFIX)) return {
+			type: "internal",
+			location: source.slice(9)
+		};
+		const parsed = tryParseDocRef(source);
+		if (parsed?.kind === "git") return {
+			type: "url",
+			location: gitDocRefToRawUrl(parsed)
+		};
+		if (parsed?.kind === "local") return {
+			type: "local",
+			location: parsed.path
+		};
+		return {
+			type: "url",
+			location: source
+		};
+	}
+	/**
+	* Fetch content from a source.
+	*
+	* @throws If the source cannot be fetched
+	*/
+	async fetchContent(source) {
+		if (source.type === "internal") return this.fetchInternalContent(source.location);
+		if (source.type === "local") return await readFile(join(this.tbdRoot, source.location), "utf-8");
+		return this.fetchUrlContent(source.location);
+	}
+	/**
+	* Fetch content from an internal bundled doc.
+	*/
+	async fetchInternalContent(location) {
+		const basePaths = getDocsBasePath();
+		for (const basePath of basePaths) {
+			const fullPath = join(basePath, location);
+			try {
+				await access(fullPath);
+				return await readFile(fullPath, "utf-8");
+			} catch {}
+		}
+		throw new Error(`Internal doc not found: ${location}`);
+	}
+	/**
+	* Fetch content from a URL (with gh CLI fallback on 403).
+	*/
+	async fetchUrlContent(url) {
+		const { content } = await fetchWithGhFallback(url);
+		return content;
+	}
+	/**
+	* Get the current state of the docs directory.
+	* Returns a set of relative paths that exist in .tbd/docs/.
+	*/
+	async getCurrentState() {
+		const paths = /* @__PURE__ */ new Set();
+		try {
+			await access(this.docsDir);
+		} catch {
+			return paths;
+		}
+		await this.scanDirectory(this.docsDir, "", paths);
+		return paths;
+	}
+	/**
+	* Recursively scan a directory and add all .md file paths to the set.
+	*/
+	async scanDirectory(baseDir, prefix, paths) {
+		try {
+			const dirEntries = await readdir(baseDir, { withFileTypes: true });
+			for (const entry of dirEntries) {
+				const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+				if (entry.isDirectory()) await this.scanDirectory(join(baseDir, entry.name), relativePath, paths);
+				else if (entry.isFile() && entry.name.endsWith(".md")) paths.add(relativePath);
+			}
+		} catch {}
+	}
+	/**
+	* Sync all docs from config to .tbd/docs/.
+	*
+	* - Downloads/copies new docs
+	* - Updates docs whose source has changed
+	* - Removes docs no longer in config
+	*
+	* @param options - Sync options (dryRun, silent)
+	*/
+	async sync(options = {}) {
+		const result = {
+			sourceRevisions: {},
+			added: [],
+			updated: [],
+			removed: [],
+			errors: [],
+			success: true
+		};
+		const currentPaths = await this.getCurrentState();
+		const configPaths = new Set(Object.keys(this.config));
+		const groups = groupSourceEntries(this.config);
+		const failedGroups = /* @__PURE__ */ new Set();
+		for (const group of groups) if (group.gitSource) {
+			const revision = await captureGitRevision(group.gitSource);
+			if (revision) result.sourceRevisions[group.key] = revision;
+		}
+		for (const group of groups) for (const [destPath, sourceStr] of group.entries) {
+			if (failedGroups.has(group.key)) {
+				result.errors.push({
+					path: destPath,
+					error: `skipped: source group ${group.key} unreachable`
+				});
+				result.success = false;
+				continue;
+			}
+			try {
+				const source = this.parseSource(sourceStr);
+				const content = await this.fetchContent(source);
+				const fullPath = join(this.docsDir, destPath);
+				let exists = false;
+				let existingContent = "";
+				try {
+					existingContent = await readFile(fullPath, "utf-8");
+					exists = true;
+				} catch {}
+				if (!exists) {
+					if (!options.dryRun) {
+						await mkdir(dirname(fullPath), { recursive: true });
+						await writeFile(fullPath, content);
+					}
+					result.added.push(destPath);
+				} else if (existingContent !== content) {
+					if (!options.dryRun) await writeFile(fullPath, content);
+					result.updated.push(destPath);
+				}
+			} catch (err) {
+				const message = err.message;
+				result.errors.push({
+					path: destPath,
+					error: message
+				});
+				result.success = false;
+				if (group.gitSource && /fetch|network|ENOTFOUND|ETIMEDOUT|ECONNREFUSED|HTTP/i.test(message)) failedGroups.add(group.key);
+			}
+		}
+		for (const existingPath of currentPaths) if (!configPaths.has(existingPath)) try {
+			if (!options.dryRun) await rm(join(this.docsDir, existingPath));
+			result.removed.push(existingPath);
+		} catch (err) {
+			result.errors.push({
+				path: existingPath,
+				error: `Failed to remove: ${err.message}`
+			});
+		}
+		return result;
+	}
+	/**
+	* Get a status of what would change without actually making changes.
+	*/
+	async status() {
+		return this.sync({ dryRun: true });
+	}
+};
+/**
+* Get base docs paths (with fallbacks for development).
+* Matches the logic in setup.ts.
+*/
+function getDocsBasePath() {
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	return [join(__dirname, "docs"), join(__dirname, "..", "..", "docs")];
+}
+/**
+* Generate default doc_cache config by scanning bundled docs.
+*
+* This creates a config entry for each .md file found in the bundled
+* docs directories (shortcuts, guidelines, templates).
+*
+* @returns A doc_cache config mapping destination paths to internal: sources
+*/
+async function generateDefaultDocCacheConfig() {
+	const config = {};
+	const basePaths = getDocsBasePath();
+	let docsDir = null;
+	for (const path of basePaths) try {
+		await access(path);
+		docsDir = path;
+		break;
+	} catch {}
+	if (!docsDir) return config;
+	const scanDirs = [
+		{
+			subdir: "shortcuts/system",
+			prefix: "shortcuts/system"
+		},
+		{
+			subdir: "shortcuts/standard",
+			prefix: "shortcuts/standard"
+		},
+		{
+			subdir: "guidelines",
+			prefix: "guidelines"
+		},
+		{
+			subdir: "templates",
+			prefix: "templates"
+		},
+		{
+			subdir: "references",
+			prefix: "references"
+		}
+	];
+	config[`references/tbd-docs.md`] = `${INTERNAL_SOURCE_PREFIX}tbd-docs.md`;
+	config[`references/tbd-design.md`] = `${INTERNAL_SOURCE_PREFIX}tbd-design.md`;
+	for (const { subdir, prefix } of scanDirs) {
+		const fullDir = join(docsDir, subdir);
+		try {
+			const entries = await readdir(fullDir, { withFileTypes: true });
+			for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".md")) {
+				const relativePath = `${prefix}/${entry.name}`;
+				config[relativePath] = `${INTERNAL_SOURCE_PREFIX}${relativePath}`;
+			}
+		} catch {}
+	}
+	return config;
+}
+/**
+* Merge user's doc_cache config with default bundled docs.
+*
+* This ensures:
+* - New bundled docs from tbd updates are added to existing configs
+* - User's custom sources (URLs, etc.) are preserved
+* - User's overrides of bundled docs are respected
+*
+* @param userConfig - The user's existing doc_cache config (may be undefined/empty)
+* @param defaults - The default config from generateDefaultDocCacheConfig()
+* @returns Merged config with defaults as base, user config overlaid
+*/
+function mergeDocCacheConfig(userConfig, defaults) {
+	return {
+		...defaults,
+		...userConfig
+	};
+}
+/**
+* Check if docs are stale based on last sync time and configured hours.
+*
+* @param lastSyncAt - ISO timestamp of last sync (or undefined if never synced)
+* @param autoSyncHours - Hours between auto-syncs (0 = disabled)
+* @returns true if docs should be synced
+*/
+function isDocsStale(lastSyncAt, autoSyncHours) {
+	if (autoSyncHours <= 0) return false;
+	if (!lastSyncAt) return true;
+	const lastSync = new Date(lastSyncAt).getTime();
+	return (Date.now() - lastSync) / (1e3 * 60 * 60) >= autoSyncHours;
+}
+/**
+* Check if an internal bundled doc exists.
+*
+* @param location - The internal doc path (without 'internal:' prefix)
+* @returns true if the doc exists in any of the bundled doc paths
+*/
+async function internalDocExists(location) {
+	const basePaths = getDocsBasePath();
+	for (const basePath of basePaths) {
+		const fullPath = join(basePath, location);
+		try {
+			await access(fullPath);
+			return true;
+		} catch {}
+	}
+	return false;
+}
+/**
+* Prune entries from config that point to non-existent internal sources.
+*
+* This handles the case where a bundled doc is removed in a tbd update -
+* the stale config entry is automatically cleaned up.
+*
+* @param config - The doc_cache config to prune
+* @returns Object with pruned config and list of removed entries
+*/
+async function pruneStaleInternals(config) {
+	const result = {};
+	const pruned = [];
+	for (const [dest, source] of Object.entries(config)) {
+		if (source.startsWith(INTERNAL_SOURCE_PREFIX)) {
+			if (!await internalDocExists(source.slice(9))) {
+				pruned.push(dest);
+				continue;
+			}
+		}
+		result[dest] = source;
+	}
+	return {
+		config: result,
+		pruned
+	};
+}
+/**
+* Deep equality check for config objects.
+*/
+function configsEqual(a, b) {
+	const keysA = Object.keys(a).sort();
+	const keysB = Object.keys(b).sort();
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (!Object.hasOwn(b, key) || a[key] !== b[key]) return false;
+	return true;
+}
+/**
+* Sync docs with merged defaults and auto-pruning.
+*
+* This is the single entry point for all doc sync operations that need
+* to pick up new bundled docs from tbd upgrades.
+*
+* Steps:
+* 1. Read current config
+* 2. Generate defaults from bundled docs
+* 3. Merge: defaults as base, user config overlays
+* 4. Prune entries with missing internal sources
+* 5. Sync files to .tbd/docs/
+* 6. Write config if changed
+* 7. Update last_doc_sync_at in state
+*
+* @param tbdRoot - The tbd project root directory
+* @param options - Sync options (quiet, dryRun)
+* @returns Sync result with added/updated/removed/pruned counts
+*/
+async function syncDocsWithDefaults(tbdRoot, options = {}) {
+	const config = await readConfig(tbdRoot);
+	const originalFiles = config.docs_cache?.files ?? {};
+	const { config: prunedConfig, pruned } = await pruneStaleInternals(mergeDocCacheConfig(originalFiles, await generateDefaultDocCacheConfig()));
+	const syncResult = await new DocSync(tbdRoot, prunedConfig).sync({ dryRun: options.dryRun });
+	const configChanged = !configsEqual(prunedConfig, originalFiles);
+	if (configChanged && !options.dryRun) {
+		const lookupPath = config.docs_cache?.lookup_path ?? [".tbd/docs/shortcuts/system", ".tbd/docs/shortcuts/standard"];
+		config.docs_cache = {
+			...config.docs_cache,
+			lookup_path: lookupPath,
+			files: prunedConfig
+		};
+		await writeConfig(tbdRoot, config);
+	}
+	if (!options.dryRun) await updateLocalState(tbdRoot, { last_doc_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
+	return {
+		added: syncResult.added,
+		updated: syncResult.updated,
+		removed: syncResult.removed,
+		pruned,
+		configChanged,
+		errors: syncResult.errors,
+		success: syncResult.success
+	};
+}
+
+//#endregion
+//#region src/lib/format-utils.ts
+/**
+* Human-readable formatting utilities for tbd CLI.
+*
+* Uses sindresorhus libraries for consistent, well-tested formatting:
+* - pretty-bytes: Byte sizes (1337 -> "1.34 kB")
+* - pretty-ms: Durations (3600000 -> "1h")
+*/
+/**
+* Estimate token count from text content.
+* Uses CHARS_PER_TOKEN (~3.5) for markdown/code content.
+*/
+function estimateTokens(text) {
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+* Format token count: "~1.2k tok" or "~450 tok"
+*/
+function formatTokens(tokens) {
+	if (tokens >= 1e3) return `~${(tokens / 1e3).toFixed(1)}k tok`;
+	return `~${tokens} tok`;
+}
+/**
+* Format doc size for list display: "(1.8 kB, ~450 tok)"
+*/
+function formatDocSize(sizeBytes, approxTokens) {
+	return `(${prettyBytes(sizeBytes)}, ${formatTokens(approxTokens)})`;
+}
+/**
+* Format relative time from Date: "2d ago", "3h ago", "5m ago"
+* Uses compact format for concise display.
+*/
+function formatTimeAgo(date) {
+	const ms = Date.now() - date.getTime();
+	if (ms < 0) return "just now";
+	if (ms < 6e4) return "just now";
+	return `${prettyMs(ms, { compact: true })} ago`;
+}
+/**
+* Format relative time from ISO timestamp string.
+* Returns null if timestamp is invalid.
+*/
+function formatTimestampAgo(timestamp) {
+	if (!timestamp) return null;
+	const date = new Date(timestamp);
+	if (isNaN(date.getTime())) return null;
+	return formatTimeAgo(date);
+}
+
+//#endregion
+//#region src/file/doc-cache.ts
+/**
+* DocCache - Path-ordered markdown document cache with lookup.
+*
+* Provides document lookups for the `tbd shortcut` command, supporting
+* both exact matching by filename and fuzzy matching against metadata.
+*
+* Also provides auto-sync functionality when docs are stale (per spec).
+*
+* See: docs/project/specs/active/plan-2026-01-22-doc-cache-abstraction.md
+* See: docs/project/specs/active/plan-2026-01-26-configurable-doc-cache-sync.md
+*/
+/** Score for exact filename match (with or without .md extension) */
+const SCORE_EXACT_MATCH = 1;
+/** Score when query is a prefix of the filename */
+const SCORE_PREFIX_MATCH = .9;
+/** Score when filename contains all query words */
+const SCORE_CONTAINS_ALL = .8;
+/** Base score for partial word matches (multiplied by matched/total ratio) */
+const SCORE_PARTIAL_BASE = .7;
+/** Minimum score threshold to return a fuzzy match result */
+const SCORE_MIN_THRESHOLD = .5;
+/**
+* Path-ordered markdown document cache.
+*
+* Loads all .md files from configured paths in order, with earlier paths
+* taking precedence (like shell $PATH). Supports exact lookup by filename
+* and fuzzy search across filename + frontmatter metadata.
+*/
+var DocCache = class {
+	/** Active docs (first occurrence of each name) */
+	docs = [];
+	/** All docs including shadowed ones */
+	allDocs = [];
+	/** Track names we've seen for shadow detection */
+	seenNames = /* @__PURE__ */ new Set();
+	/** Whether the cache has been loaded */
+	loaded = false;
+	/**
+	* Create a new DocCache.
+	*
+	* @param paths - Ordered array of directory paths to search (relative to baseDir)
+	* @param baseDir - Base directory for resolving relative paths (default: cwd)
+	*/
+	constructor(paths, baseDir = process.cwd()) {
+		this.paths = paths;
+		this.baseDir = baseDir;
+	}
+	/**
+	* Load all documents from configured paths.
+	*
+	* Reads all .md files from each path in order. Documents with the same
+	* name in later paths are shadowed (tracked but not returned by default).
+	*
+	* If auto-sync is enabled and docs are stale, triggers a sync first.
+	*
+	* @param options - Load options (quiet: suppress auto-sync output)
+	*/
+	async load(options) {
+		if (this.loaded) return;
+		await this.checkAutoSync(options?.quiet ?? false);
+		for (const relativePath of this.paths) {
+			const dirPath = join(this.baseDir, relativePath);
+			await this.loadDirectory(dirPath, relativePath);
+		}
+		this.loaded = true;
+	}
+	/**
+	* Check if docs are stale and auto-sync if needed.
+	* Respects the quiet option - only silent when explicitly requested.
+	*
+	* Uses syncDocsWithDefaults() to ensure auto-sync also picks up new bundled
+	* docs from tbd upgrades, not just existing config entries.
+	*
+	* @param quiet - If true, suppress sync output
+	*/
+	async checkAutoSync(quiet) {
+		try {
+			const tbdRoot = await findTbdRoot(this.baseDir);
+			if (!tbdRoot) return;
+			const config = await readConfig(tbdRoot);
+			const state = await readLocalState(tbdRoot);
+			const autoSyncHours = config.settings?.doc_auto_sync_hours ?? 24;
+			if (!isDocsStale(state.last_doc_sync_at, autoSyncHours)) return;
+			await syncDocsWithDefaults(tbdRoot, { quiet });
+		} catch {}
+	}
+	/**
+	* Load documents from a single directory.
+	*/
+	async loadDirectory(dirPath, sourceDir) {
+		let entries;
+		try {
+			entries = await readdir(dirPath);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.endsWith(".md")) continue;
+			const filePath = join(dirPath, entry);
+			const name = basename(entry, ".md");
+			try {
+				const content = await readFile(filePath, "utf-8");
+				const doc = {
+					path: filePath,
+					name,
+					frontmatter: this.parseFrontmatterData(content),
+					content,
+					sourceDir,
+					sizeBytes: Buffer.byteLength(content, "utf-8"),
+					approxTokens: estimateTokens(content)
+				};
+				this.allDocs.push(doc);
+				if (!this.seenNames.has(name)) {
+					this.docs.push(doc);
+					this.seenNames.add(name);
+				}
+			} catch (error) {
+				console.warn(`Failed to load shortcut ${filePath}: ${error.message}`);
+			}
+		}
+	}
+	/**
+	* Parse YAML frontmatter from content and return typed data.
+	* Uses gray-matter for consistent frontmatter parsing.
+	*/
+	parseFrontmatterData(content) {
+		if (!matter.test(content)) return;
+		try {
+			const parsed = matter(content).data;
+			return {
+				title: typeof parsed.title === "string" ? parsed.title : void 0,
+				description: typeof parsed.description === "string" ? parsed.description : void 0,
+				category: typeof parsed.category === "string" ? parsed.category : void 0,
+				tags: Array.isArray(parsed.tags) ? parsed.tags.filter((t) => typeof t === "string") : void 0
+			};
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Get a document by exact name match.
+	*
+	* @param name - Filename to match (with or without .md extension)
+	* @returns Match with score SCORE_EXACT_MATCH, or null if not found
+	*/
+	get(name) {
+		const lookupName = name.endsWith(".md") ? name.slice(0, -3) : name;
+		const doc = this.docs.find((d) => d.name === lookupName);
+		if (!doc) return null;
+		return {
+			doc,
+			score: SCORE_EXACT_MATCH
+		};
+	}
+	/**
+	* Search for documents matching a query.
+	*
+	* Performs fuzzy matching against filename, title, and description.
+	* Returns matches sorted by score descending.
+	*
+	* @param query - Search query string
+	* @param limit - Maximum number of results (default: 10)
+	* @returns Array of matches sorted by score descending
+	*/
+	search(query, limit = 10) {
+		const matches = [];
+		for (const doc of this.docs) {
+			const score = this.calculateScore(doc, query);
+			if (score >= SCORE_MIN_THRESHOLD) matches.push({
+				doc,
+				score
+			});
+		}
+		matches.sort((a, b) => {
+			if (b.score !== a.score) return b.score - a.score;
+			return a.doc.name.localeCompare(b.doc.name);
+		});
+		return matches.slice(0, limit);
+	}
+	/**
+	* Calculate relevance score for a document against a query.
+	*/
+	calculateScore(doc, query) {
+		const queryLower = query.toLowerCase().trim();
+		if (queryLower.length === 0) return 0;
+		const nameLower = doc.name.toLowerCase();
+		const titleLower = doc.frontmatter?.title?.toLowerCase() ?? "";
+		const descLower = doc.frontmatter?.description?.toLowerCase() ?? "";
+		if (nameLower === queryLower) return SCORE_EXACT_MATCH;
+		if (nameLower.startsWith(queryLower)) return SCORE_PREFIX_MATCH;
+		const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
+		const searchableText = `${nameLower} ${titleLower} ${descLower}`;
+		if (queryWords.every((word) => searchableText.includes(word)) && queryWords.length > 0) return SCORE_CONTAINS_ALL;
+		const matchedWords = queryWords.filter((word) => searchableText.includes(word));
+		if (matchedWords.length > 0) return SCORE_PARTIAL_BASE * (matchedWords.length / queryWords.length);
+		return 0;
+	}
+	/**
+	* List all documents.
+	*
+	* @param includeAll - If true, include shadowed documents
+	* @returns Array of cached documents
+	*/
+	list(includeAll = false) {
+		return includeAll ? this.allDocs : this.docs;
+	}
+	/**
+	* Check if a document is shadowed by an earlier path.
+	*
+	* @param doc - Document to check
+	* @returns True if this doc is shadowed (not the first with this name)
+	*/
+	isShadowed(doc) {
+		return this.docs.find((d) => d.name === doc.name) !== doc;
+	}
+	/**
+	* Check if the cache has been loaded.
+	*/
+	isLoaded() {
+		return this.loaded;
+	}
+};
+/**
+* Marker comments for shortcut directory section in skill files.
+* Used for incremental updates without overwriting user content.
+*/
+const SHORTCUT_DIRECTORY_BEGIN = "<!-- BEGIN SHORTCUT DIRECTORY -->";
+const SHORTCUT_DIRECTORY_END = "<!-- END SHORTCUT DIRECTORY -->";
+const GUIDELINE_GROUPS = [
+	{
+		heading: "General engineering",
+		note: "Read all of these for any engineering work (writing or reviewing code).",
+		match: (n) => n.startsWith("general-") || n === "error-handling-rules" || n === "backward-compatibility-rules" || n === "commit-conventions" || n.includes("tdd") || n.includes("testing") || n.includes("golden")
+	},
+	{
+		heading: "TypeScript & JS ecosystem",
+		note: "Also load these when working in TypeScript or JavaScript.",
+		match: (n) => n.startsWith("typescript-") || n.endsWith("monorepo-patterns") || n.startsWith("electron-")
+	},
+	{
+		heading: "Python",
+		note: "Also load these when working in Python.",
+		match: (n) => n.startsWith("python-")
+	},
+	{
+		heading: "Convex",
+		note: "Also load these when working with Convex.",
+		match: (n) => n.startsWith("convex-")
+	},
+	{
+		heading: "Docs, process & tooling",
+		match: () => true
+	}
+];
+/**
+* Build table rows from docs (shared helper for shortcuts and guidelines).
+*/
+function buildTableRows(docs, skipNames = []) {
+	const sortedDocs = [...docs].sort((a, b) => a.name.localeCompare(b.name));
+	const rows = [];
+	for (const doc of sortedDocs) {
+		if (skipNames.includes(doc.name)) continue;
+		const name = doc.name;
+		const escapedDescription = (doc.frontmatter?.description ?? "").replace(/\|/g, "\\|");
+		rows.push(`| ${name} | ${escapedDescription} |`);
+	}
+	return rows;
+}
+/**
+* Generate a formatted markdown directory of shortcuts and guidelines.
+*
+* The output includes:
+* 1. Marker comments for incremental updates
+* 2. Available Shortcuts section with name and description
+* 3. Available Guidelines section, grouped by area (General engineering first, then
+*    language/framework groups), with name and description (if provided)
+*
+* @param shortcuts - Array of shortcut CachedDoc objects
+* @param guidelines - Optional array of guideline CachedDoc objects
+* @returns Formatted markdown string with shortcuts and guidelines directory
+*
+* @example
+* const directory = generateShortcutDirectory(shortcutDocs, guidelineDocs);
+* // Returns:
+* // <!-- BEGIN SHORTCUT DIRECTORY -->
+* // ## Available Shortcuts
+* // | Name | Description |
+* // | --- | --- |
+* // | code-review-and-commit | Run pre-commit checks, review changes, and commit code |
+* // ...
+* // ## Available Guidelines
+* // ### General engineering
+* // | Name | Description |
+* // | --- | --- |
+* // | error-handling-rules | Rules for handling errors... |
+* // ...
+* // ### TypeScript & JS ecosystem
+* // | typescript-rules | TypeScript coding rules and best practices |
+* // ...
+* // <!-- END SHORTCUT DIRECTORY -->
+*/
+function generateShortcutDirectory(shortcuts, guidelines = []) {
+	const lines = [SHORTCUT_DIRECTORY_BEGIN];
+	const shortcutRows = buildTableRows(shortcuts, [
+		"skill-baseline",
+		"skill-brief",
+		"skill-minimal",
+		"shortcut-explanation"
+	]);
+	lines.push("## Available Shortcuts");
+	lines.push("");
+	lines.push("Run `tbd shortcut <name>` to use any of these shortcuts:");
+	lines.push("");
+	if (shortcutRows.length === 0) lines.push("No shortcuts available. Create shortcuts in `.tbd/docs/shortcuts/standard/`.");
+	else {
+		lines.push("| Name | Description |");
+		lines.push("| --- | --- |");
+		lines.push(...shortcutRows);
+	}
+	if (guidelines.length > 0) {
+		const grouped = GUIDELINE_GROUPS.map((group) => ({
+			group,
+			docs: []
+		}));
+		const catchAll = grouped[grouped.length - 1];
+		for (const doc of guidelines) (grouped.find((g) => g.group.match(doc.name)) ?? catchAll)?.docs.push(doc);
+		if (grouped.some((g) => g.docs.length > 0)) {
+			lines.push("");
+			lines.push("## Available Guidelines");
+			lines.push("");
+			lines.push("Run `tbd guidelines <name>` to apply any of these guidelines.");
+			lines.push("Load the **General engineering** group first, then the language or framework group.");
+			for (const { group, docs } of grouped) {
+				const rows = buildTableRows(docs);
+				if (rows.length === 0) continue;
+				lines.push("");
+				lines.push(`### ${group.heading}`);
+				if (group.note) {
+					lines.push("");
+					lines.push(`*${group.note}*`);
+				}
+				lines.push("");
+				lines.push("| Name | Description |");
+				lines.push("| --- | --- |");
+				lines.push(...rows);
+			}
+		}
+	}
+	lines.push("");
+	lines.push(SHORTCUT_DIRECTORY_END);
+	return lines.join("\n");
+}
+
+//#endregion
+export { SCORE_PARTIAL_BASE as a, formatDocSize as c, fetchWithGhFallback as d, gitDocRefToRawUrl as f, SCORE_MIN_THRESHOLD as i, formatTimestampAgo as l, SCORE_CONTAINS_ALL as n, SCORE_PREFIX_MATCH as o, SCORE_EXACT_MATCH as r, generateShortcutDirectory as s, DocCache as t, syncDocsWithDefaults as u };
+//# sourceMappingURL=doc-cache-CamtXfi4.mjs.map