@crouton-kit/crouter 0.1.3 → 0.1.6

package/dist/core/spawn.js

@@ -0,0 +1,309 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, watch, readFileSync, existsSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { general, notFound } from './errors.js';
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const PANE_POLL_MS = 2000;
+export const DEFAULT_PANE_OPTS = {
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+};
+function isInTmux() {
+    return Boolean(process.env.TMUX);
+}
+function sessionRoot() {
+    const root = join(tmpdir(), 'crtr-sessions');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+export function createSession() {
+    const id = randomUUID();
+    const dir = join(sessionRoot(), id);
+    mkdirSync(dir, { recursive: true });
+    return { id, dir };
+}
+export function submitToSession(sessionDir, content) {
+    const tmp = join(sessionDir, '.content.tmp');
+    const final = join(sessionDir, 'content');
+    writeFileSync(tmp, content, 'utf8');
+    renameSync(tmp, final);
+}
+function paneAlive(paneId) {
+    const result = spawnSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return false;
+    return result.stdout.split('\n').some((line) => line.trim() === paneId);
+}
+function killPane(paneId) {
+    spawnSync('tmux', ['kill-pane', '-t', paneId], { stdio: 'ignore' });
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
+ * then schedule the originating pane to be killed after `killAfterSeconds`.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the user can `/clear` to fall back to a normal default Claude session.
+ *
+ * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ */
+export function spawnAndDetach(opts) {
+    if (!isInTmux()) {
+        return {
+            status: 'not-in-tmux',
+            message: 'handoff requires tmux (TMUX env var not set)',
+        };
+    }
+    const claudeCmd = [
+        'claude',
+        '--dangerously-skip-permissions',
+        shellQuote(opts.prompt),
+    ].join(' ');
+    const splitArgs = [];
+    if (opts.placement === 'new-window') {
+        splitArgs.push('new-window');
+    }
+    else {
+        splitArgs.push('split-window');
+        splitArgs.push(opts.placement === 'split-h' ? '-h' : '-v');
+    }
+    splitArgs.push('-P', '-F', '#{pane_id}');
+    splitArgs.push('-c', opts.cwd);
+    splitArgs.push(claudeCmd);
+    const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? 'tmux split-window/new-window failed' : stderrText;
+        return { status: 'spawn-failed', message: msg };
+    }
+    const paneId = split.stdout.trim();
+    // Schedule self-kill of the originating pane. We detach this so it survives
+    // crtr's exit.
+    const currentPane = process.env.TMUX_PANE;
+    if (currentPane !== undefined && currentPane !== '' && opts.killAfterSeconds > 0) {
+        const killCmd = `sleep ${opts.killAfterSeconds}; tmux kill-pane -t ${currentPane}`;
+        spawnSync('sh', ['-c', `nohup sh -c ${shellQuote(killCmd)} </dev/null >/dev/null 2>&1 &`], {
+            stdio: 'ignore',
+        });
+    }
+    return {
+        status: 'spawned',
+        paneId,
+        message: `handed off to pane ${paneId}; this pane will close in ${opts.killAfterSeconds}s`,
+    };
+}
+/**
+ * Spawn a side-pane `claude` reviewer. Blocks until the reviewer calls
+ * `crtr agent submit <content>`, the 10-min budget elapses, or the pane is closed.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the reviewer is a normal Claude session running a single task.
+ */
+export async function spawnSidePaneReview(opts) {
+    if (!isInTmux()) {
+        throw general('side-pane review requires tmux (TMUX env var not set)');
+    }
+    const session = createSession();
+    const timeoutMs = opts.timeoutMs;
+    const cwd = opts.cwd;
+    const claudeCmd = [
+        'claude',
+        '-p',
+        '--dangerously-skip-permissions',
+        shellQuote(opts.prompt),
+    ].join(' ');
+    // After claude exits, sleep briefly so the watcher can confirm submission.
+    // The watcher kills the pane anyway once content arrives.
+    const fullCmd = `cd ${shellQuote(cwd)} && ${claudeCmd}; sleep 2`;
+    const splitArgs = [
+        'split-window',
+        '-h',
+        '-P',
+        '-F',
+        '#{pane_id}',
+        '-e',
+        `CRTR_SESSION=${session.id}`,
+        '-e',
+        `CRTR_PIPE=${session.dir}`,
+        fullCmd,
+    ];
+    const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        rmSync(session.dir, { recursive: true, force: true });
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? 'tmux split-window failed' : stderrText;
+        return {
+            status: 'spawn-failed',
+            content: msg,
+            sessionDir: session.dir,
+        };
+    }
+    const paneId = split.stdout.trim();
+    const contentPath = join(session.dir, 'content');
+    const result = await waitForResult(session.dir, contentPath, paneId, timeoutMs);
+    if (paneAlive(paneId))
+        killPane(paneId);
+    try {
+        rmSync(session.dir, { recursive: true, force: true });
+    }
+    catch {
+        /* noop */
+    }
+    return { ...result, paneId, sessionDir: session.dir };
+}
+function metaPath(sessionDir) {
+    return join(sessionDir, 'meta.json');
+}
+function writeSessionMeta(sessionDir, meta) {
+    writeFileSync(metaPath(sessionDir), JSON.stringify(meta), 'utf8');
+}
+function readSessionMeta(sessionDir) {
+    const p = metaPath(sessionDir);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sessionDirForId(sessionId) {
+    return join(sessionRoot(), sessionId);
+}
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+/**
+ * Async sibling spawn. Launches a claude session in a new tmux pane or window
+ * (depending on current pane count vs maxPanesPerWindow). Returns immediately
+ * with the crtr session id; the parent stays alive.
+ *
+ * If `fork` is set, uses `claude --resume <id> --fork-session` so the child
+ * gets a fresh session id and does not contend with the parent's JSONL.
+ */
+export function spawnAgent(opts) {
+    if (!isInTmux()) {
+        return {
+            status: 'not-in-tmux',
+            message: 'crtr agent requires tmux (TMUX env var not set)',
+        };
+    }
+    const session = createSession();
+    const claudeParts = ['claude'];
+    if (opts.fork !== undefined) {
+        claudeParts.push('--resume', opts.fork.sessionId, '--fork-session');
+    }
+    claudeParts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
+    const claudeCmd = claudeParts.join(' ');
+    const useNewWindow = countPanesInCurrentWindow() >= opts.maxPanesPerWindow;
+    const placement = useNewWindow ? 'new-window' : 'split-window';
+    const tmuxArgs = [placement];
+    if (!useNewWindow)
+        tmuxArgs.push('-h');
+    tmuxArgs.push('-P', '-F', '#{pane_id}', '-c', opts.cwd, '-e', `CRTR_SESSION=${session.id}`, '-e', `CRTR_PIPE=${session.dir}`, claudeCmd);
+    const split = spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        rmSync(session.dir, { recursive: true, force: true });
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? `tmux ${placement} failed` : stderrText;
+        return { status: 'spawn-failed', message: msg };
+    }
+    const paneId = split.stdout.trim();
+    writeSessionMeta(session.dir, {
+        paneId,
+        createdAt: Date.now(),
+        kind: opts.fork !== undefined ? 'fork' : 'new',
+    });
+    return {
+        status: 'spawned',
+        sessionId: session.id,
+        paneId,
+        placement,
+        message: `agent ${session.id} spawned in pane ${paneId} (${placement})`,
+    };
+}
+/**
+ * Block until the agent identified by `sessionId` calls `crtr agent submit`.
+ * Returns content + status. Cleans up the session dir on completion.
+ */
+export async function awaitSession(sessionId, opts) {
+    const sessionDir = sessionDirForId(sessionId);
+    if (!existsSync(sessionDir)) {
+        throw notFound(`agent session not found: ${sessionId} (looked at ${sessionDir})`);
+    }
+    const meta = readSessionMeta(sessionDir);
+    let paneId;
+    if (meta !== undefined && meta.paneId !== '') {
+        paneId = meta.paneId;
+    }
+    const contentPath = join(sessionDir, 'content');
+    const result = await waitForResult(sessionDir, contentPath, paneId, opts.timeoutMs);
+    if (opts.killPane && paneId !== undefined && paneAlive(paneId))
+        killPane(paneId);
+    try {
+        rmSync(sessionDir, { recursive: true, force: true });
+    }
+    catch {
+        /* noop */
+    }
+    return { ...result, paneId, sessionDir };
+}
+function waitForResult(sessionDir, contentPath, paneId, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (status, content) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutTimer);
+            if (paneTimer !== undefined)
+                clearInterval(paneTimer);
+            try {
+                watcher.close();
+            }
+            catch {
+                /* noop */
+            }
+            resolve({ status, content });
+        };
+        const watcher = watch(sessionDir, (_event, name) => {
+            if (name === 'content' && existsSync(contentPath)) {
+                const content = readFileSync(contentPath, 'utf8');
+                finish('submitted', content);
+            }
+        });
+        if (existsSync(contentPath)) {
+            finish('submitted', readFileSync(contentPath, 'utf8'));
+            return;
+        }
+        const timeoutTimer = setTimeout(() => {
+            finish('timeout', '');
+        }, timeoutMs);
+        let paneTimer;
+        if (paneId !== undefined) {
+            const watchedPaneId = paneId;
+            paneTimer = setInterval(() => {
+                if (!paneAlive(watchedPaneId)) {
+                    if (existsSync(contentPath)) {
+                        finish('submitted', readFileSync(contentPath, 'utf8'));
+                    }
+                    else {
+                        finish('pane-closed', '');
+                    }
+                }
+            }, PANE_POLL_MS);
+        }
+    });
+}

package/dist/prompts/agent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * First user message for a spec → plan handoff.
+ * Bundles the full planning workflow with the spec to plan.
+ */
+export declare function planHandoffPrompt(specPath: string, plansDir: string): string;
+/**
+ * First user message for a plan → implementation handoff.
+ */
+export declare function implementHandoffPrompt(planPath: string): string;
+/**
+ * First user message for a handoff to code review of the working tree.
+ */
+export declare function reviewHandoffPrompt(): string;

package/dist/prompts/agent.js

@@ -0,0 +1,114 @@
+import { planPrompt } from './plan.js';
+/**
+ * First user message for a spec → plan handoff.
+ * Bundles the full planning workflow with the spec to plan.
+ */
+export function planHandoffPrompt(specPath, plansDir) {
+    return `${planPrompt(plansDir)}
+
+---
+
+## Your task
+
+You were just launched in a new tmux pane via \`crtr agent plan\`. A spec
+has been approved upstream and you are responsible for turning it into a plan.
+
+**Spec to plan:** ${specPath}
+
+Read the spec end-to-end before anything else. Then proceed through the
+workflow above. When you save the plan, pass \`--spec <spec-name>\` so the
+plan reviewer can check alignment.
+
+The originating pane has closed; the user is watching you here. Begin now.`;
+}
+/**
+ * First user message for a plan → implementation handoff.
+ */
+export function implementHandoffPrompt(planPath) {
+    return `You are an implementation agent. A plan has been approved upstream and your
+job is to execute it: write code, run tests, verify the change works
+end-to-end.
+
+**Plan to implement:** ${planPath}
+
+## Process
+
+1. Read the plan end-to-end before touching code.
+2. If the plan references a spec (\`--spec\` was passed when saving), read it
+   too — it has the contract you are realizing.
+3. Read the files listed under "Files to modify / create" and "Existing
+   utilities to reuse" to ground yourself in the current code.
+4. Execute the plan step by step. Stay within scope — if the plan does not
+   call for a change, do not make it.
+5. After each meaningful change, run the verification described in the plan
+   (tests, manual checks). Fix anything that fails before continuing.
+6. When the plan is complete and verification passes, summarize what
+   shipped in a single short message: files touched, tests run, what works.
+
+## Guardrails
+
+- **Do not redesign.** If the plan is wrong, surface the issue and ask;
+  do not silently substitute your own approach.
+- **Do not expand scope.** No drive-by refactors, no "while I'm here" cleanup.
+- **Honor existing conventions.** Match the file's style, naming, and
+  patterns. Use the utilities the plan named.
+- Commit only if the user asks.
+
+When verification passes, your turn ends. The user may then ask for a code
+review via \`crtr agent review\`.
+
+You were launched in a new tmux pane via \`crtr agent implement\`. The
+originating pane has closed; the user is watching you here. Begin by reading
+the plan.`;
+}
+/**
+ * First user message for a handoff to code review of the working tree.
+ */
+export function reviewHandoffPrompt() {
+    return `You are a code reviewer. A change has just been implemented and your job is
+to review it before it lands.
+
+## Scope
+
+Review the **uncommitted** changes in the working tree of the current
+directory. Use \`git status\` and \`git diff\` (including staged changes via
+\`git diff --cached\`) to enumerate what changed. If there are zero changes,
+say so and stop.
+
+## What to check
+
+| Category | What to look for |
+|----------|------------------|
+| Correctness | Does the code do what it claims? Off-by-ones, wrong branches, missed cases. |
+| Security | Injection, auth bypass, leaking secrets, unsafe defaults. |
+| Style fit | Matches the file's existing conventions, naming, error-handling style. |
+| Tests | Are there tests for new behavior? Do they actually exercise the change? |
+| Scope | Did the change stay within its mandate, or sneak in unrelated edits? |
+| Reuse | Are there existing utilities that should have been used? |
+
+## Calibration
+
+Only flag issues that would matter to the next reader, on-call, or future
+maintainer. Nits are fine in a "Recommendations" section, but **do not block
+on style preferences**. Approve unless something is wrong, missing, or risky.
+
+## Output
+
+\`\`\`
+## Code Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [file:line]: [specific issue] — [why it matters]
+
+**Recommendations (advisory):**
+- [suggestions]
+\`\`\`
+
+After printing the review, your turn ends.
+
+You were launched in a new tmux pane via \`crtr agent review\`. The
+originating pane has closed; the user is watching you here. Begin by checking
+the working tree.`;
+}

package/dist/prompts/plan.js

@@ -87,14 +87,50 @@ EOF
 
 - Pick a short, descriptive kebab-case name. Names may be nested
   (\`crtr plan --name auth/jwt-refresh\`) — they become subdirectories.
+- If this plan implements a saved spec, pass \`--spec <spec-name>\` so the
+  reviewer can check alignment:
+  \`crtr plan --name <name> --spec <spec-name> <<'EOF' ... EOF\`
 - The file lands at \`${plansDir}/<name>.md\`.
 - If you are running inside tmux, the saved plan auto-opens in a side pane
   via termrender. No extra step needed.
 
-## Phase 5: Done
+## Phase 5: Review
 
-Your turn ends after the save command succeeds. No need to summarize the plan
-in chat — the user can read the file.
+By default the save command **blocks** while a reviewer agent reads the plan
+(and the spec, if \`--spec\` was passed) in a side pane (10-min budget) and
+returns its findings on stdout under a \`--- review ---\` marker. **Read the
+review** when the command returns:
+
+- If \`Status: Approved\`, you are done.
+- If \`Status: Issues Found\`, address the listed issues by editing the plan
+  (\`crtr plan edit <name>\` or rewriting via the save command), then save
+  again to re-trigger review.
+
+Pass \`--no-review\` only when the plan is genuinely trivial (one-line fix,
+typo, single-file rename). For anything substantive, take the review.
+
+## Phase 6: Oversize check
+
+If the save command emits a \`--- advisory ---\` warning that the plan is
+too long, do not ignore it. Split the plan into a short index plan plus
+one or more nested part plans, each under the threshold, and re-save. The
+implementer will execute parts one at a time; very long plans tend to be
+under-decomposed.
+
+## Phase 7: Done
+
+After the review returns Approved (or you have addressed its issues), your
+turn ends. No need to summarize the plan in chat — the user can read the file.
+
+If the user is ready to start building, ask once whether they want to hand
+off now. If yes, run:
+
+\`\`\`bash
+crtr agent implement --plan <name>
+\`\`\`
+
+This fires up an implementer in a new tmux pane and closes the current
+pane a few seconds later. Do NOT run this without the user's go-ahead.
 
 ## See also
 

package/dist/prompts/review.d.ts

@@ -0,0 +1,2 @@
+export declare function specReviewPrompt(specPath: string): string;
+export declare function planReviewPrompt(planPath: string, specPath: string | null): string;

package/dist/prompts/review.js

@@ -0,0 +1,103 @@
+const SUBMIT_INSTRUCTIONS = `## Delivering your review
+
+When your review is complete, run a single Bash command to submit it back to
+the parent agent:
+
+\`\`\`bash
+crtr agent submit "$(cat <<'EOF'
+<your full review markdown here, using the Output Format below>
+EOF
+)"
+\`\`\`
+
+The pane will close automatically once your review is delivered. Do NOT
+summarize or chat after submission — \`crtr agent submit\` IS the response.
+
+If you cannot complete the review (file missing, totally malformed, etc.),
+still call \`crtr agent submit\` with a brief explanation of why.`;
+export function specReviewPrompt(specPath) {
+    return `You are reviewing a spec document. Verify it is complete and ready for planning.
+
+**Spec to review:** ${specPath}
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+| YAGNI | Unrequested features, over-engineering |
+
+## Calibration
+
+**Only flag issues that would cause real problems during implementation planning.**
+A missing section, a contradiction, or a requirement so ambiguous it could be
+interpreted two different ways — those are issues. Minor wording improvements,
+stylistic preferences, and "sections less detailed than others" are not.
+
+Approve unless there are serious gaps that would lead to a flawed plan.
+
+## Output Format
+
+## Spec Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Section X]: [specific issue] - [why it matters for planning]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions for improvement]
+
+${SUBMIT_INSTRUCTIONS}`;
+}
+export function planReviewPrompt(planPath, specPath) {
+    const inputs = specPath === null
+        ? `**Plan to review:** ${planPath}
+
+No spec was provided for cross-reference — evaluate the plan on its own
+merits (internal completeness, task decomposition, buildability). Skip the
+"Spec Alignment" check.`
+        : `**Plan to review:** ${planPath}
+**Spec for reference:** ${specPath}
+
+Read the plan first, then the spec, then evaluate alignment and the other
+criteria below.`;
+    return `You are reviewing a plan document. Verify it is complete and ready for implementation.
+
+${inputs}
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+| Spec Alignment | Plan covers spec requirements, no major scope creep |
+| Task Decomposition | Tasks have clear boundaries, steps are actionable |
+| Buildability | Could an engineer follow this plan without getting stuck? |
+
+## Calibration
+
+**Only flag issues that would cause real problems during implementation.**
+An implementer building the wrong thing or getting stuck is an issue.
+Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+Approve unless there are serious gaps — missing requirements from the spec,
+contradictory steps, placeholder content, or tasks so vague they can't be acted on.
+
+## Output Format
+
+## Plan Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Task X, Step Y]: [specific issue] - [why it matters for implementation]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions for improvement]
+
+${SUBMIT_INSTRUCTIONS}`;
+}

package/dist/prompts/skill.d.ts

@@ -1 +1,2 @@
 export declare function skillPrompt(): string;
+export declare function skillCreatePrompt(topic: string): string;