@akanjs/devkit 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @akanjs/devkit
 
+## 3.0.1
+
+### Minor Changes
+
+- 4871ae5: New lint rule `no-static-in-object-light-model` for `*.constant.ts`: a `static` on an `XObject` or `LightX` class is an error. The full model `via(XObject, LightX, …)` mixes in their prototypes only, so such a static never reaches `X`; declare it on `XInput` (or a scalar), `X`, or `XInsight` instead.
+
+### Patch Changes
+
+- Updated dependencies [4871ae5]
+- Updated dependencies [4871ae5]
+- Updated dependencies [4871ae5]
+  - akanjs@3.1.0
+
 ## 3.0.0
 
 ### Minor Changes
@@ -542,11 +555,11 @@
 
   **Lint config now extends a config shipped in the package.** `@akanjs/devkit/biome.base.json` carries the
   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`
+  `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
+  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

package/akanApp/akanApp.host.test.ts

@@ -19,6 +19,68 @@ describe("readProcessRssBytes", () => {
   });
 });
 
+describe("Redis tunnels during dev startup", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "testing" });
+  const track = tempRoots();
+
+  test.each(["single", "multiple", "cluster", undefined, "local"] as const)(
+    "%s mode preserves its Redis startup requirement",
+    async (mode) => {
+      const { root, app } = track(await createTempApp("demo"));
+      await writeText(
+        path.join(root, "apps/demo/main.ts"),
+        'process.send?.({ type: "backend-ready", pid: process.pid });\nsetInterval(() => undefined, 1_000);\n',
+      );
+      const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+      const port = listener.port;
+      listener.stop(true);
+      process.env.SSH_TUNNEL_PORT = String(port);
+      if (mode === "local") process.env.AKAN_PUBLIC_ENV = "local";
+      const create = IncrementalBuilderHost.create;
+      IncrementalBuilderHost.create = async () =>
+        ({
+          status: "ready",
+          patcherOff: false,
+          start: ({ onReady }: { onReady?: () => void }) => onReady?.(),
+          send: () => true,
+          stop: () => undefined,
+        }) as unknown as IncrementalBuilderHost;
+      const ready = Promise.withResolvers<void>();
+      const env = { ...process.env } as Record<string, string>;
+      delete env.AKAN_DATABASE_MODE;
+      if (mode !== undefined && mode !== "local") env.AKAN_DATABASE_MODE = mode;
+      const host = new AkanAppHost(app, {
+        env,
+        onDevEvent: (event) => {
+          if ("state" in event && event.state === "ready") ready.resolve();
+        },
+      });
+      let deadline: ReturnType<typeof setTimeout> | undefined;
+      try {
+        if (mode === "single" || mode === "local") {
+          await host.start();
+          await Promise.race([
+            ready.promise,
+            new Promise<never>((_, reject) => {
+              deadline = setTimeout(() => reject(new Error("backend-ready IPC timed out")), 5_000);
+            }),
+          ]);
+          expect(host.env.REDIS_HOST).toBe(mode === "local" ? "localhost" : "redis-tunnel-unavailable.invalid");
+          if (mode === "single") expect(host.env.REDIS_HOST).not.toBe("localhost");
+        } else {
+          await expect(host.start()).rejects.toThrow(
+            new RegExp(`redis.*demo-testing\\.localhost:${port}.*ECONNREFUSED`),
+          );
+        }
+      } finally {
+        clearTimeout(deadline);
+        await host.stop();
+        IncrementalBuilderHost.create = create;
+      }
+    },
+  );
+});
+
 describe("a gateway whose replica crash-loops", () => {
   isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
   const track = tempRoots();

package/akanApp/akanApp.host.ts

@@ -32,6 +32,7 @@ import {
   mergeBackendRestartReasons,
   mergeInvalidateMessages,
   normalizeBackendReportedGeneration,
+  redisTunnelPolicy,
   resolveIdleSuspendMs,
   type SourceFingerprints,
   shouldAbandonBackendRecovery,
@@ -46,6 +47,7 @@ import {
   shouldRestartBuilderByDevPlan,
   shouldRestartDevHostByDevPlan,
   shouldWarnBuilderRssCeilingTight,
+  UNAVAILABLE_REDIS_HOST,
 } from "./devHostPolicy";
 
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
@@ -203,8 +205,17 @@ export class AkanAppHost {
 
   async #prepareDatabase(type: "redis") {
     const environment = WorkspaceExecutor.getBaseDevEnv().env;
-    if (environment === "local") return "localhost";
-    return await createTunnel(type, { app: this.app, environment });
+    const policy = redisTunnelPolicy({ environment, databaseMode: this.env.AKAN_DATABASE_MODE });
+    if (policy === "none") return "localhost";
+    if (policy === "required") return await createTunnel(type, { app: this.app, environment });
+    try {
+      return await createTunnel(type, { app: this.app, environment });
+    } catch (error) {
+      this.logger.warn(
+        `${error instanceof Error ? error.message : String(error)} - continuing without Redis: the single database mode does not use it unless an app adaptor does`,
+      );
+      return UNAVAILABLE_REDIS_HOST;
+    }
   }
   #startBackend(startStatus: { generation?: number; files: string[] } | null = null) {
     if (this.#stopping) return;

package/akanApp/devHostPolicy.test.ts

@@ -16,6 +16,7 @@ import {
   mergeBackendRestartReasons,
   mergeInvalidateMessages,
   normalizeBackendReportedGeneration,
+  redisTunnelPolicy,
   resolveIdleSuspendMs,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
@@ -31,6 +32,19 @@ import {
   shouldWarnBuilderRssCeilingTight,
 } from "./devHostPolicy";
 
+describe("redisTunnelPolicy", () => {
+  test.each([
+    ["local", "single", "none"],
+    ["local", "multiple", "none"],
+    ["testing", "single", "optional"],
+    ["testing", "multiple", "required"],
+    ["testing", "cluster", "required"],
+    ["testing", undefined, "required"],
+  ] as const)("%s with %s Redis is %s", (environment, databaseMode, expected) => {
+    expect(redisTunnelPolicy({ environment, databaseMode })).toBe(expected);
+  });
+});
+
 const status = (phase: BuildPhase, generation: number, ok: boolean): DevBuildStatus => ({
   generation,
   phase,

package/akanApp/devHostPolicy.ts

@@ -9,6 +9,17 @@ import type {
 } from "akanjs/server";
 import type { IncrementalBuilderStatus } from "../incrementalBuilder";
 
+export const UNAVAILABLE_REDIS_HOST = "redis-tunnel-unavailable.invalid";
+
+export const redisTunnelPolicy = ({
+  environment,
+  databaseMode,
+}: {
+  environment: string;
+  databaseMode?: string;
+}): "none" | "optional" | "required" =>
+  environment === "local" ? "none" : databaseMode === "single" ? "optional" : "required";
+
 const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 
 // A page load asks for several routes, but a builder that never returns must not grow the hold queue unbounded.

package/akanConfig/akanConfig.test.ts

@@ -678,6 +678,9 @@ describe("AkanAppConfig", () => {
     expect(make({ native: { server: { url: "http://x" } } })).toThrow(
       "native.server in apps/portal/akan.config.ts is not a native setting",
     );
+    expect(make({ native: { desktop: { dmg: { backgroundImage: "bg.png" } } } })).toThrow(
+      "native.desktop.dmg.backgroundImage in apps/portal/akan.config.ts is not a native setting",
+    );
   });
 
   test("derives a repo-scoped default appId and records an explicit native section", () => {
@@ -693,7 +696,7 @@ describe("AkanAppConfig", () => {
 
 describe("deriveDefaultAppId", () => {
   test("sanitizes org/app names into a valid reverse-DNS bundle id", () => {
-    expect(deriveDefaultAppId("leading-flight-guidance", "myapp")).toBe("com.leadingflightguidance.myapp");
+    expect(deriveDefaultAppId("my-org", "myapp")).toBe("com.myorg.myapp");
     expect(deriveDefaultAppId("Acme Corp", "Store")).toBe("com.acmecorp.store");
     // Empty org and digit-leading segments stay valid package identifiers.
     expect(deriveDefaultAppId("", "app")).toBe("com.app.app");

package/akanConfig/akanConfig.ts

@@ -401,8 +401,9 @@ export class AkanAppConfig implements AppConfigResult {
       "activity",
       "files",
     ],
-    desktop: ["indexPath", "server", "recovery", "window", "screenCapture", "entitlements"],
+    desktop: ["indexPath", "server", "recovery", "window", "screenCapture", "entitlements", "dmg"],
     desktopServer: ["omit"],
+    dmg: ["background", "background2x", "window", "iconSize", "textSize", "app", "applications"],
     deepLinks: ["schemes", "domains"],
   } as const;
   //* Settings that moved when `mobile` became `native` are named with where they went, instead of "unknown".
@@ -440,6 +441,7 @@ export class AkanAppConfig implements AppConfigResult {
       `${where}.desktop.server`,
       "desktopServer",
     );
+    check(settings.desktop?.dmg, AkanAppConfig.#nativeKeys.dmg, `${where}.desktop.dmg`, "dmg");
     check(settings.deepLinks, AkanAppConfig.#nativeKeys.deepLinks, `${where}.deepLinks`, "deepLinks");
   }
   static readonly #androidFilePattern = /^(?:res\/[^/]+\/[^/]+|assets\/.+)$/;

package/akanContext.ts

@@ -16,7 +16,14 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
-import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles, rootEntryHintOf } from "./workspaceLayout";
+import {
+  barrelFacetDirs,
+  facetIndexShadowOf,
+  isScannedRootEntry,
+  rootAllowedDirs,
+  rootAllowedFiles,
+  rootEntryHintOf,
+} from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -676,6 +683,16 @@ export class AkanContextAnalyzer {
             ),
           );
       }
+      for (const facet of barrelFacetDirs)
+        for (const entry of await safeReadDir(path.join(sysPath, facet))) {
+          const shadow = entry.isDirectory() ? null : facetIndexShadowOf(`${facet}/${entry.name}`);
+          if (!shadow) continue;
+          const entryPath = `${sys.path}/${facet}/${entry.name}`;
+          report(
+            { severity: "error", code: "facet-index-shadowed", path: entryPath, message: `${entryPath} ${shadow}` },
+            repairAction("generated", `akan sync ${sys.name}`, `Delete ${entryPath} by hand, then sync.`, false),
+          );
+        }
     }
 
     const agentDrift = await AkanContextAnalyzer.#agentGuideDrift(workspace);

package/biome.base.json

@@ -186,7 +186,14 @@
     },
     {
       "includes": ["{apps,libs}/**/*.signal.ts"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit",
+        "./node_modules/@akanjs/devkit/lint/no-unguarded-endpoint.grit"
+      ]
+    },
+    {
+      "includes": ["{apps,libs}/**/*.dictionary.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-double-brace-placeholder.grit"]
     },
     {
       "includes": ["{apps,libs}/**/*.Util.tsx", "{apps,libs}/**/*.Zone.tsx"],

package/commandDecorators/command.ts

@@ -128,6 +128,8 @@ export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unkno
     assertEnumChoice(argMeta, opt[argMeta.name]);
     return convertArgValue(opt[argMeta.name] as string, type ?? "string");
   } else if (defaultValue !== undefined) return defaultValue;
+  //? Before the choices: a nullable option left out means something (`--arch`: this computer's), so it is not asked.
+  else if (nullable) return null;
 
   if (enumChoices) {
     const choices = normalizeEnumChoices(
@@ -135,8 +137,7 @@ export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unkno
     );
     if (choices.length === 1) return choices[0]?.value;
     return await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
-  } else if (nullable) return null;
-  else if (type === "boolean") {
+  } else if (type === "boolean") {
     const message = ask ?? desc ?? `Do you want to set ${name}? ${desc ? ` (${desc})` : ""}: `;
     return await confirm({ message });
   } else return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");

package/commandDecorators/commandDecorators.test.ts

@@ -277,6 +277,13 @@ describe("enum arg choices", () => {
     ).toBe("anything");
   });
 
+  test("a nullable option left out is null, not a prompt for one of its choices", async () => {
+    const arch = { ...optionMeta(["arm64", "x64"]), name: "arch" };
+    expect(await getOptionValue({ ...arch, argsOption: { ...arch.argsOption, nullable: true } }, {}, context)).toBe(
+      null,
+    );
+  });
+
   test("an option with no enum is unaffected", async () => {
     expect(await getOptionValue(optionMeta(undefined), { format: "whatever" }, context)).toBe("whatever");
   });

package/createTunnel.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { Client } from "ssh2";
+import { createTunnel } from "./createTunnel";
+import { createTempApp, isolateEnv, tempRoots } from "./testHelpers";
+
+describe("createTunnel", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "testing" });
+  const track = tempRoots();
+
+  test("describes a refused Redis SSH connection and preserves its cause", async () => {
+    const { app } = track(await createTempApp("demo"));
+    const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    const port = listener.port;
+    listener.stop(true);
+    process.env.SSH_TUNNEL_PORT = String(port);
+
+    let originalError: Error | undefined;
+    const connect = Client.prototype.connect;
+    const observeConnect = spyOn(Client.prototype, "connect").mockImplementation(function (this: Client, options) {
+      this.once("error", (error: Error) => {
+        originalError = error;
+      });
+      return connect.call(this, options);
+    });
+    let failure: unknown;
+    try {
+      await createTunnel("redis", { app, environment: "testing" });
+    } catch (error) {
+      failure = error;
+    } finally {
+      observeConnect.mockRestore();
+    }
+    expect(failure).toBeInstanceOf(Error);
+    if (!(failure instanceof Error)) throw new Error("expected tunnel failure");
+    expect(failure.message).toContain("redis");
+    expect(failure.message).toContain(`demo-testing.localhost:${port}`);
+    expect(failure.message).toContain("redis-0.redis-svc.demo-testing.svc.cluster.local:6379");
+    expect(failure.message).toContain("ECONNREFUSED");
+    expect(failure.cause).toBeInstanceOf(Error);
+    expect(failure.cause).toBe(originalError);
+    expect(failure.cause).not.toBe(failure);
+    if (!(failure.cause instanceof Error)) throw new Error("expected original SSH error");
+    const reasons = failure.cause instanceof AggregateError ? failure.cause.errors : [failure.cause];
+    expect(reasons.length).toBeGreaterThan(0);
+    for (const reason of reasons) {
+      expect(reason).toBeInstanceOf(Error);
+      expect(reason.message).toContain("ECONNREFUSED");
+      expect(failure.message).toContain(reason.message);
+    }
+  });
+});

package/createTunnel.ts

@@ -11,19 +11,37 @@ export const createTunnel = async (
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
   const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
-  await createSshTunnel({
-    localHost: "0.0.0.0",
-    localPort: port,
-    srcHost: "0.0.0.0",
-    srcPort: port,
-    dstHost: `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`,
-    dstPort: service === "postgres" ? 5432 : 6379,
-    sshOptions: {
-      host: `${app.name}-${environment}.${serveDomain}`,
-      port: process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767,
-      username: process.env.SSH_TUNNEL_USERNAME ?? "root",
-      password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
-    },
-  });
+  const host = `${app.name}-${environment}.${serveDomain}`;
+  const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
+  const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;
+  const dstPort = service === "postgres" ? 5432 : 6379;
+  try {
+    await createSshTunnel({
+      localHost: "0.0.0.0",
+      localPort: port,
+      srcHost: "0.0.0.0",
+      srcPort: port,
+      dstHost,
+      dstPort,
+      sshOptions: {
+        //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
+        host: host.endsWith(".localhost") ? "localhost" : host,
+        port: sshPort,
+        username: process.env.SSH_TUNNEL_USERNAME ?? "root",
+        password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
+      },
+    });
+  } catch (error) {
+    const reasons =
+      error instanceof AggregateError
+        ? error.errors.map((reason) => (reason instanceof Error ? reason.message : String(reason))).join("; ")
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    throw new Error(
+      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${reasons})`,
+      { cause: error },
+    );
+  }
   return `localhost:${port}`;
 };

package/csrE2e/csrPageStack.e2e.test.ts

@@ -209,13 +209,22 @@ describe.skipIf(!CsrE2eHarness.enabled)("CSR page stack (minimal, /e2e/stack)",
     expect(await csr.reloaded()).toBe(false);
   }, 60_000);
 
-  test("an async render that throws is logged with its route instead of leaving a blank page in silence", async () => {
+  test("an async render that throws is logged with its route and shows a retry instead of a blank page", async () => {
     await csr.open("/e2e/stack/broken");
-    await csr.waitFor(() => true);
-    await Bun.sleep(500);
+    await csr.waitFor(() => !!document.querySelector("[role=alert] button"), { timeout: 10_000 });
     expect(
       csr.consoleMessages().some((line) => /render of page \d+ of \S*\/e2e\/stack\/broken failed/.test(line)),
     ).toBe(true);
+    const failure = await csr.evaluate(() => {
+      const alert = document.querySelector("[role=alert]");
+      const button = alert?.querySelector("button");
+      return {
+        message: alert?.querySelector("p")?.textContent ?? "",
+        retry: button?.textContent ?? "",
+        painted: button ? getComputedStyle(button).backgroundColor !== "rgba(0, 0, 0, 0)" : false,
+      };
+    });
+    expect(failure).toEqual({ message: "This page could not be loaded.", retry: "Try again", painted: true });
   }, 60_000);
 
   test("the memory frame trace records navigation without writing it to the console", async () => {