@akanjs/devkit 3.0.0-beta.17 → 3.0.0-beta.18

package/prompter.ts

@@ -2,7 +2,6 @@ import fsPromise from "node:fs/promises";
 import { input, select } from "@inquirer/prompts";
 
 import { getDirname } from "./getDirname";
-import type { GuideGenerateJson } from "./guideline";
 
 interface FileUpdateRequestProps {
   context: string;
@@ -34,12 +33,6 @@ export class Prompter {
     const guidelineRoot = await Prompter.#getGuidelineRoot();
     return (await fsPromise.readdir(guidelineRoot)).filter((name) => !name.startsWith("_")).sort();
   }
-  static async getGuideJson(guideName: string): Promise<GuideGenerateJson> {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.generate.json`;
-    const guideJson = await fsPromise.readFile(filePath, "utf-8");
-    return JSON.parse(guideJson) as GuideGenerateJson;
-  }
   /**
    * The name is checked against the directory listing rather than interpolated straight into a path:
    * it arrives from an MCP tool argument, and an unknown one has to name the valid set instead of

package/qualityScanner.test.ts

@@ -26,7 +26,7 @@ afterEach(async () => {
 });
 
 describe("AkanQualityScanner abstract rule", () => {
-  test("warns on an abstract over the line limit and points at akan compact", async () => {
+  test("warns on an abstract over the line limit and says how to trim it", async () => {
     const root = await makeWorkspace({
       "apps/demo/lib/post/post.abstract.md": abstractOf(AbstractDoc.maxLines + 1),
       "apps/demo/lib/post/post.constant.ts": "export class Post {}\n",
@@ -41,7 +41,8 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/lib/post/post.abstract.md");
     expect(warnings[0]?.message).toContain(`${AbstractDoc.maxLines + 1} lines`);
-    expect(warnings[0]?.fix).toContain("akan compact");
+    expect(warnings[0]?.fix).toContain("## Rules");
+    expect(warnings[0]?.fix).not.toContain("akan compact");
   });
 });
 

package/qualityScanner.ts

@@ -114,7 +114,7 @@ const RULE_FIXES: Record<string, string> = {
     "Split the file by responsibility — move Zones, Utils, or subcomponents into sibling files.",
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
   "akan.file.abstract-max-lines":
-    "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.",
+    "Trim the abstract by hand to a title, one sentence naming what the module owns, a `## Rules` list of the invariants the source cannot show, and an optional workflow chain.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
   "akan.file.bang-comment-in-client":

package/routeSourceValidator.test.ts

@@ -15,7 +15,6 @@ describe("RouteSourceValidator", () => {
       "export const reconnect = true;",
       "export const wsConnect = true;",
       "export const layoutStyle = {};",
-      'export const gaTrackingId = "G-1";',
     ].join("\n");
 
     expect(() => validate(source, "layout", true)).not.toThrow();

package/routeSourceValidator.ts

@@ -86,18 +86,6 @@ export class RouteSourceValidator {
     if (exported.has("head") && exported.has("generateHead")) {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
-    if (
-      !options.rootLayout &&
-      (exported.has("head") || exported.has("generateHead")) &&
-      (exported.has("metadata") || exported.has("generateMetadata"))
-    ) {
-      throw new Error(
-        `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
-      );
-    }
-    if (exported.has("metadata") && exported.has("generateMetadata")) {
-      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
-    }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");

package/scanInfo.ts

@@ -524,16 +524,19 @@ export class PkgInfo {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
     const scanner = await createDependencyScanner(exec);
     const npmSet = new Set(Object.keys({ ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies }));
+    const workspacePathOf = (resolve: string) => resolve.replace(/^\.\//, "");
     const pkgPathSet = new Set(
       Object.keys(tsconfig.compilerOptions.paths ?? {})
-        .filter((path) => tsconfig.compilerOptions.paths?.[path]?.some((resolve) => resolve.startsWith("pkgs/")))
+        .filter((path) =>
+          tsconfig.compilerOptions.paths?.[path]?.some((resolve) => workspacePathOf(resolve).startsWith("pkgs/")),
+        )
         .map((path) => path.replace("/*", "")),
     );
     const [npmDepSet, pkgPathDepSet] = await scanner.getImportSets([npmSet, pkgPathSet]);
     const pkgDeps = [...pkgPathDepSet]
       .map((path) => {
         const pathSplitLength = path.split("/").length;
-        return (tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
+        return workspacePathOf(tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
           .split("/")
           .slice(1, 1 + pathSplitLength)
           .join("/");

package/workflow/executor.ts

@@ -1,3 +1,4 @@
+import { capitalize } from "akanjs/common";
 import ts from "typescript";
 import type { AkanModuleContext } from "../akanContext";
 import type { Sys, Workspace } from "../commandDecorators";
@@ -396,6 +397,54 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   };
 };
 
+const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const mutation = workflowStringInput(plan.inputs.mutation) ?? "<mutation>";
+  const moduleClassName = moduleComponentName(module);
+  return {
+    recommendations: [
+      {
+        code: "add-mutation-action-surface-review",
+        kind: "manual-action",
+        target: `*/${moduleSourcePaths(module).store}`,
+        action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
+        confidence: "medium",
+        message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review action surface guidance before manually editing store or UI files.",
+      },
+    ],
+  };
+};
+
+const addSliceViewSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const slice = workflowStringInput(plan.inputs.slice) ?? "<slice>";
+  const moduleClassName = moduleComponentName(module);
+  return {
+    recommendations: [
+      {
+        code: "add-slice-view-surface-review",
+        kind: "manual-action",
+        target: `*/${moduleSourcePaths(module).zone}`,
+        action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
+        confidence: "medium",
+        message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review view surface guidance before manually editing Zone or page files.",
+      },
+    ],
+  };
+};
+
 export const createWorkflowStepRegistry = ({
   workspace,
   createModule,
@@ -494,6 +543,8 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+      addMutationActionSurfaceInspection(plan),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({
@@ -503,6 +554,7 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-slice", "update-signal-slice")]: inspect,
+    [workflowStepKey("add-slice", "connect-view-surfaces")]: async (_step, plan) => addSliceViewSurfaceInspection(plan),
   };
 };
 

package/workflow/source.ts

@@ -160,21 +160,27 @@ export const normalizeFieldType = (typeName: string) => {
   return normalizedTypes[typeName.toLowerCase()] ?? typeName;
 };
 
-export const ensureBaseTypeImport = (content: string, typeName: string) => {
-  if (typeName !== "Int" && typeName !== "Float") return content;
-  const source = sourceFileFor("constant.ts", content);
-  const baseImport = findNamedImport(source, "akanjs/base");
-  if (baseImport) {
-    if (baseImport.names.includes(typeName)) return content;
-    const nextNames = [...baseImport.names, typeName].sort();
+export const ensureNamedImport = (content: string, moduleSpecifier: string, name: string) => {
+  const source = sourceFileFor("source.ts", content);
+  const namedImport = findNamedImport(source, moduleSpecifier);
+  if (namedImport) {
+    if (namedImport.names.includes(name)) return content;
+    const nextNames = [...namedImport.names, name].sort();
     return spliceText(
       content,
-      baseImport.namedBindingsStart,
-      baseImport.namedBindingsEnd,
+      namedImport.namedBindingsStart,
+      namedImport.namedBindingsEnd,
       `{ ${nextNames.join(", ")} }`,
     );
   }
-  return `import { ${typeName} } from "akanjs/base";\n${content}`;
+  return `import { ${name} } from "${moduleSpecifier}";\n${content}`;
+};
+
+export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  if (typeName !== "Int" && typeName !== "Float") return content;
+  return ensureBaseImport(content, typeName);
 };
 
 export type FieldDefaultValue = string | number | boolean | null;
@@ -200,12 +206,12 @@ const booleanDefault = (rawDefault: FieldDefaultValue): string | null => {
 };
 
 const dateDefault = (rawDefault: FieldDefaultValue): string | null => {
-  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `new Date(${rawDefault})`;
+  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `() => dayjs(${rawDefault})`;
   if (typeof rawDefault !== "string") return null;
   const trimmed = rawDefault.trim();
   if (!trimmed) return null;
-  if (trimmed === "now") return "new Date()";
-  if (!Number.isNaN(Date.parse(trimmed))) return `new Date(${JSON.stringify(trimmed)})`;
+  if (trimmed === "now") return "() => dayjs()";
+  if (!Number.isNaN(Date.parse(trimmed))) return `() => dayjs(${JSON.stringify(trimmed)})`;
   return null;
 };
 

package/guideline.ts

@@ -1,19 +0,0 @@
-export interface GuideScan {
-  type: "example" | "source" | "usage" | (string & {});
-  description: string;
-  path: string;
-  filterText?: string;
-  sample?: number;
-}
-export interface GuideUpdate {
-  filePath: string;
-  contents: string[];
-  rules: string[];
-}
-export interface GuideGenerateJson {
-  title: string;
-  description: string;
-  scans: GuideScan[];
-  update: GuideUpdate;
-  page?: string;
-}