stack-agent 0.3.0 → 0.3.1

package/README.md

@@ -5,22 +5,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/node/v/stack-agent)](https://nodejs.org)
 
-AI-powered CLI that helps developers choose and scaffold full-stack applications through conversational interaction.
+AI-powered CLI that helps developers choose and scaffold full-stack applications through a fullscreen terminal UI.
 
-A senior software architect in your terminal — it walks you through stack decisions, explains trade-offs, and scaffolds your project using official framework tools.
+A senior software architect in your terminal — it recommends your entire stack, lets you review and refine each decision, then scaffolds the project with integration code.
 
-## How it works
-
-1. **Conversation** — The agent asks what you're building, then guides you through frontend, backend, database, auth, payments, AI/LLM, and deployment choices
-2. **Recommendations** — Each stage presents 2-3 options with a recommended pick and trade-off context
-3. **Review** — Once all decisions are made, the agent presents your full stack for approval
-4. **Scaffold** — The agent runs official tools (create-next-app, create-vite, etc.) and generates integration code grounded by current documentation
-
-## Quick start
+## Usage
 
 ```bash
 export ANTHROPIC_API_KEY=your-key-here
-npx stack-agent
+npx stack-agent            # Start or resume a session
+npx stack-agent --fresh    # Clear saved progress and start over
 ```
 
 ## Requirements
@@ -28,19 +22,13 @@ npx stack-agent
 - Node.js 20+
 - An [Anthropic API key](https://console.anthropic.com/settings/keys)
 
-## What it does
-
-- Delegates base scaffolding to official framework CLIs (create-next-app, create-vite, etc.)
-- Generates integration code (auth, database, payments) using Claude, grounded by up-to-date documentation via MCP
-- Writes `.env.example` with required environment variables
-- Installs dependencies automatically
-
 ## Development
 
 ```bash
 npm install
 npm run dev          # Run with tsx
-npm test             # Run tests
+npm run mockup       # Run interactive TUI mockup (no LLM calls)
+npm test             # Run tests (176 tests)
 npm run build        # Build with tsup
 ```
 

package/dist/index.js

@@ -262,12 +262,12 @@ function deserializeSession(json) {
 
 // src/cli/components/stage-list.tsx
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
-function StageListView({ stages, currentStageId, progress, onResult }) {
+function StageListView({ stages, currentStageId, progress, showFresh = false, onResult }) {
   const [showConfirm, setShowConfirm] = useState3(false);
   const [showWarning, setShowWarning] = useState3("");
   const [cursor, setCursor] = useState3(0);
   const canBuild = isComplete(progress);
-  const itemCount = stages.length + 1;
+  const itemCount = stages.length + 1 + (showFresh ? 1 : 0);
   useInput2((input, key) => {
     if (showConfirm) return;
     if (key.upArrow) {
@@ -281,13 +281,15 @@ function StageListView({ stages, currentStageId, progress, onResult }) {
     if (key.return) {
       if (cursor < stages.length) {
         onResult({ kind: "select", stageId: stages[cursor].id });
-      } else {
+      } else if (cursor === stages.length) {
         if (canBuild) {
           setShowConfirm(true);
         } else {
           const missing = getMissingDecisions(progress);
           setShowWarning(`Complete ${missing.join(", ")} first.`);
         }
+      } else {
+        onResult({ kind: "fresh" });
       }
     }
     if (key.escape) {
@@ -325,6 +327,10 @@ function StageListView({ stages, currentStageId, progress, onResult }) {
         requiredRemaining(progress),
         " remaining)"
       ] })
+    ] }),
+    showFresh && /* @__PURE__ */ jsxs3(Box5, { children: [
+      /* @__PURE__ */ jsx5(Text5, { children: cursor === stages.length + 1 ? "\u276F " : "  " }),
+      /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: "Start fresh" })
     ] })
   ] });
 }
@@ -471,10 +477,10 @@ function ScaffoldView({ steps }) {
 function createBridge() {
   const listeners = /* @__PURE__ */ new Map();
   let pendingResolve = null;
-  function emit(event, ...args2) {
+  function emit(event, ...args) {
     const set = listeners.get(event);
     if (set) {
-      for (const fn of set) fn(...args2);
+      for (const fn of set) fn(...args);
     }
   }
   return {
@@ -511,20 +517,48 @@ import { join as join2 } from "path";
 import Anthropic from "@anthropic-ai/sdk";
 
 // src/util/logger.ts
-import pino from "pino";
-var logger = pino({
-  level: process.env.LOG_LEVEL ?? "info",
-  transport: process.env.NODE_ENV !== "production" ? { target: "pino-pretty", options: { destination: 2 } } : void 0
-}, process.env.NODE_ENV === "production" ? pino.destination(2) : void 0);
+var LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+var currentLevel = process.env.LOG_LEVEL ?? "info";
+function log(level, component, msg, data) {
+  if (LEVELS[level] < LEVELS[currentLevel]) return;
+  const prefix = `[${level}] [${component}]`;
+  const line = data ? `${prefix} ${msg} ${JSON.stringify(data)}` : `${prefix} ${msg}`;
+  process.stderr.write(line + "\n");
+}
 function createLogger(component) {
-  return logger.child({ component });
+  return {
+    debug: (data, msg) => log("debug", component, msg, data),
+    info: (data, msg) => log("info", component, msg, data),
+    warn: (data, msg) => log("warn", component, msg, data),
+    error: (data, msg) => log("error", component, msg, data)
+  };
 }
 
 // src/llm/client.ts
-var log = createLogger("llm");
+var log2 = createLogger("llm");
 function summarizeMessages(messages) {
   return `${messages.length} messages, last: ${messages.at(-1)?.role ?? "none"}`;
 }
+function withMessageCaching(messages) {
+  if (messages.length < 2) return messages;
+  const cached = messages.map((m, i) => {
+    if (i !== messages.length - 2) return m;
+    const content = m.content;
+    if (typeof content === "string") {
+      return { ...m, content: [{ type: "text", text: content, cache_control: { type: "ephemeral" } }] };
+    }
+    if (Array.isArray(content)) {
+      const blocks = [...content];
+      const last = blocks[blocks.length - 1];
+      if (last) {
+        blocks[blocks.length - 1] = { ...last, cache_control: { type: "ephemeral" } };
+      }
+      return { ...m, content: blocks };
+    }
+    return m;
+  });
+  return cached;
+}
 function getClient() {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
@@ -543,7 +577,7 @@ function client() {
 }
 async function chat(options) {
   const { system, messages, tools, maxTokens, mcpServers } = options;
-  log.debug({ maxTokens, toolCount: tools?.length ?? 0, messages: summarizeMessages(messages) }, "chat request");
+  log2.debug({ maxTokens, toolCount: tools?.length ?? 0, messages: summarizeMessages(messages) }, "chat request");
   let response;
   if (mcpServers && Object.keys(mcpServers).length > 0) {
     const mcpServerList = Object.entries(mcpServers).map(([name, config]) => ({
@@ -573,39 +607,39 @@ async function chat(options) {
     response = await client().messages.create({
       model: "claude-sonnet-4-6",
       max_tokens: maxTokens,
-      system,
-      messages,
+      system: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }],
+      messages: withMessageCaching(messages),
       ...tools && tools.length > 0 && { tools }
     });
   }
-  log.info({
+  log2.info({
     stopReason: response.stop_reason,
     contentBlocks: response.content.length,
     usage: response.usage
   }, "chat response");
-  log.debug({ content: response.content }, "chat response content");
+  log2.debug({ content: response.content }, "chat response content");
   return response;
 }
 async function chatStream(options, callbacks) {
   const { system, messages, tools, maxTokens } = options;
-  log.debug({ maxTokens, toolCount: tools?.length ?? 0, messages: summarizeMessages(messages) }, "chatStream request");
+  log2.debug({ maxTokens, toolCount: tools?.length ?? 0, messages: summarizeMessages(messages) }, "chatStream request");
   const stream = client().messages.stream({
     model: "claude-sonnet-4-6",
     max_tokens: maxTokens,
-    system,
-    messages,
+    system: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }],
+    messages: withMessageCaching(messages),
     ...tools && tools.length > 0 && { tools }
   });
   stream.on("text", (text) => {
     callbacks.onText(text);
   });
   const finalMessage = await stream.finalMessage();
-  log.info({
+  log2.info({
     stopReason: finalMessage.stop_reason,
     contentBlocks: finalMessage.content.length,
     usage: finalMessage.usage
   }, "chatStream response");
-  log.debug({ content: finalMessage.content }, "chatStream response content");
+  log2.debug({ content: finalMessage.content }, "chatStream response content");
   for (const block of finalMessage.content) {
     if (block.type === "tool_use") {
       callbacks.onToolUse(block);
@@ -905,7 +939,7 @@ Do not ask for confirmation. Proceed through all steps automatically.`;
 import { execFileSync } from "child_process";
 import { readdirSync, existsSync } from "fs";
 import { join } from "path";
-function runScaffold(tool, args2, projectName, cwd) {
+function runScaffold(tool, args, projectName, cwd) {
   const outputDir = join(cwd, projectName);
   if (existsSync(outputDir)) {
     const entries = readdirSync(outputDir);
@@ -915,7 +949,7 @@ function runScaffold(tool, args2, projectName, cwd) {
       );
     }
   }
-  const spawnArgs = [`${tool}@latest`, projectName, ...args2];
+  const spawnArgs = [`${tool}@latest`, projectName, ...args];
   const opts = { cwd, stdio: "pipe" };
   execFileSync("npx", spawnArgs, opts);
   return outputDir;
@@ -1203,7 +1237,7 @@ async function runScaffoldLoop(progress, onProgress, mcpServers) {
 }
 
 // src/agent/recommend.ts
-var log2 = createLogger("recommend");
+var log3 = createLogger("recommend");
 var RECOMMEND_PROMPT = `You are a senior software architect. Based on the project description, recommend a complete technology stack.
 
 For each category, provide your recommendation as a JSON object. If a category is not needed for this project, set it to null.
@@ -1237,15 +1271,15 @@ Description: ${description}`
       maxTokens: 1024
     });
     const text = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
-    log2.info({ rawLength: text.length }, "received recommendation response");
-    log2.debug({ rawText: text }, "recommendation raw text");
+    log3.info({ rawLength: text.length }, "received recommendation response");
+    log3.debug({ rawText: text }, "recommendation raw text");
     const jsonStr = text.replace(/^```(?:json)?\s*\n?/m, "").replace(/\n?```\s*$/m, "").trim();
     const parsed = JSON.parse(jsonStr);
     const categories = Object.keys(parsed).filter((k) => parsed[k] !== null);
-    log2.info({ recommended: categories, skipped: Object.keys(parsed).filter((k) => parsed[k] === null) }, "parsed recommendations");
+    log3.info({ recommended: categories, skipped: Object.keys(parsed).filter((k) => parsed[k] === null) }, "parsed recommendations");
     return parsed;
   } catch (err) {
-    log2.error({ err }, "recommendation pass failed");
+    log3.error({ err }, "recommendation pass failed");
     return {};
   }
 }
@@ -1290,7 +1324,7 @@ function applyRecommendations(progress, stages, recommendations) {
 
 // src/cli/app.tsx
 import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
-function App({ manager, onBuild, onExit }) {
+function App({ manager, isResumed, onBuild, onFresh, onExit }) {
   const app = useApp();
   const { width, height } = useScreenSize();
   const [view, setView] = useState5(
@@ -1372,6 +1406,9 @@ function App({ manager, onBuild, onExit }) {
         syncState();
       }
       runStage(result.stageId);
+    } else if (result.kind === "fresh") {
+      onFresh();
+      app.exit();
     } else if (result.kind === "build") {
       setView("scaffold");
       setScaffoldSteps([]);
@@ -1458,6 +1495,7 @@ function App({ manager, onBuild, onExit }) {
           stages,
           currentStageId: currentStage?.id ?? null,
           progress,
+          showFresh: isResumed,
           onResult: handleStageResult
         }
       ),
@@ -1992,63 +2030,60 @@ What needs to change?`;
     }
   };
 }
-async function main(fresh = false) {
+async function main(startFresh = false) {
   const cwd = process.cwd();
   const invalidationFn = createInvalidationFn();
   process.on("SIGINT", () => {
     process.exit(0);
   });
-  if (fresh) {
+  if (startFresh) {
     const tempManager = StageManager.resume(cwd);
     tempManager?.cleanup();
-    console.log("Session cleared. Starting fresh.\n");
   }
   let manager;
-  const existingSession = fresh ? null : StageManager.detect(cwd);
-  if (existingSession) {
-    console.log(`
-Found saved progress for "${existingSession.progress.projectName ?? "unnamed"}"`);
-    console.log("Run with --fresh to start over.\n");
+  const isResumed = !startFresh && StageManager.detect(cwd) !== null;
+  if (isResumed) {
     const resumed = StageManager.resume(cwd, invalidationFn);
-    if (!resumed) {
-      console.log("Could not restore session. Starting fresh.");
-      manager = StageManager.start(cwd, invalidationFn);
-    } else {
-      manager = resumed;
-    }
+    manager = resumed ?? StageManager.start(cwd, invalidationFn);
   } else {
     manager = StageManager.start(cwd, invalidationFn);
   }
   let shouldBuild = false;
+  let shouldStartFresh = false;
   const ink = withFullScreen(
     React6.createElement(App, {
       manager,
+      isResumed,
       onBuild: () => {
         shouldBuild = true;
       },
+      onFresh: () => {
+        shouldStartFresh = true;
+      },
       onExit: () => {
-        shouldBuild = false;
       }
     })
   );
   await ink.start();
   await ink.waitUntilExit();
+  if (shouldStartFresh) {
+    manager.cleanup();
+    return main(true);
+  }
   if (shouldBuild) {
     const readiness = manager.progress.deployment ? checkDeployReadiness(manager.progress.deployment.component) : null;
     renderPostScaffold(manager.progress.projectName, readiness);
     console.log("\nHappy building!\n");
   }
 }
-var args = process.argv.slice(2);
-var command = args[0];
-var isFresh = args.includes("--fresh");
-if (!command || command === "init" || command === "--fresh") {
-  main(isFresh).catch((err) => {
+var command = process.argv[2];
+if (!command || command === "init") {
+  main().catch((err) => {
     console.error(err);
     process.exit(1);
   });
 } else {
   console.error(`Unknown command: ${command}`);
-  console.error("Usage: stack-agent [init] [--fresh]");
+  console.error("Usage: stack-agent [init]");
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stack-agent",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "AI-powered CLI that helps developers choose and scaffold full-stack applications through conversational interaction",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,6 @@
     "ink": "^6.8.0",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
-    "pino": "^10.3.1",
     "react": "^19.2.4",
     "zod": "^4.3.6"
   },
@@ -55,7 +54,6 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "ink-testing-library": "^4.0.0",
-    "pino-pretty": "^13.1.3",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",