@akanjs/devkit 2.3.11-rc.3 → 2.3.11-rc.5

package/akanApp/akanApp.host.ts

@@ -11,6 +11,7 @@ const BACKEND_RESTART_DEBOUNCE_MS = 120;
 const BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
 const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
 const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
+const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -270,6 +271,7 @@ export class AkanAppHost {
   #pendingRestartReason: BackendRestartReason | null = null;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail: string[] = [];
   #lastGoodFrontend: LastGoodFrontendState = {};
   #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
   #pendingBuildStatusReplay: DevBuildStatus[] = [];
@@ -321,6 +323,7 @@ export class AkanAppHost {
     this.#backendStartStatus = startStatus;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
+    this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
       stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
@@ -351,6 +354,38 @@ export class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
+    if (this.withInk) {
+      // Ink mode pipes backend stdio to keep the TUI clean; drain the pipes and surface
+      // them through the logger so runtime errors are not silently swallowed.
+      void this.#forwardBackendStream(backend.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
+      void this.#forwardBackendStream(backend.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
+    }
+  }
+  #recordBackendStderr(chunk: string) {
+    const lines = chunk.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0) return;
+    this.#backendStderrTail.push(...lines);
+    if (this.#backendStderrTail.length > BACKEND_STDERR_TAIL_LIMIT) {
+      this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
+    }
+  }
+  async #forwardBackendStream(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
+    if (!stream) return;
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text.trim()) continue;
+        if (kind === "stderr") {
+          this.#recordBackendStderr(text);
+          this.logger.warn(`[backend] ${text.trimEnd()}`);
+        } else {
+          this.logger.verbose(`[backend] ${text.trimEnd()}`);
+        }
+      }
+    } catch {
+      // The stream closes when the backend exits; nothing further to surface here.
+    }
   }
   #nextBackendBuildStatusGeneration(generation?: number): number {
     if (typeof generation === "number") {
@@ -482,6 +517,9 @@ export class AkanAppHost {
     this.logger.warn(
       `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
     );
+    if (this.#backendStderrTail.length > 0) {
+      this.logger.warn(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
+    }
     this.#backendRecoveryTimer = setTimeout(() => {
       this.#backendRecoveryTimer = null;
       if (this.#backend) return;

package/applicationTestPreload.ts

@@ -32,9 +32,14 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
     path.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH),
   );
 
-  for (const candidate of [...new Set(candidates)]) {
+  const uniqueCandidates = [...new Set(candidates)];
+  for (const candidate of uniqueCandidates) {
     if (await Bun.file(candidate).exists()) return candidate;
   }
 
-  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}`);
+  throw new Error(
+    `Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.\nProbed paths:\n${uniqueCandidates
+      .map((candidate) => `  - ${candidate}`)
+      .join("\n")}`,
+  );
 }

package/executors.test.ts

@@ -140,7 +140,7 @@ describe("Executor filesystem helpers", () => {
     expect(await readFile(path.join(root, "workspace/.env"), "utf8")).toContain("AKAN_PUBLIC_REPO_NAME");
     expect(await readFile(path.join(root, "workspace/.vscode/settings.json"), "utf8")).toContain("typescript.tsdk");
     expect(await readFile(path.join(root, "workspace/.cursor/rules/akan.mdc"), "utf8")).toContain(
-      "Akan.js Workspace Rules",
+      "Akan workspace agent guide",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
     expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(

package/lint/no-deep-internal-import.grit

@@ -21,5 +21,15 @@ or {
       span = $source,
       message = "Module files should not import from two or more parent directories."
     )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport(),
+    not $filename <: r".*\.(?:test|spec)\.tsx?",
+    $filename <: r".*/lib/.+\.tsx",
+    $source <: r"\"\.\./.*\"",
+    register_diagnostic(
+      span = $source,
+      message = "Module UI (.tsx) files under lib must not use internal relative imports like ../cnst. Import from the package client/server entrypoint instead."
+    )
   }
 }

package/lint/no-redeclare-predefined-endpoint.grit

@@ -0,0 +1,26 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every model already gets auto-generated CRUD endpoints in its slice fetch
+// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts):
+//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>.
+// Re-declaring one of them inside the `endpoint(...)` block of a
+// `<model>.signal.ts` file shadows the framework contract and can pass
+// sync/typecheck/build while failing at runtime, so flag it here.
+`$key: $value` as $prop where {
+  $prop <: within `class $className extends $base {}` where {
+    $base <: contains `endpoint`,
+    $className <: r"([A-Z][a-zA-Z0-9]*)Endpoint"($Cap)
+  },
+  $filename <: r".*/([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
+  or {
+    $key <: $model,
+    $key <: r"(?:light|create|update|remove)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
+      $keyCap <: $Cap
+    }
+  },
+  register_diagnostic(
+    span = $key,
+    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.11-rc.3",
+  "version": "2.3.11-rc.5",
   "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.11-rc.3",
+    "akanjs": "2.3.11-rc.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/scanInfo.ts

@@ -52,6 +52,7 @@ const appRootAllowedFiles = new Set([
   "package.json",
   "server.ts",
   "tsconfig.json",
+  "tsconfig.tsbuildinfo",
 ]);
 const appRootAllowedDirs = new Set([
   ".akan",

package/workflow/executor.ts

@@ -403,6 +403,8 @@ export const createWorkflowStepRegistry = ({
   createUi,
   addField,
   addEnumField,
+  addMutation,
+  addSlice,
 }: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
   const inspect = async () => undefined;
   const commandOnly = async () => undefined;
@@ -483,6 +485,24 @@ export const createWorkflowStepRegistry = ({
       ),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
     [workflowStepKey("add-enum-field", "update-option")]: inspect,
+    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await addMutation({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          mutation: workflowStringInput(plan.inputs.mutation),
+        }),
+      ),
+    [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await addSlice({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          slice: workflowStringInput(plan.inputs.slice),
+        }),
+      ),
+    [workflowStepKey("add-slice", "update-signal-slice")]: inspect,
   };
 };
 

package/workflow/source.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { inspectDictionaryStructure } from "./source";
+import {
+  hasClassMethod,
+  hasSignalFactoryEntry,
+  hasSourceParseErrors,
+  insertClassMethod,
+  insertSignalFactoryEntry,
+  inspectDictionaryStructure,
+} from "./source";
 
 describe("inspectDictionaryStructure", () => {
   test("preserves protected dictionary chain order around the model object", () => {
@@ -60,3 +67,109 @@ export const dictionary = modelDictionary(["en", "ko"])
     expect(structure.chainMethods).toEqual(["modelDictionary", "slice", "model", "translate", "error"]);
   });
 });
+
+describe("insertClassMethod", () => {
+  test("inserts a method into an empty service class body", () => {
+    const content = `import { serve } from "akanjs/service";
+import * as db from "../db";
+export class BannerService extends serve(db.banner, () => ({})) {}
+`;
+    const next = insertClassMethod(content, "BannerService", "  async archive() {\n    return true;\n  }");
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next as string, "service.ts")).toBe(false);
+    expect(hasClassMethod(next as string, "BannerService", "archive")).toBe(true);
+  });
+
+  test("inserts a method into a populated service class body", () => {
+    const content = `import { serve } from "akanjs/service";
+import * as db from "../db";
+export class NotificationService extends serve(db.notification, () => ({})) {
+  async subscribe(token: string) {
+    return token;
+  }
+}
+`;
+    const next = insertClassMethod(content, "NotificationService", "  async archive() {\n    return true;\n  }");
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next as string, "service.ts")).toBe(false);
+    expect(hasClassMethod(next as string, "NotificationService", "archive")).toBe(true);
+    expect(hasClassMethod(next as string, "NotificationService", "subscribe")).toBe(true);
+  });
+
+  test("returns null when the class is not found", () => {
+    expect(insertClassMethod("export class Other {}", "MissingService", "  x() {}")).toBeNull();
+  });
+});
+
+describe("insertSignalFactoryEntry", () => {
+  const mutationEntry =
+    "archive: mutation(Boolean)\n    .exec(async function () {\n      return await this.bannerService.archive();\n    }),";
+
+  test("adds mutation param when the endpoint factory has no params", () => {
+    const content = `import { endpoint } from "akanjs/signal";
+import * as srv from "../srv";
+export class BannerEndpoint extends endpoint(srv.banner, () => ({})) {}
+`;
+    const next = insertSignalFactoryEntry(content, "BannerEndpoint", "archive", mutationEntry, {
+      mode: "destructure",
+      name: "mutation",
+    });
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next as string, "signal.ts")).toBe(false);
+    expect(hasSignalFactoryEntry(next as string, "BannerEndpoint", "archive")).toBe(true);
+    expect(next as string).toContain("{ mutation }");
+  });
+
+  test("extends an existing destructured param without dropping siblings", () => {
+    const content = `import { endpoint } from "akanjs/signal";
+import * as srv from "../srv";
+export class BannerEndpoint extends endpoint(srv.banner, ({ pubsub, query }) => ({
+  existing: query(String).exec(async function () {
+    return "x";
+  }),
+})) {}
+`;
+    const next = insertSignalFactoryEntry(content, "BannerEndpoint", "archive", mutationEntry, {
+      mode: "destructure",
+      name: "mutation",
+    });
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next as string, "signal.ts")).toBe(false);
+    expect(next as string).toContain("{ pubsub, query, mutation }");
+    expect(hasSignalFactoryEntry(next as string, "BannerEndpoint", "archive")).toBe(true);
+    expect(hasSignalFactoryEntry(next as string, "BannerEndpoint", "existing")).toBe(true);
+  });
+
+  test("adds the init param to a slice factory and inserts the slice entry", () => {
+    const content = `import { slice, Admin, Public } from "akanjs/signal";
+import * as srv from "../srv";
+export class BannerSlice extends slice(srv.banner, { guards: { root: Admin, get: Public, cru: Admin } }, () => ({})) {}
+`;
+    const sliceEntry =
+      "inPublic: init()\n    .exec(function () {\n      return this.bannerService.queryInPublic();\n    }),";
+    const next = insertSignalFactoryEntry(content, "BannerSlice", "inPublic", sliceEntry, {
+      mode: "positional",
+      name: "init",
+    });
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next as string, "signal.ts")).toBe(false);
+    expect(next as string).toContain("(init) =>");
+    expect(hasSignalFactoryEntry(next as string, "BannerSlice", "inPublic")).toBe(true);
+  });
+
+  test("is idempotent when the entry already exists", () => {
+    const content = `import { endpoint } from "akanjs/signal";
+import * as srv from "../srv";
+export class BannerEndpoint extends endpoint(srv.banner, ({ mutation }) => ({
+  archive: mutation(Boolean).exec(async function () {
+    return true;
+  }),
+})) {}
+`;
+    const next = insertSignalFactoryEntry(content, "BannerEndpoint", "archive", mutationEntry, {
+      mode: "destructure",
+      name: "mutation",
+    });
+    expect(next).toBe(content);
+  });
+});

package/workflow/source.ts

@@ -862,3 +862,134 @@ export const parseValues = (value: string | null) =>
     ?.split(",")
     .map((item) => item.trim())
     .filter(Boolean) ?? [];
+
+// ---- Service / signal insertion (add-mutation, add-slice) ----
+
+export const hasSourceParseErrors = (content: string, fileName = "source.ts") =>
+  hasParseDiagnostics(sourceFileFor(fileName, content));
+
+const findClassDeclaration = (source: ts.SourceFile, className: string): ts.ClassDeclaration | null => {
+  let found: ts.ClassDeclaration | null = null;
+  const visit = (node: ts.Node) => {
+    if (found) return;
+    if (ts.isClassDeclaration(node) && node.name?.text === className) {
+      found = node;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(source, visit);
+  return found;
+};
+
+const firstHeritageCall = (node: ts.ClassDeclaration): ts.CallExpression | null => {
+  const expression = (node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [])[0]?.expression;
+  return expression && ts.isCallExpression(expression) ? expression : null;
+};
+
+const factoryArrowOf = (call: ts.CallExpression): ts.ArrowFunction | ts.FunctionExpression | null => {
+  const arg = call.arguments.find((argument) => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+  return arg && (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) ? arg : null;
+};
+
+export const hasClassMethod = (content: string, className: string, methodName: string) => {
+  const node = findClassDeclaration(sourceFileFor("service.ts", content), className);
+  return Boolean(
+    node?.members.some((member) => ts.isMethodDeclaration(member) && nodeName(member.name) === methodName),
+  );
+};
+
+export const insertClassMethod = (content: string, className: string, methodBlock: string): string | null => {
+  const source = sourceFileFor("service.ts", content);
+  const node = findClassDeclaration(source, className);
+  if (!node) return null;
+  const closeBrace = node.getEnd() - 1;
+  if (content[closeBrace] !== "}") return null;
+  const lead = content.slice(0, closeBrace).endsWith("\n") ? "" : "\n";
+  return spliceText(content, closeBrace, closeBrace, `${lead}${methodBlock}\n`);
+};
+
+export interface FactoryParamPlan {
+  mode: "destructure" | "positional";
+  name: string;
+}
+
+const arrowParamInnerRegion = (
+  content: string,
+  source: ts.SourceFile,
+  arrow: ts.ArrowFunction | ts.FunctionExpression,
+) => {
+  if (arrow.parameters.length > 0) {
+    return {
+      start: arrow.parameters[0].getStart(source),
+      end: arrow.parameters[arrow.parameters.length - 1].getEnd(),
+    };
+  }
+  const open = content.indexOf("(", arrow.getStart(source));
+  if (open < 0) return null;
+  const close = content.indexOf(")", open);
+  if (close < 0) return null;
+  return { start: open + 1, end: close };
+};
+
+const factoryParamEdit = (
+  content: string,
+  source: ts.SourceFile,
+  arrow: ts.ArrowFunction | ts.FunctionExpression,
+  plan: FactoryParamPlan,
+): { start: number; end: number; text: string } | "unchanged" | null => {
+  if (arrow.parameters.length > 1) return null;
+  const region = arrowParamInnerRegion(content, source, arrow);
+  if (!region) return null;
+  if (arrow.parameters.length === 0) {
+    return { ...region, text: plan.mode === "destructure" ? `{ ${plan.name} }` : plan.name };
+  }
+  const param = arrow.parameters[0];
+  if (plan.mode === "positional") return nodeName(param.name) === plan.name ? "unchanged" : null;
+  if (!ts.isObjectBindingPattern(param.name)) return null;
+  const names = param.name.elements.map((element) => (ts.isIdentifier(element.name) ? element.name.text : null));
+  if (names.some((name) => name === null)) return null;
+  if (names.includes(plan.name)) return "unchanged";
+  return {
+    start: param.getStart(source),
+    end: param.getEnd(),
+    text: `{ ${[...(names as string[]), plan.name].join(", ")} }`,
+  };
+};
+
+const factoryObjectOf = (source: ts.SourceFile, className: string) => {
+  const node = findClassDeclaration(source, className);
+  const call = node ? firstHeritageCall(node) : null;
+  const arrow = call ? factoryArrowOf(call) : null;
+  const object = arrow ? firstObjectReturnedByArrow(arrow) : null;
+  return arrow && object ? { arrow, object } : null;
+};
+
+export const hasSignalFactoryEntry = (content: string, className: string, entryName: string) => {
+  const located = factoryObjectOf(sourceFileFor("signal.ts", content), className);
+  return Boolean(located?.object.properties.some((property) => propertyName(property) === entryName));
+};
+
+export const insertSignalFactoryEntry = (
+  content: string,
+  className: string,
+  entryName: string,
+  entryLine: string,
+  param: FactoryParamPlan,
+): string | null => {
+  const source = sourceFileFor("signal.ts", content);
+  const located = factoryObjectOf(source, className);
+  if (!located) return null;
+  const locator = locatedObject(source, located.object);
+  if (locator.fields.some((field) => field.name === entryName)) return content;
+  // Compute the param edit first (its offsets precede the object), but apply it last so the
+  // object splice (at a higher offset) does not invalidate the param region positions.
+  const paramEdit = factoryParamEdit(content, source, located.arrow, param);
+  if (paramEdit === null) return null;
+  const withEntry = insertOrderedFieldLine(content, locator, entryName, entryLine, {
+    fieldIndent: "  ",
+    closingIndent: "",
+  });
+  if (withEntry === content) return null;
+  return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
+};

package/workflow/types.ts

@@ -47,6 +47,14 @@ export interface AddEnumFieldInput extends PrimitiveTargetInput {
   includeInLight?: boolean | null;
 }
 
+export interface AddMutationInput extends PrimitiveTargetInput {
+  mutation: string | null;
+}
+
+export interface AddSliceInput extends PrimitiveTargetInput {
+  slice: string | null;
+}
+
 export interface WorkflowInputSpec {
   type: WorkflowInputType;
   required?: boolean;
@@ -472,4 +480,6 @@ export interface WorkflowPrimitiveOperations {
   createUi: (input: PrimitiveTargetInput & { surface: UiSurface }) => Promise<PrimitiveWriteReport>;
   addField: (input: AddFieldInput) => Promise<PrimitiveWriteReport>;
   addEnumField: (input: AddEnumFieldInput) => Promise<PrimitiveWriteReport>;
+  addMutation: (input: AddMutationInput) => Promise<PrimitiveWriteReport>;
+  addSlice: (input: AddSliceInput) => Promise<PrimitiveWriteReport>;
 }