@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/spinner.ts

@@ -2,23 +2,11 @@ import ora, { type Ora } from "ora";
 
 export class Spinner {
   static padding = 12;
-  /**
-   * XXX: `discardStdin` must stay off. It makes ora put the terminal into raw mode for as long as the
-   * spinner runs, and a Bun child spawned in that window snapshots the raw termios and writes it back
-   * when it exits — long after the spinner restored the terminal. `akan start` spawns the builder and
-   * the backend under the "Preparing backend..." spinner, so the first builder recycle (a config or
-   * runtime-metadata change) SIGTERMs that child and silently turns the developer's terminal raw:
-   * `isig` goes off, Ctrl+C stops producing SIGINT at all, and the dev server looks unkillable.
-   */
+  // XXX: `discardStdin` must stay off: ora raw-modes the terminal while spinning, a Bun child spawned then writes that
+  // raw termios back when it exits, and Ctrl+C stops producing SIGINT.
   static oraOptions = { discardStdin: false } as const;
-  /**
-   * ora sizes its clear loop as `ceil(lineWidth / stream.columns)`, so a tty that reports **0** columns
-   * makes it `Infinity` and `clear()` never returns. An unsized pty does exactly that (`isTTY: true`,
-   * `columns: 0`) — CI runners, `expect`/`script` harnesses, some detached panes. Measured: 750MB of
-   * cursor moves and 8.7GB RSS inside a minute, in a loop that no longer reaches the point where SIGINT
-   * or SIGTERM could be handled, so only SIGKILL ends it. A terminal with no width has nothing to
-   * animate anyway; fall back to plain lines.
-   */
+  // ora's clear loop is `ceil(lineWidth / columns)`, so an unsized pty (`isTTY` with 0 columns: CI, `script`) never
+  // returns from `clear()`; such a terminal gets plain lines.
   static canAnimate(stream: NodeJS.WriteStream = process.stderr): boolean {
     return !stream.isTTY || stream.columns > 0;
   }

package/sshTunnel.ts

@@ -20,7 +20,6 @@ interface TunnelSocketData {
   closed: boolean;
 }
 
-type BunServer = { stop(): void };
 type BunSocket = Bun.Socket<TunnelSocketData>;
 
 const closeQuietly = (close: () => void) => {
@@ -126,7 +125,7 @@ export const createSshTunnel = async (options: SshTunnelOptions): Promise<SshTun
       closing = true;
       for (const socket of sockets) closeSocket(socket, error);
       closeQuietly(() => client.end());
-      closeBunServer(server);
+      server.stop();
     };
 
     client.once("error", (error) => closeTunnel(error));
@@ -146,7 +145,3 @@ const closeBunSocket = (socket: BunSocket, error?: Error) => {
   else socket.data.stream?.end();
   closeQuietly(() => socket.end());
 };
-
-const closeBunServer = (server: BunServer) => {
-  server.stop();
-};

package/ssrScanner.test.ts

@@ -3,12 +3,7 @@ import ts from "typescript";
 import type { SourceFileInfo } from "./qualityScanner";
 import { formatSsrBalance, SSR_SERVER_SHARE_TARGET, SsrScanner } from "./ssrScanner";
 
-/**
- * `SsrScanner` is a documented gate — `akan quality ssr` prints the server share and AGENTS.md names 50% as
- * the floor — so both halves matter: a rule that stops firing lets the share rot, and a rule that
- * over-reports is what makes developers stop reading the output. Every rule here gets a positive and the
- * negative that must stay quiet.
- */
+//? Each rule gets a positive and a negative: one that stops firing lets the share rot, one that over-reports is ignored
 const fileOf = (file: string, content: string): SourceFileInfo => ({
   file,
   absolutePath: `/repo/${file}`,

package/ssrScanner.ts

@@ -22,34 +22,32 @@ interface ComponentInfo {
   vendorTags: boolean;
 }
 
-// A component with no client-only touch at all never needed the client bundle, so even a small subtree is
-// worth moving. A mostly-static component keeps its interaction and hands the static part to the server, so
-// it only pays off once the static subtree is large enough to matter.
+// A component with no client-only touch is worth moving even when small; a mostly-static one only once its static
+// subtree is large enough to matter.
 const STATIC_COMPONENT_MIN_MASS = 4;
 const MIXED_COMPONENT_MIN_MASS = 10;
 const MIXED_COMPONENT_MAX_TOUCHES = 2;
 const MODULE_SERVER_VIEW_MIN_CLIENT_MASS = 12;
 
+export const fileWarning = (
+  rule: string,
+  scope: QualityWarning["scope"],
+  file: string,
+  message: string,
+  line?: number,
+): QualityWarning =>
+  line === undefined
+    ? { rule, scope, severity: "warning", file, message }
+    : { rule, scope, severity: "warning", file, line, message };
+
 export class SsrScanner {
-  // `usePage` and `getSelf` read request-scoped server context and are legal in server components, so they
-  // must not count as evidence that a file needs "use client".
+  // `usePage` and `getSelf` read request-scoped server context, which server components may do.
   static #serverSafeCalls = new Set(["usePage", "getSelf", "useServer"]);
-  static #clientGlobals = new Set([
-    "window",
-    "document",
-    "navigator",
-    "localStorage",
-    "sessionStorage",
-    "location",
-    "history",
-    "screen",
-    "matchMedia",
-    "IntersectionObserver",
-    "ResizeObserver",
-    "MutationObserver",
-    "requestAnimationFrame",
-    "WebSocket",
-  ]);
+  static #clientGlobals = new Set(
+    "window document navigator localStorage sessionStorage location history screen matchMedia IntersectionObserver"
+      .split(" ")
+      .concat("ResizeObserver MutationObserver requestAnimationFrame WebSocket".split(" ")),
+  );
   // Runtime singletons that only exist in the client bundle; importing either is what forces the directive.
   static #clientRuntimeImports = new Set(["st", "fetch"]);
 
@@ -78,27 +76,29 @@ export class SsrScanner {
       this.#getTouches(sourceFile.sourceFile, sourceFile.sourceFile).length === 0 &&
       !this.#isConventionClientFile(sourceFile.file)
     ) {
-      warnings.push({
-        rule: "akan.ssr.unnecessary-use-client",
-        scope: "ssr",
-        severity: "warning",
-        file: sourceFile.file,
-        line: 1,
-        message: `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`,
-      });
+      warnings.push(
+        fileWarning(
+          "akan.ssr.unnecessary-use-client",
+          "ssr",
+          sourceFile.file,
+          `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`,
+          1,
+        ),
+      );
     }
 
     for (const component of components) {
       if (component.vendorTags) continue;
       if (component.touches.length === 0 && component.mass >= STATIC_COMPONENT_MIN_MASS) {
-        warnings.push({
-          rule: "akan.ssr.client-static-component",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`,
-        });
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-static-component",
+            "ssr",
+            sourceFile.file,
+            `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`,
+            component.line,
+          ),
+        );
         continue;
       }
       if (
@@ -106,14 +106,15 @@ export class SsrScanner {
         component.touches.length <= MIXED_COMPONENT_MAX_TOUCHES &&
         component.mass >= MIXED_COMPONENT_MIN_MASS
       ) {
-        warnings.push({
-          rule: "akan.ssr.client-static-markup",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`,
-        });
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-static-markup",
+            "ssr",
+            sourceFile.file,
+            `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`,
+            component.line,
+          ),
+        );
       }
     }
 
@@ -122,8 +123,7 @@ export class SsrScanner {
     return warnings;
   }
 
-  // A database module whose rendering happens entirely in Template/Zone/Util has no server-rendered surface at
-  // all, so every consumer pays for hydration even when it only needs to display the model.
+  // A module rendered only from Template/Zone/Util makes every consumer pay for hydration just to display it.
   #scanModules(sourceFiles: SourceFileInfo[]): QualityWarning[] {
     const modules = new Map<string, { clientMass: number; serverFiles: number; line: string }>();
     for (const sourceFile of sourceFiles) {
@@ -136,36 +136,32 @@ export class SsrScanner {
     }
     return [...modules]
       .filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS)
-      .map(([moduleDir, entry]) => ({
-        rule: "akan.ssr.module-missing-server-view",
-        scope: "ssr" as const,
-        severity: "warning" as const,
-        file: entry.line,
-        message: `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`,
-      }));
+      .map(([moduleDir, entry]) =>
+        fileWarning(
+          "akan.ssr.module-missing-server-view",
+          "ssr",
+          entry.line,
+          `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`,
+        ),
+      );
   }
 
-  // A load fired from a mount-only effect is data the route already could have fetched: the client renders an
-  // empty shell, hydrates, then fetches. A reactive effect (non-empty deps) responds to client state instead
-  // and has no server-side equivalent, so only the empty-dependency form is a finding.
+  // Only an empty-dependency effect is a finding: a reactive effect answers client state and has no server equivalent.
   #getMountLoadWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
     const warnings: QualityWarning[] = [];
-    const visit = (node: ts.Node) => {
-      if (this.#isMountEffect(sourceFile.sourceFile, node)) {
-        for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
-          warnings.push({
-            rule: "akan.ssr.client-mount-load",
-            scope: "ssr",
-            severity: "warning",
-            file: sourceFile.file,
-            line: this.#getLine(sourceFile.sourceFile, load.node),
-            message: `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
-          });
-        }
-      }
-      ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (!this.#isMountEffect(sourceFile.sourceFile, node)) return;
+      for (const load of this.#getLoadCalls(sourceFile.sourceFile, node))
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-mount-load",
+            "ssr",
+            sourceFile.file,
+            `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
+            this.#getLine(sourceFile.sourceFile, load.node),
+          ),
+        );
+    });
     return warnings;
   }
 
@@ -179,35 +175,30 @@ export class SsrScanner {
 
   #getLoadCalls(sourceFile: ts.SourceFile, node: ts.Node) {
     const calls: Array<{ callee: string; node: ts.Node }> = [];
-    const visit = (child: ts.Node) => {
-      if (ts.isCallExpression(child)) {
-        const callee = child.expression.getText(sourceFile);
-        if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
-          calls.push({ callee, node: child });
-      }
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    SsrScanner.#walk(node, (child) => {
+      if (!ts.isCallExpression(child)) return;
+      const callee = child.expression.getText(sourceFile);
+      if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
+        calls.push({ callee, node: child });
+    });
     return calls;
   }
 
   #getTemplateStateWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
     if (!sourceFile.file.endsWith(".Template.tsx")) return [];
     const warnings: QualityWarning[] = [];
-    const visit = (node: ts.Node) => {
-      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
-        warnings.push({
-          rule: "akan.ssr.template-client-state",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: this.#getLine(sourceFile.sourceFile, node),
-          message: "Template holds form state in useState. Templates are store-driven and carry no local state.",
-        });
-      }
-      ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState")
+        warnings.push(
+          fileWarning(
+            "akan.ssr.template-client-state",
+            "ssr",
+            sourceFile.file,
+            "Template holds form state in useState. Templates are store-driven and carry no local state.",
+            this.#getLine(sourceFile.sourceFile, node),
+          ),
+        );
+    });
     return warnings;
   }
 
@@ -261,7 +252,7 @@ export class SsrScanner {
 
   #getTouches(sourceFile: ts.SourceFile, node: ts.Node): string[] {
     const touches: string[] = [];
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isCallExpression(child)) {
         const callee = child.expression.getText(sourceFile);
         const bareName = callee.split(".").pop() ?? callee;
@@ -275,41 +266,42 @@ export class SsrScanner {
         if (root === "st") touches.push("st");
         else if (SsrScanner.#clientGlobals.has(root)) touches.push(root);
       }
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return touches;
   }
 
   #getTagNames(sourceFile: ts.SourceFile, node: ts.Node): Set<string> {
     const tags = new Set<string>();
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child))
         tags.add(child.tagName.getText(sourceFile).split(".")[0]);
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return tags;
   }
 
   #getMass(node: ts.Node) {
     let mass = 0;
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child)) mass += 1;
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return mass;
   }
 
+  static #walk(node: ts.Node, visit: (descendant: ts.Node) => void) {
+    const walk = (child: ts.Node) => {
+      visit(child);
+      ts.forEachChild(child, walk);
+    };
+    ts.forEachChild(node, walk);
+  }
+
   #hasUseClient(sourceFile: ts.SourceFile) {
     const first = sourceFile.statements[0];
     if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression)) return false;
     return first.expression.text === "use client";
   }
 
-  // A bare specifier is a third-party package: it may be client-only, which is a legitimate reason for the
-  // directive that no amount of AST reading can rule out.
+  // A third-party package may be client-only, a legitimate reason for the directive no AST reading can rule out.
   #hasVendorImport(sourceFile: ts.SourceFile) {
     return sourceFile.statements.some(
       (statement) => ts.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)),
@@ -340,9 +332,7 @@ export class SsrScanner {
     return false;
   }
 
-  // Zone/Template/Util carry the directive mechanically by file role, and `index_.tsx` is the declared
-  // "use client" + lazy() boundary. In neither case is the directive a stray — for module UI it means markup
-  // belongs in a Unit or View instead, which the component rules already cover.
+  // Zone/Template/Util carry the directive by file role, and `index_.tsx` is the declared lazy() boundary.
   #isConventionClientFile(file: string) {
     if (file.endsWith("/index_.tsx")) return true;
     return /\.(Zone|Template|Util)\.tsx$/.test(file) && this.#getModuleDir(file) !== null;

package/stripAnsi.ts

@@ -0,0 +1,3 @@
+const ansi = new RegExp(`${String.fromCharCode(27)}(?:[@-Z\\\\-_]|\\[[\\s\\S]*?[@-~])`, "g");
+
+export const stripAnsi = (text: string) => text.replace(ansi, "");

package/subspace.test.ts

@@ -1,31 +1,17 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, setDefaultTimeout, test } from "bun:test";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { formatSubspaceDiff, formatSubspacePushResults, formatSubspaceStatuses, Subspace } from "./subspace";
 import { SubspaceConfig } from "./subspaceConfig";
+import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 
-const tempRoots: string[] = [];
-const originalEnv = { ...process.env };
+//? Each case drives several real git clones and pushes; on a 4-core Windows VM that alone lands at 2-5s.
+setDefaultTimeout(20_000);
 
-beforeEach(() => {
-  process.env = { ...originalEnv };
-  process.env.AKAN_PUBLIC_REPO_NAME = "workspace";
-  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
-  process.env.AKAN_PUBLIC_ENV = "local";
-});
-
-afterEach(async () => {
-  process.env = { ...originalEnv };
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
+isolateEnv({ AKAN_PUBLIC_REPO_NAME: "workspace", AKAN_PUBLIC_SERVE_DOMAIN: "example.com", AKAN_PUBLIC_ENV: "local" });
+const makeTempRoot = tempDirs("akan-subspace-");
 
 const git = async (cwd: string, args: string[]) =>
   await new Executor("fixture", cwd).spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...args]);
@@ -64,10 +50,8 @@ const makeSys = async (root: string, member: "apps" | "libs", name: string, extr
     await write(path.join(root, member, name, relative), content);
 };
 
-/** A workspace with two apps, one shared library, and a subspace that serves only the first app. */
 const makeMirror = async (servedApp: string, privateApp: string, libName: string) => {
-  const workRoot = await mkdtemp(path.join(os.tmpdir(), "akan-subspace-"));
-  tempRoots.push(workRoot);
+  const workRoot = await makeTempRoot();
   const wsRoot = path.join(workRoot, "workspace");
   const bareRoot = path.join(workRoot, "subspace.git");
   await mkdir(wsRoot, { recursive: true });
@@ -96,7 +80,7 @@ const makeMirror = async (servedApp: string, privateApp: string, libName: string
   await write(path.join(wsRoot, "benchmarks/bench.ts"), "export {};\n");
   await write(
     path.join(wsRoot, "akan.subspace.ts"),
-    `export default { pushableBranches: ["develop"], exclude: ["benchmarks"], subspaces: [{ name: "acme", repo: "${bareRoot}", apps: ["${servedApp}"] }] };\n`,
+    `export default { pushableBranches: ["develop"], exclude: ["benchmarks"], subspaces: [{ name: "acme", repo: ${JSON.stringify(bareRoot)}, apps: ["${servedApp}"] }] };\n`,
   );
 
   await makeSys(wsRoot, "apps", servedApp, {