@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/platform/releaseCache.d.ts

@@ -0,0 +1,69 @@
+/** One component's current version, as the platform publishes it. */
+export interface ReleaseComponent {
+    version: string;
+    /**
+     * ABSENT means unauthored — a different fact from `{required: false}`, which
+     * is the AUTHORED "no action required". Collapsing them silently defeats the
+     * argument that a note is accurate or absent and never speculative: an agent
+     * cannot tell blank from forgotten, so the platform must say which one it is.
+     */
+    migration?: ReleaseMigration;
+}
+export interface ReleaseMigration {
+    required: boolean;
+    summary: string;
+    notes: string[];
+}
+export interface PlatformRelease {
+    /**
+     * `"2026.09.3"` — an IDENTIFIER, never semver, never version-compared. It is
+     * compared for EQUALITY only, which is what makes the notice fire once per
+     * changed release rather than once per interval.
+     */
+    release: string;
+    releasedAt?: string;
+    /** Keyed by package identity (`@vincentt-xr/sdk`), never repo shorthand. */
+    components: Record<string, ReleaseComponent>;
+}
+export interface ReleaseCache {
+    release: PlatformRelease;
+    /** When it was fetched (epoch ms). */
+    at: number;
+    /** The release identifier this machine has already announced, if any. */
+    announcedRelease?: string;
+    etag?: string;
+}
+/**
+ * Freshness, with a clock that moved backwards treated as STALE rather than as
+ * fresh forever. Same rule and same TTL as the CLI update check — reused rather
+ * than re-chosen, because two "how often do we ask" constants drift and the
+ * second one is always the one nobody knows about.
+ */
+export declare function isReleaseFresh(cache: ReleaseCache | undefined, now: number): boolean;
+/**
+ * Parse defensively and STRICTLY. A hand-edited or half-written file must
+ * degrade to "no cache" rather than to a bogus comparison — a partially-parsed
+ * release would produce a notice about versions nobody publishes.
+ */
+export declare function readReleaseCache(raw: unknown): ReleaseCache | undefined;
+/**
+ * Parse the endpoint's body. A component whose version is not a non-empty string
+ * is DROPPED rather than failing the whole document: the platform composes the
+ * set from one row per component, so a single malformed component is not a
+ * reason to know nothing about the others. A MALFORMED MIGRATION NOTE IS TREATED
+ * AS ABSENT and never partially parsed — half a note is worse than none, because
+ * the half that survives reads as complete.
+ */
+export declare function readPlatformRelease(raw: unknown): PlatformRelease | undefined;
+export declare function releaseCachePath(): string;
+/**
+ * Read the cache. Any fault reads as "no cache".
+ *
+ * OFF-SWITCH SITE: with the check off this returns undefined WITHOUT touching
+ * the file. Callers also gate before calling (see `notice.ts`), because a gate
+ * placed only here still means the loader was invoked — and the requirement is
+ * that off means not read at all.
+ */
+export declare function loadReleaseCache(): ReleaseCache | undefined;
+/** Write the cache. Best-effort: a cache that cannot be written asks again. */
+export declare function saveReleaseCache(cache: ReleaseCache): void;

package/dist/platform/releaseCache.js

@@ -0,0 +1,140 @@
+/**
+ * `~/.vincentt/platform-release.json` — the machine-wide answer to "what does
+ * the platform currently publish", plus the record of what this machine has
+ * already said out loud.
+ *
+ * `announcedRelease` is STORED rather than derived, and that is the whole reason
+ * this file holds more than the fetched payload. Derived, "we already told them"
+ * is unfalsifiable: a creator who says they were never told about the new SDK
+ * cannot be answered, and the platform cannot know either. Stored, it is a fact
+ * on disk with the creator's cooperation.
+ *
+ * Nothing here is a secret and nothing here is state a creator would miss, so
+ * the write is best-effort and non-atomic, unlike the machine config. A torn
+ * write costs one extra fetch.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CHECK_TTL_MS } from "../dx/updateCheck.js";
+import { platformCheckEnabled } from "./offSwitch.js";
+const CACHE_FILE = "platform-release.json";
+/**
+ * Freshness, with a clock that moved backwards treated as STALE rather than as
+ * fresh forever. Same rule and same TTL as the CLI update check — reused rather
+ * than re-chosen, because two "how often do we ask" constants drift and the
+ * second one is always the one nobody knows about.
+ */
+export function isReleaseFresh(cache, now) {
+    if (cache === undefined)
+        return false;
+    if (!Number.isFinite(cache.at))
+        return false;
+    const age = now - cache.at;
+    return age >= 0 && age < CHECK_TTL_MS;
+}
+/**
+ * Parse defensively and STRICTLY. A hand-edited or half-written file must
+ * degrade to "no cache" rather than to a bogus comparison — a partially-parsed
+ * release would produce a notice about versions nobody publishes.
+ */
+export function readReleaseCache(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { release, at, announcedRelease, etag } = raw;
+    const parsed = readPlatformRelease(release);
+    if (parsed === undefined)
+        return undefined;
+    if (typeof at !== "number" || !Number.isFinite(at))
+        return undefined;
+    const cache = { release: parsed, at };
+    if (typeof announcedRelease === "string" && announcedRelease !== "") {
+        cache.announcedRelease = announcedRelease;
+    }
+    if (typeof etag === "string" && etag !== "")
+        cache.etag = etag;
+    return cache;
+}
+/**
+ * Parse the endpoint's body. A component whose version is not a non-empty string
+ * is DROPPED rather than failing the whole document: the platform composes the
+ * set from one row per component, so a single malformed component is not a
+ * reason to know nothing about the others. A MALFORMED MIGRATION NOTE IS TREATED
+ * AS ABSENT and never partially parsed — half a note is worse than none, because
+ * the half that survives reads as complete.
+ */
+export function readPlatformRelease(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { release, releasedAt, components } = raw;
+    if (typeof release !== "string" || release === "")
+        return undefined;
+    if (typeof components !== "object" || components === null)
+        return undefined;
+    const out = {};
+    for (const [name, value] of Object.entries(components)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { version, migration } = value;
+        if (typeof version !== "string" || version === "")
+            continue;
+        const component = { version };
+        const note = readMigration(migration);
+        if (note !== undefined)
+            component.migration = note;
+        out[name] = component;
+    }
+    const parsed = { release, components: out };
+    if (typeof releasedAt === "string" && releasedAt !== "")
+        parsed.releasedAt = releasedAt;
+    return parsed;
+}
+function readMigration(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { required, summary, notes } = raw;
+    // `required` is MANDATORY and boolean. Absent or non-boolean is an unauthored
+    // note, not a defaulted one: defaulting it to false would manufacture the
+    // authored "no action required" out of a parse failure.
+    if (typeof required !== "boolean")
+        return undefined;
+    if (typeof summary !== "string")
+        return undefined;
+    const list = Array.isArray(notes)
+        ? notes.filter((n) => typeof n === "string")
+        : [];
+    return { required, summary, notes: list };
+}
+export function releaseCachePath() {
+    return path.join(os.homedir(), ".vincentt", CACHE_FILE);
+}
+/**
+ * Read the cache. Any fault reads as "no cache".
+ *
+ * OFF-SWITCH SITE: with the check off this returns undefined WITHOUT touching
+ * the file. Callers also gate before calling (see `notice.ts`), because a gate
+ * placed only here still means the loader was invoked — and the requirement is
+ * that off means not read at all.
+ */
+export function loadReleaseCache() {
+    if (!platformCheckEnabled())
+        return undefined;
+    try {
+        return readReleaseCache(JSON.parse(fs.readFileSync(releaseCachePath(), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write the cache. Best-effort: a cache that cannot be written asks again. */
+export function saveReleaseCache(cache) {
+    if (!platformCheckEnabled())
+        return;
+    try {
+        fs.mkdirSync(path.dirname(releaseCachePath()), { recursive: true });
+        fs.writeFileSync(releaseCachePath(), JSON.stringify(cache) + "\n", "utf8");
+    }
+    catch {
+        // Nothing here is worth failing a verb over.
+    }
+}

package/dist/platform/releaseFetch.d.ts

@@ -0,0 +1,51 @@
+import { type PlatformRelease } from "./releaseCache.js";
+export declare const VERSIONS_PATH = "/platform/versions";
+export interface FetchReleaseResult {
+    release: PlatformRelease;
+    etag?: string;
+}
+export interface FetchReleaseOptions {
+    /** The API origin. */
+    apiUrl: string;
+    /** Sent as `If-None-Match`. The only request header that changes the response. */
+    etag?: string;
+    signal?: AbortSignal;
+    /** Test seam. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch the current set. `undefined` means nothing to say, including on a `304`
+ * — the caller already holds that answer in its cache and a 304 is not new
+ * information.
+ *
+ * OFF-SWITCH SITE (the refresh): with the check off no request is made at all.
+ */
+export declare function fetchRelease(opts: FetchReleaseOptions): Promise<FetchReleaseResult | undefined>;
+/**
+ * The same read, on an UNREF'D SOCKET, for the unbidden path only.
+ *
+ * WHY THIS EXISTS AND IS NOT `fetch`. The design's performance guarantee is
+ * structural: `preview`'s time-to-URL must not move, and the mechanism named for
+ * it is an `unref`'d refresh. Measured, `unref`'ing the TIMERS is not sufficient
+ * — a pending `fetch` keeps its SOCKET as an active handle, and the platform
+ * exposes no way to unref it, so a verb run against an endpoint that accepts the
+ * connection and never answers waits the full budget before exiting. Against a
+ * healthy endpoint nobody notices; against a hung one every command appears to
+ * hang, and the delay lands on `preview`, where someone is waiting to open a URL
+ * on a phone. That is the exact failure the guarantee was written to exclude.
+ *
+ * `node:http` with `socket.unref()` exits immediately (measured: 2ms against the
+ * same hung endpoint), so the unbidden path uses it and the guarantee holds as a
+ * property rather than as an aspiration. `fetchRelease` above keeps `fetch` and
+ * its injectable seam for `outdated`, which was ASKED for and may legitimately
+ * wait.
+ *
+ * Best-effort throughout, and `undefined` on every fault — including a body that
+ * arrives after the process has already exited, which is the normal case here
+ * and is why this writes through a callback rather than returning a promise the
+ * caller could await.
+ */
+export declare function fetchReleaseDetached(opts: {
+    apiUrl: string;
+    etag?: string;
+}, onResult: (result: FetchReleaseResult) => void): void;

package/dist/platform/releaseFetch.js

@@ -0,0 +1,150 @@
+/**
+ * The one network read: `GET /platform/versions`.
+ *
+ * Public and unauthenticated, so no PAT is attached and no binding is consulted
+ * for anything but the host. `undefined` ON ANY FAULT — a refusal, a timeout, a
+ * 503 from a box with an empty corpus, a body of the wrong shape, a connection
+ * reset. Every one of them is "nothing to say", and the unbidden caller's
+ * silence on all of them must be byte-identical to the silence of a project with
+ * nothing to report. `preview` must not acquire a new way to look broken.
+ *
+ * The 2s budget is f7's `FETCH_TIMEOUT_MS`, reused rather than re-chosen. A
+ * second timeout constant is a second thing to tune and the one nobody finds.
+ */
+import http from "node:http";
+import https from "node:https";
+import { CLIENT_HEADER, clientHeaderValue } from "../shared/clientHeader.js";
+import { FETCH_TIMEOUT_MS } from "../dx/updateCheck.js";
+import { readPlatformRelease } from "./releaseCache.js";
+import { platformCheckEnabled } from "./offSwitch.js";
+export const VERSIONS_PATH = "/platform/versions";
+/**
+ * Fetch the current set. `undefined` means nothing to say, including on a `304`
+ * — the caller already holds that answer in its cache and a 304 is not new
+ * information.
+ *
+ * OFF-SWITCH SITE (the refresh): with the check off no request is made at all.
+ */
+export async function fetchRelease(opts) {
+    if (!platformCheckEnabled())
+        return undefined;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    timer.unref?.();
+    const onAbort = () => controller.abort();
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetchImpl(`${opts.apiUrl.replace(/\/$/, "")}${VERSIONS_PATH}`, {
+            signal: controller.signal,
+            headers: {
+                // The client tag rides along because the existing middleware LOGS it,
+                // and logging is not branching: the handler reads no header but
+                // `If-None-Match`, so this cannot change the answer. Omitting it would
+                // make this one route's requests distinguishable from every other
+                // request the CLI makes, which is the opposite of what is wanted.
+                [CLIENT_HEADER]: clientHeaderValue(),
+                ...(opts.etag ? { "if-none-match": opts.etag } : {}),
+            },
+        });
+        if (!res.ok)
+            return undefined;
+        const release = readPlatformRelease(await res.json());
+        if (release === undefined)
+            return undefined;
+        const etag = res.headers.get("etag") ?? undefined;
+        return etag ? { release, etag } : { release };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * The same read, on an UNREF'D SOCKET, for the unbidden path only.
+ *
+ * WHY THIS EXISTS AND IS NOT `fetch`. The design's performance guarantee is
+ * structural: `preview`'s time-to-URL must not move, and the mechanism named for
+ * it is an `unref`'d refresh. Measured, `unref`'ing the TIMERS is not sufficient
+ * — a pending `fetch` keeps its SOCKET as an active handle, and the platform
+ * exposes no way to unref it, so a verb run against an endpoint that accepts the
+ * connection and never answers waits the full budget before exiting. Against a
+ * healthy endpoint nobody notices; against a hung one every command appears to
+ * hang, and the delay lands on `preview`, where someone is waiting to open a URL
+ * on a phone. That is the exact failure the guarantee was written to exclude.
+ *
+ * `node:http` with `socket.unref()` exits immediately (measured: 2ms against the
+ * same hung endpoint), so the unbidden path uses it and the guarantee holds as a
+ * property rather than as an aspiration. `fetchRelease` above keeps `fetch` and
+ * its injectable seam for `outdated`, which was ASKED for and may legitimately
+ * wait.
+ *
+ * Best-effort throughout, and `undefined` on every fault — including a body that
+ * arrives after the process has already exited, which is the normal case here
+ * and is why this writes through a callback rather than returning a promise the
+ * caller could await.
+ */
+export function fetchReleaseDetached(opts, onResult) {
+    if (!platformCheckEnabled())
+        return;
+    let url;
+    try {
+        url = new URL(`${opts.apiUrl.replace(/\/$/, "")}${VERSIONS_PATH}`);
+    }
+    catch {
+        return;
+    }
+    const transport = url.protocol === "https:" ? https : http;
+    try {
+        const req = transport.request({
+            protocol: url.protocol,
+            hostname: url.hostname,
+            port: url.port,
+            path: `${url.pathname}${url.search}`,
+            method: "GET",
+            headers: {
+                [CLIENT_HEADER]: clientHeaderValue(),
+                ...(opts.etag ? { "if-none-match": opts.etag } : {}),
+            },
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return;
+            }
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+                // Bounded: this is parsed on a creator's machine off a public route,
+                // and an endless body must not grow without limit.
+                if (body.length > 256_000)
+                    req.destroy();
+            });
+            res.on("end", () => {
+                try {
+                    const release = readPlatformRelease(JSON.parse(body));
+                    if (release === undefined)
+                        return;
+                    const etag = res.headers.etag;
+                    onResult(typeof etag === "string" ? { release, etag } : { release });
+                }
+                catch {
+                    // A malformed body is nothing to say.
+                }
+            });
+            res.on("error", () => { });
+        });
+        // THE LOAD-BEARING CALL. Without it a pending request is an active handle
+        // and the process waits on it.
+        req.on("socket", (socket) => socket.unref());
+        req.on("error", () => { });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => req.destroy());
+        req.end();
+    }
+    catch {
+        // A refresh that cannot even be started is nothing to say.
+    }
+}

package/dist/platform/resolve.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The wire shape. `packages` keys are package identities; `template` is the
+ * recorded baseline, and ABSENT means unknown.
+ *
+ * The field names and casing are the contract — the same name and shape on the
+ * publish route and the report route.
+ */
+export interface BuiltWith {
+    packages: Record<string, string>;
+    template?: string;
+}
+export interface ResolveBuiltWithOptions {
+    /**
+     * The recorded template baseline, injected so the resolver does not have to
+     * decide where a binding lives. Omitted → read from the project binding.
+     */
+    templateVersion?: string;
+    /** Test seam: skip the binding read entirely. */
+    readBinding?: boolean;
+}
+/**
+ * Resolve the version set for `projectDir`, or `undefined` when there is
+ * nothing to say.
+ *
+ * ITERATES THE ALLOWLIST — it never enumerates the creator's dependencies and
+ * filters. Only allowlisted paths are opened, so a third-party name is never
+ * read into memory in the first place. This is `B-F17-1` as control flow, and it
+ * is why the creator-facing disclosure can say "and nothing else" truthfully.
+ */
+export declare function resolveBuiltWith(projectDir: string, opts?: ResolveBuiltWithOptions): Promise<BuiltWith | undefined>;

package/dist/platform/resolve.js

@@ -0,0 +1,128 @@
+/**
+ * `builtWith` — what this project resolved on THIS machine, right now.
+ *
+ * ONE resolver, two callers (the publish body and the dx report body). That is
+ * not tidiness: the two payloads carrying byte-identical values for the same
+ * project is the mechanical proof there is one resolver and not two that drifted
+ * — a second resolver is how one surface starts reporting declared ranges while
+ * the other reports installed versions, and neither looks wrong alone.
+ *
+ * INSTALLED, NEVER DECLARED. The version read is the one in
+ * `node_modules/<name>/package.json`, because `^1.2.0` cannot answer "did the
+ * fix reach anyone" and `1.4.0` can. A creator whose lockfile resolved 1.4.0
+ * under a `^1.2.0` declaration HAS the fix, and recording the range would report
+ * them behind while current. (The UPGRADE edits the declared range, because that
+ * is what an install resolves from — two different reads of two different
+ * things, and a dev unifying them breaks one of the two.)
+ *
+ * ABSENT vs EMPTY are different facts and both are first-class. `undefined`
+ * means resolution did not run or found nothing to say; an object with an empty
+ * `packages` map means it ran and found none installed. Nothing is ever
+ * backfilled and there is no `"unknown"` sentinel — a valid-looking version
+ * string is how a surface ends up rendering `sdk@unknown` as a version and how a
+ * comparison ends up running against it.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { PLATFORM_PACKAGES } from "./allowlist.js";
+import { loadProjectBinding } from "../shared/config.js";
+/** §9's bounds. Over-bound entries are DROPPED, never an error. */
+const MAX_PACKAGES = 16;
+const MAX_NAME_BYTES = 128;
+const MAX_VERSION_BYTES = 64;
+/**
+ * The character class a version string must satisfy WHOLE, matching the api's
+ * own `dxCLIVersionRe`. It admits every registry semver — `2.0.0-alpha.3+build.1`,
+ * `1.0.0-rc.1+meta.20260908`, `1.0.0-rc-16` — and nothing that can carry a
+ * sentence.
+ *
+ * Printable ASCII was not enough, and the gap was demonstrated rather than
+ * argued: control bytes were already dropped, so ANSI and OSC-8 were closed, but
+ * punctuation-only injection was wide open. A `version` field in a
+ * `node_modules/*​/package.json` is writable by any postinstall script or
+ * transitive dependency, this string lands INSIDE the payload block on a consent
+ * screen, the CLI's stdout is a coding agent's input, and the sentence below it
+ * asserts "and nothing else" — so the attacker's text lands where an agent parses
+ * loosely with the platform's own copy vouching for it.
+ */
+const VERSION_CLASS = /^[0-9A-Za-z.\-+]+$/;
+/**
+ * A version string, or `undefined` when there is nothing safe to say.
+ *
+ * THE CLASS CHECK RUNS FIRST, on the value AS RECEIVED, and an out-of-class
+ * value is dropped WHOLE. Order is the decision: applied after truncation it
+ * would store a PREFIX of a hostile value, and `1.4` standing in for `1.4.7` is
+ * a wrong fact that looks entirely plausible — a wrong answer to "did the fix
+ * reach anyone", and worse than absence. Truncation therefore only ever sees a
+ * value already known to be in class, which also makes mid-rune truncation moot.
+ *
+ * DROPPED, NEVER REFUSED. An out-of-class value omits the entry; the send still
+ * succeeds. `file:` and `git+ssh://` installs fall out of class and become
+ * ABSENT, which is a first-class state every surface renders honestly, and it is
+ * the accepted cost of closing an injection channel on a consent surface.
+ */
+function sanitizeVersion(raw) {
+    if (!VERSION_CLASS.test(raw))
+        return undefined;
+    if (Buffer.byteLength(raw, "utf8") > MAX_VERSION_BYTES)
+        return undefined;
+    return raw;
+}
+/**
+ * Read one allowlisted package's installed version.
+ *
+ * A missing package, an unreadable manifest, a manifest with no `version` and a
+ * manifest that is not JSON are all the same answer: this package contributes
+ * nothing. None of them is an error, because a project legitimately does not
+ * install every platform package.
+ */
+async function installedVersion(projectDir, name) {
+    try {
+        const manifestPath = path.join(projectDir, "node_modules", ...name.split("/"), "package.json");
+        const raw = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+        if (typeof raw.version !== "string")
+            return undefined;
+        return sanitizeVersion(raw.version);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the version set for `projectDir`, or `undefined` when there is
+ * nothing to say.
+ *
+ * ITERATES THE ALLOWLIST — it never enumerates the creator's dependencies and
+ * filters. Only allowlisted paths are opened, so a third-party name is never
+ * read into memory in the first place. This is `B-F17-1` as control flow, and it
+ * is why the creator-facing disclosure can say "and nothing else" truthfully.
+ */
+export async function resolveBuiltWith(projectDir, opts = {}) {
+    const packages = {};
+    for (const pkg of PLATFORM_PACKAGES) {
+        if (Object.keys(packages).length >= MAX_PACKAGES)
+            break;
+        if (Buffer.byteLength(pkg.name, "utf8") > MAX_NAME_BYTES)
+            continue;
+        const version = await installedVersion(projectDir, pkg.name);
+        if (version !== undefined)
+            packages[pkg.name] = version;
+    }
+    let template = opts.templateVersion;
+    if (template === undefined && opts.readBinding !== false) {
+        try {
+            template = (await loadProjectBinding(projectDir))?.template?.version;
+        }
+        catch {
+            template = undefined;
+        }
+    }
+    const cleanTemplate = template === undefined ? undefined : sanitizeVersion(template);
+    // Nothing resolved at all → undefined, so the caller OMITS the field rather
+    // than sending `{}`. A `{}` says "resolution ran and found nothing", which is
+    // a different and specific fact, and a surface that renders the two the same
+    // way collapses two of the three states this design exists to distinguish.
+    if (Object.keys(packages).length === 0 && cleanTemplate === undefined)
+        return undefined;
+    return cleanTemplate === undefined ? { packages } : { packages, template: cleanTemplate };
+}

package/dist/platform/templateUpgrade.d.ts

@@ -0,0 +1,56 @@
+import { type DependencyChange, type TrackedState } from "./upgradeReport.js";
+/** The manifest file, read-only: it arrives with the TO tree and is never in its own overwrite set. */
+export declare const MANIFEST_FILE = ".vincentt-template.json";
+/** The first template version carrying a manifest, for the blocked report's copy. */
+export declare const FIRST_MANIFEST_VERSION = "1.5.0";
+export type GitRunner = (args: string[]) => Promise<string | void>;
+/**
+ * Validate a recorded FROM ref BEFORE it reaches git.
+ *
+ * Anything not exactly `MAJOR.MINOR.PATCH` is NO BASELINE — not an error, and
+ * not a bare attempt. `../../etc`, `refs/heads/1.4.3`, `1.4.3; rm -rf` and
+ * `latest` all resolve to "no baseline" without git being invoked at all.
+ */
+export declare function validateFromRef(raw: string | undefined): string | undefined;
+export interface UpgradeDeps {
+    projectDir: string;
+    /** The TO version — a concrete tag. */
+    to: string;
+    /**
+     * What the dependency half reported. The template half is attempted only when
+     * every platform package the project has is accounted for here.
+     */
+    dependencyOutcome: DependencyOutcome;
+    runGit?: GitRunner;
+    /** Test seam: substitute the clone with a local directory per ref. */
+    fetchTag?: (ref: string) => Promise<string | undefined>;
+    /** Test seam for tracked-ness, so the git plumbing is injectable. */
+    trackedStateOf?: (projectDir: string, rel: string) => Promise<TrackedState>;
+}
+export interface DependencyOutcome {
+    /** Packages the dependency half completed. */
+    completed: DependencyChange[];
+    /**
+     * Packages it did NOT complete. Non-empty means the template half is not
+     * attempted — the ordering precondition, expressed as data the report reads
+     * rather than as an exit code the procedure may not read.
+     */
+    outstanding: string[];
+}
+export interface UpgradeOutcome {
+    /** The rendered report. The procedure reads THIS, never an exit code. */
+    report: string[];
+    /** Whether the template half wrote any file. */
+    templateAttempted: boolean;
+    /** The baseline recorded, if any. Written LAST. */
+    baselineWritten?: string;
+}
+/**
+ * Run the template half.
+ *
+ * Every early return renders a report and writes nothing. There is no path
+ * through this function that overwrites a file without the report naming it.
+ */
+export declare function upgradeTemplate(deps: UpgradeDeps): Promise<UpgradeOutcome>;
+/** Which platform packages this project has installed, for the ordering precondition. */
+export declare function installedPlatformPackages(projectDir: string): Promise<string[]>;