@easonwumac/computer-linker 0.1.2

package/dist/config-diagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { LocalPortConfig } from "./permissions.js";
+export type ConfigDiagnosticSeverity = "info" | "warning" | "critical";
+export interface ConfigDiagnostic {
+    id: string;
+    severity: ConfigDiagnosticSeverity;
+    title: string;
+    detail: string;
+    workspaceId?: string;
+    path?: string;
+}
+export declare function configDiagnostics(config: LocalPortConfig): ConfigDiagnostic[];

package/dist/config-diagnostics.js

@@ -0,0 +1,185 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+export function configDiagnostics(config) {
+    const findings = [];
+    const workspaceIds = new Set();
+    const workspacePaths = new Map();
+    if (!config.machineName?.trim()) {
+        findings.push({
+            id: "machine-name-missing",
+            severity: "critical",
+            title: "Machine name is missing",
+            detail: "machineName is required so clients can identify this computer.",
+        });
+    }
+    if (config.publicBaseUrl && !validUrl(config.publicBaseUrl)) {
+        findings.push({
+            id: "public-base-url-invalid",
+            severity: "critical",
+            title: "Public base URL is invalid",
+            detail: "publicBaseUrl must be a valid URL origin.",
+        });
+    }
+    if (config.workspaces.length === 0) {
+        findings.push({
+            id: "workspace-missing",
+            severity: "critical",
+            title: "No workspace scopes are configured",
+            detail: "At least one folder-backed scope is required before clients can operate this computer.",
+        });
+    }
+    for (const workspace of config.workspaces) {
+        const workspaceId = workspace.id?.trim();
+        if (!workspaceId) {
+            findings.push({
+                id: "workspace-id-missing",
+                severity: "critical",
+                title: "Workspace id is missing",
+                detail: "Each configured scope needs a stable id.",
+                path: workspace.path,
+            });
+        }
+        else if (workspaceIds.has(workspaceId)) {
+            findings.push({
+                id: "workspace-id-duplicate",
+                severity: "critical",
+                title: "Workspace id is duplicated",
+                detail: `More than one configured scope uses id ${workspaceId}.`,
+                workspaceId,
+                path: workspace.path,
+            });
+        }
+        else {
+            workspaceIds.add(workspaceId);
+        }
+        const pathFinding = workspacePathFinding(workspace.path, workspaceId);
+        if (pathFinding)
+            findings.push(pathFinding);
+        const pathKey = normalizedWorkspacePathKey(workspace.path);
+        if (pathKey) {
+            const first = workspacePaths.get(pathKey);
+            if (first) {
+                findings.push({
+                    id: "workspace-path-duplicate",
+                    severity: "warning",
+                    title: "Workspace path is duplicated",
+                    detail: `This scope points at the same folder as ${first.workspaceId ?? first.path}. Keep one scope per folder unless separate permissions are intentional.`,
+                    workspaceId,
+                    path: workspace.path,
+                });
+            }
+            else {
+                workspacePaths.set(pathKey, { workspaceId, path: workspace.path });
+            }
+        }
+        if (!workspace.permissions.read && !workspace.permissions.write && !workspace.permissions.shell && !workspace.permissions.codex && !workspace.permissions.screen) {
+            findings.push({
+                id: "workspace-no-permissions",
+                severity: "warning",
+                title: "Workspace has no enabled permissions",
+                detail: "This scope is visible to clients but has no useful operation permissions.",
+                workspaceId,
+                path: workspace.path,
+            });
+        }
+        if (workspace.permissions.write && !workspace.permissions.read) {
+            findings.push({
+                id: "workspace-write-without-read",
+                severity: "warning",
+                title: "Write permission is enabled without read",
+                detail: "Most editing workflows need read permission to verify current content before writing.",
+                workspaceId,
+                path: workspace.path,
+            });
+        }
+        if ((workspace.permissions.shell || workspace.permissions.codex) && !workspace.policy) {
+            findings.push({
+                id: "workspace-execution-policy-missing",
+                severity: "warning",
+                title: "Execution policy is missing",
+                detail: "Shell or Codex scopes should set allowedCommands, maxRuntimeSeconds, and maxOutputBytes before broad use.",
+                workspaceId,
+                path: workspace.path,
+            });
+        }
+        else if ((workspace.permissions.shell || workspace.permissions.codex) && !workspace.policy?.allowedCommands?.length) {
+            findings.push({
+                id: "workspace-command-allowlist-missing",
+                severity: "warning",
+                title: "Command allowlist is missing",
+                detail: "Without allowedCommands, any command can run from this scope when shell or Codex permission is enabled.",
+                workspaceId,
+                path: workspace.path,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        findings.push({
+            id: "config-baseline-ok",
+            severity: "info",
+            title: "Configuration baseline is valid",
+            detail: "Configured scopes are usable and no immediate config issues were found.",
+        });
+    }
+    return findings;
+}
+function normalizedWorkspacePathKey(path) {
+    const text = path?.trim();
+    if (!text)
+        return undefined;
+    const resolved = resolve(text);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function workspacePathFinding(path, workspaceId) {
+    if (!path?.trim()) {
+        return {
+            id: "workspace-path-missing",
+            severity: "critical",
+            title: "Workspace path is missing",
+            detail: "Folder-backed scopes require a path.",
+            workspaceId,
+        };
+    }
+    if (!existsSync(path)) {
+        return {
+            id: "workspace-path-missing-on-disk",
+            severity: "critical",
+            title: "Workspace path does not exist",
+            detail: "Operations cannot run until the configured path exists.",
+            workspaceId,
+            path,
+        };
+    }
+    try {
+        if (!statSync(path).isDirectory()) {
+            return {
+                id: "workspace-path-not-directory",
+                severity: "critical",
+                title: "Workspace path is not a directory",
+                detail: "Folder-backed scopes must point at a directory.",
+                workspaceId,
+                path,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            id: "workspace-path-unreadable",
+            severity: "critical",
+            title: "Workspace path cannot be inspected",
+            detail: error instanceof Error ? error.message : String(error),
+            workspaceId,
+            path,
+        };
+    }
+    return undefined;
+}
+function validUrl(value) {
+    try {
+        void new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import { type LocalPortConfig } from "./permissions.js";
+export declare function configDir(): string;
+export declare function configPath(): string;
+export declare function auditLogPath(): string;
+export declare function codexRunsPath(): string;
+export declare function oauthStatePath(): string;
+export declare function loadConfig(): LocalPortConfig;
+export declare function writeDefaultConfig(): string;
+export declare function writeConfig(config: LocalPortConfig): string;
+export declare function generateOwnerToken(): string;

package/dist/config.js

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { defaultConfig, expandHomePath, normalizeConfig, } from "./permissions.js";
+export function configDir() {
+    return resolve(expandHomePath(firstNonBlank(process.env.COMPUTER_LINKER_CONFIG_DIR, process.env.WORKSPACE_LINKER_CONFIG_DIR, process.env.LOCALPORT_CONFIG_DIR) ?? join(homedir(), ".computer-linker")));
+}
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+export function auditLogPath() {
+    return join(configDir(), "audit.jsonl");
+}
+export function codexRunsPath() {
+    return join(configDir(), "codex-runs.jsonl");
+}
+export function oauthStatePath() {
+    return join(configDir(), "oauth-state.json");
+}
+export function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path)) {
+        writeConfig(defaultConfig());
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const normalized = normalizeConfig(withEnvOverrides(parsed));
+        if (!parsed.machineId?.trim()) {
+            writeConfig({
+                ...parsed,
+                machineId: normalized.machineId,
+            });
+        }
+        return normalized;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read ${path}: ${reason}`);
+    }
+}
+export function writeDefaultConfig() {
+    const path = configPath();
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, JSON.stringify({
+        ...defaultConfig(),
+        ownerToken: generateOwnerToken(),
+    }, null, 2) + "\n", { mode: 0o600 });
+    return path;
+}
+export function writeConfig(config) {
+    const path = configPath();
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, JSON.stringify(normalizeConfig(config), null, 2) + "\n", { mode: 0o600 });
+    return path;
+}
+export function generateOwnerToken() {
+    return randomBytes(32).toString("base64url");
+}
+function withEnvOverrides(config) {
+    return {
+        ...config,
+        publicBaseUrl: firstNonBlank(process.env.COMPUTER_LINKER_PUBLIC_BASE_URL, process.env.WORKSPACE_LINKER_PUBLIC_BASE_URL, process.env.LOCALPORT_PUBLIC_BASE_URL) ?? config.publicBaseUrl,
+        ownerToken: firstNonBlank(process.env.COMPUTER_LINKER_OWNER_TOKEN, process.env.WORKSPACE_LINKER_OWNER_TOKEN, process.env.LOCALPORT_OWNER_TOKEN) ?? config.ownerToken,
+    };
+}
+function firstNonBlank(...values) {
+    return values.find((value) => value !== undefined && value.trim().length > 0);
+}

package/dist/history-insights.d.ts

@@ -0,0 +1,132 @@
+import { type AuditEvent, type AuditReplayTemplate } from "./audit.js";
+export type HistoryInsightView = "summary" | "last" | "timeline" | "sessions" | "connections" | "failed_replay" | "debug_bundle";
+export interface HistoryInsightOptions {
+    view?: string;
+    limit?: number;
+    query?: string;
+    workspaceId?: string;
+    events?: AuditEvent[];
+}
+export interface CompactAuditEvent {
+    timestamp: string;
+    type: AuditEvent["type"];
+    success: boolean;
+    tool?: string;
+    workspaceId?: string;
+    workspaceRef?: string;
+    requestPath?: string;
+    remoteAddress?: string;
+    path?: string;
+    workingDirectory?: string;
+    commandPreview?: string;
+    operation?: string;
+    target?: string;
+    detail?: string;
+    replay?: AuditReplayTemplate;
+    error?: string;
+    durationMs?: number;
+    provider?: string;
+    tunnelId?: string;
+    externalSessionId?: string;
+    requestId?: string;
+    cmdRequestId?: string;
+    rpcRequestId?: string;
+    tunnelRequestId?: string;
+    severity?: "info" | "warn" | "error";
+    statusCode?: number;
+}
+export interface FailedReplayItem {
+    timestamp: string;
+    error?: string;
+    replayable: boolean;
+    reason?: string;
+    requiresInput?: string[];
+    request?: {
+        action: "workspace_operation";
+        workspace: string;
+        input: {
+            op: string;
+            target?: string;
+            input: Record<string, unknown>;
+            options: Record<string, unknown>;
+        };
+    };
+}
+export interface HistorySessionSummary {
+    key: string;
+    scope: "workspace" | "surface";
+    workspaceId?: string;
+    workspaceRef?: string;
+    surface?: string;
+    startedAt: string;
+    lastActivityAt: string;
+    totalEvents: number;
+    successfulEvents: number;
+    failedEvents: number;
+    tools: Record<string, number>;
+    operations: Record<string, number>;
+    lastEvent: CompactAuditEvent;
+    recentFailures: CompactAuditEvent[];
+}
+export interface HistoryConnectionSummary {
+    key: string;
+    scope: "tunnel" | "mcp" | "workspace" | "surface";
+    provider?: string;
+    tunnelId?: string;
+    externalSessionId?: string;
+    remoteAddress?: string;
+    startedAt: string;
+    lastActivityAt: string;
+    totalEvents: number;
+    successfulEvents: number;
+    failedEvents: number;
+    requestCount: number;
+    tools: Record<string, number>;
+    operations: Record<string, number>;
+    lastEvent: CompactAuditEvent;
+    recentFailures: CompactAuditEvent[];
+}
+export interface HistoryLastInsight {
+    event?: CompactAuditEvent;
+    workspaceOperation?: CompactAuditEvent;
+    failure?: CompactAuditEvent;
+    replay?: FailedReplayItem;
+    session?: HistorySessionSummary;
+    connection?: HistoryConnectionSummary;
+    suggestedNextActions: string[];
+}
+export interface HistoryInsight {
+    view: HistoryInsightView;
+    generatedAt: string;
+    filters: {
+        workspaceId?: string;
+        query?: string;
+        limit: number;
+    };
+    summary: {
+        totalEvents: number;
+        successfulEvents: number;
+        failedEvents: number;
+        lastEvent?: CompactAuditEvent;
+        lastWorkspaceOperation?: CompactAuditEvent;
+        recentFailures: CompactAuditEvent[];
+        toolCounts: Record<string, number>;
+        workspaceCounts: Record<string, number>;
+    };
+    last?: HistoryLastInsight;
+    timeline?: CompactAuditEvent[];
+    sessions?: HistorySessionSummary[];
+    connections?: HistoryConnectionSummary[];
+    failedReplay?: FailedReplayItem[];
+    debugBundle?: {
+        format: "computer-linker-debug-bundle-v1";
+        auditLogPath: string;
+        redactions: string[];
+        events: CompactAuditEvent[];
+        connections: HistoryConnectionSummary[];
+        failedReplay: FailedReplayItem[];
+    };
+}
+export declare function historyInsight(options?: HistoryInsightOptions): HistoryInsight;
+export declare function historyInsightFromEvents(events: AuditEvent[], options?: HistoryInsightOptions): HistoryInsight;
+export declare function historyInsightView(value: string | undefined): HistoryInsightView;