@vincentt-xr/cli 0.15.2 → 0.17.0

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[]>;