@mandipadk7/kavi 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# Kavi
+
+Kavi is a local terminal control plane for managed Codex and Claude collaboration.
+
+Current capabilities:
+- `kavi init`: create repo-local `.kavi` config, prompt files, and ignore rules.
+- `kavi init --home`: also scaffold the user-local config file used for binary overrides.
+- `kavi doctor`: verify Node, Codex, Claude, git worktree support, and local readiness.
+- `kavi start`: start a managed session without attaching the TUI.
+- `kavi open`: create a managed session with separate Codex and Claude worktrees and open the terminal dashboard.
+- `kavi resume`: reopen the dashboard for the current repo session.
+- `kavi status`: inspect session health and task counts from any terminal.
+- `kavi paths`: inspect resolved repo-local, user-local, worktree, and runtime paths.
+- `kavi task`: enqueue a task for `codex`, `claude`, or `auto` routing.
+- `kavi tasks`: inspect the session task list with summaries and artifact availability.
+- `kavi task-output`: inspect the normalized envelope and raw output for a completed task.
+- `kavi approvals`: inspect the approval inbox.
+- `kavi approve` and `kavi deny`: resolve a pending approval request, optionally with `--remember`.
+- `kavi events`: inspect recent daemon and task events.
+- `kavi stop`: stop the background daemon for the current repo session.
+- `kavi land`: snapshot dirty agent worktrees into commits, merge them in a transient integration worktree, run validation there, and then fast-forward the target branch.
+
+Runtime model:
+- Repo-local state lives under `.kavi/`.
+- Machine-local state defaults to `~/.config/kavi` and `~/.local/state/kavi`.
+- In restricted environments you can override those with `KAVI_HOME_CONFIG_DIR` and `KAVI_HOME_STATE_DIR`.
+- User-local runtime overrides live in `~/.config/kavi/config.toml` and can point Kavi at custom `node`, `codex`, and `claude` binaries.
+- SQLite event mirroring is opt-in with `KAVI_ENABLE_SQLITE_HISTORY=1`; the default event log is JSONL under `.kavi/state/events.jsonl`.
+
+Development:
+
+```bash
+node bin/kavi.js init --home
+node bin/kavi.js doctor --json
+node bin/kavi.js paths
+node bin/kavi.js start --goal "Build the auth backend"
+node bin/kavi.js status
+node bin/kavi.js task --agent auto "Design the dashboard shell"
+node bin/kavi.js tasks
+node bin/kavi.js task-output latest
+node bin/kavi.js approvals
+node bin/kavi.js open
+node --experimental-strip-types --test src/**/*.test.ts
+```
+
+Notes:
+- The current managed task runners use the installed `codex` and `claude` CLIs directly.
+- The dashboard uses a file-backed control loop instead of local sockets so it can run in restricted shells and sandboxes.
+
+Local install options:
+
+```bash
+# Run directly from the repo
+node bin/kavi.js help
+
+# Symlink into ~/.local/bin
+./scripts/install-local.sh
+
+# Or use npm link from this repo
+npm link
+```
+
+Publishing for testers:
+
+```bash
+# authenticate once
+npm login
+
+# verify the package before publish
+npm run release:check
+
+# publish a beta that friends can install immediately
+npm run publish:beta
+
+# later, publish the stable tag
+npm run publish:latest
+```
+
+Install commands for testers:
+
+```bash
+# beta channel
+npm install -g @mandipadk7/kavi@beta
+
+# one-off
+npx @mandipadk7/kavi@beta help
+```
+
+Notes on publish:
+- The package name is scoped as `@mandipadk7/kavi` to match the npm user `mandipadk7`.
+- The publish flow now builds a compiled `dist/` directory first, and the installed CLI prefers `dist/main.js`. Source mode remains available for local development.
+- `prepublishOnly` runs the release checks automatically during publish.
+
+User-local config example:
+
+```toml
+version = 1
+
+[runtime]
+node_bin = ""
+codex_bin = "codex"
+claude_bin = "claude"
+```
+
+Planned release shape:
+- npm global install: `npm install -g @mandipadk7/kavi`
+- one-off use: `npx @mandipadk7/kavi`
+- optional native installer script or package-managed distribution after the npm workflow is stable

package/bin/kavi.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+function nodeMajor(version) {
+  return Number(version.split(".")[0] ?? 0);
+}
+
+if (nodeMajor(process.versions.node) < 25) {
+  console.error(`Kavi requires Node 25 or newer. Current runtime: ${process.version}`);
+  process.exit(1);
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const distEntrypoint = path.join(here, "..", "dist", "main.js");
+const srcEntrypoint = path.join(here, "..", "src", "main.ts");
+const useDist = fs.existsSync(distEntrypoint);
+const entrypoint = useDist ? distEntrypoint : srcEntrypoint;
+const nodeArgs = useDist
+  ? [entrypoint, ...process.argv.slice(2)]
+  : ["--experimental-strip-types", entrypoint, ...process.argv.slice(2)];
+
+const child = spawn(process.execPath, nodeArgs, {
+  stdio: "inherit",
+  env: process.env
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/dist/adapters/claude.js

@@ -0,0 +1,122 @@
+import fs from "node:fs/promises";
+import { buildEnvelopeInstruction, buildPeerMessages, buildSharedContext, extractJsonObject } from "./shared.js";
+import { runCommand } from "../process.js";
+import { buildKaviShellCommand } from "../runtime.js";
+function findWorktree(session, agent) {
+    const worktree = session.worktrees.find((item)=>item.agent === agent);
+    if (!worktree) {
+        throw new Error(`Missing worktree for ${agent}.`);
+    }
+    return worktree;
+}
+export async function writeClaudeSettings(paths, session) {
+    const buildHookCommand = (event)=>buildKaviShellCommand(session.runtime, [
+            "__hook",
+            "--repo-root",
+            paths.repoRoot,
+            "--agent",
+            "claude",
+            "--event",
+            event
+        ]);
+    const settings = {
+        permissions: {
+            defaultMode: "plan"
+        },
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: "startup|resume|compact",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("SessionStart")
+                        }
+                    ]
+                }
+            ],
+            PreToolUse: [
+                {
+                    matcher: "Bash|Edit|Write|MultiEdit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("PreToolUse")
+                        }
+                    ]
+                }
+            ],
+            PostToolUse: [
+                {
+                    matcher: "Bash|Edit|Write|MultiEdit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("PostToolUse")
+                        }
+                    ]
+                }
+            ],
+            Notification: [
+                {
+                    matcher: "permission_prompt|idle_prompt|auth_success",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("Notification")
+                        }
+                    ]
+                }
+            ],
+            Stop: [
+                {
+                    matcher: "stop",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("Stop")
+                        }
+                    ]
+                }
+            ]
+        },
+        env: {
+            KAVI_SESSION_ID: session.id
+        }
+    };
+    await fs.writeFile(paths.claudeSettingsFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+export async function runClaudeTask(session, task, paths) {
+    const worktree = findWorktree(session, "claude");
+    const claudeSessionId = `${session.id}-claude`;
+    await writeClaudeSettings(paths, session);
+    const prompt = [
+        buildSharedContext(session, task, "claude"),
+        "",
+        `User goal or prompt:\n${task.prompt}`,
+        "",
+        buildEnvelopeInstruction("claude", worktree.path)
+    ].join("\n");
+    const result = await runCommand(session.runtime.claudeExecutable, [
+        "-p",
+        "--session-id",
+        claudeSessionId,
+        "--settings",
+        paths.claudeSettingsFile,
+        "--permission-mode",
+        "plan",
+        prompt
+    ], {
+        cwd: worktree.path
+    });
+    const rawOutput = result.code === 0 ? result.stdout : `${result.stdout}\n${result.stderr}`;
+    const envelope = extractJsonObject(rawOutput);
+    return {
+        envelope,
+        raw: rawOutput
+    };
+}
+export { buildPeerMessages };
+
+
+//# sourceURL=adapters/claude.ts

package/dist/adapters/codex.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { runCommand } from "../process.js";
+import { buildEnvelopeInstruction, buildPeerMessages, buildSharedContext, extractJsonObject } from "./shared.js";
+function findWorktree(session, agent) {
+    const worktree = session.worktrees.find((item)=>item.agent === agent);
+    if (!worktree) {
+        throw new Error(`Missing worktree for ${agent}.`);
+    }
+    return worktree;
+}
+export async function runCodexTask(session, task, paths) {
+    const worktree = findWorktree(session, "codex");
+    const outputFile = path.join(paths.runtimeDir, `codex-${task.id}.txt`);
+    const prompt = [
+        buildSharedContext(session, task, "codex"),
+        "",
+        `User goal or prompt:\n${task.prompt}`,
+        "",
+        buildEnvelopeInstruction("codex", worktree.path)
+    ].join("\n");
+    const result = await runCommand(session.runtime.codexExecutable, [
+        "exec",
+        "--skip-git-repo-check",
+        "--cd",
+        worktree.path,
+        "--sandbox",
+        "workspace-write",
+        "--output-last-message",
+        outputFile,
+        prompt
+    ], {
+        cwd: session.repoRoot
+    });
+    const rawOutput = result.code === 0 ? await fs.readFile(outputFile, "utf8") : `${result.stdout}\n${result.stderr}`;
+    const envelope = extractJsonObject(rawOutput);
+    return {
+        envelope,
+        raw: rawOutput
+    };
+}
+export { buildPeerMessages };
+
+
+//# sourceURL=adapters/codex.ts

package/dist/adapters/shared.js

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import { nowIso } from "../paths.js";
+export function extractJsonObject(rawOutput) {
+    const trimmed = rawOutput.trim();
+    const fencedMatch = trimmed.match(/```json\s*([\s\S]*?)```/i);
+    const candidate = fencedMatch ? fencedMatch[1] : trimmed.slice(trimmed.indexOf("{"), trimmed.lastIndexOf("}") + 1);
+    if (!candidate || !candidate.trim().startsWith("{")) {
+        throw new Error(`Unable to find JSON object in output:\n${rawOutput}`);
+    }
+    const parsed = JSON.parse(candidate);
+    return {
+        summary: parsed.summary ?? "",
+        status: parsed.status ?? "completed",
+        blockers: Array.isArray(parsed.blockers) ? parsed.blockers.map((item)=>String(item)) : [],
+        nextRecommendation: parsed.nextRecommendation === null || typeof parsed.nextRecommendation === "string" ? parsed.nextRecommendation : null,
+        peerMessages: Array.isArray(parsed.peerMessages) ? parsed.peerMessages.map((message)=>({
+                to: message.to,
+                intent: message.intent,
+                subject: String(message.subject ?? ""),
+                body: String(message.body ?? "")
+            })) : []
+    };
+}
+export function buildPeerMessages(envelope, from, taskId) {
+    return envelope.peerMessages.map((message)=>({
+            id: randomUUID(),
+            taskId,
+            from,
+            to: message.to,
+            intent: message.intent,
+            subject: message.subject,
+            body: message.body,
+            createdAt: nowIso()
+        }));
+}
+export function buildSharedContext(session, task, agent) {
+    const inbox = session.peerMessages.filter((message)=>message.to === agent).slice(-session.config.messageLimit).map((message)=>`- [${message.intent}] ${message.subject}: ${message.body}`).join("\n");
+    const tasks = session.tasks.map((item)=>`- ${item.id} | ${item.owner} | ${item.status} | ${item.title}`).join("\n");
+    return [
+        `Session goal: ${session.goal ?? "No goal recorded."}`,
+        `Current task: ${task.title}`,
+        "Task board:",
+        tasks || "- none",
+        `Peer inbox for ${agent}:`,
+        inbox || "- empty"
+    ].join("\n");
+}
+export function buildEnvelopeInstruction(agent, worktreePath) {
+    const peer = agent === "codex" ? "claude" : "codex";
+    const focus = agent === "codex" ? "Focus on planning, architecture, backend concerns, codebase structure, and implementation risks." : "Focus on intent, user experience, frontend structure, and interaction quality.";
+    return [
+        focus,
+        `You are working inside the worktree at ${worktreePath}.`,
+        `Return JSON only with this exact shape:`,
+        "{",
+        '  "summary": "short summary",',
+        '  "status": "completed" | "blocked" | "needs_review",',
+        '  "blockers": ["optional blockers"],',
+        '  "nextRecommendation": "optional next step or null",',
+        '  "peerMessages": [',
+        `    { "to": "${peer}", "intent": "question|handoff|review_request|blocked|context_share", "subject": "short", "body": "short" }`,
+        "  ]",
+        "}",
+        "Do not wrap the JSON in Markdown."
+    ].join("\n");
+}
+
+
+//# sourceURL=adapters/shared.ts

package/dist/approvals.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, fileExists, readJson, writeJson } from "./fs.js";
+import { nowIso } from "./paths.js";
+function normalizeWhitespace(value) {
+    return value.replaceAll(/\s+/g, " ").trim();
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    } catch  {
+        return String(value);
+    }
+}
+function truncate(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, limit - 3))}...`;
+}
+function readString(input, key) {
+    const value = input[key];
+    return typeof value === "string" ? value : null;
+}
+function readObject(input, key) {
+    const value = input[key];
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export function describeToolUse(payload) {
+    const toolName = readString(payload, "tool_name") ?? "UnknownTool";
+    const toolInput = readObject(payload, "tool_input");
+    let detail = "";
+    switch(toolName){
+        case "Bash":
+            detail = normalizeWhitespace(readString(toolInput, "command") ?? safeJson(toolInput));
+            break;
+        case "Write":
+        case "Edit":
+        case "MultiEdit":
+        case "Read":
+            detail = readString(toolInput, "file_path") ?? safeJson(toolInput);
+            break;
+        case "Glob":
+        case "Grep":
+            detail = readString(toolInput, "pattern") ?? safeJson(toolInput);
+            break;
+        case "WebFetch":
+            detail = readString(toolInput, "url") ?? safeJson(toolInput);
+            break;
+        default:
+            detail = safeJson(toolInput);
+            break;
+    }
+    const normalized = normalizeWhitespace(detail);
+    return {
+        toolName,
+        summary: `${toolName}: ${truncate(normalized || "(no details)", 140)}`,
+        matchKey: `${toolName}:${normalized.toLowerCase()}`
+    };
+}
+async function loadRequests(paths) {
+    if (!await fileExists(paths.approvalsFile)) {
+        return [];
+    }
+    return readJson(paths.approvalsFile);
+}
+async function saveRequests(paths, requests) {
+    await writeJson(paths.approvalsFile, requests);
+}
+export async function listApprovalRequests(paths, options = {}) {
+    const requests = await loadRequests(paths);
+    const filtered = options.includeResolved ? requests : requests.filter((request)=>request.status === "pending");
+    return filtered.sort((left, right)=>left.createdAt.localeCompare(right.createdAt));
+}
+export async function createApprovalRequest(paths, input) {
+    const descriptor = describeToolUse(input.payload);
+    const timestamp = nowIso();
+    const request = {
+        id: randomUUID(),
+        sessionId: input.sessionId,
+        repoRoot: input.repoRoot,
+        agent: input.agent,
+        hookEvent: input.hookEvent,
+        toolName: descriptor.toolName,
+        summary: descriptor.summary,
+        matchKey: descriptor.matchKey,
+        payload: input.payload,
+        status: "pending",
+        decision: null,
+        remember: false,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        resolvedAt: null
+    };
+    const requests = await loadRequests(paths);
+    requests.push(request);
+    await saveRequests(paths, requests);
+    return request;
+}
+export async function loadApprovalRequest(paths, requestId) {
+    const requests = await loadRequests(paths);
+    return requests.find((request)=>request.id === requestId) ?? null;
+}
+export async function resolveApprovalRequest(paths, requestId, decision, remember) {
+    const requests = await loadRequests(paths);
+    const request = requests.find((item)=>item.id === requestId);
+    if (!request) {
+        throw new Error(`Approval request ${requestId} not found.`);
+    }
+    request.status = decision === "allow" ? "approved" : "denied";
+    request.decision = decision;
+    request.remember = remember;
+    request.updatedAt = nowIso();
+    request.resolvedAt = request.updatedAt;
+    await saveRequests(paths, requests);
+    if (remember) {
+        await upsertApprovalRule(paths, request, decision);
+    }
+    return request;
+}
+export async function expireApprovalRequest(paths, requestId) {
+    const requests = await loadRequests(paths);
+    const request = requests.find((item)=>item.id === requestId);
+    if (!request || request.status !== "pending") {
+        return;
+    }
+    request.status = "expired";
+    request.updatedAt = nowIso();
+    request.resolvedAt = request.updatedAt;
+    await saveRequests(paths, requests);
+}
+export async function waitForApprovalDecision(paths, requestId, timeoutMs = 300_000) {
+    const startedAt = Date.now();
+    while(Date.now() - startedAt < timeoutMs){
+        const request = await loadApprovalRequest(paths, requestId);
+        if (request && request.status !== "pending") {
+            return request;
+        }
+        await new Promise((resolve)=>setTimeout(resolve, 500));
+    }
+    await expireApprovalRequest(paths, requestId);
+    return loadApprovalRequest(paths, requestId);
+}
+async function loadRules(paths) {
+    if (!await fileExists(paths.homeApprovalRulesFile)) {
+        return [];
+    }
+    return readJson(paths.homeApprovalRulesFile);
+}
+async function saveRules(paths, rules) {
+    await ensureDir(path.dirname(paths.homeApprovalRulesFile));
+    await writeJson(paths.homeApprovalRulesFile, rules);
+}
+export async function findApprovalRule(paths, input) {
+    const rules = await loadRules(paths);
+    return rules.find((rule)=>rule.repoRoot === input.repoRoot && rule.agent === input.agent && rule.toolName === input.toolName && rule.matchKey === input.matchKey) ?? null;
+}
+async function upsertApprovalRule(paths, request, decision) {
+    const rules = await loadRules(paths);
+    const existing = rules.find((rule)=>rule.repoRoot === request.repoRoot && rule.agent === request.agent && rule.toolName === request.toolName && rule.matchKey === request.matchKey);
+    if (existing) {
+        existing.decision = decision;
+        existing.summary = request.summary;
+        existing.updatedAt = nowIso();
+        await saveRules(paths, rules);
+        return;
+    }
+    const timestamp = nowIso();
+    rules.push({
+        id: randomUUID(),
+        repoRoot: request.repoRoot,
+        agent: request.agent,
+        toolName: request.toolName,
+        matchKey: request.matchKey,
+        summary: request.summary,
+        decision,
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+    await saveRules(paths, rules);
+}
+
+
+//# sourceURL=approvals.ts

package/dist/command-queue.js

@@ -0,0 +1,25 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import { ensureDir, fileExists } from "./fs.js";
+import { nowIso } from "./paths.js";
+export async function appendCommand(paths, type, payload) {
+    const command = {
+        id: randomUUID(),
+        type,
+        createdAt: nowIso(),
+        payload
+    };
+    await ensureDir(paths.runtimeDir);
+    await fs.appendFile(paths.commandsFile, `${JSON.stringify(command)}\n`, "utf8");
+}
+export async function consumeCommands(paths) {
+    if (!await fileExists(paths.commandsFile)) {
+        return [];
+    }
+    const content = await fs.readFile(paths.commandsFile, "utf8");
+    await fs.writeFile(paths.commandsFile, "", "utf8");
+    return content.split(/\r?\n/).filter(Boolean).map((line)=>JSON.parse(line));
+}
+
+
+//# sourceURL=command-queue.ts