@vincentt-xr/cli 0.12.3 → 0.13.0

package/README.md

@@ -67,7 +67,8 @@ Project
                        [--force] [--no-install]
   link <project-id>  Link this directory to an existing project
   unlink             Detach this directory from its project
-  projects           List the workspace's projects and their ids
+  projects           List the workspace's projects, their ids, and where each
+                       one lives on this machine
                        [--json] [--org <s>]
 
 Dev loop
@@ -119,5 +120,23 @@ In a directory that is not linked to anything, `npx vincentt projects` lists the
 workspace's projects with their ids, which is what `vincentt link <project-id>`
 needs. `--json` prints the same rows for a program to read.
 
+It also reports **where each project lives on this machine**. Any command run in
+a linked folder records that folder against the project, so a project you have
+worked on here is listed with its directory on an indented line under its row:
+
+```
+  66f1c2a9e4b7   museum-ar-tour   Museum AR Tour   museum-ar-tour.vincentt.app
+      ↳ /Users/alice/code/museum-ar-tour
+```
+
+A project this machine has no folder for reads `no folder known on this machine`
+rather than leaving a gap, and a project checked out in several places lists
+every one without picking. The folder is checked when it is read — it is only
+reported if it still holds that project's binding — so a path that has moved or
+been unbound is never handed back. Under `--json` every project carries a
+`locations` array: empty when unknown, one member when located, several when the
+project is in more than one place. Nothing about this leaves the machine, and
+deleting `~/.vincentt/locations.ndjson` costs nothing but the shortcut.
+
 `vincentt` is a project devDependency in the scaffold, so invoke it as
 `npx vincentt <verb>` and it resolves to the local copy — no global install.

package/dist/cli/index.js

@@ -19,6 +19,7 @@ import { httpAuthBackend } from "../login/authBackend.js";
 import { loginCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
 import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
+import { fileLocationStore } from "../shared/locationStore.js";
 import { getMe, listProjects, ProjectUnreachableError } from "../lib/backend.js";
 import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
@@ -395,6 +396,7 @@ async function projects() {
             return resolveOrgForCommand(cfg, { flag: flag("--org") });
         },
         list: listProjects,
+        store: fileLocationStore,
     }, { json: has("--json") });
 }
 /**

package/dist/cli/usage-text.js

@@ -30,7 +30,10 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       [--org <s>] [--preview] [--force] [--no-install]\n` +
     `  link <project-id>  Link this folder to an existing project\n` +
     `  unlink             Disconnect this folder from its project\n` +
-    `  projects           List the workspace's projects and their ids  [--json]\n` +
+    `  projects           List the workspace's projects, their ids, and where each\n` +
+    `                       one lives on this machine  [--json]\n` +
+    `                       A project this machine has no folder for says\n` +
+    `                       "no folder known on this machine" rather than leaving a gap.\n` +
     `                       [--org <s>] to list a workspace other than the active one\n\n` +
     `Dev loop\n` +
     `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +

package/dist/lib/listProjects.d.ts

@@ -1,5 +1,8 @@
 import type { ProjectView } from "./backend.js";
 import type { ResolvedConfig } from "../shared/config.js";
+import { type LocationStore } from "../shared/locationStore.js";
+/** The unknown case, printed rather than omitted. Repeated verbatim in the scaffolded agent contract. */
+export declare const NO_LOCATION = "no folder known on this machine";
 export interface ListProjectsDeps {
     print: (line: string) => void;
     /** The machine's API host + PAT, or undefined when nothing is signed in. */
@@ -16,6 +19,14 @@ export interface ListProjectsDeps {
         message: string;
     }>;
     list: (cfg: ResolvedConfig, orgSlug: string) => Promise<ProjectView[]>;
+    /**
+     * The machine's location store. REQUIRED as a dep, not optional: without it
+     * this command acquires a hard dependency on the real home directory and the
+     * header's claim above stops being true.
+     */
+    store?: LocationStore;
+    /** The verification predicate, injectable so the drop-or-report decision needs no filesystem. */
+    verify?: (dir: string, projectId: string) => boolean;
 }
 export interface ListProjectsOptions {
     json?: boolean;
@@ -38,4 +49,4 @@ export declare function listProjectsCommand(deps: ListProjectsDeps, opts?: ListP
  * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
  * address on staging and dev.
  */
-export declare function projectRows(projects: ProjectView[]): string[];
+export declare function projectRows(projects: ProjectView[], locations?: Map<string, string[]>): string[];

package/dist/lib/listProjects.js

@@ -10,8 +10,21 @@
 // were bad: guess an id, tell the creator to open the console and copy one, or
 // fail. `link` needs an id, and until now nothing printed one.
 //
-// The IO boundary (print, backend, org) is injected, so every branch is testable
-// with no API, no HOME, and no network.
+// It also answers WHERE, for a project this machine has worked on before, by
+// joining the machine-local location store on the project id. The store is a
+// hint pointing at a hint: every candidate folder is verified against the
+// binding it claims to hold before it is reported, and the server re-authorizes
+// on every request regardless. It is the ONLY reader of the store in the
+// product.
+//
+// The IO boundary (print, backend, org, store, verify) is injected, so every
+// branch is testable with no API, no HOME, and no network.
+import { compactEntries, fileLocationStore, } from "../shared/locationStore.js";
+import { joinLocations, verifyLocation } from "./locations.js";
+/** The unknown case, printed rather than omitted. Repeated verbatim in the scaffolded agent contract. */
+export const NO_LOCATION = "no folder known on this machine";
+/** The row's own two spaces, plus four. A CONSTANT — never aligned to a column. */
+const CONTINUATION_INDENT = "      ";
 /**
  * The columns are `id`, `slug`, `name` and where it stands.
  *
@@ -32,13 +45,32 @@ export async function listProjectsCommand(deps, opts = {}) {
         return 1;
     }
     const projects = await deps.list(cfg, org.org.slug);
+    // The store is not consulted when there is nothing to join against: a creator
+    // with no projects must not learn that a location feature exists, and the
+    // location is a property of a project ROW.
+    const located = projects.length === 0
+        ? { byProject: new Map(), compact: () => { } }
+        : readLocationsFor(deps, projects);
     if (opts.json) {
         // `{projects: [...]}` — the server's own envelope, holding the SAME
         // `ProjectView` every other verb in this CLI parses a project into. It is a
         // projection of the wire row (the API also sends version/timestamp fields),
         // and it is deliberately the shared one rather than a listing-specific
         // shape: a second projection here would be a second thing that can drift.
-        deps.print(JSON.stringify({ projects }, null, 2));
+        //
+        // `locations` is COMPOSED alongside the parsed row rather than added to
+        // `ProjectView`. That type's contract is "what the API returned", and
+        // putting a purely local filesystem fact inside it is how a never-transmitted
+        // value comes to look transmittable to the next reader — the property this
+        // whole design rests on. It is the LAST key for the same reason: the object
+        // is the API row plus one local fact, and the reading order says where the
+        // wire ends.
+        const rows = projects.map((p) => ({
+            ...p,
+            locations: located.byProject.get(p.id) ?? [],
+        }));
+        deps.print(JSON.stringify({ projects: rows }, null, 2));
+        located.compact();
         return 0;
     }
     if (projects.length === 0) {
@@ -52,12 +84,51 @@ export async function listProjectsCommand(deps, opts = {}) {
     }
     deps.print(`${projects.length} project${projects.length === 1 ? "" : "s"} in ${org.org.name}`);
     deps.print("");
-    for (const line of projectRows(projects))
+    for (const line of projectRows(projects, located.byProject))
         deps.print(line);
     deps.print("");
     deps.print("  Link a folder to one:  vincentt link <project-id>");
+    // AFTER the answer has printed, never before: a compaction that fails must
+    // not delay or break it.
+    located.compact();
     return 0;
 }
+/**
+ * Read the store, verify what this listing joins against, and hand back both the
+ * answer and a deferred compaction.
+ *
+ * Nothing here throws: a store that cannot be read yields no locations, every
+ * project reports unknown, and that is BYTE-IDENTICAL to a fresh install — which
+ * is the correct blast radius for a broken shortcut index.
+ */
+function readLocationsFor(deps, projects) {
+    const store = deps.store ?? fileLocationStore;
+    const verify = deps.verify ?? verifyLocation;
+    try {
+        const entries = store.read();
+        const joined = joinLocations(entries, projects.map((p) => p.id), verify);
+        return {
+            byProject: joined.byProject,
+            compact: () => {
+                try {
+                    const next = compactEntries(joined.survivors);
+                    // A read that dropped nothing and is already inside the bound has
+                    // nothing to rewrite, and a rename window nobody needs is a window an
+                    // append can be lost in.
+                    if (!joined.dropped && next.length === entries.length)
+                        return;
+                    store.compact(next);
+                }
+                catch {
+                    // The answer is already printed.
+                }
+            },
+        };
+    }
+    catch {
+        return { byProject: new Map(), compact: () => { } };
+    }
+}
 /**
  * Aligned on the widest id and slug so the block reads as a table in a terminal
  * and stays greppable in an agent's transcript.
@@ -67,11 +138,31 @@ export async function listProjectsCommand(deps, opts = {}) {
  * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
  * address on staging and dev.
  */
-export function projectRows(projects) {
+export function projectRows(projects, locations = new Map()) {
     const idWidth = Math.max(...projects.map((p) => p.id.length));
     const slugWidth = Math.max(...projects.map((p) => p.slug.length));
-    return projects.map((p) => {
+    const out = [];
+    for (const p of projects) {
         const state = p.publishState === "live" && p.liveUrl ? p.liveUrl : p.publishState;
-        return `  ${p.id.padEnd(idWidth)}   ${p.slug.padEnd(slugWidth)}   ${p.name}   ${state}`;
-    });
+        out.push(`  ${p.id.padEnd(idWidth)}   ${p.slug.padEnd(slugWidth)}   ${p.name}   ${state}`);
+        // EVERY row carries exactly one non-empty `↳` block. That regularity is the
+        // design: the reader learns the shape once and never has to decide whether a
+        // missing line means UNKNOWN or NOT PRINTED — and it makes an older CLI,
+        // which prints no `↳` at all, a visible difference rather than an ambiguity.
+        //
+        // Nothing marks one of several as preferred: no `(newest)`, no bullet, no
+        // count, no bold. Ordering is most-recently-worked-in first and is
+        // presentation only, deliberately not printed, because a printed "newest" is
+        // the hint that becomes a pick.
+        //
+        // The path is never truncated. A wrapped path is ugly; a path a creator
+        // cannot copy is a bug report.
+        const dirs = locations.get(p.id) ?? [];
+        if (dirs.length === 0)
+            out.push(`${CONTINUATION_INDENT}↳ ${NO_LOCATION}`);
+        else
+            for (const d of dirs)
+                out.push(`${CONTINUATION_INDENT}↳ ${d}`);
+    }
+    return out;
 }

package/dist/lib/locations.d.ts

@@ -0,0 +1,59 @@
+import type { LocationEntry } from "../shared/locationStore.js";
+/**
+ * At most this many folder checks per listing. 64 reads is ~1-3 ms against an
+ * API call the listing already spent 50-200 ms on. The ceiling exists so a
+ * pathological store — an agent looping `create` in generated folders — cannot
+ * turn a listing into a filesystem walk, and it FAILS TOWARD "unknown", never
+ * toward "here is a path we did not check", which is the only direction the
+ * verify-at-read rule permits.
+ */
+export declare const VERIFY_LIMIT = 64;
+/**
+ * Does `dir` still hold a binding naming `projectId`?
+ *
+ *   ENOENT                          → dead (deleted, moved, drive unmounted, unbound)
+ *   present but unparseable         → dead
+ *   present with no projectId       → dead
+ *   projectId !== the entry's       → dead (bound to a different project)
+ *   otherwise                       → live
+ *
+ * A DIRECT read, not `locateProjectBinding`'s upward walk. The store recorded
+ * the directory that HOLDS the file, and walking upward from it would let a
+ * PARENT repo's binding validate a child folder the store should have dropped —
+ * answering with a plausible-but-wrong path, which is precisely what
+ * verify-at-read exists to prevent.
+ *
+ * Exactly one `readFile` of an ~80-byte file. Not a `stat` then a read: ENOENT
+ * is the negative answer.
+ */
+export declare function verifyLocation(dir: string, projectId: string): boolean;
+export interface JoinResult {
+    /** Verified folders, newest first, keyed by project id. */
+    byProject: Map<string, string[]>;
+    /** Every entry that should survive compaction, oldest-first as the file holds it. */
+    survivors: LocationEntry[];
+    /** Whether anything was dropped, so a clean read can skip the rewrite. */
+    dropped: boolean;
+}
+/**
+ * Join the store against the ids in this listing, verify newest-first, and
+ * report what survives.
+ *
+ * Verification is SCOPED TO THE JOIN: entries for projects in another workspace
+ * are not read, not touched, and not dropped. That is a correctness rule before
+ * it is a cost one — dropping an entry because you listed a DIFFERENT workspace
+ * would be a bug, and scoping to the join makes it unrepresentable.
+ *
+ * Candidates are sorted by `t` DESCENDING before the ceiling applies, and the
+ * ordering is part of the contract. Store order (append order, oldest first) is
+ * the implementation a reader falls into without deciding, and its failure is
+ * the worst shape available: a creator with 70 stale entries and one live one
+ * spends all 64 reads on the oldest dead ones, is told their project has no
+ * known folder, and then compaction drops those 64 so the NEXT listing succeeds
+ * — an intermittent failure that heals itself, which is the hardest possible
+ * triage. Newest-first fails as "you have not touched this folder in a very long
+ * time", which is diagnosable.
+ *
+ * Presentation order and verification order are the same sort, applied once.
+ */
+export declare function joinLocations(entries: LocationEntry[], projectIds: string[], verify?: (dir: string, projectId: string) => boolean): JoinResult;

package/dist/lib/locations.js

@@ -0,0 +1,117 @@
+/**
+ * The read half of the location store: verify a candidate folder, and join the
+ * store against the listing's API rows.
+ *
+ * Kept out of `listProjects.ts` so the predicate is a pure function a human can
+ * reproduce with one `cat` and no CLI — which is the whole triage story for the
+ * report that will actually arrive ("it says it does not know where my project
+ * is, and I am looking at the folder").
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * At most this many folder checks per listing. 64 reads is ~1-3 ms against an
+ * API call the listing already spent 50-200 ms on. The ceiling exists so a
+ * pathological store — an agent looping `create` in generated folders — cannot
+ * turn a listing into a filesystem walk, and it FAILS TOWARD "unknown", never
+ * toward "here is a path we did not check", which is the only direction the
+ * verify-at-read rule permits.
+ */
+export const VERIFY_LIMIT = 64;
+/**
+ * Does `dir` still hold a binding naming `projectId`?
+ *
+ *   ENOENT                          → dead (deleted, moved, drive unmounted, unbound)
+ *   present but unparseable         → dead
+ *   present with no projectId       → dead
+ *   projectId !== the entry's       → dead (bound to a different project)
+ *   otherwise                       → live
+ *
+ * A DIRECT read, not `locateProjectBinding`'s upward walk. The store recorded
+ * the directory that HOLDS the file, and walking upward from it would let a
+ * PARENT repo's binding validate a child folder the store should have dropped —
+ * answering with a plausible-but-wrong path, which is precisely what
+ * verify-at-read exists to prevent.
+ *
+ * Exactly one `readFile` of an ~80-byte file. Not a `stat` then a read: ENOENT
+ * is the negative answer.
+ */
+export function verifyLocation(dir, projectId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(dir, ".vincentt", "project.json"), "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return false;
+        return parsed.projectId === projectId;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Join the store against the ids in this listing, verify newest-first, and
+ * report what survives.
+ *
+ * Verification is SCOPED TO THE JOIN: entries for projects in another workspace
+ * are not read, not touched, and not dropped. That is a correctness rule before
+ * it is a cost one — dropping an entry because you listed a DIFFERENT workspace
+ * would be a bug, and scoping to the join makes it unrepresentable.
+ *
+ * Candidates are sorted by `t` DESCENDING before the ceiling applies, and the
+ * ordering is part of the contract. Store order (append order, oldest first) is
+ * the implementation a reader falls into without deciding, and its failure is
+ * the worst shape available: a creator with 70 stale entries and one live one
+ * spends all 64 reads on the oldest dead ones, is told their project has no
+ * known folder, and then compaction drops those 64 so the NEXT listing succeeds
+ * — an intermittent failure that heals itself, which is the hardest possible
+ * triage. Newest-first fails as "you have not touched this folder in a very long
+ * time", which is diagnosable.
+ *
+ * Presentation order and verification order are the same sort, applied once.
+ */
+export function joinLocations(entries, projectIds, verify = verifyLocation) {
+    // Exact equality on the FULL project id — never a prefix or a substring. Ids
+    // are 12-char opaque hex, and a truncating join looks reasonable to a future
+    // reader while silently leaking another tenant's folder into this listing.
+    const inScope = new Set(projectIds);
+    const candidates = [];
+    const untouched = [];
+    for (const e of entries) {
+        if (inScope.has(e.p))
+            candidates.push(e);
+        else
+            untouched.push(e);
+    }
+    const ordered = [...candidates].sort((a, b) => (b.t ?? "").localeCompare(a.t ?? ""));
+    const byProject = new Map();
+    const live = [];
+    let reads = 0;
+    const dead = new Set();
+    for (const e of ordered) {
+        if (reads >= VERIFY_LIMIT)
+            break;
+        reads += 1;
+        if (verify(e.d, e.p)) {
+            live.push(e);
+            const at = byProject.get(e.p);
+            if (at)
+                at.push(e.d);
+            else
+                byProject.set(e.p, [e.d]);
+        }
+        else {
+            dead.add(e);
+        }
+    }
+    // Beyond the ceiling an entry is neither reported nor dropped: it was not
+    // checked, and dropping what you did not check is the one thing the ceiling
+    // must not do.
+    const survivors = entries.filter((e) => !dead.has(e));
+    return { byProject, survivors, dropped: dead.size > 0 };
+}

package/dist/shared/config.js

@@ -12,6 +12,7 @@ import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { recordLocation } from "./recordLocation.js";
 export const MACHINE_CONFIG_PATH = path.join(os.homedir(), ".vincentt", "config.json");
 const BINDING_DIR = ".vincentt";
 const BINDING_FILE = "project.json";
@@ -137,8 +138,12 @@ export async function locateProjectBinding(cwd) {
     let dir = path.resolve(cwd);
     for (;;) {
         const binding = await readJsonIfExists(projectBindingPath(dir));
-        if (binding)
+        if (binding) {
+            // The ONE success return, so every verb that resolves a binding records
+            // its folder without a per-verb checklist. Best-effort and synchronous.
+            recordLocation(binding.projectId, dir);
             return { binding, dir, path: projectBindingPath(dir) };
+        }
         if (await isGitRoot(dir))
             return undefined;
         const parent = path.dirname(dir);
@@ -165,6 +170,10 @@ export async function writeProjectBinding(cwd, binding) {
     const p = projectBindingPath(cwd);
     await fs.writeFile(p, JSON.stringify(binding, null, 2) + "\n", "utf8");
     await ensureGitignored(cwd, `${BINDING_DIR}/`);
+    // `create` and `link` WRITE a binding rather than resolve one, so they never
+    // pass through the resolver's hook. Between the two, every way a folder comes
+    // to name a project records that folder.
+    recordLocation(binding.projectId, path.resolve(cwd));
     return p;
 }
 /** Remove the per-tree binding so the directory can be re-created/rebound. */

package/dist/shared/locationStore.d.ts

@@ -0,0 +1,82 @@
+export interface LocationEntry {
+    /** The project id — the join key against the listing's API rows. */
+    p: string;
+    /**
+     * The absolute directory holding `.vincentt/project.json`, REALPATH-resolved.
+     * Not the cwd: the cwd may be a subdirectory of it.
+     */
+    d: string;
+    /** ISO8601 UTC, when the entry was last written. The presentation tiebreak. */
+    t: string;
+}
+/**
+ * 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 declare 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 declare function locationsPath(): string;
+/** The store's whole surface, so the listing can be driven with no filesystem. */
+export interface LocationStore {
+    read(): LocationEntry[];
+    append(entry: LocationEntry): void;
+    compact(keep: LocationEntry[]): void;
+}
+/**
+ * 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 declare function readLocations(): LocationEntry[];
+/**
+ * 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 declare function needsLeadingNewline(file: string): boolean;
+/**
+ * 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 declare function appendLocation(entry: LocationEntry): void;
+/**
+ * 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 declare function compactEntries(entries: LocationEntry[]): LocationEntry[];
+/**
+ * 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 declare function compactLocations(keep: LocationEntry[]): void;
+/** The real store, reading and writing the creator's own home directory. */
+export declare const fileLocationStore: LocationStore;

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.13.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",