@easonwumac/computer-linker 0.1.2

package/dist/api.js

@@ -0,0 +1,360 @@
+import { errorMessage, readAuditEvents, writeAuditEvent, writeAuthFailureEvent } from "./audit.js";
+import { workspaceCapabilityPolicy } from "./capability-policy.js";
+import { getLocalPortCapabilities, getLocalPortDoctor } from "./capabilities.js";
+import { chatGptSetupStatus } from "./chatgpt.js";
+import { computerOperationContract, publicComputerOperationRegistry } from "./computer-operation-registry.js";
+import { computerOperationAuditFields, getComputerInfo, getMcpClientSetup, getOperationHistory, runComputerOperation } from "./computer-contract.js";
+import { loadConfig } from "./config.js";
+import { historyInsight } from "./history-insights.js";
+import { isAuthorizedLocalPortRequest } from "./http-auth.js";
+import { PermissionDeniedError } from "./permissions.js";
+import { parseChatGptProfileMode } from "./profile.js";
+import { listTunnelProcesses } from "./tunnels.js";
+import { WorkspaceRegistry } from "./workspaces.js";
+import { allowedWorkspaceOperations, normalizeWorkspaceOperationInput, publicWorkspaceOperationRegistry, runWorkspaceOperation, workspaceOperationContract, workspaceOperationRegistry, workspaceOperationAuditFields, } from "./workspace-operations.js";
+export function registerApiRoutes(app) {
+    app.use("/api/v1", (req, res, next) => {
+        if (!isAuthorizedLocalPortRequest(req, loadConfig().ownerToken)) {
+            writeAuthFailureEvent({
+                surface: "api",
+                method: req.method,
+                requestPath: requestPath(req),
+                remoteAddress: req.ip,
+            });
+            res.status(401).json({ ok: false, error: "Unauthorized" });
+            return;
+        }
+        next();
+    });
+    app.get("/api/v1/health", (_req, res) => {
+        const config = loadConfig();
+        res.json({ ok: true, data: { name: "computer-linker", machineId: config.machineId, machineName: config.machineName } });
+    });
+    app.get("/api/v1/capabilities", (_req, res) => {
+        res.json({ ok: true, data: getLocalPortCapabilities() });
+    });
+    app.get("/api/v1/workspaces", (_req, res) => {
+        res.json({ ok: true, data: workspacesData() });
+    });
+    app.get("/api/v1/history", (req, res) => {
+        res.json({ ok: true, data: historyData(req.query) });
+    });
+    app.post("/api/v1/workspace-operation", apiRoute(async (req) => {
+        const input = workspaceOperationInput(req.body);
+        return withWorkspace(req.body, "workspace_operation", workspaceOperationAuditFields(input), async (registry, workspace) => (runWorkspaceOperation(registry, workspace, input)));
+    }));
+    app.post("/api/v1/control", apiRoute(async (req) => control(req)));
+}
+function apiRoute(handler) {
+    return (req, res) => {
+        handler(req)
+            .then((data) => res.json({ ok: true, data }))
+            .catch((error) => sendApiError(res, error));
+    };
+}
+async function withWorkspace(body, tool, fields, run) {
+    const workspaceRef = requiredString(body.workspace ?? body.workspaceRef, "workspace");
+    const registry = new WorkspaceRegistry(loadConfig());
+    const workspace = await registry.openWorkspace(workspaceRef);
+    return auditedApiCall(tool, {
+        workspaceId: workspace.exposedPath.id,
+        workspaceRoot: workspace.root,
+        workspaceRef,
+        ...fields,
+    }, async () => run(registry, workspace));
+}
+async function control(req) {
+    const action = requiredString(req.body.action, "action");
+    switch (action) {
+        case "get_computer_info":
+        case "computer_info":
+            return getComputerInfo();
+        case "client_setup":
+        case "mcp_client_setup":
+            return getMcpClientSetup({ tunnels: listTunnelProcesses() });
+        case "get_capabilities":
+        case "capabilities":
+            return getLocalPortCapabilities();
+        case "doctor":
+            return getLocalPortDoctor();
+        case "chatgpt_setup":
+            return chatGptSetupData(req.body.input && typeof req.body.input === "object" ? req.body.input : req.body);
+        case "list_workspaces":
+        case "workspaces":
+            return workspacesData();
+        case "history":
+            return historyData(req.body.filters && typeof req.body.filters === "object" ? req.body.filters : req.body);
+        case "history_insight":
+            return historyInsightData(req.body.filters && typeof req.body.filters === "object" ? req.body.filters : req.body);
+        case "get_operation_history":
+        case "operation_history":
+            return getOperationHistory(req.body.input && typeof req.body.input === "object" ? req.body.input : req.body);
+        case "operation_registry":
+            return operationRegistryData(req.body.input && typeof req.body.input === "object" ? req.body.input : req.body);
+        case "computer_operation_registry":
+            return computerOperationRegistryData(req.body.input && typeof req.body.input === "object" ? req.body.input : req.body);
+        case "workspace_operation_registry":
+            return workspaceOperationRegistryData(req.body.input && typeof req.body.input === "object" ? req.body.input : req.body);
+        case "computer_operation":
+            return auditedApiCall("computer_operation", await computerOperationAuditFields({
+                scope: optionalString(req.body.scope),
+                op: optionalString(req.body.op),
+                target: optionalString(req.body.target),
+                input: req.body.input && typeof req.body.input === "object" ? req.body.input : {},
+                options: req.body.options && typeof req.body.options === "object" ? req.body.options : {},
+            }), async () => runComputerOperation({
+                scope: optionalString(req.body.scope),
+                op: optionalString(req.body.op),
+                target: optionalString(req.body.target),
+                input: req.body.input && typeof req.body.input === "object" ? req.body.input : {},
+                options: req.body.options && typeof req.body.options === "object" ? req.body.options : {},
+            }), operationResultSucceeded);
+        case "workspace_operation":
+        case "operation": {
+            const body = controlWorkspaceOperationBody(req.body);
+            const input = workspaceOperationInput(body);
+            return withWorkspace(body, "workspace_operation", workspaceOperationAuditFields(input), async (registry, workspace) => (runWorkspaceOperation(registry, workspace, input)));
+        }
+        default:
+            throw new Error("action must be one of: get_computer_info, client_setup, get_capabilities, doctor, list_workspaces, history, history_insight, get_operation_history, operation_registry, computer_operation_registry, workspace_operation_registry, computer_operation, workspace_operation, operation");
+    }
+}
+function controlWorkspaceOperationBody(body) {
+    if (body.op || body.operation)
+        return body;
+    const inputBody = body.input && typeof body.input === "object" ? body.input : undefined;
+    if (!inputBody)
+        return body;
+    return { ...inputBody, workspace: body.workspace ?? inputBody.workspace };
+}
+function workspacesData() {
+    const config = loadConfig();
+    const registry = new WorkspaceRegistry(config);
+    return {
+        machineId: config.machineId,
+        machineName: config.machineName,
+        workspaces: registry.listDefinedWorkspaces().map((workspace) => ({
+            ...workspace,
+            capabilityPolicy: workspaceCapabilityPolicy(workspace.permissions),
+            allowedOperations: allowedWorkspaceOperations(workspace.permissions),
+        })),
+    };
+}
+function chatGptSetupData(input) {
+    return chatGptSetupStatus(loadConfig(), parseChatGptProfileMode(optionalString(input.mode), "chatgpt_setup mode"), {
+        tunnels: listTunnelProcesses(),
+    });
+}
+function historyData(input) {
+    return {
+        events: readAuditEvents({
+            type: auditType(input.type),
+            success: optionalBoolean(input.success),
+            tool: optionalString(input.tool),
+            workspaceId: optionalString(input.workspaceId),
+            query: optionalString(input.q ?? input.query),
+            limit: optionalPositiveInteger(input.limit),
+        }),
+    };
+}
+function historyInsightData(input) {
+    return historyInsight({
+        view: optionalString(input.view),
+        workspaceId: optionalString(input.workspaceId ?? input.workspace),
+        query: optionalString(input.q ?? input.query),
+        limit: optionalPositiveInteger(input.limit),
+    });
+}
+function operationRegistryData(input) {
+    const contract = optionalString(input.contract ?? input.compatibility);
+    return contract === "workspace"
+        ? workspaceOperationRegistryData(input)
+        : computerOperationRegistryData(input);
+}
+function computerOperationRegistryData(input) {
+    const category = optionalString(input.category);
+    const permission = optionalString(input.permission);
+    const query = optionalString(input.q ?? input.query)?.toLowerCase();
+    const operations = publicComputerOperationRegistry().filter((operation) => (matchesComputerOperationCategory(operation, category) &&
+        matchesComputerOperationPermission(operation, permission) &&
+        matchesComputerOperationQuery(operation, query)));
+    return {
+        kind: "computer-operation-registry",
+        schemaVersion: 1,
+        contract: computerOperationContract,
+        filters: {
+            contract: "computer",
+            category,
+            permission,
+            query,
+        },
+        count: operations.length,
+        operations,
+        compatibility: {
+            workspaceRegistry: {
+                action: "operation_registry",
+                input: { contract: "workspace" },
+            },
+        },
+    };
+}
+function workspaceOperationRegistryData(input) {
+    const category = optionalString(input.category);
+    const permission = optionalString(input.permission);
+    const query = optionalString(input.q ?? input.query)?.toLowerCase();
+    const operations = publicWorkspaceOperationRegistry(workspaceOperationRegistry.filter((operation) => (matchesOperationCategory(operation, category) &&
+        matchesOperationPermission(operation, permission) &&
+        matchesOperationQuery(operation, query))));
+    return {
+        kind: "operation-registry",
+        schemaVersion: 1,
+        contract: workspaceOperationContract,
+        filters: {
+            contract: "workspace",
+            category,
+            permission,
+            query,
+        },
+        count: operations.length,
+        operations,
+    };
+}
+function matchesComputerOperationCategory(operation, category) {
+    if (!category)
+        return true;
+    if (operation.category === category)
+        return true;
+    if (category === "search")
+        return operation.op === "file.search" || operation.op === "code.search_symbols";
+    if (category === "coding")
+        return operation.category === "code";
+    if (category === "files")
+        return operation.category === "file";
+    if (category === "metadata")
+        return operation.category === "history";
+    return false;
+}
+function matchesComputerOperationPermission(operation, permission) {
+    return !permission || operation.permission === permission;
+}
+function matchesComputerOperationQuery(operation, query) {
+    if (!query)
+        return true;
+    return [
+        operation.op,
+        operation.category,
+        operation.permission,
+        operation.description,
+        operation.boundary,
+        operation.target ?? "",
+        operation.backendOperation,
+        operation.legacyWorkspaceOperation,
+        ...operation.capabilities,
+        ...operation.requiredInput,
+        ...operation.optionalInput,
+        ...operation.options,
+    ].some((value) => value.toLowerCase().includes(query));
+}
+function matchesOperationCategory(operation, category) {
+    return !category || operation.category === category;
+}
+function matchesOperationPermission(operation, permission) {
+    return !permission || operation.permission === permission;
+}
+function matchesOperationQuery(operation, query) {
+    if (!query)
+        return true;
+    return [
+        operation.operation,
+        operation.name,
+        operation.category,
+        operation.permission,
+        operation.description,
+        operation.boundary,
+        ...operation.capabilities,
+        ...operation.requiredFields,
+        ...operation.optionalFields,
+    ].some((value) => value.toLowerCase().includes(query));
+}
+async function auditedApiCall(tool, fields, run, success) {
+    const startedAt = performance.now();
+    try {
+        const result = await run();
+        writeAuditEvent({
+            type: "tool_call",
+            tool,
+            success: success ? success(result) : true,
+            durationMs: Math.round(performance.now() - startedAt),
+            ...fields,
+        });
+        return result;
+    }
+    catch (error) {
+        writeAuditEvent({
+            type: "tool_call",
+            tool,
+            success: false,
+            durationMs: Math.round(performance.now() - startedAt),
+            error: errorMessage(error),
+            ...fields,
+        });
+        throw error;
+    }
+}
+function operationResultSucceeded(result) {
+    return !(result && typeof result === "object" && result.ok === false);
+}
+function sendApiError(res, error) {
+    const status = error instanceof PermissionDeniedError ? 403 : 400;
+    res.status(status).json({ ok: false, error: errorMessage(error) });
+}
+function requiredString(value, name) {
+    const text = optionalString(value);
+    if (!text)
+        throw new Error(`${name} is required`);
+    return text;
+}
+function optionalString(value) {
+    const text = String(value ?? "").trim();
+    return text || undefined;
+}
+function optionalPositiveInteger(value) {
+    return optionalBoundedPositiveInteger(value, 1000);
+}
+function optionalBoundedPositiveInteger(value, max) {
+    const text = optionalString(value);
+    if (!text)
+        return undefined;
+    const parsed = Number.parseInt(text, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, max) : undefined;
+}
+function optionalBoundedNonNegativeInteger(value, max) {
+    const text = optionalString(value);
+    if (!text)
+        return undefined;
+    const parsed = Number.parseInt(text, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.min(parsed, max) : undefined;
+}
+function optionalBoolean(value) {
+    if (value === true || value === "true" || value === "on" || value === "1")
+        return true;
+    if (value === false || value === "false" || value === "off" || value === "0")
+        return false;
+    return undefined;
+}
+function workspaceOperationInput(body) {
+    return normalizeWorkspaceOperationInput(body);
+}
+function auditType(value) {
+    const text = optionalString(value);
+    return text === "tool_call" || text === "workspace_open" || text === "mcp_session" || text === "auth_failure" || text === "admin_action" ? text : undefined;
+}
+function optionalStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const paths = value.map(optionalString).filter((path) => Boolean(path));
+    return paths.length ? paths.slice(0, 100) : undefined;
+}
+function requestPath(req) {
+    return `${req.baseUrl}${req.path}`;
+}

package/dist/audit.d.ts

@@ -0,0 +1,70 @@
+export interface AuditEvent {
+    timestamp: string;
+    type: "tool_call" | "workspace_open" | "mcp_session" | "auth_failure" | "admin_action" | "tunnel_event";
+    success: boolean;
+    durationMs?: number;
+    tool?: string;
+    workspaceId?: string;
+    workspaceRoot?: string;
+    workspaceRef?: string;
+    path?: string;
+    requestPath?: string;
+    remoteAddress?: string;
+    workingDirectory?: string;
+    commandPreview?: string;
+    operation?: string;
+    target?: string;
+    detail?: string;
+    replay?: AuditReplayTemplate;
+    error?: string;
+    provider?: string;
+    tunnelId?: string;
+    externalSessionId?: string;
+    requestId?: string;
+    cmdRequestId?: string;
+    rpcRequestId?: string;
+    tunnelRequestId?: string;
+    severity?: "info" | "warn" | "error";
+    statusCode?: number;
+}
+export interface AuditReplayTemplate {
+    action: "workspace_operation";
+    replayable: boolean;
+    reason?: string;
+    requiresInput?: string[];
+    input: {
+        op: string;
+        target?: string;
+        input: Record<string, unknown>;
+        options: Record<string, unknown>;
+    };
+}
+export type AuditEventInput = Omit<AuditEvent, "timestamp">;
+export interface ReadAuditEventsOptions {
+    limit?: number;
+    type?: AuditEvent["type"];
+    success?: boolean;
+    tool?: string;
+    workspaceId?: string;
+    query?: string;
+}
+export declare function writeAuditEvent(event: AuditEventInput): void;
+export declare function writeAuthFailureEvent(input: {
+    surface: "api" | "mcp";
+    method: string;
+    requestPath: string;
+    remoteAddress?: string;
+    detail?: string;
+}): void;
+export declare function writeAdminActionEvent(input: {
+    action: string;
+    success?: boolean;
+    workspaceId?: string;
+    path?: string;
+    detail?: string;
+    error?: string;
+}): void;
+export declare function readRecentAuditEvents(limit?: number): AuditEvent[];
+export declare function readAuditEvents(options?: ReadAuditEventsOptions): AuditEvent[];
+export declare function errorMessage(error: unknown): string;
+export declare function previewCommand(command: string): string;

package/dist/audit.js

@@ -0,0 +1,102 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { auditLogPath } from "./config.js";
+export function writeAuditEvent(event) {
+    const path = auditLogPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify({ timestamp: new Date().toISOString(), ...event })}\n`, {
+        mode: 0o600,
+    });
+}
+export function writeAuthFailureEvent(input) {
+    writeAuditEvent({
+        type: "auth_failure",
+        success: false,
+        tool: input.surface,
+        requestPath: input.requestPath,
+        remoteAddress: input.remoteAddress,
+        detail: input.detail ?? "unauthorized",
+    });
+}
+export function writeAdminActionEvent(input) {
+    const detail = input.detail && input.detail !== input.action
+        ? `${input.action}: ${input.detail}`
+        : input.action;
+    writeAuditEvent({
+        type: "admin_action",
+        success: input.success ?? true,
+        tool: "cli",
+        workspaceId: input.workspaceId,
+        path: input.path,
+        detail,
+        error: input.error,
+    });
+}
+export function readRecentAuditEvents(limit = 50) {
+    return readAuditEvents({ limit });
+}
+export function readAuditEvents(options = {}) {
+    const path = auditLogPath();
+    if (!existsSync(path))
+        return [];
+    let events = readFileSync(path, "utf8")
+        .trimEnd()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    if (options.type)
+        events = events.filter((event) => event.type === options.type);
+    if (options.success !== undefined)
+        events = events.filter((event) => event.success === options.success);
+    if (options.tool)
+        events = events.filter((event) => event.tool === options.tool);
+    if (options.workspaceId) {
+        events = events.filter((event) => event.workspaceId === options.workspaceId || event.workspaceRef === options.workspaceId);
+    }
+    if (options.query) {
+        const query = options.query.toLowerCase();
+        events = events.filter((event) => auditSearchText(event).includes(query));
+    }
+    if (options.limit && options.limit > 0) {
+        events = events.slice(Math.max(0, events.length - options.limit));
+    }
+    return events.reverse();
+}
+function auditSearchText(event) {
+    return [
+        event.timestamp,
+        event.type,
+        event.tool,
+        event.workspaceId,
+        event.workspaceRoot,
+        event.workspaceRef,
+        event.path,
+        event.requestPath,
+        event.remoteAddress,
+        event.workingDirectory,
+        event.commandPreview,
+        event.operation,
+        event.target,
+        event.detail,
+        event.error,
+        event.provider,
+        event.tunnelId,
+        event.externalSessionId,
+        event.requestId,
+        event.cmdRequestId,
+        event.rpcRequestId,
+        event.tunnelRequestId,
+        event.severity,
+        event.statusCode === undefined ? undefined : String(event.statusCode),
+    ]
+        .filter(Boolean)
+        .join("\n")
+        .toLowerCase();
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function previewCommand(command) {
+    const normalized = command.replace(/\s+/g, " ").trim();
+    return normalized.length > 160 ? `${normalized.slice(0, 157)}...` : normalized;
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,98 @@
+import { type ConfigDiagnostic } from "./config-diagnostics.js";
+import type { LocalPortConfig } from "./permissions.js";
+import { securityDiagnostics } from "./security.js";
+import { type ServiceStatus } from "./service.js";
+export interface CommandCapability {
+    name: string;
+    category: "agent" | "search" | "runtime" | "package-manager" | "vcs" | "shell" | "container";
+    importance: "required" | "recommended" | "optional";
+    available: boolean;
+    path?: string;
+    version?: string;
+    usedFor: string[];
+    install?: ToolInstallHint;
+    error?: string;
+}
+export interface ToolInstallHint {
+    macos?: string;
+    linux?: string;
+    windows?: string;
+    docs?: string;
+}
+export interface ToolReadiness {
+    kind: "computer-linker-tool-readiness";
+    schemaVersion: 1;
+    ready: boolean;
+    requiredMissing: string[];
+    recommendedMissing: string[];
+    availableRecommended: string[];
+    installHints: Array<{
+        name: string;
+        importance: CommandCapability["importance"];
+        usedFor: string[];
+        install?: ToolInstallHint;
+    }>;
+}
+export interface StartupReadinessCheck {
+    id: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+    detail?: string;
+}
+export interface StartupReadinessMode {
+    id: "start" | "tunnel-cloudflare" | "tunnel-tailscale" | "tunnel-openai" | "stdio" | "service";
+    title: string;
+    command: string;
+    persistent: boolean;
+    useWhen: string;
+}
+export interface StartupReadiness {
+    kind: "computer-linker-startup-readiness";
+    schemaVersion: 1;
+    ready: boolean;
+    platform: string;
+    recommendedMode: StartupReadinessMode["id"];
+    localMcpUrl: string;
+    localApiUrl: string;
+    modes: StartupReadinessMode[];
+    service: {
+        platform: string;
+        serviceName: string;
+        label: string;
+        command: string;
+        manifestPath: string;
+        manifestExists: boolean | null;
+        statusCommands: string[];
+        profileCommand: string;
+        profileBundleCommand: string;
+        installDryRunCommand: string;
+        uninstallDryRunCommand: string;
+    };
+    checks: StartupReadinessCheck[];
+    nextActions: string[];
+}
+export interface ReleaseReadinessCheck {
+    id: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+    detail?: string;
+}
+export interface ReleaseReadiness {
+    kind: "computer-linker-release-readiness";
+    schemaVersion: 1;
+    ready: boolean;
+    status: "ready" | "needs_attention" | "blocked";
+    checks: ReleaseReadinessCheck[];
+    blockingReasons: string[];
+    warnings: string[];
+    recommendedGate: string;
+}
+export declare function getLocalPortCapabilities(): unknown;
+export declare function getLocalPortDoctor(): unknown;
+export declare function startupReadiness(config: LocalPortConfig, service?: ServiceStatus): StartupReadiness;
+export declare function releaseReadiness(config: LocalPortConfig, input: {
+    toolReadiness: ToolReadiness;
+    startup: StartupReadiness;
+    configFindings: ConfigDiagnostic[];
+    securityFindings: ReturnType<typeof securityDiagnostics>;
+}): ReleaseReadiness;