@akanjs/cli 3.0.1 → 3.0.2-rc.0

package/guidelines/transportRule/transportRule.instruction.md

@@ -8,7 +8,8 @@ mutation is mounted under. `conventions` carries the invariants — this is the
 
 - Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` (`pkgs/akanjs/signal/signalContext.ts`) instead of branching on `getHttpContext()` / `getWebSocketContext()`.
 - Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is unguarded unless it declares its own `guards` in its signal option.
-- A pubsub room is authorized once, at subscribe. When a socket's credential changes the framework re-runs each room's guards and unsubscribes the ones that now fail (`SignalResolver.revalidateWsRooms`), so guards must stay side-effect free and safe to re-run.
+- A pubsub room is authorized once, at subscribe. When a socket's credential changes the framework re-runs each room's guards and unsubscribes the ones that now fail (`SignalResolver.revalidateWsRooms`), so guards must stay side-effect free and safe to re-run. Each re-check runs on a fresh `SignalContext`, so a guard that memoizes per context answers anew.
+- **Arguments are parsed after the `"account"` guards** (`SignalContext.init` reads the body, `exec` parses): the order is middlewares → `account` guards → parse → `resource` guards → internal arguments → handler, whatever order `guards: [...]` lists them in. A caller an account guard refuses never reaches a scalar parser, which is what keeps a slow parser from being a pre-auth denial of service. A guard or middleware that reads `context.args` / `getArg()` earlier still gets the value, parsed on first read — a mismarked account guard keeps working. One visible consequence: an unauthenticated call with a malformed argument answers 401/403 instead of 400.
 - 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.
 - **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`.** Whenever a federation
   gateway is in front, `ws.remoteAddress` and the child's own peer are the *gateway* (`127.0.0.1`) for every
@@ -74,11 +75,46 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
 - **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
   uncached; a failed write is warned and dropped.
-- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs guards →
-  internal arguments → cache → handler: a hung cache backend is bounded by the same deadline as the handler it
-  stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs an
+  `account` rate limit → account guards → argument parse → resource guards → internal arguments → cache →
+  handler: a hung cache backend is bounded by the same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
   whose failure it cannot classify replays whatever the first attempt already did.
 
+## Rate Limits
+
+- **`{ rateLimit: { calls, windowMs?, by? } }` in an endpoint's signal option** counts calls per caller per window
+  (`windowMs` 60 000 unless named). `by: "ip"` (the default) is checked in `SignalContext.init`, after the
+  cross-site check and before the body is read, so a refused flood costs no parse at all. `by: "account"` is
+  checked after the middlewares and before the guards, keyed by `accountKey(account)`; a caller it names nothing
+  for — an anonymous one — is counted by address. Leaving a pubsub room is never counted.
+- **The answer is 429 `base.error.tooManyRequests` with `data: { seconds }`** and a `Retry-After` header; a WS
+  call gets the same payload as its error frame, and the HTTP client restores a proxy's own non-JSON 429 under the
+  same key (seconds from its `Retry-After`, else 60). The first refusal per endpoint per process is warned once;
+  later ones log at `debug`, so a flood does not become a log flood.
+- **Keys and addresses.** The address is `context.getClientIp()` — the trusted-proxy answer, never a raw header
+  from an untrusted peer. Callers whose address is unknown share one `unknown` budget (fail closed), and the first
+  such call is warned about, since it usually means the proxy in front records no `X-Real-IP`/`X-Forwarded-For`
+  or is not trusted (`AKAN_TRUSTED_PROXIES`). A page's server-side fetches carry the visitor's address: the page
+  renderer hands the RSC worker the address it resolved as `x-real-ip`, and the server-side fetch client forwards
+  it on same-origin calls.
+- **Counters live in the cache** (`CacheAdaptor.incr`, epoch-aligned windows), so replicas draw on one budget; a
+  cache that fails falls back to counting per process, warned once. The MCP endpoint's own limiter is the same
+  `RateLimiter` under its own topic, and keys an anonymous MCP caller by the same trusted address.
+- **App and lib configuration** is `option.setRateLimit(...)` in `lib/option.ts`, merged in mount order with the
+  app last: `budget` is the default for every endpoint that declares none (unset leaves those unlimited),
+  `endpoints` overrides one by key — a lib's declared budget included — or exempts it with `false`, `accountKey`
+  names who `by: "account"` counts (default: `account.id ?? sub ?? sid`; a lib whose accounts carry `self`/`me`
+  should name `self.id ?? me.id`, or each session counts apart), and `enabled: false` (or `setRateLimit(false)`)
+  turns budgets off for a deployment rate-limited at its edge. `rateLimit: false` on an endpoint exempts it from
+  the app's `budget` only.
+- **`AKAN_RATE_LIMIT`**: `off` turns every budget off whatever the code says; `on` turns them on in a `local`
+  environment, where they are otherwise off; `<calls>[/<seconds>]` is the default budget wherever the code names
+  none. Tests run in the `testing` environment, where budgets apply.
+- **A business key is a service's own count**: `rateLimit: plug(RateLimit)` then
+  ``await this.rateLimit.consume(`otp:${phone}`, { calls: 5, windowMs: 3_600_000 })``, which answers
+  `{ ok: true } | { ok: false, retryAfterMs }` and is never switched off — throw the module's own `Err` with the
+  wait when it refuses.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`

package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md

@@ -124,7 +124,7 @@ starts it itself. The full contract — targets, updates, what the carried serve
 ```bash
 akan start-desktop <%= appName %>                   # Run the desktop app on this computer
 akan start-ios <%= appName %>                       # Run it in a simulator or on an iPhone (start-android alike)
-akan build-desktop <%= appName %>                   # Build it for this computer into .akan/native/<target>/build
+akan build-desktop <%= appName %>                   # Build it for this computer into dist/native/<%= appName %>/<target>/build
 akan build-desktop <%= appName %> --installer true  # Windows: add a per-user setup program
 akan update-keygen <%= appName %>                   # Make the update signing key once; print its public key
 akan publish-update <%= appName %>                  # Build and sign a desktop release to upload to updates.url

package/incrementalBuilder.proc.js

@@ -8,7 +8,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-150s07n8.js";
+} from "./index-50wb2a26.js";
 import"./index-52w0fvh8.js";
 import {
   GraphClientEntryDiscovery,
@@ -20,7 +20,7 @@ import {
   DevChangePlanner,
   DevGeneratedIndexSync,
   SsrDevBundler
-} from "./index-m3xsb1ms.js";
+} from "./index-krjcg4y6.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";

package/{index-66yspb67.js → index-1bjkfvm9.js}

@@ -2,14 +2,12 @@
 import {
   runner,
   script
-} from "./index-a37by9hn.js";
-import {
-  LibExecutor
-} from "./index-150s07n8.js";
+} from "./index-q6ft9fkc.js";
 import {
   LibSource,
-  formatLibStatuses
-} from "./index-bjwxs904.js";
+  formatLibStatuses,
+  LibExecutor
+} from "./index-50wb2a26.js";
 
 // pkgs/@akanjs/cli/library/library.script.ts
 import { Logger } from "akanjs/common";
@@ -86,28 +84,32 @@ class LibraryRunner extends runner("library") {
     return await Promise.all(libNames.map((libName) => new LibSource(LibExecutor.from(workspace, libName)).status()));
   }
   async mergeLibraryDependencies(lib) {
-    const libPackageJson = await lib.getPackageJson();
-    const rootPackageJson = await lib.workspace.getPackageJson();
-    const dependencies = {};
-    const devDependencies = {};
-    const libDependencies = { ...libPackageJson.dependencies, ...libPackageJson.devDependencies };
-    const rootDependencies = { ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies };
-    const allDependencies = Object.fromEntries(Object.keys({ ...libDependencies, ...rootDependencies }).map((dep) => {
-      const libVersion = libDependencies[dep] ?? "0.0.0";
-      const rootVersion = rootDependencies[dep] ?? "0.0.0";
-      const newerVersion = compareSemver(rootVersion, libVersion) > 0 ? rootVersion : libVersion;
-      return [dep, newerVersion];
-    }));
-    Object.keys(allDependencies).sort().forEach((dep) => {
-      if (libPackageJson.dependencies?.[dep] || rootPackageJson.dependencies?.[dep])
-        dependencies[dep] = allDependencies[dep];
-      else
-        devDependencies[dep] = allDependencies[dep];
+    const [libPackageJson, rootPackageJson] = await Promise.all([lib.getPackageJson(), lib.workspace.getPackageJson()]);
+    const rootVersionOf = (dep) => rootPackageJson.dependencies?.[dep] ?? rootPackageJson.devDependencies?.[dep];
+    const missingFrom = (deps = {}) => Object.entries(deps).filter(([dep]) => !rootVersionOf(dep));
+    const dependencies = missingFrom(libPackageJson.dependencies);
+    const devDependencies = missingFrom(libPackageJson.devDependencies).filter(([dep]) => !libPackageJson.dependencies?.[dep]);
+    const behind = Object.entries({ ...libPackageJson.devDependencies, ...libPackageJson.dependencies }).flatMap(([dep, version]) => {
+      const rootVersion = rootVersionOf(dep);
+      return rootVersion && compareSemver(version, rootVersion) > 0 ? [`${dep} ${rootVersion} (lib: ${version})`] : [];
     });
-    const newRootPackageJson = { ...rootPackageJson, dependencies, devDependencies };
-    await lib.workspace.setPackageJson(newRootPackageJson);
-    await lib.workspace.spawn("bun", ["install"]);
-    await lib.workspace.commit(`Merge ${lib.name} library dependencies`);
+    if (behind.length)
+      lib.logger.warn(`Kept the root versions of packages libs/${lib.name} lists newer: ${behind.join(", ")}`);
+    if (dependencies.length || devDependencies.length) {
+      await lib.workspace.setPackageJson({
+        ...rootPackageJson,
+        dependencies: this.#withAdded(rootPackageJson.dependencies, dependencies),
+        devDependencies: this.#withAdded(rootPackageJson.devDependencies, devDependencies)
+      });
+      await lib.workspace.spawn("bun", ["install"]);
+    }
+    if (await lib.workspace.hasChanges())
+      await lib.workspace.commit(`Merge ${lib.name} library dependencies`);
+  }
+  #withAdded(deps, added) {
+    if (!added.length)
+      return deps;
+    return Object.fromEntries([...Object.entries(deps ?? {}), ...added].sort(([a], [b]) => a < b ? -1 : 1));
   }
 }
 

package/{index-b95yhqjr.js → index-1gs9g12n.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-a37by9hn.js";
+} from "./index-q6ft9fkc.js";
 import {
   AGENT_BLOCK_START,
   AGENT_BLOCK_END,
@@ -13,14 +13,14 @@ import {
   CLAUDE_COMMENT_RULE,
   AppExecutor,
   LibExecutor
-} from "./index-150s07n8.js";
+} from "./index-50wb2a26.js";
 import {
   collectRecipeSources2,
   scanRecipes2
 } from "./index-hj6w4ka1.js";
 import {
   AkanContextAnalyzer
-} from "./index-8kvy8qb4.js";
+} from "./index-zyw622y1.js";
 import {
   Prompter2
 } from "./index-zzvvc845.js";

package/{index-y7hx1ygz.js → index-3xmzr1p1.js}

@@ -2,13 +2,13 @@
 import {
   runner,
   script
-} from "./index-a37by9hn.js";
+} from "./index-q6ft9fkc.js";
 import {
   FileSys2
 } from "./index-52w0fvh8.js";
 import {
   PkgExecutor
-} from "./index-150s07n8.js";
+} from "./index-50wb2a26.js";
 import {
   TypeScriptDependencyScanner2
 } from "./index-2ahj896a.js";

package/{index-mzjb6zp4.js → index-50jjwg8y.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   AppInfo
-} from "./index-150s07n8.js";
+} from "./index-50wb2a26.js";
 
 // pkgs/@akanjs/devkit/slicePlanner.ts
 class SlicePlanner {