@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/events.js

@@ -0,0 +1,87 @@
+/**
+ * Code-thread events: what a Mac-hosted terminal tells ProhostAI about its
+ * thread — a prompt, a finished turn, a permission prompt, an interrupt.
+ *
+ * Both the daemon and the hook commands Claude Code / Codex run post here. The
+ * credential is not the paired API key: it is a narrow, expiring `host_events`
+ * token the relay mints for this machine over its control socket, kept in
+ * `$PROHOST_HOME/code-host/hook.json` (0600) and re-read on every post. So a
+ * hook in a shell that has been open for days uses whatever token the current
+ * daemon last wrote, and a machine whose daemon has been off for a day posts
+ * nothing rather than holding a long-lived secret in a file.
+ *
+ * Posting never costs the agent anything: every failure — no token yet, an
+ * expired one, a server without the endpoint (404), a closed thread — is
+ * swallowed. Never throws.
+ */
+import path from 'node:path';
+import { endpointProblem } from '../agent/base-url.js';
+import { USER_AGENT } from '../version.js';
+import { codeHostDir, readJsonObject, writePrivateJson } from './settings.js';
+export const EVENT_POST_TIMEOUT_MS = 5_000;
+export function hookConfigPath(env = process.env) {
+    return path.join(codeHostDir(env), 'hook.json');
+}
+export function writeHookConfig(config, env = process.env) {
+    writePrivateJson(hookConfigPath(env), config);
+}
+/** The current config, or `undefined` when there is none, it is malformed, or it has expired. */
+export function readHookConfig(env = process.env, nowMs = Date.now()) {
+    const raw = readJsonObject(hookConfigPath(env));
+    if (!raw || raw.version !== 1)
+        return undefined;
+    const { endpoint, token, expires_at: expiresAt } = raw;
+    if (typeof endpoint !== 'string' || typeof token !== 'string' || !token || typeof expiresAt !== 'number') {
+        return undefined;
+    }
+    // Same rule as every other credential the CLI sends: never in plaintext off loopback.
+    if (endpointProblem(endpoint, 'http'))
+        return undefined;
+    if (expiresAt * 1000 <= nowMs)
+        return undefined;
+    return { version: 1, endpoint, token, expires_at: expiresAt };
+}
+export function codeThreadEventsPath(codeThreadId) {
+    return `/v1/code-threads/${encodeURIComponent(codeThreadId)}/events`;
+}
+export function event(type, data, nowMs = Date.now()) {
+    return { type, at: new Date(nowMs).toISOString(), data };
+}
+/**
+ * POST one event. Returns the HTTP status, or 0 when nothing was sent or no
+ * answer came back. Never throws.
+ */
+export async function postCodeThreadEvent(config, codeThreadId, body, fetchImpl = fetch, timeoutMs = EVENT_POST_TIMEOUT_MS) {
+    if (!config)
+        return 0;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(`${config.endpoint.replace(/\/+$/, '')}${codeThreadEventsPath(codeThreadId)}`, {
+            method: 'POST',
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.token}`,
+                'User-Agent': USER_AGENT,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        // Drain so the socket is reusable; the answer carries nothing we act on.
+        await response.text().catch(() => undefined);
+        return response.status;
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The daemon's sink: re-reads `hook.json` for every post, like the hooks do. */
+export function fileEventSink(env = process.env, fetchImpl) {
+    return {
+        post: (codeThreadId, body) => postCodeThreadEvent(readHookConfig(env), codeThreadId, body, fetchImpl),
+    };
+}

package/dist/codehost/folders.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The folders this Mac has opened for Code threads, and the rule a folder
+ * start is held to.
+ *
+ * A folder thread runs in place: in the folder itself, with no worktree and no
+ * branch (or, with "Work in a separate copy", in a worktree of the git
+ * checkout the folder is in). On this Mac the owner picks any folder in the
+ * desktop app's native picker, which records it here
+ * (`prohost agent code-host folders add`). From anywhere else — a phone, the
+ * web — a start may only name a folder this Mac has opened, or one under it:
+ * the server never checks a path; this file is the only list that counts.
+ *
+ * `$PROHOST_HOME/code-host/folders.json` (0600):
+ *
+ *     { "v": 1, "folders": [{ "path": "/abs/realpath", "openedAt": "<ISO>" }] }
+ *
+ * Most recent first, at most {@link MAX_OPENED_FOLDERS}. Every path is a
+ * realpath, and a start's folder is realpathed before it is compared, by path
+ * segments: a symlink inside an opened folder that points out of it does not
+ * count as inside.
+ */
+export declare const FOLDERS_VERSION = 1;
+export declare const MAX_OPENED_FOLDERS = 50;
+/** The server's bound on a start's `folder` (CONTRACT: ≤ 1024 chars). */
+export declare const MAX_FOLDER_PATH_CHARS = 1024;
+/** What a start's thread says when its folder is not one this Mac opened (the contract's words). */
+export declare const FOLDER_NOT_OPENED = "This folder hasn't been opened on this Mac. Open it from the Prohost desktop app first.";
+/** What a separate-copy start says when its folder is not in a git checkout (the contract's words). */
+export declare const SEPARATE_COPY_NEEDS_GIT = "Work in a separate copy needs a git repository.";
+export interface OpenedFolder {
+    path: string;
+    openedAt: string;
+}
+/** One opened folder as the status frame reports it. */
+export interface ReportedFolder {
+    path: string;
+    git: boolean;
+}
+export type FolderResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function foldersPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * `input` as an absolute path: `~` and `~/…` are the home directory, any other
+ * relative path is refused (there is no "current directory" for a start sent
+ * from a phone). Normalised, not yet realpathed.
+ */
+export declare function expandFolder(input: string, home?: string): string | undefined;
+/** The realpath of an existing directory, or `undefined`. */
+export declare function realDirectory(absolute: string): string | undefined;
+/** Whether `child` is `parent` or inside it, by whole path segments (`/a/bc` is not inside `/a/b`). */
+export declare function isWithin(child: string, parent: string): boolean;
+/** The list on disk, newest first; a missing, unreadable or malformed file is empty. */
+export declare function loadFolders(env?: NodeJS.ProcessEnv): OpenedFolder[];
+/** A lock older than this was left by a process that died holding it (a change takes milliseconds). */
+export declare const FOLDERS_LOCK_STALE_MS = 10000;
+/** How long a change waits for another process's change to the list before giving up. */
+export declare const FOLDERS_LOCK_WAIT_MS = 3000;
+/** What a start's move-to-front waits at most: it runs on the daemon's event loop, and may be skipped. */
+export declare const TOUCH_LOCK_WAIT_MS = 100;
+export declare class FoldersBusyError extends Error {
+    constructor();
+}
+/**
+ * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
+ * judged by its age again. A file that is no longer stale is another process's fresh lock (it took
+ * over the same stale one a moment earlier) and is linked back, unless a lock exists again. Judged
+ * by age, never by inode: Linux reuses a deleted file's inode for the next one made.
+ */
+export declare function takeOverStale(lock: string, nowMs?: number): void;
+/**
+ * Run `work` (a read-modify-write of `folders.json`) holding the list's lock: `folders.json.lock`,
+ * created exclusively. The desktop app's `folders add`, a second `folders add` and the daemon
+ * moving a started folder to the front are separate processes; without it, two that read the same
+ * list each write it back without the other's folder. A lock left by a process that died is taken
+ * over once it is {@link FOLDERS_LOCK_STALE_MS} old.
+ *
+ * @throws FoldersBusyError when another process holds it past {@link FOLDERS_LOCK_WAIT_MS}.
+ */
+export declare function withFoldersLock<T>(env: NodeJS.ProcessEnv, work: () => T, options?: {
+    waitMs?: number;
+    now?: () => number;
+}): T;
+/**
+ * Open `input` on this Mac (`folders add`): it must be an existing directory;
+ * its realpath goes to the front of the list.
+ */
+export declare function addFolder(input: string, env?: NodeJS.ProcessEnv, options?: {
+    home?: string;
+    now?: Date;
+}): FolderResult;
+/**
+ * Forget `input` (`folders remove`), matched as written or by its realpath.
+ * Returns the path removed, or `undefined` when it was not in the list.
+ */
+export declare function removeFolder(input: string, env?: NodeJS.ProcessEnv, options?: {
+    home?: string;
+}): string | undefined;
+/** A thread started in `folder` (a realpath): it moves to the front of the list. Never throws. */
+export declare function touchFolder(folder: string, env?: NodeJS.ProcessEnv, now?: Date): void;
+/**
+ * The folder a start names, held to the rule: an existing directory that is,
+ * after realpath, an opened folder or inside one. Returns its realpath, or why
+ * it is refused (shown on the thread).
+ */
+export declare function resolveOpenedFolder(input: string, env?: NodeJS.ProcessEnv, options?: {
+    home?: string;
+}): FolderResult;
+/**
+ * Whether `folder` is in a git work tree, by looking for `.git` in it and each
+ * parent — no `git` process per folder per status frame. The start of a
+ * separate copy asks git itself.
+ */
+export declare function inGitWorkTree(folder: string): boolean;
+/** The opened folders that still exist, for the status frame (newest first). */
+export declare function reportFolders(env?: NodeJS.ProcessEnv): ReportedFolder[];
+/** The file's mtime and size (`''` when there is none): the host's cheap "did the list change". */
+export declare function foldersStamp(env?: NodeJS.ProcessEnv): string;

package/dist/codehost/folders.js

@@ -0,0 +1,317 @@
+/**
+ * The folders this Mac has opened for Code threads, and the rule a folder
+ * start is held to.
+ *
+ * A folder thread runs in place: in the folder itself, with no worktree and no
+ * branch (or, with "Work in a separate copy", in a worktree of the git
+ * checkout the folder is in). On this Mac the owner picks any folder in the
+ * desktop app's native picker, which records it here
+ * (`prohost agent code-host folders add`). From anywhere else — a phone, the
+ * web — a start may only name a folder this Mac has opened, or one under it:
+ * the server never checks a path; this file is the only list that counts.
+ *
+ * `$PROHOST_HOME/code-host/folders.json` (0600):
+ *
+ *     { "v": 1, "folders": [{ "path": "/abs/realpath", "openedAt": "<ISO>" }] }
+ *
+ * Most recent first, at most {@link MAX_OPENED_FOLDERS}. Every path is a
+ * realpath, and a start's folder is realpathed before it is compared, by path
+ * segments: a symlink inside an opened folder that points out of it does not
+ * count as inside.
+ */
+import { closeSync, linkSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { codeHostDir, ensurePrivateDir, readJsonObject, writePrivateJson } from './settings.js';
+export const FOLDERS_VERSION = 1;
+export const MAX_OPENED_FOLDERS = 50;
+/** The server's bound on a start's `folder` (CONTRACT: ≤ 1024 chars). */
+export const MAX_FOLDER_PATH_CHARS = 1024;
+/** What a start's thread says when its folder is not one this Mac opened (the contract's words). */
+export const FOLDER_NOT_OPENED = "This folder hasn't been opened on this Mac. Open it from the Prohost desktop app first.";
+/** What a separate-copy start says when its folder is not in a git checkout (the contract's words). */
+export const SEPARATE_COPY_NEEDS_GIT = 'Work in a separate copy needs a git repository.';
+export function foldersPath(env = process.env) {
+    return path.join(codeHostDir(env), 'folders.json');
+}
+/** NUL, C0 controls and DEL: never part of a folder this CLI accepts. */
+const CONTROL = /[\u0000-\u001f\u007f]/;
+/**
+ * `input` as an absolute path: `~` and `~/…` are the home directory, any other
+ * relative path is refused (there is no "current directory" for a start sent
+ * from a phone). Normalised, not yet realpathed.
+ */
+export function expandFolder(input, home = os.homedir()) {
+    if (typeof input !== 'string' || !input || input.length > MAX_FOLDER_PATH_CHARS || CONTROL.test(input))
+        return undefined;
+    let expanded;
+    if (input === '~')
+        expanded = home;
+    else if (input.startsWith('~/'))
+        expanded = path.join(home, input.slice(2));
+    else if (path.isAbsolute(input))
+        expanded = input;
+    else
+        return undefined;
+    return path.resolve(expanded);
+}
+/** The realpath of an existing directory, or `undefined`. */
+export function realDirectory(absolute) {
+    try {
+        const real = realpathSync.native(absolute);
+        return statSync(real).isDirectory() ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `child` is `parent` or inside it, by whole path segments (`/a/bc` is not inside `/a/b`). */
+export function isWithin(child, parent) {
+    const relative = path.relative(parent, child);
+    if (relative === '')
+        return true;
+    if (path.isAbsolute(relative))
+        return false;
+    return relative.split(path.sep)[0] !== '..';
+}
+/** The list on disk, newest first; a missing, unreadable or malformed file is empty. */
+export function loadFolders(env = process.env) {
+    const raw = readJsonObject(foldersPath(env));
+    if (!raw || raw.v !== FOLDERS_VERSION || !Array.isArray(raw.folders))
+        return [];
+    const folders = [];
+    for (const entry of raw.folders) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const { path: folder, openedAt } = entry;
+        if (typeof folder !== 'string' || !path.isAbsolute(folder) || folder.length > MAX_FOLDER_PATH_CHARS)
+            continue;
+        if (CONTROL.test(folder) || folders.some((seen) => seen.path === folder))
+            continue;
+        folders.push({ path: folder, openedAt: typeof openedAt === 'string' ? openedAt : new Date(0).toISOString() });
+        if (folders.length >= MAX_OPENED_FOLDERS)
+            break;
+    }
+    return folders;
+}
+/** Unlocked: only ever called inside {@link withFoldersLock}, so not exported. */
+function saveFolders(folders, env) {
+    writePrivateJson(foldersPath(env), { v: FOLDERS_VERSION, folders: folders.slice(0, MAX_OPENED_FOLDERS) });
+}
+/** A lock older than this was left by a process that died holding it (a change takes milliseconds). */
+export const FOLDERS_LOCK_STALE_MS = 10_000;
+/** How long a change waits for another process's change to the list before giving up. */
+export const FOLDERS_LOCK_WAIT_MS = 3_000;
+/** What a start's move-to-front waits at most: it runs on the daemon's event loop, and may be skipped. */
+export const TOUCH_LOCK_WAIT_MS = 100;
+export class FoldersBusyError extends Error {
+    constructor() {
+        super('The opened-folders list is busy (another prohost is changing it). Try again.');
+    }
+}
+/**
+ * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
+ * judged by its age again. A file that is no longer stale is another process's fresh lock (it took
+ * over the same stale one a moment earlier) and is linked back, unless a lock exists again. Judged
+ * by age, never by inode: Linux reuses a deleted file's inode for the next one made.
+ */
+export function takeOverStale(lock, nowMs = Date.now()) {
+    const aside = `${lock}.${process.pid}.${Math.random().toString(16).slice(2)}.stale`;
+    try {
+        renameSync(lock, aside);
+    }
+    catch {
+        return; // someone else moved or released it
+    }
+    try {
+        if (nowMs - statSync(aside).mtimeMs <= FOLDERS_LOCK_STALE_MS) {
+            try {
+                linkSync(aside, lock);
+            }
+            catch {
+                /* a newer lock is there: that one stands */
+            }
+        }
+    }
+    finally {
+        rmSync(aside, { force: true });
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Run `work` (a read-modify-write of `folders.json`) holding the list's lock: `folders.json.lock`,
+ * created exclusively. The desktop app's `folders add`, a second `folders add` and the daemon
+ * moving a started folder to the front are separate processes; without it, two that read the same
+ * list each write it back without the other's folder. A lock left by a process that died is taken
+ * over once it is {@link FOLDERS_LOCK_STALE_MS} old.
+ *
+ * @throws FoldersBusyError when another process holds it past {@link FOLDERS_LOCK_WAIT_MS}.
+ */
+export function withFoldersLock(env, work, options = {}) {
+    const lock = `${foldersPath(env)}.lock`;
+    ensurePrivateDir(path.dirname(lock));
+    const now = options.now ?? Date.now;
+    const deadline = now() + (options.waitMs ?? FOLDERS_LOCK_WAIT_MS);
+    // Released only while the file is still this one: never a lock another process holds now.
+    const token = `${process.pid}.${Math.random().toString(16).slice(2)}`;
+    for (;;) {
+        try {
+            const fd = openSync(lock, 'wx', 0o600);
+            try {
+                writeSync(fd, token);
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        try {
+            if (now() - statSync(lock).mtimeMs > FOLDERS_LOCK_STALE_MS) {
+                takeOverStale(lock, now());
+                continue;
+            }
+        }
+        catch {
+            continue; // released between the open and the stat: try again at once
+        }
+        if (now() >= deadline)
+            throw new FoldersBusyError();
+        sleepSync(10 + Math.floor(Math.random() * 20));
+    }
+    try {
+        return work();
+    }
+    finally {
+        try {
+            if (readFileSync(lock, 'utf8') === token)
+                rmSync(lock, { force: true });
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** `folder` (a realpath) at the front, opened now; the oldest past the cap drops off. */
+function upsertFront(folder, env, now, waitMs) {
+    withFoldersLock(env, () => {
+        const rest = loadFolders(env).filter((entry) => entry.path !== folder);
+        saveFolders([{ path: folder, openedAt: now.toISOString() }, ...rest], env);
+    }, { waitMs });
+}
+/**
+ * Open `input` on this Mac (`folders add`): it must be an existing directory;
+ * its realpath goes to the front of the list.
+ */
+export function addFolder(input, env = process.env, options = {}) {
+    const absolute = expandFolder(input, options.home);
+    if (!absolute)
+        return { ok: false, reason: 'Give an absolute path (or one starting with ~/).' };
+    const real = realDirectory(absolute);
+    if (!real)
+        return { ok: false, reason: `There's no folder at ${absolute}.` };
+    try {
+        upsertFront(real, env, options.now ?? new Date());
+    }
+    catch (err) {
+        if (err instanceof FoldersBusyError)
+            return { ok: false, reason: err.message };
+        throw err;
+    }
+    return { ok: true, path: real };
+}
+/**
+ * Forget `input` (`folders remove`), matched as written or by its realpath.
+ * Returns the path removed, or `undefined` when it was not in the list.
+ */
+export function removeFolder(input, env = process.env, options = {}) {
+    const absolute = expandFolder(input, options.home);
+    if (!absolute)
+        return undefined;
+    const real = realDirectory(absolute);
+    return withFoldersLock(env, () => {
+        const folders = loadFolders(env);
+        const match = folders.find((entry) => entry.path === absolute || (real !== undefined && entry.path === real));
+        if (!match)
+            return undefined;
+        saveFolders(folders.filter((entry) => entry !== match), env);
+        return match.path;
+    });
+}
+/** A thread started in `folder` (a realpath): it moves to the front of the list. Never throws. */
+export function touchFolder(folder, env = process.env, now = new Date()) {
+    try {
+        // Best effort, on the daemon's event loop: never wait long for another process's change.
+        upsertFront(folder, env, now, TOUCH_LOCK_WAIT_MS);
+    }
+    catch {
+        /* the thread runs either way; the list is only what phones are offered */
+    }
+}
+/**
+ * The folder a start names, held to the rule: an existing directory that is,
+ * after realpath, an opened folder or inside one. Returns its realpath, or why
+ * it is refused (shown on the thread).
+ */
+export function resolveOpenedFolder(input, env = process.env, options = {}) {
+    const absolute = expandFolder(input, options.home);
+    if (!absolute)
+        return { ok: false, reason: FOLDER_NOT_OPENED };
+    const real = realDirectory(absolute);
+    if (!real)
+        return { ok: false, reason: `There's no folder at ${absolute} on this Mac.` };
+    for (const opened of loadFolders(env)) {
+        // An entry is a realpath when it is written; re-read in case what it names moved since.
+        const roots = new Set([opened.path, realDirectory(opened.path) ?? opened.path]);
+        for (const root of roots)
+            if (isWithin(real, root))
+                return { ok: true, path: real };
+    }
+    return { ok: false, reason: FOLDER_NOT_OPENED };
+}
+/**
+ * Whether `folder` is in a git work tree, by looking for `.git` in it and each
+ * parent — no `git` process per folder per status frame. The start of a
+ * separate copy asks git itself.
+ */
+export function inGitWorkTree(folder) {
+    let current = folder;
+    for (;;) {
+        try {
+            statSync(path.join(current, '.git'));
+            return true;
+        }
+        catch {
+            /* not here */
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+/** The opened folders that still exist, for the status frame (newest first). */
+export function reportFolders(env = process.env) {
+    const reported = [];
+    for (const { path: folder } of loadFolders(env)) {
+        if (realDirectory(folder) !== folder)
+            continue;
+        reported.push({ path: folder, git: inGitWorkTree(folder) });
+    }
+    return reported;
+}
+/** The file's mtime and size (`''` when there is none): the host's cheap "did the list change". */
+export function foldersStamp(env = process.env) {
+    try {
+        const stat = statSync(foldersPath(env));
+        return `${stat.mtimeMs}:${stat.size}`;
+    }
+    catch {
+        return '';
+    }
+}