@akanjs/cli 3.1.1-rc.0 → 3.1.1-rc.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +1 -1
- package/{CodeAgent-4pnxwptq.js → CodeAgent-8d5qs787.js} +2 -2
- package/{CodeTui-hhndze8h.js → CodeTui-z5vkm9ea.js} +1 -1
- package/TunnelShare-qkm8zp03.js +14 -0
- package/{agent.command-p02330r6.js → agent.command-ydftceda.js} +5 -5
- package/akanCode.js +2 -2
- package/{application.command-ywks5ywm.js → application.command-wthg8nn9.js} +18 -13
- package/{applicationBuildRunner-9cnnsdm5.js → applicationBuildRunner-t2r84sz6.js} +72 -26
- package/buildBatch.proc.js +5 -5
- package/{cloud.command-1tzkvje1.js → cloud.command-sz11hpre.js} +22 -17
- package/cloud.script-nqevg5qw.js +24 -0
- package/{code.command-16pm1p2v.js → code.command-9h3yrzhe.js} +6 -6
- package/{context.command-6ys86sqf.js → context.command-15j9b7c0.js} +16 -16
- package/context.runner-8gg030b0.js +25 -0
- package/{guideline.command-3zay3d8g.js → guideline.command-snh85ctf.js} +2 -2
- package/guidelines/agentRule/agentRule.instruction.md +21 -4
- package/guidelines/conventions/conventions.instruction.md +17 -10
- package/guidelines/mcpRule/mcpRule.instruction.md +13 -6
- package/guidelines/pageRule/pageRule.instruction.md +21 -5
- package/guidelines/queryRule/queryRule.instruction.md +13 -1
- package/guidelines/runtimeRule/runtimeRule.instruction.md +20 -2
- package/guidelines/ssrRule/ssrRule.instruction.md +6 -1
- package/guidelines/transportRule/transportRule.instruction.md +12 -5
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +2 -1
- package/incrementalBuilder.proc.js +3 -3
- package/{index-jgs8z8xb.js → index-0fz95kxe.js} +1 -1
- package/{index-1f33g2z5.js → index-2azahjaw.js} +81 -28
- package/{index-kcbq2qcf.js → index-2mwc0g0d.js} +1 -1
- package/{index-qkcwsg6r.js → index-2xcc2ax5.js} +2 -2
- package/{index-68c3gzvg.js → index-301pdbzz.js} +56 -9
- package/{index-z6v7k9sb.js → index-31es1yev.js} +24 -2
- package/{index-p4dnj2wc.js → index-3wypz6xj.js} +59 -8
- package/{index-e9e9cebg.js → index-40brg4px.js} +3 -3
- package/{index-tk3jg2bm.js → index-42j4a8zq.js} +2 -2
- package/{index-1mfyyxh5.js → index-4vgbysa0.js} +3 -3
- package/{index-9hbhm6cs.js → index-55j120r8.js} +1 -1
- package/{index-vg28jsf9.js → index-6txx6a9p.js} +214 -71
- package/{index-zn6bn1s2.js → index-74tjjsnc.js} +4 -4
- package/{index-g2s33373.js → index-905qdgqp.js} +1 -1
- package/{index-qtkycaqn.js → index-9th4gszy.js} +38 -21
- package/{index-bb4hj03s.js → index-a58emady.js} +10 -10
- package/{index-4w3skd33.js → index-a5dhqkdr.js} +3 -3
- package/{index-sh9mmp5v.js → index-b70zct19.js} +7 -7
- package/{index-z9xepn8t.js → index-bt438yxm.js} +556 -142
- package/{index-ngpn9hzy.js → index-espk51ah.js} +2 -2
- package/{index-b5vptvnt.js → index-hmt54t45.js} +4 -4
- package/{index-qfzfaq96.js → index-j9vyj3dj.js} +3 -3
- package/{index-ekpp5tax.js → index-js6geqjn.js} +4 -97
- package/{index-fmder14z.js → index-pcwzkdqb.js} +1 -1
- package/{index-jaa81e9r.js → index-qfp55x1y.js} +4 -4
- package/{index-sng3vt0p.js → index-skk9zc1x.js} +2 -2
- package/{index-rr7jk14m.js → index-wcej7g4z.js} +13 -10
- package/{index-q8age5az.js → index-xb8809yb.js} +2 -2
- package/{index-ynqxpwx6.js → index-xjf5j657.js} +1 -1
- package/index.js +22 -22
- package/{library.command-a8n9h8j4.js → library.command-gycrwhf1.js} +3 -3
- package/{localRegistry.command-1e6m7w2f.js → localRegistry.command-jtd8gaes.js} +12 -12
- package/{module.command-b6f1p1xa.js → module.command-v6hgs1bc.js} +5 -5
- package/{package.command-tc27ftmy.js → package.command-shzpcfph.js} +3 -3
- package/package.json +2 -2
- package/{page.command-m5wyqfkd.js → page.command-ptxn5kqk.js} +3 -3
- package/{pipeline.command-4qxyafpz.js → pipeline.command-zz31pgax.js} +2 -2
- package/{primitive.command-9yaatk0d.js → primitive.command-a1vse91z.js} +6 -6
- package/{projectTypecheck-87k6z6ab.js → projectTypecheck-2ztky9cf.js} +1 -1
- package/{quality.command-ht1wjhv8.js → quality.command-ah8qcakd.js} +387 -73
- package/{repair.command-evg9g911.js → repair.command-cvazbz99.js} +5 -5
- package/{scalar.command-xsejjeq1.js → scalar.command-0acvyp26.js} +4 -4
- package/{subspace.command-ps12q5y7.js → subspace.command-822qx2bx.js} +8 -8
- package/templates/app/tsconfig.json.template +2 -7
- package/templates/env/_env.server.type.ts +10 -5
- package/templates/facetIndex/index.ts +2 -2
- package/templates/workspaceRoot/bunfig.toml.template +0 -4
- package/{tunnel.command-khzgvrj8.js → tunnel.command-ycmja19q.js} +7 -7
- package/{workflow.command-qpyq0ya5.js → workflow.command-abb1d5xy.js} +10 -10
- package/{workspace.command-3dq7e9g2.js → workspace.command-qm7cw29v.js} +33 -32
- package/TunnelShare-zmq6bbar.js +0 -14
- package/cloud.script-8g83xqdg.js +0 -24
- package/context.runner-3jrypwe3.js +0 -25
|
@@ -31,7 +31,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
|
|
|
31
31
|
**refuses every call until the app names a guard of its own** — the same answer `None` gives, with no boot
|
|
32
32
|
warning. A product with accounts names it in its `option.ts`, `option.setAgentAccess(SignedIn)`, taking the same
|
|
33
33
|
guard classes every endpoint takes (an array is ANDed, `null` clears what a library set); without one the chat
|
|
34
|
-
cannot spend the LLM key.
|
|
34
|
+
cannot spend the LLM key. **The guard decides who, not what** — the browser writes the instructions, tools and
|
|
35
|
+
transcript — so `option.setAgentRequestPolicy((request, { account, ip }) => request)` sees each turn after the
|
|
36
|
+
guard, before the quota and the model (tool names as the page published them), and returns what is sent, or
|
|
37
|
+
throws an `Err` (`agent.error.requestRefused`) to refuse it.
|
|
35
38
|
`persist` keeps the transcript across reloads (sessionStorage; `{ storage: "local" }` to outlive the tab),
|
|
36
39
|
default off, and `shortcut={false}` gives the browser back the Cmd/Ctrl+L the launcher otherwise captures.
|
|
37
40
|
**`persist` also takes a `SessionHistory` of the app's own** — `{ load, save, clear }` — which is how a
|
|
@@ -104,7 +107,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
|
|
|
104
107
|
parts, so that is what it answers with no `host` set. A `host` the app named is a gateway the class knows
|
|
105
108
|
nothing about, and it stays text-only until `option.setLlm({ accepts })` says otherwise — handing bytes to a
|
|
106
109
|
model that cannot decode them kills the whole turn on a 400, where text-only degrades them to a note the model
|
|
107
|
-
can repeat back.
|
|
110
|
+
can repeat back. A `host` naming OpenAI's own endpoint is the default host by hostname, not a gateway, and an
|
|
111
|
+
app's own chat-completions adaptor claims through `OpenaiLlm.acceptsOf(llmOption)` instead of copying the rule —
|
|
112
|
+
a copy that read "any host is a gateway" kept a vision model text-only for an app that spelled out
|
|
113
|
+
`https://api.openai.com/v1`.
|
|
108
114
|
- **A refusal is `agent.error.llmRequestFailed`, and it names the host** — unless the prompt did not fit. The
|
|
109
115
|
provider's own sentence rides in `reason` and the hostname in `provider`. `LlmOverflow.refusal(host, status,
|
|
110
116
|
reason)` builds it, and reads the one refusal a chat can undo — a prompt past the window, recognized from each
|
|
@@ -627,7 +633,7 @@ pages declaring one name never clash, and a registry kept outside the surface re
|
|
|
627
633
|
|
|
628
634
|
## Built-In Tools
|
|
629
635
|
- The framework publishes six built-ins on every store surface: `navigate` (internal paths only, the same router
|
|
630
|
-
`Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and a page
|
|
636
|
+
`Link` rides, so the app's navigation guards are asked and a refusal is reported as a kept page), `goBack` (this session's history — global, because history is not a control a page owns and a page
|
|
631
637
|
that draws no back link is not one you may not leave — a screen that must not be left withholds them with `builtins`,
|
|
632
638
|
not with prose), `readScreen` (the rendered DOM as compact text — headings, links, control values, and `(disabled)`
|
|
633
639
|
on a control or button that has it; the chat's own UI is skipped via `data-agent-ui`, and a password value is never
|
|
@@ -648,7 +654,18 @@ pages declaring one name never clash, and a registry kept outside the surface re
|
|
|
648
654
|
page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`, `viewImage`) declare it,
|
|
649
655
|
because a wait costs 120ms of quiet at the very least and they change nothing a resource holds.
|
|
650
656
|
New tools and state from a fresh route are still only listed from the next turn: the catalogue is snapshotted
|
|
651
|
-
when the turn starts.
|
|
657
|
+
when the turn starts. **So a navigation ends the model's turn, and a name nobody listed is answered with the names
|
|
658
|
+
that exist.** A call is looked up when it runs, so one batched behind `navigate` already reaches the new screen —
|
|
659
|
+
but the model wrote it against the old catalogue, and a screen-scoped name it never saw is one it composed
|
|
660
|
+
(`addBacklogTicketInProject` for `addBacklogTicket`), and refused with a bare `Unknown tool` it composes the next.
|
|
661
|
+
`AgentService.preamble` therefore says that a navigation ends the turn and that names are never guessed, and the
|
|
662
|
+
session answers an unknown name with the tools listed now — saying, when the catalogue moved since the turn's
|
|
663
|
+
list was written, that the call was written against the screen it left and the new one's tools arrive with their
|
|
664
|
+
arguments next turn. `navigate`'s own answer says the same, reports the path the page actually landed on when a
|
|
665
|
+
redirect or the not-found page moved it elsewhere, and a path with no route is refused with the internal links on
|
|
666
|
+
screen (`ScreenTarget.linkedRoutes`) rather than an invitation to compose another. Layout-level tools — a channel
|
|
667
|
+
post, a new wiki page — stay listed across routes, which is why the cross-screen requests that use only them never
|
|
668
|
+
hit this.
|
|
652
669
|
- **A tool that waits for its own work costs no model turns; one that returns early costs one round trip per
|
|
653
670
|
look.** The session awaits `run`, so a `.exec` that awaits the store action finishing the job simply makes the
|
|
654
671
|
turn take that long — and the change report that follows carries whatever landed, so the model needs no second
|
|
@@ -160,9 +160,10 @@ not "fix" it back.
|
|
|
160
160
|
- Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
|
|
161
161
|
tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
|
|
162
162
|
security-relevant behaviour gets a real suite.
|
|
163
|
-
- Run `bun run akan test <pkg
|
|
164
|
-
|
|
165
|
-
|
|
163
|
+
- Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
|
|
164
|
+
the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
|
|
165
|
+
object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
|
|
166
|
+
of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
|
|
166
167
|
- Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
|
|
167
168
|
`Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
|
|
168
169
|
describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
|
|
@@ -252,7 +253,8 @@ Declared in `akan.config.ts`, narrowed — never widened — by an env at boot;
|
|
|
252
253
|
`ca-certificates` and `tzdata`.
|
|
253
254
|
- **Native apps are the `native` section** (iOS, Android, desktop). A desktop app's carried server listens on a
|
|
254
255
|
loopback port any local program can call — guard it as a network server — and ships `private/` and its env
|
|
255
|
-
readable on the user's computer; read runtime files from `AKAN_APP_DIR
|
|
256
|
+
readable on the user's computer; read runtime files from `AKAN_APP_DIR`, and keep a secret the user gives it with
|
|
257
|
+
`NativeSecret` (the OS credential store), never in a file.
|
|
256
258
|
- **`database: { modes: [...] }`** (`single`, `multiple`, `cluster`), chosen by `AKAN_DATABASE_MODE`; an app running
|
|
257
259
|
in two modes avoids `q.raw`.
|
|
258
260
|
|
|
@@ -333,8 +335,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
|
|
|
333
335
|
`remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
|
|
334
336
|
- **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
|
|
335
337
|
effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
|
|
336
|
-
document, then save, then notify
|
|
337
|
-
|
|
338
|
+
document, then save, then notify; writes that must land together go in `this.transaction(async () => …)` and
|
|
339
|
+
their notification in `this.afterCommit(…)` (`queryRule`). Return `null` / `false` for not allowed or not found;
|
|
340
|
+
the signal decides whether that is an error.
|
|
338
341
|
- **`<model>.signal.ts`** — `XInternal` → `XSlice` → `XEndpoint`, all three even when empty; `exec` is a one-liner
|
|
339
342
|
calling the service.
|
|
340
343
|
- **`<model>.store.ts`** — custom actions only for a toast, an optimistic update, or a multi-field write:
|
|
@@ -394,9 +397,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
|
|
|
394
397
|
wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
|
|
395
398
|
path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
|
|
396
399
|
input keeps an absent field absent.
|
|
397
|
-
- **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
|
|
398
|
-
|
|
399
|
-
|
|
400
|
+
- **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
|
|
401
|
+
whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
|
|
402
|
+
name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
400
403
|
- **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
|
|
401
404
|
`query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
|
|
402
405
|
A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
|
|
@@ -414,7 +417,8 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
|
|
|
414
417
|
screen with `page().prompt(name, description)`, and publish one component a host draws with
|
|
415
418
|
`page().app(name, description, load)` — a read-only tool whose `load` may only query.
|
|
416
419
|
- **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
|
|
417
|
-
every call until `option.setAgentAccess(<guard>)
|
|
420
|
+
every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
|
|
421
|
+
`option.setAgentRequestPolicy`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
|
|
418
422
|
The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
|
|
419
423
|
`st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
|
|
420
424
|
`visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
|
|
@@ -505,6 +509,9 @@ export default page()
|
|
|
505
509
|
- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
|
|
506
510
|
return; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
|
|
507
511
|
(title, redirect, link id) in one `Promise.all`.
|
|
512
|
+
- **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
|
|
513
|
+
`base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
|
|
514
|
+
`{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
|
|
508
515
|
- Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
|
|
509
516
|
`create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
|
|
510
517
|
endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
|
|
@@ -40,6 +40,9 @@ export class FileSlice extends slice(srv.file, {
|
|
|
40
40
|
`update`, `remove`), same fallbacks (`create`/`update`/`remove` inherit `cru`), and the same scope: it narrows
|
|
41
41
|
the root slice and the generated CRUD, and never reaches a named slice or a custom endpoint. Those declare
|
|
42
42
|
their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
|
|
43
|
+
- **An app's slice replaces a lib's whole**, on the server and in the client: its own `guards` (a `None` verb is
|
|
44
|
+
denied everywhere) and its own `mcp` map, or, when it writes none, every verb the lib's slice took off stays off.
|
|
45
|
+
To keep a mounted lib's tools off without its slice, use `setMcp({ excludeSignals, excludeEndpoints })` (below).
|
|
43
46
|
- **A view keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
|
|
44
47
|
is published with `visibility: ["app"]`: an app's view may call it, the model is never shown it (below). Every
|
|
45
48
|
other refusal still holds there.
|
|
@@ -56,11 +59,13 @@ export class FileSlice extends slice(srv.file, {
|
|
|
56
59
|
## Configuration
|
|
57
60
|
Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
|
|
58
61
|
`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`,
|
|
59
|
-
`promptBudget`, `apps`, `modern`, and `
|
|
62
|
+
`promptBudget`, `apps`, `modern`, `auth`, and `excludeSignals` / `excludeEndpoints` (curation like `mcp: false`,
|
|
63
|
+
added up across libs, an unmatched name warned at boot) — or `setMcp((env) => …)` for settings derived from the
|
|
64
|
+
server env.
|
|
60
65
|
**Not `main.ts`**: the gateway
|
|
61
66
|
there only spawns children, and `option.ts` is the app-authored file `server.ts` already hands to the process that
|
|
62
67
|
mounts `/mcp`. Every lib's option is read in mount order with the app's last, so an app tightens what a library
|
|
63
|
-
declared without restating it. Each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
|
|
68
|
+
declared without restating it. Each field but the two lists also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
|
|
64
69
|
`AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
|
|
65
70
|
`AKAN_MCP_LANGUAGE`, `AKAN_MCP_LEGACY_TEXT`, `AKAN_MCP_OUTPUT_SCHEMA`, `AKAN_MCP_RATE_LIMIT`, `AKAN_MCP_CONCURRENT`,
|
|
66
71
|
`AKAN_MCP_PROMPT_BUDGET`, `AKAN_MCP_APPS`, `AKAN_MCP_MODERN`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that configures what the source does
|
|
@@ -410,8 +415,9 @@ export default page()
|
|
|
410
415
|
names share one namespace with the prompts, and an endpoint keeps its name over an app's, with a boot warning.
|
|
411
416
|
- **`load` may only query.** A mutation, a file upload, a room subscription or a message sent while it runs throws
|
|
412
417
|
`base.error.mutationInApp` before anything is sent — on the server through every `await`, in a browser for its
|
|
413
|
-
synchronous part.
|
|
414
|
-
`.guard()`: a `getSelf({ unauthorize })` inside `load` would
|
|
418
|
+
synchronous part, `{ duringRender: true }` or not. The buttons and forms that write stay in `.render()` around the
|
|
419
|
+
element (the `Close` above), and gating stays in `.guard()`: a `getSelf({ unauthorize })` inside `load` would
|
|
420
|
+
redirect a view.
|
|
415
421
|
- **A host that declares the extension** (claude.ai, Claude Desktop, ChatGPT, VS Code, Goose) is also given
|
|
416
422
|
`_meta.ui.resourceUri` (`ui://<app>/apps/<name>`) and draws the app's own view in place of the result: one HTML
|
|
417
423
|
document per app, which `akan build` writes to `mcp-apps/<name>.html` beside `csr/` and `akan start` writes to
|
|
@@ -444,8 +450,9 @@ export default page()
|
|
|
444
450
|
reaches the host with `base.error.readOnlyDeployment`, toasted in the person's language. A `.prompt()` page's text
|
|
445
451
|
tool is dropped, since its run renders the whole page; the prompt stays.
|
|
446
452
|
- **`.prompt()` is a briefing, never a view.** Its page is also a text tool of the same name, marked
|
|
447
|
-
`readOnlyHint: false`, since running the page makes its own `fetch.*` calls
|
|
448
|
-
|
|
453
|
+
`readOnlyHint: false`, since running the page makes its own `fetch.*` calls; like any render it refuses a mutation
|
|
454
|
+
with `base.error.mutationInRender` unless the call passes `{ duringRender: true }`. To have a host draw part of that
|
|
455
|
+
screen, declare an `.app()` beside it.
|
|
449
456
|
- **The view has no network.** `connect-src` stays closed; the app's own origin is opened for what a page loads by
|
|
450
457
|
URL — fonts (served with `Access-Control-Allow-Origin: *`) and stored images — and every root-relative URL the
|
|
451
458
|
page writes is pointed at it, since a host may block the document's `<base>` (Claude does).
|
|
@@ -41,6 +41,13 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
41
41
|
hydration, so an effect that needs the query on its first run takes the page's `.search()` value as a prop.
|
|
42
42
|
- There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
|
|
43
43
|
`.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
|
|
44
|
+
- **A route only reads while it renders.** A `fetch.<mutation>()` (or socket message) sent from `.render()`, `.guard()`,
|
|
45
|
+
`.head()`, `.loading()` or a layout's `.notFound()` / `.error()` (a `.prompt()` run included) throws
|
|
46
|
+
`base.error.mutationInRender` synchronously, before it is sent — a `.catch()` on its promise never sees it: opening a
|
|
47
|
+
link to the page would perform it. Send a write from a user action — a button through a store action. Only a write
|
|
48
|
+
that is harmless to repeat and safe for anyone to trigger (a warm-up) passes `{ duringRender: true }` as the option
|
|
49
|
+
after the endpoint's own arguments (`fetch.updateX(id, data, { duringRender: true })`). `akan quality` flags the call,
|
|
50
|
+
same-file helpers included, as `akan.ssr.render-mutation`.
|
|
44
51
|
|
|
45
52
|
## Route Guards — `.guard()`
|
|
46
53
|
|
|
@@ -71,6 +78,14 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
71
78
|
- **A route guard is not authorization for data.** It keeps a person off a screen and redirects early; every query
|
|
72
79
|
the screen makes is still judged by that endpoint's own `guards`. Write both: the signal guard is the gate, the
|
|
73
80
|
route guard is the courtesy that answers before the screen draws.
|
|
81
|
+
- **Keeping a person on a page is `router.addNavigationGuard(guard)`, not `.guard()`.** `guard({ kind, from, to })`
|
|
82
|
+
is asked before every in-app move — `push`, `replace`, `back`, a `Link`, the browser's back and forward (`pop`), a
|
|
83
|
+
native back or swipe, the agent's `navigate` and `goBack` — with routes free of locale and basePath and `to: null`
|
|
84
|
+
for a `back`. `false`, a throw or a rejection keeps the page, `router.navigation()` rejects with
|
|
85
|
+
`NavigationRefused`, and a refused browser back is undone before the page redraws. Guards answer one at a time; a
|
|
86
|
+
move started while one decides is refused. Register it from an effect and return the remover
|
|
87
|
+
(`useEffect(() => router.addNavigationGuard(…), [isDirty])`). Redirects, `notFound()`, `setLang` and moves off the
|
|
88
|
+
origin are not asked; a closing tab is `beforeunload`'s.
|
|
74
89
|
|
|
75
90
|
## MCP Apps — `.app()`
|
|
76
91
|
|
|
@@ -82,11 +97,12 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
82
97
|
source), shares one namespace with every page's prompts and apps, and needs an English description. A name
|
|
83
98
|
`.render()` already receives (`lang`, a `.param()` / `.search()` name, another app) fails to compile and throws when
|
|
84
99
|
the module loads, as does an app named like the page's `.prompt()`.
|
|
85
|
-
- **`load` may only query** (`base.error.mutationInApp` otherwise
|
|
86
|
-
gating in `.guard()`. The view runs `load` with no layout body
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
chain is the `export default` expression itself: one
|
|
100
|
+
- **`load` may only query** (`base.error.mutationInApp` otherwise, `duringRender` or not): keep the buttons and forms
|
|
101
|
+
that write in `.render()` around the element, and gating in `.guard()`. The view runs `load` with no layout body
|
|
102
|
+
and no `.render()`: it gets the root layout's theme, fonts and framework providers through the generated
|
|
103
|
+
`McpAppRoot` and the `_overrides.tsx` over the page (one the web draws outside the root layout wraps `McpAppRoot`,
|
|
104
|
+
its toasts included), and nothing a layout body provides. The chain is the `export default` expression itself: one
|
|
105
|
+
bound to a name fails the build. Full contract: `mcpRule`.
|
|
90
106
|
|
|
91
107
|
## Heads
|
|
92
108
|
|
|
@@ -72,6 +72,9 @@ this is the full contract behind them.
|
|
|
72
72
|
"there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
|
|
73
73
|
The query is a compare-and-set in every mode: of two concurrent `updateOne({ id, balance: { $gte: n } }, …)` that
|
|
74
74
|
both read the row as matching, only one applies, so `modifiedCount` is the verdict.
|
|
75
|
+
- **`{ touch: false }` leaves `updatedAt` as stored** on a query-level write: in the options of `updateOne` /
|
|
76
|
+
`updateMany` / `updateById`, or `.set(update, { touch: false })` on a filter chain. Bookkeeping that is no edit — a
|
|
77
|
+
lease heartbeat, a mirrored snapshot — otherwise moves the row in every `updatedAt` period and sort.
|
|
75
78
|
- **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
|
|
76
79
|
model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
|
|
77
80
|
throws at boot instead (`assertFilterFitsCrud`).
|
|
@@ -112,9 +115,18 @@ this is the full contract behind them.
|
|
|
112
115
|
document path**: they fire no hooks, so a model whose removal cascades or carries a `_postRemove` still goes
|
|
113
116
|
through `remove<Model>(id)`.
|
|
114
117
|
- The write-through pair is `pickAndWrite(id, data)` / `pickOneAndWrite(query, data)` — pick the document, write
|
|
115
|
-
into it and save it, so the save hooks do run; reach for those when the write has to be seen by them.
|
|
118
|
+
into it and save it, so the save hooks do run; reach for those when the write has to be seen by them. A third
|
|
119
|
+
argument `{ touch: false }`, like `doc.save({ touch: false })`, keeps `updatedAt` while the hooks and live sync
|
|
120
|
+
still run — a nudge that re-sends a row its rooms must re-read, with no edit to stamp.
|
|
116
121
|
- `upsertById(data, { preserveTimestamps })` writes a record whole under its own id, new or in place, with no
|
|
117
122
|
hook: the write a sync or a backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
|
|
123
|
+
- **Writes that must land together go in `this.transaction(async () => …)`**, which every service has: it commits
|
|
124
|
+
when the body resolves, returns its value, and rolls back when it throws, rethrowing that error unchanged. A
|
|
125
|
+
server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
|
|
126
|
+
outer one, with no savepoint. Cache, `memory` and outside calls are not in it — hand them to
|
|
127
|
+
`this.afterCommit(fn)`, run once the commit lands, never after a rollback, at once outside one; one that throws is
|
|
128
|
+
logged, never thrown, and the rest still run. On SQLite it holds the only write turn: keep it short.
|
|
129
|
+
`@Transaction()` is deprecated.
|
|
118
130
|
|
|
119
131
|
## Text Search In A Filter — `q.search()`
|
|
120
132
|
|
|
@@ -101,6 +101,10 @@ worker per web-serving replica.
|
|
|
101
101
|
- **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
|
|
102
102
|
gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
|
|
103
103
|
rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
|
|
104
|
+
- **Health detail and metrics answer only `Authorization: Bearer $AKAN_STATUS_TOKEN`** (or the log stream token)
|
|
105
|
+
outside `local`: without it `/_akan/app/health` is `{ status }` alone (still 200) and `/_akan/app/metrics` is 401.
|
|
106
|
+
A probe that reads only the status code needs nothing; give a scraper or monitor `AKAN_STATUS_TOKEN`, which reads
|
|
107
|
+
nothing else.
|
|
104
108
|
- **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
|
|
105
109
|
with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
|
|
106
110
|
- **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
|
|
@@ -209,7 +213,7 @@ normalized to `info` with one warning.
|
|
|
209
213
|
`AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
|
|
210
214
|
`raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
|
|
211
215
|
- **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events);
|
|
212
|
-
unset, the route does not exist.
|
|
216
|
+
unset, the route does not exist. The same bearer also unlocks the health detail and metrics.
|
|
213
217
|
- **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
|
|
214
218
|
keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
|
|
215
219
|
`AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — in `local`, or with the
|
|
@@ -235,6 +239,10 @@ const config: AppConfig = { docker: "FROM oven/bun:1.4.4-slim\n…" }; // verbat
|
|
|
235
239
|
`RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
|
|
236
240
|
before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
|
|
237
241
|
and before the app files are copied.
|
|
242
|
+
- **The image installs the versions the workspace locked.** `akan build` writes a `bun.lock` beside the image's
|
|
243
|
+
`package.json`, cut down from the workspace's to what the server needs, and the image installs it
|
|
244
|
+
`--frozen-lockfile`. A workspace without a root `bun.lock` gets a warning and an unlocked install; a Dockerfile
|
|
245
|
+
written whole copies `bun.lock` itself.
|
|
238
246
|
- **A lib declares the steps its own runtime needs**, and every app that mounts it inherits them:
|
|
239
247
|
`libs/<lib>/akan.config.ts` takes `docker: { preRuns, postRuns }` and nothing else — the base image and the
|
|
240
248
|
command belong to the app. Lib steps are emitted before the app's own, and an identical step declared twice
|
|
@@ -509,6 +517,14 @@ The carried server asks the shell that showed the dialog over its IPC channel, s
|
|
|
509
517
|
and nothing else, and no page ever holds a path. Behind a dev build `akan start` checks the grant's signature
|
|
510
518
|
against a key in `~/.akan/native` instead, in `operationMode` local only; every other server refuses a grant.
|
|
511
519
|
|
|
520
|
+
**A secret the user gives the server is kept by the OS, never in a file.** `NativeSecret.set(key, value)`,
|
|
521
|
+
`get(key)` (null when none is kept) and `remove(key)` from `akanjs/server` reach the OS credential store through the
|
|
522
|
+
shell that carries the server — the macOS Keychain, the Windows Credential Manager, the Secret Service on Linux — in a
|
|
523
|
+
store of the server's own, apart from the page's `secretStorage`, so no page script reads it. Anywhere but a carried
|
|
524
|
+
server `NativeSecret.available` is false and every call rejects: keep secrets in the env there. On macOS without a
|
|
525
|
+
Team ID signature, any program of the same user can read the store's key through `security`, as with
|
|
526
|
+
`secretStorage`.
|
|
527
|
+
|
|
512
528
|
**Devices belong to the shell, not the server.** Displays and their changes (`screen`), windows placed on them
|
|
513
529
|
(`window`), the system volume and mute (`volume`), global shortcuts (`global-shortcut`), keep-awake (`keep-awake`)
|
|
514
530
|
and launch at login (`autostart`) are native runtime plugins, each added to `native.plugins`. Every builtin plugin's
|
|
@@ -532,7 +548,9 @@ bypasses the store akanjs picks per platform (the shell's Preferences in an app)
|
|
|
532
548
|
code never touches `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`): it
|
|
533
549
|
uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage` for tokens and credentials, all from
|
|
534
550
|
`akanjs/client`. `setCookie` writes `path=/; SameSite=Lax; Secure`, and an options object overrides only the keys it
|
|
535
|
-
names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back.
|
|
551
|
+
names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. `getCookie` reads a name sent
|
|
552
|
+
twice as unset, since a sibling subdomain can plant a second copy; server code reads `cookieJar()` from
|
|
553
|
+
`akanjs/fetch`, or `CookieJar.parse(req.headers.get("cookie"))`, never `req.cookies`. Browser APIs an app WebView lacks
|
|
536
554
|
stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`, which is where the app side goes
|
|
537
555
|
too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
|
|
538
556
|
`navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
|
|
@@ -28,7 +28,12 @@ on the client side**.
|
|
|
28
28
|
- `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Keep the interactive
|
|
29
29
|
element in the client component and hoist the static subtree into a server component received as `children`.
|
|
30
30
|
- `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data. Fetch it in the route and pass the
|
|
31
|
-
init/view object down.
|
|
31
|
+
init/view object down. A mutation is not a load: send it from a user action (a button through a store action),
|
|
32
|
+
never from the route.
|
|
33
|
+
- `akan.ssr.render-mutation` — a route's stages (a layout's `.notFound()` / `.error()` included), or a same-file
|
|
34
|
+
function they call, send a mutation, which throws `base.error.mutationInRender`: opening a link would perform it.
|
|
35
|
+
Move it to a user action; pass `{ duringRender: true }`, as the option after the endpoint's own arguments, only for
|
|
36
|
+
a write that is harmless to repeat and safe for anyone to trigger.
|
|
32
37
|
- `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util` and declares no
|
|
33
38
|
`Unit`/`View`. Add them and have the `Zone` delegate.
|
|
34
39
|
- `akan.ssr.template-client-state` — a `Template` holds form state in `useState`. Bind to the store instead:
|
|
@@ -20,14 +20,21 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
|
|
|
20
20
|
- A websocket carries its credential in the handshake snapshot on `ws.data` (`AppWsData`); clients that hold the token in memory send it with `fetch.setJwt(...)`, which forwards an auth frame over the socket.
|
|
21
21
|
- **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`.** Whenever a federation
|
|
22
22
|
gateway is in front, `ws.remoteAddress` and the child's own peer are the *gateway* (`127.0.0.1`) for every
|
|
23
|
-
caller and for the whole life of every socket. `Ip` reads
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
caller and for the whole life of every socket. `Ip` reads forwarded headers only from a trusted peer — loopback,
|
|
24
|
+
a unix socket, and the private ranges until `AKAN_TRUSTED_PROXIES` (CIDRs or addresses, plus `private`, `none`,
|
|
25
|
+
`*`) replaces them; any other peer is the caller itself. Unset or `*`, it reads `x-real-ip`, else the leftmost
|
|
26
|
+
`x-forwarded-for` entry. A list walks `x-forwarded-for` from the nearest hop to the first untrusted address and
|
|
27
|
+
reads `x-real-ip` only without one — so list the load balancer's and ingress controller's own addresses (or a CIDR
|
|
28
|
+
holding only them), and have the proxy set or append `X-Forwarded-For` rather than pass the client's through.
|
|
29
|
+
`private` lets any pod in those ranges name any caller: pair it with a NetworkPolicy admitting only the ingress.
|
|
30
|
+
From any other peer `x-forwarded-host` / `-proto` / `-port` are dropped before a route runs, so a public proxy
|
|
31
|
+
that rewrites `Host` must be listed, or the browser's mutations fail the cross-site check.
|
|
32
|
+
The gateway hands its children the one address it resolved; `context.getClientIp()` is the same answer inside a
|
|
33
|
+
guard or middleware. It arrives in one canonical spelling, unwrapped from
|
|
27
34
|
its `::ffff:` IPv4-mapped form, so it can address a `udp4` socket as well as identify a caller, and it is
|
|
28
35
|
`null` rather than a placeholder when genuinely unknown — a loopback-looking address for an unknown caller
|
|
29
36
|
is the failure this replaced. The gateway also forwards the client port (`x-forwarded-port`, read with
|
|
30
|
-
`context.getClientPort()`)
|
|
37
|
+
`context.getClientPort()`), host and protocol, each taken from the request only when its peer is trusted.
|
|
31
38
|
- **A device or another server proves itself with a machine token.** `MachineToken.issue({ kind, id, version },
|
|
32
39
|
{ expiresAt? })` in `akanjs/server` signs an EdDSA JWT (`typ: akan-machine+jwt`, `aud: <app>/<environment>`) with
|
|
33
40
|
`AKAN_MACHINE_PRIVATE_KEY`; it never expires unless asked. `akan machine-keygen <file>` writes that key to a file
|
|
@@ -250,7 +250,8 @@ query-level writes are in `queryRule`; these are the shapes that build green and
|
|
|
250
250
|
a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
|
|
251
251
|
`Unknown document field path: 0`. (See Recipe 3.)
|
|
252
252
|
- **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
|
|
253
|
-
already exist. A collision
|
|
253
|
+
already exist wherever the slice mounts the verb. A collision builds green and the server refuses to boot
|
|
254
|
+
(`[DI:fetch]`) — pick a distinct verb.
|
|
254
255
|
- **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck.
|
|
255
256
|
- **Array fields use `field([T])`** — `tags: field([String])`, `images: field([File])`.
|
|
256
257
|
- **Reading a secret field needs an explicit select, and the two call sites spell it differently.**
|
|
@@ -8,7 +8,7 @@ import {
|
|
|
8
8
|
CodegenLock,
|
|
9
9
|
WorkspaceExecutor,
|
|
10
10
|
AppExecutor
|
|
11
|
-
} from "./index-
|
|
11
|
+
} from "./index-wcej7g4z.js";
|
|
12
12
|
import"./index-52w0fvh8.js";
|
|
13
13
|
import {
|
|
14
14
|
GraphClientEntryDiscovery,
|
|
@@ -19,10 +19,10 @@ import {
|
|
|
19
19
|
DevChangePlanner,
|
|
20
20
|
DevGeneratedIndexSync,
|
|
21
21
|
SsrDevBundler
|
|
22
|
-
} from "./index-
|
|
22
|
+
} from "./index-espk51ah.js";
|
|
23
23
|
import {
|
|
24
24
|
ServerGraphFile
|
|
25
|
-
} from "./index-
|
|
25
|
+
} from "./index-0fz95kxe.js";
|
|
26
26
|
import {
|
|
27
27
|
prepareDevWatchBatch
|
|
28
28
|
} from "./index-a5vmm6x4.js";
|