@vincentt-xr/cli 0.12.3 → 0.14.0

package/dist/shared/locationStore.js

@@ -0,0 +1,216 @@
+/**
+ * The location store — which folder a project was last worked in, on THIS
+ * machine, never transmitted.
+ *
+ * The binding points folder → project. This points project → folder, so a
+ * project can be resumed by name from anywhere on the machine it was worked on.
+ * It is written as a byproduct of resolving or creating a binding: there is no
+ * command to run and nothing for the creator to remember.
+ *
+ * It lives beside the journal and reuses its file mechanics deliberately —
+ * append-only NDJSON, O_APPEND atomicity in place of a lock, skip-malformed on
+ * read, never-throws on write, 0700/0600 with the explicit post-write chmod, and
+ * the same Windows caveat (chmodSync toggles the read-only bit there and nothing
+ * else; config.json holds the PAT in the same directory with the same exposure,
+ * so hardening this file alone would imply a boundary the more valuable file
+ * does not have).
+ *
+ * It deviates from the journal in exactly two places, and both have the same
+ * reason: a lost journal line costs a slightly-wrong friction report, and a lost
+ * entry here costs the creator their shortcut, which is the feature.
+ *
+ *   1. Compaction happens ON READ by temp-file-plus-rename, not on every write
+ *      by whole-file rewrite. The journal's rewrite is not atomic and two
+ *      trimming processes can lose entries.
+ *   2. The writer TERMINATES DEFENSIVELY. The journal appends `entry + "\n"` and
+ *      trusts the previous write; a process killed mid-append leaves an
+ *      unterminated fragment, and the next append concatenates onto it, making
+ *      one unparseable line that destroys BOTH the torn entry and a good entry
+ *      that was never at risk.
+ *
+ * It holds a path where the journal may not (B-F7-1) for a narrow reason: the
+ * journal is a candidate for transmission and describes Vincentt; this file is
+ * never transmitted, by any command, on any schedule, in any report, on any
+ * failure path, and describes only the creator's own filesystem. Any future
+ * proposal to send it is a re-groom, not an increment.
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const LOCATIONS_FILE = "locations.ndjson";
+/**
+ * An entry is a DISTINCT FOLDER, not a run, so the bound is far smaller than the
+ * journal's 2000. 500 folders is beyond any real creator and holds the file
+ * under ~60 KB.
+ */
+export const MAX_ENTRIES = 500;
+/**
+ * Resolved per call rather than captured at module load — the same discipline
+ * and the same reason as `journalPath()`: the home directory is the seam tests
+ * move, and a frozen path silently writes the developer's real one.
+ */
+export function locationsPath() {
+    return path.join(os.homedir(), ".vincentt", LOCATIONS_FILE);
+}
+function isEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const e = value;
+    return typeof e.p === "string" && e.p !== "" && typeof e.d === "string" && e.d !== "";
+}
+/**
+ * Read oldest-first. Malformed lines are skipped, and an unreadable file yields
+ * an empty list — a store that FAILS is indistinguishable from a store that is
+ * EMPTY, which is the correct blast radius: a fresh install is exactly that
+ * state and is fully supported.
+ */
+export function readLocations() {
+    let raw;
+    try {
+        raw = fs.readFileSync(locationsPath(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isEntry(parsed))
+                out.push({ p: parsed.p, d: parsed.d, t: parsed.t ?? "" });
+        }
+        catch {
+            // A torn line from a killed process is not a reason to lose the rest.
+        }
+    }
+    return out;
+}
+/**
+ * Does the file end in a newline, or is there nothing there yet?
+ *
+ * Two syscalls against the page cache (`statSync` for the size, a one-byte read
+ * at `size - 1`), skipped entirely when the file is absent or empty. Writing
+ * `"\n" + line` unconditionally was rejected: it makes a leading blank line the
+ * normal case the reader must then tolerate, hiding the torn-write signal
+ * instead of repairing it.
+ */
+export function needsLeadingNewline(file) {
+    let size;
+    try {
+        size = fs.statSync(file).size;
+    }
+    catch {
+        return false;
+    }
+    if (size === 0)
+        return false;
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const buf = Buffer.alloc(1);
+        const read = fs.readSync(fd, buf, 0, 1, size - 1);
+        return read === 1 && buf[0] !== 0x0a;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Nothing to salvage; the append below is best-effort anyway.
+            }
+        }
+    }
+}
+/**
+ * Append one entry. Never throws, for the journal's stated reason:
+ * instrumentation that breaks the tool it measures is worse than none. Every
+ * failure mode here (a read-only home, a full disk, a directory where the file
+ * should be) is one the creator would rather have silently ignored than turned
+ * into a failed `publish`.
+ *
+ * `locationsPath()` is INSIDE the try because it calls `os.homedir()`, which can
+ * itself throw on a hostile environment.
+ */
+export function appendLocation(entry) {
+    try {
+        const file = locationsPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const prefix = needsLeadingNewline(file) ? "\n" : "";
+        fs.appendFileSync(file, prefix + JSON.stringify(entry) + "\n", {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        // `mode` on appendFile only applies when it CREATES the file, so a store
+        // that predates this (or a looser umask) would keep its old perms.
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // A shortcut index that can fail a publish is not worth having.
+    }
+}
+/**
+ * Collapse duplicate `(p, d)` pairs to their newest `t`, then keep the newest
+ * MAX_ENTRIES. Returned oldest-first, which is the order the file holds.
+ */
+export function compactEntries(entries) {
+    const newest = new Map();
+    for (const e of entries) {
+        const key = `${e.p}\0${e.d}`;
+        const seen = newest.get(key);
+        if (!seen || (e.t ?? "") >= (seen.t ?? ""))
+            newest.set(key, e);
+    }
+    const all = [...newest.values()].sort((a, b) => (a.t ?? "").localeCompare(b.t ?? ""));
+    return all.slice(-MAX_ENTRIES);
+}
+/**
+ * Rewrite the store with the survivors, ATOMICALLY: a unique temp file at 0600,
+ * chmod'ed explicitly, renamed over the target, and removed if the rename fails.
+ * The discipline `persistMachineConfig` already uses for the credential file.
+ *
+ * Rewrite-with-survivors rather than delete-lines, so a crash leaves either the
+ * original file or the fully compacted one and never a truncated store — which
+ * would be indistinguishable from an empty one BY DESIGN, and therefore
+ * invisible at every behavioral tier.
+ *
+ * An append landing inside the rename window is lost. That is accepted and
+ * self-healing (the folder that appended is a folder a verb just ran in), and it
+ * is the one place the no-lock choice has a visible cost.
+ *
+ * Never throws: it runs AFTER the answer has printed, and a compaction that
+ * fails must not delay or break it.
+ */
+export function compactLocations(keep) {
+    const file = locationsPath();
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        const body = keep.map((e) => JSON.stringify(e)).join("\n");
+        fs.writeFileSync(tmp, body === "" ? "" : body + "\n", {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // A stray temp file is not worth failing a listing over.
+        }
+    }
+}
+/** The real store, reading and writing the creator's own home directory. */
+export const fileLocationStore = {
+    read: readLocations,
+    append: appendLocation,
+    compact: compactLocations,
+};

package/dist/shared/recordLocation.d.ts

@@ -0,0 +1,33 @@
+import { type LocationStore } from "./locationStore.js";
+export interface RecordLocationDeps {
+    /** Injectable for tests; defaults to the real home-directory store. */
+    append?: LocationStore["append"];
+    /**
+     * Resolve a path through its symlinks. Injectable following
+     * `ProjectCommandDeps.realpath`, so the case-twin and symlink arms are
+     * testable on a Linux runner that cannot reproduce either natively.
+     */
+    realpath?: (dir: string) => string;
+    now?: () => Date;
+}
+/**
+ * Record that `projectId` lives in `dir`.
+ *
+ * `d` is the REALPATH-resolved directory, falling back to the unresolved path on
+ * failure exactly as `create` and `workingTreeKey` already do. A symlinked path,
+ * a macOS case-insensitive twin, or a bind mount otherwise yields two different
+ * `d` strings for one directory, which neither the dedup set nor compaction
+ * collapses — and the listing then reports one folder twice as an ambiguity that
+ * does not exist, asking the creator to choose between two spellings of the same
+ * place. Falling back rather than dropping keeps an unresolvable folder recorded.
+ *
+ * The dedup key's SHAPE is unchanged — `${projectId}\0${dir}` — but `dir` is now
+ * guaranteed canonical, which is what makes the key correct rather than merely
+ * well-formed. A folder rebound from project A to project B still legitimately
+ * holds two entries, because the key includes the project.
+ *
+ * Never throws.
+ */
+export declare function recordLocation(projectId: string, dir: string, deps?: RecordLocationDeps): void;
+/** Test seam only — the dedup set is process-lifetime state. */
+export declare function resetLocationDedupForTest(): void;

package/dist/shared/recordLocation.js

@@ -0,0 +1,76 @@
+/**
+ * The write hook — one binding resolution or creation becomes one store entry.
+ *
+ * It hangs off `locateProjectBinding`'s success return and off
+ * `writeProjectBinding`, which are the only two ways a folder comes to name a
+ * project. A hook per verb was rejected: it creates the class of bug where a
+ * newly added verb silently does not record, and one hook in the one resolver
+ * makes "any command that successfully resolves a binding records that folder"
+ * true by construction rather than by a checklist somebody has to keep current.
+ *
+ * SYNCHRONOUS on purpose, inside async callers. The CLI's top-level handler
+ * calls `process.exit(1)` and the feedback watch calls `process.exit(0)` on
+ * SIGINT; both abandon a pending async write, so an async store would lose
+ * exactly the runs worth recording.
+ */
+import fs from "node:fs";
+import { appendLocation } from "./locationStore.js";
+/**
+ * Deduplicated per PROCESS, not per call. `locateProjectBinding` runs more than
+ * once per invocation on several paths — `publish` reaches it via
+ * `resolveConfig` and via its own `binding` dep — so without this the file grows
+ * with internal resolution calls rather than with distinct folders touched.
+ */
+const written = new Set();
+function defaultRealpath(dir) {
+    return fs.realpathSync(dir);
+}
+/**
+ * Record that `projectId` lives in `dir`.
+ *
+ * `d` is the REALPATH-resolved directory, falling back to the unresolved path on
+ * failure exactly as `create` and `workingTreeKey` already do. A symlinked path,
+ * a macOS case-insensitive twin, or a bind mount otherwise yields two different
+ * `d` strings for one directory, which neither the dedup set nor compaction
+ * collapses — and the listing then reports one folder twice as an ambiguity that
+ * does not exist, asking the creator to choose between two spellings of the same
+ * place. Falling back rather than dropping keeps an unresolvable folder recorded.
+ *
+ * The dedup key's SHAPE is unchanged — `${projectId}\0${dir}` — but `dir` is now
+ * guaranteed canonical, which is what makes the key correct rather than merely
+ * well-formed. A folder rebound from project A to project B still legitimately
+ * holds two entries, because the key includes the project.
+ *
+ * Never throws.
+ */
+export function recordLocation(projectId, dir, deps = {}) {
+    try {
+        if (!projectId || !dir)
+            return;
+        const resolve = deps.realpath ?? defaultRealpath;
+        let resolved;
+        try {
+            resolved = resolve(dir);
+        }
+        catch {
+            resolved = dir;
+        }
+        const key = `${projectId}\0${resolved}`;
+        if (written.has(key))
+            return;
+        written.add(key);
+        const append = deps.append ?? appendLocation;
+        append({
+            p: projectId,
+            d: resolved,
+            t: (deps.now ? deps.now() : new Date()).toISOString(),
+        });
+    }
+    catch {
+        // A shortcut index must never break the command it rides on.
+    }
+}
+/** Test seam only — the dedup set is process-lifetime state. */
+export function resetLocationDedupForTest() {
+    written.clear();
+}

package/package.json

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