@vincentt-xr/cli 0.22.0 → 0.23.0

package/dist/editor/reads.js

@@ -0,0 +1,269 @@
+// `vincentt editor --selection [--json]` and `--status --json`: read the editor's local files
+// and print them. A read flag never talks to the running app; when none runs for the folder it
+// says so on stderr, still prints one JSON object on stdout, and exits 1. A file in a schema
+// major this CLI does not know is refused whole ("too new"), never printed in part.
+import { pidAlive } from "./app.js";
+import { NOT_RUNNING, tooNew } from "./copy.js";
+import { realpath } from "node:fs/promises";
+import { lastHandoff } from "./handoffs.js";
+import { parsePidFile, readLocalFile, readLocalFileStat, } from "./localFiles.js";
+import { agentSafe, agentSafeValue } from "./text.js";
+export const SELECTION_SCHEMA = "vincentt.editor-selection/1";
+export const STATE_SCHEMA = "vincentt.editor-state/1";
+/**
+ * True when the code `pid` is running meets the requirement, from any path. Checked on the
+ * running process itself, so no path the OS reports for it is trusted.
+ */
+export async function isVerifiedEditor(pid, p) {
+    const verdict = await p.system.verifyPid(pid, p.requirement).catch(() => undefined);
+    return verdict?.ok === true;
+}
+/** `ps` reports whole seconds and the app writes whole seconds. */
+const START_SLACK_MS = 1_000;
+/**
+ * True when the process now holding `pid` was already running when the record was written. A
+ * process that started after `startedAt` reused the pid of the editor that wrote it.
+ */
+export function startedBeforeRecord(processStart, rec) {
+    return processStart !== undefined && processStart <= rec.startedAt + START_SLACK_MS;
+}
+/** The editor recorded in `pid`, when that process is live, is that record's process, and is a verified editor. */
+export async function runningEditor(root, p) {
+    const text = await readLocalFile(root, "pid").catch(() => undefined);
+    const rec = text === undefined ? undefined : parsePidFile(text);
+    if (rec === undefined || !(p.isAlive ?? pidAlive)(rec.pid))
+        return undefined;
+    const start = await p.system.startTime(rec.pid).catch(() => undefined);
+    if (!startedBeforeRecord(start, rec))
+        return undefined;
+    return (await isVerifiedEditor(rec.pid, p)) ? rec : undefined;
+}
+/** Whether `schema` is `<family>/1`, a later major of the family, or something else. */
+export function schemaMajor(schema, family) {
+    if (typeof schema !== "string")
+        return "foreign";
+    const m = /^(.+)\/(\d+)$/.exec(schema);
+    if (m === null || m[1] !== family)
+        return "foreign";
+    const major = Number(m[2]);
+    if (major === 1)
+        return "known";
+    return major > 1 ? { newer: schema } : "foreign";
+}
+const SELECTION_FAMILY = "vincentt.editor-selection";
+const STATE_FAMILY = "vincentt.editor-state";
+async function readJson(root, name) {
+    return (await readJsonStat(root, name))?.value;
+}
+async function readJsonStat(root, name) {
+    const file = await readLocalFileStat(root, name).catch(() => undefined);
+    if (file === undefined)
+        return undefined;
+    try {
+        const v = JSON.parse(file.text);
+        return typeof v === "object" && v !== null && !Array.isArray(v)
+            ? { value: v, mtimeMs: file.mtimeMs }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A snapshot belongs to the running editor when it carries the pid record's session and, when it
+ * names a pid, that pid.
+ */
+function sameEditor(file, rec) {
+    if (typeof file.session !== "string" || file.session !== rec.session)
+        return false;
+    return typeof file.pid !== "number" || file.pid === rec.pid;
+}
+/** Fields the CLI states itself; file content never supplies them. */
+const RESERVED_STATE_KEYS = ["schema", "running", "pid", "session"];
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+/** A string field, sanitised; anything that is not a string reads as empty. */
+const str = (v, max) => typeof v === "string" ? agentSafe(v, max) : "";
+/** The selection as the agent may read it: an allowlist of fields, every string sanitised. */
+export function shapeSelection(sel) {
+    if (typeof sel !== "object" || sel === null)
+        return null;
+    const s = sel;
+    const src = (typeof s.source === "object" && s.source !== null ? s.source : {});
+    const values = Array.isArray(s.values) ? s.values : [];
+    return {
+        objectKey: str(s.objectKey, 400),
+        label: str(s.label, 200),
+        type: str(s.type, 80),
+        kind: str(s.kind, 20),
+        source: {
+            file: str(src.file, 400),
+            line: num(src.line) ?? null,
+            column: num(src.column) ?? null,
+        },
+        values: values.slice(0, 256).map((raw) => {
+            const v = (typeof raw === "object" && raw !== null ? raw : {});
+            const out = {
+                path: str(v.path, 200),
+                type: str(v.type, 20),
+                value: agentSafeValue(v.value),
+            };
+            if (typeof v.unit === "string")
+                out.unit = agentSafe(v.unit, 10);
+            out.editable =
+                v.editable === true
+                    ? true
+                    : agentSafeValue(v.editable ?? { readonly: "unsupported" }, 40);
+            if (typeof v.decl === "string")
+                out.decl = agentSafe(v.decl, 200);
+            if (num(v.sharedBy) !== undefined)
+                out.sharedBy = num(v.sharedBy);
+            return out;
+        }),
+    };
+}
+function tooNewResult(schema) {
+    return { stdout: [], stderr: tooNew(schema), exitCode: 1, reason: "too_new" };
+}
+export async function selectionRead(root, json, p) {
+    const file = await readJson(root, "selection.json");
+    const major = schemaMajor(file?.schema, SELECTION_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const rec = await runningEditor(root, p);
+    if (rec === undefined) {
+        return {
+            stdout: json
+                ? [JSON.stringify({ schema: SELECTION_SCHEMA, running: false, selection: null })]
+                : [],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    const selection = file && major === "known" && sameEditor(file, rec)
+        ? shapeSelection(file.selection)
+        : null;
+    if (json) {
+        return {
+            stdout: [JSON.stringify({ schema: SELECTION_SCHEMA, running: true, selection })],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    return { stdout: humanSelection(selection), stderr: [], exitCode: 0 };
+}
+function display(v) {
+    if (Array.isArray(v))
+        return v.map(display).join(", ");
+    if (v !== null && typeof v === "object") {
+        return Object.entries(v)
+            .map(([k, x]) => `${k}: ${display(x)}`)
+            .join(", ");
+    }
+    return String(v);
+}
+export function humanSelection(sel) {
+    if (sel === null)
+        return ["Nothing is selected in the editor."];
+    const src = sel.source;
+    const kind = sel.kind === "sdk" ? " (Vincentt SDK)" : "";
+    const out = [
+        `${sel.label}  ${sel.type}${kind}  ${src.file}${src.line !== null ? `:${src.line}` : ""}`,
+    ];
+    for (const v of sel.values) {
+        const unit = typeof v.unit === "string" ? ` ${v.unit}` : "";
+        const ro = v.editable === true
+            ? ""
+            : `   (read-only: ${display(v.editable?.readonly ?? "unsupported")})`;
+        out.push(`  ${String(v.path).padEnd(26)} ${display(v.value)}${unit}${ro}`);
+    }
+    return out;
+}
+const APP_VERSION = /^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]{1,32})?$/;
+const LAST_OPEN = /^(opened|awaiting_trust|cancelled|refused:[A-Za-z0-9_-]{1,16})$/;
+/**
+ * `app` as the agent may read it: exactly `{version, lastOpen}`, each null unless it is one of
+ * the shapes the app writes. `trustLastOpen` false nulls `lastOpen` whatever the file says.
+ */
+export function shapeApp(app, trustLastOpen) {
+    const a = (typeof app === "object" && app !== null ? app : {});
+    const version = typeof a.version === "string" && APP_VERSION.test(a.version) ? a.version : null;
+    const lastOpen = trustLastOpen && typeof a.lastOpen === "string" && LAST_OPEN.test(a.lastOpen)
+        ? a.lastOpen
+        : null;
+    return { version, lastOpen };
+}
+/**
+ * A state file no running editor vouches for is believed about the last open only when it
+ * changed after this machine's last hand-off of this folder: a committed or copied state.json
+ * predates it, and a folder never handed over has no open to report. A time in the future (an
+ * unpacked archive keeps whatever mtime it was given) is not after anything.
+ */
+async function lastOpenTrusted(root, mtimeMs) {
+    const project = await realpath(root).catch(() => undefined);
+    if (project === undefined)
+        return false;
+    const at = await lastHandoff(project).catch(() => undefined);
+    return at !== undefined && mtimeMs > at && mtimeMs <= Date.now() + 5_000;
+}
+function appField(file, trustLastOpen) {
+    return file !== undefined && file.app !== undefined
+        ? { app: shapeApp(file.app, trustLastOpen) }
+        : {};
+}
+export async function statusRead(root, p) {
+    const read = await readJsonStat(root, "state.json");
+    const file = read?.value;
+    const major = schemaMajor(file?.schema, STATE_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const known = major === "known" ? file : undefined;
+    const rec = await runningEditor(root, p);
+    if (known && rec && known.running === true && sameEditor(known, rec)) {
+        // The running, verified editor wrote this file. Sanitised first, so a key that only
+        // becomes `pid` once its control characters are stripped is removed too.
+        const shaped = agentSafeValue(known, 400);
+        for (const k of RESERVED_STATE_KEYS)
+            delete shaped[k];
+        if (known.app !== undefined)
+            shaped.app = shapeApp(known.app, true);
+        return {
+            stdout: [
+                JSON.stringify({ schema: STATE_SCHEMA, running: true, pid: rec.pid, ...shaped }),
+            ],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    const trusted = known !== undefined &&
+        read !== undefined &&
+        (await lastOpenTrusted(root, read.mtimeMs));
+    if (rec === undefined) {
+        // A refused or cancelled open leaves no running editor behind, so the outcome of the last
+        // hand-off is reported here too, when the file is believed.
+        return {
+            stdout: [
+                JSON.stringify({
+                    schema: STATE_SCHEMA,
+                    running: false,
+                    ...appField(known, trusted),
+                }),
+            ],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    return {
+        stdout: [
+            JSON.stringify({
+                schema: STATE_SCHEMA,
+                running: true,
+                pid: rec.pid,
+                ...appField(known, trusted),
+            }),
+        ],
+        stderr: [],
+        exitCode: 0,
+    };
+}

package/dist/editor/text.d.ts

@@ -0,0 +1,7 @@
+export declare function isUnsafeChar(ch: string): boolean;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export declare function agentSafe(s: string, max: number): string;
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export declare const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export declare function agentSafeValue(v: unknown, max?: number, depth?: number): unknown;

package/dist/editor/text.js

@@ -0,0 +1,58 @@
+// Text that reaches the creator's terminal or their agent from the editor's files. The app
+// already strips these characters (B-F21-8); the CLI strips them again because it is the last
+// step before a shell, and a stale or planted file never passed the app.
+// C0 and C1 controls, DEL, the Arabic letter mark, zero-width characters and direction marks,
+// line and paragraph separators, bidi embeddings, overrides and isolates, the word joiner,
+// invisible operators, the byte order mark, the soft hyphen, the combining grapheme joiner,
+// the Mongolian vowel separator, variation selectors and tag characters. Code points rather
+// than a character class, so no bidi character sits in source.
+const UNSAFE = [
+    [0x0000, 0x001f],
+    [0x007f, 0x009f],
+    [0x00ad, 0x00ad],
+    [0x034f, 0x034f],
+    [0x061c, 0x061c],
+    [0x180e, 0x180e],
+    [0x200b, 0x200f],
+    [0x2028, 0x2029],
+    [0x2060, 0x2064],
+    [0xfe00, 0xfe0f],
+    [0xfeff, 0xfeff],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+    [0xe0000, 0xe007f],
+    [0xe0100, 0xe01ef],
+];
+export function isUnsafeChar(ch) {
+    const cp = ch.codePointAt(0) ?? 0;
+    return UNSAFE.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+// CSI and OSC sequences, removed whole so no `[31m` residue is left behind.
+// eslint-disable-next-line no-control-regex
+const ANSI_G = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u009b[0-?]*[ -/]*[@-~]/g;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export function agentSafe(s, max) {
+    return Array.from(s.replace(ANSI_G, ""))
+        .filter((ch) => !isUnsafeChar(ch))
+        .slice(0, max)
+        .join("");
+}
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export function agentSafeValue(v, max = 200, depth = 0) {
+    if (typeof v === "string")
+        return agentSafe(v, max);
+    if (depth >= MAX_DEPTH && v !== null && typeof v === "object")
+        return null;
+    if (Array.isArray(v))
+        return v.slice(0, 64).map((x) => agentSafeValue(x, max, depth + 1));
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const [k, x] of Object.entries(v).slice(0, 256)) {
+            out[agentSafe(k, 80)] = agentSafeValue(x, max, depth + 1);
+        }
+        return out;
+    }
+    return v;
+}

package/dist/editor/tools.d.ts

@@ -0,0 +1,5 @@
+export type Tool = "codesign" | "open" | "sw_vers" | "plutil" | "lsappinfo" | "ps";
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export declare function toolCandidates(tool: Tool, platform?: NodeJS.Platform): string[];
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export declare function toolPath(tool: Tool, platform?: NodeJS.Platform, exists?: (p: string) => boolean): string | undefined;

package/dist/editor/tools.js

@@ -0,0 +1,20 @@
+// The macOS tools the launcher runs, by absolute path only. A bare name would be resolved from
+// PATH, so a project (or anything earlier on PATH) could plant a `codesign` that answers "this
+// app is signed by Vincentt".
+import { existsSync } from "node:fs";
+const DARWIN = {
+    ps: ["/bin/ps"],
+    codesign: ["/usr/bin/codesign"],
+    open: ["/usr/bin/open"],
+    sw_vers: ["/usr/bin/sw_vers"],
+    plutil: ["/usr/bin/plutil"],
+    lsappinfo: ["/usr/bin/lsappinfo"],
+};
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export function toolCandidates(tool, platform = process.platform) {
+    return platform === "darwin" ? DARWIN[tool] : [];
+}
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export function toolPath(tool, platform = process.platform, exists = existsSync) {
+    return toolCandidates(tool, platform).find((p) => exists(p));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "3.0.0"
+    "@vincentt-xr/harness": "3.1.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",