@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.10

package/commandDecorators/commandDecorators.test.ts

@@ -1,7 +1,21 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { AppExecutor, WorkspaceExecutor } from "../executors";
-import { App, type ArgMeta, type ArgsOption, getArgMetas, Lib, Module, Pkg, Sys, Workspace } from "./argMeta";
-import { getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import path from "node:path";
+import { AppExecutor, LibExecutor, WorkspaceExecutor } from "../executors";
+import { makeCliTempWorkspace, tempRoots, writeText } from "../testHelpers";
+import {
+  App,
+  type ArgMeta,
+  type ArgsOption,
+  getArgMetas,
+  type InternalArgMeta,
+  Lib,
+  Module,
+  Pkg,
+  Sys,
+  SysOrOnlyApp,
+  Workspace,
+} from "./argMeta";
+import { getAppsArgumentValue, getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -289,6 +303,89 @@ describe("enum arg choices", () => {
   });
 });
 
+describe("prompts on a stdin that is not a terminal", () => {
+  const ownIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+  beforeEach(() => {
+    Object.defineProperty(process.stdin, "isTTY", { value: undefined, configurable: true });
+  });
+  afterEach(() => {
+    if (ownIsTTY) Object.defineProperty(process.stdin, "isTTY", ownIsTTY);
+    else Reflect.deleteProperty(process.stdin, "isTTY");
+  });
+  const metaOf = (type: "Argument" | "Option", name: string, argsOption: ArgsOption = {}): ArgMeta => ({
+    name,
+    argsOption: { type: "string", ...argsOption },
+    key: "run",
+    idx: 0,
+    type,
+  });
+  const context = { values: {} };
+  const workspaceWith = (appNames: string[]) => {
+    const workspace = new WorkspaceExecutor({ workspaceRoot: "/workspace", repoName: "repo" });
+    workspace.getExecs = async () => [appNames, ["util"], []];
+    workspace.getApps = async () => appNames;
+    return workspace;
+  };
+
+  test("a missing positional is refused by name instead of read from the pipe", async () => {
+    await expect(getArgumentValue(metaOf("Argument", "name", { desc: "secret name" }), undefined)).rejects.toThrow(
+      "Missing argument 'name': stdin is not a terminal to prompt on, so pass it on the command line.",
+    );
+    await expect(getArgumentValue(metaOf("Argument", "action", { enum: ["scan", "ssr"] }), undefined)).rejects.toThrow(
+      "Missing argument 'action': stdin is not a terminal to prompt on, so pass it on the command line (choices: scan, ssr).",
+    );
+  });
+
+  test("a missing option names its flag and the values it takes", async () => {
+    await expect(
+      getOptionValue(metaOf("Option", "platform", { enum: ["ios", "android"] }), {}, context),
+    ).rejects.toThrow(
+      "Missing option '--platform': stdin is not a terminal to prompt on, so pass it on the command line (choices: ios, android).",
+    );
+    await expect(
+      getOptionValue(
+        metaOf("Option", "format", { enum: [{ label: "JSON output", value: "json" }, "text"] }),
+        {},
+        context,
+      ),
+    ).rejects.toThrow("(choices: json, text)");
+    await expect(getOptionValue(metaOf("Option", "assembleType"), {}, context)).rejects.toThrow(
+      "Missing option '--assemble-type'",
+    );
+    await expect(getOptionValue(metaOf("Option", "force", { type: "boolean" }), {}, context)).rejects.toThrow(
+      "Missing option '--force'",
+    );
+  });
+
+  test("a value given, defaulted, nullable or the only choice still resolves without a prompt", async () => {
+    expect(await getArgumentValue(metaOf("Argument", "name"), "NPM_TOKEN")).toBe("NPM_TOKEN");
+    expect(await getOptionValue(metaOf("Option", "env", { default: "main" }), {}, context)).toBe("main");
+    expect(await getOptionValue(metaOf("Option", "host", { nullable: true }), {}, context)).toBe(null);
+    expect(await getOptionValue(metaOf("Option", "target", { enum: async () => ["default"] }), {}, context)).toBe(
+      "default",
+    );
+    const [app] = await getAppsArgumentValue(undefined, workspaceWith(["web"]));
+    expect(app?.name).toBe("web");
+  });
+
+  test("an app that is missing or unknown is refused with the workspace's apps", async () => {
+    const workspace = workspaceWith(["web", "admin"]);
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "App" }, undefined, workspace)).rejects.toThrow(
+      "Missing app: stdin is not a terminal to prompt on, so pass it on the command line (choices: web, admin).",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "App" }, "globex", workspace)).rejects.toThrow(
+      "Unknown app 'globex'",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "Sys" }, "globex", workspace)).rejects.toThrow(
+      "Unknown app or lib 'globex': stdin is not a terminal to prompt on, so pass it on the command line (choices: web, admin, util).",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "Module" }, undefined, workspace)).rejects.toThrow(
+      "Missing module",
+    );
+    await expect(getAppsArgumentValue(undefined, workspace)).rejects.toThrow("(choices: web, admin, all)");
+  });
+});
+
 describe("enum arg type inference", () => {
   afterEach(() => {
     CommandContainer.clear();
@@ -334,3 +431,107 @@ describe("enum arg type inference", () => {
     ]);
   });
 });
+
+describe("a Sys that defaults to the only app", () => {
+  const ownIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+  const asked: unknown[] = [];
+  let answer = "";
+  const setTTY = (isTTY: boolean | undefined) =>
+    Object.defineProperty(process.stdin, "isTTY", { value: isTTY, configurable: true });
+  beforeEach(() => {
+    asked.length = 0;
+    mock.module("@inquirer/prompts", () => ({
+      select: async ({ choices }: { choices: unknown[] }) => {
+        asked.push(choices);
+        return answer;
+      },
+    }));
+  });
+  afterEach(() => {
+    CommandContainer.clear();
+    if (ownIsTTY) Object.defineProperty(process.stdin, "isTTY", ownIsTTY);
+    else Reflect.deleteProperty(process.stdin, "isTTY");
+  });
+  const workspaceWith = (appNames: string[]) => {
+    const workspace = new WorkspaceExecutor({ workspaceRoot: "/workspace", repoName: "repo" });
+    workspace.getExecs = async () => [appNames, ["util"], []];
+    return workspace;
+  };
+  const sysMetaOf = (key: "typecheck" | "sync") => {
+    class OnlyAppCommand extends command("onlyApp", ({ public: target }) => ({
+      typecheck: target({ desc: "opted in" })
+        .with(SysOrOnlyApp)
+        .exec((sys) => sys),
+      sync: target({ desc: "plain" })
+        .with(Sys)
+        .exec((sys) => sys),
+    })) {}
+    const meta = getArgMetas(OnlyAppCommand, key)[0].find((arg): arg is InternalArgMeta => arg.type === "Sys");
+    if (!meta) throw new Error(`no Sys meta on ${key}`);
+    return meta;
+  };
+
+  test("the opted-in command takes a one-app workspace's app without asking, even on a piped stdin", async () => {
+    setTTY(undefined);
+    const meta = sysMetaOf("typecheck");
+    expect(meta.option).toEqual({ onlyApp: true });
+
+    const app = await getInternalArgumentValue(meta, undefined, workspaceWith(["web"]));
+    expect(app instanceof AppExecutor ? app.name : null).toBe("web");
+    expect(asked).toEqual([]);
+  });
+
+  test("a plain Sys command still asks app or library in a one-app workspace", async () => {
+    setTTY(true);
+    answer = "util";
+    const meta = sysMetaOf("sync");
+    expect(meta.option).toBeUndefined();
+
+    const lib = await getInternalArgumentValue(meta, undefined, workspaceWith(["web"]));
+    expect(lib instanceof LibExecutor ? lib.name : null).toBe("util");
+    expect(asked).toEqual([["web", "util"]]);
+  });
+
+  test("the opted-in command still asks when the workspace has two apps", async () => {
+    setTTY(true);
+    answer = "admin";
+    const app = await getInternalArgumentValue(sysMetaOf("typecheck"), undefined, workspaceWith(["web", "admin"]));
+    expect(app instanceof AppExecutor ? app.name : null).toBe("admin");
+    expect(asked).toEqual([["web", "admin", "util"]]);
+  });
+});
+
+describe("the exit code of a command that failed", () => {
+  const track = tempRoots();
+  const run = async (failure: string) => {
+    const { root } = track(await makeCliTempWorkspace());
+    await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
+    await writeText(path.join(root, "tsconfig.json"), "{}\n");
+    const entry = path.join(root, "cli.ts");
+    await writeText(
+      entry,
+      [
+        `import { command, ExitCodeError, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        'class VerdictRunner extends runner("verdict") {}',
+        'class VerdictScript extends script("verdict", [VerdictRunner]) {}',
+        'class VerdictCommand extends command("verdict", [VerdictScript], ({ public: target }) => ({',
+        '  verdict: target({ desc: "fails" }).exec(async function () {',
+        `    throw ${failure};`,
+        "  }),",
+        "})) {}",
+        "await runCommands(VerdictCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "verdict"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    return { stdout, code };
+  };
+
+  test("is the one an ExitCodeError carries, and 1 for any other error", async () => {
+    const verdict = await run('new ExitCodeError("needs a new store build", 2)');
+    expect(verdict.stdout).toContain("needs a new store build");
+    expect(verdict.code).toBe(2);
+    expect((await run('new Error("broke")')).code).toBe(1);
+  }, 30_000);
+});

package/commandDecorators/exitCodeError.ts

@@ -0,0 +1,15 @@
+//* A failure that is an answer, not a breakage: the CLI exits with its code, so a CI tells the two apart.
+export class ExitCodeError extends Error {
+  override readonly name = "ExitCodeError";
+
+  constructor(
+    message: string,
+    readonly exitCode: number,
+  ) {
+    super(message);
+  }
+
+  static codeOf(error: unknown): number | null {
+    return error instanceof ExitCodeError ? error.exitCode : null;
+  }
+}

package/commandDecorators/index.ts

@@ -2,5 +2,6 @@ export * from "./argMeta";
 export * from "./command";
 export * from "./commandBuilder";
 export * from "./dependencyBuilder";
+export * from "./exitCodeError";
 export * from "./helpFormatter";
 export * from "./targetMeta";

package/createTunnel.test.ts

@@ -48,4 +48,18 @@ describe("createTunnel", () => {
       expect(failure.message).toContain(reason.message);
     }
   });
+
+  test("refuses to dial a cluster host built on the local default serve domain", async () => {
+    const { app } = track(await createTempApp("demo"));
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const connect = spyOn(Client.prototype, "connect");
+    try {
+      await expect(createTunnel("redis", { app, environment: "debug" })).rejects.toThrow(
+        'The redis tunnel for the "debug" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(connect).not.toHaveBeenCalled();
+    } finally {
+      connect.mockRestore();
+    }
+  });
 });

package/createTunnel.ts

@@ -10,7 +10,9 @@ export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
-  const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
+  const baseDevEnv = WorkspaceExecutor.getBaseDevEnv();
+  WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, `The ${service} tunnel`);
+  const { serveDomain, repoName } = baseDevEnv;
   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`;

package/dependencyScanner.ts

@@ -107,7 +107,7 @@ export class TypeScriptDependencyScanner {
     return {
       npmDeps: [...runtimeDeps].sort(),
       npmDevDeps: [...devDeps].sort(),
-      missingDeps: missingDeps.sort(),
+      missingDeps: missingDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
     };
   }
 

package/devkitUtils.test.ts

@@ -76,7 +76,7 @@ describe("TypeScriptDependencyScanner", () => {
     });
     expect(deps.pkgDeps).toEqual(["akanjs/tool"]);
     expect(deps.libDeps).toEqual(["shared"]);
-    expect(deps.npmDeps.sort()).toEqual(["lodash", "react"]);
+    expect(deps.npmDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(["lodash", "react"]);
     expect(deps.npmDevDeps).toEqual(["typescript"]);
 
     const graph = scanner.generateDependencyGraph();

package/executors.test.ts

@@ -99,6 +99,29 @@ describe("Executor filesystem helpers", () => {
     expect(entries.dirs).toContain("nested");
   });
 
+  test("lists a folder in name order, whatever order the filesystem keeps it in", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    for (const name of ["summary", "file", "banner", "_noti", "admin"]) await exec.mkdir(`lib/${name}`);
+    for (const name of ["st.ts", "cnst.ts", "dict.ts"]) await exec.writeFile(`lib/${name}`, "");
+
+    expect(await exec.readdir("lib")).toEqual([
+      "_noti",
+      "admin",
+      "banner",
+      "cnst.ts",
+      "dict.ts",
+      "file",
+      "st.ts",
+      "summary",
+    ]);
+    expect(await exec.getFilesAndDirs("lib")).toEqual({
+      files: ["cnst.ts", "dict.ts", "st.ts"],
+      dirs: ["_noti", "admin", "banner", "file", "summary"],
+    });
+    expect(await exec.getAllFiles("**/*", { cwd: exec.getPath("lib") })).toEqual(["cnst.ts", "dict.ts", "st.ts"]);
+  });
+
   test("a refreshed tsconfig re-reads the config it extends", async () => {
     const root = await makeTempRoot();
     const appDir = path.join(root, "apps/demo");
@@ -188,6 +211,35 @@ describe("Executor filesystem helpers", () => {
     expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
   });
 
+  test("hands the formatter only the files a template wrote, never one overwrite: false kept", async () => {
+    const { root, app } = trackRoot(await createTempApp("demo"));
+    const formatted: string[] = [];
+    app.getLinter = () =>
+      ({
+        fixFiles: async (filePaths: string[]) => {
+          formatted.push(...filePaths);
+          return { fixed: [] };
+        },
+      }) as unknown as ReturnType<Executor["getLinter"]>;
+    const scalarDir = path.join(root, "apps/demo/lib/__scalar/money");
+    const own = "export class Money   {}\n";
+    await writeText(path.join(scalarDir, "money.constant.ts"), own);
+
+    const applied = await app.applyTemplate({
+      basePath: "./lib/__scalar",
+      template: "__scalar",
+      dict: { model: "money", models: "moneys", sysName: "demo" },
+      overwrite: false,
+    });
+
+    expect(applied.map((fileContent) => fileContent.filePath)).toContain(path.join(scalarDir, "money.constant.ts"));
+    expect(formatted.sort((a, b) => a.localeCompare(b))).toEqual([
+      path.join(scalarDir, "money.dictionary.ts"),
+      path.join(scalarDir, "money.document.ts"),
+    ]);
+    expect(await readFile(path.join(scalarDir, "money.constant.ts"), "utf8")).toBe(own);
+  });
+
   test("a formatter that cannot run does not fail the scaffold", async () => {
     // create-akan-workspace scaffolds before `bun install`, so Biome may be absent; a lint fix beats a failed scaffold.
     const root = await makeTempRoot();
@@ -263,10 +315,27 @@ describe("Executor filesystem helpers", () => {
       await readFile(path.join(templateRoot, "favicon.ico")),
     );
   });
+
+  test("keeps a static file already there when overwrite is false, and reports it unwritten", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    await writeText(path.join(root, "app/public/logo.png"), "the app's own logo");
+
+    const applied = await exec.applyTemplate({
+      basePath: "app/public",
+      template: "app/public/logo.png",
+      overwrite: false,
+    });
+
+    expect(await readFile(path.join(root, "app/public/logo.png"), "utf8")).toBe("the app's own logo");
+    expect(applied).toEqual([
+      expect.objectContaining({ filePath: path.join(root, "app/public/logo.png"), written: false }),
+    ]);
+  });
 });
 
 describe("Workspace and app executor environment contracts", () => {
-  test("reads base development environment and reports required missing values", () => {
+  test("reads base development environment", () => {
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
     process.env.AKAN_PUBLIC_ENV = "local";
@@ -282,10 +351,53 @@ describe("Workspace and app executor environment contracts", () => {
       env: "local",
       portOffset: 10,
       workspaceId: undefined,
+      defaulted: [],
     });
+  });
 
-    delete process.env.AKAN_PUBLIC_REPO_NAME;
-    expect(() => WorkspaceExecutor.getBaseDevEnv()).toThrow("AKAN_PUBLIC_REPO_NAME is not set");
+  test("unset, the repo name is the origin remote's and the serve domain localhost, both marked defaulted", async () => {
+    const root = await makeTempRoot();
+    for (const args of [
+      ["init", "-q"],
+      ["remote", "add", "origin", "git@github.com:akan-team/fixture-repo.git"],
+    ])
+      expect(Bun.spawnSync(["git", ...args], { cwd: root }).exitCode).toBe(0);
+    for (const key of ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN", "AKAN_PUBLIC_ENV", "AKAN_WORKSPACE_ROOT"])
+      delete process.env[key];
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"],
+    });
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "example.com",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME"],
+    });
+  });
+
+  test("a build or tunnel for a real environment refuses a defaulted value, and a local one takes it", () => {
+    const baseDevEnv = {
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug" as const,
+      portOffset: 0,
+      workspaceRoot: undefined,
+    };
+    const defaulted = { ...baseDevEnv, defaulted: ["AKAN_PUBLIC_SERVE_DOMAIN" as const] };
+
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "main", "akan build")).toThrow(
+      'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+    );
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "local", "akan build")).not.toThrow();
+    expect(() =>
+      WorkspaceExecutor.assertDeployableEnv({ ...baseDevEnv, defaulted: [] }, "main", "akan build"),
+    ).not.toThrow();
+    expect(() => WorkspaceExecutor.assertDeployableEnv(baseDevEnv, "main", "akan build")).not.toThrow();
   });
 
   test("reads base development environment from an explicit env file", async () => {
@@ -313,6 +425,7 @@ describe("Workspace and app executor environment contracts", () => {
       env: "develop",
       portOffset: 7,
       workspaceId: undefined,
+      defaulted: [],
     });
   });
 
@@ -371,6 +484,21 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("the app command env hands the dev server the local defaults that stood in for unset values", async () => {
+    const root = await makeTempRoot();
+    delete process.env.AKAN_PUBLIC_REPO_NAME;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    process.env.AKAN_WORKSPACE_ROOT = root;
+    const app = AppExecutor.from(new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }), "defaults");
+
+    const env = app.getCommandEnv();
+    expect(env.AKAN_PUBLIC_SERVE_DOMAIN).toBe("localhost");
+    expect(env.AKAN_PUBLIC_REPO_NAME).toBe(WorkspaceExecutor.getBaseDevEnv().repoName);
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(app.getCommandEnv().AKAN_PUBLIC_SERVE_DOMAIN).toBe("example.com");
+  });
+
   test("akan start clears the dev output and keeps the bin downloads and a native folder from before dist/native", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";