basis-design 0.1.0 → 0.1.1

package/README.md

@@ -18,12 +18,12 @@ npx basis-design
 
 Or install it once with `npm install -g basis-design` and start it with `basis`. Open http://localhost:5320. Basis starts Claude Code by default (shown as Claude in the picker above the chat); switch to Codex there. Basis needs Node.js 22.12 or later and `git` on the PATH.
 
-- **Claude Code:** log in once with `claude` in a terminal. Basis starts it through `@agentclientprotocol/claude-agent-acp`.
+- **Claude Code:** install it and log in once with `claude` in a terminal. Basis runs your own Claude Code through `@agentclientprotocol/claude-agent-acp`, which npx fetches on first use without a copy of Claude Code of its own. If Basis does not find it, set `CLAUDE_CODE_EXECUTABLE` to its path.
 - **Codex:** log in once with `codex login`. Basis starts it through `npx @agentclientprotocol/codex-acp`, at a fixed version that npx fetches on first use.
 
 Usage counts against your own plan. A turn can take up to three agent runs (the turn and up to two fix-ups), and ×2 or ×3 alternatives multiply that.
 
-The first install is large, about 300 MB, because the Claude adapter brings its own copy of Claude Code. To work on Basis itself, clone the repository and run `npm install` and `npm run dev`.
+To work on Basis itself, clone the repository and run `npm install` and `npm run dev`.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
@@ -42,6 +42,7 @@ A project can link the **product repo** it designs for (project menu, **Link pro
 - **New project** starts from Basis' defaults, or as a copy of the open project's tokens and components (not its history). It lives in `~/.basis/workspaces/`.
 - **Open folder** adds a workspace from anywhere, or an empty or new folder for Basis to set up, inside a product repo for instance. Basis refuses a folder that already has other files, so it never starts a history in someone's project.
 - Switching waits while the agent works. The agent of the project you leave stops, and coming back resumes its conversation, so it remembers where you were. The export remembers its target folder per project.
+- When Basis' starter components improve, the files a project never changed update by themselves. For the ones the agent changed, the project menu offers a guided turn that brings the improvements in, as a review, keeping the project's own look.
 - Removing a project from the list never deletes its folder. Earlier versions kept the project list in the Basis folder; it moves to `~/.basis` on first start, and its projects stay where they are. The `./workspace` of versions before projects becomes the first project.
 
 ## The workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basis-design",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Prompt a complete design system into existence with your own coding agent over ACP.",
   "keywords": [
     "design-system",
@@ -39,12 +39,13 @@
     "start": "tsx server/index.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test \"test/*.test.ts\"",
+    "test:e2e": "playwright test",
+    "template:history": "tsx scripts/template-history.ts",
     "lint": "oxlint",
     "format": "prettier --write .",
     "check": "tsc --noEmit && oxlint && prettier --check . && npm test"
   },
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "0.92.0",
     "@agentclientprotocol/sdk": "^1.9.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
@@ -60,6 +61,7 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
     "@types/node": "^26.6.5",
     "@types/ws": "^8.18.2",
     "oxlint": "1.88.0",

package/server/agent.ts

@@ -2,7 +2,6 @@ import { spawn, spawnSync, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
 import { EventEmitter } from "node:events";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import path from "node:path";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
@@ -22,35 +21,52 @@ import { ALTERNATIVE_LABELS, describeTarget, MAX_ALTERNATIVES } from "../shared/
 import { loadChat, saveChat } from "./chatlog.ts";
 import { PRODUCT_FILE, relativeInside } from "./paths.ts";
 import { AGENT_BRIEF, FIRST_PROMPT_PREAMBLE } from "./brief.ts";
+import { CLAUDE_MISSING, findClaude } from "./claude.ts";
 import type { Workspace } from "./workspace.ts";
 
-const require = createRequire(import.meta.url);
-
 interface LaunchSpec {
   command: string;
   args: string[];
   shell: boolean;
   loginHint: string;
+  /** Variables the agent needs on top of Basis' own environment. */
+  env?: Record<string, string>;
+  /** Why the agent cannot start, shown instead of starting it. */
+  missing?: string;
+  /** Added when the agent exits on its own, for the failures an update fixes. */
+  exitHint?: string;
 }
 
-/** The Codex adapter Basis was tested with; npx fetches it on first use. */
+/**
+ * The adapters Basis was tested with, at fixed versions: an unpinned one would fetch whatever was published last.
+ * npx fetches each on first use and reuses it after (--prefer-offline, so Basis also starts offline).
+ */
+const CLAUDE_ACP = "@agentclientprotocol/claude-agent-acp@0.92.0";
 const CODEX_ACP = "@agentclientprotocol/codex-acp@2.2.2";
 
 /** How each supported agent is started. Both reuse the user's own CLI login, so no API keys are needed. */
 function launchSpec(id: AgentId): LaunchSpec {
+  // The end-to-end tests run a stand-in agent (test/e2e/fake-agent.mjs), since no CLI is logged in on CI.
+  if (process.env.BASIS_AGENT_SCRIPT) {
+    const script = path.resolve(process.env.BASIS_AGENT_SCRIPT);
+    return { command: process.execPath, args: [script], shell: false, loginHint: "" };
+  }
   if (id === "claude") {
-    const pkg = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+    // Without --omit=optional the adapter's SDK brings its own copy of Claude Code; Basis runs the user's instead.
+    const claude = findClaude();
     return {
-      command: process.execPath,
-      args: [path.join(path.dirname(pkg), "dist", "index.js")],
-      shell: false,
+      command: "npx",
+      args: ["-y", "--prefer-offline", "--omit=optional", CLAUDE_ACP],
+      shell: true,
+      env: claude ? { CLAUDE_CODE_EXECUTABLE: claude } : undefined,
+      missing: claude ? undefined : CLAUDE_MISSING,
       loginHint: "Run `claude` in a terminal and log in, then restart the agent.",
+      exitHint: "If it keeps happening, update Claude Code with `claude update`.",
     };
   }
   return {
     command: "npx",
-    // A fixed version: an unpinned one would fetch whatever was published last on every start.
-    args: ["-y", CODEX_ACP],
+    args: ["-y", "--prefer-offline", CODEX_ACP],
     shell: true,
     loginHint: "Run `codex login` in a terminal, then restart the agent.",
   };
@@ -180,13 +196,17 @@ export class AgentHost extends EventEmitter<Events> {
     await this.stop();
     this.setState({ id: agentId, status: "starting", detail: "Starting agent…" });
     const spec = launchSpec(agentId);
+    if (spec.missing) {
+      this.fail(spec.missing);
+      return;
+    }
     // Through a shell, the command goes as one line: Node no longer accepts separate arguments there.
     const [command, args] = spec.shell ? [[spec.command, ...spec.args].join(" "), []] : [spec.command, spec.args];
     const proc = spawn(command, args, {
       cwd: this.workspace.dir,
       shell: spec.shell,
       stdio: ["pipe", "pipe", "pipe"],
-      env: agentEnv(),
+      env: { ...agentEnv(), ...spec.env },
       windowsHide: true,
     });
     this.proc = proc;
@@ -204,7 +224,8 @@ export class AgentHost extends EventEmitter<Events> {
       this.connection = undefined;
       this.sessionId = undefined;
       const tail = this.stderrTail.slice(-3).join(" ");
-      this.fail(`The agent exited (code ${code ?? "?"}).${tail ? ` ${tail}` : ""}`);
+      const hint = spec.exitHint ? ` ${spec.exitHint}` : "";
+      this.fail(`The agent exited (code ${code ?? "?"}).${tail ? ` ${tail}` : ""}${hint}`);
     });
 
     const stream = acp.ndJsonStream(

package/server/brief.ts

@@ -350,6 +350,24 @@ export function importInstruction(repo: string): string {
   ].join("\n");
 }
 
+/**
+ * The guided turn that brings a newer starter template into a workspace whose agent changed the starter files.
+ * `changes` is the part of template/CHANGES.md the workspace has not caught up with.
+ */
+export function templateInstruction(changes: string, files: string[]): string {
+  return [
+    "Basis has improved its starter template since this design system started from it. Bring the improvements below into this workspace's own components, patterns and views, in this turn.",
+    "",
+    changes,
+    "",
+    `1. The current template is in .basis/template/ (components/, patterns/, views/). These files here differ from it because they were changed: ${files.join(", ")}. Read each and its template version with your read tool; the list above says what changed, so you need no shell commands or diffs.`,
+    "2. Bring in each improvement where the workspace's file still has the part it concerns. Keep this design system's own look, tokens, variants and additions, and every contract. If the workspace already solves it another way, leave it.",
+    "3. Edit the files with your tools; never copy a template file over the workspace's own.",
+    "4. Write review.json showing the specimens that changed most (up to four), so the user compares before and after.",
+    "Finish with a short summary: which improvements you brought in and where, and what you left out and why.",
+  ].join("\n");
+}
+
 /** Prepended to the first prompt when the agent cannot take an appended system prompt. */
 export const FIRST_PROMPT_PREAMBLE =
   "You are working inside Basis. Read AGENTS.md in the current folder first and follow it: you edit only design-system.json, review.json, product.md and files under components/, patterns/ and views/.";

package/server/claude.ts

@@ -0,0 +1,72 @@
+import { realpathSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/*
+ * Basis runs the user's own Claude Code rather than a copy of its own: the Claude adapter is fetched without the
+ * native binary its SDK would otherwise bring (about 260 MB), and is pointed at the user's executable through
+ * CLAUDE_CODE_EXECUTABLE. The user already has it, logged in, since that is how they sign in to Claude.
+ */
+
+interface Where {
+  env: NodeJS.ProcessEnv;
+  platform: NodeJS.Platform;
+  home: string;
+}
+
+const isFile = (file: string) => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The user's Claude Code executable, or null when it is not installed. In order: CLAUDE_CODE_EXECUTABLE when it
+ * names a file, `claude` on the PATH, then the native installer's folders. On Windows the npm install puts a
+ * `claude.cmd` shim on the PATH, which cannot be started without a shell, so the executable behind it is used.
+ */
+export function findClaude(
+  { env, platform, home }: Where = { env: process.env, platform: process.platform, home: os.homedir() },
+): string | null {
+  const explicit = env.CLAUDE_CODE_EXECUTABLE;
+  if (explicit && isFile(explicit)) return explicit;
+
+  const windows = platform === "win32";
+  // Paths are on this machine's file system; `platform` only decides the names and the PATH separator.
+  const join = path.join;
+  const pathVar = env.PATH ?? env.Path ?? "";
+  const dirs = pathVar.split(windows ? ";" : ":").filter(Boolean);
+  for (const dir of dirs) {
+    if (windows) {
+      const exe = join(dir, "claude.exe");
+      if (isFile(exe)) return exe;
+      // The npm shims (claude, claude.cmd) start this executable.
+      const npm = join(dir, "node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe");
+      if ((isFile(join(dir, "claude.cmd")) || isFile(join(dir, "claude"))) && isFile(npm)) return npm;
+    } else {
+      const bin = join(dir, "claude");
+      if (isFile(bin)) return realpath(bin);
+    }
+  }
+
+  const installed = windows
+    ? [join(home, ".local", "bin", "claude.exe")]
+    : [join(home, ".local", "bin", "claude"), join(home, ".claude", "local", "claude")];
+  for (const file of installed) if (isFile(file)) return windows ? file : realpath(file);
+  return null;
+}
+
+/** Symlinks (the native installer links to a versioned binary) resolved, so the agent starts the binary itself. */
+function realpath(file: string): string {
+  try {
+    return realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+/** What the user is told when Basis cannot find Claude Code. */
+export const CLAUDE_MISSING =
+  "Basis runs your own Claude Code, and it is not installed. Install it (https://claude.com/claude-code), log in once with `claude` in a terminal, then pick Claude again. If it is installed, set CLAUDE_CODE_EXECUTABLE to its path.";

package/server/index.ts

@@ -13,11 +13,12 @@ import {
   type ProjectEntry,
   type ServerMessage,
 } from "../shared/protocol.ts";
-import { createInstruction, importInstruction, viewInstruction } from "./brief.ts";
+import { createInstruction, importInstruction, templateInstruction, viewInstruction } from "./brief.ts";
 import { buildStarterKit, slug, writeStarterKit, zipStarterKit } from "./export.ts";
 import { PreviewReports } from "./previews.ts";
 import { guard, isLocalHost, OpenProject, refuseHost, type ProjectOptions } from "./project.ts";
 import { checkRepo, Projects } from "./projects.ts";
+import { templateChanges } from "./template.ts";
 
 // History, reviews and restores all run on git; without it nothing below works, and the error would not say why.
 if (spawnSync("git", ["--version"], { windowsHide: true }).error) {
@@ -94,7 +95,8 @@ const chromeVite = await createVite({
   appType: "spa",
   cacheDir: "node_modules/.vite/chrome",
   optimizeDeps: { entries: ["index.html"] },
-  server: { middlewareMode: true, hmr: { server: chromeServer } },
+  // Vite forwards browser console errors to the terminal when it thinks an agent runs it; for Basis that is noise.
+  server: { middlewareMode: true, hmr: { server: chromeServer }, forwardConsole: false },
 });
 const chromeGuard = guard((url) => url === "/preview.html");
 chromeServer.on("request", (req, res) => {
@@ -381,9 +383,27 @@ async function handle(message: ClientMessage, socket: WebSocket): Promise<void>
     }
     case "import-design":
       return bringInDesign(socket);
+    case "template-update":
+      return bringInTemplate();
+    case "template-skip":
+      return current.workspace.settleTemplateUpdate();
   }
 }
 
+/**
+ * Starts (or queues) the guided turn that brings a newer starter template's changes into the workspace's changed
+ * starter files. The workspace counts as caught up once the turn has run (or is queued); its review shows what came
+ * in.
+ */
+async function bringInTemplate(): Promise<void> {
+  const update = current.workspace.templateUpdate;
+  if (!update) return;
+  const workspace = current.workspace;
+  const instruction = templateInstruction(await templateChanges(update.from), update.files);
+  await current.agent.prompt("Bring in the improvements to Basis' starter template", { instruction });
+  await workspace.settleTemplateUpdate();
+}
+
 /** Starts (or queues, while the agent works) the guided turn that brings in the linked repo's design system. */
 async function bringInDesign(socket: WebSocket): Promise<void> {
   const repo = current.entry.repo;

package/server/project.ts

@@ -99,6 +99,8 @@ export class OpenProject {
       },
       server: {
         middlewareMode: true,
+        // Agent-written code logs in the preview; its console belongs in the browser, not in the terminal.
+        forwardConsole: false,
         hmr: { server: previewServer },
         fs: { allow: [root, entry.dir] },
         // 'self': the preview embeds a copy of itself for the accessibility check in the other theme.