@akanjs/devkit 3.2.0-rc.1 → 3.2.0-rc.3

package/CHANGELOG.md

@@ -34,6 +34,43 @@
   - **`pkgs/akanjs/ARCHITECTURE.md`** pairs a hand-kept walk through the processes and a request with a generated part between markers. `akan sync-architecture` regenerates that part, and a devkit test fails when it is stale, when a channel is gone, when two facets load values from each other, when a message lacks a recognised sender or handler outside a short list whose other end lies beyond the framework source, or when the hand-kept part names a class the source no longer has.
   - **`AkanIpcMessage` no longer lists `backend-ready`.** The gateway sends it to the dev host, which reads it as a `BuilderMessage`, where it stays; no gateway or child ever handled it.
 
+- 4d61170: The Akan Graph follows an app's adaptor wiring further. `applyAdaptor(LlmAdaptorRole, ChatCompletionsLlm)` in an app's or lib's `option.ts` draws a `binds` edge from the role, `adaptor::LlmAdaptorRole`, to the implementation it binds, labelled with the app or lib and located at the call, so a method that calls a plugged role reaches the class that answers it. `get_graph` scoped to an app keeps that app's own bindings, and a lib's binding of a role the app does not bind itself; scoped to a lib or a module it keeps every binding of a role it reaches. A Change Map carries every binding of a role it shows, changed or not, so the binding an app runs stays in view; a binding the app removed no longer hides the lib binding it now runs; and Studio's Change Map for one app keeps only the bindings that app runs. An app service holds the fields its module's lib services plug (`...user.services`), so `this.notifier.getMemo()` in an app method links to the `Notifier` a lib's `MemoService` plugs, where it linked to the `memo` model; a service whose own builder declares the field (`notifier: use<…>()`) inherits nothing. A plug imported from a package outside the workspace, `plug(Stripe)` from `stripe-sdk`, or through a lib's re-export of it (`export { Stripe }`, `export { default as Stripe }`, or `export * from "stripe-sdk"` where the lib declares no `Stripe` itself), is `adaptor:stripe-sdk:Stripe` with the package in `detail`, where it linked to a same-name adaptor the app declares or to an unlocated `adaptor:libs/util:Stripe`. Two adaptors with the same class name in one app or lib are two nodes, each with its own location, digest and `plugs`, and a plug reaches the one its import names. A job's `detail` lists only the options its kind honours: `once` on an `initialize` job, `unlocked` on an `interval` job (`Bun.cron` never overlaps a cron job, so `lock: false` changes nothing there); `cron("0 * * * *" as const)` reads `0 * * * *`.
+
+  Ids and details that change for a saved graph or a Change Map base:
+
+  - While two adaptors of one owner share a class name, each is keyed by its file, `adaptor:apps/demo:srvkit/clockB.ts#Clock`; an adaptor whose name no other adaptor of its owner shares keeps `adaptor:<owner>:<Name>`. The Change Map treats the two forms of one declaration as one node, so a second same-name adaptor shows as one added node, not a removal of the first.
+  - A plug from a non-workspace package is `adaptor:<package>:<Name>` with the package as `detail`, where it was `adaptor::<Name>` or a workspace adaptor of that name.
+  - A job's `detail` drops `once` and `unlocked` where the runtime ignores them, and `as const` from a cron expression.
+
+  - **`binds`** joins `AkanGraphEdgeKind` in `akanjs/common`.
+  - **`FileFacts.adaptorBindings`** in `@akanjs/language`: each `applyAdaptor(role, adaptor)` call a file makes; `AkanIndex.setFile` also reads non-test files whose text mentions `applyAdaptor`. **`ServiceClassFact.fields`**: the names a service's builder declares.
+
+- c723713: The Akan Graph keys a guard function by the file that declares it, locates more of a workspace's guards, and stops counting things that are not guards.
+
+  A guard function a route or layout imports is keyed by its file, as one the page declares already was: `guard:libs/shared:webkit/signedIn.ts#signedIn`. A `canEdit` in `webkit/` and one in `common/` are two nodes, each at its own declaration, and an edit to either marks only that one changed in the Change Map. A guard called through a namespace import (`auth.signedIn()`), or imported under a name a file re-exports (`export { signedIn as hasSession } from "./auth"`), reaches its declaration. A function the guard declares, or a parameter it binds, shadows an import of the same name only inside its own scope, so `[1].forEach((signedIn) => …)` no longer hides a real `signedIn()` beside it. A guard declared after another declarator (`export const ready = true, signedIn = …`) is found, and an overloaded guard's digest covers every signature. Only a file whose text declares or re-exports the name is parsed, so a guard that calls `usePage()` from the generated client no longer parses every page that names it.
+
+  A function is a guard factory only when it returns a guard, a class that implements `Guard` (also one handed to a wrapper, `withName(class implements Guard {…}, field)`) or a call to a factory, so `const guardCount = countGuards()` is no longer a guard. An import from a package outside the workspace (`@vendor/auth`) resolves to no guard: it no longer links a same-name workspace guard, and a vendor's `Public` no longer reads as the framework's. A factory imported from akanjs or a package makes no guard. A lib's `export *` chain, walked from the path the import names, is followed only when it reaches exactly one workspace lib declaring the name, none of its `export *` names a package, and the lib does not declare, destructure or export the name itself; otherwise the guard stays `guard:<lib>:<Name>` without a location, so a vendor shim no longer links another lib's guard. A class extending a base that is not a known guard is no guard, even when a lib declares a guard of that name.
+
+  More guards carry their location: a name a lib re-exports under another name (`export { Admin as AdminGuard }`) reaches the class, and one it re-exports from akanjs is `guard::Public`; `srvkit.SSO.Kakao` reads through the namespace to the lib's map; a map entry a factory makes (`SSO = { Kakao: ssoGuardOf("kakao") }`) is the guard `SSO.Kakao`; a local wrapper of an imported factory, a factory called through a namespace (`srvkit.resourceGuard("pin")`) and a class that extends a guard (`class DemoAdmin extends Admin`) and a factory a lib re-exports under another name (`export { resourceGuard as rg }`) make guards; a guard made in place, `guards: [canEdit("memo")]`, is a node at the call, keyed by its member, callee and ordinal so an edit to its arguments, or to another member's guards, keeps the id. Of two same-name guards in one owner, an import reaches the one its path names. A wrapper's digest covers every factory it can return, and an edit to a factory in another file marks the guards it makes changed instead of listing the file as unmapped.
+
+  In the Change Map, a declaration whose id moves between `kind:owner:Name` and `kind:owner:<file>#Name` at the same file is one node, so a second same-name guard shows as one addition, not the first one removed and re-added.
+
+  `get_graph` past the node limit names owners by the nodes it would answer with, changed pages included, so 650 changed routes no longer hide behind one changed lib method. A guard on `const route = page()…; export default route` is no longer read: `RouteSourceValidator` rejects that shape.
+
+  Ids and details that change for a saved graph or a Change Map base:
+
+  - An imported guard function's id names its file: `guard:libs/shared:signedIn` is now `guard:libs/shared:webkit/signedIn.ts#signedIn`.
+  - A guard name two files of one owner declare is keyed by file, `guard:apps/demo:srvkit/admin.ts#Admin`.
+  - A guard made in place is `guard:<owner>:<file>#<model>.<key>:<callee>@<n>`, the `n`th in-place call of that callee in that slice or endpoint key (`…/memo.signal.ts#memo.shareMemo:resourceGuard@1`). Its label, an endpoint's `detail` and the editor hover name the call: `resourceGuard("memo")` where `detail` read `resourceGuard`, or `allow(…)` when the arguments run past 32 characters or a line. A guard read through a namespace's map reads `srvkit.SSO.Kakao` where it read `Kakao`.
+  - A map entry a factory makes is `guard:libs/shared:SSO.Kakao` where it was `guard::Kakao` or `guard:<lib>:Kakao`, and a local map's `Roles.Owner` is `guard:apps/demo:Roles.Owner` where it linked `guard:apps/demo:Owner`.
+  - A guard a lib re-exports, under its own name or another, or from akanjs, takes the declaring owner's id (`guard:libs/util:Admin`, `guard::Public`) where it took the re-exporting lib's.
+  - A guard imported from an unknown package draws no edge.
+  - A name the old "sole visible lib" fallback linked through a lib that does not declare it (`guard:libs/billing:Admin` behind a vendor `export *`) now reads `guard:<lib>:<Name>` without a location, unless the lib's `export *` chain reaches exactly one workspace lib declaring it.
+  - A class extending a base that is not a known guard (`class Thing extends Base` with an ordinary `Base`) no longer has a guard node; an endpoint naming it in `guards` links an unlocated `guard:<owner>:Thing`.
+
+  - **`AkanGraphNode.sources`** in `akanjs/common`: the files besides `at.file` that a node's digest reads, set only with digests. The Change Map uses it to map those files and leaves it out of its answer.
+  - **The fact reader** in `@akanjs/language`: `GuardFactoryFact.via` is a list and gains `direct`; `GuardCallFact` gains `kind` (`call` or `extends`) and `scope`; `FileFacts` gains `guardLabels`, an in-place guard's name to its call. A slice's or endpoint's guard made in place is read as `<model>.<key>:<callee>@<n>`, and every in-place call is a `GuardCallFact`.
+
 - 0351ad4: The Akan Graph keys each guard by the app or lib that declares it, `guard:libs/shared:Admin`, and follows the import that names it there, so `Admin as AdminGuard` reaches `Admin`, `srvkit.Admin` reaches the lib's class, and two libs' `Admin` stay two nodes. A guard read out of an object map, `SSO.Kakao`, resolves through the imports of the file that declares the map. A name a lib only re-exports reaches the class it re-exports. A guard a factory makes is a guard too, whether the factory sits in the same file, wraps another factory there, or is imported from another lib. A guard node carries its source location, `doc` (the comment above its declaration that says what it checks) and, in `detail`, its `scope` (`account` or `resource`). A factory-made guard takes the factory's scope, and takes its doc when no guard of that factory has its own. With digests, an edit to a guard or to the factory that makes it marks the guard changed in the Change Map. Every guard a workspace declares is a node, referenced or not. `Public` and `None` come from `akanjs`, carry no location and say what they do. Studio shows a node's `doc` in its tooltip.
 
   Ids and details that change for a saved graph or a Change Map base:
@@ -128,6 +165,7 @@
   - **`@akanjs/devkit`**: `applyTemplate` takes `dryRun` to list the files a template would write without writing them, and `WorkspaceExecutor.commit` takes an `identity` to commit under.
 
 - 1870fcd: `akan verify` adds a `fix:` line to a module file's two-parent import that names the layer barrel to import from instead, such as `import from "@apps/<app>/common"`. The lint message itself now points at the layer barrel too.
+- 76ab8d4: `akan doctor` exits with code 1 when its report says `"status": "failed"`, in text or JSON, with or without `--strict`, and for `--ios`, so the `agent:doctor` script (`akan doctor --strict --format json`) or a CI step fails on it. Before, it always exited 0. The full report still prints on stdout. A warning never changes the exit code: `--strict` still only decides which conventions count as errors, today a missing module abstract. Doctor's `dictionary-label-missing` now reads a constant's fields from its syntax, so a field that appears only in a comment or a string no longer asks for a label. A new `--sample` workspace no longer warns about `task`'s `priority`, `tags`, `assignee` and `completedAt` or `workHistory`'s `actor` and `previousStatus`, which its constants suggest only in comments.
 - 245d318: A font declared on a root layout now gets its metric-adjusted fallback faces: `@font-face` rules named `"<font> fallback"` that draw a local system font with `size-adjust`, `ascent-override` and `descent-override` matched to the web font. The variable `--font-<name>` already named that family, but the build never wrote it, because fontaine's `readMetrics` takes a URL and returned nothing for the file path it was given. While a web font loaded (`font-display: swap`), text drew in the browser's default font, usually a serif, and moved when the web font arrived. The metrics are read from the source font, not the subset, so a subset without Latin letters (`subsets: ["ks-x-1001"]`, or only `subsetText`) still sizes the fallback correctly. A font whose metrics cannot be read keeps its face and gets no fallback, as before. Set `adjustFontFallback: false` on a font to keep the old output. Cached font output from `akan start` is regenerated once.
 - 6f6cc2a: A fresh clone of a workspace now builds and starts after `bun install` alone. The env files that hold secrets stay gitignored, so a clone has none of them: before, `akan typecheck`, `akan build` and `akan verify` failed with `Cannot find module './env.server.local'`, and with no `.env` the CLI picked the `debug` environment, so `akan build` stopped asking for `AKAN_PUBLIC_REPO_NAME` and `AKAN_PUBLIC_SERVE_DOMAIN`.
 
@@ -177,11 +215,14 @@
   - **The CSR build and its MCP App views** rewrite `akanjs/ui` imports to the components a file names, as the SSR route builds already did, so a page that imports `Link` no longer bundles every component.
   - **Animations use `@react-spring/web`** instead of the `react-spring` umbrella package, which also installed the native, three.js, konva and zdog renderers.
 
+- 58b7329: `akan create-scalar`, `remove-scalar`, `create-module`, `create-service`, `create-application`, `create-library`, `install-library` and `create-workspace --app` refuse a name that is not one plain path segment before they touch a file, such as `"../.." is no scalar name; use letters, digits, - and _, starting with a letter`. Before, the name went into the path unchecked: `akan remove-scalar ../.. <app>` deleted `apps/<app>` and exited 0, and the create commands wrote their files outside `lib/`, `apps/` or `libs/`. A scalar, module or service name is checked as a workflow's `module` input already was, an app or lib name as its `app` input; both checks now live in `@akanjs/devkit/workflow/plainName`, with `assertPlainName`.
+- b4b8f85: `akan preview` and the code agent's page preview give a browser that died or was closed the full `startTimeoutMs` (120 s by default) for its next start. Before, after one page had run out of the start bound, a browser that then died while another page waited for it stayed marked as slow to start. The next page started a fresh browser within only its own `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
 - 686e0b8: `akan preview` and the code agent's page preview bound a page only once the browser is up. Before, a process's first page shared its `timeoutMs` with starting the browser. On a cold machine where Chrome took longer than that to start, the first page failed as `Timed out loading …; the dev server may be rebuilding or stuck.`
 
   Starting the browser now has its own bound of 120 s, `startTimeoutMs` on `PreviewView.probe`. Running out of it reads `Timed out starting the <engine> browser after 120 s.`, where the engine is `chrome` or `webkit`. A browser that misses its bound may still come up late, so later pages in that process try again, but each waits only its own `timeoutMs` for the browser. Once the browser answers, the full bound applies again. So a browser that never starts holds the first page for 120 s, where before it held it for `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
 
 - eefd9cb: `akan preview <app> /_akan/studio` opens Studio instead of a 404. Preview added the default locale to every path, and the server routes `/_akan/*` without one, so `/en/_akan/studio` matched no page. A path under `/_akan`, `/__csr`, `/__rsc`, `/.well-known` or the app's API prefix, a file the app's `public/` holds, and the server's own `/favicon.ico`, `/robots.txt`, `sitemap.xml` and `manifest.webmanifest` now open as written: no locale, and no CSR boot query under `--csr`. Every other path, including one that already starts with a locale or ends in a dotted segment such as `/release/1.2.3`, is a page and gets the default locale as before. The `akan-debug` skill and the `akan preview` reference say so.
+- b101fcf: `akan remove-application`, `remove-library`, `remove-package`, `remove-module` and `remove-scalar` no longer delete a target they picked themselves. Left out, or named but not in the workspace, the target is refused in a terminal or not, with the choices and the line to rerun, such as `` Missing app: this command deletes files and never picks its target, so rerun it as `akan remove-application <app>` (choices: pokedex). `` Before, `akan remove-application` in a one-app workspace removed `apps/<app>` without asking, and without a terminal `akan remove-scalar <name>` removed the scalar from the only app or lib. A terminal is no longer offered a select for these commands. Other commands still take the only app, or the only app or lib without a terminal, as before. A command declares this with `destructive: true` on its target.
 - 4fcf44f: A new `rename-key` workflow renames a slice key or a Filter query key everywhere it is spelled. That covers the key itself, every name derived from it (`initMemoInPublic`, `memoListInPublic`, `queryByName`) in the app and every lib, and its module dictionary entry. It is the same rename the editor extension's F2 runs, so agents get it through `plan_workflow` / `apply_workflow` and the CLI through `akan workflow plan rename-key --app <app> --module <module> --slice <key> --to <newKey>` (or `--query <key>`). The plan lists each file it will change. A use that could also be another model's is left alone, and `akan verify` then reports it.
 - 9a9e1fa: A server page from `akan build` now preloads its client modules from `<head>`, so a cold load stops waiting on chains of imports.
 
@@ -263,8 +304,13 @@
   - **Bootstrap.** Each route's `"use client"` entry, every generated root layout and the SSR dev registry start with `import "@apps/<app>/lib/useClient"` and `import "@apps/<app>/lib/st"`, which load the client runtime and the store. They used to import `@apps/<app>/client` bare, and that bundled the whole barrel.
   - **Narrowed barrel imports.** A named import from an app or lib `client` barrel is still narrowed to the files that define the names. This includes `import { st } from "@apps/<app>/client"` in a component and the generated `import { RootStore as <lib> } from "@libs/<lib>/client"` in `lib/st.ts`.
     - What the rewrite keeps of the barrel is now the files that define its `usePage` and `st`, normally `lib/useClient` and `lib/st`. It used to keep a bare import of the barrel itself, which put every module's UI of the app and of each merged lib on every route.
-    - A barrel that defines neither name keeps its bare import, as before.
+    - A barrel that lacks either name keeps its bare import, as before. One that defines only one of them is not the generated shape, so what else it runs on import is unknown.
   - **Namespace re-exports.** A name the barrel re-exports as a namespace (`export * as cnst`, `export * as store`) is now narrowed too. `import { cnst } from "@libs/<lib>/client"` becomes `import * as cnst from "@libs/<lib>/lib/cnst"`, where it used to load the whole barrel.
+  - **`akan start`.** The dev module registry narrows app and lib barrels the same way, so a page loads in dev the module UI it loads in production. The narrowed imports are written as relative paths, so a save that adds a barrel import still updates the page without a full rebuild. `akanjs` barrels stay whole in dev: in an installed workspace their files are npm modules, and a save that reached a new one would rebuild the whole registry.
+    - On `apps/minimal`, the registry behind `/en/explore`, `/en/memo` and `/en/lab/data` holds 505 modules (2.5MB app, 1.2MB vendor), down from 949 (2.6MB app, 6.0MB vendor).
+    - Moving an export to another file of a barrel compiles again the importers whose names now point at that file, and only those. This works during `akan start` and on the next start after a move made while it was stopped.
+    - Client entry discovery under `akan start` reads a barrel again when one of its files changes. An export moved into a `"use client"` file is found without a restart.
+  - **CSR shell and MCP App views.** The single-file CSR build that native apps load, and each MCP App view, narrow app and lib barrels too; they used to narrow only `akanjs/ui`. On `apps/minimal` the CSR shell is 1.58MB raw / 411.9K br, down from 3.51MB / 828.8K, and its MCP App views are 20-29% smaller.
   - **Discovery and Tailwind.** Client entry discovery and Tailwind's candidate scan follow the same imports. A lib `"use client"` component is no longer a client entry of every route, and a module UI file that no route imports is no longer scanned.
   - **Size.** Production build of `apps/minimal`:
     - A route that renders only `Link` ships 53.1K raw / 17.2K br of route code, down from 226.6K / 67.1K.
@@ -288,11 +334,14 @@
     - The rule's own rewrite is removed. Under `--unsafe` it renamed a `#field` where it was called but not where it was declared.
   - **A raw `Error` in an `srvkit/` adapter names its fix.** `akan verify` prints the `Err` import path from that file, and where the key goes: the app's or lib's own service dictionary, `lib/_<name>/<name>.dictionary.ts`, as `<name>.error.<key>`.
 
+- d2b2291: A failed workflow no longer reports success to its caller. `akan workflow plan` exits 1 when the plan has an error, `akan workflow apply` when the apply or its `--dry-run` fails, and `akan workflow validate` when its status is `failed` (which includes `passed-with-baseline-blockers`); all three exited 0 before. A dry run of a plan with an error, such as `add-field --type Number`, reports `failed` and lists no changed or generated files, where it used to list the plan's edits under "Automatically Modified". Over MCP, `plan_workflow` names `apply_workflow` in `next` and `approval.canApplyWith` only for a plan without an error, and `apply_workflow` names `run_validation` only when the apply did not fail; a refused plan also drops its "apply this plan" and "validate the apply report" recommendations. The workflows that write into an existing module (`add-field`, `add-enum-field`, `add-mutation`, `add-slice`, `create-ui`, `rename-key`) now refuse a service module, or any folder without its `<module>.constant.ts`, at plan time and again at apply. The `workflow-module-not-database` error lists the target's database modules and points at `create-module`, and for a field at `create-scalar`. Before, `add-field` on a service module passed its plan and dry run and failed only at apply, and `create-ui` wrote a misnamed `_<service>.View.tsx` into it. The `workflow-module-missing` error now lists only database modules too, says a name that matches a service module (with or without its `_`) is one instead of asking "Did you mean \_<service>?", and points at another app or library only when it holds a database module of that name.
 - adcdf3b: `akan workflow plan` and the `plan_workflow` MCP tool refuse a module the target app or library lacks, for every workflow that writes into an existing module (`add-field`, `add-enum-field`, `add-mutation`, `add-slice`, `create-ui`, `rename-key`). The `workflow-module-missing` error names the module, lists the modules the target has, and points at the module whose name differs only in case or by a leading `_`, at a scalar of that name, or at the app or library that holds it; only when none exists does it point at `create-module`. Before, the plan passed and its dry run reported `passed`. `add-mutation` used to plan a missing module with a warning so that a `create-module` plan could precede it; it now refuses too, so plan it after applying `create-module`. Every workflow now refuses an unknown `app` at plan time, listing the workspace's apps and libraries. `apply` and `--dry-run` check the target again before anything else, so a plan written earlier for a module that is gone fails instead of passing. `plan_workflow` now inspects the MCP server's workspace rather than the process directory.
 - Updated dependencies [bc792ab]
 - Updated dependencies [61fbd7d]
 - Updated dependencies [b3f85fa]
 - Updated dependencies [a707354]
+- Updated dependencies [4d61170]
+- Updated dependencies [c723713]
 - Updated dependencies [0351ad4]
 - Updated dependencies [ba417c6]
 - Updated dependencies [bb40785]
@@ -346,7 +395,9 @@
 - Updated dependencies [5e08722]
 - Updated dependencies [df32c46]
 - Updated dependencies [5f809e8]
+- Updated dependencies [76705dd]
 - Updated dependencies [206bb69]
+- Updated dependencies [e4c7e5c]
 - Updated dependencies [6291fec]
 - Updated dependencies [0c480c6]
 - Updated dependencies [d9eaacc]

package/akanContext.ts

@@ -2,6 +2,7 @@ import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { capitalize, isRecord, parseRouteModuleKey } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
+import { constantFieldNames } from "./constantFieldNames";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
@@ -337,9 +338,6 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
   ];
 };
 
-const constantFieldNames = (content: string) =>
-  [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
-
 const safeReadDir = async (dirPath: string) =>
   (await readdir(dirPath, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
 

package/akanMcpContract.ts

@@ -199,7 +199,7 @@ export const defaultWorkflowPlanPath = (workflow: string, inputs: WorkflowPlanIn
 export const applyFirstPolicy = {
   mode: "apply-first",
   directSourceEdits: "fallback-only",
-  applyRequiredWhen: ["plan_workflow returns planPath", "plan_workflow returns next.tool=apply_workflow"],
+  applyRequiredWhen: ["plan_workflow returns next.tool=apply_workflow"],
   approvalMeaning:
     "requiresApproval is an agent/user review signal before apply_workflow mutates files; it is not a separate MCP permission gate.",
   validationRequiredAfterApply: ["validationTarget", "applyReportPath"],
@@ -324,7 +324,7 @@ export const readonlyMcpTools: McpToolDefinition[] = [
   {
     name: "get_graph",
     description:
-      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with the guards they name (each guard keyed by the app or lib that declares it, with its scope and the comment that says what it checks), the service methods and queries each calls, the store actions that fetch them, and the components and routes that use them. A module's jobs (internal: interval, cron, timeout, initialize, destroy, process) read their schedule and server or operation modes and call service methods like endpoints do; each adaptor a service plugs (an adapt() class, or an akanjs role) is a node, a method that calls it links to it, and an adaptor links to the adaptors it plugs itself. Each page/ file is a route (its URL pattern after the locale) or a layout, layouts wrap what they contain, and a route or layout that runs .guard() reads `guard` and links each function its guard calls; a layout's guard gates every route it wraps. A graph too large to answer unscoped drops first the routes and layouts that neither changed nor use a change; app or module brings them back. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
+      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with the guards they name (each guard keyed by the app or lib that declares it, with its scope and the comment that says what it checks), the service methods and queries each calls, the store actions that fetch them, and the components and routes that use them. A module's jobs (internal: interval, cron, timeout, initialize, destroy, process) read their schedule and server or operation modes and call service methods like endpoints do; each adaptor a service plugs (an adapt() class, or an akanjs role) is a node, a method that calls it links to it (an app service holds the fields its module's lib services plug, unless it declares the field itself), an adaptor links to the adaptors it plugs itself, a class from a package outside the workspace is adaptor:<package>:<Name>, and a role an app binds with applyAdaptor(Role, Impl) links to that implementation (binds, labelled with the app; a scope keeps its app's bindings). Each page/ file is a route (its URL pattern after the locale) or a layout, layouts wrap what they contain, and a route or layout that runs .guard() reads `guard` and links each function its guard calls; a layout's guard gates every route it wraps. A graph too large to answer unscoped drops first the routes and layouts that neither changed nor use a change; app or module brings them back. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
     inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty, since: stringProperty } },
   },
   {
@@ -371,7 +371,7 @@ export const planMcpTools: McpToolDefinition[] = [
   {
     name: "plan_workflow",
     description:
-      "Create a read-only workflow plan after context inspection and return planPath plus next.tool=apply_workflow.",
+      "Create a read-only workflow plan after context inspection and return planPath, plus next.tool=apply_workflow unless a diagnostic is an error.",
     inputSchema: {
       type: "object",
       properties: { workflow: stringProperty, inputs: objectProperty, out: stringProperty },
@@ -383,7 +383,8 @@ export const planMcpTools: McpToolDefinition[] = [
 export const applyMcpTools: McpToolDefinition[] = [
   {
     name: "apply_workflow",
-    description: "Apply a stored workflow plan before direct edits and return validationTarget for run_validation.",
+    description:
+      "Apply a stored workflow plan before direct edits and return validationTarget, plus next.tool=run_validation unless the apply failed.",
     inputSchema: {
       type: "object",
       properties: { planPath: stringProperty, dryRun: booleanProperty },

package/artifact/storeBootstrap.ts

@@ -14,8 +14,9 @@ export class StoreBootstrap {
     if (!/^@(?:apps|libs)\/[^/]+\/client$/.test(specifier)) return null;
     const runtime = exports.get("usePage");
     const store = exports.get("st");
-    if (!runtime || runtime.namespace || !store || store.namespace) return StoreBootstrap.#lines([specifier]);
-    return StoreBootstrap.#lines([...new Set([runtime.subpath, store.subpath])]);
+    //? A barrel with only one of the two is not the generated shape, so what else it runs on import is unknown.
+    if (!runtime || runtime.namespace || !store || store.namespace) return [specifier];
+    return [...new Set([runtime.subpath, store.subpath])];
   }
 
   static #lines(specifiers: string[]): string[] {

package/codeAgent/skills/akan-scaffold/SKILL.md

@@ -37,7 +37,8 @@ Then pick the workflow that matches the intent:
 
 ## The chain
 
-Each result names the next call in `next.tool`. Follow it; do not improvise.
+Each result names the next call in `next.tool`. Follow it; do not improvise. A result with an error diagnostic, or
+an apply that failed, names none: do what the diagnostic says, then plan again.
 
 1. `plan_workflow({ workflow: "create-module", inputs: { app: "<app>", module: "comment" } })` — read-only.
    Returns `planPath` and `next.tool=apply_workflow`. (`list_workflows` / `explain_workflow` give the names

package/commandDecorators/command.ts

@@ -138,16 +138,22 @@ const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
 };
 
 // On a piped stdin a prompt takes the pipe as its answer and echoes it: a piped secret printed as the secret's name.
-export const assertPromptable = (
-  problem: string,
-  { choices = [], remedy = "pass it on the command line" }: { choices?: readonly unknown[]; remedy?: string } = {},
-) => {
+export const assertPromptable = (problem: string, refusal: Refusal = {}) => {
   if (process.stdin.isTTY) return;
-  throw new Error(
-    `${problem}: stdin is not a terminal to prompt on, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`,
-  );
+  throw refusalOf(problem, "stdin is not a terminal to prompt on", refusal);
 };
 
+interface Refusal {
+  choices?: readonly unknown[];
+  remedy?: string;
+}
+
+const refusalOf = (
+  problem: string,
+  reason: string,
+  { choices = [], remedy = "pass it on the command line" }: Refusal,
+) => new Error(`${problem}: ${reason}, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`);
+
 const inputMessageOf = ({ name, argsOption: { desc, example, ask } }: ArgMeta) =>
   ask ? `${ask}: ` : desc ? `${desc}: ` : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
 
@@ -293,11 +299,18 @@ export const getInternalArgumentValue = async (
   value: string | undefined,
   workspace: WorkspaceExecutor,
   rerun?: RerunOf,
+  { destructive = false }: { destructive?: boolean } = {},
 ) => {
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
   const [appNames, libNames, pkgNames] = await workspace.getExecs();
   const problemOf = (kind: string) => (value ? `Unknown ${kind} '${value}'` : `Missing ${kind}`);
+  //? Refused in a terminal too: a select deletes on a stray Enter, its cursor resting on the first choice.
+  const assertAskable = (kind: string, choices: readonly unknown[], placeholder: string) => {
+    const refusal = { choices, ...rerunRemedyOf(rerun, placeholder) };
+    if (destructive) throw refusalOf(problemOf(kind), "this command deletes files and never picks its target", refusal);
+    assertPromptable(problemOf(kind), refusal);
+  };
   if (sysType === "sys" || sysType === "exec") {
     const pkgChoices = sysType === "exec" ? pkgNames : [];
     const execOf = (name: string) => {
@@ -308,14 +321,14 @@ export const getInternalArgumentValue = async (
     };
     const found = value ? execOf(value) : null;
     if (found) return found;
-    if (!value && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
+    if (!value && !destructive && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
       return AppExecutor.from(workspace, appNames[0]);
     const [kind, placeholder] =
       sysType === "exec" ? ["app, lib or pkg", "<app-lib-or-pkg>"] : ["app or lib", "<app-or-lib>"];
     const choices = [...appNames, ...libNames, ...pkgChoices];
     const only = choices.length === 1 ? execOf(choices[0] ?? "") : null;
     //? Not for Lib, Pkg or Module, which name what a command acts on: `akan remove-library` would delete the only one.
-    if (!value && only && !process.stdin.isTTY) {
+    if (!value && !destructive && only && !process.stdin.isTTY) {
       const how = rerun ? `: ${rerun(only.name)}` : "";
       Logger.rawLog(
         `No ${kind} named, so this runs on '${only.name}', the only one in this workspace${how}`,
@@ -324,7 +337,7 @@ export const getInternalArgumentValue = async (
       );
       return only;
     }
-    assertPromptable(problemOf(kind), { choices, ...rerunRemedyOf(rerun, placeholder) });
+    assertAskable(kind, choices, placeholder);
     const name = await select<string>({
       message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
       choices,
@@ -334,19 +347,19 @@ export const getInternalArgumentValue = async (
     return picked;
   } else if (sysType === "app") {
     if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
-    if (!value && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
-    assertPromptable(problemOf("app"), { choices: appNames, ...rerunRemedyOf(rerun, "<app>") });
+    if (!value && !destructive && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
+    assertAskable("app", appNames, "<app>");
     const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
     return AppExecutor.from(workspace, appName);
   } else if (sysType === "lib") {
     if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
-    assertPromptable(problemOf("lib"), { choices: libNames, ...rerunRemedyOf(rerun, "<lib>") });
+    assertAskable("lib", libNames, "<lib>");
     const libName = await select<string>({ message: `Select the ${sysType} name`, choices: libNames });
     return LibExecutor.from(workspace, libName);
   } else if (sysType === "pkg") {
     const pkgs = await workspace.getPkgs();
     if (value && pkgs.includes(value)) return PkgExecutor.from(workspace, value);
-    assertPromptable(problemOf("pkg"), { choices: pkgs, ...rerunRemedyOf(rerun, "<pkg>") });
+    assertAskable("pkg", pkgs, "<pkg>");
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
@@ -368,10 +381,13 @@ export const getInternalArgumentValue = async (
       ...appNames.map((name) => AppExecutor.from(workspace, name)),
       ...libNames.map((name) => LibExecutor.from(workspace, name)),
     ];
-    const choices = process.stdin.isTTY
-      ? []
-      : (await Promise.all(systems.map(async (sys) => (await sys.getModules()).map((m) => `${sys.name}:${m}`)))).flat();
-    assertPromptable(problemOf("module"), { choices, ...rerunRemedyOf(rerun, "<sys:module>") });
+    const choices =
+      process.stdin.isTTY && !destructive
+        ? []
+        : (
+            await Promise.all(systems.map(async (sys) => (await sys.getModules()).map((m) => `${sys.name}:${m}`)))
+          ).flat();
+    assertAskable("module", choices, "<sys:module>");
     const { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -503,6 +519,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
                 cmdArgs[argMeta.idx] as string,
                 workspace,
                 rerun,
+                { destructive: targetMeta.targetOption.destructive },
               );
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;

package/commandDecorators/commandDecorators.test.ts

@@ -551,6 +551,63 @@ describe("a Sys that defaults to the only app", () => {
     );
     expect(asked).toEqual([]);
   });
+
+  test("a destructive command never takes the only app, lib, pkg or module, nor asks, terminal or not", async () => {
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], ["util"], []];
+    workspace.getPkgs = async () => ["tools"];
+    workspace.getDirInModule = async (basePath) => (basePath === "apps/web/lib" ? ["pokemon"] : []);
+    const refusedAs = (rerun: string, choices: string) =>
+      `: this command deletes files and never picks its target, so rerun it as \`${rerun}\` (choices: ${choices}).`;
+    const resolve = (type: InternalArgMeta["type"], commandName: string, operands: (string | undefined)[]) =>
+      getInternalArgumentValue(
+        { key: "", idx: operands.length - 1, type },
+        operands.at(-1),
+        workspace,
+        rerunCommandOf(
+          [commandName, ...operands.filter((operand): operand is string => operand !== undefined)],
+          operands,
+          operands.length - 1,
+        ),
+        { destructive: true },
+      );
+    for (const isTTY of [true, undefined]) {
+      setTTY(isTTY);
+      answer = "web";
+      await expect(resolve("App", "remove-application", [undefined])).rejects.toThrow(
+        `Missing app${refusedAs("akan remove-application <app>", "web")}`,
+      );
+      await expect(resolve("Lib", "remove-library", [undefined])).rejects.toThrow(
+        `Missing lib${refusedAs("akan remove-library <lib>", "util")}`,
+      );
+      await expect(resolve("Pkg", "remove-package", [undefined])).rejects.toThrow(
+        `Missing pkg${refusedAs("akan remove-package <pkg>", "tools")}`,
+      );
+      await expect(resolve("Module", "remove-module", [undefined])).rejects.toThrow(
+        `Missing module${refusedAs("akan remove-module <sys:module>", "web:pokemon")}`,
+      );
+      await expect(resolve("Sys", "remove-scalar", ["place", undefined])).rejects.toThrow(
+        `Missing app or lib${refusedAs("akan remove-scalar place <app-or-lib>", "web, util")}`,
+      );
+      await expect(resolve("App", "remove-application", ["webb"])).rejects.toThrow(
+        `Unknown app 'webb'${refusedAs("akan remove-application <app>", "web")}`,
+      );
+    }
+    expect(asked).toEqual([]);
+  });
+
+  test("a destructive command takes the target it is named, while another still takes the only app", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    const named = await getInternalArgumentValue({ key: "", idx: 0, type: "App" }, "web", workspace, undefined, {
+      destructive: true,
+    });
+    expect(named instanceof AppExecutor ? named.name : null).toBe("web");
+    const taken = await getInternalArgumentValue(sysMetaOf("typecheck"), undefined, workspace);
+    expect(taken instanceof AppExecutor ? taken.name : null).toBe("web");
+    expect(asked).toEqual([]);
+  });
 });
 
 describe("the line a refused target is rerun with", () => {
@@ -573,7 +630,7 @@ describe("the line a refused target is rerun with", () => {
 
 describe("a target left out where no terminal can ask for it", () => {
   const track = tempRoots();
-  const run = async (apps: string[]) => {
+  const run = async (apps: string[], args = ["create-thing", "photo", "--force"]) => {
     const { root } = track(await makeCliTempWorkspace());
     await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
     await writeText(path.join(root, "tsconfig.json"), "{}\n");
@@ -582,7 +639,7 @@ describe("a target left out where no terminal can ask for it", () => {
     await writeText(
       entry,
       [
-        `import { command, runCommands, Sys } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        `import { App, command, runCommands, Sys } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
         'class ThingCommand extends command("thing", ({ public: target }) => ({',
         '  createThing: target({ desc: "creates a thing" })',
         '    .arg("thing", String, { desc: "name of the thing" })',
@@ -591,12 +648,17 @@ describe("a target left out where no terminal can ask for it", () => {
         "    .exec(async function (thing, sys, force) {",
         '      process.stdout.write(thing + " in " + sys.name + ", force " + force + "\\n");',
         "    }),",
+        '  removeThing: target({ desc: "removes an app", destructive: true })',
+        "    .with(App)",
+        "    .exec(async function (app) {",
+        '      process.stdout.write("removed " + app.name + "\\n");',
+        "    }),",
         "})) {}",
         "await runCommands(ThingCommand);",
         "",
       ].join("\n"),
     );
-    const proc = Bun.spawn(["bun", entry, "create-thing", "photo", "--force"], {
+    const proc = Bun.spawn(["bun", entry, ...args], {
       cwd: root,
       stdin: "ignore",
       stdout: "pipe",
@@ -628,6 +690,16 @@ describe("a target left out where no terminal can ask for it", () => {
     expect(refused.stdout).toMatch(/\(choices: (web, admin|admin, web)\)\./);
     expect(refused.stdout).not.toContain("photo in");
   }, 30_000);
+
+  test("a destructive command exits with the line to rerun even when the workspace has one app", async () => {
+    const refused = await run(["web"], ["remove-thing"]);
+    expect(refused.code).toBe(1);
+    expect(refused.stdout).toContain(
+      "Missing app: this command deletes files and never picks its target, so rerun it as `akan remove-thing <app>` (choices: web).",
+    );
+    expect(refused.stdout).not.toContain("removed");
+    expect((await run(["web"], ["remove-thing", "web"])).stdout).toContain("removed web\n");
+  }, 30_000);
 });
 
 describe("the exit code of a command that failed", () => {

package/commandDecorators/targetMeta.ts

@@ -45,6 +45,8 @@ export interface TargetOption {
   stdio?: boolean;
   failureExitCode?: number;
   usageExitCode?: number;
+  /** It deletes files in its app, lib, pkg or module, so one left out or unknown is refused, never picked or asked. */
+  destructive?: boolean;
   /** Runs after the CLI printed a failure and before it exits, so what it writes ends the output. */
   onFailure?: (error: unknown, failure: TargetFailure) => void | Promise<void>;
 }

package/constantFieldNames.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { constantFieldNames } from "./constantFieldNames";
+
+describe("constantFieldNames", () => {
+  test("names each field the code declares, chained or not", () => {
+    const content = `export class TaskInput extends via((field) => ({
+  title: field(String),
+  tags: field(String).list().optional(),
+  workHistory: field([WorkHistory]),
+})) {}
+export class TaskObject extends via(TaskInput, (field) => ({
+  due: field(Date).optional(),
+  total: resolve<number>(),
+})) {}
+`;
+
+    expect(constantFieldNames(content)).toEqual(["title", "tags", "workHistory", "due"]);
+  });
+
+  test("leaves out a field that appears only in a comment or a string", () => {
+    const content = `export class TaskInput extends via((field) => ({
+  title: field(String),
+  // priority: field(TaskPriority, { default: "medium" })
+  /* assignee: field(ID).optional() */
+  note: field(String, { default: "completedAt: field(Date)" }),
+})) {}
+// ---- Expandable additional fields: ----
+//  - actor: field(String).optional() — who performed the action
+export const example = \`previousStatus: field(TaskStatus)\`;
+`;
+
+    expect(constantFieldNames(content)).toEqual(["title", "note"]);
+  });
+});

package/constantFieldNames.ts

@@ -0,0 +1,18 @@
+import ts from "typescript";
+
+const isFieldCall = (node: ts.Expression): boolean =>
+  ts.isCallExpression(node) &&
+  (ts.isIdentifier(node.expression)
+    ? node.expression.text === "field"
+    : ts.isPropertyAccessExpression(node.expression) && isFieldCall(node.expression.expression));
+
+export const constantFieldNames = (content: string) => {
+  const names: string[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && isFieldCall(node.initializer))
+      names.push(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(ts.createSourceFile("constant.ts", content, ts.ScriptTarget.Latest));
+  return names;
+};

package/frontendBuild/buildRouteClient.test.ts

@@ -343,6 +343,49 @@ describe("route client store bootstrap", () => {
     expect(bundled).not.toContain("lib-ui-marker");
   });
 
+  test("a route's bundle runs the client runtime and the stores before the UI it renders, which reads them on load", async () => {
+    const { appDir, app } = await writeBarrelFixture();
+    const record = (label: string) =>
+      `((globalThis as { __akanOrder?: string[] }).__akanOrder ??= []).push("${label}");`;
+    await write(
+      path.join(appDir, "lib/useClient.ts"),
+      `${record("runtime")}\nexport const { msg, Err, usePage, fetch, sig } = { usePage: () => "page" } as Record<string, unknown>;\n`,
+    );
+    await write(
+      path.join(appDir, "../../libs/kit/lib/st.ts"),
+      `${record("lib-store")}\nexport class RootStore {}\nexport const st = Object.freeze({ mark: "lib-store-marker" });\n`,
+    );
+    await write(
+      path.join(appDir, "lib/st.ts"),
+      `import { RootStore as kit } from "@libs/kit/client";\n${record("store")}\nexport class RootStore {}\nexport const st = Object.freeze({ mark: "store-marker", kit });\n`,
+    );
+    await write(
+      path.join(appDir, "lib/memo/Memo.Zone.tsx"),
+      `"use client";\nimport { Memo, st } from "@apps/demo/client";\n${record("memo-ui")}\nexport const seen = [st.mark, typeof Memo];\n`,
+    );
+
+    await new RouteClientBuilder({
+      app,
+      seeds: [],
+      entries: [path.join(appDir, "lib/memo/Memo.Zone.tsx")],
+      artifact: {} as never,
+      browser: "chunks",
+    }).build();
+
+    const clientOut = path.join(appDir, ".akan/artifact/client");
+    const entries = [...new Bun.Glob("*.js").scanSync(clientOut)];
+    expect(entries).toHaveLength(1);
+    const loaded = (await import(path.join(clientOut, entries[0] ?? ""))) as { seen?: unknown };
+
+    expect(loaded.seen).toEqual(["store-marker", "object"]);
+    expect((globalThis as { __akanOrder?: string[] }).__akanOrder).toEqual([
+      "runtime",
+      "lib-store",
+      "store",
+      "memo-ui",
+    ]);
+  });
+
   test("a route reaching a lib's cnst through its client barrel carries no module UI", async () => {
     const { root, appDir, app } = await writeBarrelFixture();