@akanjs/devkit 3.0.2 → 3.1.0-rc.1

package/transforms/serverEnvPlugin.test.ts

@@ -34,13 +34,22 @@ const writeApp = async (root: string) => {
   return { envDir, entry };
 };
 
-const build = async (root: string, environment: string) => {
+const build = async (root: string, environment: string, profile?: string) => {
   const { envDir, entry } = await writeApp(root);
+  if (profile)
+    await write(
+      path.join(envDir, `env.server.${environment}.${profile}.ts`),
+      [
+        'import { libEnv } from "./env.server.type";',
+        `export const env = { ...libEnv, origin: "${environment}-${profile}-origin" };`,
+        "",
+      ].join("\n"),
+    );
   const result = await Bun.build({
     entrypoints: [entry],
     outdir: path.join(root, "out"),
     target: "bun",
-    plugins: [createServerEnvPlugin({ envDir, environment, environments })],
+    plugins: [createServerEnvPlugin({ envDir, environment, environments, profile })],
   });
   expect(result.success).toBe(true);
   const output = result.outputs.find((artifact) => artifact.kind === "entry-point");
@@ -87,6 +96,88 @@ describe("createServerEnvPlugin", () => {
     expect(text).not.toContain("main-secret");
   });
 
+  test("a profile bundles its own file in place of the environment's, which never enters the bundle", async () => {
+    const { file, text } = await build(await makeTempRoot(), "main", "edge");
+    expect(text).toContain("main-edge-origin");
+    expect(text).not.toContain("main-secret");
+    const proc = run(file, "main");
+    expect(proc.exitCode).toBe(0);
+    expect(JSON.parse(proc.stdout.toString())).toEqual({ shared: "shared-value", origin: "main-edge-origin" });
+  });
+
+  test("a profile carries a lib's env defaults without their secrets, and still stubs the app's other environments", async () => {
+    const root = await makeTempRoot();
+    const libEnv = path.join(root, "libs/shared/env/env.server.testing.ts");
+    await write(
+      libEnv,
+      'export const env = { hostname: "lib-host", ttl: 30, security: { jwtSecret: "lib-jwt", accessTokenSeconds: 900 }, mailer: { auth: { user: "mailer-user", pass: "lib-pass" } }, cloudflare: { authKey: "lib-cf" } };\n',
+    );
+    const { envDir, entry } = await writeApp(root);
+    await write(path.join(envDir, "env.server.main.edge.ts"), 'export const env = { origin: "edge" };\n');
+    await write(
+      entry,
+      `import { env as app } from "./env/env.server";\nimport { env as lib } from ${JSON.stringify(libEnv)};\nconsole.info(JSON.stringify({ app, lib }));\n`,
+    );
+    const reports: unknown[] = [];
+    const result = await Bun.build({
+      entrypoints: [entry],
+      outdir: path.join(root, "out"),
+      target: "bun",
+      plugins: [
+        createServerEnvPlugin({
+          envDir,
+          environment: "main",
+          environments,
+          profile: "edge",
+          onLibEnv: (file, report) => reports.push({ file: path.basename(file), ...report }),
+        }),
+      ],
+    });
+    expect(result.success).toBe(true);
+    const output = result.outputs.find((artifact) => artifact.kind === "entry-point");
+    const text = (await output?.text()) ?? "";
+    for (const secret of ["lib-jwt", "lib-pass", "lib-cf", "develop-secret", "main-secret"])
+      expect(text).not.toContain(secret);
+    expect(reports).toEqual([
+      {
+        file: "env.server.testing.ts",
+        profileFile: false,
+        stripped: ["security.jwtSecret", "mailer.auth.pass", "cloudflare.authKey"],
+      },
+    ]);
+    const proc = run(output?.path ?? "", "main");
+    expect(JSON.parse(proc.stdout.toString()).lib).toEqual({
+      hostname: "lib-host",
+      ttl: 30,
+      security: { accessTokenSeconds: 900 },
+      mailer: { auth: { user: "mailer-user" } },
+      cloudflare: {},
+    });
+  });
+
+  test("a lib's own profile file is bundled in place of its defaults, and refused when it holds a secret", async () => {
+    const root = await makeTempRoot();
+    const libEnv = path.join(root, "libs/util/env/env.server.testing.ts");
+    await write(libEnv, 'export const env = { hostname: "lib-host", security: { jwtSecret: "lib-jwt" } };\n');
+    const edgeEnv = path.join(root, "libs/util/env/env.server.testing.edge.ts");
+    await write(edgeEnv, 'export const env = { hostname: "lib-edge-host" };\n');
+    const { envDir, entry } = await writeApp(root);
+    await write(path.join(envDir, "env.server.main.edge.ts"), "export const env = {};\n");
+    await write(entry, `import { env } from ${JSON.stringify(libEnv)};\nconsole.info(JSON.stringify(env));\n`);
+    const plugin = () => createServerEnvPlugin({ envDir, environment: "main", environments, profile: "edge" });
+    const ok = await Bun.build({ entrypoints: [entry], target: "bun", plugins: [plugin()] });
+    expect(ok.success).toBe(true);
+    const text = (await ok.outputs[0]?.text()) ?? "";
+    expect(text).toContain("lib-edge-host");
+    expect(text).not.toContain("lib-jwt");
+
+    await write(edgeEnv, 'export const env = { mailer: { pass: "edge-pass" } };\n');
+    const refused = await Bun.build({ entrypoints: [entry], target: "bun", plugins: [plugin()], throw: false });
+    expect(refused.success).toBe(false);
+    expect(refused.logs.map((log) => log.message).join("\n")).toContain("holds secret-named values");
+    expect(refused.logs.map((log) => log.message).join("\n")).toContain("mailer.pass");
+  });
+
   test("leaves env files outside the app's env directory alone", async () => {
     const root = await makeTempRoot();
     const other = path.join(root, "libs/shared/env/env.server.testing.ts");

package/transforms/serverEnvPlugin.ts

@@ -1,41 +1,94 @@
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
-import type { BunPlugin } from "bun";
+import type { BunPlugin, OnLoadResult } from "bun";
+import { ServerEnvProfile } from "./serverEnvProfile";
 
 export interface ServerEnvPluginOptions {
   envDir: string;
   /** The environment the image runs: its Dockerfile fixes `AKAN_PUBLIC_ENV` to it. */
   environment: string;
   environments: Iterable<string>;
+  /** Bundled in place of the environment's own file: `env.server.<environment>.<profile>.ts`, read from the same folder. */
+  profile?: string;
+  /** Under a profile, once per lib env file: whether the lib gave one of the profile's, and what was left out if not. */
+  onLibEnv?: (file: string, report: { profileFile: boolean; stripped: string[] }) => void;
 }
 
 const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 //* `env.server.ts` imports every environment's file, so an image would hand out the secrets of each environment it
 //* never runs. Every file but the image's own is swapped for exports that refuse to be read.
-export const createServerEnvPlugin = ({ envDir, environment, environments }: ServerEnvPluginOptions): BunPlugin => {
+export const createServerEnvPlugin = ({
+  envDir,
+  environment,
+  environments,
+  profile,
+  onLibEnv,
+}: ServerEnvPluginOptions): BunPlugin => {
   const others = [...new Set(environments)].filter((name) => name !== environment);
   //? Bun hands onLoad the real path, which differs from the given one under a symlink (macOS's /var -> /private/var).
   const dirs = new Set([path.resolve(envDir), existsSync(envDir) ? realpathSync.native(envDir) : envDir]);
-  const names = others.map(escapeRegExp).join("|");
-  const filter = new RegExp(`^(?:${[...dirs].map(escapeRegExp).join("|")})[\\\\/]env\\.server\\.(?:${names})\\.ts$`);
+  const folder = `^(?:${[...dirs].map(escapeRegExp).join("|")})[\\\\/]env\\.server\\.`;
+  const filter = new RegExp(`${folder}(?:${others.map(escapeRegExp).join("|")})\\.ts$`);
+  const own = new RegExp(`${folder}${escapeRegExp(environment)}\\.ts$`);
+  const libEnvs = new Map<string, Promise<OnLoadResult>>();
+  //* A lib's `server.ts` hands its `env.server.testing.ts` to the server as defaults, so a profile swaps those as it
+  //* swaps the app's: for the lib's `env.server.<name>.<profile>.ts`, else for the defaults without a secret in them.
+  const libEnv = async (file: string): Promise<OnLoadResult> => {
+    const profileFile = ServerEnvProfile.profileFileOf(file, profile ?? "");
+    const libRoot = path.dirname(path.dirname(file));
+    if (await Bun.file(profileFile).exists()) {
+      const secrets = ServerEnvProfile.secretPaths(await ServerEnvProfile.evaluate(profileFile, libRoot));
+      if (secrets.length)
+        throw new Error(
+          `${profileFile} holds secret-named values, which the "${profile}" bundle carries to every computer it runs on: ${secrets.join(", ")}.`,
+        );
+      onLibEnv?.(file, { profileFile: true, stripped: [] });
+      return { loader: "ts", contents: await Bun.file(profileFile).text() };
+    }
+    const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(file).text());
+    if (exports.some((name) => name !== "env"))
+      throw new Error(
+        `${file} exports ${exports.join(", ")}: a "${profile}" build carries only a lib env's \`env\`, so give the lib ${path.basename(profileFile)}.`,
+      );
+    const { value, stripped } = ServerEnvProfile.strip(await ServerEnvProfile.evaluate(file, libRoot));
+    onLibEnv?.(file, { profileFile: false, stripped });
+    return { loader: "js", contents: `export const env = ${JSON.stringify(value ?? {})};\n` };
+  };
   return {
     name: "akan-server-env",
     setup(build) {
-      if (!others.length) return;
-      build.onLoad({ filter }, async (args) => {
-        const name = path.basename(args.path, ".ts").slice("env.server.".length);
-        const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(args.path).text());
-        const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it: AKAN_PUBLIC_ENV=${name} in the workspace's .env, which outranks the shell, or --env ${name} on a desktop or mobile build.`;
-        return {
-          loader: "js",
-          contents: [
-            `const refuse = () => { throw new Error(${JSON.stringify(message)}); };`,
-            "const unbuilt = new Proxy({}, { get: refuse, has: refuse, ownKeys: refuse, getOwnPropertyDescriptor: refuse });",
-            `export { ${exports.map((exported) => `unbuilt as ${JSON.stringify(exported)}`).join(", ")} };`,
-          ].join("\n"),
-        };
-      });
+      //* The environment's own file never enters a profile's bundle: its contents are the profile file's.
+      if (profile)
+        build.onLoad({ filter: own }, async (args) => ({
+          loader: "ts",
+          contents: await Bun.file(
+            path.join(path.dirname(args.path), `env.server.${environment}.${profile}.ts`),
+          ).text(),
+        }));
+      if (others.length)
+        build.onLoad({ filter }, async (args) => {
+          const name = path.basename(args.path, ".ts").slice("env.server.".length);
+          const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(args.path).text());
+          const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it: AKAN_PUBLIC_ENV=${name} in the workspace's .env, which outranks the shell, or --env ${name} on a desktop or mobile build.`;
+          return {
+            loader: "js",
+            contents: [
+              `const refuse = () => { throw new Error(${JSON.stringify(message)}); };`,
+              "const unbuilt = new Proxy({}, { get: refuse, has: refuse, ownKeys: refuse, getOwnPropertyDescriptor: refuse });",
+              `export { ${exports.map((exported) => `unbuilt as ${JSON.stringify(exported)}`).join(", ")} };`,
+            ].join("\n"),
+          };
+        });
+      //? Last: the app's own env files above are taken by the handlers before it, which match them first.
+      if (profile)
+        build.onLoad({ filter: /[\\/]env[\\/]env\.server\.[A-Za-z0-9-]+\.ts$/ }, async (args) => {
+          const name = path.basename(args.path, ".ts").slice("env.server.".length);
+          if (dirs.has(path.dirname(args.path)) || name === "type" || name === "example")
+            return { loader: "ts", contents: await Bun.file(args.path).text() };
+          if (!libEnvs.has(args.path)) libEnvs.set(args.path, libEnv(args.path));
+          return (await libEnvs.get(args.path)) as OnLoadResult;
+        });
     },
   };
 };

package/transforms/serverEnvProfile.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { ServerEnvProfile } from "./serverEnvProfile";
+
+const makeTempRoot = tempDirs("akan-devkit-server-env-profile-");
+
+const writeProfile = async (body: string) => {
+  const envDir = path.join(await makeTempRoot(), "apps/demo/env");
+  await write(path.join(envDir, "env.server.main.edge.ts"), body);
+  return envDir;
+};
+
+describe("ServerEnvProfile.secretPaths", () => {
+  test("names every secret-named key holding a string, and every string beneath one", () => {
+    expect(
+      ServerEnvProfile.secretPaths({
+        hostname: "edge.example.com",
+        security: { jwtSecret: "s", sso: { google: { clientID: "id", clientSecret: "cs" } } },
+        llm: { model: "m", apiKey: "k" },
+        slack: { webhookUrl: "https://hooks" },
+        privateKey: { pem: "-----BEGIN" },
+        nvrAuth: { id: "admin", password: "" },
+        enrollKey: "fleet",
+        security2: { verifies: [["password", "phone"]] },
+        mailer: { auth: { user: "u", pass: "p" } },
+        cloudflare: { authEmail: "e", authKey: "k" },
+        iapVerify: { apple: "shared", google: { client_email: "c" } },
+      }),
+    ).toEqual([
+      "security.jwtSecret",
+      "security.sso.google.clientSecret",
+      "llm.apiKey",
+      "slack.webhookUrl",
+      "privateKey.pem",
+      "mailer.auth.pass",
+      "cloudflare.authKey",
+      "iapVerify.apple",
+      "iapVerify.google.client_email",
+    ]);
+  });
+});
+
+describe("ServerEnvProfile.assertShippable", () => {
+  test("passes a profile with no secret in it", async () => {
+    const envDir = await writeProfile('export const env = { hostname: "edge", cloudOrigin: "https://cloud" };\n');
+    await expect(ServerEnvProfile.assertShippable({ envDir, environment: "main", profile: "edge" })).resolves.toBe(
+      undefined,
+    );
+  });
+
+  test("refuses a literal fallback the bundle would carry, even when the build's shell sets the variable", async () => {
+    const envDir = await writeProfile(
+      'export const env = { security: { jwtSecret: process.env.EDGE_JWT_SECRET ?? "fallback" } };\n',
+    );
+    process.env.EDGE_JWT_SECRET = "from-the-shell";
+    try {
+      await expect(ServerEnvProfile.assertShippable({ envDir, environment: "main", profile: "edge" })).rejects.toThrow(
+        "env/env.server.main.edge.ts holds secret-named values, which a profile's bundle carries to every computer it runs on: security.jwtSecret.",
+      );
+    } finally {
+      delete process.env.EDGE_JWT_SECRET;
+    }
+  });
+
+  test("passes a secret read from the server's own process env with no fallback", async () => {
+    const envDir = await writeProfile("export const env = { security: { jwtSecret: process.env.EDGE_JWT_SECRET } };\n");
+    await expect(ServerEnvProfile.assertShippable({ envDir, environment: "main", profile: "edge" })).resolves.toBe(
+      undefined,
+    );
+  });
+
+  test("refuses a missing profile file and a malformed name", async () => {
+    const envDir = await writeProfile("export const env = {};\n");
+    await expect(ServerEnvProfile.assertShippable({ envDir, environment: "develop", profile: "edge" })).rejects.toThrow(
+      'The server env profile "edge" bundles env/env.server.develop.edge.ts in place of env/env.server.develop.ts, and there is no such file.',
+    );
+    await expect(ServerEnvProfile.assertShippable({ envDir, environment: "main", profile: "../x" })).rejects.toThrow(
+      "must be a lowercase-first name",
+    );
+  });
+});

package/transforms/serverEnvProfile.ts

@@ -0,0 +1,114 @@
+import path from "node:path";
+
+export interface ServerEnvProfileProps {
+  envDir: string;
+  environment: string;
+  profile: string;
+}
+
+//* The logger's redaction pattern plus what a config carries as a credential under another name: a webhook URL, a
+//* cloud access key, a mailer's `pass`, an HMAC key, a registry's `regcred`, and blocks that are credentials whole —
+//* `iapVerify` (its `apple` is the App Store shared secret) and a service account.
+const secretKey =
+  /password|passwd|passphrase|^pass$|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key|access[-_]?key|auth[-_]?key|hash[-_]?key|webhook|cred|iap[-_]?verify|service[-_]?account/i;
+
+//* A server env profile is bundled in place of the environment's own file, for a server that runs where its bundle
+//* can be read: the computers a desktop app is installed on. So it may hold no secret.
+export class ServerEnvProfile {
+  static readonly namePattern = /^[a-z][a-zA-Z0-9-]*$/;
+
+  static fileName(environment: string, profile: string) {
+    return `env.server.${environment}.${profile}.ts`;
+  }
+
+  /** `env.server.<name>.ts` → `env.server.<name>.<profile>.ts`, the file a profile build bundles in its place. */
+  static profileFileOf(file: string, profile: string) {
+    return file.replace(/\.ts$/, `.${profile}.ts`);
+  }
+
+  /** The value with every string `secretPaths` names left out, and those paths. */
+  static strip(value: unknown, at = "", underSecret = false): { value: unknown; stripped: string[] } {
+    if (typeof value === "string")
+      return underSecret && value.trim() ? { value: undefined, stripped: [at] } : { value, stripped: [] };
+    if (!value || typeof value !== "object") return { value, stripped: [] };
+    const stripped: string[] = [];
+    const strip = (key: string, child: unknown) => {
+      const result = ServerEnvProfile.strip(child, at ? `${at}.${key}` : key, underSecret || secretKey.test(key));
+      stripped.push(...result.stripped);
+      return result.value;
+    };
+    if (Array.isArray(value)) return { value: value.map((child, idx) => strip(String(idx), child)), stripped };
+    const kept = Object.fromEntries(
+      Object.entries(value)
+        .map(([key, child]) => [key, strip(key, child)] as const)
+        .filter(([, child]) => child !== undefined),
+    );
+    return { value: kept, stripped };
+  }
+
+  /**
+   * The values to look for in a bundle: each under a secret-named key, and each long one in a block that is a
+   * credential whole — not a URL or a lowercase constant there (`service_account`), which library code holds as well.
+   */
+  static secretValues(value: unknown, at = "", underSecret = false): { path: string; value: string }[] {
+    if (typeof value === "string") {
+      const named = secretKey.test(at.split(".").at(-1) ?? "");
+      const distinct = value.length >= 16 && !/^https?:\/\//.test(value) && !/^[a-z]+(?:[._-][a-z]+)*$/.test(value);
+      return underSecret && value.length >= 8 && (named || distinct) ? [{ path: at, value }] : [];
+    }
+    if (!value || typeof value !== "object") return [];
+    return Object.entries(value).flatMap(([key, child]) =>
+      ServerEnvProfile.secretValues(child, at ? `${at}.${key}` : key, underSecret || secretKey.test(key)),
+    );
+  }
+
+  /** Every secret-named key holding a non-empty string, or one beneath it, as a dotted path. */
+  static secretPaths(value: unknown, at = "", underSecret = false): string[] {
+    if (typeof value === "string") return underSecret && value.trim() ? [at] : [];
+    if (!value || typeof value !== "object") return [];
+    return Object.entries(value).flatMap(([key, child]) =>
+      ServerEnvProfile.secretPaths(child, at ? `${at}.${key}` : key, underSecret || secretKey.test(key)),
+    );
+  }
+
+  //* Evaluated in a child with no app env, so `process.env.X ?? "fallback"` reads as the fallback the bundle carries.
+  static async evaluate(file: string, cwd: string): Promise<unknown> {
+    const script = [
+      "const { env } = await import(process.env.AKAN_PROFILE_ENV_FILE);",
+      'const plain = (_, value) => (typeof value === "function" || typeof value === "symbol" ? undefined : typeof value === "bigint" ? String(value) : value);',
+      "process.stdout.write(JSON.stringify(env ?? null, plain));",
+    ].join("\n");
+    const child = Bun.spawn([process.execPath, "--eval", script], {
+      cwd,
+      env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AKAN_PROFILE_ENV_FILE: file },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    if (exitCode !== 0)
+      throw new Error(`${path.basename(file)} could not be evaluated to check it for secrets:\n${stderr.trim()}`);
+    return JSON.parse(stdout || "null") as unknown;
+  }
+
+  static async assertShippable({ envDir, environment, profile }: ServerEnvProfileProps) {
+    if (!ServerEnvProfile.namePattern.test(profile))
+      throw new Error(
+        `The server env profile "${profile}" must be a lowercase-first name of letters, digits and dashes.`,
+      );
+    const name = ServerEnvProfile.fileName(environment, profile);
+    const file = path.join(envDir, name);
+    if (!(await Bun.file(file).exists()))
+      throw new Error(
+        `The server env profile "${profile}" bundles env/${name} in place of env/env.server.${environment}.ts, and there is no such file.`,
+      );
+    const secrets = ServerEnvProfile.secretPaths(await ServerEnvProfile.evaluate(file, path.dirname(envDir)));
+    if (secrets.length)
+      throw new Error(
+        `env/${name} holds secret-named values, which a profile's bundle carries to every computer it runs on: ${secrets.join(", ")}. Leave them out, or read them from the process env of the server that needs them.`,
+      );
+  }
+}

package/typecheck/projectTypecheck.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { ProjectTypecheck } from "./projectTypecheck";
+
+const makeTempRoot = tempDirs("akan-devkit-project-typecheck-");
+
+const project = async () => {
+  const root = await makeTempRoot();
+  const dir = path.join(root, "libs/demo");
+  await write(
+    path.join(dir, "tsconfig.json"),
+    JSON.stringify({ compilerOptions: { strict: true, types: [], target: "esnext", module: "esnext", noEmit: true } }),
+  );
+  await write(path.join(dir, "server.ts"), "export const port: number = 8282;\n");
+  await write(path.join(dir, "lib/user/user.signal.test.ts"), 'export const port: number = "8282";\n');
+  await write(path.join(dir, ".akan/stale/old.test.ts"), 'export const port: number = "8282";\n');
+  return { root, dir };
+};
+
+describe("ProjectTypecheck", () => {
+  test("checks a test nothing imports only when asked, and leaves .akan out", async () => {
+    const { root, dir } = await project();
+    const typecheck = new ProjectTypecheck(dir, root, { ...process.env });
+
+    await typecheck.run(["../../server.ts"]);
+    const error = await typecheck.run(["../../server.ts"], { tests: true }).catch((e: Error) => e);
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("lib/user/user.signal.test.ts");
+    expect((error as Error).message).not.toContain("old.test.ts");
+  }, 60_000);
+});

package/typecheck/projectTypecheck.ts

@@ -0,0 +1,71 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+export interface ProjectTypecheckOptions {
+  clean?: boolean;
+  incremental?: boolean;
+  /** The project's own `*.test.ts` / `*.spec.ts` as well. */
+  tests?: boolean;
+}
+
+//* tsc checks what the entries import, and nothing imports a test, so a test is checked only when it is included by
+//* name. Each mode keeps a tsconfig and an incremental cache of its own, so one never invalidates the other.
+export class ProjectTypecheck {
+  static readonly #testIncludes = ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"];
+  static readonly #excludes = [".akan/**", "node_modules/**", "local/**"];
+
+  constructor(
+    readonly projectDir: string,
+    readonly workspaceRoot: string,
+    readonly env: Record<string, string | undefined>,
+  ) {}
+
+  get typecheckDir() {
+    return path.join(this.projectDir, ".akan", "typecheck");
+  }
+
+  /** `entries`: relative to the typecheck folder (`../../server.ts`). */
+  async run(entries: string[], { clean = false, incremental = true, tests = false }: ProjectTypecheckOptions = {}) {
+    const name = tests ? "tsconfig.tests" : "tsconfig";
+    await mkdir(this.typecheckDir, { recursive: true });
+    const tsconfig = {
+      extends: "../../tsconfig.json",
+      compilerOptions: { noEmit: true, incremental, tsBuildInfoFile: `./${name}.tsbuildinfo` },
+      include: [...entries, ...(tests ? ProjectTypecheck.#testIncludes.map((glob) => `../../${glob}`) : [])],
+      ...(tests ? { exclude: ProjectTypecheck.#excludes.map((glob) => `../../${glob}`) } : {}),
+      references: [],
+    };
+    const tsconfigPath = path.join(this.typecheckDir, `${name}.json`);
+    await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
+    if (clean) await rm(path.join(this.typecheckDir, `${name}.tsbuildinfo`), { force: true });
+    await this.#check(tsconfigPath);
+    return tsconfigPath;
+  }
+
+  async #check(tsconfigPath: string) {
+    const proc = Bun.spawn([process.execPath, await this.#workerEntry()], {
+      cwd: this.workspaceRoot,
+      env: { ...this.env, AKAN_COMMAND_TYPE: "typecheck", AKAN_TYPECHECK_TSCONFIG: tsconfigPath },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+  }
+
+  async #workerEntry() {
+    const candidates = [
+      path.join(this.workspaceRoot, "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(this.workspaceRoot, "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(import.meta.dir, "typecheck.proc.js"),
+      path.join(import.meta.dir, "typecheck.proc.ts"),
+      path.join(import.meta.dir, "..", "typecheck.proc.js"),
+    ];
+    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
+    throw new Error(`[cli] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
+}

package/workspaceLayout.test.ts

@@ -7,8 +7,10 @@ import {
   facetIndexShadowOf,
   isAllowedLibFacetRootFile,
   isScannedRootEntry,
+  libFacetRootHintOf,
   libRootAllowedDirs,
   libRootAllowedFiles,
+  moduleTestTargetOf,
   rootEntryHintOf,
 } from "./workspaceLayout";
 
@@ -104,17 +106,38 @@ describe("hand-written facet index", () => {
 });
 
 describe("lib facet root allowlist", () => {
-  test("admits the generated support facets and a root signal test", () => {
+  test("admits the generated support facets", () => {
     expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);
     expect(isAllowedLibFacetRootFile("option.ts")).toBe(true);
-    expect(isAllowedLibFacetRootFile("user.signal.test.ts")).toBe(true);
-    expect(isAllowedLibFacetRootFile("user.signal.spec.ts")).toBe(true);
   });
 
   test("rejects a hand-written file beside the barrels", () => {
     expect(isAllowedLibFacetRootFile("helper.ts")).toBe(false);
     expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
+
+  test("rejects a test at the lib root and points it at its module folder or srvkit", () => {
+    for (const filename of ["cloud.signal.test.ts", "user.signal.spec.ts", "release.test.tsx"]) {
+      expect(isAllowedLibFacetRootFile(filename)).toBe(false);
+      expect(libFacetRootHintOf(filename)).toContain("lib/<model>/<model>.signal.test.ts");
+      expect(libFacetRootHintOf(filename)).toContain("srvkit/");
+    }
+    expect(libFacetRootHintOf("helper.ts")).toBeNull();
+  });
+});
+
+describe("module test target", () => {
+  test("names the module file a test covers", () => {
+    expect(moduleTestTargetOf("chatMessage.signal.test.ts")).toBe("chatMessage.signal.ts");
+    expect(moduleTestTargetOf("chatMessage.signal.spec.ts")).toBe("chatMessage.signal.ts");
+    expect(moduleTestTargetOf("ChatMessage.Zone.test.tsx")).toBe("ChatMessage.Zone.tsx");
+    expect(moduleTestTargetOf("chatMessage.trim.signal.test.ts")).toBe("chatMessage.trim.signal.ts");
+  });
+
+  test("leaves a file that is not a test alone", () => {
+    expect(moduleTestTargetOf("chatMessage.signal.ts")).toBeNull();
+    expect(moduleTestTargetOf("chatMessage.testing.ts")).toBeNull();
+  });
 });
 
 const templatesDir = path.join(import.meta.dir, "..", "cli", "templates");

package/workspaceLayout.ts

@@ -78,11 +78,22 @@ export const libFacetRootAllowedFiles = new Set([
   "useServer.ts",
 ]);
 
-/** `<model>.signal.test.ts` — lib 파싯 루트에 놓이는 유일한 비생성 파일 (테스트가 배럴 전체를 부팅한다). */
-const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
+export const isAllowedLibFacetRootFile = (filename: string) => libFacetRootAllowedFiles.has(filename);
 
-export const isAllowedLibFacetRootFile = (filename: string) =>
-  libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
+const testSuffix = /\.(test|spec)(\.tsx?)$/;
+
+export const libFacetRootHintOf = (filename: string) =>
+  testSuffix.test(filename)
+    ? "a test beside the generated barrels; move it into the module folder it covers " +
+      "(lib/<model>/<model>.signal.test.ts), or into srvkit/ when it drives several modules"
+    : null;
+
+export const moduleTestTargetOf = (filename: string) =>
+  testSuffix.test(filename) ? filename.replace(testSuffix, "$2") : null;
+
+export const moduleTestHint =
+  "a module test is named after the one module file it covers (<model>.<role>.test.ts); add a describe block to " +
+  "that file's suite instead, or move a suite that drives several modules into srvkit/";
 
 export const barrelFacetDirs = ["ui", "webkit", "srvkit", "common", "plugin"] as const;