@akanjs/devkit 3.0.2-rc.0 → 3.0.2

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

@@ -696,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.2-rc.0",
+  "version": "3.0.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.2-rc.0",
+    "akanjs": "3.0.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/workspaceLayout.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
 import {
   appRootAllowedDirs,
   appRootAllowedFiles,
@@ -114,3 +116,55 @@ describe("lib facet root allowlist", () => {
     expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
 });
+
+const templatesDir = path.join(import.meta.dir, "..", "cli", "templates");
+
+type TsConfig = { references?: { path: string }[] };
+
+const loadRootTemplate = async (dir: string): Promise<TsConfig> =>
+  JSON.parse(await Bun.file(path.join(templatesDir, dir, "tsconfig.json.template")).text());
+
+const templateDirsWithRootTsconfig = async (): Promise<string[]> => {
+  const entries = await readdir(templatesDir, { withFileTypes: true });
+  const dirs: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (await Bun.file(path.join(templatesDir, entry.name, "tsconfig.json.template")).exists()) dirs.push(entry.name);
+  }
+  return dirs.sort((a, b) => a.localeCompare(b));
+};
+
+describe("cli root tsconfig templates vs workspace scan allowlists", () => {
+  test("only the app and libRoot root templates may declare references", async () => {
+    const dirs = await templateDirsWithRootTsconfig();
+    for (const dir of ["app", "libRoot", "pkgRoot", "workspaceRoot"]) expect(dirs).toContain(dir);
+    for (const dir of dirs) {
+      const tsconfig = await loadRootTemplate(dir);
+      if (!tsconfig.references) continue;
+      expect(["app", "libRoot"], `${dir} template declares references`).toContain(dir);
+    }
+  });
+
+  test("app template references stay inside appRootAllowedFiles", async () => {
+    const tsconfig = await loadRootTemplate("app");
+    for (const reference of tsconfig.references ?? []) {
+      const filename = path.basename(reference.path);
+      expect(appRootAllowedFiles.has(filename), `app template references "${reference.path}"`).toBe(true);
+    }
+  });
+
+  test("libRoot template references stay inside libRootAllowedFiles", async () => {
+    const tsconfig = await loadRootTemplate("libRoot");
+    for (const reference of tsconfig.references ?? []) {
+      const filename = path.basename(reference.path);
+      expect(libRootAllowedFiles.has(filename), `libRoot template references "${reference.path}"`).toBe(true);
+    }
+  });
+
+  test("pkgRoot and workspaceRoot templates declare no references", async () => {
+    for (const dir of ["pkgRoot", "workspaceRoot"]) {
+      const tsconfig = await loadRootTemplate(dir);
+      expect(tsconfig.references, `${dir} template must not declare references`).toBeUndefined();
+    }
+  });
+});