@akanjs/cli 3.0.0-alpha.9 → 3.0.0-alpha.91

package/guidelines/workspaceRecipes/workspaceRecipes.generate.json

@@ -0,0 +1,33 @@
+{
+  "title": "Workspace Recipes",
+  "description": "Worked step-by-step recipes for common Akan changes, plus the auto-generated signal/service/store/document API reference",
+  "group": "core",
+  "codegenPriority": 5,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Module files a recipe walks through",
+      "path": "{apps,libs}/*/lib/*/*.{constant,document,service,signal,store}.ts",
+      "sample": 5
+    }
+  ],
+  "update": {
+    "filePath": "./workspaceRecipes.instruction.md",
+    "contents": [
+      "add a field",
+      "inject a dependency",
+      "create a slice",
+      "create a mutation",
+      "internal triggers",
+      "insights",
+      "auto-generated API reference"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Every recipe names the files to edit and the order to edit them in",
+      "Keep the <%= appName %> placeholder so the rendered guide names this workspace's app",
+      "Never duplicate a rule that workspaceOnboarding already states — link to it instead"
+    ]
+  }
+}

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -0,0 +1,402 @@
+# Workspace Recipes — Worked Examples And The Auto-Generated API
+
+Step-by-step recipes for the most frequent Akan.js changes, and the reference of what `akan sync` generates for
+you at each layer. `workspaceOnboarding` carries the index and the rules; this is the worked code behind them.
+Read the whole recipe before editing, and change only the sections it names — do not rewrite a file.
+
+## Workflow Recipes
+
+Concrete step-by-step recipes for the most frequent Akan.js changes. Each recipe shows which files to edit
+and in what order. The code examples reference the `task` module in `apps/<app>/lib/task/` as a
+template; replace `task` with your model name and `Task` with your PascalCase model name.
+
+When editing a file, always read the existing content first. Only change the relevant sections — do not
+rewrite the entire file.
+
+---
+
+### Recipe 1: Adding a New Field to a Model
+
+**Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan sync`
+
+```typescript
+// 1. apps/<app>/lib/<model>/<model>.constant.ts
+// Add field to the Input class. Use field() builder with optional defaults
+export class TaskInput extends via((field) => ({
+  title: field(String),
+  priority: field(TaskPriority, { default: "medium" }),  // NEW FIELD
+})) {}
+
+// If the new field should appear in list views, also add it to LightTask:
+export class LightTask extends via(TaskObject, ["title", "priority", "status", "due"] as const, () => ({})) {}
+
+// 2. apps/<app>/lib/<model>/<model>.dictionary.ts
+// Add i18n labels for the new field (and its enum values if any).
+// Labels are [en, ko] pairs, and nearly every one also carries a .desc([en, ko]).
+.model<Task>((t) => ({
+  priority: t(["Priority", "우선순위"]).desc(["How urgent the task is", "할 일의 긴급도"]),
+}))
+.enum<TaskPriority>("taskPriority", (t) => ({
+  low: t(["Low", "낮음"]),
+  medium: t(["Medium", "보통"]),
+  high: t(["High", "높음"]),
+}))
+
+// 3. apps/<app>/lib/<model>/<Model>.Template.tsx
+// Add a form field using st.do.setXxxOnYyy (auto-generated setter)
+const form = st.use.taskForm();
+<Field.ToggleSelect
+  label={l("task.priority")}
+  items={cnst.TaskPriority}
+  value={form.priority}
+  onChange={st.do.setPriorityOnTask}
+/>
+
+// 4. apps/<app>/lib/<model>/<Model>.Unit.tsx
+// Display the new field in card/list views
+<Badge variant={task.priority === "high" ? "error" : task.priority === "medium" ? "warning" : "default"}>
+  {task.priority}
+</Badge>
+
+// 5. Regenerate barrels
+// akan sync <name>
+```
+
+---
+
+### Recipe 2: Injecting a Dependency into a Service
+
+Three patterns: injecting an **external adapter** (`use<>()`), another **module's service** (`service<>()`),
+or a **predefined framework adapter** (`plug()`). A field named `<refName>Service` resolves to the service
+registered under `<refName>` — the `Service`/`Signal` suffix is required and stripped to derive the lookup key.
+
+> **For a new adapter you own, prefer the `adapt()` shape in pattern C over the `option.ts` registration in
+> pattern A.** An `adapt()` class self-registers and is injected with `plug(TheClass)`, so it never touches
+> `option.ts`. Pattern A is the legacy constructor-style shape: recognise it, keep it working, and migrate one
+> only when you are already changing it.
+
+> `apps/<app>/lib/option.ts` is a **user-owned** file scaffolded once — edit it to register adapters/DI. Unlike the
+> barrels (`cnst.ts`, `db.ts`, `srv.ts`, …) it is **not** overwritten by `akan sync`, so your `.use(...)` registrations
+> are safe.
+
+**A. Adapter injection via `use<>()` (for external clients / global singletons)**
+
+```typescript
+// 1. Create the adapter class in apps/<app>/srvkit/
+// apps/<app>/srvkit/EmailClient.ts
+export class EmailClient {
+  constructor(readonly apiKey: string) {}
+  async send(opts: { to: string; subject: string; body: string }) { /* ... */ }
+}
+
+// 2. Register in apps/<app>/lib/option.ts
+export const option = new AkanOption()
+  .use((options) => ({
+    emailClient: new EmailClient(options.mailerApiKey),
+  }));
+
+// 3. Inject via use<>() in <model>.service.ts
+export class TaskService extends serve(db.task, ({ use }) => ({
+  emailClient: use<EmailClient>(),
+})) {
+  async _postCreate(task: cnst.Task) {
+    await this.emailClient.send({ to: "...", subject: "Task Created", body: `Task "${task.title}" created.` });
+  }
+}
+```
+
+**B. Cross-module service injection via `service<>()` (for other Akan services)**
+
+```typescript
+// In <model>.service.ts — inject another module's service
+import * as srv from "../srv";
+
+export class TaskService extends serve(db.task, ({ service }) => ({
+  notiService: service<srv.NotiService>(),
+})) {
+  async _postCreate(task: cnst.Task) {
+    await this.notiService.send("info", `Task "${task.title}" created`);
+  }
+}
+```
+
+**C. Predefined framework adapter injection via `plug()` (storage, cache, queue, schedule, …)**
+
+Akan ships predefined adapter roles from `akanjs/service`: `StorageAdaptorRole`, `CacheAdaptorRole`,
+`QueueAdaptorRole`, `ScheduleAdaptorRole`, `DatabaseAdaptorRole`, `WebsocketAdaptorRole`,
+`LoggingAdaptorRole`, `CompressAdaptorRole`. `plug()` injects the concrete adapter bound to that role (the
+default `StorageAdaptor` binding is `BlobStorage`). `plug()` also accepts a concrete adapter class directly.
+
+```typescript
+// In <model>.service.ts — inject the framework storage adapter by role
+import { plug, serve, StorageAdaptorRole } from "akanjs/service";
+
+export class TaskService extends serve(db.task, ({ plug }) => ({
+  storage: plug(StorageAdaptorRole),
+})) {
+  async attach(taskId: string, path: string, localPath: string) {
+    // BlobStorage returns a URL under blobStorage.urlPrefix (default "/api/localFile/getBlob").
+    return await this.storage.uploadDataFromLocal({ path, localPath });
+  }
+}
+```
+
+For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`.
+Injecting a file/image field is usually simpler than calling
+storage directly: declare `image: field(File).optional()` (or `images: field([File])`) on the model and let the
+store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "removeRef" }` to that
+field when the file belongs to the model alone, and removing the model removes the file and its stored object.
+
+---
+
+### Recipe 3: Creating and Using a Slice
+
+A Slice is a named, filtered data view. Add file entries and connect from a page.
+
+> **Silent failure — a slice `exec` must return a query descriptor, never an executed list.**
+> Return `this.taskService.queryByStatuses(...)` (the `query<Filter>` builder), **not**
+> `this.taskService.listByStatuses(...)` / `listBy...(...)` (which returns a `Promise<Doc[]>`).
+> Returning an array type-checks but throws at runtime during insight aggregation with the opaque
+> `Error: Unknown document field path: 0`. If you see that error, your slice is returning a list, not a query.
+
+```typescript
+// 1. apps/<app>/lib/<model>/<model>.signal.ts — Define the slice
+export class TaskSlice extends slice(srv.task, { guards: { root: Admin, get: SignedIn, cru: SignedIn } }, (init) => ({
+  inTodo: init({ guards: [SignedIn] })
+    .search("statuses", [cnst.TaskStatus])
+    .exec(function (statuses?) {
+      // ✅ query<Filter> — a query descriptor.  ❌ listByStatuses(...) returns an array and fails at runtime.
+      return this.taskService.queryByStatuses(statuses ?? ["todo", "inProgress"]);
+    }),
+})) {}
+
+// 2. apps/<app>/lib/<model>/<model>.document.ts — Add query filter for slice
+export class TaskFilter extends from(cnst.Task, (filter) => ({
+  query: {
+    byStatuses: filter()
+      .arg("statuses", [cnst.TaskStatus])
+      .query((statuses) => ({ status: { $in: statuses } })),
+  },
+})) {}
+
+// 3. apps/<app>/lib/<model>/<model>.dictionary.ts — Slice labels
+.slice<TaskSlice>((fn) => ({
+  inTodo: fn(["Tasks In Todo", "할 일"]).arg((t) => ({
+    statuses: t(["Statuses", "상태"]),
+  })),
+}))
+
+// 4. In page — Init the slice in an async Page and hand the init to a Zone.
+export default async function Page() {
+  const [{ taskInitInTodo }] = await Promise.all([fetch.initTaskInTodo()]);
+  return <Task.Zone.Card init={taskInitInTodo} sliceName="taskInTodo" />;
+}
+```
+
+The slice name in code uses camelCase (`inTodo`). In dictionary and components it becomes `"taskInTodo"`.
+
+---
+
+### Recipe 4: Creating a Mutation Endpoint (with Status Workflow)
+
+**Files to edit (in order):** `document.ts` → `service.ts` → `signal.ts` → `dictionary.ts` → `store.ts` → `Util.tsx`
+
+```typescript
+// 1. <model>.document.ts — Document chain method with state validation
+export class TaskDocument extends by(cnst.Task) {
+  start() {
+    if (this.status !== "todo") throw new Err("task.error.cannotStartFromNonTodo");
+    this.status = "inProgress";
+    return this;  // Return this for chaining: task.start().save()
+  }
+}
+
+// 2. <model>.service.ts — Service method wrapping document
+async startTask(taskId: string) {
+  const task = await this.getTask(taskId);
+  return task.start().save();
+}
+
+// 3. <model>.signal.ts — Mutation endpoint
+export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({
+  startTask: mutation(cnst.Task, { guards: [SignedIn] })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      return await this.taskService.startTask(taskId);
+    }),
+})) {}
+
+// 4. <model>.dictionary.ts — Endpoint + error labels
+.endpoint<TaskEndpoint>((fn) => ({
+  startTask: fn(["Start Task", "작업시작"])
+    .arg((t) => ({ taskId: t(["Task ID", "할 일 ID"]) })),
+}))
+.error({
+  cannotStartFromNonTodo: ["Task can only start from todo status", "할 일 상태에서만 시작 가능"],
+})
+
+// 5. <model>.store.ts — Client-side action with toast feedback
+async startTask(taskId: string) {
+  msg.loading("task.startTaskLoading", { key: "startTask" });
+  const task = await fetch.startTask(taskId);
+  this.setTask(task);  // Auto-generated: updates task state in store
+  msg.success("task.startTaskSuccess", { key: "startTask" });
+}
+
+// 6. <Model>.Util.tsx — Reusable button component
+export const Start = ({ taskId }: { taskId: string }) => (
+  <button className={buttonRecipe({ variant: "primary", size: "xs" })} onClick={() => st.do.startTask(taskId)}>
+    Start
+  </button>
+);
+```
+
+---
+
+### Recipe 5: Internal Triggers — Interval & Cron
+
+Server-side background jobs. Defined in `internal()` signal, implemented in service.
+
+```typescript
+// 1. <model>.signal.ts — Define triggers
+export class TaskInternal extends internal(srv.task, ({ interval, cron }) => ({
+  cleanupStaleTasks: interval(10000).exec(async function () {
+    await this.taskService.cleanupStaleTasks();
+  }),
+
+  dailyDigest: cron("0 0 * * *").exec(async function () {
+    await this.taskService.sendDailyDigest();
+  }),
+})) {}
+
+// 2. <model>.service.ts — Implement the logic
+async cleanupStaleTasks() {
+  const weekAgo = dayjs().subtract(7, "day").toDate();
+  const stale = await this.taskModel.listDueBefore(weekAgo);
+  for (const task of stale) {
+    await task.remove();
+  }
+}
+```
+
+**Available trigger types:**
+- `interval(ms)` — runs repeatedly at the given interval
+- `cron("min hour dom month dow")` — runs on a schedule
+- `initialize()` — runs once on service startup
+- `process(Return).msg(Type)` — message queue consumer
+
+---
+
+### Recipe 6: Creating an Insight (Aggregation / Dashboard Stats)
+
+Insights display aggregated statistics across model data.
+
+```typescript
+// 1. <model>.constant.ts — Insight class with accumulate rules
+export class TaskInsight extends via(Task, (field) => ({
+  totalCount: field(Int, { default: 0, accumulate: {} }),
+  completedCount: field(Int, { default: 0, accumulate: { status: "completed" } }),
+})) {}
+
+// 2. <model>.dictionary.ts — Insight field labels
+.insight<TaskInsight>((t) => ({
+  totalCount: t(["Total Tasks", "전체 할 일"]),
+  completedCount: t(["Completed", "완료됨"]),
+}))
+
+// 3. <Model>.View.tsx — Display component consuming an Insight model
+export const Stats = ({ taskInsight }: { taskInsight: cnst.TaskInsight }) => (
+  <div className="grid grid-cols-2 gap-4">
+    <div className="rounded-lg border border-border bg-card p-4">
+      <div className="text-muted-foreground text-sm">{l("task.totalCount")}</div>
+      <div className="font-bold text-2xl text-primary">{taskInsight.totalCount}</div>
+    </div>
+    <div className="rounded-lg border border-border bg-card p-4">
+      <div className="text-muted-foreground text-sm">{l("task.completedCount")}</div>
+      <div className="font-bold text-2xl text-success">{taskInsight.completedCount}</div>
+    </div>
+  </div>
+);
+
+// 4. <Model>.Zone.tsx — Mount in page via Load.Insight bound to a slice
+export const Insight = ({ sliceName }: { sliceName: string }) => {
+  const insight = st.slice[sliceName].use.taskInsight();
+  if (!insight) return null;
+  return <Task.View.Stats taskInsight={insight} />;
+};
+```
+
+---
+
+### Data Flow Summary
+
+For each business question, follow this chain:
+
+| Question | File Pattern |
+|----------|-------------|
+| What fields does it have? | `constant.ts` — `via()` layers: Input → Object → Light → Model → Insight |
+| How is it stored/searched? | `document.ts` — `from()` filters + `by()` document methods + `into()` model |
+| What business rule should run? | `service.ts` — `serve()` with DI (`use`, `service`, `plug`, `env`, `memory`) |
+| What should a page call? | `signal.ts` — `internal()` (jobs), `endpoint()` (APIs), `slice()` (data views) |
+| What client state is shared? | `store.ts` — `store()` with auto-generated form/insight state + custom actions |
+| What should users see? | `View.tsx` + `Zone.tsx` (detail/container), `Template.tsx` (forms), `Unit.tsx` (cards), `Util.tsx` (buttons) |
+
+
+## Auto-Generated API Reference
+
+akan sync automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
+
+### Signal — Endpoint Auto-Generation
+
+| Auto-Generated | Signature | Description |
+|---------------|-----------|-------------|
+| `view[Model](id)` | `fetch.viewTask(id)` | Fetch single model for detail view |
+| `edit[Model](id)` | `fetch.editTask(id)` | Fetch model for edit view |
+| `merge[Model](id, data)` | `fetch.mergeTask(data)` | Create (no id) or update (with id) model |
+| `[model]List[Suffix](args, skip, limit, sort)` | `fetch.taskListInTodo(args)` | Paginated list from slice filter |
+| `[model]Insight[Suffix](args)` | `fetch.taskInsightInTodo(args)` | Aggregated insight from slice query |
+| `init[Model][Suffix](args)` | `fetch.initTaskInTodo(args)` | Initialize slice with list + insight |
+
+**Rule**: Only define `query()`, `mutation()`, `message()`, `pubsub()` endpoints manually when the endpoint needs custom business logic. Standard CRUD is already auto-generated.
+
+### Service — CRUD & Query Auto-Generation
+
+| Auto-Generated | Description |
+|---------------|-------------|
+| `this.<model>Model` | Auto-injected model adaptor |
+| `get<Model>(id)`, `load<Model>(id)` | Single document lookup |
+| `create<Model>(data)`, `update<Model>(id, data)`, `remove<Model>(id)` | CRUD operations — named after the model, e.g. `createTask`/`updateTask`/`removeTask` (there is no literal `createModel`) |
+| `list<Query>(args)`, `find<Query>(args)`, `pick<Query>(args)` | Filter-based queries |
+| `exists<Query>(args)`, `count<Query>(args)`, `insight<Query>(args)` | Filter-based helpers |
+| `_preCreate`, `_postCreate`, `_preUpdate`, `_postUpdate`, `_preRemove`, `_postRemove` | Lifecycle hooks (override to add logic) |
+
+**Rule**: Use `_preCreate`/`_postCreate` lifecycle hooks for side effects (e.g., push workHistory entries). Write custom service methods only for multi-model orchestration.
+
+### Store — State & Action Auto-Generation
+
+| Auto-Generated | Description |
+|---------------|-------------|
+| `[model]` (cached full model), `[model]Loading`, `[model]Form`, `[model]Modal` | Base model states |
+| `create[Model](data)`, `update[Model](id, data)`, `remove[Model](id)` | CRUD actions |
+| `new[Model](partial)`, `edit[Model](model)`, `view[Model](model)` | Form/view state actions |
+| `[slice]List`, `[slice]InitList`, `[slice]Insight`, `[slice]Selection` | Slice states |
+| `init[Slice](args)`, `refresh[Slice]()`, `setPageOf[Slice](page)` | Slice actions |
+| `set[Field]On[Model](value)` | Auto-setters for each model field |
+
+**Rule**: Write custom store actions only for toast messages (`msg.loading`/`msg.success`) or multi-step workflows. State fields and CRUD actions are already auto-generated.
+
+### Document — Filter Query Auto-Generation
+
+| Auto-Generated (from Filter definition) | Description |
+|----------------------------------------|-------------|
+| `list[Query](args)`, `listIds[Query](args)` | List documents matching filter |
+| `find[Query](args)`, `findId[Query](args)` | Find one (null if not found) |
+| `pick[Query](args)`, `pickId[Query](args)` | Find one (throw if not found) |
+| `exists[Query](args)`, `count[Query](args)` | Existence check and count |
+| `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
+| `remove[Query](args)`, `removeOne[Query](args)` | Query-level soft remove — all matches, or the newest one (`createdAt` desc, not caller-chosen) |
+| `update[Query](args).set(patch)`, `updateOne[Query](args).set(patch)` | Query-level update — the patch lands on a terminal `.set()`, because a filter's trailing args may be optional |
+
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 14 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+
+**The four query-level writes fire no hooks**, so no `_pre`/`_postRemove` and no cascade run — same as `updateManyByQuery`. Reach for them when the model carries no removal side effect; otherwise remove documents one at a time. A filter keyed after its own model (filter `chat` on model `chat`) is rejected at boot, because `removeChat`/`updateChat` would otherwise shadow the generated single-document CRUD.

package/incrementalBuilder.proc.js

@@ -1,26 +1,25 @@
 // @bun
 import {
-  prepareDevWatchBatch
-} from "./index-fgc8r6dj.js";
+  CodegenLock,
+  WorkspaceExecutor,
+  AppExecutor
+} from "./index-q8sn827n.js";
+import"./index-q0y2jq9j.js";
+import"./index-6wwzs1bc.js";
 import {
+  GraphClientEntryDiscovery,
+  RouteClientBuilder,
   AutoImportSync,
   DevChangePlanner,
-  DevGeneratedIndexSync,
-  GraphClientEntryDiscovery,
-  RouteClientBuilder
-} from "./index-j9cxndc0.js";
+  DevGeneratedIndexSync
+} from "./index-w8kmx1b6.js";
 import {
   HmrWatcher,
   WatchRootResolver
-} from "./index-bjpxzr6s.js";
+} from "./index-9wtbw98m.js";
 import {
-  AppExecutor,
-  WorkspaceExecutor
-} from "./index-z8ptfkzv.js";
-import"./index-mxvakhsm.js";
-import"./index-1577bej2.js";
-import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+  prepareDevWatchBatch
+} from "./index-a5vmm6x4.js";
 
 // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
 import path2 from "path";
@@ -68,13 +67,13 @@ class BuildBatchRunner {
       env: process.env,
       stdio: ["ignore", "inherit", "inherit"],
       serialization: "advanced",
-      ipc: (message2) => {
-        if (!message2 || typeof message2 !== "object")
+      ipc: (message) => {
+        if (!message || typeof message !== "object")
           return;
-        if (message2.type === "build-batch-result")
-          result = message2.data;
+        if (message.type === "build-batch-result")
+          result = message.data;
         else
-          onMessage(message2);
+          onMessage(message);
       }
     });
     const exitCode = await proc.exited;
@@ -250,7 +249,8 @@ class IncrementalBuilder {
       return;
     this.#shuttingDown = true;
     const started = Date.now();
-    this.#logger.info(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    this.#logger.debug(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    this.#watcher?.stop();
     if (this.#cssRebuildTimer) {
       clearTimeout(this.#cssRebuildTimer);
       this.#cssRebuildTimer = null;
@@ -263,7 +263,7 @@ class IncrementalBuilder {
       return;
     });
     const flushed = await BuilderChannel.drain();
-    this.#logger.info(`drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`);
+    this.#logger.debug(`drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`);
     process.exit(0);
   }
   get shuttingDown() {
@@ -353,20 +353,21 @@ 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, event, hasSyncErrors } = prepareDevWatchBatch({
+    const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
       indexSync,
       changePlanner: this.#changePlanner
     });
-    const devPlan = event.devPlan;
     this.#logger.verbose(`[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${files.length} generated=${indexSync.changedFiles.length} roles=${devPlan.roles.join(",") || "(none)"} actions=${devPlan.actions.join(",") || "(none)"}`);
     for (const error of indexSync.errors)
       this.#logger.error(error);

package/{index-774gcx29.js → index-0emb9eat.js}

@@ -1,38 +1,45 @@
 // @bun
 import {
-  workflowRunArtifactPath,
-  workflowSyncDir
-} from "./index-rxkpk7n4.js";
-import {
-  AppExecutor,
-  LibExecutor,
-  appRootAllowedDirs,
-  appRootAllowedFiles,
   extractBlockVersion,
-  isScannedAppRootEntry,
-  readDevkitVersion
-} from "./index-z8ptfkzv.js";
-import {
-  collectRecipeSources,
-  findInlineRecipeDuplicates,
-  scanRecipes
-} from "./index-xys926f2.js";
+  readDevkitVersion,
+  rootAllowedFiles,
+  rootAllowedDirs,
+  isScannedRootEntry,
+  AppExecutor,
+  LibExecutor
+} from "./index-q8sn827n.js";
 import {
   FileSys
-} from "./index-67546d0j.js";
+} from "./index-q0y2jq9j.js";
+import {
+  collectRecipeSources2,
+  scanRecipes2,
+  findInlineRecipeDuplicates2
+} from "./index-by5gpp8x.js";
+import {
+  workflowRunArtifactPath,
+  workflowSyncDir
+} from "./index-e82dyeqy.js";
 
 // pkgs/@akanjs/devkit/akanContext.ts
 import { readdir } from "fs/promises";
 import path from "path";
 import { capitalize } from "akanjs/common";
-var resourceList = [
+var guidelineResourceUri = (name) => `akan://guidelines/${name}`;
+var staticResourceList = [
   { uri: "akan://docs/framework", name: "Akan framework guide", mimeType: "text/markdown" },
-  { uri: "akan://guidelines/framework", name: "Framework guideline", mimeType: "text/markdown" },
-  { uri: "akan://guidelines/modelSignal", name: "Model signal guideline", mimeType: "text/markdown" },
   { uri: "akan://workspace/summary", name: "Workspace summary", mimeType: "application/json" },
   { uri: "akan://workspace/apps", name: "Workspace apps", mimeType: "application/json" },
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" }
 ];
+var buildResourceList = (guidelineNames) => [
+  ...staticResourceList,
+  ...guidelineNames.map((name) => ({
+    uri: guidelineResourceUri(name),
+    name: `${name} guideline`,
+    mimeType: "text/markdown"
+  }))
+];
 var cursorMcpConfigPath = ".cursor/mcp.json";
 var claudeMcpConfigPath = ".mcp.json";
 var codexMcpConfigPath = ".codex/config.toml";
@@ -404,19 +411,19 @@ class AkanContextAnalyzer {
       repairAction("generated", "akan repair generated --app <app-or-lib>", "Refresh generated Akan files.", true),
       repairAction("format", "akan repair format --target <app-or-lib-or-pkg>", "Run the formatter/linter repair path.", true)
     ];
-    for (const app of context.apps) {
-      const appPath = path.join(workspace.workspaceRoot, app.path);
-      for (const entry of await safeReadDir(appPath)) {
-        if (!isScannedAppRootEntry(entry.name))
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sysPath = path.join(workspace.workspaceRoot, sys.path);
+      for (const entry of await safeReadDir(sysPath)) {
+        if (!isScannedRootEntry(sys.type, entry.name))
           continue;
-        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
+        const allowed = entry.isDirectory() ? rootAllowedDirs[sys.type].has(entry.name) : rootAllowedFiles[sys.type].has(entry.name);
         if (!allowed) {
-          const action = repairAction("module-shape", `akan repair module-shape --app ${app.name}`, "Review app root shape and remove or move the unknown entry.", false);
+          const action = repairAction("module-shape", `akan repair module-shape --app ${sys.name}`, `Review ${sys.type} root shape and remove or move the unknown entry.`, false);
           diagnostics.push({
             severity: "error",
-            code: "app-root-unknown-entry",
-            path: `${app.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            code: `${sys.type}-root-unknown-entry`,
+            path: `${sys.path}/${entry.name}`,
+            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}`,
             repairActions: [action]
           });
           repairActions.push(action);
@@ -486,10 +493,10 @@ class AkanContextAnalyzer {
       }
     }
     for (const sys of [...context.apps, ...context.libs]) {
-      const sources = await collectRecipeSources(path.join(workspace.workspaceRoot, sys.path, "ui"), "ui");
+      const sources = await collectRecipeSources2(path.join(workspace.workspaceRoot, sys.path, "ui"), "ui");
       if (sources.length === 0)
         continue;
-      const recipes = scanRecipes(sources);
+      const recipes = scanRecipes2(sources);
       const files = [];
       const glob = new Bun.Glob("**/*.tsx");
       for await (const abs of glob.scan({ cwd: path.join(workspace.workspaceRoot, sys.path), absolute: true })) {
@@ -500,7 +507,7 @@ class AkanContextAnalyzer {
           content: await Bun.file(abs).text().catch(() => "")
         });
       }
-      const duplicates = findInlineRecipeDuplicates(recipes, files);
+      const duplicates = findInlineRecipeDuplicates2(recipes, files);
       if (duplicates.length === 0)
         continue;
       const preview = duplicates.slice(0, 3).map((duplicate) => `${path.relative(workspace.workspaceRoot, duplicate.path)}:${duplicate.line}`).join(", ");
@@ -511,7 +518,7 @@ class AkanContextAnalyzer {
         message: `${sys.name}: ${duplicates.length} inline className(s) re-author a recipe fingerprint (${preview}${duplicates.length > 3 ? ", \u2026" : ""}) \u2014 consume the recipe instead.`
       });
     }
-    const scanNames = async (uiDirPath, basename) => new Set(scanRecipes(await collectRecipeSources(uiDirPath, "ui", basename)).map((info) => info.name));
+    const scanNames = async (uiDirPath, basename) => new Set(scanRecipes2(await collectRecipeSources2(uiDirPath, "ui", basename)).map((info) => info.name));
     const declaredByImport = new Map;
     declaredByImport.set("akanjs/ui", await scanNames(path.join(workspace.workspaceRoot, "pkgs/akanjs/ui"), "recipe"));
     for (const sys of [...context.apps, ...context.libs])
@@ -626,4 +633,4 @@ class AkanContextAnalyzer {
   }
 }
 
-export { resourceList, codexMcpConfigPath, akanMcpInstallTargets, akanMcpInstallConfigPaths, createAkanMcpServer, createAkanCodexMcpServerBlock, upsertCodexMcpServerBlock, renderDoctorText, AkanContextAnalyzer };
+export { buildResourceList, codexMcpConfigPath, akanMcpInstallTargets, akanMcpInstallConfigPaths, createAkanMcpServer, createAkanCodexMcpServerBlock, upsertCodexMcpServerBlock, renderDoctorText, AkanContextAnalyzer };