@akanjs/cli 3.0.0-alpha.88 → 3.0.0-alpha.89

package/guidelines/modelTemplate/modelTemplate.instruction.md

@@ -17,6 +17,11 @@ Generate form and interaction fragments bound to store form state and generated
 - Do not call service or signal directly from inputs.
 - Do not duplicate validation that belongs in constants or service invariants.
 - Do not build page layout here when Zone should compose it.
+- Do not persist typed values yourself. The edit shells (`Load.Edit`, `Model.EditModal`, `Model.New`) save the
+  whole `<model>Form` and recover it on the next open; a Template that reaches for `localStorage` or a per-field
+  cache saves a fragment of a form and restores it over whatever the server just returned.
+- The `Field.*` `cache` prop and the `Input` `cacheKey` prop are deprecated and store nothing. Turn recovery off
+  with `draft={false}` on the shell, or name a scope with `draft="<scope>"`; do not reintroduce a field-level one.
 
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -42,6 +42,43 @@ const config: AppConfig = { web: false }; // api only
   reached for any of them. An app that needs one declares it in `docker.preRuns` / `docker.postRuns`, which are
   emitted around the `bun install` — that is the migration for a `puppeteer` or `ffmpeg` app.
 
+## Route Prefixes — Where The API Is Mounted
+
+Signal endpoints hang off `/api` and the websocket upgrade off `/api/ws`. Both move, and both have to move in
+three places at once: the route table the replica builds, the gateway's own upgrade check, and the `fetchClient`
+in every browser tab. That last one is the constraint the design is built around.
+
+```ts
+// apps/<app>/main.ts — the deployment's answer
+await new AkanApp({ prefix: "/backend", websocketPrefix: "/socket" }).start();
+```
+
+```ts
+// apps/<app>/akan.config.ts — the build's answer, for the bundles a server never gets to correct
+const config: AppConfig = { api: { prefix: "/backend", websocketPrefix: "/socket" } };
+```
+
+- **Three sources, narrowest first.** `globalThis.__AKAN_PREFIX__`, then `AKAN_API_PREFIX` / `AKAN_WS_PREFIX`,
+  then `AKAN_PUBLIC_API_PREFIX` / `AKAN_PUBLIC_WS_PREFIX`, then `/api` and `/ws`. Read them through
+  `getApiPrefix()` / `getWsPrefix()` from `akanjs/base`; never write either literal again.
+- **`AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*` namespace.** Only that namespace is inlined
+  into client bundles at build time, so a name inside it could never act as a runtime override — and only a name
+  inside it can reach a prebuilt bundle at all. The two jobs need two names.
+- **`new AkanApp({ prefix })` reaches the browser through the page, not through a prop.** `FetchClient` fixes its
+  origin when the module graph initializes, before any component renders, so a React prop — a `System.Provider`
+  value, anything out of `implicitRootLayout` — is always too late. The value rides the SSR classic bootstrap
+  script instead, the one thing guaranteed to run ahead of every module script, and is omitted when it matches
+  what the bundle already assumes. `akan.config.ts` is what a Capacitor bundle or a statically served CSR shell
+  follows, because neither is rendered by a server that could tell it otherwise.
+- **A prefix is a path segment.** A blank value or a bare `/` is refused: `/` would be mounted ahead of the SSR
+  catch-all and swallow every page route. A prefix whose first segment is a declared basePath is refused at
+  `init()` for the same reason in the other direction.
+- **The prefix is fixed before `init()`.** `setPrefix` / `setWebsocketPrefix` throw once the server has started,
+  because `init()` is where the route table and the devtools routes are built.
+- `robots.txt`, the locale redirect's API bypass and the OpenAPI `servers` URL all derive from it. The blob
+  storage default (`/api/localFile/getBlob`) does **not**: those URLs are stored in rows, so moving the prefix
+  does not move what was already written.
+
 ## The Process Model — Gateway And Solo
 
 A container runs one process per replica, a gateway in front of them when there is more than one, and one RSC

package/incrementalBuilder.proc.js

@@ -1,9 +1,10 @@
 // @bun
 import {
+  CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-k1n0h7dk.js";
-import"./index-ayy5ecax.js";
+} from "./index-q8sn827n.js";
+import"./index-q0y2jq9j.js";
 import"./index-6wwzs1bc.js";
 import {
   GraphClientEntryDiscovery,
@@ -11,7 +12,7 @@ import {
   AutoImportSync,
   DevChangePlanner,
   DevGeneratedIndexSync
-} from "./index-x23688ar.js";
+} from "./index-w8kmx1b6.js";
 import {
   HmrWatcher,
   WatchRootResolver
@@ -352,12 +353,14 @@ class IncrementalBuilder {
     if (rawKinds.size === 0)
       return;
     const generation = ++this.#generation;
-    const autoImport = await this.#autoImportSync.syncForBatch(batch.files);
+    const [autoImport, indexSync] = await CodegenLock.run(this.#app.workspace.workspaceRoot, `hmr-batch:${this.#app.name}`, async () => {
+      const auto = await this.#autoImportSync.syncForBatch(batch.files);
+      return [auto, await this.#generatedIndexSync.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);
     await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
     const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,

package/{index-5y7qba1c.js → index-0emb9eat.js}

@@ -7,10 +7,10 @@ import {
   isScannedRootEntry,
   AppExecutor,
   LibExecutor
-} from "./index-k1n0h7dk.js";
+} from "./index-q8sn827n.js";
 import {
   FileSys
-} from "./index-ayy5ecax.js";
+} from "./index-q0y2jq9j.js";
 import {
   collectRecipeSources2,
   scanRecipes2,
@@ -19,7 +19,7 @@ import {
 import {
   workflowRunArtifactPath,
   workflowSyncDir
-} from "./index-saheq2bs.js";
+} from "./index-e82dyeqy.js";
 
 // pkgs/@akanjs/devkit/akanContext.ts
 import { readdir } from "fs/promises";

package/{index-cd5x18qh.js → index-3vvbv974.js}

@@ -1,12 +1,12 @@
 // @bun
 import {
   script
-} from "./index-ft1sfjz0.js";
+} from "./index-cezy7yb3.js";
 import {
   AppExecutor,
   LibExecutor,
   ModuleExecutor
-} from "./index-k1n0h7dk.js";
+} from "./index-q8sn827n.js";
 import {
   compactDiagnostics,
   createPrimitiveWriteReport,
@@ -39,10 +39,10 @@ import {
   hasSignalFactoryEntry,
   insertSignalFactoryEntry,
   addFieldUiPolicyForType
-} from "./index-saheq2bs.js";
+} from "./index-e82dyeqy.js";
 import {
   ModuleScript
-} from "./index-k86zc21w.js";
+} from "./index-9bwhxrqf.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.script.ts
 import { capitalize } from "akanjs/common";

package/{index-v0s24t8j.js → index-5xdqxbn9.js}

@@ -2,15 +2,15 @@
 import {
   runner,
   script
-} from "./index-ft1sfjz0.js";
+} from "./index-cezy7yb3.js";
 import {
   generatedFilesForSync,
   createPassedPrimitiveReport,
   scalarChangedFiles
-} from "./index-saheq2bs.js";
+} from "./index-e82dyeqy.js";
 import {
   AiSession
-} from "./index-wet2ytnr.js";
+} from "./index-n85fer99.js";
 import {
   Prompter
 } from "./index-h7yw2z9n.js";

package/{index-k86zc21w.js → index-9bwhxrqf.js}

@@ -1,17 +1,17 @@
 // @bun
 import {
   FileSys
-} from "./index-ayy5ecax.js";
+} from "./index-q0y2jq9j.js";
 import {
   AiSession
-} from "./index-wet2ytnr.js";
+} from "./index-n85fer99.js";
 import {
   ModuleExecutor
-} from "./index-k1n0h7dk.js";
+} from "./index-q8sn827n.js";
 import {
   runner,
   script
-} from "./index-ft1sfjz0.js";
+} from "./index-cezy7yb3.js";
 import {
   sourceFile,
   moduleSourcePaths,
@@ -19,10 +19,10 @@ import {
   createPassedPrimitiveReport,
   bilingualLabelForField,
   bilingualDescriptionForField
-} from "./index-saheq2bs.js";
+} from "./index-e82dyeqy.js";
 import {
   PageScript
-} from "./index-1kzsn94d.js";
+} from "./index-mpmyqm1y.js";
 import {
   Prompter
 } from "./index-h7yw2z9n.js";

package/{index-ft1sfjz0.js → index-cezy7yb3.js}

@@ -1,4 +1,7 @@
 // @bun
+import {
+  FileSys
+} from "./index-q0y2jq9j.js";
 import {
   Executor,
   WorkspaceExecutor,
@@ -6,10 +9,7 @@ import {
   LibExecutor,
   PkgExecutor,
   ModuleExecutor
-} from "./index-k1n0h7dk.js";
-import {
-  FileSys
-} from "./index-ayy5ecax.js";
+} from "./index-q8sn827n.js";
 import {
   getDirname2
 } from "./index-6wwzs1bc.js";
@@ -51,6 +51,7 @@ var normalizePrimitiveArgType = (type) => {
   throw new Error(`Invalid primitive argument type: ${type}`);
 };
 var App = createInternalArgToken("App");
+var Apps = createInternalArgToken("Apps");
 var Lib = createInternalArgToken("Lib");
 var Sys = createInternalArgToken("Sys");
 var Exec = createInternalArgToken("Exec");
@@ -59,11 +60,29 @@ var Module = createInternalArgToken("Module");
 var Workspace = createInternalArgToken("Workspace");
 
 // pkgs/@akanjs/devkit/commandDecorators/command.ts
-import path from "path";
+import path2 from "path";
 import { Logger } from "akanjs/common";
 import chalk2 from "chalk";
 import { program } from "commander";
 
+// pkgs/@akanjs/devkit/appSelectionMemory.ts
+import path from "path";
+class AppSelectionMemory {
+  static pathIn(workspaceRoot) {
+    return path.join(workspaceRoot, "local", ".akan", "lastStart.json");
+  }
+  static async read(workspaceRoot) {
+    const stored = await Bun.file(AppSelectionMemory.pathIn(workspaceRoot)).json().catch(() => null);
+    const apps = stored?.apps;
+    return Array.isArray(apps) ? apps.filter((name) => typeof name === "string") : [];
+  }
+  static async write(workspaceRoot, apps) {
+    await FileSys.writeJson(AppSelectionMemory.pathIn(workspaceRoot), { apps }).catch(() => {
+      return;
+    });
+  }
+}
+
 // pkgs/@akanjs/devkit/commandDecorators/dependencyBuilder.ts
 var capitalize = (value) => value.slice(0, 1).toUpperCase() + value.slice(1);
 var createDependencyKey = (refName, kind) => `${refName}${capitalize(kind)}`;
@@ -261,6 +280,8 @@ var formatCommandHelp = (command, key) => {
       return "";
     if (arg.type === "Module")
       return "[sys:module]";
+    if (arg.type === "Apps")
+      return "[apps...]";
     if (arg.type === "Argument") {
       return `[${camelToKebabCase2(arg.name)}]`;
     }
@@ -287,6 +308,9 @@ var formatCommandHelp = (command, key) => {
       } else if (arg.type === "Module") {
         argName = "sys:module";
         argDesc = "Module in format: app-name:module-name or lib-name:module-name";
+      } else if (arg.type === "Apps") {
+        argName = "apps...";
+        argDesc = "App names, space- or comma-separated, or all. Omit to pick them interactively";
       } else {
         argName = arg.type.toLowerCase();
         argDesc = `${arg.type} name in this workspace`;
@@ -380,6 +404,7 @@ var prompts = async () => await import("@inquirer/prompts");
 var select = (config, context) => prompts().then((m) => m.select(config, context));
 var confirm = (config, context) => prompts().then((m) => m.confirm(config, context));
 var input = (config, context) => prompts().then((m) => m.input(config, context));
+var checkbox = (config, context) => prompts().then((m) => m.checkbox(config, context));
 var assertEnumChoice = (argMeta, value) => {
   const enumChoices = argMeta.argsOption.enum;
   if (!enumChoices || typeof enumChoices === "function")
@@ -474,6 +499,31 @@ var assertCurrentDirectoryIsWorkspaceRoot = async () => {
   ].join(`
 `));
 };
+var parseAppNameList = (value) => (Array.isArray(value) ? value : value === undefined ? [] : [value]).flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter(Boolean);
+var getAppsArgumentValue = async (value, workspace) => {
+  const appNames = await workspace.getApps();
+  if (appNames.length === 0)
+    throw new Error("No apps found in this workspace (apps/<appName>/akan.config.ts)");
+  const requested = parseAppNameList(value);
+  if (requested.includes("all"))
+    return appNames.map((name) => AppExecutor.from(workspace, name));
+  if (requested.length) {
+    const unknown = requested.filter((name) => !appNames.includes(name));
+    if (unknown.length)
+      throw new Error(`Unknown app${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Available: ${appNames.join(", ")}, all`);
+    return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
+  }
+  if (appNames.length === 1 && appNames[0])
+    return [AppExecutor.from(workspace, appNames[0])];
+  const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
+  const picked = await checkbox({
+    message: "Select the apps to run (space to toggle, enter to confirm)",
+    choices: appNames.map((name) => ({ name, value: name, checked: remembered.has(name) })),
+    required: true
+  });
+  await AppSelectionMemory.write(workspace.workspaceRoot, picked);
+  return picked.map((name) => AppExecutor.from(workspace, name));
+};
 var getInternalArgumentValue = async (argMeta, value, workspace) => {
   if (argMeta.type === "Workspace")
     return workspace;
@@ -578,7 +628,7 @@ var runCommands = async (...commands) => {
     process.exit(1);
   });
   const __dirname2 = getDirname2(import.meta.url);
-  const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname2}/../package.json`];
+  const packageJsonCandidates = [`${path2.dirname(Bun.main)}/package.json`, `${__dirname2}/../package.json`];
   let cliPackageJson = null;
   for (const packageJsonPath of packageJsonCandidates) {
     if (!await FileSys.fileExists(packageJsonPath))
@@ -625,6 +675,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
             continue;
           else if (argMeta.type === "Module") {
             programCommand = programCommand.argument(`[sys-name:module-name]`, `${argMeta.type} in this workspace (apps|libs)/<sys-name>/lib/<module-name>`);
+          } else if (argMeta.type === "Apps") {
+            programCommand = programCommand.argument(`[apps...]`, `apps in this workspace apps/<appName>, or all (space- or comma-separated; omit to pick interactively)`);
           } else {
             const sysType = argMeta.type.toLowerCase();
             programCommand = programCommand.argument(`[${sysType}]`, `${sysType} in this workspace ${sysType}s/<${sysType}Name>`);
@@ -649,10 +701,17 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
               commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt, commandContext);
             else if (argMeta.type === "Argument")
               commandArgs[argMeta.idx] = await getArgumentValue(argMeta, cmdArgs[argMeta.idx]);
+            else if (argMeta.type === "Apps")
+              commandArgs[argMeta.idx] = await getAppsArgumentValue(cmdArgs[argMeta.idx], workspace);
             else
               commandArgs[argMeta.idx] = await getInternalArgumentValue(argMeta, cmdArgs[argMeta.idx], workspace);
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = commandArgs[argMeta.idx].name;
+            else if (Array.isArray(commandArgs[argMeta.idx])) {
+              const apps = commandArgs[argMeta.idx];
+              if (apps.length === 1 && apps[0])
+                process.env.AKAN_PUBLIC_APP_NAME = apps[0].name;
+            }
             assignCommandContext(commandContext, argMeta, commandArgs[argMeta.idx]);
             if (opt.verbose)
               Executor.setVerbose(true);
@@ -772,4 +831,4 @@ function command(refName, depsOrBuilder, builder) {
   }
   return CommandBase;
 }
-export { getTargetMetas, getTargetCommandNames, App, Lib, Sys, Exec, Pkg, Module, Workspace, CommandContainer, runner, script, runCommands, command };
+export { getTargetMetas, getTargetCommandNames, App, Apps, Lib, Sys, Exec, Pkg, Module, Workspace, CommandContainer, runner, script, runCommands, command };