@akanjs/devkit 3.0.0-alpha.5 → 3.0.0-alpha.51

package/executors.test.ts

@@ -31,7 +31,6 @@ const rootPackageJson = (extra: Partial<PackageJson> = {}): PackageJson => ({
     react: "19.0.0",
     "react-dom": "19.0.0",
     "react-server-dom-webpack": "19.0.0",
-    sharp: "1.0.0",
     lodash: "4.0.0",
   },
   devDependencies: {
@@ -149,8 +148,10 @@ describe("Executor filesystem helpers", () => {
       "AI Development Guide",
     );
     expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
+    // Rules and their plugin registrations live in the package's base config, so a framework release reaches an
+    // existing workspace on `bun update` — the workspace file only extends it and scopes its own files.
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
-      "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
+      '"extends": ["@akanjs/devkit/biome.base.json"]',
     );
   });
 
@@ -758,6 +759,29 @@ describe("Workspace and app executor environment contracts", () => {
     expect(offsetMinimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8286");
     expect(offsetMinimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8286");
   });
+
+  test("pins the start command to development so an ambient NODE_ENV cannot pick the production router", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/ambient"), { recursive: true });
+    await writeFile(path.join(root, "apps/ambient/akan.config.ts"), "export default {};\n");
+
+    const originalNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      const started = await AppExecutor.from(workspace, "ambient").prepareCommand("start");
+      expect(started.env.NODE_ENV).toBe("development");
+      // The builder runs in this process and bakes NODE_ENV into the dev bundles it emits.
+      expect(process.env.NODE_ENV).toBe("development");
+    } finally {
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+      else process.env.NODE_ENV = originalNodeEnv;
+    }
+  });
 });
 
 describe("PkgExecutor package generation", () => {
@@ -771,7 +795,7 @@ describe("PkgExecutor package generation", () => {
       exports: { "./extra": { import: "./extra.ts" } },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
@@ -781,12 +805,12 @@ describe("PkgExecutor package generation", () => {
     expect(distPackageJson).toMatchObject({
       name: "@sample/tool",
       type: "module",
-      engines: { bun: ">=1.3.13" },
+      engines: { bun: ">=1.4.0" },
       dependencies: { lodash: "4.0.0" },
       devDependencies: { typescript: "6.0.0" },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
     expect(distPackageJson.exports?.["."]).toEqual({
       import: "./index.ts",

package/executors.ts

@@ -23,6 +23,7 @@ import { pathToFileURL } from "node:url";
 import type { AkanPlugin, AkanSyncContext, PluginRuntimeContext } from "akanjs";
 import {
   capitalize,
+  getPageSourceFileViolation,
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
@@ -42,6 +43,7 @@ import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
+import { resolveRepoName } from "./repoIdentity";
 import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
 // Type-only: the implementation is loaded on demand in `getTypeChecker` to keep `typescript` out of
@@ -232,7 +234,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command,
@@ -341,7 +343,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command: modulePath,
@@ -788,7 +790,7 @@ export class WorkspaceExecutor extends Executor {
   static #execs = new Map<string, WorkspaceExecutor>();
   static fromRoot({
     workspaceRoot = process.cwd(),
-    repoName = path.basename(process.cwd()),
+    repoName = resolveRepoName(workspaceRoot),
   }: {
     workspaceRoot?: string;
     repoName?: string;
@@ -1005,6 +1007,16 @@ export class SysExecutor extends Executor {
     const path = this.type === "app" ? `apps/${this.name}/lib` : `libs/${this.name}/lib`;
     return await this.workspace.getDirInModule(path, this.name);
   }
+  async getPageConventionViolations(): Promise<{ relativePath: string; reason: string }[]> {
+    if (!(await this.exists("page"))) return [];
+    const violations: { relativePath: string; reason: string }[] = [];
+    for (const entry of await this.getAllFiles("**/*", { cwd: this.getPath("page") })) {
+      const relativePath = entry.split(path.sep).join("/");
+      const reason = getPageSourceFileViolation(relativePath);
+      if (reason) violations.push({ relativePath: `page/${relativePath}`, reason });
+    }
+    return violations;
+  }
 
   #scanInfo: AppInfo | LibInfo | null = null;
   hasScanInfo() {
@@ -1363,6 +1375,12 @@ export class AppExecutor extends SysExecutor {
         this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true }),
       ]);
     } else await this.removeDir(".akan");
+    //? `akan start` is the dev server, and it must say so rather than inherit an answer. Bun auto-loads the
+    //? workspace `.env`, so NODE_ENV=production can reach this process without ever being exported in a shell —
+    //? and a dev server that believes it is production serves from the production route cache, whose every
+    //? route throws because a dev artifact carries no routes manifest. Written into `process.env` and not only
+    //? into the child env because the builder runs here and bakes NODE_ENV into the bundles it emits.
+    if (type === "start") process.env.NODE_ENV = "development";
     const devPort = type === "start" ? (await this.getDevPort()).toString() : undefined;
     const env = this.getCommandEnv({
       AKAN_COMMAND_TYPE: type,
@@ -1700,7 +1718,7 @@ export class LibExecutor extends SysExecutor {
   #akanConfig: AkanLibConfig | null = null;
   override async getConfig({ refresh }: { refresh?: boolean } = {}) {
     if (this.#akanConfig && !refresh) return this.#akanConfig;
-    this.#akanConfig = await AkanLibConfig.from(this);
+    this.#akanConfig = await AkanLibConfig.from(this, { bustImportCache: refresh });
     return this.#akanConfig;
   }
 }
@@ -1806,7 +1824,7 @@ export class PkgExecutor extends Executor {
           default: "./index.ts",
         },
       },
-      engines: { bun: ">=1.3.13" },
+      engines: { bun: ">=1.4.0" },
       ...dependencyMaps,
     };
     await Promise.all([this.dist.writeJson("package.json", distPkgJson), this.writeJson("package.json", distPkgJson)]);

package/formSetterScanner.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { FormSetterScanner } from "./formSetterScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/tmp/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX),
+});
+
+const scan = (content: string) =>
+  new FormSetterScanner().scan([fileOf("apps/demo/lib/task/Task.Template.tsx", content)]);
+
+describe("FormSetterScanner", () => {
+  test("a setter passed by reference publishes, so nothing is reported", () => {
+    expect(
+      scan(`export const General = () => (
+  <Field.Text value={taskForm.title} onChange={st.do.setTitleOnTask} />
+);
+`),
+    ).toEqual([]);
+  });
+
+  test("every wrapper shape is counted once per field, whatever the wrapper was for", () => {
+    const warnings = scan(`export const General = () => (
+  <>
+    <Field.Text onChange={st.do.setTitleOnTask} />
+    <Field.ToggleSelect onChange={(type) => { st.do.setTypeOnTask(type); }} />
+    <Field.Phone onChange={(phone) => st.do.setPhoneOnTask(formatPhone(phone))} />
+    <Field.Parent
+      onChange={(project) => {
+        st.do.setProjectOnTask(project);
+        if (project) st.do.addMembersOnTask(project.members ?? []);
+      }}
+    />
+  </>
+);
+`);
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.rule).toBe("akan.agent.unpublished-form-setter");
+    expect(warnings[0]?.scope).toBe("agent");
+    expect(warnings[0]?.message).toContain("setPhoneOnTask, setProjectOnTask, setTypeOnTask");
+    expect(warnings[0]?.locations).toHaveLength(3);
+  });
+
+  test("a nested path write is unannotatable by design and is not counted", () => {
+    expect(
+      scan(`export const Rows = ({ idx }: { idx: number }) => (
+  <Field.Text onChange={(title) => st.do.writeOnTask(\`payments.\${idx}.title\`, title)} />
+);
+`),
+    ).toEqual([]);
+  });
+
+  test("a zero-parameter handler is a button setting a constant, not a form control", () => {
+    expect(
+      scan(`export const Actions = () => (
+  <Button onClick={() => st.do.setStatusOnTask("done")}>Done</Button>
+);
+`),
+    ).toEqual([]);
+  });
+
+  test("a non-setter action behind a wrapper is somebody else's rule", () => {
+    expect(
+      scan(`export const Filters = () => (
+  <Select onChange={(ids) => st.do.setQueryArgsOfTaskInSelf(ids)} />
+);
+`),
+    ).toEqual([]);
+  });
+
+  test("only .tsx is scanned", () => {
+    const content = `export const set = (v: string) => <X onChange={(t) => st.do.setTitleOnTask(t)} />;\n`;
+    expect(new FormSetterScanner().scan([fileOf("apps/demo/lib/task/task.store.ts", content)])).toEqual([]);
+  });
+});

package/formSetterScanner.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+/**
+ * The inventory of model fields a screen writes but does not publish.
+ *
+ * A control handed `onChange={st.do.setTitleOnTask}` **by reference** names the field it writes, so it emits
+ * `data-akan-action` and `useFieldTool` publishes the field to the in-page agent. Any wrapper around that setter is
+ * an anonymous closure carrying neither, and the field goes quiet — for the agent, for an E2E selector, and for the
+ * accessibility tree.
+ *
+ * `no-unpublished-form-setter.grit` is the per-line enforcement, and it fires only on a pure forwarding wrapper,
+ * because every other shape has a legitimate reading and a lint error would be wrong. This is the other half: the
+ * per-file count of fields that ended up unreachable whatever the reason, which is the number worth watching. A
+ * warning rather than an error for the same reason — the remedy depends on why the wrapper is there.
+ *
+ * Only a handler that takes a parameter is counted. A zero-parameter handler (`onClick={() => st.do.setStatusOnUser
+ * ("active")}`) is a button setting a constant, not a form control, and its remedy is an `st.tool` beside it.
+ */
+export class FormSetterScanner {
+  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
+  }
+
+  #scanFile({ file, sourceFile }: SourceFileInfo): QualityWarning[] {
+    const wrapped: { setter: string; line: number }[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isJsxAttribute(node)) {
+        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        if (setter) wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    if (!wrapped.length) return [];
+    const setters = [...new Set(wrapped.map((entry) => entry.setter))].sort();
+    return [
+      {
+        rule: "akan.agent.unpublished-form-setter",
+        scope: "agent",
+        severity: "warning",
+        message:
+          setters.length === 1
+            ? `${setters[0]} is reached through a wrapper, so that field publishes no agent tool and carries no data-akan-action.`
+            : `${setters.length} field setters are reached through a wrapper, so those fields publish no agent tool and carry no data-akan-action: ${setters.join(", ")}.`,
+        file,
+        line: wrapped[0]?.line,
+        locations: wrapped.map(({ line }) => ({ file, line })),
+      },
+    ];
+  }
+
+  /** The setter a handler prop writes behind a wrapper, or null when it is passed by reference or absent. */
+  static #wrappedSetterOf(attribute: ts.JsxAttribute): string | null {
+    if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text)) return null;
+    const initializer = attribute.initializer;
+    if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression) return null;
+    const handler = initializer.expression;
+    if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler)) return null;
+    if (!handler.parameters.length) return null;
+    return FormSetterScanner.#setterCallIn(handler.body);
+  }
+
+  static #setterCallIn(node: ts.Node): string | null {
+    let found: string | null = null;
+    const visit = (current: ts.Node) => {
+      if (found) return;
+      if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const { expression, name } = current.expression;
+        if (
+          ts.isPropertyAccessExpression(expression) &&
+          ts.isIdentifier(expression.expression) &&
+          expression.expression.text === "st" &&
+          expression.name.text === "do" &&
+          FormSetterScanner.#fieldSetter.test(name.text)
+        ) {
+          found = name.text;
+          return;
+        }
+      }
+      ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+  }
+
+  static #lineOf(sourceFile: ts.SourceFile, node: ts.Node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}

package/frontendBuild/buildRouteClient.test.ts

@@ -82,16 +82,42 @@ describe("route client store bootstrap", () => {
   });
 
   test("bundles akan fetch into production SSR client chunks", () => {
-    expect(RouteClientBuilder.resolveSsrClientExternalOptions("start")).toMatchObject({
+    expect(RouteClientBuilder.resolveSsrClientBundleOptions("start")).toMatchObject({
       external: expect.arrayContaining(["akanjs/fetch"]),
       externalSubpaths: ["akanjs/fetch"],
     });
 
-    expect(RouteClientBuilder.resolveSsrClientExternalOptions("build")).toEqual({
+    expect(RouteClientBuilder.resolveSsrClientBundleOptions("build")).toEqual({
+      target: "bun",
       external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"],
     });
   });
 
+  test("targets the server so SSR client chunks never resolve a browser export condition", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "node_modules/dom-conditioned-pkg");
+    await write(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "dom-conditioned-pkg",
+        type: "module",
+        exports: { ".": { browser: "./index.dom.js", default: "./index.js" } },
+      }),
+    );
+    await write(path.join(pkgDir, "index.dom.js"), 'export const element = document.createElement("i");\n');
+    await write(path.join(pkgDir, "index.js"), "export const element = null;\n");
+    const entry = path.join(root, "entry.ts");
+    await write(entry, 'export { element } from "dom-conditioned-pkg";\n');
+
+    for (const command of ["start", "build"] as const) {
+      const { target } = RouteClientBuilder.resolveSsrClientBundleOptions(command);
+      const built = await Bun.build({ entrypoints: [entry], target, format: "esm" });
+
+      expect(built.success).toBe(true);
+      expect(await built.outputs[0].text()).not.toContain("document.createElement");
+    }
+  });
+
   test("rewrites SSR external imports to runtime aliases", () => {
     const source = [
       'import React, { useState } from "react";',

package/frontendBuild/clientBuildTypes.ts

@@ -55,6 +55,8 @@ export interface BuildClientResult {
   rscClientUrl: string;
 }
 
+export type ClientBundleTarget = "browser" | "bun";
+
 export const CLIENT_BUNDLE_NAMING = {
   entry: "[name]-[hash].[ext]",
   chunk: "chunks/[hash].[ext]",
@@ -79,6 +81,8 @@ export interface BundleClientEntriesOptions {
 }
 
 export interface BundleClientEntriesInternalOptions extends BundleClientEntriesOptions {
+  /** Module-resolution target. `"bun"` for the server-executed `client-ssr` bundle, `"browser"` otherwise. */
+  target?: ClientBundleTarget;
   external?: readonly string[];
   externalSubpaths?: readonly string[];
   externalAliases?: Partial<Record<string, string>>;

package/frontendBuild/clientEntriesBundler.ts

@@ -7,6 +7,7 @@ import {
   type BundleClientEntriesInternalOptions,
   type BundleClientEntriesResult,
   CLIENT_BUNDLE_NAMING,
+  type ClientBundleTarget,
   type ClientManifest,
   type MetafileOutput,
   type OpaqueEntryAliases,
@@ -25,6 +26,7 @@ export class ClientEntriesBundler {
   #externalSubpaths: readonly string[];
   #externalAliases: Partial<Record<string, string>>;
   #command: "build" | "start";
+  #target: ClientBundleTarget;
   #outputSubdir: string;
   #reactFastRefresh: boolean;
   #artifactDir: string;
@@ -47,6 +49,7 @@ export class ClientEntriesBundler {
     this.#externalSubpaths = options.externalSubpaths ?? [];
     this.#externalAliases = options.externalAliases ?? {};
     this.#command = options.command ?? "start";
+    this.#target = options.target ?? "browser";
     this.#outputSubdir = options.outputSubdir ?? "client";
     this.#reactFastRefresh = options.reactFastRefresh ?? false;
     this.#artifactDir = `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
@@ -61,7 +64,7 @@ export class ClientEntriesBundler {
       entrypoints: this.#opaqueEntries.entries,
       outdir: this.#outdir,
       splitting: true,
-      target: "browser",
+      target: this.#target,
       format: "esm",
       naming: CLIENT_BUNDLE_NAMING,
       metafile: true,

package/frontendBuild/cssCandidateCache.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CssCandidateCache } from "./cssCandidateCache";
+
+const scan = async (source: string) => {
+  const dir = await mkdtemp(path.join(tmpdir(), "css-candidate-"));
+  const file = path.join(dir, "probe.tsx");
+  await writeFile(file, source);
+  return await new CssCandidateCache(path.join(dir, "cache.json")).load().then((c) => c.candidatesFor(file));
+};
+
+describe("CssCandidateCache token extraction", () => {
+  test("keeps plain utilities, variants and arbitrary values whole", async () => {
+    const candidates = await scan(`const c = "w-full hover:bg-muted md:w-1/2 text-[#fff]";`);
+    expect(candidates).toEqual(expect.arrayContaining(["w-full", "hover:bg-muted", "md:w-1/2", "text-[#fff]"]));
+  });
+
+  // A candidate that opens with `[` used to be torn into `_td` + `px-3`, so every descendant-variant
+  // rule in the framework compiled to nothing and its element rendered unstyled with no diagnostic.
+  test("keeps an arbitrary variant that starts with a bracket", async () => {
+    const candidates = await scan(`const c = "[&_td]:px-3 [&>*]:gap-2 [&_tbody_tr]:border-t";`);
+    expect(candidates).toEqual(expect.arrayContaining(["[&_td]:px-3", "[&>*]:gap-2", "[&_tbody_tr]:border-t"]));
+    expect(candidates).not.toContain("_td");
+  });
+
+  // A labelled tuple type looks like an arbitrary property, and compiles to a rule whose declaration is
+  // TypeScript. `optimize()` cannot parse that, and drops far more than the offending rule on its way
+  // out — every variant in the build went missing, so nothing hovered, focused or responded to a
+  // breakpoint. Tailwind writes a space in an arbitrary value as `_`, so whitespace rules the token out.
+  test("ignores a labelled tuple type that only looks like an arbitrary property", async () => {
+    const candidates = await scan(
+      `type A = [key: string, make: () => unknown][];\ntype B = [setQueryArgs: (a: Args) => Args, options?: Policy];`,
+    );
+    expect(candidates.filter((candidate) => candidate.startsWith("["))).toEqual([]);
+  });
+});

package/frontendBuild/cssCandidateCache.ts

@@ -1,7 +1,19 @@
 import { stat } from "node:fs/promises";
 
-/** Every identifier-ish token in a source file is a potential tailwind class. */
-const CANDIDATE_RE = /-?[\w@][\w:/.-]*(?:\[[^\]]+\][\w:/.-]*)*/g;
+/**
+ * Every identifier-ish token in a source file is a potential tailwind class. The leading alternation
+ * matters: an arbitrary variant starts with `[` (`[&_td]:px-3`, `[&>*]:gap-2`), and a pattern anchored
+ * on a word character tears it into `_td` plus `px-3` instead — both meaningless, so the rule compiles
+ * to nothing and the element silently renders unstyled.
+ *
+ * Brackets must hold no whitespace. Tailwind spells a space in an arbitrary value `_`, so a bracket
+ * group containing one is never a class — but it is exactly the shape of a labelled tuple type
+ * (`[key: string, make: () => unknown]`). Scanned as a candidate, that compiles to an arbitrary
+ * *property* rule carrying TypeScript as its declaration, which the lightningcss pass in `optimize()`
+ * cannot parse; its error recovery then drops a whole span of the stylesheet — in practice every
+ * variant rule in the build, leaving hover, focus, responsive and dark styles silently absent.
+ */
+const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:\[[^\]\s]+\][\w:/.-]*)*/g;
 
 interface CachedFile {
   mtimeMs: number;
@@ -27,7 +39,7 @@ interface CacheFile {
  */
 export class CssCandidateCache {
   /** Bump when the token regex or the entry shape changes, so stale extractions are not reused. */
-  static readonly #version = 1;
+  static readonly #version = 3;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
   #dirty = false;