@wei840222/qmd 2026.8.23

package/dist/cli/version.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Build/commit identification for `qmd --version`.
+ *
+ * The commit is *stamped at build time* (scripts/build.mjs writes
+ * build-info.json next to the compiled CLI) rather than discovered at runtime.
+ * A published tarball carries no git history of its own, so a runtime lookup
+ * can only ever find some *other* repository's HEAD: `git -C <dir> rev-parse`
+ * walks up the tree, and a global install under a git-managed prefix (e.g.
+ * Homebrew's /opt/homebrew) reported that prefix's commit as qmd's.
+ *
+ * Running from a source checkout has no stamp, so the git lookup remains as a
+ * fallback — but only after confirming the enclosing repository is the package
+ * we are actually running from.
+ */
+/** Written next to the compiled CLI (dist/cli/) by scripts/build.mjs. */
+export declare const BUILD_INFO_FILENAME = "build-info.json";
+export type BuildInfo = {
+    commit: string;
+    builtAt?: string;
+};
+/**
+ * Read the commit stamped into this build, or "" when there is none.
+ *
+ * Deliberately looks beside the running script rather than in the package's
+ * dist/ directory: a source run (src/cli/) must not pick up the stamp left by
+ * an earlier, possibly unrelated, build in dist/.
+ */
+export declare function readStampedCommit(scriptDir: string): string;
+/**
+ * Short HEAD of the checkout we are running from, or "" when we are not
+ * running from one.
+ *
+ * The guard is the whole point: an enclosing repository is only qmd's if its
+ * top level *is* this package's root. Without that check, any install nested
+ * inside an unrelated repository reports that repository's HEAD.
+ */
+export declare function gitCommitForCheckout(scriptDir: string, packageRoot: string): string;
+/**
+ * The commit to report for this invocation: the build stamp when there is one,
+ * otherwise the verified checkout HEAD, otherwise nothing.
+ */
+export declare function resolveCommit(scriptDir: string, packageRoot: string): string;

package/dist/cli/version.js

@@ -0,0 +1,80 @@
+/**
+ * Build/commit identification for `qmd --version`.
+ *
+ * The commit is *stamped at build time* (scripts/build.mjs writes
+ * build-info.json next to the compiled CLI) rather than discovered at runtime.
+ * A published tarball carries no git history of its own, so a runtime lookup
+ * can only ever find some *other* repository's HEAD: `git -C <dir> rev-parse`
+ * walks up the tree, and a global install under a git-managed prefix (e.g.
+ * Homebrew's /opt/homebrew) reported that prefix's commit as qmd's.
+ *
+ * Running from a source checkout has no stamp, so the git lookup remains as a
+ * fallback — but only after confirming the enclosing repository is the package
+ * we are actually running from.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+/** Written next to the compiled CLI (dist/cli/) by scripts/build.mjs. */
+export const BUILD_INFO_FILENAME = "build-info.json";
+/**
+ * Read the commit stamped into this build, or "" when there is none.
+ *
+ * Deliberately looks beside the running script rather than in the package's
+ * dist/ directory: a source run (src/cli/) must not pick up the stamp left by
+ * an earlier, possibly unrelated, build in dist/.
+ */
+export function readStampedCommit(scriptDir) {
+    try {
+        const raw = readFileSync(join(scriptDir, BUILD_INFO_FILENAME), "utf-8");
+        const info = JSON.parse(raw);
+        return typeof info.commit === "string" ? info.commit : "";
+    }
+    catch {
+        // No stamp (source run), unreadable, or malformed — fall through.
+        return "";
+    }
+}
+function git(args, cwd) {
+    // execFileSync, not execSync: no shell, so a path containing spaces or shell
+    // metacharacters is passed through intact instead of silently failing.
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+/**
+ * Short HEAD of the checkout we are running from, or "" when we are not
+ * running from one.
+ *
+ * The guard is the whole point: an enclosing repository is only qmd's if its
+ * top level *is* this package's root. Without that check, any install nested
+ * inside an unrelated repository reports that repository's HEAD.
+ */
+export function gitCommitForCheckout(scriptDir, packageRoot) {
+    try {
+        const top = git(["rev-parse", "--show-toplevel"], scriptDir);
+        if (realpathSync(top) !== realpathSync(packageRoot))
+            return "";
+        const commit = git(["rev-parse", "--short", "HEAD"], top);
+        if (!commit)
+            return "";
+        // Same "-dirty" marker scripts/build.mjs stamps: running edited sources is
+        // not the commit it names, and that distinction is the whole point of
+        // printing a commit at all.
+        const dirty = git(["status", "--porcelain"], top);
+        return dirty ? `${commit}-dirty` : commit;
+    }
+    catch {
+        // Not a git repo, git not installed, or an unborn branch.
+        return "";
+    }
+}
+/**
+ * The commit to report for this invocation: the build stamp when there is one,
+ * otherwise the verified checkout HEAD, otherwise nothing.
+ */
+export function resolveCommit(scriptDir, packageRoot) {
+    return readStampedCommit(scriptDir) || gitCommitForCheckout(scriptDir, packageRoot);
+}

package/dist/collections.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Collections configuration management
+ *
+ * This module manages the YAML-based collection configuration at ~/.config/qmd/index.yml.
+ * Collections define which directories to index and their associated contexts.
+ */
+/**
+ * Context definitions for a collection
+ * Key is path prefix (e.g., "/", "/2024", "/Board of Directors")
+ * Value is the context description
+ */
+export type ContextMap = Record<string, string>;
+/**
+ * A single collection configuration
+ */
+export interface Collection {
+    path: string;
+    pattern: string;
+    ignore?: string[];
+    context?: ContextMap;
+    update?: string;
+    includeByDefault?: boolean;
+}
+/**
+ * Model configuration for embedding, reranking, and generation
+ */
+export interface ModelsConfig {
+    embed?: string;
+    embed_url?: string;
+    embed_base_url?: string;
+    embed_api_url?: string;
+    embed_api_model?: string;
+    embed_api_key?: string;
+    embed_dimension?: number;
+    rerank?: string;
+    generate?: string;
+    generate_url?: string;
+    generate_base_url?: string;
+    generate_api_url?: string;
+    generate_api_model?: string;
+    generate_api_key?: string;
+    rerank_url?: string;
+    rerank_base_url?: string;
+    rerank_api_url?: string;
+    rerank_api_model?: string;
+    rerank_api_key?: string;
+}
+/**
+ * The complete configuration file structure
+ */
+export interface CollectionConfig {
+    global_context?: string;
+    editor_uri?: string;
+    editor_uri_template?: string;
+    editorUri?: string;
+    "editor-uri"?: string;
+    collections: Record<string, Collection>;
+    models?: ModelsConfig;
+    dictionary?: string;
+}
+/**
+ * Collection with its name (for return values)
+ */
+export interface NamedCollection extends Collection {
+    name: string;
+}
+export type CollectionConfigSource = {
+    type: "file";
+    path?: string;
+} | {
+    type: "inline";
+    config: CollectionConfig;
+};
+export declare function createCollectionConfigSource(source?: {
+    configPath?: string;
+    config?: CollectionConfig;
+}): CollectionConfigSource;
+export type ConfigWriteStage = "before-temp-write" | "before-rename";
+/** @internal Test-only fault injection for crash-safety verification. */
+export declare function setConfigWriteFaultInjectorForTests(injector?: (stage: ConfigWriteStage) => void): void;
+/**
+ * Set the config source for SDK mode.
+ * - File path: load/save from a specific YAML file
+ * - Inline config: use an in-memory CollectionConfig (saveConfig updates in place, no file I/O)
+ * - undefined: reset to default file-based config
+ */
+export declare function setConfigSource(source?: {
+    configPath?: string;
+    config?: CollectionConfig;
+}): void;
+/**
+ * Set the current index name for config file lookup
+ * Config file will be ~/.config/qmd/{indexName}.yml
+ */
+export declare function setConfigIndexName(name: string): void;
+export declare function getConfigDir(): string;
+/**
+ * Find a project-local QMD config by walking upward from startDir.
+ * The local config lives at .qmd/index.yaml or .qmd/index.yml and,
+ * when used by the CLI, keeps both config and index DB writes inside
+ * the project instead of the global ~/.config / ~/.cache locations.
+ */
+export declare function findLocalConfigPath(startDir?: string): string | undefined;
+/** Return the local SQLite index path paired with a local .qmd/index.yaml file. */
+export declare function getLocalDbPath(configPath: string): string;
+/**
+ * Load configuration from the configured source.
+ * - Inline config: returns the in-memory object directly
+ * - File-based: reads from YAML file (default ~/.config/qmd/index.yml)
+ * Returns empty config if file doesn't exist
+ */
+export declare function loadConfig(source?: CollectionConfigSource): CollectionConfig;
+/**
+ * Save configuration to the configured source.
+ * - Inline config: updates the in-memory object (no file I/O)
+ * - File-based: writes to YAML file (default ~/.config/qmd/index.yml)
+ */
+export declare function saveConfig(config: CollectionConfig, source?: CollectionConfigSource): void;
+/**
+ * Get a specific collection by name
+ * Returns null if not found
+ */
+export declare function getCollection(name: string): NamedCollection | null;
+/**
+ * List all collections
+ */
+export declare function listCollections(): NamedCollection[];
+/**
+ * Get collections that are included by default in queries
+ */
+export declare function getDefaultCollections(): NamedCollection[];
+/**
+ * Get collection names that are included by default
+ */
+export declare function getDefaultCollectionNames(): string[];
+/**
+ * Update a collection's settings
+ */
+export declare function updateCollectionSettings(name: string, settings: {
+    update?: string | null;
+    includeByDefault?: boolean;
+}): boolean;
+/**
+ * Add or update a collection
+ */
+export declare function addCollection(name: string, path: string, pattern?: string, ignore?: string[], source?: CollectionConfigSource): void;
+/**
+ * Remove a collection
+ */
+export declare function removeCollection(name: string, source?: CollectionConfigSource): boolean;
+/**
+ * Rename a collection
+ */
+export declare function renameCollection(oldName: string, newName: string, source?: CollectionConfigSource): boolean;
+/**
+ * Get global context
+ */
+export declare function getGlobalContext(): string | undefined;
+/**
+ * Set global context
+ */
+export declare function setGlobalContext(context: string | undefined, source?: CollectionConfigSource): void;
+/**
+ * Get all contexts for a collection
+ */
+export declare function getContexts(collectionName: string): ContextMap | undefined;
+/**
+ * Add or update a context for a specific path in a collection
+ */
+export declare function addContext(collectionName: string, pathPrefix: string, contextText: string, source?: CollectionConfigSource): boolean;
+/**
+ * Remove a context from a collection
+ */
+export declare function removeContext(collectionName: string, pathPrefix: string, source?: CollectionConfigSource): boolean;
+/**
+ * List all contexts across all collections
+ */
+export declare function listAllContexts(): Array<{
+    collection: string;
+    path: string;
+    context: string;
+}>;
+/**
+ * Find best matching context for a given collection and path
+ * Returns the most specific matching context (longest path prefix match)
+ */
+export declare function findContextForPath(collectionName: string, filePath: string): string | undefined;
+/**
+ * Get the config file path (useful for error messages)
+ */
+export declare function getConfigPath(): string;
+/**
+ * Check if config file exists
+ */
+export declare function configExists(): boolean;
+/**
+ * Validate a collection name
+ * Collection names must be valid and not contain special characters
+ */
+export declare function isValidCollectionName(name: string): boolean;