@akanjs/devkit 2.3.13 → 2.4.0-rc.0

package/akanConfig/akanConfig.test.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PackageJson } from "../types";
 import { AkanAppConfig, AkanLibConfig } from "./akanConfig";
+import type { DeepPartial, LibConfigResult } from "./types";
 
 const akanPackageJson = JSON.parse(
   fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../akanjs/package.json"), "utf8"),

package/capacitorApp.ts

@@ -1004,15 +1004,14 @@ export class CapacitorApp {
     }
     for (const permission of this.target.permissions ?? []) {
       const claimants = nativePlugins.get(permission);
-      if (!claimants?.length) {
-        this.app.logger.warn(
-          `Mobile target '${this.target.name}' declares permission '${permission}' but no plugin configures it. ` +
-            `Depend on a lib (e.g. @libs/util) whose akan.config declares a plugin with capacitor.permission '${permission}'.`,
-        );
+      if (claimants?.length) {
+        const ctx = this.#makeNativeContext({ operation, env });
+        for (const plugin of claimants) await plugin.capacitor?.configureNative?.(ctx);
         continue;
       }
-      const ctx = this.#makeNativeContext({ operation, env });
-      for (const plugin of claimants) await plugin.capacitor?.configureNative?.(ctx);
+      if (permission === "camera") await this.addCamera();
+      else if (permission === "contacts") await this.addContact();
+      else if (permission === "location") await this.addLocation();
     }
   }
   #makeNativeContext({ operation, env }: Pick<RunConfig, "operation" | "env">): AkanNativeContext {
@@ -1143,6 +1142,28 @@ export class CapacitorApp {
       await this.#clearRootCapacitorConfigs();
     }
   }
+  async addCamera() {
+    await this.#setPermissionInIos({
+      cameraUsageDescription: "$(PRODUCT_NAME) requires access to the camera to take photos.",
+      photoAddUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+      photoUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+    });
+    this.#setPermissionsInAndroid(["READ_MEDIA_IMAGES", "READ_EXTERNAL_STORAGE", "WRITE_EXTERNAL_STORAGE"]);
+  }
+  async addContact() {
+    await this.#setPermissionInIos({
+      contactsUsageDescription: "$(PRODUCT_NAME) requires access to the contacts to add new contacts.",
+    });
+    this.#setPermissionsInAndroid(["READ_CONTACTS", "WRITE_CONTACTS"]);
+  }
+  async addLocation() {
+    await this.#setPermissionInIos({
+      locationAlwaysUsageDescription: "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+      locationWhenInUseUsageDescription: "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+    });
+    this.#setPermissionsInAndroid(["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"]);
+    this.#setFeaturesInAndroid(["android.hardware.location.gps"]);
+  }
   #addIosEntitlements(entitlements: Record<string, string | string[]>) {
     Object.assign(this.#iosEntitlements, entitlements);
   }

package/frontendBuild/autoImportSync.test.ts

@@ -0,0 +1,357 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AutoImportSync, transformSource } from "./autoImportSync";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-auto-import-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const constantCtx = { role: "constant", scope: "libs", project: "shared" } as const;
+const documentCtx = { role: "document", scope: "libs", project: "shared" } as const;
+const serviceCtx = { role: "service", scope: "libs", project: "shared" } as const;
+const signalCtx = { role: "signal", scope: "libs", project: "shared" } as const;
+const dictionaryCtx = { role: "dictionary", scope: "libs", project: "shared" } as const;
+const srvkitCtx = { role: "srvkit", scope: "libs", project: "shared" } as const;
+const storeCtx = { role: "store", scope: "libs", project: "shared" } as const;
+const clientLibCtx = { role: "client", scope: "libs", project: "shared" } as const;
+const clientAppCtx = { role: "client", scope: "apps", project: "akasys" } as const;
+
+describe("transformSource — base scalars (akanjs/base)", () => {
+  test("adds a missing scalar as a new import after the last import", () => {
+    const source = `import { via } from "akanjs/constant";\n\nexport class A extends via {\n  count = field(Int);\n}\n`;
+    const out = transformSource(source, "a.constant.ts", constantCtx);
+    expect(out).toBe(
+      `import { via } from "akanjs/constant";\nimport { Int } from "akanjs/base";\n\nexport class A extends via {\n  count = field(Int);\n}\n`,
+    );
+  });
+
+  test("merges into an existing akanjs/base import, sorted case-insensitively", () => {
+    const source = `import { dayjs } from "akanjs/base";\n\nconst x = field(Int);\nconst y = field(Any);\n`;
+    const out = transformSource(source, "a.document.ts", documentCtx);
+    expect(out).toBe(
+      `import { Any, dayjs, Int } from "akanjs/base";\n\nconst x = field(Int);\nconst y = field(Any);\n`,
+    );
+  });
+
+  test("no change when everything used is already imported", () => {
+    const source = `import { Int } from "akanjs/base";\n\nconst x = field(Int);\n`;
+    expect(transformSource(source, "a.signal.ts", signalCtx)).toBeNull();
+  });
+
+  test("ignores JS globals and unknown identifiers (String, Date, Number)", () => {
+    const source = `const a = field(String);\nconst b = field(Date);\nconst c = field(Number);\n`;
+    expect(transformSource(source, "a.constant.ts", constantCtx)).toBeNull();
+  });
+
+  test("does not treat member access as a bare scalar reference", () => {
+    const source = `const a = obj.Int;\nconst b = obj.Any;\n`;
+    expect(transformSource(source, "a.constant.ts", constantCtx)).toBeNull();
+  });
+
+  test("skips a scalar that is locally declared", () => {
+    const source = `const Int = 1;\nconst a = Int + 2;\n`;
+    expect(transformSource(source, "a.constant.ts", constantCtx)).toBeNull();
+  });
+});
+
+describe("transformSource — server roles (framework symbols + relative barrels)", () => {
+  test("document: merges akanjs/document helpers and adds db/cnst namespaces", () => {
+    const source = `import { SchemaOf } from "akanjs/document";\n\nexport const h = () => by("id") && from(db.user) && cnst.User;\n`;
+    const out = transformSource(source, "x.document.ts", documentCtx);
+    expect(out).toBe(
+      `import { by, from, SchemaOf } from "akanjs/document";\nimport * as db from "../db";\nimport * as cnst from "../cnst";\n\nexport const h = () => by("id") && from(db.user) && cnst.User;\n`,
+    );
+  });
+
+  test("service: resolves serve, db/srv namespaces, DataInputOf and Err", () => {
+    const source = `export class S extends serve(srv.user) {\n  async m(x: DataInputOf<"user">) {\n    db.user.get();\n    Err.notFound();\n  }\n}\n`;
+    const out = transformSource(source, "x.service.ts", serviceCtx);
+    expect(out).not.toBeNull();
+    expect(out).toContain(`import { serve } from "akanjs/service";`);
+    expect(out).toContain(`import { DataInputOf } from "akanjs/document";`);
+    expect(out).toContain(`import { Err } from "../dict";`);
+    expect(out).toContain(`import * as db from "../db";`);
+    expect(out).toContain(`import * as srv from "../srv";`);
+  });
+
+  test("signal: resolves endpoint/internal/Public plus srv/cnst namespaces", () => {
+    const source = `export class Sig {\n  a = endpoint(Public).query(cnst.User);\n  b = internal(srv.user);\n}\n`;
+    const out = transformSource(source, "x.signal.ts", signalCtx);
+    expect(out).toContain(`import { endpoint, internal, Public } from "akanjs/signal";`);
+    expect(out).toContain(`import * as srv from "../srv";`);
+    expect(out).toContain(`import * as cnst from "../cnst";`);
+  });
+
+  test("dictionary: resolves modelDictionary from akanjs/dictionary", () => {
+    const source = `export const d = modelDictionary({});\n`;
+    expect(transformSource(source, "x.dictionary.ts", dictionaryCtx)).toBe(
+      `import { modelDictionary } from "akanjs/dictionary";\n\nexport const d = modelDictionary({});\n`,
+    );
+  });
+
+  test("srvkit: resolves Logger, adapt and base scalars", () => {
+    const source = `export const log = new Logger("x");\nexport const a = adapt(() => dayjs());\n`;
+    const out = transformSource(source, "aes.ts", srvkitCtx);
+    expect(out).toContain(`import { Logger } from "akanjs/common";`);
+    expect(out).toContain(`import { adapt } from "akanjs/service";`);
+    expect(out).toContain(`import { dayjs } from "akanjs/base";`);
+  });
+});
+
+describe("transformSource — type-only imports", () => {
+  test("hoists to `import type` when a standalone type symbol is added", () => {
+    const source = `export const useRoot = (): RootStore => ({}) as RootStore;\n`;
+    const out = transformSource(source, "x.store.ts", storeCtx);
+    expect(out).toBe(
+      `import type { RootStore } from "../st";\n\nexport const useRoot = (): RootStore => ({}) as RootStore;\n`,
+    );
+  });
+
+  test("uses inline `type` when a type symbol joins value imports from the same specifier", () => {
+    const source = `import { dayjs } from "akanjs/base";\n\nexport const now = (): Dayjs => dayjs();\n`;
+    const out = transformSource(source, "x.document.ts", documentCtx);
+    expect(out).toBe(`import { type Dayjs, dayjs } from "akanjs/base";\n\nexport const now = (): Dayjs => dayjs();\n`);
+  });
+
+  test("no change when a type symbol is already imported", () => {
+    const source = `import type { RootStore } from "../st";\n\nexport const x = (): RootStore => ({}) as RootStore;\n`;
+    expect(transformSource(source, "x.store.ts", storeCtx)).toBeNull();
+  });
+});
+
+describe("transformSource — store role (relative barrels)", () => {
+  test("adds namespace cnst and named fetch from their respective barrels", () => {
+    const source = `import { store } from "akanjs/store";\n\nexport class S extends store {\n  async m() {\n    const a = new cnst.Admin();\n    await fetch.me();\n  }\n}\n`;
+    const out = transformSource(source, "s.store.ts", storeCtx);
+    expect(out).toBe(
+      `import { store } from "akanjs/store";\nimport { fetch } from "../useClient";\nimport * as cnst from "../cnst";\n\nexport class S extends store {\n  async m() {\n    const a = new cnst.Admin();\n    await fetch.me();\n  }\n}\n`,
+    );
+  });
+
+  test("does not re-add an already-present namespace cnst", () => {
+    const source = `import * as cnst from "../cnst";\n\nconst a = new cnst.Admin();\n`;
+    expect(transformSource(source, "s.store.ts", storeCtx)).toBeNull();
+  });
+});
+
+describe("transformSource — client role (package client entry)", () => {
+  test("adds client imports below the use client directive when no imports exist", () => {
+    const source = `"use client";\n\nexport const C = () => fetch.me() && cnst.Foo;\n`;
+    const out = transformSource(source, "C.Unit.tsx", clientLibCtx);
+    expect(out).toBe(
+      `"use client";\nimport { cnst, fetch } from "@libs/shared/client";\n\nexport const C = () => fetch.me() && cnst.Foo;\n`,
+    );
+  });
+
+  test("resolves the app client entry for apps files", () => {
+    const source = `import { Load } from "akanjs/ui";\n\nexport const C = () => st.foo;\n`;
+    const out = transformSource(source, "C.Zone.tsx", clientAppCtx);
+    expect(out).toBe(
+      `import { Load } from "akanjs/ui";\nimport { st } from "@apps/akasys/client";\n\nexport const C = () => st.foo;\n`,
+    );
+  });
+
+  test("handles webkit .ts files (no jsx) the same as tsx", () => {
+    const source = `import { getEnv } from "akanjs/base";\n\nexport const load = () => fetch.me();\n`;
+    const out = transformSource(source, "cookie.ts", clientLibCtx);
+    expect(out).toBe(
+      `import { getEnv } from "akanjs/base";\nimport { fetch } from "@libs/shared/client";\n\nexport const load = () => fetch.me();\n`,
+    );
+  });
+});
+
+describe("AutoImportSync.syncForBatch", () => {
+  const seed = async (root: string, rel: string, content: string) => {
+    const abs = path.join(root, rel);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, content);
+    return abs;
+  };
+
+  test("writes the fix once, then is idempotent", async () => {
+    const root = await makeTempRoot();
+    const abs = await seed(
+      root,
+      "libs/shared/lib/foo/foo.constant.ts",
+      `import { via } from "akanjs/constant";\n\nconst x = field(Int);\n`,
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const first = await sync.syncForBatch([abs]);
+    expect(first.errors).toEqual([]);
+    expect(first.changedFiles).toEqual([abs]);
+    expect(await readFile(abs, "utf8")).toContain(`import { Int } from "akanjs/base";`);
+
+    const second = await sync.syncForBatch([abs]);
+    expect(second.changedFiles).toEqual([]);
+  });
+
+  test("skips files outside a known facet and test files", async () => {
+    const root = await makeTempRoot();
+    const outside = await seed(root, "libs/shared/foo.constant.ts", `const x = field(Int);\n`);
+    const testFile = await seed(root, "libs/shared/lib/foo/foo.constant.test.ts", `const x = field(Int);\n`);
+    const scriptFile = await seed(root, "libs/shared/script/foo.ts", `const x = dayjs();\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([outside, testFile, scriptFile]);
+    expect(result.changedFiles).toEqual([]);
+    expect(await readFile(outside, "utf8")).not.toContain("akanjs/base");
+    expect(await readFile(testFile, "utf8")).not.toContain("akanjs/base");
+    expect(await readFile(scriptFile, "utf8")).not.toContain("akanjs/base");
+  });
+
+  test("common facet resolves base scalars, lib barrels and domain refs", async () => {
+    const root = await makeTempRoot();
+    await seed(root, "libs/x/lib/cnst.ts", `export const x = 1;\n`);
+    await seed(root, "libs/x/lib/character/character.constant.ts", `export class Character extends via {}\n`);
+    const common = await seed(
+      root,
+      "libs/x/common/helper.ts",
+      `export const f = (c: Character) => dayjs() && cnst.Foo && c;\n`,
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([common]);
+    expect(result.errors).toEqual([]);
+    const out = await readFile(common, "utf8");
+    expect(out).toContain(`import { dayjs } from "akanjs/base";`);
+    expect(out).toContain(`import * as cnst from "../lib/cnst";`);
+    expect(out).toContain(`import { Character } from "../lib/character/character.constant";`);
+  });
+
+  test("routes the srvkit facet and skips its generated index.ts", async () => {
+    const root = await makeTempRoot();
+    const aes = await seed(root, "libs/shared/srvkit/aes.ts", `export const log = new Logger("x");\n`);
+    const index = await seed(root, "libs/shared/srvkit/index.ts", `export * from "./aes";\nconst x = Logger;\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([aes, index]);
+    expect(result.changedFiles).toEqual([aes]);
+    expect(await readFile(aes, "utf8")).toContain(`import { Logger } from "akanjs/common";`);
+    expect(await readFile(index, "utf8")).not.toContain("akanjs/common");
+  });
+
+  test("covers ui/page tsx and webkit ts, and resolves the app client entry", async () => {
+    const root = await makeTempRoot();
+    const uiFile = await seed(root, "apps/akan/ui/Card.tsx", `"use client";\n\nexport const C = () => st.foo;\n`);
+    const pageFile = await seed(root, "apps/akan/page/(user)/home/_index.tsx", `export default () => cnst.Foo;\n`);
+    const webkitFile = await seed(root, "libs/shared/webkit/cookie.ts", `export const load = () => fetch.me();\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([uiFile, pageFile, webkitFile]);
+    expect(result.errors).toEqual([]);
+    expect(result.changedFiles.sort()).toEqual([pageFile, webkitFile, uiFile].sort());
+    expect(await readFile(uiFile, "utf8")).toContain(`import { st } from "@apps/akan/client";`);
+    expect(await readFile(pageFile, "utf8")).toContain(`import { cnst } from "@apps/akan/client";`);
+    expect(await readFile(webkitFile, "utf8")).toContain(`import { fetch } from "@libs/shared/client";`);
+  });
+
+  test("resolves domain model/scalar refs from sibling files in a constant", async () => {
+    const root = await makeTempRoot();
+    await seed(root, "libs/x/lib/file/file.constant.ts", `export class File extends via {}\n`);
+    await seed(root, "libs/x/lib/__scalar/encourageInfo/encourageInfo.constant.ts", `export class EncourageInfo {}\n`);
+    const user = await seed(
+      root,
+      "libs/x/lib/user/user.constant.ts",
+      `import { via } from "akanjs/constant";\n\nexport class User extends via {\n  file = field(File);\n  info = field(EncourageInfo);\n}\n`,
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([user]);
+    expect(result.errors).toEqual([]);
+    const out = await readFile(user, "utf8");
+    expect(out).toContain(`import { File } from "../file/file.constant";`);
+    expect(out).toContain(`import { EncourageInfo } from "../__scalar/encourageInfo/encourageInfo.constant";`);
+  });
+
+  test("dictionary resolves same-folder .constant/.document/.signal refs", async () => {
+    const root = await makeTempRoot();
+    await seed(root, "libs/x/lib/user/user.constant.ts", `export class User extends via {}\n`);
+    await seed(root, "libs/x/lib/user/user.document.ts", `export class UserFilter {}\n`);
+    await seed(root, "libs/x/lib/user/user.signal.ts", `export class UserEndpoint {}\n`);
+    const dict = await seed(
+      root,
+      "libs/x/lib/user/user.dictionary.ts",
+      `export const d = modelDictionary(User, UserFilter, UserEndpoint);\n`,
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    await sync.syncForBatch([dict]);
+    const out = await readFile(dict, "utf8");
+    expect(out).toContain(`import { modelDictionary } from "akanjs/dictionary";`);
+    expect(out).toContain(`import { User } from "./user.constant";`);
+    expect(out).toContain(`import { UserFilter } from "./user.document";`);
+    expect(out).toContain(`import { UserEndpoint } from "./user.signal";`);
+  });
+
+  test("leaves JS globals and ambiguous domain names alone", async () => {
+    const root = await makeTempRoot();
+    // `Map` is a real model here but must not shadow the JS global.
+    await seed(root, "libs/x/lib/map/map.constant.ts", `export class Map extends via {}\n`);
+    // `Dup` is exported by two files → ambiguous → skipped.
+    await seed(root, "libs/x/lib/a/a.constant.ts", `export class Dup {}\n`);
+    await seed(root, "libs/x/lib/b/b.constant.ts", `export class Dup {}\n`);
+    const consumer = await seed(
+      root,
+      "libs/x/lib/user/user.constant.ts",
+      `import { via } from "akanjs/constant";\n\nexport class User extends via {\n  m() {\n    const x = new Map();\n    return Dup;\n  }\n}\n`,
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([consumer]);
+    expect(result.changedFiles).toEqual([]);
+    const out = await readFile(consumer, "utf8");
+    expect(out).not.toContain("map.constant");
+    expect(out).not.toContain("a.constant");
+    expect(out).not.toContain("b.constant");
+  });
+
+  test("srvkit: resolves lib barrels relative to file depth", async () => {
+    const root = await makeTempRoot();
+    for (const barrel of ["dict", "db", "cnst"]) await seed(root, `libs/x/lib/${barrel}.ts`, `export const x = 1;\n`);
+    const shallow = await seed(root, "libs/x/srvkit/api.ts", `export const f = () => Err.of(cnst.User, db.user);\n`);
+    const deep = await seed(root, "libs/x/srvkit/a/b/api.ts", `export const g = () => Err.of(cnst.User);\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    await sync.syncForBatch([shallow, deep]);
+    const shallowOut = await readFile(shallow, "utf8");
+    expect(shallowOut).toContain(`import { Err } from "../lib/dict";`);
+    expect(shallowOut).toContain(`import * as cnst from "../lib/cnst";`);
+    expect(shallowOut).toContain(`import * as db from "../lib/db";`);
+    const deepOut = await readFile(deep, "utf8");
+    expect(deepOut).toContain(`import { Err } from "../../../lib/dict";`);
+    expect(deepOut).toContain(`import * as cnst from "../../../lib/cnst";`);
+  });
+
+  test("srvkit: does not import a barrel whose file is absent", async () => {
+    const root = await makeTempRoot();
+    await seed(root, "libs/x/lib/dict.ts", `export const x = 1;\n`); // no lib/srv.ts
+    const file = await seed(root, "libs/x/srvkit/api.ts", `export const f = () => Err.of(srv.user);\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    await sync.syncForBatch([file]);
+    const out = await readFile(file, "utf8");
+    expect(out).toContain(`import { Err } from "../lib/dict";`);
+    expect(out).not.toContain("lib/srv");
+  });
+
+  test("skips generated webkit index.ts", async () => {
+    const root = await makeTempRoot();
+    const indexFile = await seed(root, "libs/shared/webkit/index.ts", `export * from "./cookie";\nconst x = fetch;\n`);
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    const result = await sync.syncForBatch([indexFile]);
+    expect(result.changedFiles).toEqual([]);
+    expect(await readFile(indexFile, "utf8")).not.toContain("@libs/shared/client");
+  });
+});

package/frontendBuild/autoImportSync.ts

@@ -0,0 +1,610 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import ts from "typescript";
+
+//* Auto-import daemon: a source-editing sibling of DevGeneratedIndexSync. When a domain file changes,
+//* framework symbols that are used but not imported (e.g. `Int` in a *.constant.ts, `fetch` in a *.store.ts)
+//* are inserted automatically. Detection is a closed-registry scan: we only look for a fixed, framework-owned
+//* set of identifiers per file role, so no type information is required. Writes only happen on a real diff,
+//* which keeps the watcher from looping on its own edits.
+
+export interface AutoImportSyncResult {
+  changedFiles: string[];
+  errors: string[];
+}
+
+export interface AutoImportSyncOptions {
+  workspaceRoot: string;
+}
+
+type FileRole =
+  | "constant"
+  | "document"
+  | "service"
+  | "signal"
+  | "dictionary"
+  | "srvkit"
+  | "common"
+  | "store"
+  | "client";
+type ImportKind = "named" | "namespace";
+
+interface FileContext {
+  role: FileRole;
+  scope: "apps" | "libs";
+  project: string;
+}
+
+interface ImportTarget {
+  specifier: string;
+  kind: ImportKind;
+  //* When true, emitted as a type-only import (`import type { X }`, or inline `type X` when mixed with
+  //* value names from the same specifier). Only meaningful for `kind: "named"`.
+  typeOnly?: boolean;
+}
+
+//* A registry rule: the identifiers `names` should be imported from `specifier` with the given `kind`.
+//* `specifier` may depend on the file's package (e.g. the client entrypoint).
+interface ImportRule {
+  names: string[];
+  specifier: string | ((ctx: FileContext) => string);
+  kind: ImportKind;
+  typeOnly?: boolean;
+}
+
+const TEST_FILE_RE = /\.(test|spec)\.(ts|tsx)$/;
+
+//* Shared rules reused across roles. Domain (`lib/<model>/`) files sit at a fixed depth, so the
+//* relative barrels `../cnst`, `../db`, `../srv`, `../dict` are always correct for them.
+const AKAN_BASE: ImportRule = {
+  names: ["Int", "Float", "ID", "Any", "Upload", "enumOf", "dayjs"],
+  specifier: "akanjs/base",
+  kind: "named",
+};
+//* Type-only exports of akanjs/base — emitted as `type` imports (e.g. `import { type Dayjs, dayjs }`).
+const AKAN_BASE_TYPES: ImportRule = { names: ["Dayjs"], specifier: "akanjs/base", kind: "named", typeOnly: true };
+const CNST_NS: ImportRule = { names: ["cnst"], specifier: "../cnst", kind: "namespace" };
+const DB_NS: ImportRule = { names: ["db"], specifier: "../db", kind: "namespace" };
+const SRV_NS: ImportRule = { names: ["srv"], specifier: "../srv", kind: "namespace" };
+const ERR_DICT: ImportRule = { names: ["Err"], specifier: "../dict", kind: "named" };
+
+//* The closed registry, keyed by file role. Derived from an import-frequency scan across apps/libs;
+//* only high-confidence, framework-owned identifiers are listed (domain model/scalar refs are resolved
+//* separately). Order matters only when the same name could appear twice — keep names unique per role.
+const RULES: Record<FileRole, ImportRule[]> = {
+  constant: [AKAN_BASE, AKAN_BASE_TYPES, { names: ["via"], specifier: "akanjs/constant", kind: "named" }],
+  document: [
+    AKAN_BASE,
+    AKAN_BASE_TYPES,
+    CNST_NS,
+    DB_NS,
+    ERR_DICT,
+    {
+      names: ["by", "from", "into", "SchemaOf", "DataInputOf", "DocumentUpdateHelper", "documentQueryHelper", "Mdl"],
+      specifier: "akanjs/document",
+      kind: "named",
+    },
+  ],
+  service: [
+    AKAN_BASE,
+    AKAN_BASE_TYPES,
+    DB_NS,
+    SRV_NS,
+    CNST_NS,
+    ERR_DICT,
+    { names: ["serve"], specifier: "akanjs/service", kind: "named" },
+    {
+      names: ["DataInputOf", "ListQueryOption", "DatabaseRegistry", "getFilterInfoByKey"],
+      specifier: "akanjs/document",
+      kind: "named",
+    },
+  ],
+  signal: [
+    AKAN_BASE,
+    AKAN_BASE_TYPES,
+    SRV_NS,
+    CNST_NS,
+    ERR_DICT,
+    {
+      names: ["endpoint", "internal", "slice", "Public", "Req", "Ws", "None", "Res"],
+      specifier: "akanjs/signal",
+      kind: "named",
+    },
+  ],
+  dictionary: [
+    {
+      names: ["modelDictionary", "scalarDictionary", "serviceDictionary"],
+      specifier: "akanjs/dictionary",
+      kind: "named",
+    },
+  ],
+  srvkit: [
+    AKAN_BASE,
+    AKAN_BASE_TYPES,
+    { names: ["Logger", "HttpClient", "sleep"], specifier: "akanjs/common", kind: "named" },
+    { names: ["adapt"], specifier: "akanjs/service", kind: "named" },
+    { names: ["SignalContext", "Guard", "InternalArg", "Middleware"], specifier: "akanjs/signal", kind: "named" },
+  ],
+  common: [AKAN_BASE, AKAN_BASE_TYPES],
+  store: [
+    CNST_NS,
+    { names: ["store"], specifier: "akanjs/store", kind: "named" },
+    { names: ["fetch", "usePage", "sig"], specifier: "../useClient", kind: "named" },
+    { names: ["st"], specifier: "../st", kind: "named" },
+    { names: ["RootStore"], specifier: "../st", kind: "named", typeOnly: true },
+  ],
+  client: [
+    {
+      names: ["cnst", "fetch", "st", "usePage"],
+      specifier: (ctx) => `@${ctx.scope}/${ctx.project}/client`,
+      kind: "named",
+    },
+  ],
+};
+
+//* Domain imports resolve open-ended model/scalar class refs against a per-package index, rather than
+//* a fixed registry. Only these roles opt in, and each may pull from the listed sibling file kinds.
+type DomainKind = "constant" | "document" | "signal";
+type DomainIndex = Map<string, { file: string; kind: DomainKind }[]>;
+const PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+const DOMAIN_ROLE_KINDS: Partial<Record<FileRole, DomainKind[]>> = {
+  constant: ["constant"],
+  dictionary: ["constant", "document", "signal"],
+  common: ["constant"],
+};
+//* lib barrel imports (srvkit/common): identifier -> generated `lib/<barrel>.ts` file + import shape.
+//* Their specifier depth is per-file (see `#libBarrelResolver`), so they can't live in the RULES table.
+const LIB_BARRELS: Record<string, { barrel: string; kind: ImportKind }> = {
+  Err: { barrel: "dict", kind: "named" },
+  db: { barrel: "db", kind: "namespace" },
+  cnst: { barrel: "cnst", kind: "namespace" },
+  srv: { barrel: "srv", kind: "namespace" },
+};
+//* ECMAScript/TS structural globals never resolved as domain symbols, so that a package model named
+//* e.g. `Map` cannot shadow the JS `Map` used in `new Map()`. Domain-y globals like `File` are allowed
+//* on purpose (they are real models here).
+const DOMAIN_DENYLIST = new Set([
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "Date",
+  "Promise",
+  "Array",
+  "Object",
+  "Error",
+  "TypeError",
+  "RangeError",
+  "RegExp",
+  "Symbol",
+  "Proxy",
+  "Reflect",
+  "JSON",
+  "Math",
+  "Number",
+  "BigInt",
+  "Function",
+  "Boolean",
+  "String",
+  "Record",
+  "Partial",
+  "Required",
+  "Readonly",
+  "Pick",
+  "Omit",
+  "Exclude",
+  "Extract",
+  "NonNullable",
+  "ReturnType",
+  "Parameters",
+  "Awaited",
+  "InstanceType",
+]);
+
+export class AutoImportSync {
+  readonly #workspaceRoot: string;
+  //* Per-package domain index (symbol -> source file), invalidated when a package's model file changes.
+  readonly #domainCache = new Map<string, DomainIndex>();
+
+  constructor({ workspaceRoot }: AutoImportSyncOptions) {
+    this.#workspaceRoot = path.resolve(workspaceRoot);
+  }
+
+  async syncForBatch(files: string[]): Promise<AutoImportSyncResult> {
+    const changedFiles: string[] = [];
+    const errors: string[] = [];
+    const seen = new Set<string>();
+
+    // Drop cached domain indexes for any package whose model files changed in this batch, so a newly
+    // added/renamed model is visible to references resolved later in the same batch.
+    for (const file of files) {
+      const pkgRoot = this.#domainPkgRootOf(file);
+      if (pkgRoot) this.#domainCache.delete(pkgRoot);
+    }
+
+    for (const file of files) {
+      const abs = path.resolve(file);
+      if (seen.has(abs)) continue;
+      seen.add(abs);
+      const ctx = this.#contextFor(abs);
+      if (!ctx) continue;
+      try {
+        const changed = await this.#syncFile(abs, ctx);
+        if (changed) changedFiles.push(abs);
+      } catch (err) {
+        errors.push(`[auto-import] sync failed for ${file}: ${formatError(err)}`);
+      }
+    }
+
+    return { changedFiles, errors };
+  }
+
+  //* Resolve the role + package location for a file, or null when the file is out of scope
+  //* (outside apps/libs, a generated/declaration/test file, or a facet+extension we do not handle).
+  #contextFor(abs: string): FileContext | null {
+    const rel = path.relative(this.#workspaceRoot, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+    const base = path.basename(abs);
+    if (TEST_FILE_RE.test(base) || base === "index.ts" || base === "index.tsx" || base.endsWith(".d.ts")) return null;
+
+    const parts = rel.split(path.sep).filter(Boolean);
+    const [scope, project, facet] = parts;
+    if ((scope !== "apps" && scope !== "libs") || !project || !facet) return null;
+    const role = roleFor(facet, base);
+    if (!role) return null;
+
+    return { role, scope, project };
+  }
+
+  async #syncFile(abs: string, ctx: FileContext): Promise<boolean> {
+    const stats = await stat(abs).catch(() => null);
+    if (!stats?.isFile()) return false;
+    const source = await readFile(abs, "utf8");
+    const resolveExtra = await this.#extraResolverFor(abs, ctx);
+    const next = transformSource(source, abs, ctx, resolveExtra);
+    if (next === null || next === source) return false;
+    await writeFile(abs, next);
+    return true;
+  }
+
+  //* Build the dynamic resolver for identifiers the static registry does not cover, or undefined when
+  //* the role has none. `srvkit`/`common` resolve the package's generated lib barrels (variable depth);
+  //* the domain roles resolve open-ended model/scalar refs against the per-package index. `common`
+  //* uses both — barrels first, then domain (the two symbol sets are disjoint).
+  async #extraResolverFor(abs: string, ctx: FileContext) {
+    const resolvers: ((symbol: string) => ImportTarget | null)[] = [];
+    if (ctx.role === "srvkit" || ctx.role === "common") resolvers.push(await this.#libBarrelResolver(abs, ctx));
+    const kinds = DOMAIN_ROLE_KINDS[ctx.role];
+    if (kinds) resolvers.push(await this.#domainResolver(abs, ctx, kinds));
+    if (resolvers.length === 0) return undefined;
+    return (symbol: string): ImportTarget | null => {
+      for (const resolve of resolvers) {
+        const target = resolve(symbol);
+        if (target) return target;
+      }
+      return null;
+    };
+  }
+
+  //* Resolve an unbound PascalCase identifier to a relative import of the package model/scalar that
+  //* exports it (only when exactly one package file of an allowed kind exports that name).
+  async #domainResolver(abs: string, ctx: FileContext, kinds: DomainKind[]) {
+    const index = await this.#domainIndex(path.join(this.#workspaceRoot, ctx.scope, ctx.project));
+    const fileDir = path.dirname(abs);
+    return (symbol: string): ImportTarget | null => {
+      if (!PASCAL_CASE_RE.test(symbol) || DOMAIN_DENYLIST.has(symbol)) return null;
+      const entries = (index.get(symbol) ?? []).filter((entry) => kinds.includes(entry.kind));
+      if (entries.length !== 1) return null; // unknown or ambiguous → leave it alone
+      return { specifier: relativeSpecifier(fileDir, entries[0].file), kind: "named" };
+    };
+  }
+
+  //* srvkit/common files import the package's generated lib barrels from a variable depth
+  //* (`../lib/dict`, `../../lib/dict`, …). Resolve each barrel name to a path relative to this file,
+  //* but only for barrels that actually exist (so an absent `lib/srv.ts` never yields a broken import).
+  async #libBarrelResolver(abs: string, ctx: FileContext) {
+    const fileDir = path.dirname(abs);
+    const libDir = path.join(this.#workspaceRoot, ctx.scope, ctx.project, "lib");
+    const available = new Map<string, ImportTarget>();
+    for (const [symbol, { barrel, kind }] of Object.entries(LIB_BARRELS)) {
+      if (await fileExists(path.join(libDir, `${barrel}.ts`)))
+        available.set(symbol, { specifier: relativeSpecifier(fileDir, path.join(libDir, barrel)), kind });
+    }
+    return (symbol: string): ImportTarget | null => available.get(symbol) ?? null;
+  }
+
+  async #domainIndex(pkgRoot: string): Promise<DomainIndex> {
+    const cached = this.#domainCache.get(pkgRoot);
+    if (cached) return cached;
+    const index = await buildDomainIndex(path.join(pkgRoot, "lib"));
+    this.#domainCache.set(pkgRoot, index);
+    return index;
+  }
+
+  //* The apps/libs package root for a model file (`*.constant/document/signal.ts` under `lib/`), else null.
+  #domainPkgRootOf(file: string): string | null {
+    const rel = path.relative(this.#workspaceRoot, path.resolve(file));
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+    const [scope, project, facet] = rel.split(path.sep).filter(Boolean);
+    if ((scope !== "apps" && scope !== "libs") || !project || facet !== "lib") return null;
+    if (!domainKindOf(path.basename(file))) return null;
+    return path.join(this.#workspaceRoot, scope, project);
+  }
+}
+
+//* Which facet+extension combinations get auto-imports, and the role that drives their registry.
+//* `client` covers every file that pulls domain symbols from the package client entrypoint:
+//* lib UI (.tsx), the `ui`/`page` facets (.tsx), and the `webkit` facet (.ts/.tsx).
+const roleFor = (facet: string, base: string): FileRole | null => {
+  if (facet === "lib") {
+    if (base.endsWith(".constant.ts")) return "constant";
+    if (base.endsWith(".document.ts")) return "document";
+    if (base.endsWith(".service.ts")) return "service";
+    if (base.endsWith(".signal.ts")) return "signal";
+    if (base.endsWith(".dictionary.ts")) return "dictionary";
+    if (base.endsWith(".store.ts")) return "store";
+    if (base.endsWith(".tsx")) return "client";
+    return null;
+  }
+  if (facet === "ui" || facet === "page") return base.endsWith(".tsx") ? "client" : null;
+  if (facet === "webkit") return base.endsWith(".ts") || base.endsWith(".tsx") ? "client" : null;
+  if (facet === "srvkit") return base.endsWith(".ts") ? "srvkit" : null;
+  if (facet === "common") return base.endsWith(".ts") || base.endsWith(".tsx") ? "common" : null;
+  return null;
+};
+
+const targetFor = (symbol: string, ctx: FileContext): ImportTarget | null => {
+  for (const rule of RULES[ctx.role]) {
+    if (!rule.names.includes(symbol)) continue;
+    const specifier = typeof rule.specifier === "function" ? rule.specifier(ctx) : rule.specifier;
+    return { specifier, kind: rule.kind, typeOnly: rule.typeOnly };
+  }
+  return null;
+};
+
+//* Returns the rewritten source, or null when nothing needs to change. `resolveExtra` (when supplied)
+//* handles identifiers not matched by the framework registry — domain model refs and srvkit barrels.
+export const transformSource = (
+  source: string,
+  fileName: string,
+  ctx: FileContext,
+  resolveExtra?: (symbol: string) => ImportTarget | null,
+): string | null => {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindFor(fileName));
+  const bound = collectBoundNames(sf);
+  const used = collectUsedReferences(sf);
+
+  // Group the needed symbols by their import target: framework registry first, then dynamic resolver.
+  // Named groups map each name to whether it is type-only, so we can emit `import type`/inline `type`.
+  const namedBySpecifier = new Map<string, Map<string, boolean>>();
+  const namespaceImports: { name: string; specifier: string }[] = [];
+  for (const name of used) {
+    if (bound.has(name)) continue;
+    const target = targetFor(name, ctx) ?? resolveExtra?.(name) ?? null;
+    if (!target) continue;
+    if (target.kind === "namespace") namespaceImports.push({ name, specifier: target.specifier });
+    else {
+      const names = namedBySpecifier.get(target.specifier) ?? new Map<string, boolean>();
+      names.set(name, target.typeOnly ?? false);
+      namedBySpecifier.set(target.specifier, names);
+    }
+  }
+  if (namedBySpecifier.size === 0 && namespaceImports.length === 0) return null;
+
+  const importDecls = sf.statements.filter(ts.isImportDeclaration);
+  const anchor = importDecls.at(-1) ?? null;
+  const namedImportsBySpecifier = collectExistingNamedImports(importDecls);
+
+  const edits: { start: number; end: number; text: string }[] = [];
+  const newStatements: string[] = [];
+
+  for (const [specifier, names] of namedBySpecifier) {
+    const existing = namedImportsBySpecifier.get(specifier);
+    if (existing) {
+      const merged = new Map(existing.names);
+      for (const [name, isType] of names) if (!merged.has(name)) merged.set(name, isType);
+      edits.push({
+        start: existing.decl.getStart(sf),
+        end: existing.decl.getEnd(),
+        text: formatNamedImport(specifier, merged),
+      });
+    } else newStatements.push(formatNamedImport(specifier, names));
+  }
+  for (const ns of namespaceImports) newStatements.push(`import * as ${ns.name} from "${ns.specifier}";`);
+
+  if (newStatements.length > 0) {
+    // If the anchor import is itself being merged, fold the new lines into that edit to avoid a
+    // zero-width insertion sharing a boundary with the merge replacement.
+    const anchorEdit = anchor ? edits.find((edit) => edit.start === anchor.getStart(sf)) : undefined;
+    if (anchorEdit) anchorEdit.text = `${anchorEdit.text}\n${newStatements.join("\n")}`;
+    else if (anchor)
+      edits.push({ start: anchor.getEnd(), end: anchor.getEnd(), text: `\n${newStatements.join("\n")}` });
+    else {
+      const prologueEnd = directivePrologueEnd(sf);
+      if (prologueEnd >= 0) edits.push({ start: prologueEnd, end: prologueEnd, text: `\n${newStatements.join("\n")}` });
+      else edits.push({ start: 0, end: 0, text: `${newStatements.join("\n")}\n\n` });
+    }
+  }
+  if (edits.length === 0) return null;
+
+  edits.sort((a, b) => b.start - a.start);
+  let out = source;
+  for (const edit of edits) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+  return out === source ? null : out;
+};
+
+//* Every name introduced into scope: import bindings plus local declarations. Over-collecting only
+//* suppresses an insertion (safe); under-collecting would risk a duplicate import (unsafe).
+const collectBoundNames = (sf: ts.SourceFile): Set<string> => {
+  const names = new Set<string>();
+  const visit = (node: ts.Node) => {
+    if (ts.isImportClause(node)) {
+      if (node.name) names.add(node.name.text);
+      const bindings = node.namedBindings;
+      if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text);
+      if (bindings && ts.isNamedImports(bindings)) for (const el of bindings.elements) names.add(el.name.text);
+    }
+    if (
+      (ts.isVariableDeclaration(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isParameter(node) ||
+        ts.isBindingElement(node) ||
+        ts.isEnumDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isInterfaceDeclaration(node)) &&
+      node.name &&
+      ts.isIdentifier(node.name)
+    )
+      names.add(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  return names;
+};
+
+const collectUsedReferences = (sf: ts.SourceFile): Set<string> => {
+  const used = new Set<string>();
+  const visit = (node: ts.Node) => {
+    if (ts.isIdentifier(node) && isReferencePosition(node)) used.add(node.text);
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  return used;
+};
+
+//* True when the identifier reads a binding, as opposed to being a member name, property key, or
+//* declaration name. e.g. in `cnst.Coordinate`, `cnst` is a reference but `Coordinate` is not.
+const isReferencePosition = (node: ts.Identifier): boolean => {
+  const parent = node.parent;
+  if (!parent) return true;
+  if (ts.isPropertyAccessExpression(parent) && parent.name === node) return false;
+  if (ts.isQualifiedName(parent) && parent.right === node) return false;
+  if (ts.isPropertyAssignment(parent) && parent.name === node) return false;
+  if (ts.isPropertySignature(parent) && parent.name === node) return false;
+  if (ts.isBindingElement(parent) && parent.propertyName === node) return false;
+  if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent)) return false;
+  return true;
+};
+
+interface ExistingNamedImport {
+  decl: ts.ImportDeclaration;
+  names: Map<string, boolean>; // name -> type-only (whole-clause `import type` or inline `type`)
+}
+
+const collectExistingNamedImports = (importDecls: ts.ImportDeclaration[]): Map<string, ExistingNamedImport> => {
+  const map = new Map<string, ExistingNamedImport>();
+  for (const decl of importDecls) {
+    const clause = decl.importClause;
+    const bindings = clause?.namedBindings;
+    if (!clause || !bindings || !ts.isNamedImports(bindings)) continue;
+    if (!ts.isStringLiteral(decl.moduleSpecifier)) continue;
+    const specifier = decl.moduleSpecifier.text;
+    if (map.has(specifier)) continue; // first same-specifier named import wins as the merge site
+    const names = new Map<string, boolean>();
+    for (const el of bindings.elements) names.set(el.name.text, clause.isTypeOnly || el.isTypeOnly);
+    map.set(specifier, { decl, names });
+  }
+  return map;
+};
+
+//* Render a named import, hoisting to `import type { … }` when every name is type-only and otherwise
+//* prefixing each type-only name with inline `type`. Names sorted case-insensitively (Biome order).
+const formatNamedImport = (specifier: string, names: Map<string, boolean>): string => {
+  const entries = [...names.entries()].sort((a, b) => compareNames(a[0], b[0]));
+  if (entries.every(([, isType]) => isType))
+    return `import type { ${entries.map(([name]) => name).join(", ")} } from "${specifier}";`;
+  const parts = entries.map(([name, isType]) => (isType ? `type ${name}` : name));
+  return `import { ${parts.join(", ")} } from "${specifier}";`;
+};
+
+const directivePrologueEnd = (sf: ts.SourceFile): number => {
+  let end = -1;
+  for (const stmt of sf.statements) {
+    if (ts.isExpressionStatement(stmt) && ts.isStringLiteral(stmt.expression)) end = stmt.getEnd();
+    else break;
+  }
+  return end;
+};
+
+const scriptKindFor = (fileName: string) => (fileName.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+
+//* Case-insensitive primary order with a case-sensitive tie-break (uppercase first), matching Biome's
+//* import specifier sort — so e.g. `Dayjs` precedes `dayjs`.
+const compareNames = (a: string, b: string): number => {
+  const [la, lb] = [a.toLowerCase(), b.toLowerCase()];
+  if (la !== lb) return la < lb ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
+const formatError = (err: unknown) => (err instanceof Error ? err.message : String(err));
+
+const fileExists = async (file: string) =>
+  stat(file)
+    .then((s) => s.isFile())
+    .catch(() => false);
+
+// ---- Domain index ---------------------------------------------------------------------------------
+
+const domainKindOf = (base: string): DomainKind | null => {
+  if (base.endsWith(".constant.ts")) return "constant";
+  if (base.endsWith(".document.ts")) return "document";
+  if (base.endsWith(".signal.ts")) return "signal";
+  return null;
+};
+
+//* Scan a package `lib/` for model files and index their exported PascalCase declarations.
+const buildDomainIndex = async (libDir: string): Promise<DomainIndex> => {
+  const index: DomainIndex = new Map();
+  for (const file of await collectDomainFiles(libDir)) {
+    const kind = domainKindOf(path.basename(file));
+    if (!kind) continue;
+    const src = await readFile(file, "utf8").catch(() => null);
+    if (src === null) continue;
+    for (const name of exportedPascalNames(src, file)) {
+      const entries = index.get(name) ?? [];
+      entries.push({ file, kind });
+      index.set(name, entries);
+    }
+  }
+  return index;
+};
+
+const collectDomainFiles = async (dir: string): Promise<string[]> => {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const files: string[] = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...(await collectDomainFiles(full)));
+    else if (domainKindOf(entry.name) && !TEST_FILE_RE.test(entry.name)) files.push(full);
+  }
+  return files;
+};
+
+const exportedPascalNames = (source: string, fileName: string): string[] => {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
+  const isExported = (node: ts.Node) =>
+    ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+  const names: string[] = [];
+  for (const stmt of sf.statements) {
+    if ((ts.isClassDeclaration(stmt) || ts.isFunctionDeclaration(stmt) || ts.isEnumDeclaration(stmt)) && stmt.name) {
+      if (isExported(stmt)) names.push(stmt.name.text);
+    } else if (ts.isVariableStatement(stmt) && isExported(stmt)) {
+      for (const decl of stmt.declarationList.declarations) if (ts.isIdentifier(decl.name)) names.push(decl.name.text);
+    } else if (ts.isExportDeclaration(stmt) && stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+      for (const el of stmt.exportClause.elements) names.push(el.name.text);
+    }
+  }
+  return names.filter((name) => PASCAL_CASE_RE.test(name));
+};
+
+//* Relative module specifier from a file's directory to a target file, extension stripped, `./`-anchored.
+const relativeSpecifier = (fromDir: string, toFile: string): string => {
+  const rel = path
+    .relative(fromDir, toFile)
+    .replace(/\.tsx?$/, "")
+    .split(path.sep)
+    .join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+};

package/frontendBuild/index.ts

@@ -1,4 +1,5 @@
 export * from "./allRoutesBuilder";
+export * from "./autoImportSync";
 export * from "./clientBuildTypes";
 export * from "./clientEntriesBundler";
 export * from "./clientEntryDiscovery";

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import {
   type App,
   AppExecutor,
+  AutoImportSync,
   type ChangeBatch,
   type ClientEntryDiscovery,
   CsrArtifactBuilder,
@@ -47,6 +48,7 @@ class IncrementalBuilder {
   #discovery: ClientEntryDiscovery;
   #changePlanner: DevChangePlanner;
   #generatedIndexSync: DevGeneratedIndexSync;
+  #autoImportSync: AutoImportSync;
   #generation = 0;
   #workQueue: Promise<void> = Promise.resolve();
   #cssRebuildQueue: Promise<void> = Promise.resolve();
@@ -62,6 +64,7 @@ class IncrementalBuilder {
     this.#discovery = options.discovery;
     this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
+    this.#autoImportSync = new AutoImportSync({ workspaceRoot: options.app.workspace.workspaceRoot });
   }
 
   async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
@@ -269,6 +272,13 @@ class IncrementalBuilder {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
+    //* Insert framework imports that are used but omitted (e.g. `Int` in *.constant.ts, `fetch` in
+    //* *.store.ts) before regenerating barrels. Edits land on files already in this batch, so they
+    //* rebuild in this same generation; the write is idempotent so it does not re-trigger the watcher.
+    const autoImport = await this.#autoImportSync.syncForBatch(batch.files);
+    for (const error of autoImport.errors) this.#logger.error(error);
+    if (autoImport.changedFiles.length > 0)
+      this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
     const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
     const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.13",
+  "version": "2.4.0-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.13",
+    "akanjs": "2.4.0-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",