@revealui/harnesses 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+import { WorkboardManager } from './workboard/index.js';
+export { ConflictResult, SessionType, WorkboardEntry, WorkboardSession, WorkboardState, deriveSessionId, detectSessionType } from './workboard/index.js';
+
+/**
+ * Core types for the AI harness integration system.
+ * Mirrors packages/editors/src/types/core.ts for the harness domain.
+ */
+interface HarnessCapabilities {
+    /** Can generate code from a prompt */
+    generateCode: boolean;
+    /** Can analyze/explain existing code */
+    analyzeCode: boolean;
+    /** Can apply inline code edits */
+    applyEdit: boolean;
+    /** Can sync configuration files */
+    applyConfig: boolean;
+    /** Can query workboard state */
+    readWorkboard: boolean;
+    /** Can write workboard state */
+    writeWorkboard: boolean;
+}
+type ConfigSyncDirection = 'push' | 'pull';
+type HarnessCommand = {
+    type: 'generate-code';
+    prompt: string;
+    context?: string;
+    language?: string;
+} | {
+    type: 'analyze-code';
+    filePath: string;
+    question?: string;
+} | {
+    type: 'apply-edit';
+    filePath: string;
+    diff: string;
+} | {
+    type: 'apply-config';
+    configPath: string;
+    content: string;
+} | {
+    type: 'get-status';
+} | {
+    type: 'get-running-instances';
+} | {
+    type: 'sync-config';
+    direction: ConfigSyncDirection;
+} | {
+    type: 'diff-config';
+} | {
+    type: 'read-workboard';
+} | {
+    type: 'update-workboard';
+    sessionId: string;
+    task?: string;
+    files?: string[];
+};
+interface HarnessCommandResult {
+    success: boolean;
+    command: HarnessCommand['type'];
+    message?: string;
+    data?: unknown;
+}
+type HarnessEvent = {
+    type: 'harness-connected';
+    harnessId: string;
+} | {
+    type: 'harness-disconnected';
+    harnessId: string;
+} | {
+    type: 'generation-started';
+    taskId: string;
+} | {
+    type: 'generation-completed';
+    taskId: string;
+    output: string;
+} | {
+    type: 'error';
+    harnessId: string;
+    message: string;
+};
+interface HarnessInfo {
+    id: string;
+    name: string;
+    version?: string;
+    capabilities: HarnessCapabilities;
+}
+interface HarnessProcessInfo {
+    pid: number;
+    command: string;
+    harnessId: string;
+}
+interface ConfigSyncResult {
+    success: boolean;
+    harnessId: string;
+    direction: ConfigSyncDirection;
+    message?: string;
+}
+interface ConfigDiffEntry {
+    harnessId: string;
+    localExists: boolean;
+    ssdExists: boolean;
+    identical: boolean;
+}
+
+/**
+ * Contract every AI harness adapter must satisfy.
+ * Mirrors EditorAdapter from packages/editors.
+ *
+ * AI tools are external executables — never linked libraries.
+ * Communication is data-only: commands in, results out.
+ */
+interface HarnessAdapter {
+    /** Unique stable identifier, e.g. "claude-code", "cursor", "copilot" */
+    readonly id: string;
+    /** Human-readable display name */
+    readonly name: string;
+    /** Returns the static capability set for this harness */
+    getCapabilities(): HarnessCapabilities;
+    /** Returns live info (version, etc.) — may shell out */
+    getInfo(): Promise<HarnessInfo>;
+    /** True if the harness executable is on PATH and accessible */
+    isAvailable(): Promise<boolean>;
+    /** Execute a typed command against this harness */
+    execute(command: HarnessCommand): Promise<HarnessCommandResult>;
+    /** Subscribe to harness events; returns an unsubscribe function */
+    onEvent(handler: (event: HarnessEvent) => void): () => void;
+    /** Release all resources held by this adapter */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Adapter for Anthropic Claude Code (CLI: `claude`).
+ *
+ * Claude Code communicates via its CLI. Config lives at
+ * ~/.claude/settings.json and project-level .claude/settings.json.
+ * MCP integration is handled separately by @revealui/mcp.
+ *
+ * Workboard read/write requires REVEALUI_WORKBOARD_PATH to be set to the
+ * absolute path of the workboard.md file.
+ */
+declare class ClaudeCodeAdapter implements HarnessAdapter {
+    readonly id = "claude-code";
+    readonly name = "Claude Code";
+    private readonly eventHandlers;
+    private readonly workboardPath;
+    constructor(workboardPath?: string);
+    getCapabilities(): HarnessCapabilities;
+    getInfo(): Promise<HarnessInfo>;
+    isAvailable(): Promise<boolean>;
+    execute(command: HarnessCommand): Promise<HarnessCommandResult>;
+    onEvent(handler: (event: HarnessEvent) => void): () => void;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Stub adapter for GitHub Copilot.
+ *
+ * Copilot has no standalone CLI — it runs as a VS Code extension.
+ * This adapter is a stub for future integration once Copilot exposes
+ * a programmatic interface.
+ */
+declare class CopilotAdapter implements HarnessAdapter {
+    readonly id = "copilot";
+    readonly name = "GitHub Copilot";
+    private readonly eventHandlers;
+    getCapabilities(): HarnessCapabilities;
+    getInfo(): Promise<HarnessInfo>;
+    isAvailable(): Promise<boolean>;
+    execute(command: HarnessCommand): Promise<HarnessCommandResult>;
+    onEvent(handler: (event: HarnessEvent) => void): () => void;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Syncs harness config between local filesystem and SSD backup.
+ * Mirrors config-sync.ts from packages/editors.
+ */
+declare function syncConfig(harnessId: string, direction: ConfigSyncDirection, ssdBase?: string): ConfigSyncResult;
+/** Compares local vs SSD config for a harness. */
+declare function diffConfig(harnessId: string, ssdBase?: string): ConfigDiffEntry;
+
+/** Returns the local config file path for a given harness id, or undefined if unknown. */
+declare function getLocalConfigPath(harnessId: string): string | undefined;
+/** Returns the SSD config file path for a given harness id, or undefined if unknown. */
+declare function getSsdConfigPath(harnessId: string, ssdBase?: string): string | undefined;
+/** Returns ids of all harnesses with known config paths. */
+declare function getConfigurableHarnesses(): string[];
+
+/**
+ * Manages the lifecycle of HarnessAdapter instances.
+ * Mirrors EditorRegistry from packages/editors.
+ */
+declare class HarnessRegistry {
+    private readonly adapters;
+    /** Register an adapter. Throws if an adapter with the same id already exists. */
+    register(adapter: HarnessAdapter): void;
+    /** Unregister an adapter, disposing it in the process. */
+    unregister(id: string): Promise<void>;
+    /** Retrieve an adapter by id. */
+    get(id: string): HarnessAdapter | undefined;
+    /** List all registered adapter ids. */
+    listAll(): string[];
+    /** List ids of adapters that report isAvailable() === true. */
+    listAvailable(): Promise<string[]>;
+    /** Dispose all adapters and clear the registry. */
+    disposeAll(): Promise<void>;
+}
+
+interface CoordinatorOptions {
+    /** Absolute path to the project root (where .claude/workboard.md lives) */
+    projectRoot: string;
+    /** Unix socket path for the RPC server */
+    socketPath?: string;
+    /** Session task description shown in the workboard */
+    task?: string;
+}
+/**
+ * HarnessCoordinator — single entry point for harness-to-harness coordination.
+ *
+ * On start:
+ *   1. Auto-detects installed AI harnesses and registers them
+ *   2. Registers this session in the workboard
+ *   3. Starts the RPC server
+ *
+ * On stop:
+ *   1. Unregisters this session from the workboard
+ *   2. Stops the RPC server
+ *   3. Disposes all adapters
+ */
+declare class HarnessCoordinator {
+    private readonly options;
+    private readonly registry;
+    private rpcServer;
+    private sessionId;
+    private readonly workboard;
+    constructor(options: CoordinatorOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** The registry of detected harnesses. Available after start(). */
+    getRegistry(): HarnessRegistry;
+    /** The workboard manager. */
+    getWorkboard(): WorkboardManager;
+    /** Register a custom adapter (must be called before start()). */
+    registerAdapter(adapter: HarnessAdapter): void;
+}
+
+/**
+ * Detects available AI harnesses and registers them in the registry.
+ * Mirrors autoDetectEditors from packages/editors.
+ *
+ * Creates an adapter for each known harness, checks isAvailable(),
+ * and registers those that respond. Unavailable adapters are disposed.
+ */
+declare function autoDetectHarnesses(registry: HarnessRegistry): Promise<string[]>;
+
+/** Finds running processes matching a pattern using pgrep. */
+declare function findProcesses(pattern: string): Promise<{
+    pid: number;
+    command: string;
+}[]>;
+/** Finds running process instances for a specific harness. */
+declare function findHarnessProcesses(harnessId: string): Promise<HarnessProcessInfo[]>;
+/** Finds running processes for all known harnesses. */
+declare function findAllHarnessProcesses(): Promise<HarnessProcessInfo[]>;
+/** Finds Claude Code Unix socket files (used for IPC). */
+declare function findClaudeCodeSockets(): Promise<string[]>;
+
+/**
+ * JSON-RPC 2.0 server over a Unix domain socket.
+ * Mirrors RpcServer from packages/editors.
+ *
+ * Methods:
+ *   harness.list              → HarnessInfo[]
+ *   harness.execute           → HarnessCommandResult
+ *   harness.info              → HarnessInfo
+ *   harness.listRunning       → HarnessProcessInfo[]
+ *   harness.syncConfig        → ConfigSyncResult
+ *   harness.diffConfig        → ConfigDiffEntry
+ */
+declare class RpcServer {
+    private readonly registry;
+    private readonly socketPath;
+    private server;
+    constructor(registry: HarnessRegistry, socketPath: string);
+    private handleLine;
+    private dispatch;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+/**
+ * @revealui/harnesses — AI Harness Integration System (Server-side)
+ *
+ * Adapters, registry, workboard coordination, and JSON-RPC server for
+ * integrating AI coding tools (Claude Code, Cursor, Copilot) into the
+ * RevealUI development workflow.
+ *
+ * Pro tier feature: gated behind isFeatureEnabled("harnesses").
+ *
+ * @packageDocumentation
+ */
+/** Check whether the harnesses feature is licensed for this installation. */
+declare function checkHarnessesLicense(): Promise<boolean>;
+
+export { ClaudeCodeAdapter, type ConfigDiffEntry, type ConfigSyncDirection, type ConfigSyncResult, type CoordinatorOptions, CopilotAdapter, type HarnessAdapter, type HarnessCapabilities, type HarnessCommand, type HarnessCommandResult, HarnessCoordinator, type HarnessEvent, type HarnessInfo, type HarnessProcessInfo, HarnessRegistry, RpcServer, WorkboardManager, autoDetectHarnesses, checkHarnessesLicense, diffConfig, findAllHarnessProcesses, findClaudeCodeSockets, findHarnessProcesses, findProcesses, getConfigurableHarnesses, getLocalConfigPath, getSsdConfigPath, syncConfig };

package/dist/index.js

@@ -0,0 +1,61 @@
+import {
+  ClaudeCodeAdapter,
+  CopilotAdapter,
+  HarnessCoordinator,
+  HarnessRegistry,
+  RpcServer,
+  autoDetectHarnesses,
+  diffConfig,
+  findAllHarnessProcesses,
+  findClaudeCodeSockets,
+  findHarnessProcesses,
+  findProcesses,
+  getConfigurableHarnesses,
+  getLocalConfigPath,
+  getSsdConfigPath,
+  syncConfig
+} from "./chunk-BDA7D725.js";
+import "./chunk-JUNNIQS3.js";
+import {
+  WorkboardManager,
+  deriveSessionId,
+  detectSessionType
+} from "./chunk-PG4RAOWS.js";
+
+// src/index.ts
+import { isFeatureEnabled } from "@revealui/core/features";
+import { initializeLicense } from "@revealui/core/license";
+import { logger } from "@revealui/core/observability/logger";
+async function checkHarnessesLicense() {
+  await initializeLicense();
+  if (!isFeatureEnabled("harnesses")) {
+    logger.warn(
+      "[@revealui/harnesses] AI harness integration requires a Pro or Enterprise license. Visit https://revealui.com/pricing for details.",
+      { feature: "harnesses" }
+    );
+    return false;
+  }
+  return true;
+}
+export {
+  ClaudeCodeAdapter,
+  CopilotAdapter,
+  HarnessCoordinator,
+  HarnessRegistry,
+  RpcServer,
+  WorkboardManager,
+  autoDetectHarnesses,
+  checkHarnessesLicense,
+  deriveSessionId,
+  detectSessionType,
+  diffConfig,
+  findAllHarnessProcesses,
+  findClaudeCodeSockets,
+  findHarnessProcesses,
+  findProcesses,
+  getConfigurableHarnesses,
+  getLocalConfigPath,
+  getSsdConfigPath,
+  syncConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @revealui/harnesses — AI Harness Integration System (Server-side)\n *\n * Adapters, registry, workboard coordination, and JSON-RPC server for\n * integrating AI coding tools (Claude Code, Cursor, Copilot) into the\n * RevealUI development workflow.\n *\n * Pro tier feature: gated behind isFeatureEnabled(\"harnesses\").\n *\n * @packageDocumentation\n */\n\nimport { isFeatureEnabled } from '@revealui/core/features'\nimport { initializeLicense } from '@revealui/core/license'\nimport { logger } from '@revealui/core/observability/logger'\n\n/** Check whether the harnesses feature is licensed for this installation. */\nexport async function checkHarnessesLicense(): Promise<boolean> {\n  await initializeLicense()\n  if (!isFeatureEnabled('harnesses')) {\n    logger.warn(\n      '[@revealui/harnesses] AI harness integration requires a Pro or Enterprise license. ' +\n        'Visit https://revealui.com/pricing for details.',\n      { feature: 'harnesses' },\n    )\n    return false\n  }\n  return true\n}\n\n// Adapters\nexport { ClaudeCodeAdapter } from './adapters/claude-code-adapter.js'\nexport { CopilotAdapter } from './adapters/copilot-adapter.js'\n\n// Config\nexport { diffConfig, syncConfig } from './config/config-sync.js'\nexport {\n  getConfigurableHarnesses,\n  getLocalConfigPath,\n  getSsdConfigPath,\n} from './config/harness-config-paths.js'\nexport type { CoordinatorOptions } from './coordinator.js'\n// Coordinator\nexport { HarnessCoordinator } from './coordinator.js'\n\n// Detection\nexport { autoDetectHarnesses } from './detection/auto-detector.js'\nexport {\n  findAllHarnessProcesses,\n  findClaudeCodeSockets,\n  findHarnessProcesses,\n  findProcesses,\n} from './detection/process-detector.js'\n\n// Registry\nexport { HarnessRegistry } from './registry/harness-registry.js'\n\n// Server\nexport { RpcServer } from './server/rpc-server.js'\nexport type { HarnessAdapter } from './types/adapter.js'\n\n// Types — harness core\nexport type {\n  ConfigDiffEntry,\n  ConfigSyncDirection,\n  ConfigSyncResult,\n  HarnessCapabilities,\n  HarnessCommand,\n  HarnessCommandResult,\n  HarnessEvent,\n  HarnessInfo,\n  HarnessProcessInfo,\n} from './types/core.js'\n// Workboard\nexport {\n  deriveSessionId,\n  detectSessionType,\n  WorkboardManager,\n} from './workboard/index.js'\n// Types — session identity\nexport type { SessionType } from './workboard/session-identity.js'\n// Types — workboard protocol\nexport type {\n  ConflictResult,\n  WorkboardEntry,\n  WorkboardSession,\n  WorkboardState,\n} from './workboard/workboard-protocol.js'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAYA,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AAClC,SAAS,cAAc;AAGvB,eAAsB,wBAA0C;AAC9D,QAAM,kBAAkB;AACxB,MAAI,CAAC,iBAAiB,WAAW,GAAG;AAClC,WAAO;AAAA,MACL;AAAA,MAEA,EAAE,SAAS,YAAY;AAAA,IACzB;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/workboard/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * WorkboardProtocol — types for the multi-agent coordination workboard.
+ *
+ * The workboard (.claude/workboard.md) is the shared coordination primitive
+ * that lets multiple AI coding agents (Claude Code, Cursor, etc.) work safely
+ * in parallel on the same codebase without stepping on each other.
+ *
+ * This module defines machine-readable types for parsing and writing the
+ * workboard's markdown structure programmatically.
+ */
+/** A row in the ## Sessions table. */
+interface WorkboardSession {
+    /** Unique session identifier, e.g. "zed-1", "terminal-2", "cursor-1" */
+    id: string;
+    /** Human-readable environment description, e.g. "Zed/ACP", "WSL/bash" */
+    env: string;
+    /** ISO timestamp of when the session registered */
+    started: string;
+    /** Current task description */
+    task: string;
+    /** Comma-separated list of file globs this session is actively modifying */
+    files: string;
+    /** ISO timestamp of last workboard update */
+    updated: string;
+}
+/** A timestamped entry in the ## Recent section. */
+interface WorkboardEntry {
+    /** ISO-derived display timestamp "[YYYY-MM-DD HH:MM]" */
+    timestamp: string;
+    /** Session id that produced this entry */
+    sessionId: string;
+    /** Free-form description of what was accomplished */
+    description: string;
+}
+/** Full parsed workboard state. */
+interface WorkboardState {
+    sessions: WorkboardSession[];
+    recent: WorkboardEntry[];
+    /** Freeform markdown content of the ## Plans section */
+    plans: string;
+    /** Freeform markdown content of the ## Context section */
+    context: string;
+    /** Freeform markdown content of the ## Plan Reference section */
+    planReference: string;
+}
+/** Result of a conflict detection check. */
+interface ConflictResult {
+    /** True if no conflicting file reservations were found */
+    clean: boolean;
+    /** Sessions with overlapping file claims */
+    conflicts: Array<{
+        thisSession: string;
+        otherSession: string;
+        overlappingFiles: string[];
+    }>;
+}
+
+/**
+ * WorkboardManager — reads, parses, and writes .claude/workboard.md.
+ *
+ * The workboard is a markdown file with a specific structure:
+ *   ## Sessions  — markdown table
+ *   ## Plans     — freeform markdown
+ *   ## Recent    — bullet list
+ *   ## Context   — freeform markdown
+ *   ## Plan Reference — freeform markdown
+ *
+ * This class provides programmatic access to the Sessions table and Recent list.
+ * Plans, Context, and Plan Reference are treated as opaque strings.
+ */
+declare class WorkboardManager {
+    private readonly workboardPath;
+    constructor(workboardPath: string);
+    /** Read and parse the workboard. */
+    read(): WorkboardState;
+    /** Write a workboard state back to disk. */
+    write(state: WorkboardState): void;
+    /** Read and parse the workboard asynchronously. */
+    readAsync(): Promise<WorkboardState>;
+    /** Write a workboard state back to disk asynchronously. */
+    writeAsync(state: WorkboardState): Promise<void>;
+    /** Register a new session, replacing any existing row with the same id. */
+    registerSession(session: WorkboardSession): void;
+    /** Remove a session row by id. */
+    unregisterSession(id: string): void;
+    /** Update specific fields of an existing session row. */
+    updateSession(id: string, updates: Partial<WorkboardSession>): void;
+    /** Update a session's files list and timestamp. */
+    claimFiles(id: string, files: string[]): void;
+    /** Clear a session's file reservations. */
+    releaseFiles(id: string): void;
+    /** Prepend a timestamped entry to the ## Recent section (keeps last 20). */
+    addRecentEntry(entry: WorkboardEntry): void;
+    /** Returns sessions whose `updated` timestamp is older than 4 hours. */
+    detectStale(): WorkboardSession[];
+    /**
+     * Check whether the given files conflict with any other active session's reservations.
+     * Returns a ConflictResult describing any overlaps found.
+     */
+    checkConflicts(mySessionId: string, files: string[]): ConflictResult;
+}
+
+/** Type of session detected from the runtime environment. */
+type SessionType = 'zed' | 'cursor' | 'terminal';
+/**
+ * Detects whether the current process is running inside an AI tool (Zed, Cursor)
+ * or a plain terminal session by walking the parent process chain.
+ *
+ * Uses /proc/<pid>/cmdline on Linux/WSL. Falls back to TERM_PROGRAM env var.
+ */
+declare function detectSessionType(): SessionType;
+/**
+ * Derives a session ID (e.g. "zed-1", "terminal-2") given a type and a list
+ * of existing session IDs already in the workboard.
+ *
+ * Picks the next available numeric suffix to avoid collisions.
+ */
+declare function deriveSessionId(type: SessionType, existingIds: string[]): string;
+
+export { type ConflictResult, type SessionType, type WorkboardEntry, WorkboardManager, type WorkboardSession, type WorkboardState, deriveSessionId, detectSessionType };

package/dist/workboard/index.js

@@ -0,0 +1,12 @@
+import "../chunk-JUNNIQS3.js";
+import {
+  WorkboardManager,
+  deriveSessionId,
+  detectSessionType
+} from "../chunk-PG4RAOWS.js";
+export {
+  WorkboardManager,
+  deriveSessionId,
+  detectSessionType
+};
+//# sourceMappingURL=index.js.map

package/dist/workboard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@revealui/harnesses",
+  "version": "0.1.0",
+  "description": "AI harness integration system - adapters, daemon, workboard coordination, and JSON-RPC server",
+  "license": "SEE LICENSE IN ../../LICENSE.commercial",
+  "type": "module",
+  "bin": {
+    "revealui-harnesses": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./workboard": {
+      "types": "./dist/workboard/index.d.ts",
+      "import": "./dist/workboard/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@revealui/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "dev": "0.0.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "clean": "rm -rf dist"
+  }
+}