toolroll 0.5.0

package/dist/desktop-access.d.ts

@@ -0,0 +1,28 @@
+import { type ExecResult } from "./exec.js";
+export type DesktopProjectAccess = {
+    repo: string;
+    state: "ready" | "permission-needed" | "missing" | "unavailable" | "checking";
+    message: string;
+};
+export type DesktopAccessReport = {
+    version: 1;
+    controllerPid: number;
+    checkedAt: string;
+    request: string;
+    projects: DesktopProjectAccess[];
+};
+export declare function accessFailure(repo: string, code: unknown): DesktopProjectAccess;
+/** Probe only unique files we created, inside Git metadata, never tracked files.
+ * Run in a bounded child of the real service, not the foreground shell. */
+export declare function probeDesktopProject(repo: string): DesktopProjectAccess;
+export declare function interpretAccessProbe(repo: string, result: ExecResult): DesktopProjectAccess;
+export declare function checkDesktopProjects(repos: readonly string[]): Promise<DesktopProjectAccess[]>;
+/** A receipt from an old worker or old project selection is never readiness. */
+export declare function currentDesktopAccess(report: DesktopAccessReport | null, supervisor: {
+    phase?: string;
+    controllerPid?: number | null;
+    updatedAt?: string;
+} | null, repos: readonly string[], request: string): {
+    verified: boolean;
+    projects: DesktopProjectAccess[];
+};

package/dist/desktop-access.js

@@ -0,0 +1,88 @@
+/** Local desktop readiness, not a permission grant or task execution. */
+import { mkdtempSync, readFileSync, writeFileSync, unlinkSync, rmdirSync, opendirSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { run } from "./exec.js";
+export function accessFailure(repo, code) {
+    if (code === "EROFS")
+        return { repo, state: "permission-needed", message: "This project is on a read-only drive. Choose a writable copy; Privacy Settings cannot make a read-only drive writable." };
+    if (code === "EPERM" || code === "EACCES")
+        return { repo, state: "permission-needed", message: "The background worker cannot read or write this project. Check folder access in Privacy Settings, or the folder's read/write permissions." };
+    if (code === "ENOSPC")
+        return { repo, state: "unavailable", message: "There is not enough disk space to write to this project. Free some space, then check again." };
+    if (code === "ENOENT" || code === "ENOTDIR")
+        return { repo, state: "missing", message: "This folder is missing or its drive is disconnected. Reconnect it or choose the project's new location." };
+    return { repo, state: "unavailable", message: "The worker could not check this Git project. Check that Git is installed and the folder is available, then check again." };
+}
+/** Probe only unique files we created, inside Git metadata, never tracked files.
+ * Run in a bounded child of the real service, not the foreground shell. */
+export function probeDesktopProject(repo) {
+    let scratch;
+    try {
+        const directory = opendirSync(repo);
+        directory.readSync();
+        directory.closeSync();
+        const common = execFileSync("git", ["-C", repo, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", timeout: 4000, stdio: ["ignore", "pipe", "pipe"] }).trim();
+        scratch = mkdtempSync(join(realpathSync(common), "standing-orders-access-"));
+        const file = join(scratch, "check");
+        writeFileSync(file, "Toolroll access check\n", { flag: "wx", mode: 0o600 });
+        if (readFileSync(file, "utf8") !== "Toolroll access check\n")
+            throw Error("Read-back failed");
+        unlinkSync(file);
+        rmdirSync(scratch);
+        scratch = undefined;
+        return { repo, state: "ready", message: "The worker can read this project and write its Git metadata." };
+    }
+    catch (error) {
+        return accessFailure(repo, error.code);
+    }
+    finally {
+        // No recursive deletion: only our own exact file and empty directory.
+        if (scratch) {
+            try {
+                unlinkSync(join(scratch, "check"));
+            }
+            catch { }
+            try {
+                rmdirSync(scratch);
+            }
+            catch { }
+        }
+    }
+}
+export function interpretAccessProbe(repo, result) {
+    if (result.timedOut)
+        return { repo, state: "unavailable", message: "The access check did not finish. Unlock your Mac, handle any folder-access prompt, then check again." };
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (result.code === 0 && parsed.repo === repo && ["ready", "permission-needed", "missing", "unavailable"].includes(parsed.state) && typeof parsed.message === "string")
+            return parsed;
+    }
+    catch { }
+    return accessFailure(repo, result.notFound ? "ENOEXEC" : null);
+}
+export async function checkDesktopProjects(repos) {
+    const checked = [];
+    // Bound concurrency and each diagnostic; these are not task runtime caps.
+    for (let offset = 0; offset < repos.length; offset += 4) {
+        checked.push(...await Promise.all(repos.slice(offset, offset + 4).map(async (repo) => interpretAccessProbe(repo, await run(process.execPath, [fileURLToPath(import.meta.url), "probe", repo], { timeoutMs: 6500, maxBuffer: 8192 })))));
+    }
+    return checked;
+}
+/** A receipt from an old worker or old project selection is never readiness. */
+export function currentDesktopAccess(report, supervisor, repos, request) {
+    const matching = report?.version === 1 && Number.isFinite(Date.parse(report.checkedAt)) && report.request === request &&
+        Array.isArray(report.projects) && report.projects.every(one => one && typeof one.repo === "string" && typeof one.message === "string" && ["ready", "permission-needed", "missing", "unavailable"].includes(one.state)) &&
+        report.projects.length === repos.length && repos.every(repo => report.projects.some(one => one.repo === repo));
+    const current = matching && supervisor?.phase === "running" && report.controllerPid === supervisor.controllerPid && report.checkedAt >= (supervisor.updatedAt ?? "~");
+    const pending = (repo) => ({ repo, state: "checking", message: "Waiting for this background worker to check access." });
+    // Retain an actionable failure while the controller backs off, but never
+    // treat a stopped worker's successful probe as current readiness.
+    const failed = matching && ["backoff", "stopped"].includes(supervisor?.phase ?? "") && report.projects.some(one => one.state !== "ready");
+    const projects = current ? report.projects : failed ? report.projects.map(one => one.state === "ready" ? pending(one.repo) : one) : repos.map(pending);
+    return { verified: projects.length > 0 && projects.every(one => one.state === "ready"), projects };
+}
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url) && process.argv[2] === "probe" && process.argv[3]) {
+    console.log(JSON.stringify(probeDesktopProject(process.argv[3])));
+}

package/dist/desktop-bundle.d.ts

@@ -0,0 +1,16 @@
+export type DesktopBundle = {
+    path: string;
+    hash: string;
+    buildId: string;
+    version: string;
+    bundleId: string;
+    schemaVersion: number;
+    development: boolean;
+    providerBin: string;
+    recoveryProtocol?: number;
+};
+/** Hash the exact bundle, including executable modes; reject aliases inside
+ * it so a checked file cannot secretly refer to mutable external code. */
+export declare function bundleHash(path: string): string;
+export declare function readDesktopBundle(path: string): DesktopBundle;
+export declare function verifyDesktopUpdateBundles(previous: DesktopBundle, candidate: DesktopBundle): Promise<void>;

package/dist/desktop-bundle.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { run } from "./exec.js";
+/** Hash the exact bundle, including executable modes; reject aliases inside
+ * it so a checked file cannot secretly refer to mutable external code. */
+export function bundleHash(path) {
+    const hash = createHash("sha256");
+    const walk = (file, relative) => {
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile()))
+            throw Error("Update bundles must contain only regular files and directories, not links.");
+        hash.update(JSON.stringify([relative, stat.isDirectory() ? "directory" : "file", stat.mode & 0o777])).update("\0");
+        if (stat.isDirectory())
+            for (const name of readdirSync(file).sort())
+                walk(join(file, name), `${relative}/${name}`);
+        else
+            hash.update(readFileSync(file));
+        hash.update("\0");
+    };
+    walk(path, "app");
+    return hash.digest("hex");
+}
+export function readDesktopBundle(path) {
+    if (!path.endsWith(".app") || lstatSync(path).isSymbolicLink() || !lstatSync(path).isDirectory())
+        throw Error("Choose an app bundle, not a link.");
+    const canonical = realpathSync(path), resources = join(canonical, "Contents", "Resources");
+    const manifest = JSON.parse(readFileSync(join(resources, "runtime.json"), "utf8"));
+    readFileSync(join(resources, "standing-orders-bundle"));
+    if (manifest.updateProtocol !== 1)
+        throw Error("This app predates controlled updates. Complete the documented first installation before using this updater.");
+    if (manifest.node !== "runtime/node" || !/^[a-f0-9-]{36}$/.test(manifest.buildId) || !/^\d+\.\d+\.\d+$/.test(manifest.version) || !Number.isSafeInteger(manifest.schemaVersion))
+        throw Error("The update manifest is invalid.");
+    const development = manifest.bundleId === "com.standing-orders.desktop.development";
+    if (!development && manifest.bundleId !== "com.standing-orders.desktop")
+        throw Error("This is not a Toolroll app identity.");
+    if (manifest.development !== development || typeof manifest.providerBin !== "string")
+        throw Error("The update runtime identity is inconsistent.");
+    for (const file of ["runtime/node", "runtime/bundle-swap", "dist/desktop-host.js"])
+        if (!lstatSync(join(resources, file)).isFile())
+            throw Error("The app is missing an update helper.");
+    return { path: canonical, hash: bundleHash(canonical), buildId: manifest.buildId, version: manifest.version, bundleId: manifest.bundleId, schemaVersion: manifest.schemaVersion, development, providerBin: manifest.providerBin, ...(manifest.recoveryProtocol === 1 ? { recoveryProtocol: 1 } : {}) };
+}
+async function checked(file, args) {
+    const result = await run(file, args, { timeoutMs: 60_000, maxBuffer: 32_768 });
+    if (result.code !== 0)
+        throw Error(`App verification failed: ${(result.stderr || result.stdout || "command unavailable").slice(0, 1000)}`);
+    return result.stdout + result.stderr;
+}
+export async function verifyDesktopUpdateBundles(previous, candidate) {
+    if (process.platform !== "darwin")
+        throw Error("The native app updater currently supports macOS only.");
+    if (previous.bundleId !== candidate.bundleId)
+        throw Error("A preview cannot replace a release, or a different app identity.");
+    for (const app of [previous, candidate])
+        await checked("/usr/bin/codesign", ["--verify", "--deep", "--strict", app.path]);
+    const old = await checked("/usr/bin/codesign", ["-dv", "--verbose=4", previous.path]);
+    const next = await checked("/usr/bin/codesign", ["-dv", "--verbose=4", candidate.path]);
+    for (const [app, signature] of [[previous, old], [candidate, next]]) {
+        if (!signature.includes(`Identifier=${app.bundleId}\n`))
+            throw Error("The manifest and signed app identity disagree.");
+    }
+    if (candidate.development)
+        return; // Explicitly separate preview identity only.
+    const team = (text) => /^TeamIdentifier=(?!not set$)(.+)$/m.exec(text)?.[1];
+    if (!team(old) || team(old) !== team(next) || !/^Authority=Developer ID Application:/m.test(next))
+        throw Error("A release update must preserve the installed Developer ID signing team.");
+    const requirement = /designated => (.+)/.exec(await checked("/usr/bin/codesign", ["-dr", "-", previous.path]))?.[1];
+    if (!requirement)
+        throw Error("The installed signing requirement could not be read.");
+    await checked("/usr/bin/codesign", ["--verify", "--strict", "-R", requirement, candidate.path]);
+    await checked("/usr/sbin/spctl", ["--assess", "--type", "execute", candidate.path]);
+    await checked("/usr/bin/xcrun", ["stapler", "validate", candidate.path]);
+}

package/dist/desktop-host.d.ts

@@ -0,0 +1,54 @@
+import { type ServiceDefinition, type SupervisorRunner } from "./daemon.js";
+import { type ContainmentPolicy } from "./containment.js";
+import type { Store } from "./store.js";
+export type DesktopConfig = {
+    version: 1;
+    databaseFile: string;
+    repos: string[];
+    port: number;
+    identity: string;
+    runnerName?: string;
+    containment?: ContainmentPolicy;
+    databaseInitialized?: boolean;
+};
+export declare function readDesktopConfig(stateDir: string): DesktopConfig;
+export declare function writeDesktopConfig(stateDir: string, config: DesktopConfig): void;
+export declare function addDesktopProjects(stateDir: string, store: Store, paths: string[], exact?: boolean): Promise<DesktopConfig>;
+export declare function loadOrCreateDesktopConfig(stateDir: string, isolated?: boolean): DesktopConfig;
+export declare function openDesktopStore(file: string): Store;
+export declare function openConfiguredDesktopStore(stateDir: string): Store;
+/** Recovery controls must not depend on opening or migrating the task store. */
+export declare function desktopDatabaseStatus(file: string): {
+    ready: boolean;
+    message: string;
+    expectedSchema: number;
+};
+/** Share `up`'s existing durable credential, without replacing another login. */
+export declare function pairDesktopLogin(store: Store, file: string, login: {
+    name: string;
+    password: string;
+}): void;
+/** The desktop service definition the shell asks for: the shared launchd contract, labelled by the shell. */
+export declare function desktopServiceDefinition(stateDir: string, args: {
+    node: string;
+    helper: string;
+    label: string;
+    home?: string;
+    providerBin?: string;
+    containment?: ContainmentPolicy;
+    bundleId?: string;
+    buildId?: string;
+}): ServiceDefinition;
+export type DesktopLiveness = {
+    alive: true;
+    port: number;
+} | {
+    alive: false;
+    port: number;
+    problem: string;
+};
+/** The fresh-liveness check: the controller answers its identity challenge on the configured port. */
+export declare function verifyDesktopLiveness(config: DesktopConfig, fetchImpl?: typeof fetch): Promise<DesktopLiveness>;
+/** `service-start | service-stop | service-status --node <path> --helper <path> --label <label>`: the shell's service verbs, on the shared lifecycle. */
+export declare function desktopServiceCommand(verb: string, stateDir: string, config: DesktopConfig, argv: string[], supervise?: SupervisorRunner): Promise<Record<string, unknown>>;
+export declare function desktopMain(argv: string[], supervise?: SupervisorRunner): Promise<void>;