lmgrep 0.1.17 → 0.2.0

package/dist/domain/ports/WorkspacePort.d.ts

@@ -0,0 +1,38 @@
+import type { ContentHash } from "../corpus/ContentHash.js";
+import type { SourceFile } from "../corpus/SourceFile.js";
+/** Extension include/exclude overrides layered on the built-in set. */
+export interface ExtensionRules {
+    include?: string[];
+    exclude?: string[];
+}
+/** Stops a running watch. */
+export interface WatchHandle {
+    close(): void;
+}
+/** Files whose on-disk hash differs from what the manifest recorded. */
+export interface ChangeSet {
+    changed: SourceFile[];
+    /** Hash of every readable file scanned, changed or not. */
+    current: Map<string, ContentHash>;
+}
+/**
+ * The working tree: which files exist, what they contain, and when they
+ * change. The indexer talks to this rather than to `node:fs` directly.
+ */
+export interface WorkspacePort {
+    /** Indexable files under `cwd`, honouring ignore rules and extensions. */
+    listFiles(cwd: string, extraIgnore?: string[], extensions?: ExtensionRules): string[];
+    /** Content hash of one file, or undefined when it cannot be read. */
+    hashOf(cwd: string, filePath: string): ContentHash | undefined;
+    /** Keep only files modified at or after `cutoffMs`. */
+    modifiedSince(files: string[], cwd: string, cutoffMs: number): string[];
+    /**
+     * Compare on-disk hashes against a manifest, reporting what differs.
+     * `force` treats every readable file as changed.
+     */
+    detectChanges(files: string[], manifest: {
+        versionOf(path: string): ContentHash | undefined;
+    }, cwd: string, force?: boolean): ChangeSet;
+    /** Watch for changes, debounced, reporting the paths that changed. */
+    watch(cwd: string, extraIgnore: string[] | undefined, onChanges: (changedFiles: string[]) => void, debounceMs: number, extensions?: ExtensionRules): WatchHandle;
+}

package/dist/domain/ports/WorkspacePort.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=WorkspacePort.js.map

package/dist/domain/ports/WorkspacePort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspacePort.js","sourceRoot":"","sources":["../../../src/domain/ports/WorkspacePort.ts"],"names":[],"mappings":""}

package/dist/domain/project/Branch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A branch scope for reads and writes.
+ *
+ * Chunks are shared across branches by content hash; the file manifest is what
+ * is branch-scoped. A manually targeted database is flat — it uses
+ * {@link Branch.DEFAULT} so switching git branches never hides results in a
+ * database the user asked for by name or path.
+ */
+export declare class Branch {
+    private readonly name;
+    /** Scope used by non-git projects and manually targeted databases. */
+    static readonly DEFAULT_NAME = "_default";
+    private constructor();
+    static of(name: string): Branch;
+    static default(): Branch;
+    toString(): string;
+    equals(other: Branch): boolean;
+    /** Single-quote-escaped for embedding in a LanceDB filter predicate. */
+    toSqlLiteral(): string;
+}

package/dist/domain/project/Branch.js

@@ -0,0 +1,33 @@
+/**
+ * A branch scope for reads and writes.
+ *
+ * Chunks are shared across branches by content hash; the file manifest is what
+ * is branch-scoped. A manually targeted database is flat — it uses
+ * {@link Branch.DEFAULT} so switching git branches never hides results in a
+ * database the user asked for by name or path.
+ */
+export class Branch {
+    name;
+    /** Scope used by non-git projects and manually targeted databases. */
+    static DEFAULT_NAME = "_default";
+    constructor(name) {
+        this.name = name;
+    }
+    static of(name) {
+        return new Branch(name);
+    }
+    static default() {
+        return new Branch(Branch.DEFAULT_NAME);
+    }
+    toString() {
+        return this.name;
+    }
+    equals(other) {
+        return this.name === other.name;
+    }
+    /** Single-quote-escaped for embedding in a LanceDB filter predicate. */
+    toSqlLiteral() {
+        return this.name.replace(/'/g, "''");
+    }
+}
+//# sourceMappingURL=Branch.js.map

package/dist/domain/project/Branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Branch.js","sourceRoot":"","sources":["../../../src/domain/project/Branch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,MAAM;IAImB;IAHrC,sEAAsE;IACtE,MAAM,CAAU,YAAY,GAAG,UAAU,CAAC;IAE1C,YAAqC,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAErD,MAAM,CAAC,EAAE,CAAC,IAAY;QACrB,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,CAAC,OAAO;QACb,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACxC,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,YAAY;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC"}

package/dist/domain/project/DatabaseLocation.d.ts

@@ -0,0 +1,32 @@
+import type { Branch } from "./Branch.js";
+/**
+ * The fully-resolved database a command reads from and writes to.
+ *
+ * `manual` records how it was chosen, because that changes behaviour
+ * downstream: a manually targeted database is flat (no branch scoping, no
+ * ancestor prefix walking), while the git-aware default participates in both.
+ */
+export declare class DatabaseLocation {
+    /** Absolute path to the database directory. */
+    readonly path: string;
+    /** Branch scope to read and write. */
+    readonly branch: Branch;
+    /** Project root used for metadata and status display. */
+    readonly root: string;
+    /** True when chosen explicitly via `--database`. */
+    readonly manual: boolean;
+    constructor(
+    /** Absolute path to the database directory. */
+    path: string, 
+    /** Branch scope to read and write. */
+    branch: Branch, 
+    /** Project root used for metadata and status display. */
+    root: string, 
+    /** True when chosen explicitly via `--database`. */
+    manual: boolean);
+    /**
+     * Whether this database participates in branch scoping and ancestor
+     * resolution. False for `--database` targets, which are deliberately flat.
+     */
+    get isGitAware(): boolean;
+}

package/dist/domain/project/DatabaseLocation.js

@@ -0,0 +1,35 @@
+/**
+ * The fully-resolved database a command reads from and writes to.
+ *
+ * `manual` records how it was chosen, because that changes behaviour
+ * downstream: a manually targeted database is flat (no branch scoping, no
+ * ancestor prefix walking), while the git-aware default participates in both.
+ */
+export class DatabaseLocation {
+    path;
+    branch;
+    root;
+    manual;
+    constructor(
+    /** Absolute path to the database directory. */
+    path, 
+    /** Branch scope to read and write. */
+    branch, 
+    /** Project root used for metadata and status display. */
+    root, 
+    /** True when chosen explicitly via `--database`. */
+    manual) {
+        this.path = path;
+        this.branch = branch;
+        this.root = root;
+        this.manual = manual;
+    }
+    /**
+     * Whether this database participates in branch scoping and ancestor
+     * resolution. False for `--database` targets, which are deliberately flat.
+     */
+    get isGitAware() {
+        return !this.manual;
+    }
+}
+//# sourceMappingURL=DatabaseLocation.js.map

package/dist/domain/project/DatabaseLocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseLocation.js","sourceRoot":"","sources":["../../../src/domain/project/DatabaseLocation.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAGlB;IAEA;IAEA;IAEA;IARV;IACC,+CAA+C;IACtC,IAAY;IACrB,sCAAsC;IAC7B,MAAc;IACvB,yDAAyD;IAChD,IAAY;IACrB,oDAAoD;IAC3C,MAAe;QANf,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAAS;IACtB,CAAC;IAEJ;;;OAGG;IACH,IAAI,UAAU;QACb,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACD"}

package/dist/domain/project/IndexMetadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What an index records about itself: where it came from and how it was built.
+ *
+ * The model and dimensions are the important part — they are what lets a later
+ * search detect that it is querying with incompatible embeddings instead of
+ * silently returning nonsense.
+ */
+export interface IndexMetadata {
+    root: string;
+    remote?: string;
+    branch: string;
+    indexedAt: string;
+    /** Full model string used at index time (e.g. "openai:nomic-embed-text"). */
+    model?: string;
+    /** Embedding vector dimensions. */
+    dimensions?: number;
+}

package/dist/domain/project/IndexMetadata.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IndexMetadata.js.map

package/dist/domain/project/IndexMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexMetadata.js","sourceRoot":"","sources":["../../../src/domain/project/IndexMetadata.ts"],"names":[],"mappings":""}

package/dist/domain/project/ModelIdentity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A model string in `provider:model` form, the family comparison that decides
+ * whether two models produce interchangeable embeddings, and the directory
+ * slug derived from it.
+ *
+ * Only the family matters: a re-quantized or re-tagged build of the same model
+ * produces compatible embeddings, and so does the same model served by a
+ * different runtime, so comparing raw strings would partition on differences
+ * that do not exist.
+ *
+ * The slug is the load-bearing part. Databases are stored per model, so
+ * {@link toSlug} draws the boundary between them — and it must draw it in
+ * exactly the same place as {@link isSameFamilyAs}. Two models share a
+ * database if and only if they are compatible; a slug that split more finely
+ * would re-embed a corpus for nothing, and one that split more coarsely would
+ * mix incomparable vectors into one table.
+ */
+export declare class ModelIdentity {
+    private readonly value;
+    /** Quantization and tag suffixes that do not change the embedding space. */
+    private static readonly VARIANT_SUFFIX;
+    /** Long enough to stay readable in a path, short enough to stay a path. */
+    private static readonly SLUG_PREFIX_LENGTH;
+    private static readonly SLUG_HASH_LENGTH;
+    private constructor();
+    static of(model: string): ModelIdentity;
+    toString(): string;
+    /** Provider segment, or undefined when the string carries none. */
+    get provider(): string | undefined;
+    /**
+     * The model name with the provider prefix and any variant suffix removed.
+     *
+     *   "openai:nomic-embed-text"        -> "nomic-embed-text"
+     *   "ollama:nomic-embed-text:Q4_K_M" -> "nomic-embed-text"
+     *   "lmstudio:bge-large-en:fp16"     -> "bge-large-en"
+     */
+    get family(): string;
+    /** Whether two models produce interchangeable embeddings. */
+    isSameFamilyAs(other: ModelIdentity): boolean;
+    /**
+     * Directory name holding this model's embeddings.
+     *
+     * Built from the family rather than the full string, so switching runtimes
+     * (`ollama:` to `lmstudio:`) or pulling a new quantization reuses the index
+     * instead of silently re-embedding the repository.
+     *
+     * `dimensions` is part of the identity because a model with configurable
+     * output width produces vectors that cannot be compared across widths —
+     * same family, different space. It is the one axis {@link isSameFamilyAs}
+     * cannot see, so it is folded in here.
+     *
+     * The trailing hash is what actually guarantees uniqueness: the readable
+     * prefix is truncated, sanitized, and compared case-insensitively by macOS
+     * and Windows filesystems, so it cannot be relied on to separate two
+     * models on its own.
+     */
+    toSlug(dimensions?: number): string;
+}

package/dist/domain/project/ModelIdentity.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+/**
+ * A model string in `provider:model` form, the family comparison that decides
+ * whether two models produce interchangeable embeddings, and the directory
+ * slug derived from it.
+ *
+ * Only the family matters: a re-quantized or re-tagged build of the same model
+ * produces compatible embeddings, and so does the same model served by a
+ * different runtime, so comparing raw strings would partition on differences
+ * that do not exist.
+ *
+ * The slug is the load-bearing part. Databases are stored per model, so
+ * {@link toSlug} draws the boundary between them — and it must draw it in
+ * exactly the same place as {@link isSameFamilyAs}. Two models share a
+ * database if and only if they are compatible; a slug that split more finely
+ * would re-embed a corpus for nothing, and one that split more coarsely would
+ * mix incomparable vectors into one table.
+ */
+export class ModelIdentity {
+    value;
+    /** Quantization and tag suffixes that do not change the embedding space. */
+    static VARIANT_SUFFIX = /^(Q\d|q\d|fp\d|f\d|latest|gguf|ggml)/i;
+    /** Long enough to stay readable in a path, short enough to stay a path. */
+    static SLUG_PREFIX_LENGTH = 48;
+    static SLUG_HASH_LENGTH = 8;
+    constructor(value) {
+        this.value = value;
+    }
+    static of(model) {
+        return new ModelIdentity(model);
+    }
+    toString() {
+        return this.value;
+    }
+    /** Provider segment, or undefined when the string carries none. */
+    get provider() {
+        const colon = this.value.indexOf(":");
+        return colon === -1 ? undefined : this.value.slice(0, colon);
+    }
+    /**
+     * The model name with the provider prefix and any variant suffix removed.
+     *
+     *   "openai:nomic-embed-text"        -> "nomic-embed-text"
+     *   "ollama:nomic-embed-text:Q4_K_M" -> "nomic-embed-text"
+     *   "lmstudio:bge-large-en:fp16"     -> "bge-large-en"
+     */
+    get family() {
+        const colon = this.value.indexOf(":");
+        if (colon === -1)
+            return this.value;
+        const rest = this.value.slice(colon + 1);
+        const lastColon = rest.lastIndexOf(":");
+        if (lastColon === -1)
+            return rest;
+        const suffix = rest.slice(lastColon + 1);
+        if (ModelIdentity.VARIANT_SUFFIX.test(suffix)) {
+            return rest.slice(0, lastColon);
+        }
+        // Unrecognized trailing segment — likely part of the name itself.
+        return rest;
+    }
+    /** Whether two models produce interchangeable embeddings. */
+    isSameFamilyAs(other) {
+        return this.family === other.family;
+    }
+    /**
+     * Directory name holding this model's embeddings.
+     *
+     * Built from the family rather than the full string, so switching runtimes
+     * (`ollama:` to `lmstudio:`) or pulling a new quantization reuses the index
+     * instead of silently re-embedding the repository.
+     *
+     * `dimensions` is part of the identity because a model with configurable
+     * output width produces vectors that cannot be compared across widths —
+     * same family, different space. It is the one axis {@link isSameFamilyAs}
+     * cannot see, so it is folded in here.
+     *
+     * The trailing hash is what actually guarantees uniqueness: the readable
+     * prefix is truncated, sanitized, and compared case-insensitively by macOS
+     * and Windows filesystems, so it cannot be relied on to separate two
+     * models on its own.
+     */
+    toSlug(dimensions) {
+        const identity = dimensions ? `${this.family}@${dimensions}` : this.family;
+        const hash = createHash("sha256")
+            .update(identity)
+            .digest("hex")
+            .slice(0, ModelIdentity.SLUG_HASH_LENGTH);
+        const readable = this.family
+            .replace(/[^a-zA-Z0-9._-]/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "")
+            .slice(0, ModelIdentity.SLUG_PREFIX_LENGTH);
+        return readable.length > 0 ? `${readable}-${hash}` : hash;
+    }
+}
+//# sourceMappingURL=ModelIdentity.js.map

package/dist/domain/project/ModelIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelIdentity.js","sourceRoot":"","sources":["../../../src/domain/project/ModelIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IASY;IARrC,4EAA4E;IACpE,MAAM,CAAU,cAAc,GACrC,uCAAuC,CAAC;IAEzC,2EAA2E;IACnE,MAAM,CAAU,kBAAkB,GAAG,EAAE,CAAC;IACxC,MAAM,CAAU,gBAAgB,GAAG,CAAC,CAAC;IAE7C,YAAqC,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAEtD,MAAM,CAAC,EAAE,CAAC,KAAa;QACtB,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,mEAAmE;IACnE,IAAI,QAAQ;QACX,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;OAMG;IACH,IAAI,MAAM;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,SAAS,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,aAAa,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACjC,CAAC;QACD,kEAAkE;QAClE,OAAO,IAAI,CAAC;IACb,CAAC;IAED,6DAA6D;IAC7D,cAAc,CAAC,KAAoB;QAClC,OAAO,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,UAAmB;QACzB,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3E,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;aAC/B,MAAM,CAAC,QAAQ,CAAC;aAChB,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM;aAC1B,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;aAChC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;aACrB,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;QAC7C,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,CAAC"}

package/dist/domain/project/Project.d.ts

@@ -0,0 +1,17 @@
+import type { Branch } from "./Branch.js";
+import type { ProjectId } from "./ProjectId.js";
+/** A resolved project: its identity, working-tree root and current branch. */
+export declare class Project {
+    readonly id: ProjectId;
+    /** Git toplevel, or the absolute directory outside a repo. */
+    readonly root: string;
+    readonly branch: Branch;
+    /** Origin remote URL, when the project has one. */
+    readonly remote?: string | undefined;
+    constructor(id: ProjectId, 
+    /** Git toplevel, or the absolute directory outside a repo. */
+    root: string, branch: Branch, 
+    /** Origin remote URL, when the project has one. */
+    remote?: string | undefined);
+    get isGitRepository(): boolean;
+}

package/dist/domain/project/Project.js

@@ -0,0 +1,21 @@
+/** A resolved project: its identity, working-tree root and current branch. */
+export class Project {
+    id;
+    root;
+    branch;
+    remote;
+    constructor(id, 
+    /** Git toplevel, or the absolute directory outside a repo. */
+    root, branch, 
+    /** Origin remote URL, when the project has one. */
+    remote) {
+        this.id = id;
+        this.root = root;
+        this.branch = branch;
+        this.remote = remote;
+    }
+    get isGitRepository() {
+        return this.remote !== undefined || this.branch.toString() !== "_default";
+    }
+}
+//# sourceMappingURL=Project.js.map

package/dist/domain/project/Project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Project.js","sourceRoot":"","sources":["../../../src/domain/project/Project.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,MAAM,OAAO,OAAO;IAET;IAEA;IACA;IAEA;IANV,YACU,EAAa;IACtB,8DAA8D;IACrD,IAAY,EACZ,MAAc;IACvB,mDAAmD;IAC1C,MAAe;QALf,OAAE,GAAF,EAAE,CAAW;QAEb,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QAEd,WAAM,GAAN,MAAM,CAAS;IACtB,CAAC;IAEJ,IAAI,eAAe;QAClB,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,UAAU,CAAC;IAC3E,CAAC;CACD"}

package/dist/domain/project/ProjectId.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The identity of a project, and the on-disk slug derived from it.
+ *
+ * Identity is the git remote URL when there is one, so every worktree and
+ * clone of the same repository shares a single index. Without a remote it
+ * falls back to the git root, and outside git to the absolute path.
+ */
+export declare class ProjectId {
+    private readonly value;
+    private constructor();
+    static of(value: string): ProjectId;
+    toString(): string;
+    equals(other: ProjectId): boolean;
+    /**
+     * Directory name for this project's database: a readable prefix plus a hash
+     * of the full identity. The prefix is for humans browsing the state
+     * directory; the hash is what actually guarantees uniqueness.
+     */
+    toSlug(): string;
+    /**
+     * Strip the git URL scheme and any trailing `.git` so worktrees of one repo
+     * produce the same prefix regardless of where they live on disk.
+     *   git@host:user/repo.git      -> user-repo
+     *   https://host/user/repo.git  -> user-repo
+     *   /abs/path/to/project        -> to-project
+     */
+    private readablePrefix;
+}

package/dist/domain/project/ProjectId.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+/**
+ * The identity of a project, and the on-disk slug derived from it.
+ *
+ * Identity is the git remote URL when there is one, so every worktree and
+ * clone of the same repository shares a single index. Without a remote it
+ * falls back to the git root, and outside git to the absolute path.
+ */
+export class ProjectId {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    static of(value) {
+        return new ProjectId(value);
+    }
+    toString() {
+        return this.value;
+    }
+    equals(other) {
+        return this.value === other.value;
+    }
+    /**
+     * Directory name for this project's database: a readable prefix plus a hash
+     * of the full identity. The prefix is for humans browsing the state
+     * directory; the hash is what actually guarantees uniqueness.
+     */
+    toSlug() {
+        const hash = createHash("sha256")
+            .update(this.value)
+            .digest("hex")
+            .slice(0, 8);
+        return `${this.readablePrefix()}-${hash}`;
+    }
+    /**
+     * Strip the git URL scheme and any trailing `.git` so worktrees of one repo
+     * produce the same prefix regardless of where they live on disk.
+     *   git@host:user/repo.git      -> user-repo
+     *   https://host/user/repo.git  -> user-repo
+     *   /abs/path/to/project        -> to-project
+     */
+    readablePrefix() {
+        let s = this.value.replace(/\.git$/, "");
+        const scpMatch = s.match(/^[^@]+@[^:]+:(.+)$/);
+        if (scpMatch) {
+            s = scpMatch[1];
+        }
+        else {
+            s = s.replace(/^[a-z]+:\/\/[^/]+\//, "");
+        }
+        const parts = s.split("/").filter(Boolean);
+        return parts
+            .slice(-2)
+            .join("-")
+            .replace(/[^a-zA-Z0-9_-]/g, "_");
+    }
+}
+//# sourceMappingURL=ProjectId.js.map

package/dist/domain/project/ProjectId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectId.js","sourceRoot":"","sources":["../../../src/domain/project/ProjectId.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACgB;IAArC,YAAqC,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAEtD,MAAM,CAAC,EAAE,CAAC,KAAa;QACtB,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,KAAgB;QACtB,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,MAAM;QACL,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;aAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;aAClB,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACd,OAAO,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACK,cAAc;QACrB,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAC/C,IAAI,QAAQ,EAAE,CAAC;YACd,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACP,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3C,OAAO,KAAK;aACV,KAAK,CAAC,CAAC,CAAC,CAAC;aACT,IAAI,CAAC,GAAG,CAAC;aACT,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;CACD"}

package/dist/domain/project/ProjectLocator.d.ts

@@ -0,0 +1,112 @@
+import type { GitPort } from "../ports/GitPort.js";
+import type { StateDirectoryPort } from "../ports/StateDirectoryPort.js";
+import { DatabaseLocation } from "./DatabaseLocation.js";
+import type { ModelIdentity } from "./ModelIdentity.js";
+import { Project } from "./Project.js";
+/** Where a working directory sits relative to the indexed project root. */
+export interface IndexedAncestor {
+    root: string;
+    /** Subdirectory offset from the root, "" when they are the same. */
+    prefix: string;
+}
+/**
+ * Translates a working directory into a project identity and a database
+ * location.
+ *
+ * This is the only place that knows the rules, and there are three:
+ *
+ * **A repository's index lives inside it**, at `<git-common-dir>/lmgrep/`.
+ * Git resolves that to the main checkout's `.git` even from a linked worktree,
+ * so every worktree of a repository agrees on one index by construction rather
+ * than by a shared registry that could disagree with reality. It also means
+ * the index is found by `du`, deleted by `rm -rf`, and gone when the clone is
+ * — which is what stops orphaned databases from accumulating somewhere the
+ * user never looks. Git never walks its own directory, so nothing here is ever
+ * committed or indexed.
+ *
+ * **Each embedding model gets its own database.** Vectors from different
+ * models are not comparable, so pointing lmgrep at a new model used to mean
+ * discarding the index or searching it with embeddings that quietly meant
+ * nothing. Keyed by model, switching is just a different subdirectory, and
+ * switching back finds the old index intact.
+ *
+ * **Everything else falls back to the state directory**: projects outside git
+ * have no repository to live in, and `--database <name>` is by definition not
+ * tied to one.
+ */
+export declare class ProjectLocator {
+    private readonly git;
+    private readonly state;
+    /** The configured embedding model, which partitions the databases. */
+    private readonly model;
+    /** Configured output width, when the model has a configurable one. */
+    private readonly dimensions?;
+    /** Subdirectory of the git common directory holding every model's index. */
+    private static readonly REPOSITORY_SUBDIRECTORY;
+    constructor(git: GitPort, state: StateDirectoryPort, 
+    /** The configured embedding model, which partitions the databases. */
+    model: ModelIdentity, 
+    /** Configured output width, when the model has a configurable one. */
+    dimensions?: number | undefined);
+    /**
+     * Identify the project containing `cwd`.
+     *
+     * A git repo is identified by its origin URL when it has one, so every
+     * worktree and clone maps to a single identity; a remoteless repo falls
+     * back to its root path, and a plain directory to its own absolute path.
+     */
+    resolveProject(cwd: string): Project;
+    /** The directory holding every model's index for the project at `cwd`. */
+    indexHomeFor(cwd: string): string;
+    /** Database directory for the project containing `cwd`. */
+    databasePathFor(cwd: string): string;
+    /**
+     * The working tree a repository index belongs to, for display and for the
+     * registry.
+     *
+     * Worktrees share one database, so the toplevel of whichever worktree
+     * happened to run the index would name an arbitrary one of them. The main
+     * checkout — the parent of the common directory — is the stable answer.
+     */
+    projectRootFor(cwd: string): string;
+    /** Directory name the configured model's embeddings are stored under. */
+    modelSlug(): string;
+    /**
+     * Where an index built with `model` belongs.
+     *
+     * Needed when adopting a database written by an older layout, which knows
+     * which model built it but not which slot the current rules would put it
+     * in. It must go through here rather than deriving a slug independently:
+     * the width only counts when it was *configured*, since an index records
+     * the width it observed and that is the model's native size whenever
+     * nothing was requested. Computing the slug from the recorded width
+     * instead produced a directory the locator would never look in — an
+     * adopted index that was silently invisible.
+     */
+    databasePathForModel(cwd: string, model: ModelIdentity): string;
+    /**
+     * Decide which database a command targets.
+     *
+     * With no override this is the repository's index for the configured
+     * model. An override containing a separator is taken literally — it is an
+     * exact address, and appending anything to it would make it impossible to
+     * point at a database that already exists. A bare name is an identity
+     * instead, so it is model-scoped like any other.
+     *
+     * Either way the result is flat and branch-agnostic: indexing and search
+     * both use the default branch, so switching git branches never hides
+     * results in a database the user asked for explicitly. `cwd` still drives
+     * file scanning; only the database identity changes.
+     */
+    resolveDatabase(cwd: string, database?: string): DatabaseLocation;
+    /**
+     * Find the indexed project root covering `cwd` and the prefix from it.
+     *
+     * For a git repo the root is the toplevel. Outside git, walks up looking
+     * for an ancestor that already has an index, so running from a
+     * subdirectory of an indexed tree still finds it.
+     */
+    findIndexedAncestor(cwd: string): IndexedAncestor | undefined;
+    /** A `--database` override is a path when it carries a separator. */
+    private isPathLike;
+}