basis-design 0.1.0 → 0.2.0

package/server/folders.ts

@@ -0,0 +1,125 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/*
+ * Choosing folders without typing their path: the operating system's own folder dialog (Basis runs on the same
+ * computer as the browser), and the git repos found in the usual places for code.
+ */
+
+/** The folder the user chose, or null when they cancelled. Throws when this system has no folder dialog. */
+export async function pickFolder(title: string, start?: string): Promise<string | null> {
+  const from = start && existsSync(start) ? start : os.homedir();
+  // Title and start folder travel as variables, so no quoting can break the scripts.
+  const env = { ...process.env, BASIS_TITLE: title, BASIS_START: from };
+  if (process.platform === "win32") {
+    const shell = (await has("pwsh")) ? "pwsh" : "powershell";
+    return run(shell, ["-NoProfile", "-NonInteractive", "-STA", "-Command", WINDOWS_DIALOG], env);
+  }
+  if (process.platform === "darwin") {
+    const chosen = await run("osascript", ["-e", MAC_DIALOG], env);
+    return chosen && chosen.length > 1 ? chosen.replace(/\/$/, "") : chosen;
+  }
+  if (await has("zenity")) {
+    return run("zenity", ["--file-selection", "--directory", `--title=${title}`, `--filename=${from}/`], env);
+  }
+  if (await has("kdialog")) return run("kdialog", ["--getexistingdirectory", from, "--title", title], env);
+  throw new Error("This system has no folder dialog Basis can open (install zenity or kdialog), so type the path.");
+}
+
+// A hidden, topmost owner window keeps the dialog in front of the browser.
+const WINDOWS_DIALOG = `
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+Add-Type -AssemblyName System.Windows.Forms
+$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false; Opacity = 0 }
+$owner.Show()
+$dialog = New-Object System.Windows.Forms.FolderBrowserDialog
+$dialog.Description = $env:BASIS_TITLE
+$dialog.SelectedPath = $env:BASIS_START
+try { $dialog.UseDescriptionForTitle = $true } catch {}
+if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write($dialog.SelectedPath) }
+$owner.Close()
+`;
+
+const MAC_DIALOG = `POSIX path of (choose folder with prompt (system attribute "BASIS_TITLE") default location (POSIX file (system attribute "BASIS_START")))`;
+
+/** Runs a dialog: its output is the chosen path; cancelling exits non-zero with nothing printed. */
+function run(command: string, args: string[], env: NodeJS.ProcessEnv): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { env, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
+      const chosen = stdout.trim();
+      if (chosen) return resolve(chosen);
+      if (error && "code" in error && typeof error.code === "string") return reject(error); // Not found, not run.
+      resolve(null);
+    });
+  });
+}
+
+function has(command: string): Promise<boolean> {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => execFile(probe, [command], { windowsHide: true }, (error) => resolve(!error)));
+}
+
+export interface RepoSuggestion {
+  name: string;
+  dir: string;
+}
+
+/** Folders under the home folder where people usually keep their code. */
+const CODE_FOLDERS = [
+  "Code",
+  "code",
+  "Projects",
+  "projects",
+  "dev",
+  "Dev",
+  "Developer",
+  "src",
+  "repos",
+  "Repos",
+  "git",
+  "GitHub",
+  "workspace",
+  path.join("Documents", "GitHub"),
+  path.join("source", "repos"),
+];
+
+/**
+ * Git repos in the usual places for code, up to two levels down, the most recently used first (by the git index,
+ * which changes with every checkout and commit). `skip` leaves out folders such as Basis' own.
+ */
+export async function suggestRepos(home = os.homedir(), skip: string[] = [], limit = 12): Promise<RepoSuggestion[]> {
+  const found = new Map<string, number>();
+  const visit = async (dir: string, depth: number) => {
+    if (found.size >= 200) return;
+    const git = path.join(dir, ".git");
+    // The code folder itself is never the suggestion, even when someone made it a repo.
+    if (depth < 2 && existsSync(git)) {
+      const index = await stat(path.join(git, "index")).catch(() => stat(git));
+      found.set(dir, index.mtimeMs);
+      return;
+    }
+    if (depth === 0) return;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      await visit(path.join(dir, entry.name), depth - 1);
+    }
+  };
+  // One folder once, also when a case-insensitive disk finds it as both "Code" and "code".
+  const roots = new Map<string, string>();
+  for (const folder of CODE_FOLDERS) {
+    const dir = path.join(home, folder);
+    const info = await stat(dir).catch(() => null);
+    if (info?.isDirectory() && !roots.has(`${info.dev}:${info.ino}`)) roots.set(`${info.dev}:${info.ino}`, dir);
+  }
+  for (const root of roots.values()) await visit(root, 2);
+  const skipped = skip.map((dir) => path.resolve(dir).toLowerCase());
+  return [...found]
+    .filter(([dir]) => !skipped.some((other) => path.resolve(dir).toLowerCase() === other))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([dir]) => ({ name: path.basename(dir), dir }));
+}

package/server/index.ts

@@ -13,11 +13,14 @@ 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 { buildVerificationKit, writeVerificationKit, zipVerificationKit } from "./verify.ts";
 import { PreviewReports } from "./previews.ts";
 import { guard, isLocalHost, OpenProject, refuseHost, type ProjectOptions } from "./project.ts";
+import { pickFolder, suggestRepos } from "./folders.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,18 +97,65 @@ 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");
+const chromeGuard = guard((url) => url === "/preview.html" || url === "/capture.html");
 chromeServer.on("request", (req, res) => {
   if (!isLocalHost(req, port)) return refuseHost(res);
   if (req.method === "GET" && req.url === "/export/starter-kit.zip") {
     void sendStarterKitZip(res);
     return;
   }
+  if (req.method === "GET" && req.url === "/export/verification-kit.zip") {
+    sendVerificationZip(res);
+    return;
+  }
+  if (req.url?.startsWith("/api/")) {
+    void handleApi(req, res);
+    return;
+  }
   chromeGuard(req, res, () => chromeVite.middlewares(req, res));
 });
 
+/** True while a folder dialog is open: one at a time. */
+let picking = false;
+
+/**
+ * Small requests the chrome makes and waits for: a folder from the system's dialog, repos to suggest. Only POSTs
+ * from the chrome's own origin, so another web page can neither open dialogs on this computer nor read the answer.
+ */
+async function handleApi(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+  const reply = (status: number, body: unknown) => {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(body));
+  };
+  if (req.method !== "POST" || !chromeOrigins.includes(req.headers.origin ?? "")) return reply(403, {});
+  let body: { title?: string; start?: string };
+  try {
+    let raw = "";
+    for await (const chunk of req) raw += chunk;
+    body = raw ? JSON.parse(raw) : {};
+  } catch {
+    return reply(400, {});
+  }
+  if (req.url === "/api/pick-folder") {
+    if (picking) return reply(409, { error: "A folder dialog is already open." });
+    picking = true;
+    try {
+      return reply(200, { path: await pickFolder(body.title ?? "Choose a folder", body.start) });
+    } catch (error) {
+      return reply(200, { path: null, error: (error as Error).message });
+    } finally {
+      picking = false;
+    }
+  }
+  if (req.url === "/api/repos") {
+    return reply(200, { repos: await suggestRepos(undefined, [root, current.entry.dir]) });
+  }
+  reply(404, {});
+}
+
 async function starterKit() {
   return buildStarterKit(current.workspace.state.design, current.workspace.dir);
 }
@@ -127,6 +177,59 @@ async function sendStarterKitZip(res: http.ServerResponse): Promise<void> {
   }
 }
 
+/** The last verification kit built as a zip, until it is downloaded or another is built. */
+let verificationZip: { name: string; data: Uint8Array } | null = null;
+/** True while a verification kit is being built: one at a time, and no project switch meanwhile. */
+let verifying = false;
+
+function sendVerificationZip(res: http.ServerResponse): void {
+  if (!verificationZip) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("No verification kit has been built. Build one from the Export dialog.");
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "application/zip",
+    "Content-Disposition": `attachment; filename="${verificationZip.name}"`,
+    "Content-Length": verificationZip.data.byteLength,
+    "Cache-Control": "no-store",
+  });
+  res.end(verificationZip.data);
+}
+
+/** Builds the verification kit for the open project, reporting progress to every tab. */
+async function verificationKit(project: string | undefined, socket: WebSocket): Promise<void> {
+  if (verifying) {
+    send(socket, { type: "verify-result", result: { ok: false, error: "A verification kit is already being built." } });
+    return;
+  }
+  verifying = true;
+  try {
+    const { files, summary } = await buildVerificationKit({
+      design: current.workspace.state.design,
+      workspaceDir: current.workspace.dir,
+      onProgress: (step, done, total) => broadcast({ type: "verify-progress", step, done, total }),
+    });
+    if (project === undefined) {
+      verificationZip = {
+        name: `${slug(current.workspace.state.design.name)}-verification-kit.zip`,
+        data: zipVerificationKit(files),
+      };
+      broadcast({ type: "verify-result", result: { ok: true, summary } });
+      return;
+    }
+    const written = await writeVerificationKit(files, project);
+    broadcast({
+      type: "verify-result",
+      result: written.ok ? { ok: true, summary, dir: written.dir } : { ok: false, error: written.error },
+    });
+  } catch (error) {
+    broadcast({ type: "verify-result", result: { ok: false, error: (error as Error).message } });
+  } finally {
+    verifying = false;
+  }
+}
+
 chromeServer.on("upgrade", (req, socket, head) => {
   if (req.url !== "/bridge") return; // Vite's HMR socket handles its own upgrades.
   if (!chromeOrigins.includes(req.headers.origin ?? "")) {
@@ -169,6 +272,13 @@ async function switchTo(entry: ProjectEntry, socket: WebSocket): Promise<void> {
     send(socket, { type: "project-error", message: "The agent is working. Switch projects when it is done." });
     return;
   }
+  if (verifying) {
+    send(socket, {
+      type: "project-error",
+      message: "A verification kit is being built. Switch projects when it is done.",
+    });
+    return;
+  }
   switching = true;
   const previous = current.entry;
   broadcast({ type: "project-switching", project: entry });
@@ -312,6 +422,9 @@ async function handle(message: ClientMessage, socket: WebSocket): Promise<void>
       send(socket, { type: "export-result", result });
       return;
     }
+    case "verify-kit":
+      await verificationKit(typeof message.project === "string" ? message.project : undefined, socket);
+      return;
     case "project-switch": {
       const entry = projects.find(String(message.id ?? ""));
       if (entry) await switchTo(entry, socket);
@@ -381,9 +494,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

@@ -86,7 +86,7 @@ export class OpenProject {
       root,
       appType: "mpa",
       cacheDir: "node_modules/.vite/preview",
-      optimizeDeps: { entries: ["preview.html"] },
+      optimizeDeps: { entries: ["preview.html", "capture.html"] },
       plugins: [rebasePlugin(root, entry.dir)],
       resolve: {
         alias: {
@@ -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.
@@ -110,6 +112,12 @@ export class OpenProject {
     const previewGuard = guard((url) => url === "/" || url === "/index.html");
     previewServer.on("request", (req, res) => {
       if (!isLocalHost(req, options.previewPort)) return refuseHost(res);
+      // The capture page (capture.html) reads the current tokens from here, as the kit's copy reads its own file.
+      if (req.method === "GET" && req.url?.split("?")[0] === "/design.json") {
+        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end(JSON.stringify(workspace.state.design));
+        return;
+      }
       previewGuard(req, res, () => previewVite.middlewares(req, res));
     });
     await new Promise<void>((resolve, reject) => {