@vincentt-xr/cli 0.18.1 → 0.18.2

package/MIGRATION.md

@@ -3,6 +3,15 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.18.2
+
+required: false
+No action required. Behaviour that changed:
+- `init` and `create` read the public release list once and clone the template version it names, then check the cloned commit against the platform's record. A commit that does not match exits 1 and writes nothing. When the platform cannot be reached, or has no commit on record, they clone the `latest` tag as before and print one warning on stderr. Plain `init` still needs no account.
+- `vincentt create` in a folder that already holds an app, with no account and no terminal, now exits 4 (not signed in) with the `vincentt login` remedy, where it exited 1. Every not-signed-in path now exits 4.
+- The six preview ending lines no longer use em-dashes: each reads `✓ Preview stopped.` or `✗ Preview ended.` followed by its cause, for example `✗ Preview ended. It reached the 5 GB ceiling.` A script matching the old wording exactly needs updating.
+- `preview --stop` no longer signals a process that merely reuses the preview's old process id: the preview records its start time, and when the process now holding that id started at a different time, nothing is signalled and the command exits 1 as "nothing stopped", clearing the stale record. A preview started by an older CLI, or on Windows, has no start time on record and stops as before.
+
 ## 0.18.1
 
 required: false

package/dist/lib/initCommand.js

@@ -1,5 +1,7 @@
 // `vincentt init [dir]` — scaffold a Vincentt XR app. On the BARE path: NO
-// account, NO network call to the API, NO binding written.
+// account, NO binding written, and no API call beyond the scaffold's anonymous
+// read of the public release list (to verify the template commit; its failure
+// only warns).
 //
 // This is the acquisition wedge: local-first is a smaller room, not a wall, so the
 // template must be reachable without ever touching the auth gate. `create` (which

package/dist/lib/initFrom.js

@@ -93,7 +93,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
             }
             deps.print("");
             deps.print(closing);
-            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.FAILED;
+            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.NOT_AUTHENTICATED;
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");

package/dist/lib/lifecycle.d.ts

@@ -2,6 +2,7 @@ import type { OrgSource } from "./initFrom.js";
 import type { Ask } from "../publish/prompt.js";
 import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
+import { type ProcessStartTimeReader } from "./processStartTime.js";
 import { type ResolvedConfig } from "../shared/config.js";
 import { type RunningPreview, type StartPreviewOptions } from "../preview/index.js";
 import type { DiagEventKind, RelayResult } from "@vincentt-xr/harness/events";
@@ -125,6 +126,8 @@ export interface PreviewStopDeps {
     relay?: RelayClient;
     /** Injected so the SIGTERM is observable without signalling a real process. */
     kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Injected so a recycled pid can be simulated without a real process. */
+    processStartTime?: ProcessStartTimeReader;
 }
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt

package/dist/lib/lifecycle.js

@@ -10,6 +10,7 @@ import { publishCommand } from "../publish/command.js";
 import { activeOrgSlug, resolveActiveOrg } from "./org.js";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
+import { readProcessStartTime } from "./processStartTime.js";
 import { loadMachineConfig, locateProjectBinding, resolveConfig, } from "../shared/config.js";
 import { startPreview, } from "../preview/index.js";
 // The SHIPPED stopping line, reused rather than reworded: the interrupt path and
@@ -173,6 +174,7 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         pid: process.pid,
         harnessPath: "/__harness",
         expiresAt: preview.expiresAt,
+        pidStartTime: await readProcessStartTime(process.pid),
     });
     return { preview, started: true };
 }
@@ -199,6 +201,19 @@ function isAlive(pid) {
 }
 /** The bound the caller is held to: one query, no retry, isRelayResponding's window. */
 const PRESENCE_TIMEOUT_MS = 700;
+/**
+ * True only when the marker recorded a start time and the live process holding
+ * that pid PROVABLY started at a different time. A marker from an older CLI, or
+ * a start time that cannot be read, proves nothing, so the stop goes ahead as it
+ * always did. The relay is deliberately not consulted: QA-F14-06 requires the
+ * stop to happen whatever the relay answers.
+ */
+async function isRecycledPid(info, read) {
+    if (info.pidStartTime === undefined)
+        return false;
+    const live = await read(info.pid);
+    return live !== undefined && live !== info.pidStartTime;
+}
 /**
  * How many connections are attached, or UNDEFINED when that cannot be
  * established — and undefined is a first-class answer here, not an error.
@@ -259,7 +274,11 @@ export async function previewStopSignal(projectCwd, deps = {}) {
     if (!info) {
         return { stopped: false, message: "No preview is running for this directory." };
     }
-    const previewAlive = info.pid !== undefined && isAlive(info.pid);
+    // A recycled pid is treated exactly like a dead one: nothing is signalled, the
+    // relay is not asked, and the stale marker is cleared.
+    const previewAlive = info.pid !== undefined &&
+        isAlive(info.pid) &&
+        !(await isRecycledPid(info, deps.processStartTime ?? readProcessStartTime));
     if (previewAlive) {
         // PRESENCE IS READ BEFORE THE SIGNAL, and the order is the feature. The
         // creator is about to blank someone's screen, so the count has to describe

package/dist/lib/processStartTime.d.ts

@@ -0,0 +1,12 @@
+export type ProcessStartTimeReader = (pid: number) => Promise<string | undefined>;
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export declare function readProcessStartTime(pid: number, platform?: NodeJS.Platform): Promise<string | undefined>;

package/dist/lib/processStartTime.js

@@ -0,0 +1,33 @@
+// A process's start time, read as an opaque token that is only ever compared for
+// equality. Together with the pid it identifies ONE process: a recycled pid has
+// the same number and a different start time.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export async function readProcessStartTime(pid, platform = process.platform) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    if (platform === "win32")
+        return undefined;
+    try {
+        const { stdout } = await execFileP("ps", ["-o", "lstart=", "-p", String(pid)], {
+            env: { ...process.env, LC_ALL: "C" },
+            timeout: 2000,
+        });
+        const lstart = stdout.trim().replace(/\s+/g, " ");
+        return lstart === "" ? undefined : lstart;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/relayInfo.d.ts

@@ -17,6 +17,13 @@ export interface RelayInfo {
      * only assumes is live. Optional: markers written by an older CLI lack it.
      */
     expiresAt?: string;
+    /**
+     * The preview process's start time (an opaque token from
+     * `readProcessStartTime`), so `preview --stop` can tell the preview from an
+     * unrelated process that was later given the same pid. Absent from markers
+     * written by an older CLI or on a platform with no reader.
+     */
+    pidStartTime?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
 /**

package/dist/platform/releaseCache.d.ts

@@ -8,6 +8,13 @@ export interface ReleaseComponent {
      * cannot tell blank from forgotten, so the platform must say which one it is.
      */
     migration?: ReleaseMigration;
+    /**
+     * The released commit (40 lowercase hex). ABSENT for rows released before the
+     * platform recorded it, and for a value of any other shape: the scaffold
+     * verifies a clone against it, so a malformed value must read as "nothing to
+     * verify", never as a value to compare.
+     */
+    commit?: string;
 }
 export interface ReleaseMigration {
     required: boolean;

package/dist/platform/releaseCache.js

@@ -19,6 +19,7 @@ import path from "node:path";
 import { CHECK_TTL_MS } from "../dx/updateCheck.js";
 import { platformCheckEnabled } from "./offSwitch.js";
 const CACHE_FILE = "platform-release.json";
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
 /**
  * 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
@@ -75,13 +76,15 @@ export function readPlatformRelease(raw) {
     for (const [name, value] of Object.entries(components)) {
         if (typeof value !== "object" || value === null)
             continue;
-        const { version, migration } = value;
+        const { version, migration, commit } = value;
         if (typeof version !== "string" || version === "")
             continue;
         const component = { version };
         const note = readMigration(migration);
         if (note !== undefined)
             component.migration = note;
+        if (typeof commit === "string" && COMMIT_SHA.test(commit))
+            component.commit = commit;
         out[name] = component;
     }
     const parsed = { release, components: out };

package/dist/preview/copy.js

@@ -331,7 +331,7 @@ export function stoppedElsewhere() {
 export function endedDisconnected() {
     return [
         "",
-        "✗ Preview ended — the connection to Vincentt closed.",
+        "✗ Preview ended. The connection to Vincentt closed.",
         "",
         "  This window can't tell whether that was your network, your machine going to",
         "  sleep, or something on our side. Nothing is wrong with your project.",
@@ -375,7 +375,7 @@ export function hardMaxWarning(clockTime, minutesLeft) {
 export function hardMaxReached() {
     return [
         "",
-        "✓ Preview stopped — 12-hour maximum reached. The link no longer works.",
+        "✓ Preview stopped. 12-hour maximum reached. The link no longer works.",
         "",
         "  Start a new one:  vincentt preview",
         "  For an address that lasts, publish it:  vincentt publish",
@@ -435,7 +435,7 @@ export function supersededWinner() {
 export function endedUnreachable(orgName) {
     return [
         "",
-        "✗ Preview ended — this project is no longer available to you.",
+        "✗ Preview ended. This project is no longer available to you.",
         "",
         `  Your access to ${orgName} may have changed. Check who you are:  vincentt whoami`,
         "",
@@ -458,7 +458,7 @@ export function endedAuthExpired() {
 export function endedUnconfirmed() {
     return [
         "",
-        "✗ Preview ended — couldn't confirm your access to this project.",
+        "✗ Preview ended. Couldn't confirm your access to this project.",
         "",
         "  Try again:  vincentt preview",
         "",
@@ -498,7 +498,7 @@ export function endedUnconfirmed() {
 export function endedAbandoned() {
     return [
         "",
-        "✗ Preview ended — this machine stopped checking in with Vincentt.",
+        "✗ Preview ended. This machine stopped checking in with Vincentt.",
         "",
         "  The preview needed this computer to stay in touch and it went quiet, so the",
         "  link was released. Nothing is wrong with your project.",
@@ -526,7 +526,7 @@ export function egressSoft() {
 export function egressHard() {
     return [
         "",
-        "✗ Preview ended — it reached the 5 GB ceiling.",
+        "✗ Preview ended. It reached the 5 GB ceiling.",
         "",
         "  Start a new one:  vincentt preview",
         "",

package/dist/scaffold/index.d.ts

@@ -9,6 +9,11 @@ export declare const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export declare const DEFAULT_TEMPLATE_REF = "latest";
 /**
@@ -51,6 +56,12 @@ export interface ScaffoldOptions {
     ref?: string;
     /** Test seam — defaults to spawning real git. */
     runGit?: GitRunner;
+    /** API origin for the release lookup. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam for the release lookup — defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Where the unverified-template warning goes. Defaults to stderr. */
+    warn?: (line: string) => void;
 }
 /**
  * The concrete version tag the clone actually landed on, or `undefined` when the

package/dist/scaffold/index.js

@@ -8,6 +8,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { TemplateCommitMismatchError, UNVERIFIED_TEMPLATE_WARNING, resolveTemplatePin, } from "./releasedCommit.js";
 const execFileAsync = promisify(execFile);
 export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
 /**
@@ -20,6 +21,11 @@ export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export const DEFAULT_TEMPLATE_REF = "latest";
 const realGit = async (args) => {
@@ -128,10 +134,21 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
     const repo = opts.repo ?? TEMPLATE_REPO;
     const ref = opts.ref ?? DEFAULT_TEMPLATE_REF;
     const runGit = opts.runGit ?? realGit;
+    // Only the built-in template has a platform release to check against; a
+    // gallery source (`init --from`) is another repository entirely.
+    const pin = repo === TEMPLATE_REPO
+        ? await resolveTemplatePin(ref, DEFAULT_TEMPLATE_REF, {
+            apiUrl: opts.apiUrl,
+            fetchImpl: opts.fetchImpl,
+        })
+        : { ref, unverified: false };
+    if (pin.unverified) {
+        (opts.warn ?? ((line) => process.stderr.write(`${line}\n`)))(UNVERIFIED_TEMPLATE_WARNING);
+    }
     const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "vincentt-tmpl-"));
     try {
         try {
-            await runGit(["clone", "--depth", "1", "--branch", ref, repo, tmp]);
+            await runGit(["clone", "--depth", "1", "--branch", pin.ref, repo, tmp]);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -140,11 +157,26 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
             // real cause is a typo'd version). git names the ref in this specific case,
             // so split on that rather than reporting one cause for both.
             if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
-                throw new ScaffoldRefError(`The template has no version "${ref}". ` +
-                    `Check the tag exists, or omit --template to use the latest release.`);
+                throw new ScaffoldRefError(pin.ref === ref
+                    ? `The template has no version "${ref}". ` +
+                        `Check the tag exists, or omit --template to use the latest release.`
+                    : `The template has no tag for its released version "${pin.ref}". ` +
+                        `Report this to the Vincentt team.`);
             }
             throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);
         }
+        if (pin.expectedCommit !== undefined) {
+            let actual;
+            try {
+                actual = String((await runGit(["-C", tmp, "rev-parse", "HEAD"])) ?? "").trim();
+            }
+            catch {
+                actual = "";
+            }
+            if (actual !== pin.expectedCommit) {
+                throw new TemplateCommitMismatchError(pin.releasedVersion ?? pin.ref, pin.expectedCommit, actual || "(could not be read)");
+            }
+        }
         // BEFORE the strip below — `.git` is the only place the concrete tag is
         // readable, and the copy into the target deliberately does not carry it.
         // A failure here must not fail the scaffold: the files are correct either

package/dist/scaffold/releasedCommit.d.ts

@@ -0,0 +1,37 @@
+export interface TemplatePin {
+    /** The tag to clone. */
+    ref: string;
+    /** Present when the clone must be checked; the clone fails on any other commit. */
+    expectedCommit?: string;
+    /** The version the platform released, named in the mismatch error. */
+    releasedVersion?: string;
+    /** True when the default ref is cloned with nothing to check it against. */
+    unverified: boolean;
+}
+export interface PinOptions {
+    /** The API origin. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam, passed through to `fetchRelease`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export declare function resolveTemplatePin(requested: string, defaultRef: string, opts?: PinOptions): Promise<TemplatePin>;
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export declare const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export declare class TemplateCommitMismatchError extends Error {
+    constructor(version: string, expected: string, actual: string);
+}

package/dist/scaffold/releasedCommit.js

@@ -0,0 +1,71 @@
+// Which template ref to clone, and which commit it must land on.
+//
+// The template's tags live in a public repo whose admins can move them by hand,
+// so the clone alone proves nothing. The platform records each template
+// release's commit independently (`GET /platform/versions`), and a scaffold of
+// the default ref clones THAT release's version tag and checks the commit.
+import { TEMPLATE_COMPONENT } from "../platform/allowlist.js";
+import { fetchRelease } from "../platform/releaseFetch.js";
+import { loadMachineConfig, machineApiUrl } from "../shared/config.js";
+/** Same shape the scaffold accepts as a concrete version tag. */
+const CONCRETE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export async function resolveTemplatePin(requested, defaultRef, opts = {}) {
+    const row = await fetchTemplateRow(opts);
+    const verifiable = row !== undefined && row.commit !== undefined && CONCRETE_VERSION.test(row.version);
+    if (requested === defaultRef) {
+        if (!verifiable)
+            return { ref: defaultRef, unverified: true };
+        return {
+            ref: row.version,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    if (verifiable && requested === row.version) {
+        return {
+            ref: requested,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    return { ref: requested, unverified: false };
+}
+async function fetchTemplateRow(opts) {
+    try {
+        const apiUrl = opts.apiUrl ?? machineApiUrl(await loadMachineConfig());
+        const fetched = await fetchRelease({ apiUrl, fetchImpl: opts.fetchImpl });
+        return fetched?.release.components[TEMPLATE_COMPONENT];
+    }
+    catch {
+        // An unreadable machine config is the same as an unreachable platform.
+        return undefined;
+    }
+}
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export class TemplateCommitMismatchError extends Error {
+    constructor(version, expected, actual) {
+        super(`The template did not match the released version ${version}.\n` +
+            `  Expected commit ${expected}\n` +
+            `  Actual commit   ${actual}\n\n` +
+            `  Nothing was written. Report this to the Vincentt team.`);
+        this.name = "TemplateCommitMismatchError";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",