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

package/dist/services/config-resolve.js

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { closestMatch, RUNTIME_LIMITS } from '@lorepack/core';
+import { DEV_PORT } from './dev-session.js';
+import { DEFAULT_REVALIDATE_INTERVAL_MS } from './revalidate.js';
+/**
+ * Every resolved value, with the layer that supplied it and where that layer said it.
+ *
+ * Architecture 4.9 calls this transparent magic: defaults work, and nothing is hidden. The
+ * test of it is whether a user can find out what Lorepack decided without reading the
+ * source, which means a value is not enough. A number with no provenance still leaves them
+ * asking where it came from and what to edit.
+ *
+ * ## The distinction that matters most
+ *
+ * Some of these participate in the **build id** and some do not, and confusing the two is a
+ * expensive mistake in both directions. A value that decides what a build *contains*
+ * belongs in the hashed effective configuration; a value that decides how a build is
+ * *served* does not, and moving one in would change the identity of every build in
+ * existence for a number that decides nothing about what any of them hold.
+ *
+ * The Phase 3 audit on #4 called this out specifically for `RUNTIME_LIMITS`, ports and
+ * revalidation intervals. They are shown here, because a user asking "what did you decide"
+ * means all of it, and they are marked `buildId: false`.
+ */
+/** Architecture 6.8, in precedence order, lowest first. */
+export const LAYERS = ['defaults', 'project', 'targets', 'environment', 'flags'];
+/** `LORE_`-prefixed, and deliberately a short list rather than a general override channel. */
+export const ENVIRONMENT_KEYS = [
+    'LORE_DEV_PORT',
+    'LORE_REVALIDATE_INTERVAL_MS',
+    'LORE_LOCK_WAIT_MS',
+];
+/** Anything whose name looks like a credential is redacted rather than printed. */
+const SECRET_PATTERN = /token|secret|password|key|credential/i;
+export function resolveConfiguration(config, environment = process.env) {
+    const values = [];
+    const yamlText = existsSync(config.configPath) ? readFileSync(config.configPath, 'utf8') : '';
+    const declared = (path) => declaredIn(yamlText, path);
+    /**
+     * Which layer supplied a value, for a key the project file may or may not mention.
+     *
+     * Only two layers can supply these today: the built-in defaults and `lore.yaml`. The
+     * targets layer exists in the precedence order and has no content until Phase 6 adds
+     * deployment targets, which #57 says explicitly.
+     */
+    const fromProjectOrDefaults = (path, value, buildId) => declared(path)
+        ? { path, value, layer: 'project', source: config.configPath, buildId }
+        : { path, value, layer: 'defaults', source: 'built-in', buildId };
+    // Everything in the effective configuration participates in the build id, by construction:
+    // it *is* the hashed structure (architecture 11.4).
+    const effective = config.effective;
+    values.push({
+        path: 'name',
+        value: effective.name,
+        layer: 'project',
+        source: config.configPath,
+        buildId: true,
+    });
+    values.push(fromProjectOrDefaults('sources', effective.sources, true));
+    values.push(fromProjectOrDefaults('include', effective.include, true));
+    values.push(fromProjectOrDefaults('exclude', effective.exclude, true));
+    values.push(fromProjectOrDefaults('followSymlinks', effective.followSymlinks, true));
+    values.push(fromProjectOrDefaults('strictRules', effective.strictRules, true));
+    values.push(fromProjectOrDefaults('includeOriginals', effective.includeOriginals, true));
+    values.push(fromProjectOrDefaults('contextProfile', effective.contextProfile, true));
+    for (const [key, value] of Object.entries(effective.chunking)) {
+        values.push(fromProjectOrDefaults(`chunking.${key}`, value, true));
+    }
+    for (const [key, value] of Object.entries(effective.limits)) {
+        values.push(fromProjectOrDefaults(`limits.${key}`, value, true));
+    }
+    values.push({
+        path: 'defaultsVersion',
+        value: effective.defaultsVersion,
+        layer: 'defaults',
+        source: 'built-in',
+        buildId: true,
+    });
+    // Shown even when empty. It is part of the hashed structure whether or not anyone wrote a
+    // rule, and a display that claims to be complete cannot omit a value for being boring:
+    // "no rules" is exactly what a user checking why ranking looks wrong needs to see.
+    values.push({
+        path: 'rules',
+        value: effective.rules,
+        layer: effective.rules.length > 0 ? 'project' : 'defaults',
+        source: effective.rules.length > 0 ? config.configPath : 'built-in',
+        buildId: true,
+    });
+    // Serving bounds. Shown, because "what did you decide" means all of it, and marked as not
+    // participating, because a serving bound decides nothing about what a build contains.
+    for (const [key, value] of Object.entries(RUNTIME_LIMITS)) {
+        values.push(withEnvironment(`runtime.${key}`, value, environment, false));
+    }
+    values.push(withEnvironment('runtime.devPort', DEV_PORT, environment, false));
+    values.push(withEnvironment('runtime.revalidateIntervalMs', DEFAULT_REVALIDATE_INTERVAL_MS, environment, false));
+    return { projectRoot: config.projectRoot, values: values.sort(byPath) };
+}
+/** Applies the environment layer to one serving bound, when a `LORE_*` variable names it. */
+function withEnvironment(path, fallback, environment, buildId) {
+    const variable = environmentKeyFor(path);
+    const raw = variable === null ? undefined : environment[variable];
+    if (variable === null || raw === undefined) {
+        return { path, value: fallback, layer: 'defaults', source: 'built-in', buildId };
+    }
+    const parsed = Number(raw);
+    return {
+        path,
+        value: Number.isFinite(parsed) ? parsed : raw,
+        layer: 'environment',
+        source: variable,
+        buildId,
+        ...(SECRET_PATTERN.test(variable) ? { secret: true } : {}),
+    };
+}
+function environmentKeyFor(path) {
+    if (path === 'runtime.devPort')
+        return 'LORE_DEV_PORT';
+    if (path === 'runtime.revalidateIntervalMs')
+        return 'LORE_REVALIDATE_INTERVAL_MS';
+    return null;
+}
+/**
+ * Whether `lore.yaml` mentions a key, without reimplementing YAML.
+ *
+ * A deliberately shallow test: it decides which *layer* to attribute a value to, and it is
+ * checked against the parsed configuration for the value itself. Being wrong here shows the
+ * wrong provenance, never the wrong number.
+ */
+function declaredIn(yamlText, path) {
+    const [head, ...rest] = path.split('.');
+    if (head === undefined)
+        return false;
+    const topLevel = new RegExp(`^${escapeForRegExp(head)}\\s*:`, 'm');
+    if (!topLevel.test(yamlText))
+        return false;
+    if (rest.length === 0)
+        return true;
+    // A nested key, which in a project file is always indented under its parent.
+    const nested = new RegExp(`^\\s+${escapeForRegExp(rest.join('.'))}\\s*:`, 'm');
+    return nested.test(yamlText);
+}
+function escapeForRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function byPath(left, right) {
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+/** Redacted for display. Never the value, only the fact that there is one. */
+export function displayValue(entry) {
+    if (entry.secret === true)
+        return '[redacted]';
+    if (Array.isArray(entry.value)) {
+        return entry.value.length === 0 ? '(none)' : entry.value.map((item) => String(item)).join(', ');
+    }
+    if (typeof entry.value === 'object' && entry.value !== null)
+        return JSON.stringify(entry.value);
+    return String(entry.value);
+}
+/**
+ * The closest known path to something a user typed.
+ *
+ * `closestMatch` lives in core because `lore.yaml` validation needs the same answer for an
+ * unrecognized key. Two implementations of "what did they probably mean" would give two
+ * different answers to the same typo.
+ *
+ * The threshold scales with the length here, because a configuration path is much longer
+ * than a top-level key and a fixed distance of three is nearly meaningless across
+ * `chunking.targetTokens`.
+ */
+export function closestPath(wanted, known) {
+    return closestMatch(wanted, known, Math.max(2, Math.floor(wanted.length / 3)));
+}
+/** Where the targets layer will read from, once Phase 6 gives it something to say. */
+export function targetsDirectory(projectRoot) {
+    return join(projectRoot, '.lore', 'targets');
+}
+//# sourceMappingURL=config-resolve.js.map

package/dist/services/config-resolve.js.map

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

package/dist/services/deploy.d.ts

@@ -0,0 +1,70 @@
+import { type ActivationReceipt, type Capability, type DeploymentReceipt, type DeploymentTarget, type DeployPlan, type ProgressBus } from '@lorepack/core';
+/**
+ * The deploy orchestration, shared by every target.
+ *
+ * Architecture section 16.3 lists the rules a target must obey, and this is where most of them
+ * are actually enforced. That split is deliberate: a rule a target has to remember is a rule
+ * some target will forget, and the one that forgets will be the one written last, by someone
+ * reading a different target as an example.
+ *
+ * So a target **reports** and this **decides**. A target says which capabilities it can serve;
+ * this refuses the deploy. A target says what its plan would do; this prints it and stops when
+ * asked. A target writes candidate data; this is what insists verification ran against the
+ * candidate before activation is even offered.
+ *
+ * Section 18.5 fixes the sequence:
+ *
+ *     status -> plan -> build if dirty -> project candidate -> verify -> activate -> smoke -> receipt
+ *
+ * `build if dirty` belongs to the caller, because deploying is not the only thing that needs
+ * it and `--no-build` is a flag about the caller's intent rather than about the target.
+ */
+export interface DeployOptions {
+    readonly target: DeploymentTarget;
+    readonly projectRoot: string;
+    readonly projectName: string;
+    readonly buildId: string;
+    readonly buildDirectory: string;
+    readonly buildCapabilities: readonly Capability[];
+    readonly progress: ProgressBus;
+    readonly plan?: DeployPlan;
+    /** Stop after printing the plan. Nothing remote is touched, which is the point. */
+    readonly dryRun?: boolean;
+    /**
+     * Capabilities the user has accepted losing, **by name**.
+     *
+     * Section 16.3 says a named override per capability, never a blanket `--force`. The
+     * difference matters: `--force` is a habit, and a habit that silently drops table queries
+     * from a deployment is exactly what capability negotiation exists to prevent.
+     */
+    readonly allowCapabilityLoss?: readonly Capability[];
+    /** A receipt to continue from, so a partial deploy resumes rather than restarts. */
+    readonly resume?: DeploymentReceipt;
+    /**
+     * Test-only hook for forcing a resumable failure after candidate projection completed.
+     *
+     * The hook lives at the orchestration boundary so acceptance can interrupt a real target
+     * after the projected receipt was written, while production callers omit it entirely.
+     */
+    readonly afterProject?: ((receipt: DeploymentReceipt) => Promise<void> | void) | undefined;
+    readonly now?: () => Date;
+}
+export interface DeployResult {
+    readonly receipt: DeploymentReceipt;
+    readonly plan: DeployPlan;
+    /** Absent on a dry run, which is how a caller knows nothing was activated. */
+    readonly activation?: ActivationReceipt;
+    readonly dryRun: boolean;
+}
+/** Where receipts live. Local, under `.lore/`, so a resume needs nothing remote to find. */
+export declare function receiptsDirectory(projectRoot: string): string;
+export declare function receiptPath(projectRoot: string, receiptId: string): string;
+/**
+ * Reads a receipt to resume from, validated against the committed schema.
+ *
+ * Validated rather than trusted because a receipt is a file on disk that a person can edit,
+ * and a resume driven by a malformed one would replay the wrong steps against a live target.
+ */
+export declare function readReceipt(projectRoot: string, receiptId: string): DeploymentReceipt;
+export declare function runDeploy(options: DeployOptions): Promise<DeployResult>;
+//# sourceMappingURL=deploy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/services/deploy.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,UAAU,EAGf,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAKf,KAAK,WAAW,EAEjB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACrD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IAC3F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAmBrF;AAeD,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA0O7E"}

package/dist/services/deploy.js

@@ -0,0 +1,260 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEPLOY_STEPS, deploymentReceiptSchema, LORE_DIRECTORY, LoreError, writeFileAtomic, } from '@lorepack/core';
+/** Where receipts live. Local, under `.lore/`, so a resume needs nothing remote to find. */
+export function receiptsDirectory(projectRoot) {
+    return join(projectRoot, LORE_DIRECTORY, 'receipts');
+}
+export function receiptPath(projectRoot, receiptId) {
+    return join(receiptsDirectory(projectRoot), `${receiptId}.json`);
+}
+/**
+ * Reads a receipt to resume from, validated against the committed schema.
+ *
+ * Validated rather than trusted because a receipt is a file on disk that a person can edit,
+ * and a resume driven by a malformed one would replay the wrong steps against a live target.
+ */
+export function readReceipt(projectRoot, receiptId) {
+    const path = receiptPath(projectRoot, receiptId);
+    if (!existsSync(path)) {
+        throw new LoreError('LORE_E_BUILD_NOT_FOUND', `No deployment receipt ${receiptId}.`, {
+            // Deliberately naming no command: `lorepack deploy` and `lorepack target` arrive with #91 and
+            // #85, and a remediation pointing at a command that does not exist is worse than one
+            // that describes the action. These become command names when those tickets land.
+            remediation: 'Check the receipt id, or deploy again from the start.',
+            subject: receiptId,
+        });
+    }
+    const parsed = deploymentReceiptSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+    if (!parsed.success) {
+        throw new LoreError('LORE_E_BUILD_VALIDATION', `Receipt ${receiptId} is not readable.`, {
+            remediation: 'Deploy again from the start. A receipt is a record, so losing one is safe.',
+            subject: receiptId,
+        });
+    }
+    return parsed.data;
+}
+function writeReceipt(projectRoot, receipt) {
+    mkdirSync(receiptsDirectory(projectRoot), { recursive: true });
+    writeFileAtomic(receiptPath(projectRoot, receipt.receiptId), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+/** Steps already done, so a resume skips them rather than repeating a remote write. */
+function done(receipt, step) {
+    return receipt?.completedSteps.includes(step) === true;
+}
+export async function runDeploy(options) {
+    const { target, progress } = options;
+    const now = options.now ?? (() => new Date());
+    const accepted = options.allowCapabilityLoss ?? [];
+    const detection = await target.detect();
+    if (!detection.installed) {
+        throw new LoreError('LORE_E_TARGET_NOT_CONFIGURED', `The ${target.id} target is not usable here: ${detection.reason ?? 'it reported no reason'}.`, {
+            remediation: `Set up the ${target.id} target before deploying to it.`,
+            subject: target.id,
+        });
+    }
+    // `validating` rather than a new stage name: the stage set is closed on purpose, and what
+    // planning does here is check a build against a target without changing either.
+    let plan = options.plan;
+    if (plan === undefined) {
+        progress.start('validating', 'Planning', 1);
+        plan = await target.plan({
+            projectName: options.projectName,
+            buildId: options.buildId,
+            buildDirectory: options.buildDirectory,
+            buildCapabilities: options.buildCapabilities,
+        });
+        progress.finish('validating', 1);
+    }
+    /**
+     * Capability loss fails by default, and the override is per capability.
+     *
+     * Checked here rather than in a target so it cannot be forgotten by one, and checked
+     * **before** anything is applied so the refusal costs nothing.
+     */
+    const unaccepted = plan.capabilityLoss.filter((capability) => !accepted.includes(capability));
+    if (unaccepted.length > 0) {
+        throw new LoreError('LORE_E_CAPABILITY_LOSS', `This build uses ${unaccepted.join(', ')}, which the ${target.id} target cannot serve.`, {
+            remediation: `Deploying would answer fewer questions than the local build does. Accept each one by name to continue: ${unaccepted
+                .map((capability) => `--allow-capability-loss ${capability}`)
+                .join(' ')}`,
+            details: { lost: unaccepted },
+        });
+    }
+    const receiptId = options.resume?.receiptId ?? `${target.id}-${options.buildId.slice(5, 17)}`;
+    let receipt = options.resume ?? {
+        formatVersion: 1,
+        receiptId,
+        target: target.id,
+        project: options.projectName,
+        buildId: options.buildId,
+        previousBuildId: null,
+        state: 'planned',
+        deployedAt: now().toISOString(),
+        endpoint: plan.endpoint,
+        capabilityLossAccepted: [...accepted],
+        completedSteps: ['plan'],
+        ...(plan.transfer === undefined ? {} : { transfer: plan.transfer }),
+        verification: { search: 'skipped', sourceRead: 'skipped', tableQuery: 'skipped' },
+    };
+    if (options.dryRun === true) {
+        // Deliberately not written to disk. A dry run that left a receipt behind would make
+        // `--resume` offer to continue something that never started.
+        return { receipt, plan, dryRun: true };
+    }
+    writeReceipt(options.projectRoot, receipt);
+    // Project the candidate. Build-scoped only, so nothing a reader can see changes yet.
+    if (!done(options.resume, 'project')) {
+        let projectionStarted = false;
+        let uploadStarted = false;
+        let projectionCompleted = 0;
+        let uploadCompleted = 0;
+        const reportApplyProgress = (update) => {
+            if (update.stage === 'projecting') {
+                if (!projectionStarted) {
+                    progress.start('projecting', 'Projecting', update.total);
+                    projectionStarted = true;
+                }
+                projectionCompleted = update.completed;
+                progress.progress('projecting', update.completed, {
+                    ...(update.total === undefined ? {} : { total: update.total }),
+                    ...(update.unit === undefined ? {} : { unit: update.unit }),
+                    ...(update.detail === undefined ? {} : { detail: update.detail }),
+                });
+                return;
+            }
+            if (!uploadStarted) {
+                progress.start('uploading', 'Uploading', update.total);
+                uploadStarted = true;
+            }
+            uploadCompleted = update.completed;
+            progress.progress('uploading', update.completed, {
+                ...(update.total === undefined ? {} : { total: update.total }),
+                ...(update.unit === undefined ? {} : { unit: update.unit }),
+                ...(update.detail === undefined ? {} : { detail: update.detail }),
+            });
+        };
+        let applied;
+        try {
+            applied = await target.apply(plan, options.resume, reportApplyProgress);
+        }
+        catch (error) {
+            const partial = partialReceipt(error);
+            if (partial !== null)
+                writeReceipt(options.projectRoot, partial);
+            throw error;
+        }
+        /**
+         * Merged, not replaced. The orchestration owns what it decided.
+         *
+         * A target returns a receipt describing what it wrote, and taking it wholesale let it
+         * erase fields that are not its to set: the first version of this dropped
+         * `capabilityLossAccepted`, so a deploy that gave up a capability recorded that it had
+         * not. The same shape would let a target rewrite the build id or the accepted losses,
+         * which is precisely the "a target reports, this decides" split this file exists for.
+         */
+        receipt = {
+            ...applied,
+            buildId: receipt.buildId,
+            project: receipt.project,
+            target: receipt.target,
+            receiptId: receipt.receiptId,
+            capabilityLossAccepted: receipt.capabilityLossAccepted,
+            ...(applied.transfer === undefined && receipt.transfer !== undefined
+                ? { transfer: receipt.transfer }
+                : {}),
+            state: 'projected',
+            completedSteps: steps(applied, 'project'),
+        };
+        writeReceipt(options.projectRoot, receipt);
+        await options.afterProject?.(receipt);
+        progress.finish('projecting', projectionStarted ? projectionCompleted : plan.steps.length);
+        if (uploadStarted) {
+            progress.finish('uploading', uploadCompleted);
+        }
+    }
+    /**
+     * Verify the candidate, before activation is even offered.
+     *
+     * Section 16.3 says `verify` must query the candidate explicitly. The orchestration cannot
+     * check that a target did so, but it can guarantee the *order*: nothing is activated that
+     * was not verified first, and a verification that failed stops here with the previous build
+     * still serving.
+     */
+    if (!done(options.resume, 'verify')) {
+        progress.start('verifying', 'Verifying', 1);
+        const verification = await target.verify(receipt);
+        receipt = {
+            ...receipt,
+            state: 'verified',
+            ...(verification.capabilities === undefined
+                ? {}
+                : { verifiedCapabilities: [...verification.capabilities] }),
+            verification: {
+                search: verification.search,
+                sourceRead: verification.sourceRead,
+                tableQuery: verification.tableQuery,
+            },
+            completedSteps: steps(receipt, 'verify'),
+        };
+        writeReceipt(options.projectRoot, receipt);
+        progress.finish('verifying', 1);
+        const failed = Object.entries(receipt.verification)
+            .filter(([, outcome]) => outcome === 'failed')
+            .map(([what]) => what);
+        if (failed.length > 0) {
+            const failedReceipt = { ...receipt, state: 'failed' };
+            writeReceipt(options.projectRoot, failedReceipt);
+            throw new LoreError('LORE_E_REMOTE_DEPLOY', `The candidate failed verification: ${failed.join(', ')}.`, {
+                remediation: `Nothing was activated and the previous build is still serving. ${verification.failures?.join(' ') ?? ''}`.trim(),
+                details: { receiptId: receipt.receiptId, failed },
+            });
+        }
+    }
+    // The smallest possible pointer mutation, and the only step that changes what a reader sees.
+    progress.start('activating', 'Activating', 1);
+    const activation = await target.activate(receipt);
+    progress.finish('activating', 1);
+    const activatedReceipt = {
+        ...receipt,
+        previousBuildId: activation.previousBuildId,
+        endpoint: activation.endpoint,
+        completedSteps: steps(receipt, 'activate'),
+    };
+    /**
+     * The smoke check, which is the difference between "the write returned" and "it is serving".
+     *
+     * A target confirms by querying its own public endpoint, so a pointer that was written and
+     * not picked up is caught here rather than by a user. A target that cannot confirm returns
+     * null, and that is recorded rather than treated as success.
+     */
+    if (activation.confirmedBuildId !== null && activation.confirmedBuildId !== options.buildId) {
+        const failedReceipt = { ...activatedReceipt, state: 'failed' };
+        writeReceipt(options.projectRoot, failedReceipt);
+        throw new LoreError('LORE_E_REMOTE_DEPLOY', `The endpoint is serving ${activation.confirmedBuildId}, not the build that was just activated.`, {
+            remediation: 'The pointer was written but the endpoint did not pick it up. Check the target, then deploy again; the projected candidate is still there and will be reused.',
+            details: { expected: options.buildId, serving: activation.confirmedBuildId },
+        });
+    }
+    receipt = {
+        ...activatedReceipt,
+        state: 'active',
+        deployedAt: now().toISOString(),
+        completedSteps: steps(activatedReceipt, 'smoke'),
+    };
+    writeReceipt(options.projectRoot, receipt);
+    return { receipt, plan, activation, dryRun: false };
+}
+/** Appends a step once, in the order section 18.5 fixes, so a resume reads them back reliably. */
+function steps(receipt, step) {
+    const present = new Set(receipt.completedSteps);
+    present.add(step);
+    return DEPLOY_STEPS.filter((known) => present.has(known));
+}
+function partialReceipt(error) {
+    if (typeof error !== 'object' || error === null || !('receipt' in error))
+        return null;
+    const parsed = deploymentReceiptSchema.safeParse(error.receipt);
+    return parsed.success ? parsed.data : null;
+}
+//# sourceMappingURL=deploy.js.map

package/dist/services/deploy.js.map

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

package/dist/services/dev-session.d.ts

@@ -0,0 +1,52 @@
+import { type LoadedConfig } from '@lorepack/core';
+/**
+ * The receipt a running `lorepack dev` leaves, so the session is discoverable rather than
+ * guessed at.
+ *
+ * Architecture 15.3 fixes the file and the preferred port. The reason it exists is that a
+ * dev server is the one long-lived thing Lorepack runs, and everything else that wants to
+ * talk to it (another command, a connector's generated config, the person who has forgotten
+ * which terminal it is in) otherwise has to scan ports and hope.
+ *
+ * A receipt is evidence, not a lock. The process it names may be gone, and a file left
+ * behind by a machine that lost power must not stop the next session from starting. So it
+ * carries a pid and is always checked against reality before it is believed.
+ */
+export declare const DEV_PORT = 43110;
+export declare const DEV_RECEIPT = "dev.json";
+export interface DevReceipt {
+    readonly port: number;
+    readonly pid: number;
+    /** ISO 8601, for a person reading the file rather than for any comparison. */
+    readonly startedAt: string;
+    readonly buildId: string;
+    readonly host: string;
+}
+/**
+ * Written atomically, because a reader may arrive mid-write.
+ *
+ * A truncated receipt is worse than none: it names a port that is half a number, and the
+ * reader has no way to tell that from a session on a strange port. Rename is the one
+ * operation that is atomic on every filesystem this runs on.
+ */
+export declare function writeReceipt(config: LoadedConfig, receipt: DevReceipt): void;
+export declare function readReceipt(config: LoadedConfig): DevReceipt | null;
+export declare function removeReceipt(config: LoadedConfig): void;
+/**
+ * Whether the process a receipt names is still there.
+ *
+ * Signal `0` performs the permission and existence checks without delivering anything,
+ * which is the portable way to ask. `EPERM` means the process exists and belongs to someone
+ * else, which still counts as running.
+ */
+export declare function isRunning(pid: number): boolean;
+/**
+ * Refuses a second supervisor on the same project, and clears a receipt whose process died.
+ *
+ * Two supervisors on one project is not a race worth winning. They would both watch, both
+ * rebuild, and take turns failing to acquire the build lock, and the user would see a
+ * server that intermittently stalls for reasons nothing explains. Refusing with the port of
+ * the session that already exists is more useful than either of them starting.
+ */
+export declare function assertNoLiveSession(config: LoadedConfig): void;
+//# sourceMappingURL=dev-session.d.ts.map

package/dist/services/dev-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-session.d.ts","sourceRoot":"","sources":["../../src/services/dev-session.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAM5E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAkBnE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ9C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAmB9D"}