speckit-assistant 0.1.3 → 0.1.5

package/bin/adapters/secondary/agent/ProcessAgentRunner.js

@@ -34,128 +34,233 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProcessAgentRunner = void 0;
-const child_process_1 = require("child_process");
+const ptyLoader_1 = require("../pty/ptyLoader");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const PHASE_COMMANDS = {
-    constitution: '/speckit.constitution',
-    specification: '/speckit.specify',
-    clarification: '/speckit.clarify',
-    planning: '/speckit.plan',
-    checklist: '/speckit.checklist',
-    analyze: '/speckit.analyze',
-    tasks: '/speckit.tasks',
-    taskstoissues: '/speckit.taskstoissues',
-    implementation: '/speckit.implement',
+    constitution: "/speckit.constitution",
+    specification: "/speckit.specify",
+    clarification: "/speckit.clarify",
+    planning: "/speckit.plan",
+    checklist: "/speckit.checklist",
+    analyze: "/speckit.analyze",
+    tasks: "/speckit.tasks",
+    taskstoissues: "/speckit.taskstoissues",
+    implementation: "/speckit.implement",
 };
 class ProcessAgentRunner {
+    activeProcesses = new Map();
+    phaseKey(featureName, phase) {
+        return `${featureName || "global"}-${phase}`;
+    }
+    personaKey(featureName, id) {
+        return `${featureName}-impl-persona-${id}`;
+    }
+    async writeStdin(phase, featureName, text, personaId) {
+        const procKey = personaId && featureName
+            ? this.personaKey(featureName, personaId)
+            : this.phaseKey(featureName, phase);
+        const child = this.activeProcesses.get(procKey);
+        if (child) {
+            // The frontend xterm sends raw keystrokes (arrow keys, Enter as '\r', etc.)
+            // so we forward them verbatim — this is what lets interactive pickers like
+            // the clarify Q&A be navigated, not just line-based answers.
+            child.write(text);
+            return true;
+        }
+        return false;
+    }
+    async resize(phase, featureName, cols, rows, personaId) {
+        const procKey = personaId && featureName
+            ? this.personaKey(featureName, personaId)
+            : this.phaseKey(featureName, phase);
+        const child = this.activeProcesses.get(procKey);
+        if (!child)
+            return false;
+        try {
+            child.resize(cols, rows);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stop(phase, featureName, personaId) {
+        const procKey = personaId && featureName
+            ? this.personaKey(featureName, personaId)
+            : this.phaseKey(featureName, phase);
+        const child = this.activeProcesses.get(procKey);
+        if (child) {
+            try {
+                child.kill();
+                this.activeProcesses.delete(procKey);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
     async runPhase(workspacePath, phase, featureName, agentConfig, userPrompt, onData) {
-        const specArg = phase !== 'constitution' && featureName ? `specs/${featureName}` : null;
-        const slashCmd = `${PHASE_COMMANDS[phase]}${specArg ? ` ${specArg}` : ''}`;
+        const specArg = phase !== "constitution" && featureName ? `specs/${featureName}` : null;
+        const slashCmd = `${PHASE_COMMANDS[phase]}${specArg ? ` ${specArg}` : ""}`;
         const context = userPrompt?.trim();
         const fullPrompt = context ? `${context}\n\n${slashCmd}` : slashCmd;
+        return this.spawnAgent({
+            workspacePath,
+            procKey: this.phaseKey(featureName, phase),
+            doneTag: phase,
+            agentConfig,
+            fullPrompt,
+            onData,
+        });
+    }
+    async runPersona(workspacePath, featureName, persona, agentConfig, onData) {
+        // Personas always operate on a specific feature's artifacts.
+        const fullPrompt = `${persona.command} specs/${featureName}`;
+        return this.spawnAgent({
+            workspacePath,
+            procKey: this.personaKey(featureName, persona.id),
+            doneTag: `persona:${persona.id}`,
+            agentConfig,
+            fullPrompt,
+            onData,
+            persona,
+        });
+    }
+    // Shared spawn path for both phase and persona runs: spawns the agent CLI
+    // under a PTY (so interactive CLIs detect a TTY), streams output, and resolves
+    // with the exit code.
+    spawnAgent(opts) {
+        const { workspacePath, procKey, doneTag, agentConfig, fullPrompt, onData } = opts;
         const { cmd, args, stdin } = this.buildSpawnArgs(agentConfig, fullPrompt);
-        const isWin = process.platform === 'win32';
         return new Promise((resolve) => {
-            onData?.(`Running: ${cmd} ${args.join(' ')}\n\n`);
-            const child = isWin
-                ? (0, child_process_1.spawn)(cmd, args, {
-                    cwd: workspacePath,
-                    shell: true,
-                    stdio: ['pipe', 'pipe', 'pipe']
-                })
-                : (() => {
-                    const shell = process.env.SHELL || '/bin/sh';
-                    const escapedArgs = [cmd, ...args].map(arg => `'${arg.replace(/'/g, "'\\''")}'`).join(' ');
-                    return (0, child_process_1.spawn)(shell, ['-l', '-c', escapedArgs], {
-                        cwd: workspacePath,
-                        stdio: ['pipe', 'pipe', 'pipe']
-                    });
-                })();
-            if (stdin !== undefined && child.stdin) {
-                child.stdin.write(stdin);
-                child.stdin.end();
-            }
-            child.stdout.on('data', (data) => {
-                const text = data.toString();
-                onData?.(text);
+            onData?.(`Running: ${cmd} ${args.join(" ")}\n\n`);
+            // Spawn the agent under a real pseudo-terminal. This is what makes
+            // interactive CLIs (e.g. the clarify Q&A) detect a TTY via isatty() and
+            // actually prompt the user instead of running single-shot. We still go
+            // through a login shell so PATH/aliases resolve the agent binary the same
+            // way they would in the user's own terminal.
+            const isWin = process.platform === "win32";
+            const ptyFile = isWin
+                ? process.env.COMSPEC || "cmd.exe"
+                : process.env.SHELL || "/bin/bash";
+            const ptyArgs = isWin
+                ? ["/c", [cmd, ...args].join(" ")]
+                : [
+                    "-l",
+                    "-c",
+                    [cmd, ...args]
+                        .map((a) => `'${a.replace(/'/g, "'\\''")}'`)
+                        .join(" "),
+                ];
+            const child = (0, ptyLoader_1.loadPty)().spawn(ptyFile, ptyArgs, {
+                name: "xterm-256color",
+                cols: 120,
+                rows: 30,
+                cwd: workspacePath,
+                env: {
+                    ...process.env,
+                    TERM: "xterm-256color",
+                    ...(opts.persona
+                        ? {
+                            SPECKIT_PERSONA_ID: opts.persona.id || "",
+                            SPECKIT_PERSONA_LABEL: opts.persona.label || "",
+                            SPECKIT_PERSONA_MODEL: opts.persona.model || "",
+                            SPECKIT_PERSONA_SYSTEM_PROMPT: opts.persona.systemPrompt || "",
+                            SPECKIT_PERSONA_CAPABILITIES: Array.isArray(opts.persona.capabilities)
+                                ? opts.persona.capabilities.join(",")
+                                : "",
+                            SPECKIT_PERSONA_TOOLS: Array.isArray(opts.persona.tools)
+                                ? opts.persona.tools.join(",")
+                                : "",
+                        }
+                        : {}),
+                },
             });
-            child.stderr.on('data', (data) => {
-                const text = data.toString();
-                onData?.(text);
+            this.activeProcesses.set(procKey, child);
+            // For agents that receive their prompt over stdin, feed it now and send
+            // EOF (Ctrl-D) so the single-shot CLI starts processing. Agents that take
+            // the prompt as an argument keep the channel open so the user can answer
+            // interactive prompts (e.g. clarify) through writeStdin().
+            if (stdin !== undefined) {
+                child.write(stdin);
+                child.write("\x04");
+            }
+            child.onData((data) => {
+                onData?.(data);
             });
-            child.on('close', (code) => {
-                const exitCode = code === null ? -1 : code;
+            child.onExit(({ exitCode }) => {
+                this.activeProcesses.delete(procKey);
                 onData?.(`\nProcess exited with code ${exitCode}\n`);
                 // Write the phase done file so local watch logs it
                 try {
-                    const runtimeDir = path.join(workspacePath, '.specify', '.runtime');
+                    const runtimeDir = path.join(workspacePath, ".specify", ".runtime");
                     if (!fs.existsSync(runtimeDir)) {
                         fs.mkdirSync(runtimeDir, { recursive: true });
                     }
-                    fs.writeFileSync(path.join(runtimeDir, 'phase-done.txt'), `${phase}:${exitCode}`, 'utf-8');
+                    fs.writeFileSync(path.join(runtimeDir, "phase-done.txt"), `${doneTag}:${exitCode}`, "utf-8");
                 }
                 catch {
                     // ignore
                 }
                 resolve(exitCode);
             });
-            child.on('error', (err) => {
-                onData?.(`\nFailed to start process: ${err.message}\n`);
-                resolve(-1);
-            });
         });
     }
     buildSpawnArgs(config, prompt) {
         const agentType = config.agentType;
         const cliPath = config.agentPath || this.getDefaultCli(agentType);
         switch (agentType) {
-            case 'claude':
+            case "claude":
                 return {
                     cmd: cliPath,
-                    args: ['--permission-mode', 'bypassPermissions', prompt]
+                    args: ["--permission-mode", "bypassPermissions", prompt],
                 };
-            case 'gemini':
+            case "gemini":
                 return {
                     cmd: cliPath,
                     args: [],
-                    stdin: prompt
+                    stdin: prompt,
                 };
-            case 'copilot':
+            case "copilot":
                 return {
                     cmd: cliPath,
-                    args: [prompt]
+                    args: [prompt],
                 };
-            case 'openai':
+            case "openai":
                 return {
                     cmd: cliPath,
-                    args: ['exec', '-'],
-                    stdin: prompt
+                    args: ["exec", "-"],
+                    stdin: prompt,
                 };
-            case 'custom':
+            case "custom":
                 if (config.customCommand) {
-                    const parts = config.customCommand.split(' ');
+                    const parts = config.customCommand.split(" ");
                     const cmd = parts[0];
-                    const args = parts.slice(1).map(arg => arg === '{{prompt}}' ? prompt : arg);
+                    const args = parts
+                        .slice(1)
+                        .map((arg) => (arg === "{{prompt}}" ? prompt : arg));
                     // If {{prompt}} isn't in args, append it
-                    if (!config.customCommand.includes('{{prompt}}')) {
+                    if (!config.customCommand.includes("{{prompt}}")) {
                         args.push(prompt);
                     }
                     return { cmd, args };
                 }
-                return { cmd: 'specify', args: [prompt] };
+                return { cmd: "specify", args: [prompt] };
             default:
                 return { cmd: cliPath, args: [prompt] };
         }
     }
     getDefaultCli(agentType) {
         const defaults = {
-            claude: 'claude',
-            gemini: 'gemini',
-            copilot: 'ghcs',
-            openai: 'codex'
+            claude: "claude",
+            gemini: "gemini",
+            copilot: "ghcs",
+            openai: "codex",
         };
-        return defaults[agentType] || 'specify';
+        return defaults[agentType] || "specify";
     }
 }
 exports.ProcessAgentRunner = ProcessAgentRunner;

package/bin/adapters/secondary/fs/FSWorkspaceRepository.js

@@ -61,7 +61,12 @@ class FSWorkspaceRepository {
         else {
             state.constitutionPhase.filePath = null;
             state.constitutionPhase.content = null;
-            state.constitutionPhase.status = 'idle';
+            // Don't clobber explicit user/runtime states when no file is on disk:
+            // 'running' (agent still generating) and 'approved' (a stored user decision,
+            // e.g. advanced via Kanban drag) must survive reconciliation.
+            if (!this.isUserState(state.constitutionPhase.status)) {
+                state.constitutionPhase.status = 'idle';
+            }
         }
         // 2. Reconcile Features in specs/
         const specsDir = path.join(workspacePath, 'specs');
@@ -100,7 +105,9 @@ class FSWorkspaceRepository {
                     else {
                         ps.filePath = null;
                         ps.content = null;
-                        ps.status = 'idle';
+                        if (!this.isUserState(ps.status)) {
+                            ps.status = 'idle';
+                        }
                     }
                 }
                 // Reconcile clarification (clarification.md or clarify.md)
@@ -118,7 +125,9 @@ class FSWorkspaceRepository {
                 else {
                     clarifyPhase.filePath = null;
                     clarifyPhase.content = null;
-                    clarifyPhase.status = 'idle';
+                    if (!this.isUserState(clarifyPhase.status)) {
+                        clarifyPhase.status = 'idle';
+                    }
                 }
                 // Implementation phase doesn't have its own file, but we can resolve its status.
                 // If specs/[feature]/tasks.md exists, and all checkboxes are checked, it could be complete.
@@ -127,6 +136,24 @@ class FSWorkspaceRepository {
                 // Make sure its filePath is null (since there is no implementation.md file)
                 implPhase.filePath = null;
                 implPhase.content = null;
+                // Reconcile review-gate personas against their report files. Statuses
+                // saved by the gate are kept; this is a safety net that also reflects a
+                // report written/edited out of band. Never downgrade a 'running' persona.
+                if (implPhase.personas) {
+                    for (const persona of implPhase.personas) {
+                        const reportFp = path.join(specsDir, feature.name, 'reviews', `${persona.id}.md`);
+                        if (fs.existsSync(reportFp)) {
+                            persona.reportPath = path.join('specs', feature.name, 'reviews', `${persona.id}.md`);
+                            if (persona.status !== 'running') {
+                                const verdict = fs.readFileSync(reportFp, 'utf-8').toUpperCase();
+                                if (/VERDICT:\s*FAIL/.test(verdict))
+                                    persona.status = 'failed';
+                                else if (/VERDICT:\s*PASS/.test(verdict))
+                                    persona.status = 'passed';
+                            }
+                        }
+                    }
+                }
             }
         }
         else {
@@ -156,7 +183,9 @@ class FSWorkspaceRepository {
                 phases: f.phases.map(p => ({
                     phase: p.phase,
                     status: p.status,
-                    stale: p.stale
+                    stale: p.stale,
+                    // Persist the implementation review-gate persona statuses.
+                    ...(p.personas ? { personas: p.personas.map(ps => ({ id: ps.id, status: ps.status })) } : {})
                 }))
             })),
             activeFeatureName: state.activeFeatureName
@@ -245,6 +274,9 @@ class FSWorkspaceRepository {
             phases: FEATURE_PHASES.map(p => this.makePhaseState(p))
         };
     }
+    isUserState(status) {
+        return status === 'running' || status === 'approved';
+    }
     loadStateFile(workspacePath) {
         const statePath = path.join(workspacePath, '.specify', '.runtime', 'workflow-state.json');
         if (!fs.existsSync(statePath)) {
@@ -267,7 +299,10 @@ class FSWorkspaceRepository {
                             status: savedPhase?.status || 'idle',
                             stale: savedPhase?.stale || false,
                             filePath: null,
-                            content: null
+                            content: null,
+                            ...(Array.isArray(savedPhase?.personas)
+                                ? { personas: savedPhase.personas.map((ps) => ({ id: ps.id, status: ps.status || 'idle' })) }
+                                : {})
                         };
                     })
                 }));

package/bin/adapters/secondary/pty/ptyLoader.js

@@ -0,0 +1,128 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPty = loadPty;
+exports._clearPtyCacheForTesting = _clearPtyCacheForTesting;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+let cached = null;
+class PureJsPtyLike {
+    child;
+    constructor(child) {
+        this.child = child;
+    }
+    write(data) {
+        this.child.stdin?.write(data);
+    }
+    resize(cols, rows) {
+        // No-op for standard child_process pipes
+    }
+    kill(signal) {
+        this.child.kill(signal);
+    }
+    onData(cb) {
+        this.child.stdout?.on("data", (chunk) => cb(chunk.toString()));
+        this.child.stderr?.on("data", (chunk) => cb(chunk.toString()));
+    }
+    onExit(cb) {
+        this.child.on("exit", (code, signal) => {
+            cb({ exitCode: code ?? 0, signal: signal ? 1 : undefined });
+        });
+    }
+}
+const pureJsPtyModule = {
+    spawn(file, args, options) {
+        const cp = (0, child_process_1.spawn)(file, args, {
+            cwd: options.cwd,
+            env: options.env,
+        });
+        return new PureJsPtyLike(cp);
+    },
+};
+/**
+ * Loads node-pty defensively.
+ *
+ * node-pty relies on a native `spawn-helper` binary (on POSIX) that must be
+ * executable. Some package managers / extraction paths drop the exec bit when
+ * unpacking the prebuilt binaries, which makes pty.spawn fail with
+ * "posix_spawnp failed". We restore the exec bit before first use so the
+ * workspace shell and interactive agent phases work regardless of how the
+ * dependency was installed.
+ */
+function loadPty() {
+    if (cached)
+        return cached;
+    if (process.env.SPECKIT_TEST_FORCE_FALLBACK === "true") {
+        cached = pureJsPtyModule;
+        return pureJsPtyModule;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pty = require("node-pty");
+        if (process.platform !== "win32") {
+            try {
+                const ptyDir = path.dirname(require.resolve("node-pty/package.json"));
+                const prebuilds = path.join(ptyDir, "prebuilds");
+                if (fs.existsSync(prebuilds)) {
+                    for (const entry of fs.readdirSync(prebuilds)) {
+                        const helper = path.join(prebuilds, entry, "spawn-helper");
+                        if (fs.existsSync(helper)) {
+                            try {
+                                fs.chmodSync(helper, 0o755);
+                            }
+                            catch {
+                                // best effort
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // best effort — if anything fails we still return the module
+            }
+        }
+        cached = pty;
+        return pty;
+    }
+    catch (err) {
+        console.warn("node-pty failed to load, falling back to pure child_process pty emulation.");
+        cached = pureJsPtyModule;
+        return pureJsPtyModule;
+    }
+}
+function _clearPtyCacheForTesting() {
+    cached = null;
+}