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

package/dist/commands/deploy.js

@@ -0,0 +1,248 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createPlan, readLockfile, renderPlan } from '@lorepack/compiler';
+import { buildManifestSchema, LORE_DIRECTORY, LoreError, loadConfig, } from '@lorepack/core';
+import { runBuild } from '../services/build.js';
+import { buildDirectory as localBuildDirectory } from '../services/builds.js';
+import { resolveCloudflareTarget, resolveCloudflareTargetWithAdapter, } from '../services/cloudflare-target.js';
+import { readReceipt, receiptPath, runDeploy } from '../services/deploy.js';
+import { readActiveBuild, readPreviousBuild } from '../services/project.js';
+import { readStatus } from '../services/status.js';
+import { lockInputs } from '../services/versions.js';
+const TEST_ALLOW_HOOKS_ENV = 'LORE_TEST_ALLOW_HOOKS';
+const TEST_FAIL_AFTER_PROJECT_ENV = 'LORE_TEST_FAIL_DEPLOY_AFTER_PROJECT';
+export function deployCommand(options = {}) {
+    return {
+        name: 'deploy',
+        description: 'Project a build onto a remote target and activate it after verification.',
+        arguments: [{ name: 'target', description: 'which target to deploy to', required: false }],
+        flags: [
+            { flags: '--dry-run', description: 'show the deploy plan and change nothing remotely' },
+            { flags: '--no-build', description: 'refuse when sources are dirty or unbuilt' },
+            { flags: '--yes', description: 'apply without asking' },
+            { flags: '--resume <receipt-id>', description: 'continue an interrupted deploy' },
+            {
+                flags: '--allow-capability-loss <capability>',
+                description: 'accept one named capability the target cannot serve',
+            },
+        ],
+        handler: async (args, flags, context) => {
+            const config = loadConfig({ cwd: context.options.cwd });
+            const targetName = resolveTargetName(args[0]);
+            const target = options.resolveTarget === undefined
+                ? await resolveTarget(targetName, config.projectRoot, config.configPath, options.cloudflareAdapter)
+                : await options.resolveTarget(targetName, {
+                    projectRoot: config.projectRoot,
+                    configPath: config.configPath,
+                });
+            const resume = typeof flags.resume === 'string'
+                ? readReceipt(config.projectRoot, flags.resume)
+                : undefined;
+            if (resume !== undefined && resume.target !== target.id) {
+                throw new LoreError('LORE_E_INVALID_ARGUMENT', `Receipt ${resume.receiptId} belongs to ${resume.target}, not ${target.id}.`, {
+                    remediation: `Resume with \`lorepack deploy ${resume.target} --resume ${resume.receiptId}\`, or start a new deploy.`,
+                    subject: resume.receiptId,
+                });
+            }
+            const preparation = await prepareBuild({
+                configRoot: config.projectRoot,
+                config,
+                flags,
+                context,
+                ...(resume === undefined ? {} : { resume }),
+            });
+            const deployPlan = await target.plan({
+                projectName: config.config.name,
+                buildId: preparation.buildId,
+                buildDirectory: preparation.buildDirectory,
+                buildCapabilities: preparation.buildCapabilities,
+            });
+            const planLines = [...preparation.localPlanLines, renderDeployPlan(deployPlan)].filter((line) => line !== '');
+            const planText = planLines.join('\n\n');
+            if (flags.yes !== true && flags.dryRun !== true) {
+                const confirmed = await (options.confirm ?? confirmDeploy)(planText, context);
+                if (!confirmed)
+                    return { human: `${planText}\n\nCancelled. Nothing was changed.` };
+            }
+            const accepted = normalizeCapabilityLoss(flags.allowCapabilityLoss);
+            const afterProject = testAfterProjectHookFromEnv();
+            const result = await runDeploy({
+                target,
+                projectRoot: config.projectRoot,
+                projectName: config.config.name,
+                buildId: preparation.buildId,
+                buildDirectory: preparation.buildDirectory,
+                buildCapabilities: preparation.buildCapabilities,
+                plan: deployPlan,
+                progress: context.progress,
+                dryRun: flags.dryRun === true,
+                ...(afterProject === undefined ? {} : { afterProject }),
+                ...(resume === undefined ? {} : { resume }),
+                ...(accepted.length === 0 ? {} : { allowCapabilityLoss: accepted }),
+            }).catch((error) => {
+                const original = LoreError.from(error);
+                const receiptId = error instanceof LoreError && typeof error.details?.receiptId === 'string'
+                    ? error.details.receiptId
+                    : resume?.receiptId;
+                if (receiptId === undefined)
+                    throw error;
+                throw new LoreError('LORE_E_REMOTE_DEPLOY', original.message, {
+                    remediation: `${original.remediation ?? 'The previous remote build is still serving.'} Resume with \`lorepack deploy ${target.id} --resume ${receiptId}\`.`,
+                    ...(original.details === undefined ? {} : { details: original.details }),
+                    ...(original.subject === undefined ? {} : { subject: original.subject }),
+                    ...(original.cause === undefined ? {} : { cause: original.cause }),
+                });
+            });
+            return {
+                human: `${planText}\n\n${renderDeployResult(config.projectRoot, result.receipt, result.dryRun)}`,
+                json: result.receipt,
+            };
+        },
+    };
+}
+async function prepareBuild(options) {
+    if (options.resume !== undefined) {
+        return readBuildInputs(options.configRoot, options.resume.buildId);
+    }
+    const status = await readStatus({ config: options.config, progress: options.context.progress });
+    const noBuild = options.flags.build === false;
+    const needsBuild = status.sourceState === 'dirty' || status.sourceState === 'unbuilt';
+    if (needsBuild && noBuild) {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', 'The sources are not already built, and --no-build was given.', {
+            remediation: status.sourceState === 'unbuilt'
+                ? 'Run `lorepack build`, or omit `--no-build` so `lorepack deploy` can build first.'
+                : 'Run `lorepack build`, or omit `--no-build` so `lorepack deploy` can rebuild first.',
+        });
+    }
+    const localPlanLines = [];
+    if (needsBuild) {
+        const { state, previous } = readPreviousBuild(options.config);
+        try {
+            const local = await createPlan({
+                config: options.config,
+                previous,
+                previousLock: readLockfile(options.config.projectRoot),
+                lockInputs: lockInputs(),
+                progress: options.context.progress,
+            });
+            localPlanLines.push(renderPlan(local.plan));
+        }
+        finally {
+            state?.close();
+        }
+        const built = await runBuild({
+            config: options.config,
+            progress: options.context.progress,
+            activate: true,
+            ...(options.context.signal === undefined ? {} : { signal: options.context.signal }),
+        });
+        return {
+            ...readBuildInputs(options.configRoot, built.buildId),
+            localPlanLines,
+        };
+    }
+    const active = readActiveBuild(join(options.config.projectRoot, LORE_DIRECTORY));
+    if (active === null) {
+        throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'This project has no active build to deploy.', {
+            remediation: 'Run `lorepack build` first, or omit `--no-build` so `lorepack deploy` can build one.',
+        });
+    }
+    return {
+        ...readBuildInputs(options.configRoot, active.buildId),
+        localPlanLines,
+    };
+}
+function readBuildInputs(projectRoot, buildId) {
+    const loreDirectory = join(projectRoot, LORE_DIRECTORY);
+    const buildDirectory = localBuildDirectory(loreDirectory, buildId);
+    const manifestPath = join(buildDirectory, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new LoreError('LORE_E_BUILD_NOT_FOUND', `Build ${buildId} has no manifest.`, {
+            remediation: 'Run `lorepack build` again to recreate it before deploying.',
+            subject: buildId,
+        });
+    }
+    const manifest = buildManifestSchema.parse(JSON.parse(readFileSync(manifestPath, 'utf8')));
+    return {
+        buildId,
+        buildDirectory,
+        buildCapabilities: manifest.capabilities,
+        localPlanLines: [],
+    };
+}
+function testAfterProjectHookFromEnv() {
+    if (process.env[TEST_ALLOW_HOOKS_ENV] !== '1')
+        return undefined;
+    if (process.env[TEST_FAIL_AFTER_PROJECT_ENV] !== '1')
+        return undefined;
+    return (receipt) => {
+        throw new LoreError('LORE_E_REMOTE_DEPLOY', 'Forced test failure after candidate projection.', {
+            remediation: 'This test hook stops the deploy after candidate projection. Resume with the recorded receipt id.',
+            details: { receiptId: receipt.receiptId },
+        });
+    };
+}
+function renderDeployPlan(plan) {
+    const lines = [
+        `Target: ${plan.display?.targetLabel ?? plan.target}`,
+        `Build:  ${plan.input.buildId}`,
+    ];
+    if (plan.display === undefined) {
+        lines.push(`Capabilities: ${plan.input.buildCapabilities.join(', ')}`);
+    }
+    lines.push('', 'Resources', ...prefixPlanLines(plan.display?.resourceLines ?? ['Resolved by the selected deployment target.']), '', 'Projection', ...prefixPlanLines(plan.display?.projectionLines ?? [
+        'Project the sealed build as a candidate and verify it before activation.',
+    ]), '', 'Activation', ...prefixPlanLines(plan.display?.activationLines ?? [
+        'Switch the active pointer only after candidate verification and smoke confirmation.',
+    ]));
+    return lines.join('\n');
+}
+function prefixPlanLines(lines) {
+    return lines.map((line) => `  ${line}`);
+}
+function renderDeployResult(projectRoot, receipt, dryRun) {
+    if (dryRun) {
+        return ['Dry run only. Nothing remote was changed.', `Receipt id: ${receipt.receiptId}`].join('\n');
+    }
+    return [
+        `Deployed ${receipt.buildId} to ${receipt.target}.`,
+        `Endpoint: ${receipt.endpoint ?? 'unknown'}`,
+        `Active build: ${receipt.buildId}`,
+        `Receipt: ${receiptPath(projectRoot, receipt.receiptId)}`,
+    ].join('\n');
+}
+function normalizeCapabilityLoss(raw) {
+    if (raw === undefined)
+        return [];
+    if (Array.isArray(raw))
+        return raw.map((value) => String(value));
+    return [String(raw)];
+}
+function resolveTargetName(raw) {
+    return raw === undefined || raw.trim() === '' ? 'cloudflare' : raw.trim();
+}
+async function resolveTarget(name, projectRoot, _configPath, cloudflareAdapter) {
+    if (name !== 'cloudflare') {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', `Unknown deploy target ${name}.`, {
+            remediation: 'Use `cloudflare`. Additional targets are not implemented in v0.1.',
+            subject: name,
+        });
+    }
+    return cloudflareAdapter === undefined
+        ? await resolveCloudflareTarget(projectRoot)
+        : await resolveCloudflareTargetWithAdapter(projectRoot, cloudflareAdapter);
+}
+async function confirmDeploy(plan, context) {
+    if (!context.streams.isTty) {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', 'Deploy confirmation requires a terminal when --yes is not given.', {
+            remediation: 'Re-run with `--yes` in CI or another non-interactive environment.',
+        });
+    }
+    context.write(`${plan}\n\nDeploy this build? [y/N] `);
+    const answer = await new Promise((resolve) => {
+        process.stdin.setEncoding('utf8');
+        process.stdin.once('data', (chunk) => resolve(String(chunk)));
+    });
+    return /^y(es)?\s*$/i.test(answer.trim());
+}
+//# sourceMappingURL=deploy.js.map

package/dist/commands/deploy.js.map

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

package/dist/commands/dev.d.ts

@@ -0,0 +1,25 @@
+import type { CommandDefinition } from '../framework/program.js';
+/**
+ * `lorepack dev [path]`: a folder becomes a running, connected context runtime, asking nothing.
+ *
+ * This is the headline command (architecture 2.2, 6.2), and its whole design is an ordering
+ * decision: **validate, then inspect, then mutate**. Section 6.2 lists the seven steps in
+ * that order for a reason. A run that discovers on step five that this Node build has no
+ * FTS5 has already written files into someone's directory to learn it.
+ *
+ * So the order below is load-bearing rather than incidental:
+ *
+ * 1. capability validation, which touches nothing;
+ * 2. inspection, which reads the directory and writes nothing;
+ * 3. atomic init, which writes and says exactly what it wrote;
+ * 4. build and activate;
+ * 5. serve;
+ * 6. print how to connect.
+ *
+ * It supervises rather than reimplements. Init comes from the same module `lorepack init` uses,
+ * the build from the same `runBuild` that `lorepack build` calls, and the server from
+ * `services/serving.ts`, which is where `lorepack serve` gets it too. A second implementation of
+ * any of them would be a second behaviour for a user to discover.
+ */
+export declare function devCommand(): CommandDefinition;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,yBAAyB,CAAC;AAYhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,UAAU,IAAI,iBAAiB,CAoG9C"}

package/dist/commands/dev.js

@@ -0,0 +1,227 @@
+import { isAbsolute, resolve } from 'node:path';
+import { assertFts5Available } from '@lorepack/backend-local';
+import { count, LoreError, loadConfig } from '@lorepack/core';
+import { runBuild } from '../services/build.js';
+import { assertNoLiveSession, DEV_PORT, removeReceipt, writeReceipt, } from '../services/dev-session.js';
+import { enclosingProject, planInit, runInit } from '../services/init.js';
+import { parsePort, startServing, untilInterrupted } from '../services/serving.js';
+import { startWatching } from '../services/watch.js';
+/**
+ * `lorepack dev [path]`: a folder becomes a running, connected context runtime, asking nothing.
+ *
+ * This is the headline command (architecture 2.2, 6.2), and its whole design is an ordering
+ * decision: **validate, then inspect, then mutate**. Section 6.2 lists the seven steps in
+ * that order for a reason. A run that discovers on step five that this Node build has no
+ * FTS5 has already written files into someone's directory to learn it.
+ *
+ * So the order below is load-bearing rather than incidental:
+ *
+ * 1. capability validation, which touches nothing;
+ * 2. inspection, which reads the directory and writes nothing;
+ * 3. atomic init, which writes and says exactly what it wrote;
+ * 4. build and activate;
+ * 5. serve;
+ * 6. print how to connect.
+ *
+ * It supervises rather than reimplements. Init comes from the same module `lorepack init` uses,
+ * the build from the same `runBuild` that `lorepack build` calls, and the server from
+ * `services/serving.ts`, which is where `lorepack serve` gets it too. A second implementation of
+ * any of them would be a second behaviour for a user to discover.
+ */
+export function devCommand() {
+    return {
+        name: 'dev',
+        description: 'Turn a folder into a running context runtime. Builds, serves, and connects.',
+        arguments: [{ name: 'path', description: 'project directory (default: .)', required: false }],
+        flags: [
+            { flags: '--port <number>', description: `port to listen on (default ${DEV_PORT})` },
+            { flags: '--host <address>', description: 'address to bind (default 127.0.0.1)' },
+            {
+                flags: '--yes',
+                description: 'accept defaults without asking (the default path asks nothing)',
+            },
+            { flags: '--allow-large-project', description: 'continue past the supported file count' },
+        ],
+        handler: async (args, flags, context) => {
+            const directory = resolveDirectory(args[0], context);
+            // Step 1. Before anything is written. Node itself is checked in the entry point, which
+            // is earlier still; this is the capability that a supported Node can nonetheless lack,
+            // because a build linked against a shared SQLite may omit FTS5.
+            assertFts5Available();
+            // Steps 2 and 3. `planInit` reads and writes nothing, so a directory that cannot be
+            // initialized is refused before it is touched.
+            const initialized = autoInit(directory, context);
+            const config = loadConfig({ cwd: directory });
+            // Before building or binding anything: two supervisors on one project would both
+            // watch, both rebuild, and take turns losing the build lock. A receipt whose process
+            // is gone is cleared here rather than treated as an obstacle.
+            assertNoLiveSession(config);
+            // Step 4. The same builder `lorepack build` runs, with its stage table on the same bus, so
+            // a slow parse shows a moving count here exactly as it does there (architecture 6.4).
+            const built = await runBuild({
+                config,
+                progress: context.progress,
+                activate: true,
+                allowLargeProject: flags.allowLargeProject === true,
+                ...(context.signal === undefined ? {} : { signal: context.signal }),
+            });
+            // Step 5. Watching starts before serving, so the server can be handed the watcher's
+            // answer about freshness instead of polling for it. Architecture 12.11 step 3 runs
+            // inside this: a reconciliation scan once the watcher is ready, closing the race
+            // between the build above and the first event below.
+            const watching = startWatching({
+                config,
+                warn: context.warn,
+                rebuild: async (signal) => {
+                    const result = await runBuild({
+                        config,
+                        progress: context.progress,
+                        activate: true,
+                        signal,
+                    });
+                    return { created: result.created };
+                },
+            });
+            const host = typeof flags.host === 'string' ? flags.host : '127.0.0.1';
+            const server = await startServing({
+                config,
+                host,
+                // Architecture 15.3 fixes the preferred dev port, which is not the one `lorepack serve`
+                // uses: a dev session and a read-only server are different things and a developer
+                // may want both at once.
+                port: flags.port === undefined ? DEV_PORT : parsePort(flags.port),
+                warn: context.warn,
+                studio: true,
+                // The hook #112 named. A supervisor that is watching the filesystem already knows
+                // whether the sources moved, so the server stops paying for an interval scan.
+                freshness: () => watching.freshness(),
+                // The same knowledge, in full, for Studio's Diagnostics route. "Nothing has happened
+                // since you started" and "your edit was seen and the rebuild failed" look identical
+                // from a browser without it.
+                watchStatus: () => watching.status(),
+            });
+            // Written once the port is known and the build is activated, so it never advertises a
+            // session that does not exist yet.
+            writeReceipt(config, {
+                port: server.port,
+                pid: process.pid,
+                startedAt: new Date().toISOString(),
+                buildId: server.buildId,
+                host,
+            });
+            // Step 6.
+            context.write(`${render({ initialized, built, url: server.url, studio: server.studio, projectRoot: config.projectRoot, name: config.config.name })}\n`);
+            await untilInterrupted(context.warn);
+            await shutdown(config, watching, server, context.warn);
+            return { human: '', json: undefined };
+        },
+    };
+}
+/** How long a drain may take before the process stops waiting for it. */
+const SHUTDOWN_TIMEOUT_MS = 10_000;
+/**
+ * The documented stop sequence, in order, with a bound on the whole thing.
+ *
+ * The order is the correctness argument. The watcher goes first so a rebuild in flight is
+ * cancelled and its candidate discarded before anything else moves: `runBuild` removes its
+ * own incomplete candidate, so activation never sees it and the build that was active
+ * stays active (architecture 6.9). The server drains next, finishing requests already in
+ * flight rather than cutting them off. Only then are the databases released, because a
+ * request still running would otherwise reach a closed handle.
+ *
+ * The receipt is removed last and unconditionally. A session that is stopping has already
+ * stopped being useful to anyone reading it, and leaving one behind makes the next
+ * `lorepack dev` refuse to start for a process that no longer exists.
+ *
+ * The timeout exists because a wedged request must not be able to hold the process open
+ * forever. Section 15.3's contract is that Ctrl-C ends the session; it does not promise to
+ * wait indefinitely for a socket that will never close.
+ */
+async function shutdown(config, watching, server, warn) {
+    const bounded = async () => {
+        await watching.close();
+        await server.close();
+    };
+    try {
+        await Promise.race([
+            bounded(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), SHUTDOWN_TIMEOUT_MS)),
+        ]);
+    }
+    catch {
+        warn(`Shutdown took longer than ${SHUTDOWN_TIMEOUT_MS} ms. Exiting anyway.\n`);
+    }
+    finally {
+        removeReceipt(config);
+    }
+}
+/**
+ * Writes the configuration a project needs, only when it does not have one.
+ *
+ * Returns null when the project was already configured, which is the re-run path: section
+ * 6.2 promises a second `lorepack dev` skips init and rebuilds only what changed, and the build
+ * step below is already incremental, so there is nothing else to do about it.
+ */
+function autoInit(directory, context) {
+    const planned = planInit({ directory, force: false });
+    if (planned.alreadyInitialized)
+        return null;
+    // Refused for the same reason `lorepack init` refuses it: a project inside a project produces
+    // two builds over overlapping sources, and neither is wrong in a way anyone can see.
+    const enclosing = enclosingProject(directory);
+    if (enclosing !== null) {
+        throw new LoreError('LORE_E_INVALID_ARGUMENT', `${directory} is already inside a Lorepack project rooted at ${enclosing}.`, {
+            remediation: 'Nested projects are not supported. Run `lorepack dev` in the existing project instead.',
+        });
+    }
+    const result = runInit({ directory, force: false });
+    if (result.written.length > 0) {
+        // Section 6.2 step 4 makes this an answer, not a diagnostic: someone pointed a command
+        // at their directory and is owed a plain list of what appeared in it. So stdout, above
+        // the stage table, in the order it happened.
+        context.write(`Created:\n${result.written.map((file) => `  + ${file}`).join('\n')}\n\n`);
+    }
+    return result;
+}
+/**
+ * The first-run block of architecture 6.4, containing every line whose subject exists.
+ *
+ * The Studio line arrived with #64 and is printed only when the assets are actually there.
+ * A package installed without them is a broken install rather than a mode, and printing a
+ * URL that answers 404 would be worse than saying nothing.
+ *
+ * The `Connect now` list names the connectors that exist, and nothing else. Codex arrived
+ * with #80 and VS Code with #81. #53 carries the amendment recording this.
+ */
+function render(rendered) {
+    const { built } = rendered;
+    const lines = ['', `Build           ${built.buildId.slice(0, 17)}`];
+    lines.push(built.reusedArtifacts === 0
+        ? `Reused          0 artifacts (first build)`
+        : `Reused          ${count(built.reusedArtifacts, 'artifact')}`);
+    if (built.warnings > 0) {
+        lines.push(`Warnings        ${count(built.warnings, 'warning')}; run \`lorepack inspect warnings\``);
+    }
+    // Studio first, because it is the line a person opens. The order matches 6.4.
+    if (rendered.studio)
+        lines.push(`Studio          ${rendered.url}`);
+    lines.push(`HTTP            ${rendered.url}/v1`);
+    lines.push(`MCP HTTP        ${rendered.url}/mcp`);
+    // Quoted, because a project path with a space in it is ordinary on every platform and the
+    // line is meant to be pasted (#61 owns the general version of this).
+    lines.push(`MCP stdio       lorepack mcp --project "${rendered.projectRoot}"`);
+    lines.push('');
+    lines.push('Connect now:');
+    lines.push('  lorepack connect claude-code');
+    lines.push('  lorepack connect codex');
+    lines.push('  lorepack connect vscode');
+    lines.push('');
+    lines.push('Watching for changes. Press Ctrl-C to stop.');
+    return lines.join('\n');
+}
+function resolveDirectory(argument, context) {
+    if (argument === undefined)
+        return context.options.cwd;
+    return isAbsolute(argument) ? resolve(argument) : resolve(context.options.cwd, argument);
+}
+//# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

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

package/dist/commands/diff.d.ts

@@ -0,0 +1,3 @@
+import type { CommandDefinition } from '../framework/program.js';
+export declare function diffCommand(): CommandDefinition;
+//# sourceMappingURL=diff.d.ts.map

package/dist/commands/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/commands/diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,yBAAyB,CAAC;AAGhF,wBAAgB,WAAW,IAAI,iBAAiB,CA2C/C"}

package/dist/commands/diff.js

@@ -0,0 +1,75 @@
+import { join } from 'node:path';
+import { diffBuilds, renderDiff } from '@lorepack/compiler';
+import { LORE_DIRECTORY, LoreError, loadConfig } from '@lorepack/core';
+import { openStateStore, readSnapshot, resolveBuildId } from '../services/builds.js';
+export function diffCommand() {
+    return {
+        name: 'diff',
+        description: 'Compare two builds. Reads build data only, never the sources.',
+        arguments: [
+            { name: 'from', description: 'build to compare from', required: false },
+            { name: 'to', description: 'build to compare to', required: false },
+        ],
+        handler: (args, _flags, context) => {
+            const config = loadConfig({ cwd: context.options.cwd });
+            const loreDirectory = join(config.projectRoot, LORE_DIRECTORY);
+            const state = openStateStore(loreDirectory);
+            try {
+                const builds = state.listBuilds();
+                const active = state.current();
+                const [fromReference, toReference] = args;
+                // No arguments compares the active build against its neighbour in history; one
+                // argument compares that build to the active one. Both are the question a user
+                // actually has.
+                const history = builds.map((build) => build.buildId);
+                const { from, to } = fromReference === undefined && toReference === undefined
+                    ? neighbourOf(history, active?.buildId ?? firstOr(history.at(0)))
+                    : {
+                        to: toReference !== undefined
+                            ? resolveBuildId(builds, toReference)
+                            : (active?.buildId ?? firstOr(history.at(0))),
+                        from: fromReference !== undefined
+                            ? resolveBuildId(builds, fromReference)
+                            : (active?.buildId ?? firstOr(history.at(0))),
+                    };
+                const diff = diffBuilds(readSnapshot(loreDirectory, from), readSnapshot(loreDirectory, to));
+                return { human: renderDiff(diff), json: diff };
+            }
+            finally {
+                state.close();
+            }
+        },
+    };
+}
+function firstOr(buildId) {
+    if (buildId === undefined) {
+        throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'This project has no builds to compare.', {
+            remediation: 'Run `lorepack build` to create one.',
+        });
+    }
+    return buildId;
+}
+/**
+ * The pair a bare `lorepack diff` compares: the active build and the build beside it.
+ *
+ * History is newest first, so ordinarily that is the build after the target, and the diff
+ * reads "what the last build changed". After a rollback the active build is the oldest, and
+ * there is nothing after it. That used to be reported as "there is only one build", which
+ * `lorepack builds` contradicted on the line above (#176), and the suggested fix was to change
+ * a source when the build the user wanted already existed.
+ *
+ * So it looks the other way instead, and the diff reads "what moving forward would change".
+ * Both directions answer the same question, which is what the neighbouring build differs by,
+ * and the rendering names both ids so the direction is never guessed.
+ */
+function neighbourOf(history, target) {
+    const index = history.indexOf(target);
+    const older = index === -1 ? undefined : history[index + 1];
+    if (older !== undefined)
+        return { from: older, to: target };
+    const newer = index <= 0 ? undefined : history[index - 1];
+    if (newer !== undefined)
+        return { from: target, to: newer };
+    throw new LoreError('LORE_E_BUILD_NOT_FOUND', 'There is only one build, so there is nothing to compare it against.', { remediation: 'Change a source and run `lorepack build`, then diff again.' });
+}
+//# sourceMappingURL=diff.js.map

package/dist/commands/diff.js.map

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

package/dist/commands/doctor.d.ts

@@ -0,0 +1,14 @@
+import type { CommandDefinition } from '../framework/program.js';
+/**
+ * `lorepack doctor`: when something is wrong, one command names it and says what to do.
+ *
+ * Architecture 6.5 and 6.9. Everything here is read-only, so it is safe to run at any time,
+ * including against a project that is mid-build, and it works in a directory that is not a
+ * project at all: reporting the environment is useful before there is anything to configure.
+ *
+ * The checks themselves live in `services/doctor.ts` because Phase 4's Studio Diagnostics
+ * route (#69) renders the same results over HTTP, and two implementations of "what is wrong
+ * with this environment" would be two answers to one question.
+ */
+export declare function doctorCommand(): CommandDefinition;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,yBAAyB,CAAC;AAIhF;;;;;;;;;;GAUG;AAEH,wBAAgB,aAAa,IAAI,iBAAiB,CAgCjD"}