@akanjs/devkit 3.0.0-alpha.10 → 3.0.0-alpha.100

package/biome.base.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.12/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -25,7 +25,7 @@
         "noArrayIndexKey": "off",
         "noShadowRestrictedNames": "off",
         "noUnnecessaryConditions": {
-          "level": "error"
+          "level": "warn"
         }
       },
       "correctness": {
@@ -117,7 +117,9 @@
         "libs/*/client.ts",
         "libs/*/server.ts",
         "libs/*/index.ts",
-        "libs/*/lib/*/index.tsx"
+        "libs/*/lib/*/index.tsx",
+        "apps/*/lib/__lib/**",
+        "libs/*/lib/__lib/**"
       ],
       "linter": { "enabled": false },
       "formatter": { "enabled": false },
@@ -140,28 +142,65 @@
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
     {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx", "**/*.Unit.tsx", "**/*.View.tsx"],
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
       "plugins": [
         "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
         "./node_modules/@akanjs/devkit/lint/no-use-client-in-server.grit"
       ]
     },
     {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx"],
+      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
     },
     {
-      "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
+      "includes": [
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.store.ts"
+      ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
     },
     {
-      "includes": ["**/*.store.ts"],
+      "includes": ["{apps,libs}/**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
     },
     {
-      "includes": ["**/*.signal.ts"],
+      "includes": ["{apps,libs}/**/*.ts", "{apps,libs}/**/*.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-deprecated-log-level.grit"]
+    },
+    {
+      "includes": ["{apps,libs}/**/*.signal.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
     },
+    {
+      "includes": ["{apps,libs}/**/*.Util.tsx", "{apps,libs}/**/*.Zone.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-model-type-in-util-zone.grit"]
+    },
+    {
+      "includes": ["{apps,libs}/**/ui/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-async-component-in-ui.grit"]
+    },
+    {
+      "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/*.ts",
+        "{apps,libs}/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit"]
+    },
     {
       "includes": [
         "**/ui/**/*.ts",
@@ -186,46 +225,46 @@
     },
     {
       "includes": [
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"]
     },
     {
       "includes": [
-        "**/page/**/*.ts",
-        "**/page/**/*.tsx",
-        "**/index.ts",
-        "**/index.tsx",
-        "**/cnst.ts",
-        "**/db.ts",
-        "**/dict.ts",
-        "**/option.ts",
-        "**/sig.ts",
-        "**/srv.ts",
-        "**/st.ts",
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.signal.test.ts",
-        "**/*.service.test.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/index.ts",
+        "{apps,libs}/**/index.tsx",
+        "{apps,libs}/**/cnst.ts",
+        "{apps,libs}/**/db.ts",
+        "{apps,libs}/**/dict.ts",
+        "{apps,libs}/**/option.ts",
+        "{apps,libs}/**/sig.ts",
+        "{apps,libs}/**/srv.ts",
+        "{apps,libs}/**/st.ts",
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.signal.test.ts",
+        "{apps,libs}/**/*.service.test.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
       ],
       "plugins": [
         "./node_modules/@akanjs/devkit/lint/no-import-external-library.grit",

package/biomeBase.ts

@@ -6,4 +6,4 @@ export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
 // Biome disagrees with the shipped base config therefore fails to load it at all, which is why the version is
 // pinned here instead of resolved to latest at create time. Bump this and `biome.base.json` in one commit, and run
 // `biome migrate --write` in the workspace root and in `pkgs/@akanjs/devkit` so both configs move together.
-export const biomeVersion = "2.5.8";
+export const biomeVersion = "2.5.12";

package/capacitorApp.ts

@@ -123,6 +123,16 @@ interface MaterializeCapacitorConfigOptions {
 }
 type MobilePlatform = "ios" | "android";
 
+/**
+ * `AppExecutor.spawn`'s own options plus the two the Capacitor config is written from before the spawn:
+ * the platform the command targets, and — for iOS — whether it targets a device or a simulator, which
+ * decide the `capacitor.config.json` that command reads.
+ */
+type SpawnMobileOptions = Parameters<AppExecutor["spawn"]>[2] & {
+  platform?: MobilePlatform;
+  iosRunTargetKind?: IosRunTargetKind;
+};
+
 export interface LocalDevHostResolution {
   host: string;
   source: "override" | "detected" | "loopback" | "platform";

package/cloud/globalConfig.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { chmod, mkdir } from "node:fs/promises";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import {
@@ -29,9 +29,16 @@ export class GlobalConfig {
       remoteEnvServers: akanConfig.remoteEnvServers ?? defaultAkanGlobalConfig.remoteEnvServers,
     };
   }
+  /**
+   * This file holds the cloud jwt, a refresh token that does not expire, and the LLM api key, so it is
+   * written owner-only — the same `0600` the runtime gives its control socket. `Bun.write` takes no mode
+   * and lands on `0666 & ~umask` (0644 on a default shell), so the mode is applied after the write; an
+   * existing world-readable file is tightened by the next write rather than left as it was found.
+   */
   static async #setAkanGlobalConfig(akanConfig: AkanGlobalConfig) {
-    await mkdir(basePath, { recursive: true });
+    await mkdir(basePath, { recursive: true, mode: 0o700 });
     await Bun.write(configPath, JSON.stringify(akanConfig, null, 2));
+    await chmod(configPath, 0o600);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();

package/codegenLock.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodegenLock } from "./codegenLock";
+
+const roots: string[] = [];
+const makeRoot = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-codegen-lock-"));
+  roots.push(root);
+  return root;
+};
+const seedHolder = async (root: string, holder: unknown) => {
+  const lockPath = CodegenLock.pathIn(root);
+  await Bun.write(lockPath, typeof holder === "string" ? holder : JSON.stringify(holder));
+  return lockPath;
+};
+/** A pid that cannot be alive: `kill(0)` on it is ESRCH on every platform this runs on. */
+const deadPid = 0x7ffffff;
+
+afterEach(async () => {
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
+});
+
+describe("CodegenLock", () => {
+  test("serializes concurrent callers in the same process", async () => {
+    const root = await makeRoot();
+    const order: string[] = [];
+    const body = async (name: string) => {
+      order.push(`${name}:in`);
+      await Bun.sleep(20);
+      order.push(`${name}:out`);
+    };
+    await Promise.all([
+      CodegenLock.run(root, "a", () => body("a")),
+      CodegenLock.run(root, "b", () => body("b")),
+      CodegenLock.run(root, "c", () => body("c")),
+    ]);
+    for (const name of ["a", "b", "c"]) {
+      const enter = order.indexOf(`${name}:in`);
+      const leave = order.indexOf(`${name}:out`);
+      expect(leave).toBe(enter + 1);
+    }
+  });
+
+  test("releases the lock file even when the body throws", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    await expect(
+      CodegenLock.run(root, "boom", async () => {
+        expect(await Bun.file(lockPath).exists()).toBe(true);
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(await Bun.file(lockPath).exists()).toBe(false);
+  });
+
+  test("writes a holder naming this process", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const holder = await CodegenLock.run(root, "scan:minimal", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder)).toMatchObject({ pid: process.pid, label: "scan:minimal" });
+  });
+
+  test("reclaims a lock whose holder is gone", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: deadPid, at: Date.now(), label: "crashed" });
+    const started = Date.now();
+    const holder = await CodegenLock.run(root, "next", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+    expect(Date.now() - started).toBeLessThan(CodegenLock.waitTimeoutMs);
+  });
+
+  test("respects a live holder until the wait expires, then proceeds without the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: process.pid, at: Date.now(), label: "other-session" });
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      let ran = false;
+      await CodegenLock.run(root, "blocked", async () => {
+        ran = true;
+        // The foreign holder is left in place: nothing may delete a lock it does not hold.
+        expect(JSON.parse(await readFile(lockPath, "utf8")).label).toBe("other-session");
+      });
+      expect(ran).toBe(true);
+      expect(await Bun.file(lockPath).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+  });
+
+  test("keeps a young unreadable lock but reclaims a stale one", async () => {
+    const young = await makeRoot();
+    await seedHolder(young, "");
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      await CodegenLock.run(young, "young", async () => undefined);
+      expect(await Bun.file(CodegenLock.pathIn(young)).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+
+    const stale = await makeRoot();
+    const stalePath = await seedHolder(stale, "");
+    const aged = new Date(Date.now() - CodegenLock.unknownHolderStaleMs - 1_000);
+    await utimes(stalePath, aged, aged);
+    const holder = await CodegenLock.run(stale, "stale", async () => await readFile(stalePath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+  });
+
+  test("blocks a second process for as long as it holds the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const script = path.join(root, "holder.ts");
+    await writeFile(
+      script,
+      `import { CodegenLock } from ${JSON.stringify(path.resolve(import.meta.dir, "codegenLock.ts"))};
+await CodegenLock.run(${JSON.stringify(root)}, "child", async () => {
+  process.stdout.write("held\\n");
+  await Bun.sleep(400);
+});
+`,
+    );
+    const child = Bun.spawn(["bun", script], { stdio: ["ignore", "pipe", "inherit"] });
+    const reader = child.stdout.getReader();
+    await reader.read();
+    reader.releaseLock();
+
+    const started = Date.now();
+    await CodegenLock.run(root, "parent", async () => undefined);
+    expect(Date.now() - started).toBeGreaterThan(100);
+    await child.exited;
+    expect(await stat(lockPath).catch(() => null)).toBeNull();
+  });
+});

package/codegenLock.ts

@@ -0,0 +1,136 @@
+import { mkdir, open, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+
+interface LockHolder {
+  pid: number;
+  at: number;
+  label: string;
+}
+
+/**
+ * A workspace-wide mutex over the generated source files every dev server in the workspace rewrites.
+ *
+ * `WatchRootResolver` narrows each dev server to its own app and its own lib dependencies, but two apps
+ * that share a lib still both watch it, so a save there reaches both builders and both regenerate the
+ * same barrel. Whichever watcher is mid-scan then reads a half-written file back as a user edit, which is
+ * a rebuild per rewrite. `scanSync` writes the same files at boot for every mounting app.
+ *
+ * A wait that expires proceeds *without* the lock rather than failing: this sits on the dev server's
+ * hot path, and stalling the file watcher is worse than the torn read `FileSys.writeTextAtomic` already
+ * prevents on its own.
+ */
+export class CodegenLock {
+  static readonly fileName = "codegen.lock";
+  static readonly waitTimeoutMs = 10_000;
+  /**
+   * How long an unreadable lock file is respected. It covers the window between the exclusive create
+   * and the holder write, where the file exists but names no pid yet — a young one is somebody else
+   * mid-acquire, not a corpse.
+   */
+  static readonly unknownHolderStaleMs = 60_000;
+  static readonly #pollMs = 25;
+  static readonly #logger = new Logger("CodegenLock");
+  /** Serializes callers inside this process, which one `O_EXCL` file cannot tell apart. */
+  static #queue: Promise<void> = Promise.resolve();
+
+  static pathIn(workspaceRoot: string) {
+    return path.join(workspaceRoot, "local", ".akan", CodegenLock.fileName);
+  }
+
+  static async run<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const ahead = CodegenLock.#queue;
+    let done!: () => void;
+    CodegenLock.#queue = new Promise<void>((resolve) => {
+      done = resolve;
+    });
+    try {
+      await CodegenLock.#waitForQueue(ahead, label);
+      return await CodegenLock.#withFileLock(workspaceRoot, label, fn);
+    } finally {
+      done();
+    }
+  }
+
+  static async #waitForQueue(ahead: Promise<void>, label: string) {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const expired = new Promise<"expired">((resolve) => {
+      timer = setTimeout(() => resolve("expired"), CodegenLock.waitTimeoutMs);
+    });
+    try {
+      if ((await Promise.race([ahead.then(() => "done" as const), expired])) === "expired")
+        CodegenLock.#logger.warn(
+          `codegen lock queued past ${CodegenLock.waitTimeoutMs}ms in this process; continuing without waiting (${label})`,
+        );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  static async #withFileLock<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const lockPath = CodegenLock.pathIn(workspaceRoot);
+    await mkdir(path.dirname(lockPath), { recursive: true }).catch(() => undefined);
+    const held = await CodegenLock.#acquire(lockPath, label);
+    try {
+      return await fn();
+    } finally {
+      if (held) await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  static async #acquire(lockPath: string, label: string): Promise<boolean> {
+    const deadline = Date.now() + CodegenLock.waitTimeoutMs;
+    for (;;) {
+      const handle = await open(lockPath, "wx").catch(() => null);
+      if (handle) {
+        await handle
+          .writeFile(JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies LockHolder))
+          .catch(() => undefined);
+        await handle.close().catch(() => undefined);
+        return true;
+      }
+      if (await CodegenLock.#reclaimIfAbandoned(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        CodegenLock.#logger.warn(
+          `codegen lock at ${lockPath} held past ${CodegenLock.waitTimeoutMs}ms; continuing without it (${label})`,
+        );
+        return false;
+      }
+      await Bun.sleep(CodegenLock.#pollMs);
+    }
+  }
+
+  /** A live holder is never reclaimed — the wait timeout is what bounds a pathologically slow one. */
+  static async #reclaimIfAbandoned(lockPath: string): Promise<boolean> {
+    const info = await stat(lockPath).catch(() => null);
+    if (!info) return true;
+    const holder = CodegenLock.#parseHolder(await readFile(lockPath, "utf8").catch(() => ""));
+    if (holder) {
+      if (CodegenLock.#isAlive(holder.pid)) return false;
+    } else if (Date.now() - info.mtimeMs < CodegenLock.unknownHolderStaleMs) return false;
+    await rm(lockPath, { force: true }).catch(() => undefined);
+    return true;
+  }
+
+  static #parseHolder(raw: string): LockHolder | null {
+    try {
+      const parsed = JSON.parse(raw) as Partial<LockHolder>;
+      if (typeof parsed.pid !== "number" || typeof parsed.at !== "number") return null;
+      return { pid: parsed.pid, at: parsed.at, label: typeof parsed.label === "string" ? parsed.label : "" };
+    } catch {
+      // A truncated holder file names no pid, so it is aged by mtime instead.
+      return null;
+    }
+  }
+
+  static #isAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM is a pid that exists under another user, which still holds the lock.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  }
+}

package/commandDecorators/argMeta.ts

@@ -12,7 +12,7 @@ import { COMMAND_META, type CommandCls } from "./targetMeta";
 export const argTypes = ["Argument", "Option"] as const;
 export type ArgType = (typeof argTypes)[number];
 
-export const internalArgTypes = ["Workspace", "App", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
+export const internalArgTypes = ["Workspace", "App", "Apps", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
 export type InternalArgType = (typeof internalArgTypes)[number];
 
 export type PrimitiveArgType = StringConstructor | NumberConstructor | BooleanConstructor;
@@ -83,6 +83,14 @@ export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPri
 export const App = createInternalArgToken<AppExecutor, "App">("App");
 export type App = AppExecutor;
 
+/**
+ * One or more apps, from a variadic positional (`akan start a b`, `akan start a,b`, `akan start all`)
+ * or a checkbox when none is named. Reach for it only where running several is meaningful — every other
+ * command takes `App`, whose single-select is unchanged.
+ */
+export const Apps = createInternalArgToken<AppExecutor[], "Apps">("Apps");
+export type Apps = AppExecutor[];
+
 export const Lib = createInternalArgToken<LibExecutor, "Lib">("Lib");
 export type Lib = LibExecutor;