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

package/dist/services/studio-mutations.d.ts

@@ -0,0 +1,32 @@
+import { type LoadedConfig } from '@lorepack/core';
+/**
+ * The four things Studio can change, and the boundary that keeps them local.
+ *
+ * **Model-facing MCP tools stay strictly read-only** (architecture 19.4). These are Studio
+ * endpoints: loopback-bound, origin-validated, and never registered on a remote deployment.
+ * That separation is the whole reason they live here in the CLI rather than in
+ * `@lorepack/runtime`, which also compiles for the Worker: a route that does not exist in
+ * that package cannot be exposed by it, however the Worker is configured.
+ *
+ * Every one of them goes through the same code path the CLI uses, so a build activated from
+ * a browser and a build activated from a terminal are the same operation with the same
+ * pre-flight and the same lock.
+ */
+export declare function createBuildsEndpoint(config: LoadedConfig): () => Promise<unknown>;
+/**
+ * Moves the active pointer, with the pre-flight that makes it safe.
+ *
+ * `assertActivatable` runs **before** the pointer moves, so a corrupt build fails with the
+ * previous one still serving rather than after it has been made live. Architecture 18.4:
+ * activation is a pointer change and never recompiles, which is also why this is quick enough
+ * to do from a browser without a progress indicator.
+ */
+export declare function createActivateEndpoint(config: LoadedConfig): (request: unknown) => Promise<unknown>;
+/**
+ * The previous verified build, chosen the same way `lorepack rollback` chooses it.
+ *
+ * Rollback is a pointer change that never recompiles, which is what makes it cheap and safe,
+ * and is why Studio does not style it as destructive.
+ */
+export declare function createRollbackEndpoint(config: LoadedConfig): (request: unknown) => Promise<unknown>;
+//# sourceMappingURL=studio-mutations.d.ts.map

package/dist/services/studio-mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-mutations.d.ts","sourceRoot":"","sources":["../../src/services/studio-mutations.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,KAAK,YAAY,EAAa,MAAM,gBAAgB,CAAC;AAS5F;;;;;;;;;;;;GAYG;AAEH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAsBjF;AAqBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,GACnB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAgCxC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,GACnB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CA2CxC"}

package/dist/services/studio-mutations.js

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ProjectLock } from '@lorepack/backend-local';
+import { LORE_DIRECTORY, LoreError } from '@lorepack/core';
+import { assertActivatable, buildDirectory, openStateStore, previousBuild, resolveBuildId, } from './builds.js';
+/**
+ * The four things Studio can change, and the boundary that keeps them local.
+ *
+ * **Model-facing MCP tools stay strictly read-only** (architecture 19.4). These are Studio
+ * endpoints: loopback-bound, origin-validated, and never registered on a remote deployment.
+ * That separation is the whole reason they live here in the CLI rather than in
+ * `@lorepack/runtime`, which also compiles for the Worker: a route that does not exist in
+ * that package cannot be exposed by it, however the Worker is configured.
+ *
+ * Every one of them goes through the same code path the CLI uses, so a build activated from
+ * a browser and a build activated from a terminal are the same operation with the same
+ * pre-flight and the same lock.
+ */
+export function createBuildsEndpoint(config) {
+    const loreDirectory = join(config.projectRoot, LORE_DIRECTORY);
+    return async () => {
+        const state = openStateStore(loreDirectory);
+        try {
+            const active = state.current();
+            return {
+                activeBuildId: active?.buildId ?? null,
+                builds: state.listBuilds().map((build) => ({
+                    buildId: build.buildId,
+                    createdAt: build.createdAt,
+                    state: build.state,
+                    active: build.buildId === active?.buildId,
+                    counts: build.counts,
+                    capabilities: capabilitiesOf(loreDirectory, build.buildId),
+                })),
+            };
+        }
+        finally {
+            state.close();
+        }
+    };
+}
+/**
+ * A build's capabilities, read from its manifest.
+ *
+ * The manifest is a small JSON file, so this stays a file read per build rather than opening
+ * a database per row. `null` rather than an empty list when it cannot be read: a build whose
+ * manifest is missing has unknown capabilities, and an empty list would state that it has
+ * none, which is a different and false claim.
+ */
+function capabilitiesOf(loreDirectory, buildId) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(buildDirectory(loreDirectory, buildId), 'manifest.json'), 'utf8'));
+        return Array.isArray(manifest.capabilities) ? manifest.capabilities : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Moves the active pointer, with the pre-flight that makes it safe.
+ *
+ * `assertActivatable` runs **before** the pointer moves, so a corrupt build fails with the
+ * previous one still serving rather than after it has been made live. Architecture 18.4:
+ * activation is a pointer change and never recompiles, which is also why this is quick enough
+ * to do from a browser without a progress indicator.
+ */
+export function createActivateEndpoint(config) {
+    return async (request) => {
+        const reference = readBuildReference(request);
+        const loreDirectory = join(config.projectRoot, LORE_DIRECTORY);
+        const lock = new ProjectLock(join(loreDirectory, 'lock'));
+        const state = openStateStore(loreDirectory);
+        try {
+            const builds = state.listBuilds();
+            const target = resolveBuildId(builds, reference);
+            const summary = builds.find((build) => build.buildId === target);
+            if (summary === undefined) {
+                throw new LoreError('LORE_E_BUILD_NOT_FOUND', `No build ${reference}.`, {
+                    remediation: 'Choose a build from the history on this page.',
+                    subject: reference,
+                });
+            }
+            assertActivatable(loreDirectory, summary);
+            const active = state.current();
+            if (active?.buildId === target) {
+                return { buildId: target, generation: active.generation, changed: false };
+            }
+            // Held only across the pointer change itself, which is one transaction.
+            const generation = await lock.withLock(() => state.activate(target));
+            return { buildId: target, generation, changed: true };
+        }
+        finally {
+            state.close();
+        }
+    };
+}
+/**
+ * The previous verified build, chosen the same way `lorepack rollback` chooses it.
+ *
+ * Rollback is a pointer change that never recompiles, which is what makes it cheap and safe,
+ * and is why Studio does not style it as destructive.
+ */
+export function createRollbackEndpoint(config) {
+    return async (request) => {
+        const loreDirectory = join(config.projectRoot, LORE_DIRECTORY);
+        const lock = new ProjectLock(join(loreDirectory, 'lock'));
+        const state = openStateStore(loreDirectory);
+        try {
+            const builds = state.listBuilds();
+            const active = state.current();
+            const target = previousBuild(builds, active?.buildId ?? null);
+            // Studio names the build it is about to return to, and the history can move between
+            // rendering that name and confirming it: a rebuild finishing in the next terminal is
+            // enough. Rather than silently acting on a different build than the one confirmed, the
+            // stale confirmation is refused and the reader gets to look again.
+            const expected = request?.expect;
+            if (typeof expected === 'string' && expected !== target) {
+                // An argument that no longer holds, rather than a broken build: the caller can fix
+                // this by looking again, which is what separates a 400 from a 500.
+                throw new LoreError('LORE_E_INVALID_ARGUMENT', 'The build history changed while this confirmation was open.', {
+                    remediation: `Rolling back now would return to ${target}, not ${expected}. Check the history and confirm again.`,
+                    subject: expected,
+                });
+            }
+            const summary = builds.find((build) => build.buildId === target);
+            if (summary === undefined) {
+                throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'There is no earlier build to return to.', {
+                    remediation: 'Build again, and this project will have a version to roll back to.',
+                });
+            }
+            assertActivatable(loreDirectory, summary);
+            const generation = await lock.withLock(() => state.activate(target));
+            return { buildId: target, generation, changed: true };
+        }
+        finally {
+            state.close();
+        }
+    };
+}
+function readBuildReference(request) {
+    const build = request?.build;
+    if (typeof build !== 'string' || build.trim() === '') {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', 'No build was named.', {
+            remediation: 'Send a build id or a unique prefix of one.',
+        });
+    }
+    return build;
+}
+//# sourceMappingURL=studio-mutations.js.map

package/dist/services/studio-mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-mutations.js","sourceRoot":"","sources":["../../src/services/studio-mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAgB,cAAc,EAAqB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,oBAAoB,CAAC,MAAoB;IACvD,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAE/D,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,KAAK,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/B,OAAO;gBACL,aAAa,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI;gBACtC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACzC,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,MAAM,EAAE,OAAO;oBACzC,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,YAAY,EAAE,cAAc,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC;iBAC3D,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,aAAqB,EAAE,OAAgB;IAC7D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CACtD,CAAC;QAChC,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAE,QAAQ,CAAC,YAAyB,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAoB;IAEpB,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACjD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;YACjE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,SAAS,CAAC,wBAAwB,EAAE,YAAY,SAAS,GAAG,EAAE;oBACtE,WAAW,EAAE,+CAA+C;oBAC5D,OAAO,EAAE,SAAS;iBACnB,CAAC,CAAC;YACL,CAAC;YAED,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YAE1C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,MAAM,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC;gBAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC5E,CAAC;YAED,wEAAwE;YACxE,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACrE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxD,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAoB;IAEpB,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC;YAE9D,oFAAoF;YACpF,qFAAqF;YACrF,uFAAuF;YACvF,mEAAmE;YACnE,MAAM,QAAQ,GAAI,OAAuC,EAAE,MAAM,CAAC;YAClE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACxD,mFAAmF;gBACnF,mEAAmE;gBACnE,MAAM,IAAI,SAAS,CACjB,yBAAyB,EACzB,6DAA6D,EAC7D;oBACE,WAAW,EAAE,oCAAoC,MAAM,SAAS,QAAQ,wCAAwC;oBAChH,OAAO,EAAE,QAAQ;iBAClB,CACF,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;YACjE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,SAAS,CAAC,wBAAwB,EAAE,yCAAyC,EAAE;oBACvF,WAAW,EAAE,oEAAoE;iBAClF,CAAC,CAAC;YACL,CAAC;YACD,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YAE1C,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACrE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxD,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,MAAM,KAAK,GAAI,OAAsC,EAAE,KAAK,CAAC;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CAAC,yBAAyB,EAAE,qBAAqB,EAAE;YACpE,WAAW,EAAE,4CAA4C;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/services/versions.d.ts

@@ -0,0 +1,38 @@
+import { SCHEMA_VERSION } from '@lorepack/core';
+/**
+ * Versions that affect build output, in one place.
+ *
+ * The lockfile, the manifest and the build id all read from here, so they cannot disagree
+ * about which compiler or parser produced a build.
+ */
+export declare const COMPILER_VERSION: '0.1.0';
+/**
+ * Re-exported, not declared. It lives in core because the storage backend has to check a
+ * build's schema before reading it, and `backend-local` may not import the CLI.
+ */
+export { SCHEMA_VERSION };
+/**
+ * Every registered parser and its version, derived rather than listed.
+ *
+ * This was a hand-written literal naming markdown and text until #234, which is how the five
+ * parsers Phase 5 added came to be absent from the build id entirely. Bumping the XLSX
+ * parser's version and rebuilding a project full of spreadsheets produced a byte-identical
+ * build id, so a parser fix could not invalidate the artifacts it changed, and `lorepack diff`
+ * saw no difference between two builds whose content differed. Deriving from `PARSERS` makes
+ * registering a parser and recording its version one act instead of two.
+ *
+ * **Every registered parser, not only the ones a project happened to use.** The alternative
+ * is tempting, because it means adding a parser to Lorepack cannot disturb the id of a
+ * project containing no files of that type. It is rejected for two reasons. The lockfile is
+ * written during planning, before anything is parsed, so the contributing set is not known at
+ * the point this is needed. And the stability it buys is imaginary: `compilerVersion` is
+ * already a build id input, and a release that adds a parser bumps it, so every id moves
+ * regardless.
+ */
+export declare function parserVersions(): Record<string, string>;
+export declare function lockInputs(): {
+    compilerVersion: string;
+    schemaVersion: number;
+    parserVersions: Record<string, string>;
+};
+//# sourceMappingURL=versions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/services/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAG,OAAgB,CAAC;AAEjD;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIvD;AAED,wBAAgB,UAAU,IAAI;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC,CAMA"}

package/dist/services/versions.js

@@ -0,0 +1,46 @@
+import { SCHEMA_VERSION } from '@lorepack/core';
+import { PARSERS } from '@lorepack/parsers';
+/**
+ * Versions that affect build output, in one place.
+ *
+ * The lockfile, the manifest and the build id all read from here, so they cannot disagree
+ * about which compiler or parser produced a build.
+ */
+export const COMPILER_VERSION = '0.1.0';
+/**
+ * Re-exported, not declared. It lives in core because the storage backend has to check a
+ * build's schema before reading it, and `backend-local` may not import the CLI.
+ */
+export { SCHEMA_VERSION };
+/**
+ * Every registered parser and its version, derived rather than listed.
+ *
+ * This was a hand-written literal naming markdown and text until #234, which is how the five
+ * parsers Phase 5 added came to be absent from the build id entirely. Bumping the XLSX
+ * parser's version and rebuilding a project full of spreadsheets produced a byte-identical
+ * build id, so a parser fix could not invalidate the artifacts it changed, and `lorepack diff`
+ * saw no difference between two builds whose content differed. Deriving from `PARSERS` makes
+ * registering a parser and recording its version one act instead of two.
+ *
+ * **Every registered parser, not only the ones a project happened to use.** The alternative
+ * is tempting, because it means adding a parser to Lorepack cannot disturb the id of a
+ * project containing no files of that type. It is rejected for two reasons. The lockfile is
+ * written during planning, before anything is parsed, so the contributing set is not known at
+ * the point this is needed. And the stability it buys is imaginary: `compilerVersion` is
+ * already a build id input, and a release that adds a parser bumps it, so every id moves
+ * regardless.
+ */
+export function parserVersions() {
+    const versions = {};
+    for (const parser of PARSERS)
+        versions[parser.id] = parser.version;
+    return versions;
+}
+export function lockInputs() {
+    return {
+        compilerVersion: COMPILER_VERSION,
+        schemaVersion: SCHEMA_VERSION,
+        parserVersions: parserVersions(),
+    };
+}
+//# sourceMappingURL=versions.js.map

package/dist/services/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/services/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAgB,CAAC;AAEjD;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;IACnE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,UAAU;IAKxB,OAAO;QACL,eAAe,EAAE,gBAAgB;QACjC,aAAa,EAAE,cAAc;QAC7B,cAAc,EAAE,cAAc,EAAE;KACjC,CAAC;AACJ,CAAC"}

package/dist/services/watch.d.ts

@@ -0,0 +1,103 @@
+import { type LoadedConfig, type SourceState } from '@lorepack/core';
+/**
+ * Watching the sources, where the watcher is an accelerator and never the truth.
+ *
+ * Architecture 24.5 is blunt about this and 12.11 encodes it as an algorithm: filesystem
+ * events are a hint that something *may* have changed, and content hashes decide whether
+ * anything did. Every step below exists because some real editor or filesystem breaks the
+ * naive version:
+ *
+ * 1. the initial scan is the build the supervisor already ran;
+ * 2. start the watcher;
+ * 3. **reconcile after `ready`**, because a file written between the scan and the watcher
+ *    becoming ready belongs to neither and would be missed forever;
+ * 4. coalesce events over a debounce window, since one save is many events;
+ * 5. wait for size and modification time to stop moving, because editors write in chunks
+ *    and a hash taken mid-write is a hash of half a file;
+ * 6. fingerprint the content;
+ * 7. do nothing when the content is unchanged, which is what a touch or an atomic rename
+ *    of identical bytes produces;
+ * 8. build a candidate;
+ * 9. activate only after validation, which `runBuild` already guarantees.
+ *
+ * The watcher also answers `freshness()` for the server, which is the hook #112 named: a
+ * supervisor that is already watching knows whether the sources moved, so the server it
+ * supervises should stop paying for an interval scan to find out.
+ */
+export interface WatchOptions {
+    readonly config: LoadedConfig;
+    /**
+     * Builds and activates. Given a signal that aborts when a newer change arrives, so a
+     * superseded candidate is cancelled rather than finished and thrown away.
+     */
+    readonly rebuild: (signal: AbortSignal) => Promise<{
+        readonly created: boolean;
+    }>;
+    readonly warn: (text: string) => void;
+    /** How long to coalesce events before acting. */
+    readonly debounceMs?: number;
+    /** How long size and mtime must hold still before the content is trusted. */
+    readonly stabilityMs?: number;
+    /** Polling interval for the stability wait. */
+    readonly pollMs?: number;
+    /**
+     * How often to reconcile from disk regardless of what the event stream said.
+     *
+     * Architecture 12.3 and #54's design notes: a periodic full reconciliation catches missed
+     * events without polling constantly. It is cheap because it prescreens on sizes and
+     * modification times and only hashes when that moved.
+     *
+     * This is not belt and braces. Windows delivered no usable event for an ordinary append
+     * in CI, and a watcher whose correctness depends on the event stream would simply have
+     * gone on serving the old build. The stream is an accelerator; this is the floor.
+     */
+    readonly reconcileIntervalMs?: number;
+}
+export interface Watching {
+    /**
+     * Freshness from watcher state, costing no filesystem work.
+     *
+     * This is the whole point of handing it to the server. The polling revalidator exists
+     * because `lorepack serve` has no better information; a supervisor that is watching does.
+     */
+    freshness(): Promise<SourceState>;
+    close(): Promise<void>;
+    /** Resolves once the watcher is ready and the reconciliation scan has finished. */
+    readonly ready: Promise<void>;
+    /** Rebuilds actually performed, for the tests that assert one save is one rebuild. */
+    readonly rebuilds: number;
+    /** Times a change turned out to be no change, which is a visible outcome, not a silence. */
+    readonly noOps: number;
+    /**
+     * What the watcher is doing right now, for Studio's Diagnostics route.
+     *
+     * Useful precisely when something feels stuck: "the watcher saw your edit four seconds ago
+     * and the last rebuild took 90 ms" and "the watcher has seen nothing since you started"
+     * are different problems, and without this they look identical from the browser.
+     */
+    status(): WatchStatus;
+}
+export interface WatchStatus {
+    readonly state: SourceState;
+    /** Files currently watched, as chokidar counts them. */
+    readonly watchedPaths: number;
+    readonly lastEventAt: string | null;
+    readonly lastRebuild: {
+        readonly at: string;
+        readonly durationMs: number;
+        /** False when the rebuild found nothing to change, which is a result, not a failure. */
+        readonly created: boolean;
+        readonly failed: boolean;
+    } | null;
+    readonly rebuilds: number;
+    readonly noOps: number;
+}
+export declare const WATCH_DEFAULTS: {
+    readonly debounceMs: 150;
+    readonly stabilityMs: 120;
+    readonly pollMs: 40;
+    readonly reconcileIntervalMs: 2000;
+};
+export declare function startWatching(options: WatchOptions): Watching;
+export declare function resolveRealPath(path: string): string;
+//# sourceMappingURL=watch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/services/watch.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAKnG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,MAAM,IAAI,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,wFAAwF;QACxF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,GAAG,IAAI,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,cAAc;aACzB,UAAU,EAAE,GAAG;aACf,WAAW,EAAE,GAAG;aAChB,MAAM,EAAE,EAAE;aACV,mBAAmB,EAAE,IAAI;CACjB,CAAC;AAEX,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAkT7D;AAgHD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMpD"}