@lorepack/cli 0.0.0-stage → 0.1.0-alpha.0

package/dist/services/parse-cache.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFileAtomic } from '@lorepack/core';
+/** Bumped when the cached shape changes, so old entries are ignored instead of misread. */
+const CACHE_FORMAT_VERSION = 2;
+export class ParseCache {
+    #directory;
+    #hits = 0;
+    #misses = 0;
+    constructor(directory) {
+        this.#directory = directory;
+    }
+    get hits() {
+        return this.#hits;
+    }
+    get misses() {
+        return this.#misses;
+    }
+    get(key) {
+        const path = this.#pathFor(key);
+        if (!existsSync(path)) {
+            this.#misses += 1;
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed.version !== CACHE_FORMAT_VERSION || typeof parsed.objectHash !== 'string') {
+                this.#misses += 1;
+                return null;
+            }
+            this.#hits += 1;
+            return {
+                artifact: parsed.artifact,
+                nodes: parsed.nodes,
+                chunks: parsed.chunks,
+                objectHash: parsed.objectHash,
+                ...(parsed.warnings === undefined ? {} : { warnings: parsed.warnings }),
+            };
+        }
+        catch {
+            this.#misses += 1;
+            return null;
+        }
+    }
+    put(key, value) {
+        const envelope = { version: CACHE_FORMAT_VERSION, ...value };
+        try {
+            mkdirSync(join(this.#directory, key.slice(0, 2)), { recursive: true });
+            writeFileAtomic(this.#pathFor(key), JSON.stringify(envelope));
+        }
+        catch {
+            // A cache that cannot be written (read-only volume, full disk) must not fail a build
+            // that is otherwise complete.
+        }
+    }
+    clear() {
+        rmSync(this.#directory, { recursive: true, force: true, maxRetries: 3 });
+    }
+    /** Sharded by the first byte of the key: a flat directory of 50,000 entries is slow to
+     * enumerate on every platform we support. */
+    #pathFor(key) {
+        return join(this.#directory, key.slice(0, 2), `${key}.json`);
+    }
+}
+//# sourceMappingURL=parse-cache.js.map

package/dist/services/parse-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-cache.js","sourceRoot":"","sources":["../../src/services/parse-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA2CjD,2FAA2F;AAC3F,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B,MAAM,OAAO,UAAU;IACZ,UAAU,CAAS;IAC5B,KAAK,GAAG,CAAC,CAAC;IACV,OAAO,GAAG,CAAC,CAAC;IAEZ,YAAY,SAAiB;QAC3B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAkB,CAAC;YACvE,IAAI,MAAM,CAAC,OAAO,KAAK,oBAAoB,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;gBACrF,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;gBAClB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;YAChB,OAAO;gBACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;aACxE,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAkB;QACjC,MAAM,QAAQ,GAAkB,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,KAAK,EAAE,CAAC;QAC5E,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACvE,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,qFAAqF;YACrF,8BAA8B;QAChC,CAAC;IACH,CAAC;IAED,KAAK;QACH,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED;iDAC6C;IAC7C,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/services/project.d.ts

@@ -0,0 +1,49 @@
+import type { PreviousBuild } from '@lorepack/compiler';
+import { type BuildId, type LoadedConfig } from '@lorepack/core';
+/**
+ * Reads what the active build recorded, so a plan can compare against it.
+ *
+ * Every read here is read-only, including the state database. `lorepack plan` and `lorepack status`
+ * must not write, not even a migration, or they would stop being previews. A project that
+ * has never been built has no state database at all, which is the case a new user hits, so
+ * absence is a normal answer rather than an error.
+ */
+export interface ProjectState {
+    readonly state: {
+        close: () => void;
+    } | null;
+    readonly previous: PreviousBuild | null;
+}
+export declare function readPreviousBuild(config: LoadedConfig): ProjectState;
+/** The active pointer, read without opening the state store for writing. */
+export declare function readActiveBuild(loreDirectory: string): {
+    buildId: BuildId;
+    generation: number;
+} | null;
+/**
+ * Reads the comparison basis out of the sealed build itself rather than a side table.
+ *
+ * The build is the source of truth (invariant 1), so dirtiness is computed against what
+ * the active build actually contains. A summary cached elsewhere could drift from the
+ * build it claims to describe, and then `lorepack status` would confidently lie.
+ */
+/**
+ * What the previous build contains, or `null` if it cannot say.
+ *
+ * **Best effort, deliberately.** This exists to let a rebuild reuse unchanged artifacts, which
+ * is an optimisation. A build whose database is missing, truncated or overwritten used to take
+ * the *next* build down with it, which is precisely backwards: the command that exists to
+ * produce a good build failed because a bad one existed, and the project could not be recovered
+ * at all (#251). Returning `null` costs a full rebuild and is always correct.
+ */
+export declare function readBuildCatalog(loreDirectory: string, buildId: BuildId): PreviousBuild | null;
+/**
+ * Whether a sealed build can actually be read.
+ *
+ * `state.sqlite` records that a build exists; it says nothing about the directory it points at,
+ * which is a separate file tree that a disk, a sync tool or a `.gitignore` miss can remove or
+ * corrupt independently. Reuse used to trust the record alone and report "No changes" over a
+ * build nobody could open (#251).
+ */
+export declare function isBuildReadable(loreDirectory: string, buildId: BuildId): boolean;
+//# sourceMappingURL=project.d.ts.map

package/dist/services/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/services/project.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAEL,KAAK,OAAO,EAGZ,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CACzC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAKpE;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,GACpB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAcjD;AAED;;;;;;GAMG;AACH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAQ9F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAOhF"}

package/dist/services/project.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildMigrationsDirectory, loadMigrations, openReadOnly } from '@lorepack/backend-local';
+import { assertBuildId, buildManifestSchema, LORE_DIRECTORY, } from '@lorepack/core';
+export function readPreviousBuild(config) {
+    const loreDirectory = join(config.projectRoot, LORE_DIRECTORY);
+    const active = readActiveBuild(loreDirectory);
+    if (active === null)
+        return { state: null, previous: null };
+    return { state: null, previous: readBuildCatalog(loreDirectory, active.buildId) };
+}
+/** The active pointer, read without opening the state store for writing. */
+export function readActiveBuild(loreDirectory) {
+    const statePath = join(loreDirectory, 'state.sqlite');
+    if (!existsSync(statePath))
+        return null;
+    const db = openReadOnly(statePath);
+    try {
+        const row = db
+            .prepare('SELECT build_id AS buildId, generation FROM active_build WHERE id = 1')
+            .get();
+        if (row === undefined || row.buildId === null)
+            return null;
+        return { buildId: assertBuildId(row.buildId), generation: Number(row.generation) };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Reads the comparison basis out of the sealed build itself rather than a side table.
+ *
+ * The build is the source of truth (invariant 1), so dirtiness is computed against what
+ * the active build actually contains. A summary cached elsewhere could drift from the
+ * build it claims to describe, and then `lorepack status` would confidently lie.
+ */
+/**
+ * What the previous build contains, or `null` if it cannot say.
+ *
+ * **Best effort, deliberately.** This exists to let a rebuild reuse unchanged artifacts, which
+ * is an optimisation. A build whose database is missing, truncated or overwritten used to take
+ * the *next* build down with it, which is precisely backwards: the command that exists to
+ * produce a good build failed because a bad one existed, and the project could not be recovered
+ * at all (#251). Returning `null` costs a full rebuild and is always correct.
+ */
+export function readBuildCatalog(loreDirectory, buildId) {
+    try {
+        return readBuildCatalogOrThrow(loreDirectory, buildId);
+    }
+    catch {
+        // Damaged past the point of being an optimisation. `isBuildReadable` is what turns this
+        // into something the user is told about, rather than a silent full rebuild.
+        return null;
+    }
+}
+/**
+ * Whether a sealed build can actually be read.
+ *
+ * `state.sqlite` records that a build exists; it says nothing about the directory it points at,
+ * which is a separate file tree that a disk, a sync tool or a `.gitignore` miss can remove or
+ * corrupt independently. Reuse used to trust the record alone and report "No changes" over a
+ * build nobody could open (#251).
+ */
+export function isBuildReadable(loreDirectory, buildId) {
+    try {
+        if (readBuildCatalogOrThrow(loreDirectory, buildId) === null)
+            return false;
+        return buildSchemaMatches(loreDirectory, buildId);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the build's catalog schema is the one this binary reads.
+ *
+ * The same comparison the runtime makes when it opens a build, made here so `lorepack build` can
+ * act on it. Without this a build written by an older Lorepack passes every other check, is
+ * reported as "No changes", and then fails at the first request with the guard's message
+ * telling the user to run the command that just declined to help (#251, #235).
+ *
+ * Against the migration files this binary ships, so a future migration is covered by having
+ * been added rather than by anyone remembering a number.
+ */
+function buildSchemaMatches(loreDirectory, buildId) {
+    const path = join(loreDirectory, 'builds', buildId, 'context.sqlite');
+    const expected = loadMigrations(buildMigrationsDirectory()).reduce((highest, one) => (one.id > highest ? one.id : highest), '0000');
+    const db = openReadOnly(path);
+    try {
+        const row = db.prepare('SELECT max(id) AS latest FROM schema_migrations').get();
+        return (row?.latest ?? '0000') === expected;
+    }
+    finally {
+        db.close();
+    }
+}
+function readBuildCatalogOrThrow(loreDirectory, buildId) {
+    const path = join(loreDirectory, 'builds', buildId, 'context.sqlite');
+    if (!existsSync(path))
+        return null;
+    const manifest = buildManifestSchema.parse(JSON.parse(readFileSync(join(loreDirectory, 'builds', buildId, 'manifest.json'), 'utf8')));
+    const db = openReadOnly(path);
+    try {
+        const rows = db.prepare('SELECT id, content_hash FROM artifacts').all();
+        const chunks = db.prepare('SELECT count(*) AS n FROM chunks').get();
+        return {
+            buildId,
+            artifactHashes: new Map(rows.map((row) => [row.id, row.content_hash])),
+            chunkCount: Number(chunks.n),
+            configurationHash: manifest.configurationHash,
+            tableCount: manifest.counts.tables,
+            capabilities: manifest.capabilities,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=project.js.map

package/dist/services/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/services/project.ts"],"names":[],"mappings":"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"}

package/dist/services/remote-prune.d.ts

@@ -0,0 +1,7 @@
+import { type RemoteRetentionReceipt } from '@lorepack/core';
+export declare function remotePruneReceiptsDirectory(projectRoot: string): string;
+export declare function remotePruneReceiptPath(projectRoot: string, receiptId: string): string;
+export declare function readRemotePruneReceipt(projectRoot: string, receiptId: string): RemoteRetentionReceipt;
+export declare function writeRemotePruneReceipt(projectRoot: string, receipt: RemoteRetentionReceipt): void;
+export declare function remotePruneReceiptId(seed: string | null): string;
+//# sourceMappingURL=remote-prune.d.ts.map

package/dist/services/remote-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-prune.d.ts","sourceRoot":"","sources":["../../src/services/remote-prune.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,sBAAsB,EAG5B,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAuBxB;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAMN;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhE"}

package/dist/services/remote-prune.js

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { LORE_DIRECTORY, LoreError, remoteRetentionReceiptSchema, writeFileAtomic, } from '@lorepack/core';
+export function remotePruneReceiptsDirectory(projectRoot) {
+    return join(projectRoot, LORE_DIRECTORY, 'receipts');
+}
+export function remotePruneReceiptPath(projectRoot, receiptId) {
+    return join(remotePruneReceiptsDirectory(projectRoot), `${receiptId}.json`);
+}
+export function readRemotePruneReceipt(projectRoot, receiptId) {
+    const path = remotePruneReceiptPath(projectRoot, receiptId);
+    if (!existsSync(path)) {
+        throw new LoreError('LORE_E_BUILD_NOT_FOUND', `No remote cleanup receipt ${receiptId}.`, {
+            remediation: 'Check the receipt id, or start the cleanup again from the beginning.',
+            subject: receiptId,
+        });
+    }
+    const parsed = remoteRetentionReceiptSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+    if (!parsed.success) {
+        throw new LoreError('LORE_E_BUILD_VALIDATION', `Remote cleanup receipt ${receiptId} is not readable.`, {
+            remediation: 'Start the cleanup again from the beginning. A receipt is a record, so losing one is safe.',
+            subject: receiptId,
+        });
+    }
+    return parsed.data;
+}
+export function writeRemotePruneReceipt(projectRoot, receipt) {
+    mkdirSync(remotePruneReceiptsDirectory(projectRoot), { recursive: true });
+    writeFileAtomic(remotePruneReceiptPath(projectRoot, receipt.receiptId), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+export function remotePruneReceiptId(seed) {
+    return `cloudflare-prune-${seed === null ? 'none' : seed.slice(5, 17)}`;
+}
+//# sourceMappingURL=remote-prune.js.map

package/dist/services/remote-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-prune.js","sourceRoot":"","sources":["../../src/services/remote-prune.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,cAAc,EACd,SAAS,EAET,4BAA4B,EAC5B,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAC9D,OAAO,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,WAAmB,EAAE,SAAiB;IAC3E,OAAO,IAAI,CAAC,4BAA4B,CAAC,WAAW,CAAC,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,WAAmB,EACnB,SAAiB;IAEjB,MAAM,IAAI,GAAG,sBAAsB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,wBAAwB,EAAE,6BAA6B,SAAS,GAAG,EAAE;YACvF,WAAW,EAAE,sEAAsE;YACnF,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,4BAA4B,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9F,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CACjB,yBAAyB,EACzB,0BAA0B,SAAS,mBAAmB,EACtD;YACE,WAAW,EACT,2FAA2F;YAC7F,OAAO,EAAE,SAAS;SACnB,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,OAA+B;IAE/B,SAAS,CAAC,4BAA4B,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,eAAe,CACb,sBAAsB,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,EACtD,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAmB;IACtD,OAAO,oBAAoB,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AAC1E,CAAC"}

package/dist/services/retention.d.ts

@@ -0,0 +1,20 @@
+import { type BuildId, type BuildSummary } from '@lorepack/core';
+/**
+ * Local retention (architecture section 17.8): keep the active build and the previous five
+ * verified builds.
+ *
+ * A cleanup plan is always produced before anything is removed, and objects referenced by
+ * a retained build are never deleted. Retention exists to bound disk use, so deleting
+ * something a surviving build still needs would defeat its own purpose.
+ */
+export declare const DEFAULT_KEEP_PREVIOUS = 5;
+export interface RetentionPlan {
+    readonly keep: readonly BuildId[];
+    readonly remove: readonly BuildId[];
+    readonly objectsToRemove: readonly string[];
+    readonly bytesFreed: number;
+}
+export declare function planRetention(loreDirectory: string, builds: readonly BuildSummary[], active: BuildId | null, keepPrevious?: number): RetentionPlan;
+export declare function applyRetention(loreDirectory: string, plan: RetentionPlan): void;
+export declare function renderRetentionPlan(plan: RetentionPlan): string;
+//# sourceMappingURL=retention.d.ts.map

package/dist/services/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/services/retention.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,gBAAgB,CAAC;AAGxE;;;;;;;GAOG;AAEH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,YAAY,GAAE,MAA8B,GAC3C,aAAa,CAwCf;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAO/E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAY/D"}

package/dist/services/retention.js

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { openReadOnly } from '@lorepack/backend-local';
+import { count } from '@lorepack/core';
+import { buildDirectory } from './builds.js';
+/**
+ * Local retention (architecture section 17.8): keep the active build and the previous five
+ * verified builds.
+ *
+ * A cleanup plan is always produced before anything is removed, and objects referenced by
+ * a retained build are never deleted. Retention exists to bound disk use, so deleting
+ * something a surviving build still needs would defeat its own purpose.
+ */
+export const DEFAULT_KEEP_PREVIOUS = 5;
+export function planRetention(loreDirectory, builds, active, keepPrevious = DEFAULT_KEEP_PREVIOUS) {
+    // Newest first, with the active build pinned regardless of its position in history.
+    const ordered = [...builds].sort((a, b) => a.createdAt === b.createdAt
+        ? b.buildId.localeCompare(a.buildId)
+        : b.createdAt.localeCompare(a.createdAt));
+    const keep = new Set();
+    if (active !== null)
+        keep.add(active);
+    for (const build of ordered) {
+        if (keep.size >= keepPrevious + (active === null ? 0 : 1))
+            break;
+        if (build.state === 'failed')
+            continue;
+        keep.add(build.buildId);
+    }
+    const remove = ordered.map((build) => build.buildId).filter((id) => !keep.has(id));
+    // Objects are content addressed and shared between builds, so a hash is only removable
+    // when no retained build references it.
+    const referenced = new Set();
+    for (const id of keep) {
+        for (const hash of objectHashesOf(loreDirectory, id))
+            referenced.add(hash);
+    }
+    const doomed = new Set();
+    for (const id of remove) {
+        for (const hash of objectHashesOf(loreDirectory, id)) {
+            if (!referenced.has(hash))
+                doomed.add(hash);
+        }
+    }
+    return {
+        keep: [...keep],
+        remove,
+        objectsToRemove: [...doomed].sort(),
+        bytesFreed: remove.reduce((sum, id) => sum + directorySize(buildDirectory(loreDirectory, id)), 0),
+    };
+}
+export function applyRetention(loreDirectory, plan) {
+    for (const id of plan.remove) {
+        rmSync(buildDirectory(loreDirectory, id), { recursive: true, force: true, maxRetries: 3 });
+    }
+    for (const hash of plan.objectsToRemove) {
+        rmSync(objectPath(loreDirectory, hash), { force: true, maxRetries: 3 });
+    }
+}
+export function renderRetentionPlan(plan) {
+    if (plan.remove.length === 0) {
+        return `Nothing to remove. ${count(plan.keep.length, 'build')} retained.`;
+    }
+    const lines = [
+        `Removing ${count(plan.remove.length, 'build')}, keeping ${plan.keep.length}:`,
+        '',
+    ];
+    for (const id of plan.remove)
+        lines.push(`  - ${id}`);
+    lines.push('', `  ${count(plan.objectsToRemove.length, 'unreferenced object')}`);
+    lines.push(`  about ${Math.round(plan.bytesFreed / 1024)} KB freed`);
+    return lines.join('\n');
+}
+function objectHashesOf(loreDirectory, buildId) {
+    const path = join(buildDirectory(loreDirectory, buildId), 'context.sqlite');
+    if (!existsSync(path))
+        return [];
+    const db = openReadOnly(path);
+    try {
+        return db.prepare('SELECT DISTINCT object_hash FROM artifacts').all().map((row) => row.object_hash);
+    }
+    finally {
+        db.close();
+    }
+}
+function objectPath(loreDirectory, hash) {
+    return join(loreDirectory, 'objects', 'sha256', hash.slice(0, 2), hash.slice(2, 4), hash.slice(4));
+}
+function directorySize(directory) {
+    if (!existsSync(directory))
+        return 0;
+    let total = 0;
+    for (const entry of readdirSync(directory, { withFileTypes: true, recursive: true })) {
+        if (!entry.isFile())
+            continue;
+        try {
+            total += readFileSync(join(entry.parentPath, entry.name)).byteLength;
+        }
+        catch {
+            // A file that vanished between listing and reading contributes nothing. The figure
+            // is an estimate shown to a human, not an accounting record.
+        }
+    }
+    return total;
+}
+//# sourceMappingURL=retention.js.map

package/dist/services/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/services/retention.ts"],"names":[],"mappings":"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"}

package/dist/services/revalidate.d.ts

@@ -0,0 +1,36 @@
+import type { LoadedConfig, SourceState } from '@lorepack/core';
+/**
+ * Keeping a long-lived server honest about freshness, without paying for it every request.
+ *
+ * An open MCP connection is not a session (2026-07-28), so a process can serve one
+ * conversation for an hour. Checking freshness once at startup would let it report `clean`
+ * for that entire hour while the sources moved underneath it.
+ *
+ * Checking properly on every request is the other failure. Content hashing every artifact
+ * is what dominates a no-op build, and at the 50,000-chunk envelope, on bursty agent
+ * traffic, that is seconds of work to annotate a result that took milliseconds.
+ *
+ * So: an interval, and a cheap prescreen inside it. Architecture 12.3 permits size and
+ * mtime as a **prescreen** while keeping content hashes as the deciding evidence, which is
+ * exactly this case. A scan that finds nothing moved answers from cache; a scan that finds
+ * something calls the real, hashing check.
+ */
+export interface RevalidatorOptions {
+    readonly config: LoadedConfig;
+    /** Milliseconds between checks. `0` checks every request. */
+    readonly intervalMs: number;
+    /** Never checks. The answer is whatever the first one was. */
+    readonly frozen?: boolean;
+    readonly now?: () => number;
+}
+export interface Revalidator {
+    /** The freshness to stamp on a response, cheap enough to call per request. */
+    freshness(): Promise<SourceState>;
+    /** How many full, hashing checks have run. The test for "no filesystem work" reads it. */
+    readonly deepChecks: number;
+    /** How many cheap metadata scans have run. */
+    readonly prescreens: number;
+}
+export declare const DEFAULT_REVALIDATE_INTERVAL_MS = 5000;
+export declare function createRevalidator(options: RevalidatorOptions): Revalidator;
+//# sourceMappingURL=revalidate.d.ts.map

package/dist/services/revalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revalidate.d.ts","sourceRoot":"","sources":["../../src/services/revalidate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGhE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAwC1E"}

package/dist/services/revalidate.js

@@ -0,0 +1,73 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { discover } from '@lorepack/compiler';
+import { readFreshness } from './status.js';
+export const DEFAULT_REVALIDATE_INTERVAL_MS = 5000;
+export function createRevalidator(options) {
+    const now = options.now ?? Date.now;
+    let cached = 'unknown';
+    let checkedAt = Number.NEGATIVE_INFINITY;
+    let signature = '';
+    let deepChecks = 0;
+    let prescreens = 0;
+    let started = false;
+    const state = {
+        get deepChecks() {
+            return deepChecks;
+        },
+        get prescreens() {
+            return prescreens;
+        },
+        async freshness() {
+            if (options.frozen === true)
+                return 'unknown';
+            const elapsed = now() - checkedAt;
+            if (started && elapsed < options.intervalMs)
+                return cached;
+            // The prescreen: sizes and modification times only, no file contents. It cannot
+            // prove the sources are unchanged, which is why a difference sends us to the real
+            // check rather than being reported directly (architecture 12.3).
+            const scanned = scan(options.config);
+            prescreens += 1;
+            checkedAt = now();
+            if (started && scanned === signature)
+                return cached;
+            signature = scanned;
+            deepChecks += 1;
+            started = true;
+            cached = (await readFreshness({ config: options.config })).sourceState;
+            return cached;
+        },
+    };
+    return state;
+}
+/**
+ * A cheap signature of the source tree: path, size and modification time.
+ *
+ * Deliberately not evidence of anything on its own. A file can change without its mtime
+ * moving, which is the reason content hashes decide freshness, and this only decides
+ * whether to go and compute them.
+ */
+function scan(config) {
+    try {
+        const discovered = discover({ config, allowLargeProject: true });
+        const parts = [];
+        for (const artifact of discovered.artifacts) {
+            try {
+                const stats = statSync(join(config.projectRoot, artifact.relativePath));
+                parts.push(`${artifact.relativePath}:${stats.size}:${stats.mtimeMs}`);
+            }
+            catch {
+                // A file that vanished between discovery and stat is a change by itself.
+                parts.push(`${artifact.relativePath}:gone`);
+            }
+        }
+        return parts.join('\n');
+    }
+    catch {
+        // A source tree that cannot be walked is not a reason to fail a read (#147). Returning
+        // a distinct value sends the caller to the real check, which degrades properly.
+        return `unscannable:${Math.random()}`;
+    }
+}
+//# sourceMappingURL=revalidate.js.map

package/dist/services/revalidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revalidate.js","sourceRoot":"","sources":["../../src/services/revalidate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqC5C,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,IAAI,MAAM,GAAgB,SAAS,CAAC;IACpC,IAAI,SAAS,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACzC,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,KAAK,GAAgB;QACzB,IAAI,UAAU;YACZ,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,SAAS;YACb,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;gBAAE,OAAO,SAAS,CAAC;YAE9C,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC;YAClC,IAAI,OAAO,IAAI,OAAO,GAAG,OAAO,CAAC,UAAU;gBAAE,OAAO,MAAM,CAAC;YAE3D,gFAAgF;YAChF,kFAAkF;YAClF,iEAAiE;YACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,UAAU,IAAI,CAAC,CAAC;YAChB,SAAS,GAAG,GAAG,EAAE,CAAC;YAElB,IAAI,OAAO,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YAEpD,SAAS,GAAG,OAAO,CAAC;YACpB,UAAU,IAAI,CAAC,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,GAAG,CAAC,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;YACvE,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,IAAI,CAAC,MAAoB;IAChC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;gBACxE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,YAAY,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,MAAM,CAAC;gBACP,yEAAyE;gBACzE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,YAAY,OAAO,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,uFAAuF;QACvF,gFAAgF;QAChF,OAAO,eAAe,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/services/search.d.ts

@@ -0,0 +1,25 @@
+import { type LoadedConfig, type SearchResult, type SourceState } from '@lorepack/core';
+/**
+ * `lorepack search` over the active build.
+ *
+ * The query itself lives in `LoreRuntime.search`, which MCP, REST and Studio also call.
+ * This file is the CLI's adapter to it: build the local ports, ask, render. Keeping a
+ * second search path here would mean two ranking implementations and two response shapes
+ * to hold in step, and the shape is a published contract.
+ */
+export interface SearchOptions {
+    readonly config: LoadedConfig;
+    readonly query: string;
+    readonly sourceState: SourceState;
+    readonly limit?: number;
+    readonly pathGlob?: string;
+    readonly type?: string;
+    /** One document, by artifact id or canonical path. */
+    readonly artifactId?: string;
+    readonly includeArchived?: boolean;
+    /** Returns the score components, so a reader can see why a page is ordered as it is. */
+    readonly debug?: boolean;
+}
+export declare function runSearch(options: SearchOptions): Promise<SearchResult>;
+export declare function renderSearch(result: SearchResult, query: string, verbose?: boolean): string;
+//# sourceMappingURL=search.d.ts.map

package/dist/services/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/services/search.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA2B7E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,MAAM,CA6CzF"}