@easonwumac/computer-linker 0.1.2

package/dist/workspaces.d.ts

@@ -0,0 +1,61 @@
+import { type LocalPortConfig, type ResolvedExposedPath } from "./permissions.js";
+export interface Workspace {
+    id: string;
+    root: string;
+    exposedPath: ResolvedExposedPath;
+}
+export interface WorkspaceCandidate {
+    path: string;
+    id: string;
+    name: string;
+    permissions: ResolvedExposedPath["permissions"];
+}
+export interface WorkspacePathInfo {
+    path: string;
+    name: string;
+    type: "file" | "directory" | "symlink" | "other";
+    size: number;
+    modifiedAt: string;
+}
+export interface WorkspaceTreeOptions {
+    maxDepth?: number;
+    maxEntries?: number;
+    includeFiles?: boolean;
+}
+export interface WorkspaceInstructionFile {
+    path: string;
+    name: string;
+    content: string;
+    size: number;
+    truncated: boolean;
+}
+export interface WorkspaceInstructionsOptions {
+    maxBytes?: number;
+}
+export declare class WorkspaceRegistry {
+    private readonly config;
+    private readonly workspaces;
+    constructor(config: LocalPortConfig);
+    listDefinedWorkspaces(): ResolvedExposedPath[];
+    listWorkspaceCandidates(): Promise<WorkspaceCandidate[]>;
+    openWorkspace(workspaceRef: string): Promise<Workspace>;
+    private findWorkspaceByRef;
+    getWorkspace(workspaceId: string): Workspace;
+    resolvePath(workspace: Workspace, inputPath: string): string;
+    resolveExistingPath(workspace: Workspace, inputPath: string): Promise<string>;
+    resolveWritablePath(workspace: Workspace, inputPath: string): Promise<string>;
+    readFile(workspaceId: string, path: string): Promise<string>;
+    writeFile(workspaceId: string, path: string, content: string): Promise<void>;
+    createFile(workspaceId: string, path: string, content: string): Promise<void>;
+    editFile(workspaceId: string, path: string, oldText: string, newText: string): Promise<number>;
+    listDirectory(workspaceId: string, path: string): Promise<string[]>;
+    listDirectoryEntries(workspaceId: string, path: string): Promise<WorkspacePathInfo[]>;
+    tree(workspaceId: string, path: string, options?: WorkspaceTreeOptions): Promise<WorkspacePathInfo[]>;
+    instructions(workspaceId: string, path: string, options?: WorkspaceInstructionsOptions): Promise<WorkspaceInstructionFile[]>;
+    statPath(workspaceId: string, path: string): Promise<WorkspacePathInfo>;
+    private resolveInstructionTarget;
+    createDirectory(workspaceId: string, path: string): Promise<void>;
+    deletePath(workspaceId: string, path: string, recursive?: boolean): Promise<void>;
+    movePath(workspaceId: string, fromPath: string, toPath: string): Promise<void>;
+}
+export declare function formatWorkspacePath(path: string, workspace: Workspace): string;

package/dist/workspaces.js

@@ -0,0 +1,353 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, opendir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { assertPermission, isPathInsideRoot, } from "./permissions.js";
+import { assertNonSensitiveWorkspacePath } from "./sensitive-files.js";
+export class WorkspaceRegistry {
+    config;
+    workspaces = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    listDefinedWorkspaces() {
+        return this.config.workspaces.map((entry) => ({
+            ...entry,
+            path: resolve(entry.path),
+        }));
+    }
+    async listWorkspaceCandidates() {
+        return this.listDefinedWorkspaces()
+            .filter((workspace) => workspace.permissions.read)
+            .map((workspace) => ({
+            id: workspace.id,
+            name: workspace.name,
+            path: workspace.path,
+            permissions: workspace.permissions,
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    async openWorkspace(workspaceRef) {
+        const exposedPath = this.findWorkspaceByRef(workspaceRef);
+        assertPermission(exposedPath, "read");
+        await mkdir(exposedPath.path, { recursive: true });
+        if (!(await isDirectory(exposedPath.path))) {
+            throw new Error(`Workspace root must be a directory: ${exposedPath.path}`);
+        }
+        const realRoot = await realpath(exposedPath.path);
+        const workspace = {
+            id: `ws_${randomUUID()}`,
+            root: realRoot,
+            exposedPath: {
+                ...exposedPath,
+                path: realRoot,
+            },
+        };
+        this.workspaces.set(workspace.id, workspace);
+        return workspace;
+    }
+    findWorkspaceByRef(workspaceRef) {
+        const resolvedRef = resolve(workspaceRef);
+        const workspace = this.listDefinedWorkspaces().find((entry) => entry.id === workspaceRef ||
+            entry.name === workspaceRef ||
+            entry.path === resolvedRef);
+        if (!workspace) {
+            throw new Error(`Unknown configured workspace: ${workspaceRef}`);
+        }
+        return workspace;
+    }
+    getWorkspace(workspaceId) {
+        const workspace = this.workspaces.get(workspaceId);
+        if (!workspace)
+            throw new Error(`Unknown workspaceId: ${workspaceId}`);
+        return workspace;
+    }
+    resolvePath(workspace, inputPath) {
+        const absolutePath = resolve(workspace.root, inputPath);
+        if (!isPathInsideRoot(absolutePath, workspace.root)) {
+            throw new Error(`Path is outside workspace root: ${inputPath}`);
+        }
+        if (!isPathInsideRoot(absolutePath, workspace.exposedPath.path)) {
+            throw new Error(`Path is outside exposed path: ${inputPath}`);
+        }
+        return absolutePath;
+    }
+    async resolveExistingPath(workspace, inputPath) {
+        const absolutePath = this.resolvePath(workspace, inputPath);
+        await assertRealPathInside(workspace, absolutePath, inputPath);
+        return absolutePath;
+    }
+    async resolveWritablePath(workspace, inputPath) {
+        const absolutePath = this.resolvePath(workspace, inputPath);
+        try {
+            await assertRealPathInside(workspace, absolutePath, inputPath);
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+            if (await pathExists(absolutePath))
+                throw error;
+            await assertRealPathInside(workspace, dirname(absolutePath), dirname(inputPath));
+        }
+        return absolutePath;
+    }
+    async readFile(workspaceId, path) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "read");
+        const absolutePath = await this.resolveExistingPath(workspace, path);
+        assertNonSensitiveWorkspacePath(formatWorkspacePath(absolutePath, workspace), "read");
+        return readFile(absolutePath, "utf8");
+    }
+    async writeFile(workspaceId, path, content) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const absolutePath = await this.resolveWritablePath(workspace, path);
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, content, "utf8");
+    }
+    async createFile(workspaceId, path, content) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const absolutePath = await this.resolveWritablePath(workspace, path);
+        await mkdir(dirname(absolutePath), { recursive: true });
+        try {
+            await writeFile(absolutePath, content, { encoding: "utf8", flag: "wx" });
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+                throw new Error(`File already exists: ${path}`);
+            }
+            throw error;
+        }
+    }
+    async editFile(workspaceId, path, oldText, newText) {
+        const current = await this.readFile(workspaceId, path);
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const matches = current.split(oldText).length - 1;
+        if (matches !== 1) {
+            throw new Error(`edit_file expected exactly one match, found ${matches}`);
+        }
+        await this.writeFile(workspaceId, path, current.replace(oldText, newText));
+        return matches;
+    }
+    async listDirectory(workspaceId, path) {
+        return (await this.listDirectoryEntries(workspaceId, path))
+            .map((entry) => `${entry.name}${entry.type === "directory" ? "/" : ""}`);
+    }
+    async listDirectoryEntries(workspaceId, path) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "read");
+        const directory = await this.resolveExistingPath(workspace, path);
+        const entries = await opendir(directory);
+        const results = [];
+        for await (const entry of entries) {
+            results.push(await pathInfo(join(directory, entry.name), workspace));
+        }
+        return results.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async tree(workspaceId, path, options = {}) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "read");
+        const root = await this.resolveExistingPath(workspace, path);
+        const maxDepth = normalizePositiveInteger(options.maxDepth, 2, 1000);
+        const maxEntries = normalizePositiveInteger(options.maxEntries, 200, 1000);
+        const includeFiles = options.includeFiles ?? true;
+        const results = [];
+        const walk = async (directory, depth) => {
+            if (results.length >= maxEntries)
+                return;
+            let entries;
+            try {
+                entries = await opendir(directory);
+            }
+            catch {
+                return;
+            }
+            const paths = [];
+            for await (const entry of entries) {
+                if (entry.isDirectory() && SKIPPED_TREE_DIRECTORIES.has(entry.name))
+                    continue;
+                paths.push(join(directory, entry.name));
+            }
+            paths.sort((a, b) => basename(a).localeCompare(basename(b)));
+            for (const entryPath of paths) {
+                if (results.length >= maxEntries)
+                    return;
+                const info = await pathInfo(entryPath, workspace);
+                if (includeFiles || info.type === "directory")
+                    results.push(info);
+                if (info.type === "directory" && depth < maxDepth) {
+                    await walk(entryPath, depth + 1);
+                }
+            }
+        };
+        await walk(root, 1);
+        return results;
+    }
+    async instructions(workspaceId, path, options = {}) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "read");
+        const target = await this.resolveInstructionTarget(workspace, path);
+        const directory = await instructionSearchDirectory(target);
+        const maxBytes = normalizePositiveInteger(options.maxBytes, 64 * 1024, 256 * 1024);
+        const files = [];
+        for (const directoryPath of ancestorDirectories(workspace.root, directory)) {
+            for (const name of INSTRUCTION_FILE_NAMES) {
+                const instructionPath = join(directoryPath, name);
+                try {
+                    const info = await lstat(instructionPath);
+                    if (!info.isFile())
+                        continue;
+                    const content = await readFile(instructionPath, "utf8");
+                    files.push({
+                        path: formatWorkspacePath(instructionPath, workspace),
+                        name,
+                        content: content.slice(0, maxBytes),
+                        size: info.size,
+                        truncated: info.size > maxBytes,
+                    });
+                }
+                catch {
+                    // Missing instruction files are expected in most directories.
+                }
+            }
+        }
+        return files;
+    }
+    async statPath(workspaceId, path) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "read");
+        const absolutePath = this.resolvePath(workspace, path);
+        await assertRealPathInside(workspace, absolutePath, path);
+        return pathInfo(absolutePath, workspace);
+    }
+    async resolveInstructionTarget(workspace, inputPath) {
+        const absolutePath = this.resolvePath(workspace, inputPath);
+        try {
+            await assertRealPathInside(workspace, absolutePath, inputPath);
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+            if (await pathExists(absolutePath))
+                throw error;
+            await assertRealPathInside(workspace, await nearestExistingParent(absolutePath), inputPath);
+        }
+        return absolutePath;
+    }
+    async createDirectory(workspaceId, path) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const absolutePath = this.resolvePath(workspace, path);
+        await assertRealPathInside(workspace, await nearestExistingParent(absolutePath), path);
+        await mkdir(absolutePath, { recursive: true });
+    }
+    async deletePath(workspaceId, path, recursive = false) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const absolutePath = this.resolvePath(workspace, path);
+        await assertRealPathInside(workspace, absolutePath, path);
+        assertNotWorkspaceRoot(workspace, absolutePath, "delete");
+        await rm(absolutePath, { recursive, force: false });
+    }
+    async movePath(workspaceId, fromPath, toPath) {
+        const workspace = this.getWorkspace(workspaceId);
+        assertPermission(workspace.exposedPath, "write");
+        const absoluteFromPath = this.resolvePath(workspace, fromPath);
+        const absoluteToPath = await this.resolveWritablePath(workspace, toPath);
+        await assertRealPathInside(workspace, absoluteFromPath, fromPath);
+        assertNotWorkspaceRoot(workspace, absoluteFromPath, "move");
+        await mkdir(dirname(absoluteToPath), { recursive: true });
+        await rename(absoluteFromPath, absoluteToPath);
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function formatWorkspacePath(path, workspace) {
+    const relationship = relative(workspace.root, path);
+    return relationship ? relationship.split(sep).join("/") : ".";
+}
+async function pathInfo(path, workspace) {
+    const info = await lstat(path);
+    return {
+        path: formatWorkspacePath(path, workspace),
+        name: basename(path) || ".",
+        type: info.isDirectory() ? "directory" : info.isFile() ? "file" : info.isSymbolicLink() ? "symlink" : "other",
+        size: info.size,
+        modifiedAt: info.mtime.toISOString(),
+    };
+}
+function assertNotWorkspaceRoot(workspace, path, action) {
+    if (resolve(path) !== resolve(workspace.root))
+        return;
+    throw new Error(`Refusing to ${action} the workspace root`);
+}
+async function assertRealPathInside(workspace, path, inputPath) {
+    const realPath = await realpath(path);
+    if (!isPathInsideRoot(realPath, workspace.root) || !isPathInsideRoot(realPath, workspace.exposedPath.path)) {
+        throw new Error(`Path resolves outside workspace: ${inputPath}`);
+    }
+}
+async function nearestExistingParent(path) {
+    let current = path;
+    while (!(await pathExists(current))) {
+        const parent = dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+    return current;
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        throw error;
+    }
+}
+function isNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function normalizePositiveInteger(value, fallback, max) {
+    return Number.isInteger(value) && value !== undefined && value > 0 ? Math.min(value, max) : fallback;
+}
+async function instructionSearchDirectory(path) {
+    try {
+        const info = await lstat(path);
+        return info.isDirectory() ? path : dirname(path);
+    }
+    catch {
+        return dirname(path);
+    }
+}
+function ancestorDirectories(root, directory) {
+    const resolvedRoot = resolve(root);
+    let current = resolve(directory);
+    const directories = [];
+    while (isPathInsideRoot(current, resolvedRoot)) {
+        directories.push(current);
+        if (current === resolvedRoot)
+            break;
+        current = dirname(current);
+    }
+    return directories.reverse();
+}
+const SKIPPED_TREE_DIRECTORIES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".cache",
+]);
+const INSTRUCTION_FILE_NAMES = ["AGENTS.md", "CLAUDE.md"];

package/docs/agent-instructions.md

@@ -0,0 +1,65 @@
+# Agent Instructions
+
+Use these instructions when connecting an MCP-capable agent to Workspace
+Linker.
+
+## First Call
+
+Call `get_computer_info` before any workspace action. Read:
+
+- available scopes
+- workspace paths and names
+- permissions
+- `computerOperationRegistry`
+- local/public MCP URL status
+- safety boundaries
+
+## Normal Flow
+
+1. Choose one scope from `get_computer_info`.
+2. Call `computer_operation` with the generic envelope:
+
+```json
+{
+  "scope": "workspace-id",
+  "op": "file.list",
+  "target": ".",
+  "input": {},
+  "options": {}
+}
+```
+
+3. Use dotted operation names from `computerOperationRegistry`.
+4. Use write, shell, command, Codex, or screen operations only when the selected
+   scope reports the required permission.
+5. Call `get_operation_history` when debugging recent actions or connection
+   behavior.
+
+## Preferred Operations
+
+- Inspect files: `file.list`, `file.read`, `file.search`
+- Edit files: `file.write`, `file.edit`, `file.patch`
+- Git inspection: `git.status`, `git.diff`
+- Git mutation: `git.stage`, `git.commit`
+- Package commands: `package.run`
+- Shell command: `command.run`
+
+The exact list can grow. Always prefer names returned by
+`computerOperationRegistry`.
+
+## Sensitive Files
+
+Do not request secrets unless the user explicitly asks outside Workspace
+Linker. Direct reads and text searches block common sensitive files by default,
+including `.env*`, private keys, credential JSON files, and cloud CLI
+credential folders. Treat missing matches in those files as an intentional
+safety boundary.
+
+## Avoid By Default
+
+Do not call compatibility tools such as `list_workspaces`, `open_workspace`, or
+`workspace_operation` unless the MCP client cannot send the generic
+`computer_operation` envelope.
+
+Do not assume shell or write access. Computer Linker may expose read-only,
+coding, or full-trust scopes.

package/docs/alpha-evidence.example.json

@@ -0,0 +1,54 @@
+{
+  "kind": "computer-linker-alpha-evidence",
+  "schemaVersion": 1,
+  "testedAt": "2026-06-24T00:00:00.000Z",
+  "package": {
+    "name": "computer-linker",
+    "version": "0.1.0"
+  },
+  "git": {
+    "head": "replace-with-tested-git-head",
+    "shortHead": "replace-head"
+  },
+  "environment": {
+    "platform": "win32",
+    "arch": "x64",
+    "node": "v22.x"
+  },
+  "target": {
+    "client": "External MCP client",
+    "exposure": "openai",
+    "tunnelOrUrl": "redacted-tunnel-id-or-public-origin",
+    "mcpPath": "/mcp",
+    "scope": "app"
+  },
+  "checks": [
+    {
+      "id": "external-mcp-tool-flow",
+      "status": "pass",
+      "evidence": "External MCP client called get_computer_info, computer_operation, and get_operation_history successfully."
+    },
+    {
+      "id": "tunnel-transport",
+      "status": "pass",
+      "evidence": "Tunnel exposure connected from outside 127.0.0.1 and reached the local MCP server."
+    },
+    {
+      "id": "mcp-only-public-surface",
+      "status": "pass",
+      "evidence": "Public exposure allowed /mcp and did not expose /api/v1 or /healthz."
+    },
+    {
+      "id": "operation-history-reviewed",
+      "status": "pass",
+      "evidence": "history --view connections and history --view last showed the expected external MCP session and no secret payloads."
+    },
+    {
+      "id": "client-instructions-usable",
+      "status": "pass",
+      "evidence": "README Agent Instructions produced the expected first operations in the external client."
+    }
+  ],
+  "redactionConfirmed": true,
+  "notes": "Do not store owner tokens, API keys, bearer headers, screenshots, or private file contents in this evidence file."
+}

package/docs/api-compatibility.md

@@ -0,0 +1,56 @@
+# API Compatibility
+
+Computer Linker is still `0.x`, but the public MCP surface is intentionally
+small and treated as the product contract.
+
+## Stable MCP Surface
+
+Default MCP clients should use only these tools:
+
+- `get_computer_info`
+- `computer_operation`
+- `get_operation_history`
+
+The stable `computer_operation` request envelope is:
+
+```json
+{
+  "scope": "workspace-id",
+  "op": "file.list",
+  "target": ".",
+  "input": {},
+  "options": {}
+}
+```
+
+The stable operation result envelope includes:
+
+- `ok`
+- `operationId`
+- `scope`
+- `op`
+- `startedAt`
+- `durationMs`
+- `data`
+- `error`
+- `warnings`
+
+New dotted operations, new optional fields, and additional diagnostic metadata
+are non-breaking additions.
+
+## Compatibility Tools
+
+Tools such as `list_workspaces`, `open_workspace`, and `workspace_operation`
+exist for older clients and migration. New clients should not depend on them
+unless a specific MCP client cannot use the generic `computer_operation`
+contract.
+
+Removing or renaming a default MCP tool, removing required envelope fields, or
+changing operation semantics is a breaking change and must be called out in the
+changelog.
+
+## JSON API
+
+The JSON API under `/api/v1` is for local and trusted-private diagnostics,
+SDK usage, and health checks. Public cloud exposure should route only `/mcp`
+unless an operator intentionally exposes more.