aimux-cli 0.1.16 → 0.1.19

package/dist/debug-state.js

@@ -0,0 +1,540 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { getReadOnlyProjectPathsFor } from "./paths.js";
+import { TmuxRuntimeManager } from "./tmux/runtime-manager.js";
+import { listWorktrees } from "./worktree.js";
+import { RuntimeTopologyStore } from "./runtime-core/topology-store.js";
+import { RuntimeExchangeStore } from "./runtime-core/exchange-store.js";
+function asObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function getString(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return { status: "missing", path };
+    try {
+        return { status: "found", path, value: JSON.parse(readFileSync(path, "utf8")) };
+    }
+    catch (err) {
+        return {
+            status: "error",
+            path,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function readRuntimeTopology(path) {
+    if (!existsSync(path))
+        return { status: "missing", path };
+    try {
+        return { status: "found", path, value: new RuntimeTopologyStore(path).read() };
+    }
+    catch (err) {
+        return {
+            status: "error",
+            path,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function readRuntimeExchange(path) {
+    if (!existsSync(path))
+        return { status: "missing", path };
+    try {
+        return { status: "found", path, value: new RuntimeExchangeStore(path).read() };
+    }
+    catch (err) {
+        return {
+            status: "error",
+            path,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function normalizePathLike(value) {
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/"))
+        return resolve(homedir(), value.slice(2));
+    return resolve(value);
+}
+function looksPathLike(value) {
+    return value.includes("/") || value.startsWith("~");
+}
+function matchesString(candidate, target) {
+    if (!candidate)
+        return false;
+    if (candidate === target)
+        return true;
+    if (looksPathLike(candidate) || looksPathLike(target)) {
+        return normalizePathLike(candidate) === normalizePathLike(target);
+    }
+    return false;
+}
+function serviceCanonical(id, worktreePath) {
+    return id ? `service:${id}` : `service:${worktreePath ?? "unknown"}`;
+}
+function sessionCanonical(id, backendSessionId) {
+    if (id)
+        return `session:${id}`;
+    if (backendSessionId)
+        return `backend-session:${backendSessionId}`;
+    return "session:unknown";
+}
+function worktreeCanonical(path, name) {
+    return `worktree:${path ?? name ?? "unknown"}`;
+}
+function addMatch(matches, seen, match) {
+    const key = `${match.canonicalKey}:${match.source}:${match.kind}:${match.id ?? ""}:${match.backendSessionId ?? ""}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    matches.push(match);
+}
+function sourceUnavailable(reason) {
+    return { status: "unavailable", reason };
+}
+function filterSavedState(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const root = asObject(source.value);
+    const services = asArray(root?.services).filter((entry) => {
+        const record = asObject(entry);
+        const id = getString(record, "id");
+        const worktreePath = getString(record, "worktreePath");
+        const cwd = getString(record, "cwd");
+        const label = getString(record, "label");
+        const matched = matchesString(id, target) ||
+            matchesString(worktreePath, target) ||
+            matchesString(cwd, target) ||
+            matchesString(label, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: serviceCanonical(id, worktreePath),
+                kind: "service",
+                source: "savedState",
+                id,
+                worktreePath,
+                label,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { services } };
+}
+function filterMetadata(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const sessionsRecord = asObject(asObject(source.value)?.sessions);
+    const sessions = Object.entries(sessionsRecord ?? {})
+        .filter(([sessionId, entry]) => {
+        const record = asObject(entry);
+        const context = asObject(record?.context);
+        const worktreePath = getString(context, "worktreePath");
+        const worktreeName = getString(context, "worktreeName");
+        const branch = getString(context, "branch");
+        const cwd = getString(context, "cwd");
+        const matched = matchesString(sessionId, target) ||
+            matchesString(worktreePath, target) ||
+            matchesString(worktreeName, target) ||
+            matchesString(branch, target) ||
+            matchesString(cwd, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: sessionCanonical(sessionId),
+                kind: "session",
+                source: "metadata",
+                id: sessionId,
+                worktreePath,
+                worktreeName,
+                raw: entry,
+            });
+        }
+        return matched;
+    })
+        .map(([sessionId, entry]) => ({ sessionId, ...(asObject(entry) ?? {}) }));
+    return { status: "found", path: source.path, value: { sessions } };
+}
+const DEBUG_STATE_SOURCE_ROLES = {
+    savedState: {
+        role: "legacy",
+        authority: "runtime-topology.yaml for services",
+        note: "legacy service snapshot evidence; it must not create lifecycle truth",
+    },
+    runtimeTopology: {
+        role: "authority",
+        authority: "runtime-topology.yaml",
+        note: "authoritative agents, services, worktrees, lifecycle, graveyard, and bindings",
+    },
+    metadata: {
+        role: "projection",
+        authority: "runtime-topology.yaml and runtime-exchange.yaml",
+        note: "decorates known sessions only; hidden lifecycle and backend identity fields are ignored",
+    },
+    tmux: {
+        role: "substrate",
+        authority: "runtime-topology.yaml",
+        note: "live tmux window evidence and repair input, not durable lifecycle authority",
+    },
+    gitWorktrees: {
+        role: "substrate",
+        authority: "runtime-topology.yaml for aimux worktree lifecycle",
+        note: "git worktree substrate evidence; aimux lifecycle state lives in topology",
+    },
+    graveyard: {
+        role: "authority",
+        authority: "runtime-topology.yaml",
+        note: "filtered topology sessions with graveyard status",
+    },
+    worktreeGraveyard: {
+        role: "authority",
+        authority: "runtime-topology.yaml",
+        note: "topology-owned worktree graveyard entries; git path existence gates resurrection",
+    },
+    notifications: {
+        role: "projection",
+        authority: "runtime-exchange.yaml",
+        note: "notification rows are exchange threads/messages/inbox entries tagged as notifications",
+    },
+    operationFailures: {
+        role: "projection",
+        authority: "runtime-topology.yaml plus operation execution results",
+        note: "dashboard-facing failure projection, not lifecycle authority",
+    },
+    runtimeRows: {
+        role: "unavailable",
+        note: "live runtime-only view unavailable to standalone debug-state",
+    },
+    pendingActions: {
+        role: "unavailable",
+        note: "in-memory dashboard optimism unavailable to standalone debug-state",
+    },
+    dashboardSnapshot: {
+        role: "unavailable",
+        note: "project-service/dashboard projection unavailable to standalone debug-state",
+    },
+};
+function filterTmux(tmuxWindows, paths, target, matches, seen) {
+    let windows = tmuxWindows;
+    if (!windows) {
+        try {
+            windows = new TmuxRuntimeManager().listProjectManagedWindows(paths.repoRoot);
+        }
+        catch (err) {
+            return {
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    if (windows instanceof Error)
+        return { status: "error", error: windows.message };
+    const filtered = windows.filter((entry) => {
+        const metadata = entry.metadata;
+        const matched = matchesString(metadata.sessionId, target) ||
+            matchesString(metadata.backendSessionId, target) ||
+            matchesString(metadata.worktreePath, target) ||
+            matchesString(metadata.label, target) ||
+            matchesString(metadata.launchCommandLine, target) ||
+            matchesString(entry.target.windowName, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: metadata.kind === "service"
+                    ? serviceCanonical(metadata.sessionId, metadata.worktreePath)
+                    : sessionCanonical(metadata.sessionId, metadata.backendSessionId),
+                kind: "tmux-window",
+                source: "tmux",
+                id: metadata.sessionId,
+                backendSessionId: metadata.backendSessionId,
+                worktreePath: metadata.worktreePath,
+                label: metadata.label,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", value: { windows: filtered } };
+}
+function filterGitWorktrees(worktreesInput, paths, target, matches, seen) {
+    let worktrees = worktreesInput;
+    if (!worktrees) {
+        try {
+            worktrees = listWorktrees(paths.repoRoot);
+        }
+        catch (err) {
+            return {
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    if (worktrees instanceof Error)
+        return { status: "error", error: worktrees.message };
+    const filtered = worktrees.filter((entry) => {
+        const matched = matchesString(entry.name, target) || matchesString(entry.path, target) || matchesString(entry.branch, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: worktreeCanonical(entry.path, entry.name),
+                kind: "worktree",
+                source: "gitWorktrees",
+                worktreePath: entry.path,
+                worktreeName: entry.name,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", value: { worktrees: filtered } };
+}
+function filterGraveyard(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const root = source.value;
+    const entries = asArray(Array.isArray(root) ? root : asObject(root)?.sessions).filter((entry) => {
+        const record = asObject(entry);
+        const status = getString(record, "status");
+        if (status && status !== "graveyard")
+            return false;
+        const id = getString(record, "id");
+        const backendSessionId = getString(record, "backendSessionId");
+        const worktreePath = getString(record, "worktreePath");
+        const label = getString(record, "label");
+        const matched = matchesString(id, target) ||
+            matchesString(backendSessionId, target) ||
+            matchesString(worktreePath, target) ||
+            matchesString(label, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: sessionCanonical(id, backendSessionId),
+                kind: "session",
+                source: "graveyard",
+                id,
+                backendSessionId,
+                worktreePath,
+                label,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { entries } };
+}
+function filterRuntimeTopology(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const topology = source.value;
+    const sessions = topology.sessions.filter((entry) => {
+        const id = entry.id;
+        const backendSessionId = entry.backendSessionId;
+        const worktreePath = entry.worktreePath;
+        const label = entry.label;
+        const matched = matchesString(id, target) ||
+            matchesString(backendSessionId, target) ||
+            matchesString(worktreePath, target) ||
+            matchesString(label, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: sessionCanonical(id, backendSessionId),
+                kind: backendSessionId === target && id !== target ? "backend-session" : "session",
+                source: "runtimeTopology",
+                id,
+                backendSessionId,
+                worktreePath,
+                label,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    const services = topology.services.filter((entry) => {
+        const matched = matchesString(entry.id, target) ||
+            matchesString(entry.worktreePath, target) ||
+            matchesString(entry.cwd, target) ||
+            matchesString(entry.label, target) ||
+            matchesString(entry.launchCommandLine, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: serviceCanonical(entry.id, entry.worktreePath),
+                kind: "service",
+                source: "runtimeTopology",
+                id: entry.id,
+                worktreePath: entry.worktreePath,
+                label: entry.label,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    const worktrees = topology.worktrees.filter((entry) => {
+        const matched = matchesString(entry.name, target) || matchesString(entry.path, target) || matchesString(entry.branch, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: worktreeCanonical(entry.path, entry.name),
+                kind: "worktree",
+                source: "runtimeTopology",
+                worktreePath: entry.path,
+                worktreeName: entry.name,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { sessions, services, worktrees } };
+}
+function filterWorktreeGraveyard(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const entries = asArray(source.value).filter((entry) => {
+        const record = asObject(entry);
+        const name = getString(record, "name");
+        const path = getString(record, "path");
+        const branch = getString(record, "branch");
+        const agents = asArray(record?.agents);
+        const services = asArray(record?.services);
+        const childMatched = [...agents, ...services].some((child) => {
+            const childRecord = asObject(child);
+            return (matchesString(getString(childRecord, "id"), target) ||
+                matchesString(getString(childRecord, "backendSessionId"), target));
+        });
+        const matched = childMatched || matchesString(name, target) || matchesString(path, target) || matchesString(branch, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: worktreeCanonical(path, name),
+                kind: "worktree",
+                source: "worktreeGraveyard",
+                worktreePath: path,
+                worktreeName: name,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { entries } };
+}
+function filterNotifications(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const exchange = source.value;
+    if (!exchange)
+        return { ...source, value: { notifications: [] } };
+    const messagesByThread = new Map(exchange.messages.map((message) => [message.threadId, message]));
+    const notifications = exchange.threads.filter((entry) => {
+        if (!entry.tags?.includes("notification"))
+            return false;
+        const message = messagesByThread.get(entry.id);
+        const sessionId = typeof message?.metadata?.notificationSessionId === "string" ? message.metadata.notificationSessionId : undefined;
+        const targetKey = typeof message?.metadata?.notificationTargetKey === "string" ? message.metadata.notificationTargetKey : undefined;
+        const id = typeof message?.metadata?.notificationRecordId === "string" ? message.metadata.notificationRecordId : entry.id;
+        const matched = matchesString(sessionId, target) || matchesString(targetKey, target) || matchesString(id, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: `notification:${id ?? targetKey ?? sessionId ?? "unknown"}`,
+                kind: "notification",
+                source: "runtimeExchange",
+                id,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { notifications } };
+}
+function filterOperationFailures(source, target, matches, seen) {
+    if (source.status !== "found")
+        return { ...source, value: undefined };
+    const failures = asArray(asObject(source.value)?.failures).filter((entry) => {
+        const record = asObject(entry);
+        const id = getString(record, "id");
+        const targetId = getString(record, "targetId");
+        const worktreePath = getString(record, "worktreePath");
+        const worktreeName = getString(record, "worktreeName");
+        const matched = matchesString(id, target) ||
+            matchesString(targetId, target) ||
+            matchesString(worktreePath, target) ||
+            matchesString(worktreeName, target);
+        if (matched) {
+            addMatch(matches, seen, {
+                canonicalKey: `operation-failure:${id ?? targetId ?? worktreePath ?? "unknown"}`,
+                kind: "operation-failure",
+                source: "operationFailures",
+                id,
+                worktreePath,
+                worktreeName,
+                raw: entry,
+            });
+        }
+        return matched;
+    });
+    return { status: "found", path: source.path, value: { failures } };
+}
+function resolveStatus(matches) {
+    const canonicalKeys = new Set(matches.map((match) => match.canonicalKey));
+    if (canonicalKeys.size === 0)
+        return { status: "missing", entityCount: 0 };
+    if (canonicalKeys.size === 1)
+        return { status: "matched", entityCount: 1 };
+    return { status: "ambiguous", entityCount: canonicalKeys.size };
+}
+export function buildDebugStateReport(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const paths = options.paths ?? getReadOnlyProjectPathsFor(cwd);
+    const matches = [];
+    const seen = new Set();
+    const target = options.target;
+    const savedState = filterSavedState(readJson(paths.statePath), target, matches, seen);
+    const rawRuntimeTopology = readRuntimeTopology(paths.runtimeTopologyPath);
+    const rawRuntimeExchange = readRuntimeExchange(paths.runtimeExchangePath);
+    const runtimeTopology = filterRuntimeTopology(rawRuntimeTopology, target, matches, seen);
+    const metadata = filterMetadata(readJson(paths.metadataPath), target, matches, seen);
+    const tmux = filterTmux(options.tmuxWindows, paths, target, matches, seen);
+    const gitWorktrees = filterGitWorktrees(options.worktrees, paths, target, matches, seen);
+    const graveyard = filterGraveyard(runtimeTopology, target, matches, seen);
+    const worktreeGraveyard = filterWorktreeGraveyard(rawRuntimeTopology.status === "found"
+        ? { status: "found", path: rawRuntimeTopology.path, value: rawRuntimeTopology.value?.worktreeGraveyard ?? [] }
+        : rawRuntimeTopology, target, matches, seen);
+    const notifications = filterNotifications(rawRuntimeExchange, target, matches, seen);
+    const operationFailures = filterOperationFailures(readJson(paths.dashboardOperationFailuresPath), target, matches, seen);
+    const resolution = resolveStatus(matches);
+    return {
+        version: 1,
+        target,
+        project: {
+            repoRoot: paths.repoRoot,
+            projectId: paths.projectId,
+            projectStateDir: paths.projectStateDir,
+            localAimuxDir: paths.localAimuxDir,
+        },
+        targetResolution: {
+            ...resolution,
+            matches,
+        },
+        sourceRoles: DEBUG_STATE_SOURCE_ROLES,
+        sources: {
+            savedState,
+            runtimeTopology,
+            metadata,
+            tmux,
+            gitWorktrees,
+            graveyard,
+            worktreeGraveyard,
+            notifications,
+            operationFailures,
+            runtimeRows: sourceUnavailable("standalone debug-state does not attach to the live project runtime"),
+            pendingActions: sourceUnavailable("pending actions are in-memory dashboard state"),
+            dashboardSnapshot: sourceUnavailable("dashboard snapshot requires project-service/dashboard runtime"),
+        },
+    };
+}
+export function renderDebugStateReport(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/debug.d.ts

@@ -1,3 +1,41 @@
+import type { LoggingConfig, LogLevel } from "./config.js";
+export interface LoggingRuntimeConfig extends LoggingConfig {
+    path: string;
+    processKind: "cli" | "daemon" | "project-service" | "test" | string;
+    projectId?: string;
+    projectRoot?: string;
+}
+export interface LoggingCliOptions {
+    debug?: boolean;
+    trace?: boolean;
+    logLevel?: string;
+    logCategory?: string;
+}
+export interface ResolveLoggingOptions {
+    config: LoggingConfig;
+    env?: Record<string, string | undefined>;
+    cli?: LoggingCliOptions;
+    path: string;
+    processKind: LoggingRuntimeConfig["processKind"];
+    projectId?: string;
+    projectRoot?: string;
+}
+export interface LogFields {
+    [key: string]: unknown;
+}
+export declare function parseLogCategories(value: string | undefined): string[] | undefined;
+export declare function resolveLoggingRuntimeConfig(options: ResolveLoggingOptions): LoggingRuntimeConfig;
+export declare function configureLogging(config: Partial<LoggingRuntimeConfig>): LoggingRuntimeConfig;
+export declare function getLoggingConfig(): LoggingRuntimeConfig;
+export declare function resetLoggingForTests(): void;
+export declare function logAt(level: LogLevel, message: string, category?: string, fields?: LogFields): void;
+export declare const log: {
+    error: (message: string, category?: string, fields?: LogFields) => void;
+    warn: (message: string, category?: string, fields?: LogFields) => void;
+    info: (message: string, category?: string, fields?: LogFields) => void;
+    debug: (message: string, category?: string, fields?: LogFields) => void;
+    trace: (message: string, category?: string, fields?: LogFields) => void;
+};
 export declare function debug(msg: string, category?: string): void;
 export declare function debugContext(action: string, file: string, sizeBytes: number): void;
 export declare function debugCompact(sessionCount: number, totalTurns: number): void;