@fungi.computer/truffle 0.0.0-stage → 0.2.0

package/dist/private-local-computer-attach.js

@@ -0,0 +1,230 @@
+import { generateKeyPairSync } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, resolve } from "node:path";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { z } from "zod";
+import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
+import { callFungiMcpTeamControl, fungiMcpTeamEndpoint, readFungiMcpLocalBackends, writeFungiMcpLocalBackends, } from "./private-fungi-account.js";
+import { runLocalComputerBackend, startLocalComputerd, } from "./private-local-computer-backend.js";
+/**
+ * `fungi computer attach|status|detach`: this machine's folders as execution
+ * backends of Team Computers. Attaching generates a device key here, stores
+ * the folder path and private key in Local's owner-only credential file, and
+ * sends the Hub only the public key and two labels through the member's
+ * existing Team MCP login. Every request id is persisted before the network
+ * call so an uncertain outcome is retried, never duplicated.
+ */
+const requestIds = defineIdFamily({
+    family: "local-computer-backend",
+    version: 1,
+    kinds: { attach: { prefix: "local_attach_request" } },
+});
+const computerPageSchema = z.looseObject({
+    computers: z.array(z.looseObject({ computerId: z.string(), name: z.string() })),
+    nextOffset: z.number().int().nonnegative().nullable(),
+});
+const attachResultSchema = z.discriminatedUnion("kind", [
+    z.looseObject({
+        kind: z.literal("attached"),
+        requestId: z.string(),
+        backendId: z.string().regex(/^local-[a-z2-7]{16}$/),
+    }),
+    z.looseObject({
+        kind: z.enum(["uncertain", "denied", "conflict", "invalid"]),
+        requestId: z.string(),
+    }),
+]);
+const detachResultSchema = z.discriminatedUnion("kind", [
+    z.looseObject({ kind: z.literal("detached"), detached: z.boolean() }),
+    z.looseObject({ kind: z.enum(["denied", "uncertain", "invalid"]) }),
+]);
+async function control(teamEndpoint, call, schema, options) {
+    const text = await callFungiMcpTeamControl(teamEndpoint, `return await ${call};`, options);
+    if (text === undefined)
+        return undefined;
+    const parsed = schema.safeParse(JSON.parse(text));
+    return parsed.success ? parsed.data : undefined;
+}
+/** A Team Computer by id or name, through the member's own directory view. */
+async function findComputer(teamEndpoint, computer, options) {
+    let offset = 0;
+    while (offset !== null) {
+        const page = await control(teamEndpoint, `computers.list(${JSON.stringify({ limit: 100, offset })})`, computerPageSchema, options);
+        if (page === undefined)
+            throw new Error("The Hub did not list this Team's Computers; retry");
+        const found = page.computers.find((candidate) => candidate.computerId === computer || candidate.name === computer);
+        if (found !== undefined)
+            return found;
+        offset = page.nextOffset;
+    }
+    return undefined;
+}
+function sameComputer(record, computer) {
+    return record.computerId === computer || record.computerName === computer;
+}
+/** A fresh Ed25519 device key: raw public key and PKCS#8 private key, base64. */
+function deviceKey() {
+    const pair = generateKeyPairSync("ed25519");
+    const jwk = z
+        .object({ x: z.string() })
+        .parse(pair.publicKey.export({ format: "jwk" }));
+    return {
+        publicKey: Buffer.from(jwk.x, "base64url").toString("base64"),
+        privateKey: pair.privateKey
+            .export({ format: "der", type: "pkcs8" })
+            .toString("base64"),
+    };
+}
+/** Attach `folderPath` to a Team Computer, or return the existing attachment. */
+export async function attachPrivateLocalComputer(rawEndpoint, input, controlOptions = {}) {
+    const options = {
+        ...controlOptions,
+        credentialPath: controlOptions.credentialPath ??
+            capturePrivateLocalConfigRoot().credentialPath,
+    };
+    const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
+    const rootPath = await realpath(resolve(input.folderPath));
+    if (!(await stat(rootPath)).isDirectory())
+        throw new Error("The folder to attach is not a directory");
+    const saved = await readFungiMcpLocalBackends(options);
+    if (saved.issuer !== endpoint.origin)
+        throw new Error(`Fungi MCP sign-in is required; run fungi login --fungi-mcp ${endpoint.href}`);
+    let record = saved.backends.find((candidate) => candidate.teamId === teamId && sameComputer(candidate, input.computer));
+    if (record !== undefined && record.rootPath !== rootPath)
+        throw new Error(`This machine is already attached to ${record.computerName} with another folder; run fungi computer detach first`);
+    if (record === undefined) {
+        const computer = await findComputer(endpoint, input.computer, options);
+        if (computer === undefined)
+            return { kind: "not-found" };
+        record = {
+            requestId: requestIds.attach.generate(),
+            teamId,
+            computerId: computer.computerId,
+            computerName: computer.name,
+            rootPath,
+            hostLabel: z
+                .string()
+                .trim()
+                .min(1)
+                .max(256)
+                .parse(input.hostLabel ?? hostname()),
+            folderLabel: z.string().min(1).max(256).parse(basename(rootPath)),
+            ...deviceKey(),
+        };
+        const pending = record;
+        await writeFungiMcpLocalBackends((current) => [...current, pending], options);
+    }
+    if (record.backendId !== undefined)
+        return {
+            kind: "attached",
+            computerId: record.computerId,
+            computerName: record.computerName,
+            backendId: record.backendId,
+            rootPath,
+        };
+    const result = await control(endpoint, `computers.attachLocal(${JSON.stringify({
+        computerId: record.computerId,
+        publicKey: record.publicKey,
+        hostLabel: record.hostLabel,
+        folderLabel: record.folderLabel,
+        requestId: record.requestId,
+    })})`, attachResultSchema, options);
+    if (result === undefined)
+        return { kind: "uncertain" };
+    if (result.kind !== "attached")
+        return { kind: result.kind };
+    const attached = { ...record, backendId: result.backendId };
+    await writeFungiMcpLocalBackends((current) => current.map((candidate) => candidate.requestId === attached.requestId ? attached : candidate), options);
+    return {
+        kind: "attached",
+        computerId: attached.computerId,
+        computerName: attached.computerName,
+        backendId: result.backendId,
+        rootPath,
+    };
+}
+/**
+ * Detach a Computer's attachment on the Hub, then forget it here. A pending
+ * attach is replayed first so the Hub never keeps an attachment Local forgot.
+ */
+export async function detachPrivateLocalComputer(rawEndpoint, computer, input = {}) {
+    const options = {
+        ...input,
+        credentialPath: input.credentialPath ?? capturePrivateLocalConfigRoot().credentialPath,
+    };
+    const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
+    const saved = await readFungiMcpLocalBackends(options);
+    const record = saved.backends.find((candidate) => candidate.teamId === teamId && sameComputer(candidate, computer));
+    if (record === undefined)
+        return { kind: "not-attached" };
+    let backendId = record.backendId;
+    if (backendId === undefined) {
+        const replay = await attachPrivateLocalComputer(endpoint, { computer: record.computerId, folderPath: record.rootPath }, options);
+        if (replay.kind !== "attached")
+            return { kind: "uncertain" };
+        backendId = replay.backendId;
+    }
+    const result = await control(endpoint, `computers.detachLocal(${JSON.stringify({
+        computerId: record.computerId,
+        backendId,
+    })})`, detachResultSchema, options);
+    if (result === undefined)
+        return { kind: "uncertain" };
+    if (result.kind === "denied")
+        return { kind: "denied" };
+    if (result.kind !== "detached")
+        return { kind: "uncertain" };
+    await writeFungiMcpLocalBackends((current) => current.filter((candidate) => candidate.requestId !== record.requestId), options);
+    return { kind: "detached" };
+}
+/** What `fungi computer status` shows: never a key. */
+export async function listPrivateLocalComputers(options = {}) {
+    const saved = await readFungiMcpLocalBackends(options);
+    return saved.backends.map((record) => ({
+        teamId: record.teamId,
+        computerId: record.computerId,
+        computerName: record.computerName,
+        rootPath: record.rootPath,
+        backendId: record.backendId ?? null,
+    }));
+}
+/**
+ * Serve one attached folder until `signal` aborts or the Hub refuses the
+ * machine (it was detached elsewhere), in which case Local forgets it.
+ */
+export async function runPrivateLocalComputer(rawEndpoint, computer, input) {
+    const options = {
+        ...input,
+        credentialPath: input.credentialPath ?? capturePrivateLocalConfigRoot().credentialPath,
+    };
+    const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
+    const saved = await readFungiMcpLocalBackends(options);
+    const record = saved.backends.find((candidate) => candidate.teamId === teamId && sameComputer(candidate, computer));
+    if (record?.backendId === undefined)
+        throw new Error(`This machine is not attached to ${computer}`);
+    const daemon = await startLocalComputerd({ root: record.rootPath });
+    try {
+        const outcome = await runLocalComputerBackend({
+            target: {
+                hubOrigin: endpoint.origin,
+                teamId,
+                computerId: record.computerId,
+                backendId: record.backendId,
+                deviceId: record.backendId.slice("local-".length),
+                privateKey: record.privateKey,
+            },
+            root: record.rootPath,
+            computerdPort: daemon.port,
+            signal: options.signal,
+            onStatus: options.onStatus,
+        });
+        if (outcome === "stopped")
+            return "stopped";
+        await writeFungiMcpLocalBackends((current) => current.filter((candidate) => candidate.requestId !== record.requestId), options);
+        return "detached";
+    }
+    finally {
+        await daemon.stop();
+    }
+}

package/dist/private-local-computer-backend.d.ts

@@ -0,0 +1,282 @@
+import { RpcTarget } from "@fungi.computer/capnweb";
+/**
+ * A member's folder as an execution backend of a Team Computer.
+ *
+ * Local runs the same `computerd` 0.2.1 as the Computer container image,
+ * built from vendored source and run under the user's Node in shim mode, with its shim mount rooted at the chosen folder, and dials out to
+ * the Hub. The Computer then syncs and runs commands against this folder with
+ * the library's own push/pull, exactly as it does against a container.
+ *
+ * `computerd` names files by their absolute path on this machine. The Hub
+ * must only ever see `/workspace/...`, so Local serves the Hub a
+ * `WorkspaceRPC` of its own that forwards to `computerd` and translates paths
+ * at this one boundary. Entries outside the folder never cross it.
+ */
+/** The Computer-side root every backend's files live under. */
+export declare const computerWorkspaceRoot = "/workspace";
+export type ChangeCursor = {
+    rev: number;
+    path: string | null;
+};
+export type ChangeEntry = {
+    kind: "file";
+    rev: number;
+    path: string;
+    mode: number;
+    mtime: number;
+    size: number;
+    chunks: {
+        hash: Uint8Array;
+        size: number;
+    }[];
+} | {
+    kind: "dir";
+    rev: number;
+    path: string;
+    mode: number;
+    mtime: number;
+} | {
+    kind: "symlink";
+    rev: number;
+    path: string;
+    target: string;
+    mode: number;
+    mtime: number;
+} | {
+    kind: "delete";
+    rev: number;
+    path: string;
+};
+export type BlobObject = {
+    hash: Uint8Array;
+    bytes: Uint8Array;
+};
+export type ExecEvent = {
+    id: string;
+    seq: number;
+    name: "stdout" | "stderr";
+    value: Uint8Array;
+} | {
+    id: string;
+    seq: number;
+    name: "exit";
+    code: number;
+};
+export type FetchChangesInput = {
+    after?: ChangeCursor;
+    ignore?: string[];
+};
+export type ExecInput = {
+    source: string;
+    cwd?: string;
+    id?: string;
+    input?: unknown;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    stdin?: Uint8Array;
+};
+export type KillSignal = "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP";
+/** computerd's `WorkspaceRPC`, as `@cloudflare/computer` 0.2.1 speaks it. */
+export type ComputerdWorkspaceRpc = {
+    sync: {
+        push(input: {
+            senderRev: number;
+            changes: ReadableStream<ChangeEntry>;
+        }): Promise<{
+            rev: number;
+            appliedPushCursor: ChangeCursor;
+        }>;
+        fetchChanges(input: FetchChangesInput): Promise<{
+            currentCursor: ChangeCursor;
+            appliedPushCursor: ChangeCursor;
+            stream: ReadableStream<ChangeEntry>;
+        }>;
+        watermarks(): Promise<{
+            currentRev: number;
+            pushRev: number;
+            fetchCursor: ChangeCursor;
+        }>;
+        readEntry(path: string): Promise<ChangeEntry | null>;
+        hasObjects(hashes: Uint8Array[]): Promise<Uint8Array[]>;
+        /** Synchronous in computerd; a promise across the RPC session. */
+        fetchObjects(hashes: Uint8Array[]): Promise<ReadableStream<BlobObject>>;
+        pushObjects(objects: ReadableStream<BlobObject>): Promise<void>;
+    };
+    shell: {
+        exec(input: ExecInput): Promise<{
+            id: string;
+            events: ReadableStream<ExecEvent>;
+        }>;
+        getExec(input: {
+            id: string;
+            after?: number | "tail";
+        }): Promise<{
+            id: string;
+            events: ReadableStream<ExecEvent>;
+        }>;
+        killExec(input: {
+            id: string;
+            signal?: KillSignal;
+        }): Promise<void>;
+        disposeExec(input: {
+            id: string;
+        }): Promise<void>;
+    };
+};
+/** Bidirectional path mapping between the folder and `/workspace`. */
+export declare class FolderPathMap {
+    #private;
+    constructor(root: string);
+    /** A folder path as the Computer names it, or undefined outside the folder. */
+    toComputer(localPath: string): string | undefined;
+    /** A Computer path on this machine, or undefined outside `/workspace`. */
+    toLocal(computerPath: string): string | undefined;
+}
+declare class FolderSync extends RpcTarget {
+    #private;
+    constructor(remote: ComputerdWorkspaceRpc["sync"], paths: FolderPathMap);
+    push(input: {
+        senderRev: number;
+        changes: ReadableStream<ChangeEntry>;
+    }): Promise<{
+        rev: number;
+        appliedPushCursor: ChangeCursor;
+    }>;
+    fetchChanges(input: FetchChangesInput): Promise<{
+        currentCursor: ChangeCursor;
+        appliedPushCursor: ChangeCursor;
+        stream: ReadableStream<ChangeEntry>;
+    }>;
+    watermarks(): Promise<{
+        currentRev: number;
+        pushRev: number;
+        fetchCursor: ChangeCursor;
+    }>;
+    readEntry(path: string): Promise<{
+        path: string;
+        kind: "file";
+        rev: number;
+        mode: number;
+        mtime: number;
+        size: number;
+        chunks: {
+            hash: Uint8Array;
+            size: number;
+        }[];
+    } | {
+        path: string;
+        kind: "dir";
+        rev: number;
+        mode: number;
+        mtime: number;
+    } | {
+        path: string;
+        kind: "symlink";
+        rev: number;
+        target: string;
+        mode: number;
+        mtime: number;
+    } | {
+        path: string;
+        kind: "delete";
+        rev: number;
+    } | null>;
+    hasObjects(hashes: Uint8Array[]): Promise<Uint8Array<ArrayBufferLike>[]>;
+    fetchObjects(hashes: Uint8Array[]): Promise<ReadableStream<BlobObject>>;
+    pushObjects(objects: ReadableStream<BlobObject>): Promise<void>;
+}
+/** A command's working directory outside the folder is refused, not widened. */
+export declare class FolderCwdError extends Error {
+    constructor(cwd: string);
+}
+declare class FolderShell extends RpcTarget {
+    #private;
+    constructor(remote: ComputerdWorkspaceRpc["shell"], paths: FolderPathMap);
+    exec(input: ExecInput): Promise<{
+        id: string;
+        events: ReadableStream<ExecEvent>;
+    }>;
+    getExec(input: {
+        id: string;
+        after?: number | "tail";
+    }): Promise<{
+        id: string;
+        events: ReadableStream<ExecEvent>;
+    }>;
+    killExec(input: {
+        id: string;
+        signal?: KillSignal;
+    }): Promise<void>;
+    disposeExec(input: {
+        id: string;
+    }): Promise<void>;
+}
+/** The `WorkspaceRPC` the Hub's Workspace sees for this folder. */
+export declare class FolderWorkspaceRpc extends RpcTarget {
+    #private;
+    constructor(remote: ComputerdWorkspaceRpc, root: string);
+    get sync(): FolderSync;
+    get shell(): FolderShell;
+}
+/** One running computerd rooted at a folder, reachable on loopback only. */
+export type LocalComputerd = Readonly<{
+    port: number;
+    stop: () => Promise<void>;
+}>;
+/** Thrown when this machine has no Node new enough to run computerd. */
+export declare class ComputerdNodeError extends Error {
+    constructor(found: string);
+}
+/**
+ * The Node that runs computerd: FUNGI_NODE, else this process when it is
+ * Node, else `node` on the PATH (the fungi CLI itself runs on Bun). The
+ * same bundle and shim mode run on Linux and macOS; nothing native loads.
+ */
+export declare function resolveComputerdNode(): string;
+/**
+ * Start computerd for `root`. It gets a scrubbed environment: the executable
+ * search path, a home, a locale and a terminal type, never this process's
+ * ambient variables or credentials.
+ */
+export declare function startLocalComputerd(options: Readonly<{
+    root: string;
+    /** Defaults to {@link resolveComputerdNode}. */
+    node?: string;
+    startTimeoutMs?: number;
+}>): Promise<LocalComputerd>;
+/** Where one attached backend dials. */
+export type LocalBackendTarget = Readonly<{
+    hubOrigin: string;
+    teamId: string;
+    computerId: string;
+    backendId: string;
+    deviceId: string;
+    /** The device's Ed25519 private key, base64 PKCS#8. Never sent. */
+    privateKey: string;
+}>;
+export type LocalBackendStatus = Readonly<{
+    kind: "connecting";
+}> | Readonly<{
+    kind: "online";
+}> | Readonly<{
+    kind: "offline";
+    retryInMs: number;
+    reason: string;
+}> | Readonly<{
+    kind: "refused";
+}>;
+/**
+ * Keep one attached folder connected until `signal` aborts: dial out, serve
+ * the folder over the socket, and redial with backoff whenever it drops. A
+ * Hub that refuses the dial (a detached backend) stops the loop.
+ */
+export declare function runLocalComputerBackend(options: Readonly<{
+    target: LocalBackendTarget;
+    root: string;
+    computerdPort: number;
+    signal: AbortSignal;
+    onStatus?: ((status: LocalBackendStatus) => void) | undefined;
+    /** Consecutive 404 refusals before the backend counts as detached. */
+    refusedLimit?: number;
+}>): Promise<"stopped" | "refused">;
+export type { FolderSync, FolderShell };