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

package/dist/services/search.js

@@ -0,0 +1,88 @@
+import { createLocalRuntimeBackend } from '@lorepack/backend-local';
+import { count, LoreError, } from '@lorepack/core';
+import { createRuntime } from '@lorepack/runtime';
+export async function runSearch(options) {
+    const backend = createLocalRuntimeBackend({
+        projectRoot: options.config.projectRoot,
+        // The CLI has already established freshness for its own header, so the runtime is
+        // handed the answer rather than made to work it out again.
+        freshness: async () => options.sourceState,
+    });
+    try {
+        if ((await backend.provider.current()) === null) {
+            throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'This project has no active build to search.', {
+                remediation: 'Run `lorepack build` first.',
+            });
+        }
+        return await createRuntime(backend).search({
+            query: options.query,
+            limit: options.limit ?? 10,
+            includeArchived: options.includeArchived ?? false,
+            debug: options.debug ?? false,
+            ...(options.pathGlob === undefined ? {} : { pathGlob: options.pathGlob }),
+            ...(options.type === undefined ? {} : { fileType: options.type }),
+            ...(options.artifactId === undefined ? {} : { artifactId: options.artifactId }),
+        });
+    }
+    finally {
+        backend.close();
+    }
+}
+export function renderSearch(result, query, verbose = false) {
+    const lines = [
+        `Build ${result.buildId.slice(0, 17)} (sources ${result.sourceState}), ${count(result.totalIndexedChunks, 'chunk')} indexed`,
+        '',
+    ];
+    if (result.hits.length === 0) {
+        lines.push(`No matches for "${query}".`);
+        lines.push('');
+        lines.push(result.totalIndexedChunks === 0
+            ? 'This build indexed nothing. Run `lorepack inspect warnings` to see what was skipped.'
+            : `Searched ${count(result.totalIndexedChunks, 'chunk')}. Try fewer or more general terms.`);
+        return lines.join('\n');
+    }
+    let rank = 0;
+    for (const hit of result.hits) {
+        rank += 1;
+        const where = hit.locator.lineStart === undefined
+            ? hit.locator.relativePath
+            : `${hit.locator.relativePath}:${hit.locator.lineStart}`;
+        // The rank is the claim, and the score is shown only when asked for. It is a
+        // relevance heuristic: how well the words match, not how likely the content is to be
+        // right. Printing it beside every result would invite reading it as confidence.
+        lines.push(`${String(rank).padStart(2)}. ${where}${verbose ? `  (relevance ${hit.score.toFixed(2)})` : ''}`);
+        if (hit.headingPath.length > 0)
+            lines.push(`    ${hit.headingPath.join(' > ')}`);
+        if (hit.labels.length > 0)
+            lines.push(`    [${hit.labels.join(', ')}]`);
+        lines.push(`    ${hit.excerpt.replace(/\s+/g, ' ').trim()}`);
+        if (hit.scoreComponents !== undefined) {
+            lines.push(`    why: ${renderComponents(hit.scoreComponents)}`);
+        }
+        lines.push('');
+    }
+    if (result.hits.some((hit) => hit.scoreComponents !== undefined)) {
+        lines.push('Relevance is a heuristic about matching words. It is not a confidence, and');
+        lines.push('it is not evidence that a document is correct.');
+    }
+    return lines.join('\n').trimEnd();
+}
+/** The components in the order they are applied, so the line reads like the calculation. */
+function renderComponents(components) {
+    const order = [
+        'lexical',
+        'pathExact',
+        'titleExact',
+        'headingExact',
+        'allTerms',
+        'statusFactor',
+        'authorityFactor',
+        'supersededFactor',
+        'total',
+    ];
+    return order
+        .filter((name) => components[name] !== undefined)
+        .map((name) => `${name} ${components[name].toFixed(2)}`)
+        .join(', ');
+}
+//# sourceMappingURL=search.js.map

package/dist/services/search.js.map

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

package/dist/services/serving.d.ts

@@ -0,0 +1,70 @@
+import { createLocalRuntimeBackend } from '@lorepack/backend-local';
+import { type BuildId, type LoadedConfig } from '@lorepack/core';
+/** Exported for the tests, which assert the wording rather than reproducing it. */
+export declare const SERVE_DEFAULTS: {
+    readonly port: 4321;
+    readonly attempts: 20;
+};
+export interface ServingOptions {
+    readonly config: LoadedConfig;
+    readonly host: string;
+    readonly port: number;
+    readonly warn: (text: string) => void;
+    /**
+     * How the server decides whether the sources have moved on.
+     *
+     * Omitted, it polls with a metadata prescreen on `revalidateIntervalMs`. `lorepack dev` passes
+     * its watcher's answer instead, which is the hook #112 named and the Phase 3 audit expects
+     * #53 and #55 to use.
+     */
+    readonly freshness?: () => Promise<import('@lorepack/core').SourceState>;
+    readonly revalidateIntervalMs?: number;
+    /**
+     * Serve Studio at the root.
+     *
+     * `lorepack dev` does; `lorepack serve` does not, because Studio can activate and roll back and
+     * `lorepack serve` promises to be read-only and never to rebuild. Two commands with different
+     * promises should not quietly offer the same surface.
+     */
+    readonly studio?: boolean;
+    /**
+     * The watcher's live state, when there is a watcher.
+     *
+     * Supplied by `lorepack dev` for Studio's Diagnostics route. `lorepack serve` has no watcher and
+     * supplies nothing, and the route says so rather than inventing a state for it.
+     */
+    readonly watchStatus?: () => import('./watch.js').WatchStatus;
+}
+export interface RunningServer {
+    readonly url: string;
+    readonly port: number;
+    readonly buildId: BuildId;
+    /** Whether Studio's assets were found and mounted, so the caller knows what to print. */
+    readonly studio: boolean;
+    /** Drains in-flight requests, then releases the databases. Idempotent. */
+    readonly close: () => Promise<void>;
+}
+export interface ServingDependencies {
+    readonly createBackend?: typeof createLocalRuntimeBackend;
+    readonly listen?: typeof listen;
+}
+export declare function startServing(options: ServingOptions, dependencies?: ServingDependencies): Promise<RunningServer>;
+interface Listening {
+    readonly port: number;
+    readonly close: () => Promise<void>;
+}
+/**
+ * Binds, stepping to the next port when one is taken.
+ *
+ * Architecture 6.9 asks for exactly this: an occupied port is an ordinary condition of a
+ * developer machine, not a failure, so the server moves and says where it went.
+ */
+declare function listen(fetch: (request: Request) => Response | Promise<Response>, hostname: string, first: number, warn: (text: string) => void): Promise<Listening>;
+/** Resolves on the first interrupt, so a caller can drain in its own order. */
+export declare function untilInterrupted(warn: (text: string) => void): Promise<void>;
+export declare function isLoopback(host: string): boolean;
+/** Milliseconds, or 0 for every request. `off` belongs to `lorepack mcp`, which can pin. */
+export declare function parseInterval(raw: unknown): number;
+export declare function parsePort(raw: unknown): number;
+export {};
+//# sourceMappingURL=serving.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serving.d.ts","sourceRoot":"","sources":["../../src/services/serving.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,gBAAgB,CAAC;AAkC5E,mFAAmF;AACnF,eAAO,MAAM,cAAc;aAAK,IAAI;aAAgB,QAAQ;CAA0B,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,gBAAgB,EAAE,WAAW,CAAC,CAAC;IACzE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,YAAY,EAAE,WAAW,CAAC;CAC/D;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,yBAAyB,CAAC;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAC;CACjC;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,YAAY,GAAE,mBAAwB,GACrC,OAAO,CAAC,aAAa,CAAC,CAuJxB;AAED,UAAU,SAAS;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,iBAAe,MAAM,CACnB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EACzD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3B,OAAO,CAAC,SAAS,CAAC,CA2BpB;AAED,+EAA+E;AAC/E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CASlF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAS9C"}

package/dist/services/serving.js

@@ -0,0 +1,240 @@
+import { serve } from '@hono/node-server';
+import { createLocalRuntimeBackend } from '@lorepack/backend-local';
+import { LoreError } from '@lorepack/core';
+import { createMcpHttpHandler } from '@lorepack/mcp';
+import { createApiApp, createRuntime } from '@lorepack/runtime';
+import { createLocalComparer } from './comparer.js';
+import { renderBundleMarkdown } from './export.js';
+import { packBuild } from './packing.js';
+import { createRevalidator, DEFAULT_REVALIDATE_INTERVAL_MS } from './revalidate.js';
+import { createStudioAssets, studioIsBuilt } from './studio-assets.js';
+import { createDiagnosticsEndpoint } from './studio-diagnostics.js';
+import { createPlanEndpoint, createWarningsEndpoint } from './studio-endpoints.js';
+import { createActivateEndpoint, createBuildsEndpoint, createRollbackEndpoint, } from './studio-mutations.js';
+/**
+ * Serving an active build over HTTP and MCP, in one place, for the two commands that do it.
+ *
+ * `lorepack serve` and `lorepack dev` differ in what they are willing to do to a project: one never
+ * builds, the other builds and watches. They do not differ in how a build is served, and the
+ * Phase 3 audit on #4 is explicit that `lorepack dev` should supervise the existing server rather
+ * than grow a second one. Two servers would mean two port policies, two binding warnings and
+ * two ways to drain, and the difference between them would be discovered by a user.
+ *
+ * The freshness revalidator is injectable for the same reason. `lorepack serve` has no better
+ * information than an interval and a metadata prescreen, but a supervisor that is already
+ * watching the filesystem does, and supplying it is an injection rather than a rewrite.
+ */
+const DEFAULT_PORT = 4321;
+/** How many ports to try before giving up. Enough for several servers, few enough to fail. */
+const PORT_ATTEMPTS = 20;
+/** Exported for the tests, which assert the wording rather than reproducing it. */
+export const SERVE_DEFAULTS = { port: DEFAULT_PORT, attempts: PORT_ATTEMPTS };
+export async function startServing(options, dependencies = {}) {
+    const revalidator = createRevalidator({
+        config: options.config,
+        intervalMs: options.revalidateIntervalMs ?? DEFAULT_REVALIDATE_INTERVAL_MS,
+    });
+    const freshness = options.freshness ?? (() => revalidator.freshness());
+    const backend = (dependencies.createBackend ?? createLocalRuntimeBackend)({
+        projectRoot: options.config.projectRoot,
+        // Freshness is an annotation and never fails a read: a server that refused to answer
+        // because the source tree moved would be useless (#147).
+        freshness,
+    });
+    try {
+        const active = await backend.provider.current();
+        if (active === null) {
+            throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'This project has no build to serve.', {
+                remediation: 'Run `lorepack build` first.',
+            });
+        }
+        const runtime = createRuntime(backend);
+        // One handler for the process, built once: it constructs a fresh server per request
+        // internally, which is what the stateless model asks for, and holds the machinery that
+        // would otherwise be rebuilt on every call.
+        const startedAt = new Date().toISOString();
+        // Filled in by `listen` below, which is where the port stops being a request and becomes
+        // a fact. Diagnostics reads it through a closure rather than being constructed twice.
+        let boundPort = options.port;
+        const comparer = createLocalComparer(options.config.projectRoot);
+        const mcp = createMcpHttpHandler(runtime, comparer);
+        // Absent when the package was installed without built assets, which is a broken install
+        // rather than a mode: saying nothing about Studio is better than printing a URL that 404s.
+        const serveStudio = options.studio === true && studioIsBuilt();
+        const app = createApiApp({
+            runtime,
+            currentBuild: () => backend.provider.current(),
+            freshness,
+            mcpHandler: (request) => mcp.fetch(request),
+            // Reads of the **active build**, so any server can answer them: they change nothing and
+            // they touch no source file. `lorepack serve` offering them is the same promise it already
+            // makes about `/v1/search`.
+            exportBundle: async (request) => {
+                const bundle = await runtime.contextForTask(request);
+                // The same renderer `lorepack export` uses, so "copy as export" is byte-identical rather
+                // than merely similar. A parity test asserts it.
+                return renderBundleMarkdown(bundle, {
+                    projectName: options.config.config.name,
+                    moreCommand: `lorepack export --task ${JSON.stringify(bundle.task)} --profile deep`,
+                    sourceState: bundle.sourceState,
+                });
+            },
+            sources: async () => {
+                const handle = await backend.provider.acquire();
+                try {
+                    const scope = await backend.open(handle);
+                    return { buildId: handle.buildId, artifacts: await scope.catalog.artifacts() };
+                }
+                finally {
+                    handle.release();
+                }
+            },
+            warnings: createWarningsEndpoint(async () => {
+                // Acquired and released like any other read, so a warnings request cannot pin a build
+                // open after it stops being active.
+                const handle = await backend.provider.acquire();
+                try {
+                    const scope = await backend.open(handle);
+                    const manifest = await scope.catalog.manifest();
+                    return {
+                        buildId: manifest.buildId,
+                        warnings: manifest.warnings,
+                        ...(manifest.exclusions === undefined ? {} : { exclusions: manifest.exclusions }),
+                    };
+                }
+                finally {
+                    handle.release();
+                }
+            }),
+            ...(serveStudio
+                ? {
+                    assets: createStudioAssets(),
+                    allowLoopbackOrigin: true,
+                    // The one Studio read that is **not** a read of the build: planning walks the
+                    // source tree. `lorepack serve` promises never to rebuild and has no business reading
+                    // sources, so this belongs to `lorepack dev` alone.
+                    plan: createPlanEndpoint(options.config),
+                    // Reads the machine rather than the build: SQLite controls, the watcher, the
+                    // process serving this request. The port is passed as a function because it is
+                    // chosen by binding, which has not happened yet at this line.
+                    diagnostics: createDiagnosticsEndpoint({
+                        config: options.config,
+                        host: options.host,
+                        port: () => boundPort,
+                        startedAt,
+                        ...(options.watchStatus === undefined ? {} : { watchStatus: options.watchStatus }),
+                    }),
+                    // The only writes in this API, and they exist only here. `lorepack serve` promises to
+                    // be read-only, so it passes no actions and simply does not have these routes.
+                    localActions: {
+                        builds: createBuildsEndpoint(options.config),
+                        diff: (from, to) => comparer.compare(from, to),
+                        activate: createActivateEndpoint(options.config),
+                        rollback: createRollbackEndpoint(options.config),
+                        pack: async (request) => {
+                            const asked = request;
+                            return packBuild(options.config, { build: asked.build, out: asked.out });
+                        },
+                    },
+                }
+                : {}),
+        });
+        if (!isLoopback(options.host)) {
+            // Architecture 15.3: binding beyond loopback is possible and never accidental.
+            options.warn(`Warning: binding to ${options.host} exposes this build to your network. It is read-only, and it is still your documents.\n`);
+        }
+        const server = await (dependencies.listen ?? listen)(app.fetch, options.host, options.port, options.warn);
+        boundPort = server.port;
+        let closed = false;
+        return {
+            url: `http://${options.host}:${server.port}`,
+            port: server.port,
+            buildId: active.buildId,
+            studio: serveStudio,
+            close: async () => {
+                if (closed)
+                    return;
+                closed = true;
+                // Order matters: `close()` stops new connections and waits for in-flight requests,
+                // and only then are the databases released. Releasing first would let a request in
+                // flight read a closed handle.
+                await server.close();
+                await mcp.close();
+                backend.close();
+            },
+        };
+    }
+    catch (error) {
+        backend.close();
+        throw error;
+    }
+}
+/**
+ * Binds, stepping to the next port when one is taken.
+ *
+ * Architecture 6.9 asks for exactly this: an occupied port is an ordinary condition of a
+ * developer machine, not a failure, so the server moves and says where it went.
+ */
+async function listen(fetch, hostname, first, warn) {
+    for (let attempt = 0; attempt < PORT_ATTEMPTS; attempt += 1) {
+        const port = first + attempt;
+        try {
+            const server = await new Promise((resolve, reject) => {
+                const started = serve({ fetch, hostname, port }, () => resolve(started));
+                started.on('error', reject);
+            });
+            if (attempt > 0)
+                warn(`Port ${first} was busy, using ${port}.\n`);
+            return {
+                port,
+                close: () => new Promise((resolve) => {
+                    server.close(() => resolve());
+                }),
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new LoreError('LORE_E_INVALID_ARGUMENT', `No free port between ${first} and ${first + PORT_ATTEMPTS - 1}.`, { remediation: 'Pass a different --port, or stop whatever is using this range.' });
+}
+/** Resolves on the first interrupt, so a caller can drain in its own order. */
+export async function untilInterrupted(warn) {
+    await new Promise((resolve) => {
+        const stop = (signal) => {
+            warn(`\nStopping on ${signal}. Draining requests.\n`);
+            resolve();
+        };
+        process.once('SIGINT', () => stop('SIGINT'));
+        process.once('SIGTERM', () => stop('SIGTERM'));
+    });
+}
+export function isLoopback(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+/** Milliseconds, or 0 for every request. `off` belongs to `lorepack mcp`, which can pin. */
+export function parseInterval(raw) {
+    // `Number('')` is 0, and 0 is the most expensive setting there is: it content-hashes the
+    // corpus on every request. Reaching it by writing nothing, which is what a shell does
+    // with an unset variable, is not a choice anyone made (#195).
+    const blank = typeof raw === 'string' && raw.trim() === '';
+    const value = blank ? Number.NaN : Number(raw);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', `--revalidate-interval must be a number of milliseconds, got ${raw}.`, { remediation: 'Pass milliseconds, or 0 to recheck on every request.' });
+    }
+    return value;
+}
+export function parsePort(raw) {
+    if (raw === undefined)
+        return DEFAULT_PORT;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 65_535) {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', `--port must be a port number, got ${raw}.`, {
+            remediation: `Pass a number between 1 and 65535, for example --port ${DEFAULT_PORT}.`,
+        });
+    }
+    return value;
+}
+//# sourceMappingURL=serving.js.map

package/dist/services/serving.js.map

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

package/dist/services/status.d.ts

@@ -0,0 +1,54 @@
+import { type LoadedConfig, type ProgressBus, type SourceState, type Status } from '@lorepack/core';
+/**
+ * `lorepack status` answers one question: is the context my AI reads current?
+ *
+ * It never writes, not even a migration or a cache entry. Status is run constantly, often
+ * in a prompt, and a command that mutated a project as a side effect of being asked about
+ * it would be a trap.
+ */
+export interface StatusOptions {
+    readonly config: LoadedConfig;
+    readonly progress?: ProgressBus;
+    readonly allowLargeProject?: boolean;
+    readonly now?: () => Date;
+}
+export declare function readStatus(options: StatusOptions): Promise<Status>;
+export interface Freshness {
+    readonly sourceState: SourceState;
+    /** Why freshness could not be established, for the human rendering. Null when it was. */
+    readonly reason: string | null;
+}
+/**
+ * Freshness for a read-only command: an annotation on the answer, never a precondition
+ * for it.
+ *
+ * Section 4.10 says freshness travels with the result, and it is tempting to read that as
+ * "establish it or fail". That reading cost `lorepack search` its usefulness on any project
+ * above the file envelope: the build existed and was perfectly queryable, and the query was
+ * refused because a guard about the cost of *building* had been consulted first (#147). A
+ * read of a sealed build is not entitled to have an opinion about the source tree.
+ *
+ * So two things differ from `readStatus`:
+ *
+ * - **The envelope does not apply.** It bounds what Lorepack promises about build
+ *   performance, not what it will answer from a build it already made.
+ * - **Nothing here can fail the command.** A source tree that is enormous, unreadable or
+ *   gone leaves freshness `unknown`, which is precisely what the contract's third state
+ *   means, and the caller still gets the build's answer.
+ *
+ * Invariant 6 applies to the degraded case too: `unknown` says Lorepack does not know, and
+ * never that the sources are clean.
+ */
+export declare function readFreshness(options: StatusOptions): Promise<Freshness>;
+/**
+ * Which failures are allowed to become `unknown`, and which must still be raised.
+ *
+ * An allowlist rather than a bare `catch`. Swallowing everything would turn a corrupt
+ * state database into the cheerful and false statement "freshness unknown", which is the
+ * kind of helpfulness that hides a real defect for a phase or two. These three all mean
+ * "something about the source tree stopped us looking", and none of them says anything
+ * about whether the build being read is sound.
+ */
+export declare function degradedFreshness(error: unknown): Freshness | null;
+export declare function renderStatus(status: Status, verbose: boolean): string;
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/services/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AAGxB;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAiExE;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAY9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CASlE;AAsCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CA0CrE"}