@akanjs/devkit 3.0.0-alpha.88 → 3.0.0-alpha.89

package/commandDecorators/command.ts

@@ -1,8 +1,14 @@
 import path from "node:path";
-import type { confirm as inquirerConfirm, input as inquirerInput, select as inquirerSelect } from "@inquirer/prompts";
+import type {
+  checkbox as inquirerCheckbox,
+  confirm as inquirerConfirm,
+  input as inquirerInput,
+  select as inquirerSelect,
+} from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
 import { type Command, program } from "commander";
+import { AppSelectionMemory } from "../appSelectionMemory";
 import { AppExecutor, Executor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
 // Import the owning modules directly, never the root barrel: `..` re-exports all 41 devkit modules,
 // so a barrel import here drags ink, @trapezedev/project, ssh2, @langchain/* and the cloud stack into
@@ -103,6 +109,7 @@ const prompts = async () => await import("@inquirer/prompts");
 const select = ((config, context) => prompts().then((m) => m.select(config, context))) as typeof inquirerSelect;
 const confirm = ((config, context) => prompts().then((m) => m.confirm(config, context))) as typeof inquirerConfirm;
 const input = ((config, context) => prompts().then((m) => m.input(config, context))) as typeof inquirerInput;
+const checkbox = ((config, context) => prompts().then((m) => m.checkbox(config, context))) as typeof inquirerCheckbox;
 
 /**
  * Rejects a value that is not one of the declared choices, in commander's own wording.
@@ -208,6 +215,46 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   );
 };
 
+/** A variadic positional arrives as an array, and each entry may itself be a comma-separated list. */
+const parseAppNameList = (value: string | string[] | undefined): string[] =>
+  (Array.isArray(value) ? value : value === undefined ? [] : [value])
+    .flatMap((entry) => entry.split(","))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+/**
+ * The `Apps` token: named apps, `all`, or a checkbox when the command line names none. Kept out of
+ * `getInternalArgumentValue` because it is the only internal arg whose positional is variadic, so it is
+ * the only one whose raw value is an array.
+ */
+export const getAppsArgumentValue = async (
+  value: string | string[] | undefined,
+  workspace: WorkspaceExecutor,
+): Promise<AppExecutor[]> => {
+  const appNames = await workspace.getApps();
+  if (appNames.length === 0) throw new Error("No apps found in this workspace (apps/<appName>/akan.config.ts)");
+  const requested = parseAppNameList(value);
+  if (requested.includes("all")) return appNames.map((name) => AppExecutor.from(workspace, name));
+  if (requested.length) {
+    const unknown = requested.filter((name) => !appNames.includes(name));
+    if (unknown.length)
+      throw new Error(
+        `Unknown app${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Available: ${appNames.join(", ")}, all`,
+      );
+    return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
+  }
+  if (appNames.length === 1 && appNames[0]) return [AppExecutor.from(workspace, appNames[0])];
+  const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
+  const picked = await checkbox<string>({
+    message: "Select the apps to run (space to toggle, enter to confirm)",
+    choices: appNames.map((name) => ({ name, value: name, checked: remembered.has(name) })),
+    // Enter with nothing ticked is a mis-keypress far more often than an intent to run nothing.
+    required: true,
+  });
+  await AppSelectionMemory.write(workspace.workspaceRoot, picked);
+  return picked.map((name) => AppExecutor.from(workspace, name));
+};
+
 export const getInternalArgumentValue = async (
   argMeta: InternalArgMeta,
   value: string | undefined,
@@ -353,6 +400,11 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
               `[sys-name:module-name]`,
               `${argMeta.type} in this workspace (apps|libs)/<sys-name>/lib/<module-name>`,
             );
+          } else if (argMeta.type === "Apps") {
+            programCommand = programCommand.argument(
+              `[apps...]`,
+              `apps in this workspace apps/<appName>, or all (space- or comma-separated; omit to pick interactively)`,
+            );
           } else {
             const sysType = argMeta.type.toLowerCase();
             programCommand = programCommand.argument(
@@ -381,6 +433,11 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
               commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt, commandContext);
             else if (argMeta.type === "Argument")
               commandArgs[argMeta.idx] = await getArgumentValue(argMeta, cmdArgs[argMeta.idx] as string);
+            else if (argMeta.type === "Apps")
+              commandArgs[argMeta.idx] = await getAppsArgumentValue(
+                cmdArgs[argMeta.idx] as string | string[] | undefined,
+                workspace,
+              );
             else
               commandArgs[argMeta.idx] = await getInternalArgumentValue(
                 argMeta as InternalArgMeta,
@@ -390,6 +447,12 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
             // set app name to env
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;
+            //? Only when exactly one app resolved. Publishing a name while several are in play would make
+            //? every env-derived answer in this process belong to whichever app happened to be last.
+            else if (Array.isArray(commandArgs[argMeta.idx])) {
+              const apps = commandArgs[argMeta.idx] as AppExecutor[];
+              if (apps.length === 1 && apps[0]) process.env.AKAN_PUBLIC_APP_NAME = apps[0].name;
+            }
             assignCommandContext(commandContext, argMeta, commandArgs[argMeta.idx]);
             if ((opt as { verbose?: boolean }).verbose) Executor.setVerbose(true);
           }

package/commandDecorators/helpFormatter.ts

@@ -159,6 +159,7 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
     .map((arg) => {
       if (arg.type === "Workspace") return "";
       if (arg.type === "Module") return "[sys:module]";
+      if (arg.type === "Apps") return "[apps...]";
       if (arg.type === "Argument") {
         return `[${camelToKebabCase(arg.name)}]`;
       }
@@ -192,6 +193,9 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
       } else if (arg.type === "Module") {
         argName = "sys:module";
         argDesc = "Module in format: app-name:module-name or lib-name:module-name";
+      } else if (arg.type === "Apps") {
+        argName = "apps...";
+        argDesc = "App names, space- or comma-separated, or all. Omit to pick them interactively";
       } else {
         argName = arg.type.toLowerCase();
         argDesc = `${arg.type} name in this workspace`;

package/executors.ts

@@ -41,6 +41,7 @@ import {
 } from "./agentsIndex";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
+import { CodegenLock } from "./codegenLock";
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
@@ -1136,18 +1137,22 @@ export class SysExecutor extends Executor {
         : await LibInfo.fromExecutor(this as unknown as LibExecutor, {
             refresh,
           });
-    if (write) {
-      await Promise.all(this.#getScanTemplateTasks(scanInfo));
-      await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
-      if (this.type === "lib") this.#updateDependencies(scanInfo);
+    //* `writeLib` regenerates every dependency lib's barrels, and each mounting app's `akan start`
+    //* regenerates the same ones — so this region races the other dev servers in the workspace and the
+    //* builders that watch what it writes.
+    if (write)
+      await CodegenLock.run(this.workspace.workspaceRoot, `scan:${this.name}`, async () => {
+        await Promise.all(this.#getScanTemplateTasks(scanInfo));
+        await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
+        if (this.type === "lib") this.#updateDependencies(scanInfo);
 
-      if (writeLib) {
-        const libInfos = [...scanInfo.getLibInfos().values()];
-        await this.#updateDependencies(scanInfo);
-        await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
-      }
-      await this.syncAgentsIndex(scanInfo);
-    }
+        if (writeLib) {
+          const libInfos = [...scanInfo.getLibInfos().values()];
+          await this.#updateDependencies(scanInfo);
+          await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
+        }
+        await this.syncAgentsIndex(scanInfo);
+      });
     this.#scanInfo = scanInfo;
     return scanInfo;
   }
@@ -1405,6 +1410,8 @@ export class AppExecutor extends SysExecutor {
     const databaseMode = process.env.AKAN_DATABASE_MODE ?? akanConfig.defaultDatabaseMode ?? "single";
     const routeEnv = {
       AKAN_PUBLIC_BASE_PATHS: [...akanConfig.basePaths].join(","),
+      AKAN_PUBLIC_API_PREFIX: akanConfig.api.prefix,
+      AKAN_PUBLIC_WS_PREFIX: akanConfig.api.websocketPrefix,
       AKAN_DATABASE_MODE: databaseMode,
     };
     Object.assign(process.env, routeEnv);

package/fileSys.ts

@@ -1,4 +1,4 @@
-import { lstat, stat } from "node:fs/promises";
+import { lstat, rename, rm, stat } from "node:fs/promises";
 import { Logger } from "akanjs/common";
 
 export class FileSys {
@@ -39,6 +39,24 @@ export class FileSys {
   static async writeText(path: string, content: string) {
     return await Bun.file(path).write(content);
   }
+  /**
+   * Replaces a file in one `rename`, so a concurrent reader sees either the old bytes or the new ones.
+   * Generated barrels are written by every dev server watching the same `libs/` tree while those same
+   * servers' watchers are reading them, and a half-written barrel reads back as a user edit.
+   *
+   * The temp file is a sibling because `rename` is only atomic within a filesystem, and it lands in a
+   * watched directory — the `.tmp` suffix is what `HmrChangeClassifier` ignores it by.
+   */
+  static async writeTextAtomic(filePath: string, content: string) {
+    const temp = `${filePath}.${process.pid}.${Date.now().toString(36)}.tmp`;
+    try {
+      await Bun.write(temp, content);
+      await rename(temp, filePath);
+    } catch (error) {
+      await rm(temp, { force: true }).catch(() => undefined);
+      throw error;
+    }
+  }
   static async writeJson(path: string, content: object) {
     return await Bun.file(path).write(`${JSON.stringify(content, null, 2)}\n`);
   }

package/frontendBuild/autoImportSync.ts

@@ -1,6 +1,7 @@
-import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
+import { FileSys } from "../fileSys";
 
 //* Auto-import daemon: a source-editing sibling of DevGeneratedIndexSync. When a domain file changes,
 //* framework symbols that are used but not imported (e.g. `Int` in a *.constant.ts, `fetch` in a *.store.ts)
@@ -267,7 +268,7 @@ export class AutoImportSync {
     const resolveExtra = await this.#extraResolverFor(abs, ctx);
     const next = transformSource(source, abs, ctx, resolveExtra);
     if (next === null || next === source) return false;
-    await writeFile(abs, next);
+    await FileSys.writeTextAtomic(abs, next);
     return true;
   }
 

package/frontendBuild/devGeneratedIndexSync.ts

@@ -1,5 +1,6 @@
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { FileSys } from "../fileSys";
 
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
@@ -101,7 +102,7 @@ export class DevGeneratedIndexSync {
     const current = await readFile(indexPath, "utf8").catch(() => null);
     if (current === content) return false;
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, content);
+    await FileSys.writeTextAtomic(indexPath, content);
     return true;
   }
 

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -14,11 +14,25 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-status",
   "builder-metrics",
 ]);
+/**
+ * Where a dev child process writes. `"pipe"` is not only about keeping a TUI's frame clean: a Bun child
+ * that inherits the controlling terminal snapshots its termios at spawn and writes that snapshot back
+ * when it exits, so a builder spawned while something holds the terminal raw turns it raw again on the
+ * first recycle. See the XXX comment on `Spinner.oraOptions`.
+ */
+export type DevStdioMode = "inherit" | "pipe";
+
 interface IncrementalBuilderHostOptions {
   app: App;
   entry: string;
   env: Record<string, string>;
+  stdio?: DevStdioMode;
   onMessage: (message: BuilderMessage) => void;
+  /**
+   * Required when `stdio` is `"pipe"`: an undrained pipe fills and blocks the builder's next write.
+   * Text arrives as decoded chunks, not lines — a consumer that needs lines splits them itself.
+   */
+  onOutput?: (kind: "stdout" | "stderr", text: string) => void;
 }
 
 /**
@@ -63,7 +77,9 @@ export class IncrementalBuilderHost {
   app: App;
   ready = false;
   readonly #onMessage: (message: BuilderMessage) => void;
-  #proc: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  readonly #stdio: DevStdioMode;
+  readonly #onOutput: ((kind: "stdout" | "stderr", text: string) => void) | null;
+  #proc: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #status: IncrementalBuilderStatus = "stopped";
   #restartAttempts = 0;
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
@@ -83,11 +99,13 @@ export class IncrementalBuilderHost {
    */
   readonly #inFlight = new Map<number, "build-route" | "build-csr">();
   #startOptions: IncrementalBuilderStartOptions = {};
-  constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
+  constructor({ app, entry, env, stdio = "inherit", onMessage, onOutput }: IncrementalBuilderHostOptions) {
     this.app = app;
     this.entry = entry;
     this.env = env;
+    this.#stdio = stdio;
     this.#onMessage = onMessage;
+    this.#onOutput = onOutput ?? null;
   }
   get status() {
     return this.#status;
@@ -115,11 +133,11 @@ export class IncrementalBuilderHost {
     // the flag is what tells it to re-announce what it booted with.
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
-    let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
+    let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
       env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: ["ignore", this.#stdio, this.#stdio],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
@@ -167,8 +185,25 @@ export class IncrementalBuilderHost {
       },
     });
     this.#proc = proc;
+    // Re-attached per spawn, not once per host: a recycle or a crash-restart brings new pipes.
+    if (this.#stdio === "pipe" && this.#onOutput) {
+      void this.#drain(proc.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
+      void this.#drain(proc.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
+    }
     this.logger.verbose(`builder spawned pid=${proc.pid} entry=${this.entry}${isRestart ? " restart=1" : ""}`);
   }
+  async #drain(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
+    if (!stream) return;
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (text) this.#onOutput?.(kind, text);
+      }
+    } catch {
+      // The stream closes when the builder exits; nothing further to surface here.
+    }
+  }
   #scheduleRestart() {
     if (this.#manualStop || this.#restartTimer) return;
     this.#status = "restarting";
@@ -278,7 +313,15 @@ export class IncrementalBuilderHost {
     this.ready = false;
     this.#status = "stopped";
   }
-  static async create(app: App, env: Record<string, string>, onMessage: (message: BuilderMessage) => void) {
+  static async create(
+    app: App,
+    env: Record<string, string>,
+    onMessage: (message: BuilderMessage) => void,
+    {
+      stdio = "inherit",
+      onOutput,
+    }: { stdio?: DevStdioMode; onOutput?: (kind: "stdout" | "stderr", text: string) => void } = {},
+  ) {
     const candidates = [
       path.join(app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts"),
       path.join(
@@ -289,7 +332,8 @@ export class IncrementalBuilderHost {
       path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
     ];
     for (const c of candidates)
-      if (await Bun.file(c).exists()) return new IncrementalBuilderHost({ app, entry: c, env, onMessage });
+      if (await Bun.file(c).exists())
+        return new IncrementalBuilderHost({ app, entry: c, env, stdio, onMessage, onOutput });
     throw new Error(`[cli] frontend builder entry not found; looked in: ${candidates.join(", ")}`);
   }
 }

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 // barrel reaches `cssCompiler`/`ssrBaseArtifactBuilder`, which pull tailwindcss + @tailwindcss/node
 // (~40MB) into a process that then holds them for the whole dev session. Phase 2 moved css compilation
 // into the batch worker, so this process has no use for them — `entryModuleGraph.test.ts` keeps it that way.
+import { CodegenLock } from "@akanjs/devkit/codegenLock";
 import type { App } from "@akanjs/devkit/commandDecorators";
 import { AppExecutor, type PageRoot, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import { AutoImportSync } from "@akanjs/devkit/frontendBuild/autoImportSync";
@@ -299,11 +300,17 @@ class IncrementalBuilder {
     //* Insert framework imports that are used but omitted (e.g. `Int` in *.constant.ts, `fetch` in
     //* *.store.ts) before regenerating barrels. Edits land on files already in this batch, so they
     //* rebuild in this same generation; the write is idempotent so it does not re-trigger the watcher.
-    const autoImport = await this.#autoImportSync.syncForBatch(batch.files);
+    const [autoImport, indexSync] = await CodegenLock.run(
+      this.#app.workspace.workspaceRoot,
+      `hmr-batch:${this.#app.name}`,
+      async () => {
+        const auto = await this.#autoImportSync.syncForBatch(batch.files);
+        return [auto, await this.#generatedIndexSync.syncForBatch(batch.files)] as const;
+      },
+    );
     for (const error of autoImport.errors) this.#logger.error(error);
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
-    const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
     //* Both passes above write source files, and this generation's build consumes what they wrote. Hand
     //* them to the watcher so its verification scan does not read them back as a user edit and spend a
     //* second generation rebuilding identical content.

package/index.ts

@@ -45,7 +45,5 @@ export type * from "./spinner";
 export type * from "./transforms";
 export type * from "./typeChecker";
 export type * from "./types";
-export type * from "./ui";
 export type * from "./uploadRelease";
-export type * from "./useStdoutDimensions";
 export type * from "./workflow";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.88",
+  "version": "3.0.0-alpha.89",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -33,7 +33,6 @@
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
     "./mobile": "./mobile/index.ts",
     "./transforms": "./transforms/index.ts",
-    "./ui": "./ui/index.ts",
     "./workflow": "./workflow/index.ts",
     "./*.ts": "./*.ts",
     "./*": "./*.ts"
@@ -45,14 +44,13 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.88",
+    "akanjs": "3.0.0-alpha.89",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
     "fontaine": "^0.8.0",
     "fonteditor-core": "^2.6.3",
     "ignore": "^7.0.5",
-    "ink": "^6.8.0",
     "ora": "^9.4.0",
     "ssh2": "^1.17.0",
     "subset-font": "^2.5.0",