@akanjs/devkit 3.1.2-rc.3 → 3.2.0-rc.0

package/artifact/implicitRootLayout.ts

@@ -2,6 +2,7 @@ import { readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
+import { StoreBootstrap } from "./storeBootstrap";
 
 export interface PageEntry {
   key: string;
@@ -148,7 +149,7 @@ async function writeGeneratedRootLayoutFile(opts: {
   appName: string;
   boundary: RootBoundary;
   rootSourceAbsPath: string | null;
-  includeStInit: boolean;
+  includeStoreBootstrap: boolean;
   includeSystemProvider: boolean;
 }): Promise<string> {
   await assertEnvClientConvention(opts.appCwdPath, opts.appName);
@@ -161,9 +162,7 @@ async function writeGeneratedRootLayoutFile(opts: {
   const inheritedSourceAbsPath =
     opts.rootSourceAbsPath && opts.rootSourceAbsPath !== opts.boundary.sourceAbsPath ? opts.rootSourceAbsPath : null;
   const inheritedSourceSpecifier = inheritedSourceAbsPath ? importSpecifier(absPath, inheritedSourceAbsPath) : null;
-  const clientImport = opts.includeStInit
-    ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
-    : `import "@apps/${opts.appName}/client";\n`;
+  const storeImport = opts.includeStoreBootstrap ? StoreBootstrap.source(opts.appName) : "";
   //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
   const inheritedLabel = inheritedSourceAbsPath ? posixRelative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
@@ -223,7 +222,7 @@ import { System } from "akanjs/ui/System/index.tsx";
 import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
-${clientImport}${inheritedImport}${userImport}
+${storeImport}${inheritedImport}${userImport}
 const userFonts = userLayout.fonts ?? inheritedLayout.fonts ?? [];
 const defaultFonts = userFonts.filter((font) => font.default);
 if (defaultFonts.length > 1) throw new Error("[route-convention] only one default font is allowed per root layout");
@@ -323,7 +322,7 @@ export async function resolveSsrPageEntries(opts: {
         appName: opts.appName,
         boundary,
         rootSourceAbsPath,
-        includeStInit: hasSt && boundary.segments.length === 0,
+        includeStoreBootstrap: hasSt,
         includeSystemProvider: !hasAncestorRootBoundary(boundary, rootBoundaries),
       }),
       seedAbsPaths: [...new Set([boundary.sourceAbsPath, rootSourceAbsPath].filter((absPath) => absPath !== null))],

package/artifact/storeBootstrap.ts

@@ -0,0 +1,24 @@
+import type { BarrelExportMap } from "../transforms/barrelAnalyzer";
+
+//* Not a bare `@apps/<app>/client` import: it names nothing the barrel rewrite can narrow, so every module's UI ships.
+export class StoreBootstrap {
+  static importLines(appName: string): string[] {
+    return StoreBootstrap.#lines([`@apps/${appName}/lib/useClient`, `@apps/${appName}/lib/st`]);
+  }
+
+  static source(appName: string): string {
+    return `${StoreBootstrap.importLines(appName).join("\n")}\n`;
+  }
+
+  static ofClientBarrel(specifier: string, exports: BarrelExportMap): string[] | null {
+    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])]);
+  }
+
+  static #lines(specifiers: string[]): string[] {
+    return specifiers.map((specifier) => `import ${JSON.stringify(specifier)};`);
+  }
+}

package/cloud/cloudApi.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
+import dayjs from "dayjs";
 import type { Workspace } from "../commandDecorators";
 import { tempDirs, writeJson, writeText } from "../testHelpers";
 import { CloudApi } from "./cloudApi";
@@ -9,8 +10,10 @@ import { CloudApi } from "./cloudApi";
 class FakeCloud {
   readonly server: ReturnType<typeof Bun.serve>;
   readonly refreshes: string[] = [];
+  readonly refreshBearers: (string | null)[] = [];
   reused = false;
   delayMs = 0;
+  lifetimeMs = 7 * 86_400_000;
   hang: boolean = false;
   readonly remoteAuthPolls: string[] = [];
   remoteAuthAnswers: (Response | { jwt: string; refreshToken?: string } | null)[] = [];
@@ -44,6 +47,7 @@ class FakeCloud {
     if (url.pathname !== "/api/refreshAuthToken") return new Response("not found", { status: 404 });
     const { refreshToken } = (await request.json()) as { refreshToken: string };
     this.refreshes.push(refreshToken);
+    this.refreshBearers.push(request.headers.get("authorization"));
     if (this.#spent.has(refreshToken)) this.reused = true;
     if (!this.#refreshTokens.delete(refreshToken)) return Response.json({ error: "invalid" }, { status: 401 });
     this.#spent.add(refreshToken);
@@ -53,7 +57,7 @@ class FakeCloud {
     this.#jwts.add(next.jwt);
     if (this.hang) await new Promise(() => undefined);
     await Bun.sleep(this.delayMs);
-    return Response.json({ ...next, expiresAt: new Date(Date.now() + 7 * 86_400_000).toISOString() });
+    return Response.json({ ...next, expiresAt: new Date(Date.now() + this.lifetimeMs).toISOString() });
   }
 }
 
@@ -100,13 +104,21 @@ await GlobalConfig.setTestTargets({ linux: { cpus: 2 } });
   return { code: await proc.exited, stderr: await new Response(proc.stderr).text() };
 };
 
-const storeSession = async (home: string, { expiresInMs = 30 * 60_000, refreshToken = "refresh-0" } = {}) =>
+const storeSession = async (
+  home: string,
+  { expiresInMs = 30 * 60_000, refreshToken = "refresh-0", issuedAgoMs = null as number | null } = {},
+) =>
   await writeJson(path.join(home, ".akan", "config.json"), {
     cloudHost: {
       [cloud.host]: {
         host: cloud.host,
         auth: {
-          accessToken: { jwt: "jwt-0", refreshToken, expiresAt: new Date(Date.now() + expiresInMs).toISOString() },
+          accessToken: {
+            jwt: "jwt-0",
+            refreshToken,
+            expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+            issuedAt: issuedAgoMs === null ? null : new Date(Date.now() - issuedAgoMs).toISOString(),
+          },
           self: { id: "u1", nickname: "akan" },
         },
       },
@@ -114,9 +126,34 @@ const storeSession = async (home: string, { expiresInMs = 30 * 60_000, refreshTo
   });
 const storedToken = async (home: string) => {
   const config = JSON.parse(await readFile(path.join(home, ".akan", "config.json"), "utf8"));
-  return config.cloudHost[cloud.host].auth.accessToken as { jwt: string; refreshToken: string | null };
+  return config.cloudHost[cloud.host].auth.accessToken as {
+    jwt: string;
+    refreshToken: string | null;
+    issuedAt?: string | null;
+  };
 };
 
+describe("CloudApi.needsSignIn", () => {
+  const apiWith = (accessToken: { refreshToken: string | null; expiresInMs: number }) =>
+    new CloudApi({ workspaceRoot: "/nowhere" } as unknown as Workspace, {
+      host: cloud.host,
+      auth: {
+        accessToken: {
+          jwt: "jwt-0",
+          refreshToken: accessToken.refreshToken,
+          expiresAt: dayjs().add(accessToken.expiresInMs, "ms"),
+        },
+      },
+    });
+
+  test("asks for a sign-in only when a session due for refresh has no refresh token left", () => {
+    cloud = new FakeCloud();
+    expect(apiWith({ refreshToken: null, expiresInMs: 30 * 60_000 }).needsSignIn).toBe(true);
+    expect(apiWith({ refreshToken: "refresh-0", expiresInMs: 30 * 60_000 }).needsSignIn).toBe(false);
+    expect(apiWith({ refreshToken: null, expiresInMs: 3 * 3_600_000 }).needsSignIn).toBe(false);
+  });
+});
+
 describe("CloudApi.fromHost token refresh", () => {
   test("two CLI processes with a session in its last hour make exactly one refresh, and both use its result", async () => {
     cloud = new FakeCloud();
@@ -165,20 +202,46 @@ describe("CloudApi.fromHost token refresh", () => {
     cloud.hang = false;
 
     const started = Date.now();
-    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
     expect(Date.now() - started).toBeLessThan(10_000);
     expect(cloud.refreshes).toEqual(["refresh-0"]);
     expect(cloud.reused).toBe(false);
     expect((await storedToken(home)).refreshToken).toBeNull();
   }, 30_000);
 
+  test("a cloud that issues one-hour tokens is refreshed once, and every command signs in with its token", async () => {
+    cloud = new FakeCloud();
+    cloud.lifetimeMs = 60 * 60_000;
+    const home = await makeHome();
+    await storeSession(home);
+
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+    expect(cloud.refreshBearers).toEqual([null]);
+    expect(await storedToken(home)).toMatchObject({ jwt: "jwt-1", refreshToken: "refresh-1" });
+    expect((await storedToken(home)).issuedAt).toBeString();
+  }, 30_000);
+
+  test("a one-hour token in the second half of its life is refreshed, and one in the first half is not", async () => {
+    cloud = new FakeCloud();
+    const home = await makeHome();
+    await storeSession(home, { expiresInMs: 35 * 60_000, issuedAgoMs: 25 * 60_000 });
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual([]);
+
+    await storeSession(home, { expiresInMs: 25 * 60_000, issuedAgoMs: 35 * 60_000 });
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+  }, 30_000);
+
   test("a refresh the cloud refuses is not presented again", async () => {
     cloud = new FakeCloud();
     const home = await makeHome();
     await storeSession(home, { refreshToken: "refresh-unknown" });
 
-    expect(await output(await cliRun(home))).toEqual([null]);
-    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
     expect(cloud.refreshes).toEqual(["refresh-unknown"]);
     expect((await storedToken(home)).refreshToken).toBeNull();
   }, 30_000);

package/cloud/cloudApi.ts

@@ -144,9 +144,9 @@ export class CloudApi {
   static async fromHost(workspace: Workspace, host?: string) {
     const hostConfig = await GlobalConfig.getHostConfig(host);
     const accessToken = hostConfig.auth?.accessToken;
-    // No refresh token on a session in its last hour can be another process's refresh in flight: wait on its lock.
+    // No refresh token on a session due for refresh can be another process's refresh in flight: wait on its lock.
     if (!accessToken || !GlobalConfig.needRefreshToken(accessToken)) return new CloudApi(workspace, hostConfig);
-    const tokenless = new CloudApi(workspace, hostConfig);
+    const tokenless = new CloudApi(workspace, { host: hostConfig.host });
     const refreshed = await GlobalConfig.refreshHostAuth(hostConfig.host, (refreshToken) =>
       tokenless.refreshAuthToken(refreshToken),
     );
@@ -158,12 +158,18 @@ export class CloudApi {
     this.host = hostConfig.host;
     this.url = `${this.host}/api`;
     this.#api = new HttpClient(this.url);
-    if (this.#accessToken && !GlobalConfig.needRefreshToken(this.#accessToken))
+    if (this.#accessToken && !GlobalConfig.isExpired(this.#accessToken))
       this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
   }
 
+  //? With no refresh token left, a session due for refresh ends at its expiry and only a new sign-in renews it.
+  get needsSignIn(): boolean {
+    const accessToken = this.#accessToken;
+    return !!accessToken && !accessToken.refreshToken && GlobalConfig.needRefreshToken(accessToken);
+  }
+
   #authorize(accessTokenDto: AccessTokenDto) {
-    this.#accessToken = GlobalConfig.toAccessToken(accessTokenDto);
+    this.#accessToken = GlobalConfig.toAccessToken({ ...accessTokenDto, issuedAt: new Date().toISOString() });
     this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
     return this.#accessToken;
   }

package/cloud/constants.ts

@@ -61,9 +61,12 @@ export interface AccessTokenDto {
   jwt: string;
   refreshToken: string | null;
   expiresAt: string | null;
+  issuedAt?: string | null;
 }
 export interface AccessToken {
   jwt: string;
   refreshToken: string | null;
   expiresAt: Dayjs | null;
+  //? When this CLI received the token, on its own clock: the cloud's answer names only the expiry.
+  issuedAt?: Dayjs | null;
 }

package/cloud/globalConfig.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { mkdir, stat } from "node:fs/promises";
 import path from "node:path";
+import dayjs from "dayjs";
 import { tempDirs } from "../testHelpers";
 import { GlobalConfig } from "./globalConfig";
 
@@ -22,6 +23,41 @@ const modeOf = async (target: string) => (await stat(target)).mode & 0o777;
 const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
 
 describe("GlobalConfig", () => {
+  test("needRefreshToken asks for a refresh in a token's last hour, or in the second half of a shorter life", () => {
+    const token = (issuedAgoMin: number | null, expiresInMin: number) => ({
+      jwt: "jwt",
+      refreshToken: "refresh",
+      expiresAt: dayjs().add(expiresInMin, "minute"),
+      issuedAt: issuedAgoMin === null ? null : dayjs().subtract(issuedAgoMin, "minute"),
+    });
+    const week = 7 * 24 * 60;
+    expect(GlobalConfig.needRefreshToken(token(0, 60))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(25, 35))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(35, 25))).toBe(true);
+    expect(GlobalConfig.needRefreshToken(token(0, 10))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(week - 61, 61))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(week - 59, 59))).toBe(true);
+    expect(GlobalConfig.needRefreshToken(token(null, 61))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(null, 59))).toBe(true);
+    expect(GlobalConfig.isExpired(token(59, 1))).toBe(false);
+    expect(GlobalConfig.isExpired(token(61, -1))).toBe(true);
+    expect(GlobalConfig.needRefreshToken({ ...token(0, 59), issuedAt: dayjs("not a date") })).toBe(true);
+  });
+
+  test("keeps a token's issuedAt through config.json, and leaves the key out when there is none", () => {
+    const issuedAt = dayjs().subtract(10, "minute");
+    const token = { jwt: "jwt", refreshToken: "refresh", expiresAt: dayjs().add(50, "minute"), issuedAt };
+    const read = GlobalConfig.toAccessToken(
+      JSON.parse(JSON.stringify(GlobalConfig.toAccessTokenDto(token))) as ReturnType<
+        typeof GlobalConfig.toAccessTokenDto
+      >,
+    );
+    expect(Math.abs(read.issuedAt?.diff(issuedAt) ?? Number.NaN)).toBeLessThan(1_000);
+    expect(GlobalConfig.needRefreshToken(read)).toBe(false);
+    const legacy = { jwt: "jwt", refreshToken: "refresh", expiresAt: null };
+    expect(GlobalConfig.toAccessTokenDto(GlobalConfig.toAccessToken(legacy))).toEqual(legacy);
+  });
+
   test("hostFor spells --host the way the workspace's cloud.host is spelled, so one login serves both", async () => {
     for (const given of ["https://cloud.example.com/", "https://Cloud.Example.com:443", "https://cloud.example.com//"])
       expect(await GlobalConfig.hostFor(workspace(null), given)).toBe("https://cloud.example.com");

package/cloud/globalConfig.ts

@@ -129,14 +129,22 @@ export class GlobalConfig {
       testTargets: { ...akanConfig.testTargets, ...testTargets },
     }));
   }
+  static readonly #refreshMarginMs = 60 * 60_000;
   static needRefreshToken(accessToken: AccessToken): boolean {
-    return !!accessToken?.expiresAt?.isBefore(dayjs().add(1, "hour"));
+    const { expiresAt, issuedAt } = accessToken;
+    if (!expiresAt) return false;
+    const lifetimeMs = issuedAt?.isValid() ? expiresAt.diff(issuedAt) : Number.POSITIVE_INFINITY;
+    return expiresAt.isBefore(dayjs().add(Math.min(GlobalConfig.#refreshMarginMs, lifetimeMs / 2), "ms"));
+  }
+  static isExpired(accessToken: AccessToken): boolean {
+    return !!accessToken.expiresAt && !accessToken.expiresAt.isAfter(dayjs());
   }
   static toAccessToken(accessToken: AccessTokenDto): AccessToken {
     return {
       jwt: accessToken.jwt,
       refreshToken: accessToken.refreshToken ?? null,
       expiresAt: accessToken.expiresAt ? dayjs(accessToken.expiresAt) : null,
+      ...(accessToken.issuedAt ? { issuedAt: dayjs(accessToken.issuedAt) } : {}),
     };
   }
   static toAccessTokenDto(accessToken: AccessToken): AccessTokenDto {
@@ -144,6 +152,7 @@ export class GlobalConfig {
       jwt: accessToken.jwt,
       refreshToken: accessToken.refreshToken ?? null,
       expiresAt: accessToken.expiresAt?.toString() ?? null,
+      ...(accessToken.issuedAt ? { issuedAt: accessToken.issuedAt.toString() } : {}),
     };
   }
   static toHostConfigDto(hostConfig: HostConfig): HostConfigDto {

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

@@ -15,7 +15,8 @@ the server errors logged meanwhile, console errors and warnings, and layout smel
   stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
   running one.
 - Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
-  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off.
+  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off. A `/_akan` route such as Studio
+  (`/_akan/studio?view=runtime`), a signal route or a file opens as written.
   `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
   path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
 - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native

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

@@ -8,6 +8,11 @@ description: "Add or change a route under page/: the one page()/layout() chain,
 A route file exports one chain and nothing else. Every setting is a stage of it.
 
 ```tsx
+import { fetch, Task, usePage } from "@apps/<app>/client";
+import { signedIn } from "@libs/shared/webkit";
+import { ID } from "akanjs/base";
+import { page } from "akanjs/client";
+
 export default page()
   .param("orgId", ID)
   .guard(() => signedIn())
@@ -26,7 +31,8 @@ export default page()
 2. Name every `[x]` segment with `.param("x", Type)` and read a query key only with `.search("k", Type)`. Values
    arrive typed; `lang` reaches every stage and is never declared.
 3. Gate with `.guard(() => signedIn())` on the `_layout.tsx` (a real redirect before anything renders), and repeat
-   a stricter guard on a page that needs more. The endpoint guards are still the real gate.
+   a stricter guard on a page that needs more. The endpoint guards are still the real gate. `signedIn` comes from
+   `@libs/shared/webkit`, and a new workspace has that lib only with `create-workspace --libs true`.
 4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
    unawaited; await only what the shell reads, in one `Promise.all`.
 5. `.head()` takes JSX (or a function returning it), never a metadata object. A canonical link comes only from the
@@ -34,6 +40,27 @@ export default page()
 6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
    `export default override({ Slot: AppComponent })`, no logic.
 
+## API at a glance
+
+`page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
+`akanjs/webkit`, and `fetch`, `usePage` and the model namespaces from `@apps/<app>/client`. A stage receives the
+declared params and search keys plus `lang`.
+
+- Data-driven title: `.head(async ({ id }) => <title>{((await fetch.book(id)) as Book | null)?.title}</title>)`,
+  where `Book` is the `common/` interface for the query's `Any` return (`akan-service`).
+- Async page: `.render(async ({ id }) => { const book = (await fetch.book(id)) as Book | null; if (!book) return router.notFound(); … })`;
+  the same query in `.head()` and `.render()` is one request.
+- `router.notFound()` from `.guard()`, `.head()` or `.render()` answers 404 with the nearest layout's `.notFound()`
+  above it (an unmatched URL: the deepest layout covering it), else the built-in 404.
+- A layout's own 404 and error views: `.notFound(({ pathname }) => …)` and `.error(({ error }) => …)` on `layout()`
+  or `rootLayout()`.
+- `<Link href="/books/OL45804W">`: write the path without the locale; Link adds it, or leaves it off for the default
+  locale under `i18n.localePrefix: "as-needed"`. `activeClassName` marks the current one.
+- From a handler: `router.push(href)` / `router.replace(href)`; in a server stage, `router.redirect(href)`.
+- A client filter kept in the URL without reloading the page: ``router.replace(`/books?q=${q}`, { shallow: true,
+  scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
+  holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
+
 ## Never
 
 - A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
@@ -41,4 +68,5 @@ export default page()
 - `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
 - Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
 
-Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server.
+Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server; every stage's
+signature, the router's methods, Link's props and every import path: `akanApi`.

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

@@ -20,6 +20,10 @@ dictionary is a `serviceDictionary`.
   explicitly `void`-ed.
 - Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an
   error.
+- `serve(name, { serverMode: "batch" }, …)` mounts the module, endpoints included, only in a `batch` or `all`
+  process; a `federation` replica, the one serving requests in a split deployment, skips it. The app's own
+  `lib/_<app>/` service is scaffolded with it for cron and queue work. Leave it off a service a page calls, as
+  `akan create-service` does.
 
 ## Reaching other things
 
@@ -31,4 +35,76 @@ registered under `<refName>`, and the `Service` suffix is required.
 An external API or piece of infrastructure is an `adapt()` class in `srvkit/`, injected with `plug`. It
 self-registers, so do **not** add it to `lib/option.ts`.
 
-Full detail: `get_guideline` with `modelService`.
+## Recipe: pages backed by an external HTTP API
+
+`akan create-service openlibrary <app>` scaffolds `lib/_openlibrary/`; the adapter beside it is yours.
+
+```ts
+// srvkit/bookApi.ts — read at boot, so the built server takes API_BASE_URL from the host that runs it
+import { adapt } from "akanjs/service";
+
+export class BookApi extends adapt("bookApi" as const, ({ env }) => ({
+  baseUrl: env(() => process.env.API_BASE_URL ?? "http://localhost:9000"),
+})) {
+  async get<T>(path: string): Promise<T | null> {
+    try {
+      const res = await fetch(`${this.baseUrl}/${path}`, { signal: AbortSignal.timeout(20_000) });
+      if (res.ok) return (await res.json()) as T;
+      if (res.status !== 404) this.logger.warn(`${path} answered ${res.status}`);
+    } catch (error) {
+      this.logger.warn(`${path} failed: ${String(error)}`);
+    }
+    return null;
+  }
+}
+
+// lib/_openlibrary/openlibrary.service.ts — shape the upstream JSON here, not in the page
+import { BookApi } from "@apps/<app>/srvkit";
+import { serve } from "akanjs/service";
+
+interface ApiWork {
+  key: string;
+  title: string;
+}
+
+export class OpenlibraryService extends serve("openlibrary" as const, ({ plug }) => ({ bookApi: plug(BookApi) })) {
+  async getBook(id: string) {
+    const work = await this.bookApi.get<ApiWork>(`works/${id}.json`);
+    return work && { id, title: work.title };
+  }
+}
+
+// lib/_openlibrary/openlibrary.signal.ts — Any answers plain JSON; nullable lets it answer null for "not found"
+import { Any } from "akanjs/base";
+import { endpoint, internal, Public } from "akanjs/signal";
+
+import * as srv from "../srv";
+
+export class OpenlibraryInternal extends internal(srv.openlibrary, () => ({})) {}
+
+export class OpenlibraryEndpoint extends endpoint(srv.openlibrary, ({ query }) => ({
+  book: query(Any, { guards: [Public], nullable: true })
+    .param("id", String)
+    .exec(async function (id) {
+      return await this.openlibraryService.getBook(id);
+    }),
+})) {}
+
+// lib/_openlibrary/openlibrary.dictionary.ts — typecheck asks a label for every endpoint
+import { serviceDictionary } from "akanjs/dictionary";
+
+import type { OpenlibraryEndpoint } from "../sig";
+
+export const dictionary = serviceDictionary(["en", "ko"])
+  .endpoint<OpenlibraryEndpoint>((fn) => ({ book: fn(["Book", "책"]) }))
+  .error({})
+  .translate({});
+```
+
+The page calls it as `await fetch.book(id)` (`fetch` from `@apps/<app>/client`) and ends with
+`return router.notFound()` on `null`. An `Any` return reaches the page as `unknown`: type it with an interface in
+`common/`, or return a scalar (`akan create-scalar`) for a typed wire shape. A query that answers `null` without
+`nullable: true` fails the render, naming the endpoint.
+
+Full detail: `get_guideline` with `modelService`; every import path and the exact signatures of serve, adapt,
+endpoint and serviceDictionary: `akanApi`.

package/commandDecorators/command.ts

@@ -229,6 +229,28 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   );
 };
 
+export type RerunOf = (target: string) => string;
+
+const shellWordOf = (word: string) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
+
+//? Commander fills operands left to right, so every operand before an empty slot was given.
+export const rerunCommandOf =
+  (argv: readonly string[], operands: readonly unknown[], slot: number): RerunOf =>
+  (target) => {
+    const [commandName = "", ...words] = argv;
+    let at = 0;
+    for (const operand of operands.slice(0, slot)) if (typeof operand === "string") at = words.indexOf(operand, at) + 1;
+    const given = operands[slot];
+    const givenAt = typeof given === "string" ? words.indexOf(given, at) : -1;
+    const rerun = words.map(shellWordOf);
+    if (givenAt >= 0) rerun.splice(givenAt, 1, target);
+    else rerun.splice(at, 0, target);
+    return ["akan", commandName, ...rerun].join(" ");
+  };
+
+const rerunRemedyOf = (rerun: RerunOf | undefined, placeholder: string) =>
+  rerun ? { remedy: `rerun it as \`${rerun(placeholder)}\`` } : {};
+
 const parseAppNameList = (value: string | string[] | undefined): string[] =>
   (Array.isArray(value) ? value : value === undefined ? [] : [value])
     .flatMap((entry) => entry.split(","))
@@ -239,6 +261,7 @@ const parseAppNameList = (value: string | string[] | undefined): string[] =>
 export const getAppsArgumentValue = async (
   value: string | string[] | undefined,
   workspace: WorkspaceExecutor,
+  rerun?: RerunOf,
 ): Promise<AppExecutor[]> => {
   const appNames = await workspace.getApps();
   if (appNames.length === 0) throw new Error("No apps found in this workspace (apps/<appName>/akan.config.ts)");
@@ -253,7 +276,7 @@ export const getAppsArgumentValue = async (
     return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
   }
   if (appNames.length === 1 && appNames[0]) return [AppExecutor.from(workspace, appNames[0])];
-  assertPromptable("Missing apps", { choices: [...appNames, "all"] });
+  assertPromptable("Missing apps", { choices: [...appNames, "all"], ...rerunRemedyOf(rerun, "<apps...>") });
   const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
   const picked = await checkbox<string>({
     message: "Select the apps to run (space to toggle, enter to confirm)",
@@ -269,6 +292,7 @@ export const getInternalArgumentValue = async (
   argMeta: InternalArgMeta,
   value: string | undefined,
   workspace: WorkspaceExecutor,
+  rerun?: RerunOf,
 ) => {
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
@@ -286,12 +310,24 @@ export const getInternalArgumentValue = async (
     if (found) return found;
     if (!value && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
       return AppExecutor.from(workspace, appNames[0]);
-    assertPromptable(problemOf(sysType === "exec" ? "app, lib or pkg" : "app or lib"), {
-      choices: [...appNames, ...libNames, ...pkgChoices],
-    });
+    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) {
+      const how = rerun ? `: ${rerun(only.name)}` : "";
+      Logger.rawLog(
+        `No ${kind} named, so this runs on '${only.name}', the only one in this workspace${how}`,
+        undefined,
+        "error",
+      );
+      return only;
+    }
+    assertPromptable(problemOf(kind), { choices, ...rerunRemedyOf(rerun, placeholder) });
     const name = await select<string>({
       message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
-      choices: [...appNames, ...libNames, ...pkgChoices],
+      choices,
     });
     const picked = execOf(name);
     if (!picked) throw new Error(`Invalid system name: ${name}`);
@@ -299,18 +335,18 @@ export const getInternalArgumentValue = async (
   } 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 });
+    assertPromptable(problemOf("app"), { choices: appNames, ...rerunRemedyOf(rerun, "<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 });
+    assertPromptable(problemOf("lib"), { choices: libNames, ...rerunRemedyOf(rerun, "<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 });
+    assertPromptable(problemOf("pkg"), { choices: pkgs, ...rerunRemedyOf(rerun, "<pkg>") });
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
@@ -328,7 +364,14 @@ export const getInternalArgumentValue = async (
         if (modules.includes(moduleName)) return ModuleExecutor.from(lib, moduleName);
       } else throw new Error(`Invalid system name: ${sysName}`);
     }
-    assertPromptable(problemOf("module"));
+    const systems = [
+      ...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 { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -443,6 +486,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
           const workspace = WorkspaceExecutor.fromRoot();
           const commandContext: CommandContext = { values: {} };
           for (const argMeta of allArgMetas) {
+            const rerun = rerunCommandOf(process.argv.slice(2), cmdArgs, argMeta.idx);
             if (argMeta.type === "Option")
               commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt, commandContext);
             else if (argMeta.type === "Argument")
@@ -451,12 +495,14 @@ export const runCommands = async (...commands: CommandCls[]) => {
               commandArgs[argMeta.idx] = await getAppsArgumentValue(
                 cmdArgs[argMeta.idx] as string | string[] | undefined,
                 workspace,
+                rerun,
               );
             else
               commandArgs[argMeta.idx] = await getInternalArgumentValue(
                 argMeta as InternalArgMeta,
                 cmdArgs[argMeta.idx] as string,
                 workspace,
+                rerun,
               );
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;