@vincentt-xr/cli 0.21.0 → 0.23.0

package/dist/editor/copy.js

@@ -0,0 +1,95 @@
+// The `vincentt editor` screens (features/f21-visual-editor/mock/cli.md, C1 to C3). After a
+// non-zero exit the last line states what did not happen.
+import os from "node:os";
+import path from "node:path";
+import { agentSafe } from "./text.js";
+export const DOWNLOAD_URL = "https://vincentt.studio/editor";
+export const NOTHING_OPENED = "Nothing was opened.";
+export const NOT_RUNNING = "✗ No editor is running for this folder.";
+/** `~/Downloads/Vincentt Editor.app` for a path under the home folder. */
+export function tildePath(p, home = os.homedir()) {
+    const safe = agentSafe(p, 400);
+    if (home && (safe === home || safe.startsWith(home + "/"))) {
+        return "~" + safe.slice(home.length);
+    }
+    return safe;
+}
+export function sent(name) {
+    return `✓ Sent ${agentSafe(name, 80)} to Vincentt Editor.`;
+}
+export function notInstalled() {
+    return [
+        `✗ Vincentt Editor is not installed. Get it at ${DOWNLOAD_URL}`,
+        NOTHING_OPENED,
+    ];
+}
+/** `app` is the refused bundle; the copy names the folder it was found in. */
+export function badSignature(app) {
+    return [
+        `✗ The Vincentt Editor in ${tildePath(path.dirname(app))} is not signed by Vincentt, so the CLI will not open it.`,
+        `  Delete it and download it again from ${DOWNLOAD_URL}`,
+        NOTHING_OPENED,
+    ];
+}
+/** The copy on disk passes, but the one running from the same place does not. */
+export function runningCopyNotSigned() {
+    return [
+        "✗ The Vincentt Editor that is running is not signed by Vincentt, so the CLI will not open it.",
+        "  Quit the running Vincentt Editor, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+export function notMacos() {
+    return ["✗ Vincentt Editor runs on macOS only for now.", NOTHING_OPENED];
+}
+export function macosTooOld(version) {
+    return [
+        `✗ Vincentt Editor needs macOS 14 or later. This Mac has macOS ${agentSafe(version, 20)}.`,
+        NOTHING_OPENED,
+    ];
+}
+export function otherCopyRunning(bundlePath) {
+    return [
+        `✗ Another Vincentt Editor is running from ${tildePath(bundlePath)}.`,
+        "  Quit the other Vincentt Editor first, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+/** A flag the launcher had before it handed off to the app (`--port`, `--dev-url`). */
+export function removedFlag(flag) {
+    return [
+        `✗ ${flag} was removed. Vincentt Editor starts the preview itself.`,
+        "  Run:  vincentt editor",
+        NOTHING_OPENED,
+    ];
+}
+export function unknownFlag(flag) {
+    return [
+        `✗ vincentt editor has no option ${agentSafe(flag, 40)}.`,
+        "  Run:  vincentt editor   (or --selection --json, or --status --json)",
+        NOTHING_OPENED,
+    ];
+}
+export function strayArgument() {
+    return [
+        "✗ vincentt editor takes no folder name. Run it inside the project, or pass --dir <folder>.",
+        NOTHING_OPENED,
+    ];
+}
+export function bothReads() {
+    return ["✗ --selection and --status cannot be used together. Run one, then the other."];
+}
+export function openFailed() {
+    return [
+        "✗ macOS could not hand the folder to Vincentt Editor.",
+        "  Open Vincentt Editor from Applications, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+/** A local file written in a schema major this CLI does not know. */
+export function tooNew(schema) {
+    return [
+        `✗ Vincentt Editor wrote ${agentSafe(schema, 80)}, which is newer than this CLI reads.`,
+        "  Update the CLI:  npm install -g @vincentt-xr/cli@latest",
+    ];
+}

package/dist/editor/handoffs.d.ts

@@ -0,0 +1,12 @@
+/** Hand-off time (epoch ms) by project key. */
+export type Handoffs = Record<string, number>;
+/** Resolved per call: the home folder is the seam tests move. */
+export declare function handoffsPath(): string;
+/** The key a canonical project path is recorded under. */
+export declare function projectKey(project: string): string;
+/** Every recorded hand-off; empty when the file is absent, a link or unreadable. */
+export declare function readHandoffs(file?: string): Promise<Handoffs>;
+/** The last hand-off of `project` (a canonical path), or undefined when there was none. */
+export declare function lastHandoff(project: string, file?: string): Promise<number | undefined>;
+/** Records a hand-off of `project`, keeping the newest entries. Best-effort: never throws. */
+export declare function recordHandoff(project: string, at: number, file?: string): Promise<void>;

package/dist/editor/handoffs.js

@@ -0,0 +1,93 @@
+// When this CLI last handed each project folder to Vincentt Editor, kept in
+// ~/.vincentt/editor-handoffs.json. It is the CLI's own evidence that an open happened: a
+// project's `.vincentt/editor/state.json` can be committed and cloned, so an `app.lastOpen`
+// in it is believed only when the file changed after this machine's last hand-off.
+//
+// The file holds no folder paths: each entry is the SHA-256 of the canonical project path
+// mapped to the hand-off time. It is the CLI's, never the project's: written through a fresh
+// 0600 temp file and a rename, never through a link, size-capped, newest entries only.
+import { createHash } from "node:crypto";
+import { constants as fsc, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const FILE = "editor-handoffs.json";
+const MAX_ENTRIES = 50;
+const READ_CAP = 64 << 10;
+const KEY = /^[0-9a-f]{64}$/;
+/** Resolved per call: the home folder is the seam tests move. */
+export function handoffsPath() {
+    return path.join(os.homedir(), ".vincentt", FILE);
+}
+/** The key a canonical project path is recorded under. */
+export function projectKey(project) {
+    return createHash("sha256").update(project).digest("hex");
+}
+function parse(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (KEY.test(k) && typeof v === "number" && Number.isFinite(v))
+            out[k] = v;
+    }
+    return out;
+}
+/** Every recorded hand-off; empty when the file is absent, a link or unreadable. */
+export async function readHandoffs(file = handoffsPath()) {
+    let handle;
+    try {
+        handle = await fs.open(file, fsc.O_RDONLY | (fsc.O_NOFOLLOW ?? 0) | fsc.O_NONBLOCK);
+    }
+    catch {
+        return {};
+    }
+    try {
+        const st = await handle.stat();
+        if (!st.isFile() || st.size > READ_CAP)
+            return {};
+        const buf = Buffer.alloc(st.size);
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        return parse(buf.subarray(0, bytesRead).toString("utf8"));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The last hand-off of `project` (a canonical path), or undefined when there was none. */
+export async function lastHandoff(project, file = handoffsPath()) {
+    return (await readHandoffs(file))[projectKey(project)];
+}
+/** Records a hand-off of `project`, keeping the newest entries. Best-effort: never throws. */
+export async function recordHandoff(project, at, file = handoffsPath()) {
+    try {
+        const dir = path.dirname(file);
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const st = await fs.lstat(dir);
+        if (!st.isDirectory())
+            return;
+        const all = { ...(await readHandoffs(file)), [projectKey(project)]: at };
+        const kept = Object.fromEntries(Object.entries(all)
+            .sort((a, b) => a[1] - b[1])
+            .slice(-MAX_ENTRIES));
+        const tmp = path.join(dir, `.${FILE}.${process.pid}.tmp`);
+        await fs.rm(tmp, { force: true });
+        const handle = await fs.open(tmp, fsc.O_WRONLY | fsc.O_CREAT | fsc.O_EXCL | (fsc.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(kept) + "\n");
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(tmp, file);
+    }
+    catch {
+        // A missing record only makes `--status` report `lastOpen: null`, the safe direction.
+    }
+}

package/dist/editor/launcher.d.ts

@@ -0,0 +1,86 @@
+import { type MacSystem } from "./app.js";
+export { EDITOR_REQUIREMENT } from "./app.js";
+export declare const OPEN_SCHEMA = "vincentt.editor-open/1";
+/** Why the launcher did not hand the folder over; the first four are `--json`'s `reason`. */
+export type LaunchReason = "not_installed" | "bad_signature" | "unsupported_os" | "other_copy_running" | "open_failed";
+/** Every reason the f7 journal may record for `editor` (B-F7-1: a closed set, no values). */
+export type EditorReason = LaunchReason | "bad_arguments" | "not_running" | "too_new";
+/**
+ * Fixed in this module. Tests pass replacements through `editorCommand`'s last argument; no
+ * environment variable, config key or project file changes any of them.
+ */
+export interface LauncherParams {
+    platform: NodeJS.Platform;
+    /** Searched in order; the first folder holding the app decides, pass or fail. */
+    searchRoots: readonly string[];
+    requirement: string;
+    bundleName: string;
+    bundleId: string;
+    /** The macOS product version; read from the OS when absent. */
+    osVersion?: string;
+    system: MacSystem;
+}
+export type LauncherOverrides = Partial<Omit<LauncherParams, "system">> & {
+    system?: Partial<MacSystem>;
+};
+export declare function defaultParams(): LauncherParams;
+export type EditorArgs = {
+    kind: "launch";
+    json: boolean;
+} | {
+    kind: "selection";
+    json: boolean;
+} | {
+    kind: "status";
+} | {
+    kind: "refuse";
+    lines: string[];
+};
+/** `args` is everything after `editor`. */
+export declare function parseEditorArgs(args: readonly string[]): EditorArgs;
+export interface EditorIo {
+    /** stdout, one line. */
+    out: (line: string) => void;
+    /** stderr, one line. */
+    err: (line: string) => void;
+}
+export interface EditorRun {
+    exitCode: 0 | 1;
+    reason?: EditorReason;
+}
+/**
+ * `args` is everything after `editor`; `root` is the project root resolved as for every verb.
+ * `overrides` replaces module parameters, for tests only.
+ */
+export declare function editorCommand(args: readonly string[], root: string, io: EditorIo, overrides?: LauncherOverrides): Promise<EditorRun>;
+/** The module parameters a test may replace, flat. */
+export interface VerbParams extends Partial<Omit<LauncherParams, "system">> {
+    open?: MacSystem["open"] | ((app: string, folder: string) => void);
+    runningCopies?: MacSystem["runningCopies"];
+    verify?: MacSystem["verify"];
+    verifyPid?: MacSystem["verifyPid"];
+    startTime?: MacSystem["startTime"];
+}
+export interface VerbResult extends EditorRun {
+    stdout: string[];
+    stderr: string[];
+}
+/**
+ * The verb as the CLI runs it: the project root is resolved from `cwd` as for every verb (the
+ * binding's folder, else `cwd`), and the output is returned rather than printed.
+ */
+export declare function editorVerb(args: readonly string[], cwd: string, params?: VerbParams): Promise<VerbResult>;
+type Found = {
+    kind: "found";
+    app: string;
+} | {
+    kind: "refused";
+    app: string;
+    detail: string;
+};
+/**
+ * The app in the first search root that holds anything under its name; never the next one. A
+ * link there is refused (codesign would verify wherever it points), and the copy must resolve
+ * to a bundle directly inside that root; the resolved path is the one verified and opened.
+ */
+export declare function findApp(searchRoots: readonly string[], bundleName: string): Promise<Found | undefined>;

package/dist/editor/launcher.js

@@ -0,0 +1,255 @@
+// `vincentt editor [--json] | --selection [--json] | --status --json`
+// (features/f21-visual-editor/implementation.md, Launcher; transcripts in mock/cli.md C1 to C3).
+//
+// Not long-running and makes no network call: it checks the OS, finds the installed app in
+// /Applications then ~/Applications, verifies its designated requirement, refuses when another
+// copy is running from a different path, hands the project folder over with `open -a` and
+// exits. It never waits on the app; what the app did with the folder is `app.lastOpen` in
+// `--status --json`. Exit codes 0 and 1 only.
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { defaultSearchRoots, EDITOR_BUNDLE_ID, EDITOR_BUNDLE_NAME, EDITOR_REQUIREMENT, macosMajor, macSystem, MIN_MACOS_MAJOR, samePath, } from "./app.js";
+import { locateProjectBinding } from "../shared/config.js";
+import * as copy from "./copy.js";
+import { recordHandoff } from "./handoffs.js";
+import { agentSafe } from "./text.js";
+import { selectionRead, statusRead } from "./reads.js";
+export { EDITOR_REQUIREMENT } from "./app.js";
+export const OPEN_SCHEMA = "vincentt.editor-open/1";
+export function defaultParams() {
+    return {
+        platform: process.platform,
+        searchRoots: defaultSearchRoots(),
+        requirement: EDITOR_REQUIREMENT,
+        bundleName: EDITOR_BUNDLE_NAME,
+        bundleId: EDITOR_BUNDLE_ID,
+        system: macSystem(),
+    };
+}
+/** Flags the launcher had while it owned the session; each names its own removal (C1e). */
+const REMOVED_FLAGS = ["--port", "--dev-url"];
+const BOOLEAN = new Set(["--json", "--selection", "--status", "--allow-custom-api"]);
+const WITH_VALUE = new Set(["--dir"]);
+/** `args` is everything after `editor`. */
+export function parseEditorArgs(args) {
+    const names = args.filter((a) => a.startsWith("-")).map((a) => a.split("=")[0]);
+    const removed = names.find((n) => REMOVED_FLAGS.includes(n));
+    if (removed !== undefined)
+        return { kind: "refuse", lines: copy.removedFlag(removed) };
+    const seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("-"))
+            return { kind: "refuse", lines: copy.strayArgument() };
+        const name = a.split("=")[0];
+        if (WITH_VALUE.has(name)) {
+            if (!a.includes("="))
+                i++;
+            continue;
+        }
+        if (!BOOLEAN.has(a))
+            return { kind: "refuse", lines: copy.unknownFlag(name) };
+        seen.add(a);
+    }
+    const json = seen.has("--json");
+    if (seen.has("--selection") && seen.has("--status"))
+        return { kind: "refuse", lines: copy.bothReads() };
+    if (seen.has("--status"))
+        return { kind: "status" };
+    if (seen.has("--selection"))
+        return { kind: "selection", json };
+    return { kind: "launch", json };
+}
+/**
+ * `args` is everything after `editor`; `root` is the project root resolved as for every verb.
+ * `overrides` replaces module parameters, for tests only.
+ */
+export async function editorCommand(args, root, io, overrides = {}) {
+    const parsed = parseEditorArgs(args);
+    if (parsed.kind === "refuse") {
+        parsed.lines.forEach(has(args, "--json") ? io.err : io.out);
+        return { exitCode: 1, reason: "bad_arguments" };
+    }
+    const base = defaultParams();
+    const p = {
+        ...base,
+        ...overrides,
+        system: { ...base.system, ...overrides.system },
+    };
+    if (parsed.kind === "launch")
+        return launch(root, parsed.json, io, p);
+    const read = parsed.kind === "status"
+        ? await statusRead(root, p)
+        : await selectionRead(root, parsed.json, p);
+    read.stdout.forEach(io.out);
+    read.stderr.forEach(io.err);
+    return { exitCode: read.exitCode === 0 ? 0 : 1, reason: read.reason };
+}
+function has(args, flag) {
+    return args.includes(flag);
+}
+/**
+ * The verb as the CLI runs it: the project root is resolved from `cwd` as for every verb (the
+ * binding's folder, else `cwd`), and the output is returned rather than printed.
+ */
+export async function editorVerb(args, cwd, params = {}) {
+    const { open, runningCopies, verify, verifyPid, startTime, ...rest } = params;
+    const system = {};
+    if (open)
+        system.open = async (app, folder) => void (await open(app, folder));
+    if (runningCopies)
+        system.runningCopies = runningCopies;
+    if (verify)
+        system.verify = verify;
+    if (verifyPid)
+        system.verifyPid = verifyPid;
+    if (startTime)
+        system.startTime = startTime;
+    const root = (await locateProjectBinding(cwd))?.dir ?? cwd;
+    const stdout = [];
+    const stderr = [];
+    const run = await editorCommand(args, root, { out: (l) => stdout.push(l), err: (l) => stderr.push(l) }, { ...rest, system });
+    return { ...run, stdout, stderr };
+}
+async function launch(root, json, io, p) {
+    const outcome = await decide(root, p);
+    const say = json ? io.err : io.out;
+    // Paths and codesign's words come from the file system and other programs: every string an
+    // agent reads is sanitised like the editor's own files.
+    const safe = (s) => agentSafe(s, 400);
+    if (outcome.handedOff) {
+        if (json) {
+            io.out(JSON.stringify({
+                schema: OPEN_SCHEMA,
+                handedOff: true,
+                project: safe(outcome.project),
+                app: safe(outcome.app),
+                appVersion: outcome.appVersion === null ? null : agentSafe(outcome.appVersion, 40),
+            }));
+        }
+        say(copy.sent(path.basename(outcome.project)));
+        return { exitCode: 0 };
+    }
+    if (json) {
+        io.out(JSON.stringify({
+            schema: OPEN_SCHEMA,
+            handedOff: false,
+            reason: outcome.reason,
+            ...(outcome.app === undefined ? {} : { app: safe(outcome.app) }),
+            ...(outcome.detail === undefined ? {} : { detail: safe(outcome.detail) }),
+        }));
+    }
+    outcome.lines.forEach(say);
+    return { exitCode: 1, reason: outcome.reason };
+}
+async function decide(root, p) {
+    if (p.platform !== "darwin")
+        return { handedOff: false, reason: "unsupported_os", lines: copy.notMacos() };
+    // Before the app is looked for, so nobody is sent to download an app that will not open.
+    const version = p.osVersion ?? (await p.system.osVersion().catch(() => undefined));
+    const major = macosMajor(version);
+    if (version !== undefined && major !== undefined && major < MIN_MACOS_MAJOR) {
+        return {
+            handedOff: false,
+            reason: "unsupported_os",
+            lines: copy.macosTooOld(version),
+            detail: `macOS ${version}`,
+        };
+    }
+    const found = await findApp(p.searchRoots, p.bundleName);
+    if (found === undefined)
+        return { handedOff: false, reason: "not_installed", lines: copy.notInstalled() };
+    if (found.kind === "refused") {
+        return {
+            handedOff: false,
+            reason: "bad_signature",
+            lines: copy.badSignature(found.app),
+            app: found.app,
+            detail: found.detail,
+        };
+    }
+    const app = found.app;
+    const verdict = await p.system.verify(app, p.requirement);
+    if (!verdict.ok) {
+        return {
+            handedOff: false,
+            reason: "bad_signature",
+            lines: copy.badSignature(app),
+            app,
+            detail: verdict.detail,
+        };
+    }
+    // `open -a` delivers the folder to whichever copy is running, so every running copy is
+    // checked: one at another path is refused, and one at this path must be running code that
+    // meets the requirement (the bundle on disk can differ from what was launched).
+    const copies = await p.system.runningCopies(p.bundleId).catch(() => undefined);
+    if (copies === undefined) {
+        return {
+            handedOff: false,
+            reason: "open_failed",
+            lines: copy.openFailed(),
+            app,
+            detail: "could not list running copies",
+        };
+    }
+    for (const running of copies) {
+        if (!(await samePath(running.bundlePath, app))) {
+            return {
+                handedOff: false,
+                reason: "other_copy_running",
+                lines: copy.otherCopyRunning(running.bundlePath),
+                app,
+                detail: running.bundlePath,
+            };
+        }
+        const live = await p.system.verifyPid(running.pid, p.requirement).catch(() => ({
+            ok: false,
+            detail: "codesign could not check the running app",
+        }));
+        if (!live.ok) {
+            return {
+                handedOff: false,
+                reason: "bad_signature",
+                lines: copy.runningCopyNotSigned(),
+                app,
+                detail: live.detail,
+            };
+        }
+    }
+    const project = await realpath(root).catch(() => path.resolve(root));
+    const { version: appVersion } = await p.system
+        .bundleInfo(app)
+        .catch(() => ({ version: undefined }));
+    // Taken before `open`: the app can write state.json before `open` returns, and a state file
+    // is believed only when it changed after this time.
+    const at = Date.now();
+    try {
+        await p.system.open(app, project);
+    }
+    catch {
+        return { handedOff: false, reason: "open_failed", lines: copy.openFailed(), app };
+    }
+    await recordHandoff(project, at);
+    return { handedOff: true, project, app, appVersion: appVersion ?? null };
+}
+/**
+ * The app in the first search root that holds anything under its name; never the next one. A
+ * link there is refused (codesign would verify wherever it points), and the copy must resolve
+ * to a bundle directly inside that root; the resolved path is the one verified and opened.
+ */
+export async function findApp(searchRoots, bundleName) {
+    for (const dir of searchRoots) {
+        const candidate = path.join(dir, bundleName);
+        const st = await lstat(candidate).catch(() => undefined);
+        if (st === undefined)
+            continue;
+        if (st.isSymbolicLink())
+            return { kind: "refused", app: candidate, detail: "the app is a link" };
+        const real = await realpath(candidate).catch(() => undefined);
+        const root = await realpath(dir).catch(() => undefined);
+        if (real === undefined || root === undefined || path.dirname(real) !== root)
+            return { kind: "refused", app: candidate, detail: "the app is not in its folder" };
+        return { kind: "found", app: real };
+    }
+    return undefined;
+}

package/dist/editor/localFiles.d.ts

@@ -0,0 +1,31 @@
+export declare const EDITOR_DIR = ".vincentt/editor";
+export declare class UnsafeLocalFile extends Error {
+    readonly rel: string;
+    constructor(rel: string, why: string);
+}
+/**
+ * `.vincentt` and `.vincentt/editor` are real folders or absent. A link or another file type in
+ * their place throws, naming it.
+ */
+export declare function checkEditorDir(root: string): Promise<"absent" | "ok">;
+/**
+ * One local file's text, or undefined when it does not exist. Opened no-follow and
+ * non-blocking (a FIFO cannot park the read), then checked on the open descriptor.
+ */
+export declare function readLocalFile(root: string, name: "pid" | "selection.json" | "state.json"): Promise<string | undefined>;
+/** As `readLocalFile`, with the file's modification time from the same descriptor. */
+export declare function readLocalFileStat(root: string, name: "pid" | "selection.json" | "state.json"): Promise<{
+    text: string;
+    mtimeMs: number;
+} | undefined>;
+export interface PidRecord {
+    pid: number;
+    session: string;
+    /** When the app wrote the record, epoch ms. */
+    startedAt: number;
+}
+/**
+ * The app writes `{"pid","session","startedAt"}`. A record missing any of them (a bare pid, a
+ * null session, an unparseable time) is not a record.
+ */
+export declare function parsePidFile(text: string): PidRecord | undefined;

package/dist/editor/localFiles.js

@@ -0,0 +1,100 @@
+// The editor's local files under `.vincentt/editor/`, as the CLI reads them. The app writes
+// them; the CLI only reads `pid`, `selection.json` and `state.json`, and reads the way the app
+// writes: never through a link, only from a regular file, size-capped (B-F21-8).
+import { constants as fsc, promises as fs } from "node:fs";
+import path from "node:path";
+export const EDITOR_DIR = ".vincentt/editor";
+const READ_CAP = 4 << 20;
+export class UnsafeLocalFile extends Error {
+    rel;
+    constructor(rel, why) {
+        super(`${rel} ${why}`);
+        this.rel = rel;
+        this.name = "UnsafeLocalFile";
+    }
+}
+/**
+ * `.vincentt` and `.vincentt/editor` are real folders or absent. A link or another file type in
+ * their place throws, naming it.
+ */
+export async function checkEditorDir(root) {
+    for (const rel of [".vincentt", EDITOR_DIR]) {
+        let st;
+        try {
+            st = await fs.lstat(path.join(root, ...rel.split("/")));
+        }
+        catch {
+            return "absent";
+        }
+        if (st.isSymbolicLink())
+            throw new UnsafeLocalFile(rel, "is a link");
+        if (!st.isDirectory())
+            throw new UnsafeLocalFile(rel, "is not a folder");
+    }
+    return "ok";
+}
+/**
+ * One local file's text, or undefined when it does not exist. Opened no-follow and
+ * non-blocking (a FIFO cannot park the read), then checked on the open descriptor.
+ */
+export async function readLocalFile(root, name) {
+    return (await readLocalFileStat(root, name))?.text;
+}
+/** As `readLocalFile`, with the file's modification time from the same descriptor. */
+export async function readLocalFileStat(root, name) {
+    if ((await checkEditorDir(root)) === "absent")
+        return undefined;
+    const rel = `${EDITOR_DIR}/${name}`;
+    const flags = fsc.O_RDONLY |
+        (fsc.O_NOFOLLOW ?? 0) |
+        (process.platform === "win32" ? 0 : fsc.O_NONBLOCK);
+    let handle;
+    try {
+        handle = await fs.open(path.join(root, ...rel.split("/")), flags);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return undefined;
+        if (code === "ELOOP" || code === "EMLINK")
+            throw new UnsafeLocalFile(rel, "is a link");
+        throw err;
+    }
+    try {
+        const st = await handle.stat();
+        if (!st.isFile())
+            throw new UnsafeLocalFile(rel, "is not a regular file");
+        if (st.size > READ_CAP)
+            throw new UnsafeLocalFile(rel, "is too large");
+        const buf = Buffer.alloc(Math.min(st.size, READ_CAP));
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        return { text: buf.subarray(0, bytesRead).toString("utf8"), mtimeMs: st.mtimeMs };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * The app writes `{"pid","session","startedAt"}`. A record missing any of them (a bare pid, a
+ * null session, an unparseable time) is not a record.
+ */
+export function parsePidFile(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    if (typeof o.pid !== "number" || !Number.isInteger(o.pid) || o.pid <= 0)
+        return undefined;
+    if (typeof o.session !== "string" || o.session === "")
+        return undefined;
+    const startedAt = typeof o.startedAt === "string" ? Date.parse(o.startedAt) : NaN;
+    if (!Number.isFinite(startedAt))
+        return undefined;
+    return { pid: o.pid, session: o.session, startedAt };
+}