@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/scanInfo.ts

@@ -27,20 +27,13 @@ const serviceFileTypes = [
   "zone",
 ] as const;
 type ServiceFileType = (typeof serviceFileTypes)[number];
-const databaseFileTypes = [
-  "constant",
-  "dictionary",
-  "document",
-  "service",
-  "signal",
-  "store",
-  "template",
-  "unit",
-  "util",
-  "view",
-  "zone",
-] as const;
+const databaseFileTypes = ["constant", "dictionary", "document", ...serviceFileTypes.slice(1)] as const;
 type DatabaseFileType = (typeof databaseFileTypes)[number];
+const uiFileTypes = new Set<DatabaseFileType>(["template", "unit", "util", "view", "zone"]);
+const fileTypeOf = (filename: string) =>
+  databaseFileTypes.find((type) =>
+    filename.endsWith(uiFileTypes.has(type) ? `.${type[0].toUpperCase()}${type.slice(1)}.tsx` : `.${type}.ts`),
+  );
 
 type ModuleKind = "database" | "service" | "scalar";
 
@@ -56,14 +49,11 @@ const moduleUiFileTypes = {
   service: new Set(["Util", "Zone"]),
   scalar: new Set(["Template", "Unit"]),
 } satisfies Record<ModuleKind, Set<string>>;
-const testFilePattern = /\.(test|spec)\.(ts|tsx)$/;
 
-// The dependency scanner needs `typescript` (~65MB resident). Only the scan/sync commands run it, so
-// load it on demand rather than through the module graph of every process that imports scan info.
+// Lazy: the dependency scanner pulls in `typescript` (~65MB resident), which only scan and sync need.
 const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExecutor) =>
   (await import("./dependencyScanner")).TypeScriptDependencyScanner.from(exec);
 
-const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
 async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {
@@ -85,33 +75,21 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
   const allowedRootFiles: ReadonlySet<string> = rootAllowedFiles[exec.type];
   const allowedRootDirs: ReadonlySet<string> = rootAllowedDirs[exec.type];
   const { files, dirs } = await exec.getFilesAndDirs(".");
-  files
-    .filter((filename) => !allowedRootFiles.has(filename))
-    .forEach((filename) => {
-      addViolation(filename, `unsupported ${exec.type} root file`);
-    });
-  dirs
-    .filter((dirname) => !allowedRootDirs.has(dirname))
-    .forEach((dirname) => {
-      addViolation(dirname, `unsupported ${exec.type} root folder`);
-    });
+  for (const filename of files)
+    if (!allowedRootFiles.has(filename)) addViolation(filename, `unsupported ${exec.type} root file`);
+  for (const dirname of dirs)
+    if (!allowedRootDirs.has(dirname)) addViolation(dirname, `unsupported ${exec.type} root folder`);
 
-  //* An app validates its page tree in `getPageKeys`, which a lib has no equivalent of — so a lib's own
-  //* routes went unchecked until whichever app opted into them with `syncPageLibs` blew up on the sync.
+  //* A lib has no `getPageKeys`, so its own route files are validated here.
   if (exec.type === "lib")
     for (const { relativePath, reason } of await exec.getPageConventionViolations()) addViolation(relativePath, reason);
 
-  libRoot.files
-    .filter((filename) => !isAllowedLibFacetRootFile(filename))
-    .forEach((filename) => {
+  for (const filename of libRoot.files)
+    if (!isAllowedLibFacetRootFile(filename))
       addViolation(path.join("lib", filename), "unsupported lib facet root file");
-    });
-
-  libRoot.dirs
-    .filter((dirname) => dirname.startsWith("__") && !internalLibDirs.has(dirname))
-    .forEach((dirname) => {
+  for (const dirname of libRoot.dirs)
+    if (dirname.startsWith("__") && !internalLibDirs.has(dirname))
       addViolation(path.join("lib", dirname), "unsupported internal lib folder");
-    });
 
   const databaseDirs = libRoot.dirs.filter((dirname) => !dirname.startsWith("_"));
   const serviceDirs = libRoot.dirs.filter((dirname) => dirname.startsWith("_") && !dirname.startsWith("__"));
@@ -146,43 +124,23 @@ async function validateModuleFiles(
 
   const uiModuleName = moduleName[0].toUpperCase() + moduleName.slice(1);
 
-  files.forEach((filename) => {
-    const filePath = path.join(modulePath, filename);
-    if (filename === "index.ts" || filename === "index.tsx" || isAllowedTestFile(filename)) return;
-    if (filename === `${moduleName}.abstract.md`) return;
-
+  for (const filename of files) {
+    const scanPath = getScanPath(exec, path.join(modulePath, filename));
+    if (filename === "index.ts" || filename === "index.tsx" || /\.(test|spec)\.(ts|tsx)$/.test(filename)) continue;
+    if (filename === `${moduleName}.abstract.md`) continue;
     const uiMatch = filename.match(/^([A-Z][A-Za-z0-9]+)\.([A-Z][A-Za-z0-9]*)\.tsx$/);
-    if (uiMatch) {
-      const fileModuleName = uiMatch[1];
-      const fileType = uiMatch[2];
-      if (fileModuleName !== uiModuleName) {
-        violations.push(
-          `${getScanPath(exec, filePath)}: module name mismatch: expected '${uiModuleName}', got '${fileModuleName}'`,
-        );
-      }
-      if (!moduleUiFileTypes[kind].has(fileType)) {
-        violations.push(`${getScanPath(exec, filePath)}: unsupported ${kind} UI file`);
-      }
-      return;
-    }
-
-    const nonUiMatch = filename.match(/^([a-z][a-zA-Z0-9]*)\.([a-z][a-z0-9]*)\.ts$/);
-    if (nonUiMatch) {
-      const fileModuleName = nonUiMatch[1];
-      const fileType = nonUiMatch[2];
-      if (fileModuleName !== moduleName) {
-        violations.push(
-          `${getScanPath(exec, filePath)}: module name mismatch: expected '${moduleName}', got '${fileModuleName}'`,
-        );
-      }
-      if (!moduleNonUiFileTypes[kind].has(fileType)) {
-        violations.push(`${getScanPath(exec, filePath)}: unsupported ${kind} file`);
-      }
-      return;
+    const match = uiMatch ?? filename.match(/^([a-z][a-zA-Z0-9]*)\.([a-z][a-z0-9]*)\.ts$/);
+    if (!match) {
+      violations.push(`${scanPath}: unsupported module file`);
+      continue;
     }
-
-    violations.push(`${getScanPath(exec, filePath)}: unsupported module file`);
-  });
+    const [, fileModuleName, fileType] = match;
+    const expectedName = uiMatch ? uiModuleName : moduleName;
+    if (fileModuleName !== expectedName)
+      violations.push(`${scanPath}: module name mismatch: expected '${expectedName}', got '${fileModuleName}'`);
+    if (!(uiMatch ? moduleUiFileTypes : moduleNonUiFileTypes)[kind].has(fileType))
+      violations.push(`${scanPath}: unsupported ${kind}${uiMatch ? " UI" : ""} file`);
+  }
 }
 
 class ScanInfo {
@@ -239,51 +197,16 @@ class ScanInfo {
       } else databaseDirs.push(name);
     });
 
+    const collect = async (dir: string, name: string, kind: "databases" | "services" | "scalars") => {
+      for (const filename of await exec.readdir(dir)) {
+        const type = fileTypeOf(filename);
+        if (type) (files[type] as { [key in typeof kind]?: string[] })[kind]?.push(name);
+      }
+    };
     await Promise.all([
-      ...databaseDirs.map(async (name) => {
-        const filenames = await exec.readdir(path.join("lib", name));
-        filenames.forEach((filename) => {
-          if (filename.endsWith(".constant.ts")) files.constant.databases.push(name);
-          else if (filename.endsWith(".dictionary.ts")) files.dictionary.databases.push(name);
-          else if (filename.endsWith(".document.ts")) files.document.databases.push(name);
-          else if (filename.endsWith(".service.ts")) files.service.databases.push(name);
-          else if (filename.endsWith(".signal.ts")) files.signal.databases.push(name);
-          else if (filename.endsWith(".store.ts")) files.store.databases.push(name);
-          else if (filename.endsWith(".Template.tsx")) files.template.databases.push(name);
-          else if (filename.endsWith(".Unit.tsx")) files.unit.databases.push(name);
-          else if (filename.endsWith(".Util.tsx")) files.util.databases.push(name);
-          else if (filename.endsWith(".View.tsx")) files.view.databases.push(name);
-          else if (filename.endsWith(".Zone.tsx")) files.zone.databases.push(name);
-        });
-      }),
-      ...serviceDirs.map(async (dirname) => {
-        const name = dirname.slice(1);
-        const filenames = await exec.readdir(path.join("lib", dirname));
-        filenames.forEach((filename) => {
-          if (filename.endsWith(".dictionary.ts")) files.dictionary.services.push(name);
-          else if (filename.endsWith(".service.ts")) files.service.services.push(name);
-          else if (filename.endsWith(".signal.ts")) files.signal.services.push(name);
-          else if (filename.endsWith(".store.ts")) files.store.services.push(name);
-          else if (filename.endsWith(".Template.tsx")) files.template.services.push(name);
-          else if (filename.endsWith(".Unit.tsx")) files.unit.services.push(name);
-          else if (filename.endsWith(".Util.tsx")) files.util.services.push(name);
-          else if (filename.endsWith(".View.tsx")) files.view.services.push(name);
-          else if (filename.endsWith(".Zone.tsx")) files.zone.services.push(name);
-        });
-      }),
-      ...scalarDirs.map(async (name) => {
-        const filenames = await exec.readdir(path.join("lib/__scalar", name));
-        filenames.forEach((filename) => {
-          if (filename.endsWith(".constant.ts")) files.constant.scalars.push(name);
-          else if (filename.endsWith(".dictionary.ts")) files.dictionary.scalars.push(name);
-          else if (filename.endsWith(".document.ts")) files.document.scalars.push(name);
-          else if (filename.endsWith(".Template.tsx")) files.template.scalars.push(name);
-          else if (filename.endsWith(".Unit.tsx")) files.unit.scalars.push(name);
-          else if (filename.endsWith(".Util.tsx")) files.util.scalars.push(name);
-          else if (filename.endsWith(".View.tsx")) files.view.scalars.push(name);
-          else if (filename.endsWith(".Zone.tsx")) files.zone.scalars.push(name);
-        });
-      }),
+      ...databaseDirs.map((name) => collect(path.join("lib", name), name, "databases")),
+      ...serviceDirs.map((dirname) => collect(path.join("lib", dirname), dirname.slice(1), "services")),
+      ...scalarDirs.map((name) => collect(path.join("lib/__scalar", name), name, "scalars")),
     ]);
     const routes = exec.type === "lib" ? [] : await (exec as AppExecutor).getPageKeys();
     const common = {
@@ -309,35 +232,16 @@ class ScanInfo {
   constructor(scanResult: ScanResult) {
     this.name = scanResult.name;
     this.scanResult = scanResult;
-    Object.entries(scanResult.files).forEach(([_key, value]) => {
-      const key = _key as DatabaseFileType;
-      const { databases, services, scalars } = value as {
-        databases: string[];
-        services?: string[];
-        scalars?: string[];
-      };
-      databases.forEach((modelName) => {
-        const model = this.database.get(modelName) ?? new Set<DatabaseFileType>();
-        model.add(key);
-        this.database.set(modelName, model);
-        this.file[key].all.add(modelName);
-        this.file[key].databases.add(modelName);
-      });
-      services?.forEach((serviceName) => {
-        const service = this.service.get(serviceName) ?? new Set<ServiceFileType>();
-        service.add(key as ServiceFileType);
-        this.service.set(serviceName, service);
-        this.file[key].all.add(serviceName);
-        this.file[key].services.add(serviceName);
-      });
-      scalars?.forEach((scalarName) => {
-        const scalar = this.scalar.get(scalarName) ?? new Set<ScalarFileType>();
-        scalar.add(key as ScalarFileType);
-        this.scalar.set(scalarName, scalar);
-        this.file[key].all.add(scalarName);
-        this.file[key].scalars.add(scalarName);
-      });
-    });
+    const modulesOf = { databases: this.database, services: this.service, scalars: this.scalar } as {
+      [key in "databases" | "services" | "scalars"]: Map<string, Set<DatabaseFileType>>;
+    };
+    for (const [key, groups] of Object.entries(scanResult.files) as [DatabaseFileType, { [kind: string]: string[] }][])
+      for (const kind of ["databases", "services", "scalars"] as const)
+        for (const name of groups[kind] ?? []) {
+          modulesOf[kind].set(name, (modulesOf[kind].get(name) ?? new Set()).add(key));
+          this.file[key].all.add(name);
+          this.file[key][kind].add(name);
+        }
   }
   getScanResult() {
     return this.scanResult;
@@ -351,6 +255,29 @@ class ScanInfo {
   getScalarModules() {
     return [...this.scalar.keys()];
   }
+
+  #sortedLibs: string[] | null = null;
+  protected sortedLibs(libDeps: string[]) {
+    if (this.#sortedLibs) return this.#sortedLibs;
+    const libIndices = LibInfo.getSortedLibIndices();
+    this.#sortedLibs = libDeps.sort((libNameA, libNameB) => {
+      const indexA = libIndices.get(libNameA);
+      const indexB = libIndices.get(libNameB);
+      if (indexA === undefined || indexB === undefined)
+        throw new Error(`LibInfo not found: ${libNameA} or ${libNameB}`);
+      return indexA - indexB;
+    });
+    return this.#sortedLibs;
+  }
+  protected sortedLibInfos(libDeps: string[]) {
+    return new Map(
+      this.sortedLibs(libDeps).map((libName) => {
+        const libInfo = LibInfo.libInfos.get(libName);
+        if (!libInfo) throw new Error(`LibInfo not found: ${libName}`);
+        return [libName, libInfo];
+      }),
+    );
+  }
 }
 
 const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
@@ -362,7 +289,6 @@ export class AppInfo extends ScanInfo {
 
   static appInfos = new Map<string, AppInfo>();
   static async fromExecutor(exec: AppExecutor, options: { refresh?: boolean } = {}) {
-    // cache check
     const existingAppInfo = AppInfo.appInfos.get(exec.name);
     if (existingAppInfo && !options.refresh) return existingAppInfo;
     const scanResult = await ScanInfo.getScanResult(exec);
@@ -408,30 +334,11 @@ export class AppInfo extends ScanInfo {
     return [...libSet];
   }
 
-  #sortedLibs: string[] | null = null;
-  #getSortedLibs() {
-    if (this.#sortedLibs) return this.#sortedLibs;
-    const libIndices = LibInfo.getSortedLibIndices();
-    this.#sortedLibs = this.libDeps.sort((libNameA, libNameB) => {
-      const indexA = libIndices.get(libNameA);
-      const indexB = libIndices.get(libNameB);
-      if (indexA === undefined || indexB === undefined)
-        throw new Error(`LibInfo not found: ${libNameA} or ${libNameB}`);
-      return indexA - indexB;
-    });
-    return this.#sortedLibs;
-  }
   getLibs() {
-    return this.#getSortedLibs();
+    return this.sortedLibs(this.libDeps);
   }
   getLibInfos() {
-    return new Map(
-      this.#getSortedLibs().map((libName) => {
-        const libInfo = LibInfo.libInfos.get(libName);
-        if (!libInfo) throw new Error(`LibInfo not found: ${libName}`);
-        return [libName, libInfo];
-      }),
-    );
+    return this.sortedLibInfos(this.libDeps);
   }
 }
 export class LibInfo extends ScanInfo {
@@ -482,36 +389,16 @@ export class LibInfo extends ScanInfo {
     return this.scanResult as LibScanResult;
   }
 
-  #sortedLibs: string[] | null = null;
-  #getSortedLibs() {
-    if (this.#sortedLibs) return this.#sortedLibs;
-    const libs = LibInfo.getSortedLibIndices();
-    this.#sortedLibs = this.scanResult.libDeps.sort((libNameA, libNameB) => {
-      const indexA = libs.get(libNameA);
-      const indexB = libs.get(libNameB);
-      if (indexA === undefined || indexB === undefined)
-        throw new Error(`LibInfo not found: ${libNameA} or ${libNameB}`);
-      return indexA - indexB;
-    });
-    return this.#sortedLibs;
-  }
   getLibs() {
-    return this.#getSortedLibs();
+    return this.sortedLibs(this.scanResult.libDeps);
   }
   getLibInfo(libName: string) {
     if (!this.getScanResult().libDeps.includes(libName)) return undefined;
-    const libSet = new Set(this.#getSortedLibs());
-    if (!libSet.has(libName)) throw new Error(`LibInfo is invalid: ${libName}`);
+    if (!this.getLibs().includes(libName)) throw new Error(`LibInfo is invalid: ${libName}`);
     return LibInfo.libInfos.get(libName);
   }
   getLibInfos() {
-    return new Map(
-      this.#getSortedLibs().map((libName) => {
-        const libInfo = LibInfo.libInfos.get(libName);
-        if (!libInfo) throw new Error(`LibInfo not found: ${libName}`);
-        return [libName, libInfo];
-      }),
-    );
+    return this.sortedLibInfos(this.scanResult.libDeps);
   }
 }
 
@@ -524,27 +411,25 @@ export class PkgInfo {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
     const scanner = await createDependencyScanner(exec);
     const npmSet = new Set(Object.keys({ ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies }));
+    const workspacePathOf = (resolve: string) => resolve.replace(/^\.\//, "");
     const pkgPathSet = new Set(
       Object.keys(tsconfig.compilerOptions.paths ?? {})
-        .filter((path) => tsconfig.compilerOptions.paths?.[path]?.some((resolve) => resolve.startsWith("pkgs/")))
+        .filter((path) =>
+          tsconfig.compilerOptions.paths?.[path]?.some((resolve) => workspacePathOf(resolve).startsWith("pkgs/")),
+        )
         .map((path) => path.replace("/*", "")),
     );
     const [npmDepSet, pkgPathDepSet] = await scanner.getImportSets([npmSet, pkgPathSet]);
     const pkgDeps = [...pkgPathDepSet]
       .map((path) => {
         const pathSplitLength = path.split("/").length;
-        return (tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
+        return workspacePathOf(tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
           .split("/")
           .slice(1, 1 + pathSplitLength)
           .join("/");
       })
       .filter((pkg) => pkg !== exec.name);
-    const pkgScanResult = {
-      name: exec.name,
-      pkgDeps,
-      dependencies: [...npmDepSet],
-    };
-    return pkgScanResult;
+    return { name: exec.name, pkgDeps, dependencies: [...npmDepSet] };
   }
 
   static #pkgInfos = new Map<string, PkgInfo>();
@@ -582,23 +467,9 @@ export class WorkspaceInfo {
     const [appNames, libNames, pkgNames] = await Promise.all([exec.getApps(), exec.getLibs(), exec.getPkgs()]);
     // TODO: prevent duplicate scan by resolving the dependency graph
     const [appInfos, libInfos, pkgInfos] = await Promise.all([
-      Promise.all(
-        appNames.map(async (appName) => {
-          const app = AppExecutor.from(exec, appName);
-          return await app.scan();
-        }),
-      ),
-      Promise.all(
-        libNames.map(async (libName) => {
-          const lib = LibExecutor.from(exec, libName);
-          return await lib.scan();
-        }),
-      ),
-      Promise.all(
-        pkgNames.map(async (pkgName) => {
-          return await PkgExecutor.from(exec, pkgName).scan();
-        }),
-      ),
+      Promise.all(appNames.map(async (appName) => await AppExecutor.from(exec, appName).scan())),
+      Promise.all(libNames.map(async (libName) => await LibExecutor.from(exec, libName).scan())),
+      Promise.all(pkgNames.map(async (pkgName) => await PkgExecutor.from(exec, pkgName).scan())),
     ]);
     const workspaceInfo = new WorkspaceInfo(
       new Map(appInfos.map((app) => [app.exec.name, app as AppInfo])),

package/selectModel.ts

@@ -3,9 +3,8 @@ import { select } from "@inquirer/prompts";
 
 export const selectModel = async (modulePath: string) => {
   const modelNames = readdirSync(`${modulePath}/lib`).filter((dir) => !dir.includes(".") && !dir.startsWith("_"));
-  const modelName = await select({
+  return await select({
     message: "Select the model to create the unit for",
     choices: modelNames.map((name) => ({ name, value: name })),
   });
-  return modelName;
 };

package/semver.ts

@@ -1,14 +1,12 @@
-// `Bun.semver.order` compares range strings loosely — `^3.1049.0` vs `^3.721.0` answers 0 — so the
-// operator prefix has to come off before it sees the version.
+// `Bun.semver.order` compares ranges loosely (`^3.1049.0` vs `^3.721.0` answers 0), so the operator comes off first.
 const stripRangeOperator = (version: string) => version.replace(/^[\s^~>=<v]+/, "").trim();
 
-const parseVersion = (version: string): number[] => {
-  return version
+const parseVersion = (version: string): number[] =>
+  version
     .replace(/^[^\d]*/, "")
     .split(/[.-]/)
     .map((part) => Number.parseInt(part, 10))
     .map((part) => (Number.isFinite(part) ? part : 0));
-};
 
 const compareNumeric = (a: string, b: string): number => {
   const left = parseVersion(a);

package/slicePlanner.test.ts

@@ -1,30 +1,13 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { AppExecutor, Executor, WorkspaceExecutor } from "./executors";
 import { formatSlicePlan, SlicePlanner } from "./slicePlanner";
+import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 import type { PackageJson } from "./types";
 
-const tempRoots: string[] = [];
-const originalEnv = { ...process.env };
-
-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-slice-");
 
 const gitignore = [
   "node_modules",
@@ -36,8 +19,7 @@ const gitignore = [
 
 // `AppExecutor.from` and `AppInfo.fromExecutor` both memoise by name, so each fixture needs a fresh one.
 const makeWorkspace = async (appName: string, libName: string) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-slice-"));
-  tempRoots.push(root);
+  const root = await makeTempRoot();
   const rootPackageJson: PackageJson = {
     name: "workspace",
     version: "0.0.1",

package/slicePlanner.ts

@@ -18,12 +18,6 @@ export interface SlicePlan {
   warnings: string[];
 }
 
-/**
- * The exact file set a single app needs to live in a workspace of its own: the app, its transitive lib
- * closure, the workspace shell around them, and a root manifest for the result.
- *
- * Consumed by `akan plan-slice`, and by anything that moves an app or a lib between workspaces.
- */
 export class SlicePlanner {
   /** Root entries owned by an app, a lib or an in-tree package rather than by the workspace shell. */
   static readonly memberDirs = ["apps", "libs", "pkgs"];
@@ -39,13 +33,8 @@ export class SlicePlanner {
   ];
   static readonly akanPackages = ["akanjs", "@akanjs/devkit", "@akanjs/cli"];
 
-  /**
-   * What the framework imports but does not install, so a workspace root has to declare it: `react`,
-   * `scheduler` and the RSC runtime, but also `ioredis`, `postgres` and `bullmq` the moment an app uses
-   * a database or a queue. No source file in the workspace names any of them, so no scan can find them
-   * — they are the akan packages' own `peerDependencies`, read wherever those are installed. Anything
-   * they declare as a plain dependency is installed with them and needs no root entry.
-   */
+  // The akan packages' peerDependencies (react, the RSC runtime, ioredis, postgres, bullmq): the framework imports
+  // them but no workspace source names them, so no scan can find them.
   static async #frameworkPeers(workspace: WorkspaceExecutor) {
     const peers = new Set<string>();
     let found = false;
@@ -67,14 +56,8 @@ export class SlicePlanner {
     return dependency.startsWith("@") ? `@types/${dependency.slice(1).replace("/", "__")}` : `@types/${dependency}`;
   }
 
-  /**
-   * The root manifest a workspace holding only these dependencies would carry, with the workspace's own
-   * version specs kept — that is what makes one branch resolve to one dependency tree everywhere.
-   *
-   * A `@types/x` package is kept alongside `x`: nothing imports it by name, so no scan can see it, and
-   * dropping it breaks the typecheck of every file that imports `x`. `workspaces` is dropped because it
-   * names in-tree packages, which a slice never carries — it consumes akanjs from the registry.
-   */
+  // `@types/x` is kept alongside `x` since nothing imports it by name; `workspaces` is dropped because a slice
+  // consumes akanjs from the registry.
   static async pruneDependencies(
     workspace: WorkspaceExecutor,
     rootPackageJson: PackageJson,
@@ -82,9 +65,8 @@ export class SlicePlanner {
   ) {
     const peers = await SlicePlanner.#frameworkPeers(workspace);
     const { workspaces: _workspaces, ...rest } = rootPackageJson;
-    //* Without akanjs's peer list every peer looks unused, and pruning it produces an install that
-    //* succeeds and a server that fails at its first redis or postgres call. Carry the dependencies
-    //* whole instead and say why.
+    //* Without the peer list every peer looks unused, and pruning it breaks the server at its first redis or
+    //* postgres call.
     if (!peers)
       return {
         packageJson: rest as PackageJson,
@@ -121,10 +103,6 @@ export class SlicePlanner {
     this.#app = app;
   }
 
-  async #trackedFiles(paths: string[]) {
-    return await this.#app.workspace.listGitFiles(paths);
-  }
-
   async #untrackedFiles(paths: string[]) {
     const [tracked, all] = await Promise.all([
       this.#app.workspace.listGitFiles(paths),
@@ -170,14 +148,16 @@ export class SlicePlanner {
     const slicePaths = [`apps/${this.#app.name}`, ...libs.map((lib) => `libs/${lib}`)];
 
     const [appFiles, allTracked, untracked, rootPackageJson] = await Promise.all([
-      this.#trackedFiles([`apps/${this.#app.name}`]),
-      this.#trackedFiles(["."]),
+      this.#app.workspace.listGitFiles([`apps/${this.#app.name}`]),
+      this.#app.workspace.listGitFiles(["."]),
       this.#untrackedFiles(slicePaths),
       this.#app.workspace.getPackageJson(),
     ]);
 
     const libFiles = Object.fromEntries(
-      await Promise.all(libs.map(async (lib) => [lib, await this.#trackedFiles([`libs/${lib}`])] as const)),
+      await Promise.all(
+        libs.map(async (lib) => [lib, await this.#app.workspace.listGitFiles([`libs/${lib}`])] as const),
+      ),
     );
     const rootFiles = allTracked.filter((file) => !this.#isMemberFile(file));
 
@@ -211,7 +191,6 @@ export class SlicePlanner {
   }
 }
 
-/** Top-level entry each path sits under, so a long tree (`infra/**`) reads as one line. */
 const rootEntriesOf = (rootFiles: string[]) => [...new Set(rootFiles.map((file) => file.split("/")[0] ?? file))].sort();
 
 export function formatSlicePlan(plan: SlicePlan) {

package/spinner.test.ts

@@ -6,10 +6,7 @@ interface TtyStub {
   rawModeCalls: boolean[];
 }
 
-/**
- * ora only reaches for stdin when both streams look interactive, so the stub has to fake a tty on
- * stderr (which decides `isEnabled`) as well as on stdin.
- */
+// ora only reaches for stdin when both streams look interactive, so stderr (which decides `isEnabled`) is faked too.
 const stubTty = (): TtyStub => {
   const rawModeCalls: boolean[] = [];
   const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => unknown };
@@ -41,8 +38,7 @@ const stubTty = (): TtyStub => {
 };
 
 describe("Spinner", () => {
-  // A raw terminal at spawn time is what a Bun child snapshots and writes back when it exits, which is
-  // how `akan start` used to leave a terminal that no longer turns Ctrl+C into SIGINT.
+  // A Bun child snapshots a raw terminal at spawn and writes it back on exit, leaving Ctrl+C no longer a SIGINT.
   test("never puts the terminal into raw mode while it spins", () => {
     const tty = stubTty();
     try {
@@ -59,8 +55,7 @@ describe("Spinner", () => {
     expect(Spinner.oraOptions.discardStdin).toBe(false);
   });
 
-  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an
-  // infinite one — the process then writes cursor moves until it is SIGKILLed.
+  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an infinite one.
   test("refuses to animate against a tty that reports no width", () => {
     expect(Spinner.canAnimate({ isTTY: true, columns: 0 } as NodeJS.WriteStream)).toBe(false);
     expect(Spinner.canAnimate({ isTTY: true, columns: 120 } as NodeJS.WriteStream)).toBe(true);

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;
   }