@hua-labs/tap 0.1.1 → 0.2.1

package/dist/index.d.mts

@@ -8,6 +8,8 @@ interface AdapterContext {
     repoRoot: string;
     stateDir: string;
     platform: Platform;
+    /** Instance ID for TAP_AGENT_ID env injection. Set by 'tap add'. */
+    instanceId?: string;
 }
 interface ProbeResult {
     installed: boolean;
@@ -83,10 +85,32 @@ interface HeadlessConfig {
     /** Severity floor for quality-threshold strategy. Default: "high" */
     qualitySeverityFloor: "critical" | "high" | "medium";
 }
+interface AppServerAuthState {
+    mode: "query-token";
+    protectedUrl: string;
+    upstreamUrl: string;
+    tokenPath: string;
+    gatewayPid: number | null;
+    gatewayLogPath: string | null;
+}
+interface AppServerState {
+    url: string;
+    pid: number | null;
+    managed: boolean;
+    healthy: boolean;
+    lastCheckedAt: string;
+    lastHealthyAt: string | null;
+    logPath: string | null;
+    manualCommand: string;
+    auth?: AppServerAuthState | null;
+}
 interface BridgeState {
     pid: number;
     statePath: string;
     lastHeartbeat: string;
+    appServer?: AppServerState | null;
+    /** Instance-specific daemon state dir (thread/heartbeat/processed markers). */
+    runtimeStateDir?: string | null;
 }
 /** Runtime instance state. Supports multiple instances per runtime (e.g. codex-reviewer, codex-builder). */
 interface InstanceState {
@@ -140,8 +164,8 @@ interface TapStateV1 {
     packageVersion: string;
     runtimes: Partial<Record<RuntimeName, RuntimeState>>;
 }
-type CommandName = "init" | "init-worktree" | "add" | "remove" | "status" | "serve" | "bridge" | "dashboard" | "unknown";
-type CommandCode = "TAP_INIT_OK" | "TAP_ADD_OK" | "TAP_REMOVE_OK" | "TAP_STATUS_OK" | "TAP_SERVE_OK" | "TAP_NO_OP" | "TAP_ALREADY_INITIALIZED" | "TAP_NOT_INITIALIZED" | "TAP_RUNTIME_UNKNOWN" | "TAP_RUNTIME_NOT_FOUND" | "TAP_CONFIG_INVALID" | "TAP_LOCAL_SERVER_MISSING" | "TAP_INVALID_ARGUMENT" | "TAP_INSTANCE_NOT_FOUND" | "TAP_INSTANCE_AMBIGUOUS" | "TAP_PORT_CONFLICT" | "TAP_PATCH_FAILED" | "TAP_VERIFY_FAILED" | "TAP_ROLLBACK_FAILED" | "TAP_BRIDGE_START_OK" | "TAP_BRIDGE_START_FAILED" | "TAP_BRIDGE_STOP_OK" | "TAP_BRIDGE_STATUS_OK" | "TAP_BRIDGE_NOT_RUNNING" | "TAP_BRIDGE_SCRIPT_MISSING" | "TAP_SERVE_NO_SERVER" | "TAP_SERVE_BUN_REQUIRED" | "TAP_REVIEW_START_OK" | "TAP_REVIEW_TERMINATED" | "TAP_INTERNAL_ERROR";
+type CommandName = "init" | "init-worktree" | "add" | "remove" | "status" | "serve" | "bridge" | "up" | "down" | "comms" | "dashboard" | "doctor" | "unknown";
+type CommandCode = "TAP_INIT_OK" | "TAP_ADD_OK" | "TAP_REMOVE_OK" | "TAP_STATUS_OK" | "TAP_SERVE_OK" | "TAP_NO_OP" | "TAP_ALREADY_INITIALIZED" | "TAP_INIT_CLONE_FAILED" | "TAP_NOT_INITIALIZED" | "TAP_RUNTIME_UNKNOWN" | "TAP_RUNTIME_NOT_FOUND" | "TAP_CONFIG_INVALID" | "TAP_LOCAL_SERVER_MISSING" | "TAP_INVALID_ARGUMENT" | "TAP_INSTANCE_NOT_FOUND" | "TAP_INSTANCE_AMBIGUOUS" | "TAP_PORT_CONFLICT" | "TAP_PATCH_FAILED" | "TAP_VERIFY_FAILED" | "TAP_ROLLBACK_FAILED" | "TAP_BRIDGE_START_OK" | "TAP_BRIDGE_START_FAILED" | "TAP_BRIDGE_STOP_OK" | "TAP_BRIDGE_STATUS_OK" | "TAP_BRIDGE_NOT_RUNNING" | "TAP_BRIDGE_SCRIPT_MISSING" | "TAP_UP_OK" | "TAP_DOWN_OK" | "TAP_COMMS_PULL_OK" | "TAP_COMMS_PULL_FAILED" | "TAP_COMMS_PUSH_OK" | "TAP_COMMS_PUSH_FAILED" | "TAP_COMMS_NOT_REPO" | "TAP_SERVE_NO_SERVER" | "TAP_SERVE_BUN_REQUIRED" | "TAP_REVIEW_START_OK" | "TAP_REVIEW_TERMINATED" | "TAP_INTERNAL_ERROR";
 interface CommandResult<T = Record<string, unknown>> {
     ok: boolean;
     command: CommandName;
@@ -158,7 +182,7 @@ declare function loadState(repoRoot: string): TapState | null;
 declare function saveState(repoRoot: string, state: TapState): void;
 declare function createInitialState(commsDir: string, repoRoot: string, packageVersion: string): TapState;
 
-declare const version = "0.1.0";
+declare const version: string;
 
 /**
  * Shared config (tap-config.json) — git tracked, repo-level defaults.
@@ -173,6 +197,8 @@ interface TapSharedConfig {
     runtimeCommand?: string;
     /** App server WebSocket URL for bridge connections. */
     appServerUrl?: string;
+    /** GitHub URL for the comms repository (used by `tap comms pull/push`). */
+    commsRepoUrl?: string;
 }
 /**
  * Local config (tap-config.local.json) — gitignored, machine-specific overrides.
@@ -190,7 +216,7 @@ interface TapResolvedConfig {
     appServerUrl: string;
 }
 /** Config resolution source for diagnostics. */
-type ConfigSource = "cli-flag" | "env" | "local-config" | "shared-config" | "auto";
+type ConfigSource = "cli-flag" | "env" | "local-config" | "shared-config" | "legacy-shell-config" | "auto";
 interface ConfigResolution {
     config: TapResolvedConfig;
     sources: Record<keyof TapResolvedConfig, ConfigSource>;
@@ -228,6 +254,142 @@ declare function updateBridgeHeartbeat(stateDir: string, instanceId: InstanceId)
  */
 declare function getHeartbeatAge(stateDir: string, instanceId: InstanceId): number | null;
 
+/**
+ * Dashboard data collection engine.
+ * Aggregates: agents (comms presence), bridges (state + PID), PRs (gh CLI).
+ *
+ * Ref: tap public repo tap-ops-dashboard.ps1 (single-agent view)
+ * M74 extends to control-tower view (all agents, all bridges, all PRs).
+ */
+interface AgentInfo {
+    name: string;
+    status: string | null;
+    lastActivity: string | null;
+    joinedAt: string | null;
+}
+interface BridgeInfo {
+    instanceId: string;
+    runtime: string;
+    status: "running" | "stopped" | "stale";
+    pid: number | null;
+    port: number | null;
+    heartbeatAge: number | null;
+    headless: boolean;
+}
+interface PRInfo {
+    number: number;
+    title: string;
+    author: string;
+    state: string;
+    url: string;
+}
+interface DashboardWarning {
+    level: "warn" | "error";
+    message: string;
+}
+interface DashboardSnapshot {
+    generatedAt: string;
+    repoRoot: string;
+    commsDir: string;
+    agents: AgentInfo[];
+    bridges: BridgeInfo[];
+    prs: PRInfo[];
+    warnings: DashboardWarning[];
+}
+declare function collectDashboardSnapshot(repoRoot?: string, commsDirOverride?: string): DashboardSnapshot;
+
+/**
+ * State/Control API — programmatic access to tap state.
+ * GUI and autopilot consume these functions instead of shelling out to CLI.
+ *
+ * M105 P1: getDashboardSnapshot, streamEvents (read-only)
+ * M105 P2: startAgents, stopAgents (write — wraps tap up/down)
+ */
+
+interface StateApiOptions {
+    repoRoot?: string;
+    commsDir?: string;
+}
+/**
+ * Get a point-in-time snapshot of all tap state:
+ * agents, bridges, PRs, and warnings.
+ *
+ * This is the read-only entry point for GUI dashboards and autopilot.
+ */
+declare function getDashboardSnapshot(options?: StateApiOptions): DashboardSnapshot;
+interface EventStreamOptions extends StateApiOptions {
+    /** Poll interval in milliseconds (default: 2000) */
+    intervalMs?: number;
+    /** AbortSignal to stop the stream */
+    signal?: AbortSignal;
+}
+/**
+ * Async generator that yields dashboard snapshots at regular intervals.
+ * Useful for SSE or WebSocket push to GUI clients.
+ *
+ * Stops when the AbortSignal fires or the consumer breaks out.
+ */
+declare function streamEvents(options?: EventStreamOptions): AsyncGenerator<DashboardSnapshot>;
+interface AgentControlOptions {
+    /** Extra CLI args forwarded to `tap up` (e.g. `["--no-auth"]`) */
+    args?: string[];
+}
+interface AgentControlResult {
+    ok: boolean;
+    message: string;
+    snapshot: DashboardSnapshot;
+    commandResult: CommandResult;
+}
+/**
+ * Start all registered bridge daemons.
+ * Equivalent to `tap up [...args]`.
+ *
+ * Always operates on the cwd-based repo (same as CLI commands).
+ * Use read-only APIs (getDashboardSnapshot) for cross-repo queries.
+ */
+declare function startAgents(options?: AgentControlOptions): Promise<AgentControlResult>;
+/**
+ * Stop all running bridge daemons.
+ * Equivalent to `tap down`.
+ *
+ * Always operates on the cwd-based repo (same as CLI commands).
+ */
+declare function stopAgents(): Promise<AgentControlResult>;
+/**
+ * Resolve tap configuration for API consumers.
+ * Returns paths and settings without requiring CLI args.
+ */
+declare function getConfig(options?: StateApiOptions): {
+    repoRoot: string;
+    commsDir: string;
+    stateDir: string;
+    appServerUrl: string;
+};
+
+/**
+ * Minimal HTTP transport for tap State API.
+ * localhost-only, no external dependencies (uses node:http).
+ *
+ * Endpoints:
+ *   GET /api/snapshot    — DashboardSnapshot JSON
+ *   GET /api/events      — SSE stream of snapshots
+ *   GET /api/config      — Resolved tap configuration
+ *   GET /health          — Health check
+ */
+
+interface HttpServerOptions extends StateApiOptions {
+    /** Port to listen on (default: 4580) */
+    port?: number;
+}
+/**
+ * Start a localhost-only HTTP server for the tap State API.
+ * Resolves after the server is listening. Rejects on bind failure (e.g. EADDRINUSE).
+ */
+declare function startHttpServer(options?: HttpServerOptions): Promise<{
+    port: number;
+    close: () => Promise<void>;
+}>;
+
 /**
  * Common Node.js runtime resolver for all tap-comms child processes.
  *
@@ -269,4 +431,4 @@ declare function resolveNodeRuntime(configCommand: string, repoRoot: string): Re
  */
 declare function buildRuntimeEnv(repoRoot: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 
-export { type AdapterContext, type ApplyResult, type ArtifactKind, type BridgeMode, type BridgeState, type CommandCode, type CommandName, type CommandResult, type ConfigOverrides, type ConfigResolution, type ConfigSource, type InstanceId, type InstanceState, LOCAL_CONFIG_FILE, type OwnedArtifact, type PatchOp, type PatchOpType, type PatchPlan, type Platform, type ProbeResult, type ResolvedRuntime, type RuntimeAdapter, type RuntimeName, type RuntimeSource, type RuntimeState, SHARED_CONFIG_FILE, type TapLocalConfig, type TapResolvedConfig, type TapSharedConfig, type TapState, type TapStateV1, type VerifyCheck, type VerifyResult, buildRuntimeEnv, createInitialState, getFnmBinDir, getHeartbeatAge, loadLocalConfig, loadSharedConfig, loadState, probeFnmNode, readNodeVersion, resolveConfig, resolveNodeRuntime, rotateLog, saveLocalConfig, saveSharedConfig, saveState, stateExists, updateBridgeHeartbeat, version };
+export { type AdapterContext, type AgentControlOptions, type AgentControlResult, type AgentInfo, type AppServerAuthState, type AppServerState, type ApplyResult, type ArtifactKind, type BridgeInfo, type BridgeMode, type BridgeState, type CommandCode, type CommandName, type CommandResult, type ConfigOverrides, type ConfigResolution, type ConfigSource, type DashboardSnapshot, type DashboardWarning, type EventStreamOptions, type HttpServerOptions, type InstanceId, type InstanceState, LOCAL_CONFIG_FILE, type OwnedArtifact, type PRInfo, type PatchOp, type PatchOpType, type PatchPlan, type Platform, type ProbeResult, type ResolvedRuntime, type RuntimeAdapter, type RuntimeName, type RuntimeSource, type RuntimeState, SHARED_CONFIG_FILE, type StateApiOptions, type TapLocalConfig, type TapResolvedConfig, type TapSharedConfig, type TapState, type TapStateV1, type VerifyCheck, type VerifyResult, buildRuntimeEnv, collectDashboardSnapshot, createInitialState, getConfig, getDashboardSnapshot, getFnmBinDir, getHeartbeatAge, loadLocalConfig, loadSharedConfig, loadState, probeFnmNode, readNodeVersion, resolveConfig, resolveNodeRuntime, rotateLog, saveLocalConfig, saveSharedConfig, saveState, startAgents, startHttpServer, stateExists, stopAgents, streamEvents, updateBridgeHeartbeat, version };