@akanjs/devkit 3.0.2 → 3.1.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @akanjs/devkit
 
+## 3.0.2
+
+### Minor Changes
+
+- be8ed50: New lint rules: `no-unguarded-endpoint` warns on an endpoint, named slice or root slice that declares no guards, and `no-double-brace-placeholder` refuses `{{name}}` in a dictionary error/translate entry. `no-throw-raw-error` also warns on a raw `Error` constructed without `throw`, and `no-inline-color` warns on color literals in SVG color attributes and `el.style` writes.
+- af66669: Native builds moved from `apps/<app>/.akan/native/<target>` to `dist/native/<app>/<target>` (`build/<platform>`, `dev/<platform>`, `web`, `bin`, `updates`). It sits outside `dist/apps/<app>`, which every `akan build` empties, so a signed release waiting for upload survives the next build. Upload what is waiting in an old `.akan/native/<target>/updates` and delete the folder: `akan start` keeps it and warns until then. A CI step that collects installers reads `dist/native/<app>/*/build/*/` now, and `pack-update`'s default output is `dist/native/<app>/<target>/updates/<platform>`.
+- af66669: The macOS dmg `build-desktop --installer true` makes opens on a drag-to-Applications window: no toolbar, sidebar or status bar, 128 pt icons of the app and the Applications link on a background with an arrow between them (1x and 2x in one multi-resolution TIFF), and the app's icon on the mounted disk (`.VolumeIcon.icns`). Its own files (`.background`, `.VolumeIcon.icns`, `.DS_Store`, `.fseventsd`) are hidden. The window is a `.DS_Store` written directly while a read-write image is mounted, never through Finder or AppleScript, so a headless CI builds the same image; the compressed image is made afterwards and is what gets signed, notarized and stapled. `native.desktop.dmg` (a target's too) replaces the background (`background`, `background2x`, or `false`) and moves the window and the icons (`window`, `iconSize`, `textSize`, `app`, `applications`, in points); the default background lines up with the default positions only.
+- be8ed50: `akan sync` prunes a root-declared dependency nothing imports and realigns every root-declared entry to the root's version; `package.json#akan.keepDependencies`, `externalLibs` and `trustedDependencies` are always kept. `akan install-library` keeps the root's versions and only adds what the root lacks.
+
+### Patch Changes
+
+- af66669: `akan build-desktop` builds for this computer's CPU without asking; `--arch arm64|x64` picks another one. Any CLI option declared both `enum` and `nullable` is now `null` when left out instead of prompting for one of its choices.
+- af66669: Upgrading may stop `akan sync` (and every command that runs it, `build-desktop` included) with a scan-convention error on a hand-written `index.tsx`, `index.jsx` or `index.mts` at the root of `ui/`, `webkit/`, `srvkit/`, `common/` or `plugin/`. Bun loads that file ahead of the generated `index.ts` while TypeScript checks `index.ts`, so a name only the generated barrel exports typechecks and is undefined at runtime. Delete the file: the generated barrel re-exports every file and folder of the facet. A namespace it built belongs in `<facet>/<Folder>/index.tsx`, which the check leaves alone.
+- be8ed50: Generated barrels, module indexes and `akan.*.json` are written exactly as Biome prints them, so `akan lint --no-fix` passes right after a sync.
+- af66669: A native build's `--env` reaches its CSR bundle. The CSR builds passed `env: "AKAN_PUBLIC_*"` to `Bun.build`, which inlines the `.env` Bun read when the process started and ranks it above `define`, so `build-desktop --env debug` shipped the root `.env`'s `AKAN_PUBLIC_ENV=local` and called `http://localhost:8282`, and `akan build` baked back the operation mode and ports it had just dropped. Every `AKAN_PUBLIC_*` now comes from `process.env` through `define` alone, and `akan build` drops `AKAN_PUBLIC_CLIENT_PORT` / `AKAN_PUBLIC_SERVER_PORT` from `process.env` as well, so a port in `.env` is no longer baked in.
+- af66669: A Linux desktop app's window is named after its app id (X11 `WM_CLASS`, Wayland `app_id`), so a dock or task bar finds its `<app id>.desktop` and shows that entry's name and icon instead of a generic one; the dock plugin's badge and progress name the same entry. The AppImage `build-desktop --installer true` makes carries `<app id>.desktop` with `StartupWMClass=<app id>` and `<app id>.png`, so the entry AppImageLauncher or appimaged installs under another file name still matches the window. The hidden entry that handles the app's deep links now shows the app's icon (installed as `~/.local/share/icons/hicolor/256x256/apps/<app id>.png`), and from an AppImage it starts the AppImage itself (`$APPIMAGE`) rather than the mount point it ran from, which is gone once the app quits, so a link opened after quitting the app no longer fails.
+- af66669: A `--env local` release build (`build-*`, `release-*`, `start-* --release true`, `publish-update`) calls the app's own dev server: its `env.runtime.json` names `PUBLIC_AKAN_SERVER_URL=http://localhost:<dev port>`, the port `akan start` gives the app (`AKAN_DEV_PORT`, else its place among the apps). Before, it always called 8282, which in a workspace with several apps is another app or nothing. A target that carries its server keeps the URL its server hands the page at launch, and an `AKAN_PUBLIC_SERVER_URL` the bundle was built with still wins.
+- be8ed50: `akan quality scan` no longer flags a non-exported interface or type declared beside a class.
+- 73a81da: Let non-local single database mode development servers continue when the Redis SSH tunnel is unavailable, warning with the SSH target and underlying connection errors and setting an explicitly unavailable Redis host instead of falling back to a local Redis instance. Working tunnels remain available to custom Redis adaptors, while multiple and cluster modes still require Redis and local development remains unchanged.
+- Updated dependencies [be8ed50]
+- Updated dependencies [af66669]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [af66669]
+- Updated dependencies [af66669]
+- Updated dependencies [bd55713]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+- Updated dependencies [a789952]
+- Updated dependencies [be8ed50]
+- Updated dependencies [be8ed50]
+  - akanjs@3.1.0
+
 ## 3.0.1
 
 ### Minor Changes
@@ -557,13 +596,13 @@
   formatter, the rule set, and every grit plugin registration; a workspace `biome.json` is `extends` plus its own
   `files.includes`. Biome resolves the specifier through node*modules (it does not consult the package `exports`
   map), and `plugins` paths inside an extended config resolve from the entry config's directory, so the
-  `./node_modules/@akanjs/devkit/lint/*.grit` form the template already used is correct. Rule changes now reach a
-  workspace on `bun update` with no command to run. Two merge behaviours decided the split: `overrides` concatenate,
-  so the generated-file opt-out moved there from `files.includes`, which \_replaces* and would silently drop the base
-  list the moment a workspace added one exclusion of its own. Because Biome moves rules between groups across minors
-  (`noUnnecessaryConditions` is `nursery` at 2.4 and `suspicious` at 2.5, and the old position is a hard error), the
-  base config and the Biome version travel together: `biomeBase.ts` pins the version `createWorkspace` installs
-  instead of resolving `latest`.
+  `./node_modules/@akanjs/devkit/lint/*.grit`form the template already used is correct. Rule changes now reach a
+workspace on`bun update`with no command to run. Two merge behaviours decided the split:`overrides`concatenate,
+so the generated-file opt-out moved there from`files.includes`, which \_replaces* and would silently drop the base
+list the moment a workspace added one exclusion of its own. Because Biome moves rules between groups across minors
+(`noUnnecessaryConditions`is`nursery`at 2.4 and`suspicious`at 2.5, and the old position is a hard error), the
+base config and the Biome version travel together:`biomeBase.ts`pins the version`createWorkspace`installs
+instead of resolving`latest`.
 
   **The conventions body moved into the managed block.** It now ships as the `conventions` guideline and renders
   between the `akan:agent` markers, so `akan agent install` refreshes it. `AGENTS.md.template` carried a _second_,

package/akanApp/akanApp.host.ts

@@ -1289,8 +1289,9 @@ export class AkanAppHost {
       void this.#wakeFromIdle(`${message.type} arrived while suspended`);
       return;
     }
-    // In `env`, which every builder spawn re-reads, so a restarted builder stays armed for a mobile dev session.
-    if (message.type === "build-csr" && this.env.AKAN_DEV_CSR_REBUILD !== "1") {
+    // In `env`, which every builder spawn re-reads, so a restarted builder stays armed for a mobile dev session. A view's
+    // shell is asked for per read, so it arms nothing.
+    if (message.type === "build-csr" && !message.shell && this.env.AKAN_DEV_CSR_REBUILD !== "1") {
       Object.assign(this.env, { AKAN_DEV_CSR_REBUILD: "1" });
       this.logger.verbose(`[csr] armed dev CSR rebuilds (${message.reason})`);
     }

package/akanConfig/akanConfig.test.ts

@@ -342,7 +342,7 @@ describe("AkanAppConfig", () => {
     const clusterConfig = configOf({ modes: ["cluster"] });
     const edgeAndCloud = configOf({ modes: ["single", "cluster"] });
 
-    for (const driver of ["ioredis", "bullmq", "postgres", "@libsql/client", "protobufjs"])
+    for (const driver of ["ioredis", "bullmq", "postgres", "protobufjs"])
       expect(dependenciesOf(singleConfig)).not.toHaveProperty(driver);
     expect(dependenciesOf(multipleConfig)).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
@@ -353,9 +353,9 @@ describe("AkanAppConfig", () => {
       ioredis: runtimeDependencies.ioredis,
       postgres: runtimeDependencies.postgres,
     });
-    // multiple opens the same SQLite as single and Redis replaced protobuf on the wire, so neither ships by default.
+    // Redis replaced protobuf on the wire, so it ships with no mode.
     for (const config of [multipleConfig, clusterConfig])
-      for (const driver of ["@libsql/client", "protobufjs"]) expect(dependenciesOf(config)).not.toHaveProperty(driver);
+      expect(dependenciesOf(config)).not.toHaveProperty("protobufjs");
     expect(dependenciesOf(multipleConfig)).not.toHaveProperty("postgres");
     // One image for an edge site and a cloud cluster carries both modes' drivers, and says which it carries.
     expect(dependenciesOf(edgeAndCloud)).toMatchObject({ postgres: runtimeDependencies.postgres });
@@ -477,7 +477,7 @@ describe("AkanAppConfig", () => {
     ).toThrow("unknown basePath");
   });
 
-  test("a desktop server is true or { omit }, its names trimmed, deduplicated and sorted", () => {
+  test("a desktop server is true or { omit, profile, modules }, its lists trimmed, deduplicated and sorted", () => {
     const resolve = (server: unknown) =>
       new AkanAppConfig(app, [], packageJson, { native: { desktop: { server } } } as never, baseDevEnv).native.targets
         .default.desktop?.server;
@@ -487,6 +487,41 @@ describe("AkanAppConfig", () => {
     expect(resolve({})).toEqual({ omit: [] });
     expect(() => resolve({ omit: "rclnodejs" })).toThrow("native.desktop.server.omit in apps/");
     expect(() => resolve({ exclude: ["rclnodejs"] })).toThrow("native.desktop.server.exclude in apps/");
+    expect(resolve({ profile: "edge", modules: ["@edge", " edgeAgent"] })).toEqual({
+      omit: [],
+      profile: "edge",
+      modules: ["@edge", "edgeAgent"],
+    });
+    expect(() => resolve({ profile: "../main" })).toThrow("native.desktop.server.profile in apps/");
+    expect(() => resolve({ modules: "@edge" })).toThrow("native.desktop.server.modules in apps/");
+  });
+
+  test("a desktop server's env, restart and watchdog: secret-free, what the stage owns refused, a watchdog defaulted", () => {
+    const resolve = (server: unknown) =>
+      new AkanAppConfig(app, [], packageJson, { native: { desktop: { server } } } as never, baseDevEnv).native.targets
+        .default.desktop?.server;
+
+    expect(
+      resolve({
+        env: { CLOUD_ORIGIN: "https://cloud.example", ENROLL_KEY: "fleet" },
+        restart: "forever",
+        watchdog: true,
+      }),
+    ).toEqual({
+      omit: [],
+      env: { CLOUD_ORIGIN: "https://cloud.example", ENROLL_KEY: "fleet" },
+      restart: "forever",
+      watchdog: { intervalMs: 10_000, failures: 3 },
+    });
+    expect(resolve({ restart: 8, watchdog: { failures: 5 } })).toMatchObject({
+      restart: 8,
+      watchdog: { intervalMs: 10_000, failures: 5 },
+    });
+    expect(() => resolve({ env: { SLACK_WEBHOOK_URL: "https://hooks" } })).toThrow("SLACK_WEBHOOK_URL");
+    expect(() => resolve({ env: { AKAN_MODULES: "@edge" } })).toThrow("the carried server's stage owns");
+    expect(() => resolve({ env: { PORT: 1 } })).toThrow("must be an object of strings");
+    expect(() => resolve({ restart: 0 })).toThrow('must be "forever" or a count');
+    expect(() => resolve({ watchdog: { intervalMs: -1 } })).toThrow("watchdog in apps/");
   });
 
   test("an app without basePaths has one target, default, with no basePath and the section's settings", () => {
@@ -589,10 +624,10 @@ describe("AkanAppConfig", () => {
           { native: { targets: { pilot: { updates: { channel: "pilot" } } } } },
           baseDevEnv,
         ),
-    ).toThrow("native.targets.pilot.updates in apps/portal/akan.config.ts has no url or publicKey");
+    ).toThrow("native.targets.pilot.updates in apps/portal/akan.config.ts has no url or publicKeys");
     expect(
       () => new AkanAppConfig(app, [], packageJson, { native: { updates: { channel: "pilot" } } }, baseDevEnv),
-    ).toThrow("native.updates in apps/portal/akan.config.ts has no url or publicKey.");
+    ).toThrow("native.updates in apps/portal/akan.config.ts has no url or publicKeys.");
   });
 
   test("merges the desktop settings field by field, the target winning", () => {
@@ -895,3 +930,38 @@ describe("AkanAppConfig.importConfigModule", () => {
     }
   });
 });
+
+describe("pipeline and workspace keys in app and lib configs", () => {
+  test("an app's pipeline is dropped before the instance exists, so it never reaches akan.app.json", async () => {
+    const config = await loadExtAppConfig(
+      "akan-config-app-keys-",
+      'export default { externalLibs: ["ext-a"], pipeline: { stages: [{ use: "build" }] } };\n',
+      "export default {};\n",
+    );
+    expect(config.externalLibs).toContain("ext-a");
+    expect("pipeline" in config).toBe(false);
+    expect(Object.keys(JSON.parse(JSON.stringify(config)) as object)).not.toContain("pipeline");
+  });
+
+  test("an app refuses the workspace's subspace setting", async () => {
+    const loading = loadExtAppConfig(
+      "akan-config-subspace-",
+      "export default { subspace: { subspaces: [] } };\n",
+      "export default {};\n",
+    );
+    expect(loading).rejects.toThrow("a workspace setting");
+  });
+
+  test("a lib takes neither a pipeline nor a subspace", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-lib-keys-"));
+    try {
+      const lib = { name: "extlib", cwdPath: root } as never;
+      fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { pipeline: { stages: [] } };\n");
+      expect(AkanLibConfig.from(lib)).rejects.toThrow("which a lib does not take");
+      fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { subspace: { subspaces: [] } };\n");
+      expect(AkanLibConfig.from(lib, { bustImportCache: true })).rejects.toThrow("a workspace setting");
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/akanConfig/akanConfig.ts

@@ -7,6 +7,7 @@ import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
+import { ServerEnvProfile } from "../transforms/serverEnvProfile";
 import type { BaseDevEnv, PackageJson } from "../types";
 import { AkanBin } from "./akanBin";
 import {
@@ -280,9 +281,9 @@ export class AkanAppConfig implements AppConfigResult {
         if (basePath && !this.basePaths.has(basePath))
           throw new Error(`Native target '${name}' uses unknown basePath '${basePath}' in ${configPath}`);
         const { updates } = merged;
-        if (updates && (!updates.url || !updates.publicKey))
+        if (updates && (!updates.url || !(updates.publicKey || updates.publicKeys?.length)))
           throw new Error(
-            `${where}.updates in ${configPath} has no url or publicKey${named ? "; give them in native.updates or the target's own" : ""}.`,
+            `${where}.updates in ${configPath} has no url or publicKeys${named ? "; give them in native.updates or the target's own" : ""}.`,
           );
         AkanAppConfig.#assertFiles(own ?? {}, where, configPath);
         const {
@@ -330,7 +331,7 @@ export class AkanAppConfig implements AppConfigResult {
     );
     return { appName, appId, ...(root.fileName ? { fileName: root.fileName } : {}), version, buildNum, targets };
   }
-  //? `true` or `{ omit }`: each omitted name trimmed once, so two targets that omit the same packages stage one server.
+  //? `true` or `{ omit, profile, modules }`: lists trimmed once, so two targets that agree on them stage one server.
   static #desktopServer<T extends { server?: AkanNativeDesktopConfig["server"] }>(
     desktop: T,
     where: string,
@@ -339,12 +340,74 @@ export class AkanAppConfig implements AppConfigResult {
     const { server } = desktop;
     if (server === undefined || typeof server === "boolean") return desktop;
     if (!AkanAppConfig.#isPlainObject(server))
-      throw new Error(`${where} in ${configPath} must be true or { omit: string[] }.`);
-    const omit = server.omit;
-    if (omit !== undefined && (!Array.isArray(omit) || omit.some((name) => typeof name !== "string" || !name.trim())))
-      throw new Error(`${where}.omit in ${configPath} must be a list of package names.`);
-    const names = [...new Set((omit ?? []).map((name) => name.trim()))].sort();
-    return { ...desktop, server: { omit: names } };
+      throw new Error(`${where} in ${configPath} must be true or { omit, profile, modules }.`);
+    const names = (list: unknown, key: string, what: string) => {
+      if (list === undefined) return [];
+      if (!Array.isArray(list) || list.some((name) => typeof name !== "string" || !name.trim()))
+        throw new Error(`${where}.${key} in ${configPath} must be a list of ${what}.`);
+      return [...new Set(list.map((name: string) => name.trim()))].sort();
+    };
+    const { profile } = server;
+    if (profile !== undefined && (typeof profile !== "string" || !ServerEnvProfile.namePattern.test(profile)))
+      throw new Error(
+        `${where}.profile in ${configPath} names env/env.server.<env>.<profile>.ts: a lowercase-first name of letters, digits and dashes.`,
+      );
+    const modules = names(server.modules, "modules", "module names or @<operationMode> selectors");
+    const env = AkanAppConfig.#desktopServerEnv(server.env, where, configPath);
+    const { restart } = server;
+    if (restart !== undefined && restart !== "forever" && !(Number.isInteger(restart) && (restart as number) > 0))
+      throw new Error(`${where}.restart in ${configPath} must be "forever" or a count of crashes in a row from 1.`);
+    const watchdog = AkanAppConfig.#desktopServerWatchdog(server.watchdog, where, configPath);
+    return {
+      ...desktop,
+      server: {
+        omit: names(server.omit, "omit", "package names"),
+        ...(profile ? { profile } : {}),
+        ...(modules.length ? { modules } : {}),
+        ...(Object.keys(env).length ? { env } : {}),
+        ...(restart !== undefined ? { restart } : {}),
+        ...(watchdog ? { watchdog } : {}),
+      },
+    };
+  }
+  //? The stage owns these: the operation mode, the database mode and what is served are what make it the carried server.
+  static readonly #stagedServerEnv = new Set([
+    "AKAN_PUBLIC_OPERATION_MODE",
+    "AKAN_DATABASE_MODE",
+    "AKAN_DATABASE_MODES",
+    "AKAN_SSR",
+    "AKAN_CSR",
+    "AKAN_MODULES",
+  ]);
+  static #desktopServerEnv(env: unknown, where: string, configPath: string): Record<string, string> {
+    if (env === undefined) return {};
+    if (!AkanAppConfig.#isPlainObject(env) || Object.values(env).some((value) => typeof value !== "string"))
+      throw new Error(`${where}.env in ${configPath} must be an object of strings.`);
+    const staged = Object.keys(env).filter((key) => AkanAppConfig.#stagedServerEnv.has(key.toUpperCase()));
+    if (staged.length)
+      throw new Error(
+        `${where}.env in ${configPath} sets ${staged.join(", ")}, which the carried server's stage owns (modules: desktop.server.modules).`,
+      );
+    const secrets = ServerEnvProfile.secretPaths(env);
+    if (secrets.length)
+      throw new Error(
+        `${where}.env in ${configPath} holds secret-named values (${secrets.join(", ")}), and the app carries its env where anyone on the computer reads it. Leave them out.`,
+      );
+    return env as Record<string, string>;
+  }
+  static #desktopServerWatchdog(
+    watchdog: unknown,
+    where: string,
+    configPath: string,
+  ): { intervalMs: number; failures: number } | null {
+    if (watchdog === undefined || watchdog === false) return null;
+    const { intervalMs = 10_000, failures = 3 } = (watchdog === true ? {} : watchdog) as Record<string, unknown>;
+    const whole = (value: unknown) => Number.isInteger(value) && (value as number) > 0;
+    if ((watchdog !== true && !AkanAppConfig.#isPlainObject(watchdog)) || !whole(intervalMs) || !whole(failures))
+      throw new Error(
+        `${where}.watchdog in ${configPath} must be true or { intervalMs, failures }, whole numbers from 1.`,
+      );
+    return { intervalMs: intervalMs as number, failures: failures as number };
   }
   static #platformIndexPath<T extends { indexPath?: string }>(section: T): T {
     const { indexPath: rawIndexPath, ...rest } = section;
@@ -356,7 +419,7 @@ export class AkanAppConfig implements AppConfigResult {
     const merge = (kept: unknown, value: unknown, top: boolean, key: string): unknown => {
       if (!AkanAppConfig.#isPlainObject(kept) || !AkanAppConfig.#isPlainObject(value)) return value;
       //? An icon or splash given as an object is one value: its image and color go together.
-      if (top && (key === "icon" || key === "splash")) return value;
+      if (top && (key === "icon" || key === "splash" || key === "backgroundColor")) return value;
       const out: Record<string, unknown> = { ...kept };
       for (const [inner, next] of Object.entries(value))
         if (next !== undefined) out[inner] = merge(out[inner], next, false, inner);
@@ -381,10 +444,12 @@ export class AkanAppConfig implements AppConfigResult {
       "buildNum",
       "icon",
       "splash",
+      "backgroundColor",
       "permissions",
       "plugins",
       "deepLinks",
       "updates",
+      "devtools",
       "ios",
       "android",
       "desktop",
@@ -401,8 +466,18 @@ export class AkanAppConfig implements AppConfigResult {
       "activity",
       "files",
     ],
-    desktop: ["indexPath", "server", "recovery", "window", "screenCapture", "entitlements", "dmg"],
-    desktopServer: ["omit"],
+    desktop: [
+      "indexPath",
+      "server",
+      "recovery",
+      "window",
+      "screenCapture",
+      "webview2",
+      "publisher",
+      "entitlements",
+      "dmg",
+    ],
+    desktopServer: ["omit", "profile", "modules", "env", "restart", "watchdog"],
     dmg: ["background", "background2x", "window", "iconSize", "textSize", "app", "applications"],
     deepLinks: ["schemes", "domains"],
   } as const;
@@ -586,7 +661,19 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       app.workspace.getPackageJson(),
     ]);
     const resolved = typeof configImp === "function" ? configImp(app) : configImp;
-    const { plugins, ...config } = (resolved ?? {}) as AppConfigDeclaration & { plugins?: AkanPlugin[] };
+    //* `pipeline` is read by `akan pipeline` alone, from the module itself: off the instance, it never reaches akan.app.json.
+    const {
+      plugins,
+      pipeline: _pipeline,
+      ...config
+    } = (resolved ?? {}) as AppConfigDeclaration & {
+      plugins?: AkanPlugin[];
+      pipeline?: unknown;
+    };
+    if ("subspace" in config)
+      throw new Error(
+        `apps/${app.name}/akan.config.ts declares \`subspace\`, a workspace setting: it belongs in the workspace root akan.config.ts.`,
+      );
     const libContributions = await AkanAppConfig.#collectLibContributions(app, libs, bustImportCache);
     return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libContributions);
   }
@@ -664,6 +751,9 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       .map((lib) => `${lib}@${this.#resolveProductionDependencyVersion(lib)}`);
   }
   get akanVersion() {
+    return AkanAppConfig.akanVersion;
+  }
+  static get akanVersion() {
     return getAkanPackageJson().version;
   }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
@@ -752,6 +842,14 @@ export class AkanLibConfig implements LibConfigResult {
     const configImp = await AkanAppConfig.importConfigModule(lib.cwdPath, { bustImportCache });
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as LibConfigDeclaration & { plugins?: AkanPlugin[] };
+    if ("pipeline" in config)
+      throw new Error(
+        `libs/${lib.name}/akan.config.ts declares \`pipeline\`, which a lib does not take: pipelines belong to apps and the workspace root, and a lib's build-time work goes in an akan build plugin.`,
+      );
+    if ("subspace" in config)
+      throw new Error(
+        `libs/${lib.name}/akan.config.ts declares \`subspace\`, a workspace setting: it belongs in the workspace root akan.config.ts.`,
+      );
     return new AkanLibConfig(lib, config, plugins ?? []);
   }
 }

package/akanConfig/akanWorkspaceConfig.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { GlobalConfig } from "../cloud/globalConfig";
+import { WorkspaceExecutor } from "../executors";
+import { AkanWorkspaceConfig } from "./akanWorkspaceConfig";
+
+const withWorkspace = async (files: Record<string, string>, run: (workspace: WorkspaceExecutor) => Promise<void>) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-workspace-config-"));
+  try {
+    for (const [relative, content] of Object.entries(files)) {
+      fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true });
+      fs.writeFileSync(path.join(root, relative), content);
+    }
+    await run(WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" }));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+};
+
+describe("AkanWorkspaceConfig", () => {
+  test("a workspace without a root akan.config.ts has an empty one", async () => {
+    await withWorkspace({}, async (workspace) => {
+      const config = await AkanWorkspaceConfig.from(workspace);
+      expect(config.file).toBeNull();
+      expect(config.subspace).toBeNull();
+      expect(config.pipeline).toBeNull();
+    });
+  });
+
+  test("reads subspace and pipeline, and the root file is never taken for an app", async () => {
+    await withWorkspace(
+      {
+        "akan.config.ts":
+          'export default { subspace: { subspaces: [{ name: "a", repo: "a.git", apps: ["web"] }] }, pipeline: { before: [] } };\n',
+        "apps/web/akan.config.ts": "export default {};\n",
+      },
+      async (workspace) => {
+        const config = await workspace.getConfig();
+        expect(config.file).toBe(path.join(workspace.workspaceRoot, "akan.config.ts"));
+        expect(config.subspace?.subspaces.map((subspace) => subspace.name)).toEqual(["a"]);
+        expect(config.pipeline).toEqual({ before: [] });
+        expect(await workspace.getApps()).toEqual(["web"]);
+      },
+    );
+  });
+
+  test("cloud.host names the cloud the CLI talks to without --host, https unless it is this computer", async () => {
+    const hostOf = (cloud: unknown) => new AkanWorkspaceConfig(null, { cloud }).cloudHost;
+    expect(hostOf(undefined)).toBeNull();
+    expect(hostOf({})).toBeNull();
+    expect(hostOf({ host: "https://cloud.example.com/" })).toBe("https://cloud.example.com");
+    expect(hostOf({ host: "https://example.com/akasys//" })).toBe("https://example.com/akasys");
+    expect(hostOf({ host: "http://localhost:8283" })).toBe("http://localhost:8283");
+    expect(() => hostOf({ host: "http://cloud.example.com" })).toThrow("https only");
+    expect(() => hostOf({ host: "cloud.example.com" })).toThrow("is not a URL");
+    expect(() => hostOf({ host: "https://cloud.example.com?x=1" })).toThrow("is not a URL");
+    expect(() => hostOf({ host: "https://cloud.example.com", token: "x" })).toThrow("keys it does not take: token");
+
+    const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
+    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), "https://given.example.com")).toBe(
+      "https://given.example.com",
+    );
+    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), null)).toBe(
+      "https://akasys.example.com",
+    );
+    expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
+  });
+
+  test("refuses app settings and a default export that is not an object", async () => {
+    await withWorkspace({ "akan.config.ts": 'export default { docker: { image: "x" } };\n' }, async (workspace) => {
+      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("declares `docker`, which it does not take");
+    });
+    await withWorkspace({ "akan.config.ts": "export default () => ({});\n" }, async (workspace) => {
+      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("must default-export a WorkspaceConfig object");
+    });
+  });
+});

package/akanConfig/akanWorkspaceConfig.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+import type { SubspaceConfigInput, WorkspaceConfig, WorkspacePipelineConfig } from "akanjs";
+import type { WorkspaceExecutor } from "../executors";
+import { FileSys } from "../fileSys";
+import { AkanAppConfig } from "./akanConfig";
+
+/** The workspace root's own `akan.config.ts`: settings that belong to no app. Absent, it is an empty one. */
+export class AkanWorkspaceConfig {
+  static readonly fileName = "akan.config.ts";
+  static readonly #keys = ["subspace", "pipeline", "cloud"];
+  static readonly #loopbackHosts = ["localhost", "127.0.0.1", "[::1]"];
+
+  static async from(workspace: WorkspaceExecutor, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
+    const file = path.join(workspace.workspaceRoot, AkanWorkspaceConfig.fileName);
+    if (!(await FileSys.fileExists(file))) return new AkanWorkspaceConfig(null, {});
+    const input = await AkanAppConfig.importConfigModule(workspace.workspaceRoot, { bustImportCache });
+    return new AkanWorkspaceConfig(file, input);
+  }
+
+  /** Absolute path, or null when the workspace has none. */
+  readonly file: string | null;
+  readonly subspace: SubspaceConfigInput | null;
+  readonly pipeline: WorkspacePipelineConfig | null;
+  /** `cloud.host` without a trailing slash, or null for Akan Cloud. */
+  readonly cloudHost: string | null;
+
+  constructor(file: string | null, input: unknown) {
+    this.file = file;
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+      throw new Error("The workspace root akan.config.ts must default-export a WorkspaceConfig object.");
+    for (const key of Object.keys(input))
+      if (!AkanWorkspaceConfig.#keys.includes(key))
+        throw new Error(
+          `The workspace root akan.config.ts declares \`${key}\`, which it does not take: it holds \`subspace\`, \`pipeline\` and \`cloud\`, and app or lib settings belong in apps/<app>/akan.config.ts or libs/<lib>/akan.config.ts.`,
+        );
+    const config = input as WorkspaceConfig;
+    this.subspace = config.subspace ?? null;
+    this.pipeline = config.pipeline ?? null;
+    this.cloudHost = AkanWorkspaceConfig.#cloudHost(config.cloud);
+  }
+
+  //? The CLI sends its cloud login token to this host, so plain http is refused anywhere but this computer.
+  static #cloudHost(cloud: unknown): string | null {
+    if (cloud === undefined) return null;
+    const refuse = (why: string): never => {
+      throw new Error(`The workspace root akan.config.ts has cloud ${why}.`);
+    };
+    if (typeof cloud !== "object" || cloud === null || Array.isArray(cloud)) return refuse("that is not an object");
+    const unknown = Object.keys(cloud).filter((key) => key !== "host");
+    if (unknown.length) return refuse(`keys it does not take: ${unknown.join(", ")} (only \`host\`)`);
+    const { host } = cloud as { host?: unknown };
+    if (host === undefined) return null;
+    const url = typeof host === "string" && URL.canParse(host) ? new URL(host) : null;
+    if (!url || url.search || url.hash || url.username || url.password)
+      return refuse(`.host ${JSON.stringify(host)}, which is not a URL like "https://cloud.example.com"`);
+    if (
+      url.protocol !== "https:" &&
+      !(url.protocol === "http:" && AkanWorkspaceConfig.#loopbackHosts.includes(url.hostname))
+    )
+      return refuse(`.host ${JSON.stringify(host)}: https only, or http on this computer`);
+    return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+  }
+}

package/akanConfig/index.ts

@@ -1,3 +1,4 @@
 export * from "./akanBin";
 export * from "./akanConfig";
+export * from "./akanWorkspaceConfig";
 export * from "./types";

package/akanConfig/types.ts

@@ -30,6 +30,10 @@ export type {
   AppConfig,
   AppConfigInput,
   AppConfigResult,
+  AppPipelineConfig,
+  AppPipelineContext,
+  AppPipelineInput,
+  AppPipelineStageInput,
   AppScanResult,
   Arch,
   BinPlatform,
@@ -48,8 +52,26 @@ export type {
   LibScanResult,
   NativeEnv,
   NativePermission,
+  PipelineActionStageInput,
+  PipelineContext,
+  PipelineDuration,
+  PipelineGlob,
+  PipelineMatrixStageInput,
+  PipelineParallelStageInput,
+  PipelinePostInput,
+  PipelineShellStageInput,
+  PipelineStageBase,
+  PipelineStepInput,
+  PipelineStepLike,
+  PipelineWhen,
   PkgScanResult,
   ScanResult,
+  SubspaceConfigInput,
+  SubspaceDeclaration,
+  WorkspaceConfig,
+  WorkspacePipelineConfig,
+  WorkspacePipelineInput,
+  WorkspacePipelineStageInput,
   WorkspaceScanResult,
 } from "akanjs";
-export { archs, binPlatforms } from "akanjs";
+export { archs, binPlatforms, defaultAppPipeline } from "akanjs";

package/akanContext.ts

@@ -282,7 +282,7 @@ const generatedFiles = [
 const validationCommands = [
   "akan sync <app-or-lib>",
   "akan lint <app-or-lib-or-pkg>",
-  "akan typecheck <app-name>",
+  "akan typecheck <app-or-lib>",
   "akan test <app-or-lib-or-pkg>",
   "akan build <app-name>",
   "akan doctor --strict --format json",

package/applicationBuildRunner.test.ts

@@ -10,7 +10,7 @@ import { Executor } from "./executors";
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
     expect(AKAN_OPTIONAL_BACKEND_EXTERNALS).toEqual(
-      expect.arrayContaining(["@libsql/client", "bullmq", "ioredis", "postgres", "protobufjs"]),
+      expect.arrayContaining(["bullmq", "ioredis", "postgres", "protobufjs"]),
     );
   });