@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.91

package/qualityScanner.ts

@@ -5,11 +5,12 @@ import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
+import { FormSetterScanner } from "./formSetterScanner";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
 
 export interface QualityWarning {
   rule: string;
@@ -88,7 +89,8 @@ const SUGGESTED_RULES = [
   "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
   "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
   "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
-  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
+  "Move shared app and lib utilities to common/ instead of creating apps/*/base or libs/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
@@ -115,6 +117,8 @@ const RULE_FIXES: Record<string, string> = {
     "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.bang-comment-in-client":
+    "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
   "akan.file.global-declaration":
     "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
@@ -122,14 +126,22 @@ const RULE_FIXES: Record<string, string> = {
     "Move the Window augmentation into an approved browser integration file and keep it isolated.",
   "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
   "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.agent.unpublished-form-setter":
+    "Pass the setter by reference where the wrapper only forwards (onChange={st.do.setTitleOnTask}); move normalization into the control's own transform prop; move a multi-write into a _postSet<Field> hook on the store, keeping the generated setter on the control.",
   "akan.file.component-internal-declaration":
     "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
   "akan.file.component-export":
     "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix — only PascalCase components and their `<Component>Props` interface belong here.",
   "akan.layout.app-root-file":
     "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.app-root-folder":
+    "Move the folder's contents into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-root-file":
-    "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+    "Move the file into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-folder":
+    "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-facet-file":
+    "Move the file into a domain module folder under lib/; keep the lib facet root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
   "akan.ssr.unnecessary-use-client":
@@ -173,6 +185,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...new FormSetterScanner().scan(sourceFiles),
       ...ssr.warnings,
     ];
 
@@ -303,6 +316,7 @@ export class AkanQualityScanner {
       });
     }
 
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -408,26 +422,31 @@ export class AkanQualityScanner {
   }
 
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
-    const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
-      warnings.push({
-        rule: "akan.layout.app-root-file",
-        scope: "layout",
-        severity: "warning",
-        file: sourceFile.file,
-        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`,
-      });
+    const rootEntry = getSysRootEntry(sourceFile.file);
+    if (rootEntry) {
+      const { type, name, isDir } = rootEntry;
+      const allowed = isDir ? rootAllowedDirs[type].has(name) : rootAllowedFiles[type].has(name);
+      const kind = isDir ? "folder" : "file";
+      if (!allowed) {
+        warnings.push({
+          rule: `akan.layout.${type}-root-${kind}`,
+          scope: "layout",
+          severity: "warning",
+          file: sourceFile.file,
+          message: `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`,
+        });
+      }
     }
 
-    const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
+    const libFacetFile = getLibFacetRootFile(sourceFile.file);
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
       warnings.push({
-        rule: "akan.layout.lib-root-file",
+        rule: "akan.layout.lib-facet-file",
         scope: "layout",
         severity: "warning",
         file: sourceFile.file,
-        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`,
+        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`,
       });
     }
 
@@ -580,9 +599,10 @@ function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement
 
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
-    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
+    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement))
     .filter((statement) => isExported(statement))
-    .map((statement) => statement.name!.text);
+    .map((statement) => statement.name?.text)
+    .filter((name): name is string => !!name);
 }
 
 function isComponentDeclarationFile(file: string) {
@@ -662,7 +682,43 @@ function isPascalCaseName(name: string) {
 
 function isDefaultExportStatement(statement: ts.Statement) {
   if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
-  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+  if (!ts.canHaveModifiers(statement)) return false;
+  return !!ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+}
+
+/**
+ * Bun's bundler keeps `//!` and `/*!` through minification (it reads them as the `@license` class), so a
+ * bang marker in browser-reachable code ships verbatim to every visitor. `no-bang-comment-in-client.grit`
+ * is the build gate; this exists because that rule cannot see the whole file.
+ *
+ * A comment is trivia, which Biome's GritQL exposes to no node pattern, so the rule matches through
+ * `file($name, $body)` — and `$body` is the module's *token* span. A marker above the first statement or
+ * below the last one sits in leading or trailing trivia and is unreachable from GritQL at all. Reading the
+ * raw text here covers both, and re-reporting the markers grit already catches costs nothing: the two run
+ * from different commands, and a file with one is failing lint either way.
+ */
+function getBangCommentWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  if (!isClientReachableFile(sourceFile.file)) return [];
+  // Anchored to line start or to whitespace after code, so a literal like `"https://host//!path"` is not a hit.
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
+    rule: "akan.file.bang-comment-in-client",
+    scope: "file" as const,
+    severity: "warning" as const,
+    file: sourceFile.file,
+    line,
+    message: "A `//!` or `/*!` marker survives minification and ships to the browser.",
+  }));
+}
+
+/** Mirrors the path scope of `no-bang-comment-in-client.grit` in `biome.base.json`. */
+function isClientReachableFile(file: string) {
+  if (/\.(test|spec)\.tsx?$/.test(file)) return false;
+  if (/\.(constant|store)\.ts$/.test(file)) return true;
+  if (/\.(Template|Unit|Util|View|Zone)\.tsx$/.test(file)) return true;
+  const segments = file.split("/");
+  if (segments.includes("ui") || segments.includes("webkit")) return /\.tsx?$/.test(file);
+  if (segments.includes("common")) return file.endsWith(".ts");
+  return segments.includes("page") && file.endsWith(".tsx");
 }
 
 function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
@@ -821,7 +877,19 @@ function getConventionDescription(suffix: (typeof CONVENTION_SUFFIXES)[number],
   return `${modelName}Store`;
 }
 
-function getLibRootFile(file: string) {
+const sysRootTypes = { apps: "app", libs: "lib" } as const;
+
+function getSysRootEntry(file: string) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3) return null;
+  const type = sysRootTypes[root as keyof typeof sysRootTypes];
+  if (!type) return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+
+function getLibFacetRootFile(file: string) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];

package/recipeScanner.ts

@@ -118,7 +118,10 @@ const extractVariants = (config: ts.ObjectLiteralExpression) => {
         if (!ts.isPropertyAssignment(variant) || !isNamed(variant.name)) continue;
         if (!ts.isObjectLiteralExpression(variant.initializer)) continue;
         variants[propName(variant.name)] = variant.initializer.properties
-          .filter((option): option is ts.PropertyAssignment => ts.isPropertyAssignment(option) && isNamed(option.name))
+          .filter(
+            (option): option is ts.PropertyAssignment & { name: ts.Identifier | ts.StringLiteral } =>
+              ts.isPropertyAssignment(option) && isNamed(option.name),
+          )
           .map((option) => propName(option.name));
       }
     } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {

package/scanInfo.ts

@@ -9,9 +9,9 @@ import type {
   PkgScanResult,
   ScanResult,
 } from "./akanConfig";
-
+import { AkanAppConfig } from "./akanConfig";
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
-import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -57,7 +57,6 @@ const moduleUiFileTypes = {
   scalar: new Set(["Template", "Unit"]),
 } satisfies Record<ModuleKind, Set<string>>;
 const testFilePattern = /\.(test|spec)\.(ts|tsx)$/;
-const rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(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.
@@ -65,8 +64,6 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
   (await import("./dependencyScanner")).TypeScriptDependencyScanner.from(exec);
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
-const isAllowedLibRootFile = (filename: string) =>
-  libFacetRootAllowedFiles.has(filename) || rootSignalTestFilePattern.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,24 +82,29 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);
   };
 
-  if (exec.type === "app") {
-    const { files, dirs } = await exec.getFilesAndDirs(".");
-    files
-      .filter((filename) => !appRootAllowedFiles.has(filename))
-      .forEach((filename) => {
-        addViolation(filename, "unsupported app root file");
-      });
-    dirs
-      .filter((dirname) => !appRootAllowedDirs.has(dirname))
-      .forEach((dirname) => {
-        addViolation(dirname, "unsupported app root folder");
-      });
-  }
+  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`);
+    });
+
+  //* 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.
+  if (exec.type === "lib")
+    for (const { relativePath, reason } of await exec.getPageConventionViolations()) addViolation(relativePath, reason);
 
   libRoot.files
-    .filter((filename) => !isAllowedLibRootFile(filename))
+    .filter((filename) => !isAllowedLibFacetRootFile(filename))
     .forEach((filename) => {
-      addViolation(path.join("lib", filename), "unsupported lib root file");
+      addViolation(path.join("lib", filename), "unsupported lib facet root file");
     });
 
   libRoot.dirs
@@ -284,12 +286,11 @@ class ScanInfo {
       }),
     ]);
     const routes = exec.type === "lib" ? [] : await (exec as AppExecutor).getPageKeys();
-    const scanResult: AppScanResult | LibScanResult = {
+    const common = {
       name: exec.name,
       type: exec.type,
       repoName: exec.workspace.repoName,
       serveDomain: WorkspaceExecutor.getBaseDevEnv(path.join(exec.workspace.workspaceRoot, ".env")).serveDomain,
-      akanConfig,
       files,
       libDeps,
       pkgDeps,
@@ -297,6 +298,11 @@ class ScanInfo {
       devDependencies: npmDevDeps.filter((dep) => !isAkanFrameworkDependency(dep)),
       routes,
     };
+    //? `exec.type` and the resolved config class are correlated, which the union alone cannot express.
+    const scanResult: AppScanResult | LibScanResult =
+      akanConfig instanceof AkanAppConfig
+        ? ({ ...common, akanConfig } satisfies AppScanResult)
+        : ({ ...common, akanConfig } satisfies LibScanResult);
     return scanResult;
   }
 
@@ -461,7 +467,7 @@ export class LibInfo extends ScanInfo {
           LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
         }),
     );
-    const libInfo = new LibInfo(exec, scanResult);
+    const libInfo = new LibInfo(exec, scanResult as LibScanResult);
     LibInfo.libInfos.set(exec.name, libInfo);
     LibInfo.#sortedLibIndices = null;
     return libInfo;
@@ -512,7 +518,7 @@ export class LibInfo extends ScanInfo {
 export class PkgInfo {
   readonly exec: PkgExecutor;
   readonly name: string;
-  private scanResult: PkgScanResult;
+  #scanResult: PkgScanResult;
 
   static async scanExecutor(exec: PkgExecutor) {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
@@ -554,10 +560,10 @@ export class PkgInfo {
   constructor(exec: PkgExecutor, scanResult: PkgScanResult) {
     this.exec = exec;
     this.name = exec.name;
-    this.scanResult = scanResult;
+    this.#scanResult = scanResult;
   }
   getScanResult() {
-    return this.scanResult;
+    return this.#scanResult;
   }
 }
 

package/semver.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { compareSemver } from "./semver";
+
+describe("compareSemver", () => {
+  test("orders plain versions", () => {
+    expect(compareSemver("1.4.0", "1.3.13")).toBe(1);
+    expect(compareSemver("1.3.13", "1.4.0")).toBe(-1);
+    expect(compareSemver("19.2.7", "19.2.7")).toBe(0);
+  });
+
+  test("compares the version behind a range operator, not the range", () => {
+    expect(compareSemver("^3.1049.0", "^3.721.0")).toBe(1);
+    expect(compareSemver("~1.2.0", "^1.10.0")).toBe(-1);
+    expect(compareSemver(">=1.3.13", "1.4.0")).toBe(-1);
+  });
+
+  test("sorts a prerelease below its release", () => {
+    expect(compareSemver("1.0.0-alpha", "1.0.0")).toBe(-1);
+    expect(compareSemver("0.0.0-experimental-603e6108-20241029", "0.0.0")).toBe(-1);
+  });
+
+  test("falls back to numeric comparison for specs that are not versions", () => {
+    expect(compareSemver("workspace:*", "0.0.0")).toBe(0);
+    expect(compareSemver("workspace:*", "1.0.0")).toBe(-1);
+  });
+});

package/semver.ts

@@ -0,0 +1,31 @@
+// `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.
+const stripRangeOperator = (version: string) => version.replace(/^[\s^~>=<v]+/, "").trim();
+
+const parseVersion = (version: string): number[] => {
+  return 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);
+  const right = parseVersion(b);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+};
+
+export const compareSemver = (a: string, b: string): number => {
+  try {
+    return Bun.semver.order(stripRangeOperator(a), stripRangeOperator(b));
+  } catch {
+    // Not every dependency spec is a version — `workspace:*`, a git URL, a tarball path.
+    return compareNumeric(a, b);
+  }
+};

package/slicePlanner.test.ts

@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AppExecutor, Executor, WorkspaceExecutor } from "./executors";
+import { formatSlicePlan, SlicePlanner } from "./slicePlanner";
+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);
+};
+
+const gitignore = [
+  "node_modules",
+  "apps/*/lib/cnst.ts",
+  "libs/*/common/index.ts",
+  "**/env.server.local.ts",
+  "**/akan.app.json",
+].join("\n");
+
+// `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 rootPackageJson: PackageJson = {
+    name: "workspace",
+    version: "0.0.1",
+    description: "workspace",
+    workspaces: ["pkgs/*"],
+    dependencies: { lodash: "4.0.0", "unused-dep": "1.0.0", ioredis: "5.0.0" },
+    devDependencies: { typescript: "6.0.0", "@types/lodash": "4.1.0", "@types/qrcode": "1.0.0" },
+    patchedDependencies: {
+      "lodash@4.0.0": "patches/lodash@4.0.0.patch",
+      "unused-dep@1.0.0": "patches/unused-dep@1.0.0.patch",
+    },
+  };
+  await write(path.join(root, "package.json"), `${JSON.stringify(rootPackageJson, null, 2)}\n`);
+  await write(path.join(root, ".gitignore"), `${gitignore}\n`);
+  await write(path.join(root, "biome.json"), "{}\n");
+  //? The framework's peers are declared by akanjs, not by any import, so the planner reads them here.
+  await write(
+    path.join(root, "node_modules/akanjs/package.json"),
+    '{ "name": "akanjs", "version": "3.0.0", "peerDependencies": { "react": "19.0.0", "ioredis": "5.0.0" } }\n',
+  );
+  await write(path.join(root, "patches/lodash@4.0.0.patch"), "");
+  await write(path.join(root, "patches/unused-dep@1.0.0.patch"), "");
+
+  await write(path.join(root, `apps/${appName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `apps/${appName}/tsconfig.json`), "{}\n");
+  await write(
+    path.join(root, `apps/${appName}/lib/task/task.constant.ts`),
+    [
+      `import { helper } from "@libs/${libName}/common";`,
+      'import lodash from "lodash";',
+      "",
+      "export { helper, lodash };",
+      "",
+    ].join("\n"),
+  );
+  await write(path.join(root, `apps/${appName}/lib/cnst.ts`), "export {};\n");
+  await write(path.join(root, `apps/${appName}/env/env.server.local.ts`), "export const env = {};\n");
+
+  await write(path.join(root, `libs/${libName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `libs/${libName}/tsconfig.json`), "{}\n");
+  await mkdir(path.join(root, `libs/${libName}/lib`), { recursive: true });
+  await write(path.join(root, `libs/${libName}/common/helper.ts`), "export const helper = 1;\n");
+  await write(path.join(root, `libs/${libName}/common/index.ts`), 'export * from "./helper";\n');
+
+  await write(path.join(root, "pkgs/in-tree/package.json"), '{ "name": "in-tree" }\n');
+
+  const git = new Executor("fixture", root);
+  await git.spawn("git", ["init", "--quiet"]);
+  await git.spawn("git", ["add", "-A"]);
+  await git.spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "--quiet", "-m", "fixture"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `workspace-${appName}` });
+  return { root, plan: async () => await new SlicePlanner(AppExecutor.from(workspace, appName)).plan() };
+};
+
+describe("SlicePlanner", () => {
+  test("resolves the lib closure and lists only git-tracked slice files", async () => {
+    const { plan } = await makeWorkspace("slice-app", "slice-lib");
+    const result = await plan();
+
+    expect(result.app).toBe("slice-app");
+    expect(result.libs).toEqual(["slice-lib"]);
+    expect(result.appFiles).toContain("apps/slice-app/lib/task/task.constant.ts");
+    expect(result.libFiles["slice-lib"]).toContain("libs/slice-lib/common/helper.ts");
+  });
+
+  test("leaves out generated barrels, env values and every other workspace member", async () => {
+    const { plan } = await makeWorkspace("ignore-app", "ignore-lib");
+    const result = await plan();
+
+    expect(result.appFiles).not.toContain("apps/ignore-app/lib/cnst.ts");
+    expect(result.appFiles).not.toContain("apps/ignore-app/env/env.server.local.ts");
+    expect(result.libFiles["ignore-lib"]).not.toContain("libs/ignore-lib/common/index.ts");
+    expect(result.rootFiles).toEqual(expect.arrayContaining(["package.json", ".gitignore", "biome.json"]));
+    expect(result.rootFiles.filter((file) => file.startsWith("pkgs/"))).toEqual([]);
+    expect(result.rootFiles.filter((file) => /^(apps|libs)\//.test(file))).toEqual([]);
+  });
+
+  test("drops `workspaces` from the slice manifest and reports it", async () => {
+    const { plan } = await makeWorkspace("manifest-app", "manifest-lib");
+    const result = await plan();
+
+    expect(result.packageJson.workspaces).toBeUndefined();
+    expect(result.warnings.join("\n")).toContain("workspaces");
+  });
+
+  test("prunes what the slice does not import, keeping the toolchain and the type packages", async () => {
+    const { plan } = await makeWorkspace("deps-app", "deps-lib");
+    const result = await plan();
+
+    expect(result.requiredDependencies).toContain("lodash");
+    //? `ioredis` is an akanjs peer: nothing imports it, and pruning it would break the server at runtime.
+    expect(result.packageJson.dependencies).toEqual({ lodash: "4.0.0", ioredis: "5.0.0" });
+    //? Nothing imports `@types/lodash` by name, so only its companion keeps it.
+    expect(result.packageJson.devDependencies).toEqual({ typescript: "6.0.0", "@types/lodash": "4.1.0" });
+    expect(result.packageJson.patchedDependencies).toEqual({ "lodash@4.0.0": "patches/lodash@4.0.0.patch" });
+    expect(result.unusedDependencies).toEqual(["@types/qrcode", "unused-dep"]);
+  });
+
+  test("carries the dependencies whole when there is no akanjs manifest to read the peers from", async () => {
+    const { root, plan } = await makeWorkspace("nopeer-app", "nopeer-lib");
+    await rm(path.join(root, "node_modules"), { recursive: true, force: true });
+    const result = await plan();
+
+    expect(result.unusedDependencies).toEqual([]);
+    expect(result.packageJson.dependencies).toEqual({ lodash: "4.0.0", "unused-dep": "1.0.0", ioredis: "5.0.0" });
+    expect(result.warnings.join("\n")).toContain("carried whole");
+  });
+
+  test("names a type package the way DefinitelyTyped does", () => {
+    expect(SlicePlanner.typesPackageOf("lodash")).toBe("@types/lodash");
+    expect(SlicePlanner.typesPackageOf("@capacitor/core")).toBe("@types/capacitor__core");
+  });
+
+  test("warns about untracked files under the slice paths", async () => {
+    const { root, plan } = await makeWorkspace("untracked-app", "untracked-lib");
+    await write(path.join(root, "apps/untracked-app/lib/task/task.service.ts"), "export {};\n");
+    const result = await plan();
+
+    expect(result.warnings.join("\n")).toContain("apps/untracked-app/lib/task/task.service.ts");
+  });
+});
+
+describe("formatSlicePlan", () => {
+  test("collapses the workspace shell to its top-level entries", () => {
+    const text = formatSlicePlan({
+      app: "demo",
+      libs: ["util"],
+      appFiles: ["apps/demo/main.ts"],
+      libFiles: { util: ["libs/util/index.ts"] },
+      rootFiles: ["package.json", "infra/app/values/main.yaml", "infra/app/templates/app.yaml"],
+      packageJson: { name: "demo", version: "0.0.1", description: "demo" },
+      requiredDependencies: [],
+      unusedDependencies: [],
+      warnings: [],
+    });
+
+    expect(text).toContain("app: demo (apps/demo: 1 files)");
+    expect(text).toContain("3 files across infra, package.json");
+    expect(text).toContain("(none)");
+  });
+});