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

package/commandDecorators/commandDecorators.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import path from "node:path";
-import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
+import { AppExecutor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
 import { makeCliTempWorkspace, tempRoots, writeText } from "../testHelpers";
 import {
   App,
@@ -440,6 +440,7 @@ describe("enum arg type inference", () => {
 
 describe("a Sys that defaults to the only app", () => {
   const ownIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+  const ownCwd = process.cwd();
   const asked: unknown[] = [];
   let answer = "";
   const setTTY = (isTTY: boolean | undefined) =>
@@ -455,6 +456,7 @@ describe("a Sys that defaults to the only app", () => {
   });
   afterEach(() => {
     CommandContainer.clear();
+    process.chdir(ownCwd);
     if (ownIsTTY) Object.defineProperty(process.stdin, "isTTY", ownIsTTY);
     else Reflect.deleteProperty(process.stdin, "isTTY");
   });
@@ -476,6 +478,21 @@ describe("a Sys that defaults to the only app", () => {
     if (!meta) throw new Error(`no Sys meta on ${key}`);
     return meta;
   };
+  const track = tempRoots();
+  //? From the workspace root, as the CLI runs: getDirInModule stats its entries relative to the process directory.
+  const moduleWorkspace = async () => {
+    const { root, workspace } = track(await makeCliTempWorkspace());
+    process.chdir(root);
+    for (const [sys, name] of [
+      ["apps/web", "card"],
+      ["libs/util", "photo"],
+    ] as const) {
+      await writeText(path.join(root, sys, "akan.config.ts"), "export default {};\n");
+      await writeText(path.join(root, sys, "lib", name, `${name}.constant.ts`), "export {};\n");
+    }
+    await writeText(path.join(root, "apps/web/lib/_billing/billing.service.ts"), "export {};\n");
+    return workspace;
+  };
 
   test("the opted-in command takes a one-app workspace's app without asking, even on a piped stdin", async () => {
     setTTY(undefined);
@@ -525,19 +542,24 @@ describe("a Sys that defaults to the only app", () => {
     expect(asked).toEqual([]);
   });
 
-  test("without a terminal, the only lib, pkg or module is not taken, as a command may be removing it", async () => {
+  test("without a terminal, a command that deletes nothing takes the only lib, pkg or module; a terminal is asked", async () => {
     setTTY(undefined);
     const workspace = workspaceWith([]);
     workspace.getExecs = async () => [[], ["util"], []];
     workspace.getPkgs = async () => ["tools"];
-    const rerunOf = (name: string) => rerunCommandOf([name], [undefined], 0);
-    await expect(
-      getInternalArgumentValue({ key: "", idx: 0, type: "Lib" }, undefined, workspace, rerunOf("remove-library")),
-    ).rejects.toThrow("so rerun it as `akan remove-library <lib>` (choices: util).");
-    await expect(
-      getInternalArgumentValue({ key: "", idx: 0, type: "Pkg" }, undefined, workspace, rerunOf("remove-package")),
-    ).rejects.toThrow("so rerun it as `akan remove-package <pkg>` (choices: tools).");
+    workspace.getDirInModule = async (basePath) => (basePath === "libs/util/lib" ? ["photo"] : []);
+    const lib = await getInternalArgumentValue({ key: "", idx: 0, type: "Lib" }, undefined, workspace);
+    expect(lib instanceof LibExecutor ? lib.name : null).toBe("util");
+    const pkg = await getInternalArgumentValue({ key: "", idx: 0, type: "Pkg" }, undefined, workspace);
+    expect(pkg instanceof PkgExecutor ? pkg.name : null).toBe("tools");
+    const mod = await getInternalArgumentValue({ key: "", idx: 0, type: "Module" }, undefined, workspace);
+    expect(mod instanceof ModuleExecutor ? `${mod.sys.name}:${mod.name}` : null).toBe("util:photo");
     expect(asked).toEqual([]);
+
+    setTTY(true);
+    answer = "util";
+    await getInternalArgumentValue({ key: "", idx: 0, type: "Lib" }, undefined, workspace);
+    expect(asked).toEqual([["util"]]);
   });
 
   test("without a terminal, a named target the workspace lacks is refused, not swapped for the only one", async () => {
@@ -551,6 +573,106 @@ describe("a Sys that defaults to the only app", () => {
     );
     expect(asked).toEqual([]);
   });
+
+  test("a destructive command never takes the only app, lib, pkg or module, nor asks, terminal or not", async () => {
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], ["util"], []];
+    workspace.getPkgs = async () => ["tools"];
+    workspace.getDirInModule = async (basePath) => (basePath === "apps/web/lib" ? ["pokemon"] : []);
+    const refusedAs = (rerun: string, choices: string) =>
+      `: this command deletes files and never picks its target, so rerun it as \`${rerun}\` (choices: ${choices}).`;
+    const resolve = (type: InternalArgMeta["type"], commandName: string, operands: (string | undefined)[]) =>
+      getInternalArgumentValue(
+        { key: "", idx: operands.length - 1, type },
+        operands.at(-1),
+        workspace,
+        rerunCommandOf(
+          [commandName, ...operands.filter((operand): operand is string => operand !== undefined)],
+          operands,
+          operands.length - 1,
+        ),
+        { destructive: true },
+      );
+    for (const isTTY of [true, undefined]) {
+      setTTY(isTTY);
+      answer = "web";
+      await expect(resolve("App", "remove-application", [undefined])).rejects.toThrow(
+        `Missing app${refusedAs("akan remove-application <app>", "web")}`,
+      );
+      await expect(resolve("Lib", "remove-library", [undefined])).rejects.toThrow(
+        `Missing lib${refusedAs("akan remove-library <lib>", "util")}`,
+      );
+      await expect(resolve("Pkg", "remove-package", [undefined])).rejects.toThrow(
+        `Missing pkg${refusedAs("akan remove-package <pkg>", "tools")}`,
+      );
+      await expect(resolve("Module", "remove-module", [undefined])).rejects.toThrow(
+        `Missing module${refusedAs("akan remove-module <sys:module>", "web:pokemon")}`,
+      );
+      await expect(resolve("Sys", "remove-scalar", ["place", undefined])).rejects.toThrow(
+        `Missing app or lib${refusedAs("akan remove-scalar place <app-or-lib>", "web, util")}`,
+      );
+      await expect(resolve("App", "remove-application", ["webb"])).rejects.toThrow(
+        `Unknown app 'webb'${refusedAs("akan remove-application <app>", "web")}`,
+      );
+    }
+    expect(asked).toEqual([]);
+  });
+
+  test("a destructive command takes the target it is named, while another still takes the only app", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    const named = await getInternalArgumentValue({ key: "", idx: 0, type: "App" }, "web", workspace, undefined, {
+      destructive: true,
+    });
+    expect(named instanceof AppExecutor ? named.name : null).toBe("web");
+    const taken = await getInternalArgumentValue(sysMetaOf("typecheck"), undefined, workspace);
+    expect(taken instanceof AppExecutor ? taken.name : null).toBe("web");
+    expect(asked).toEqual([]);
+  });
+
+  test("a module an app or a lib lacks is refused with the modules there are, in a terminal too", async () => {
+    setTTY(true);
+    answer = "util";
+    const workspace = await moduleWorkspace();
+    for (const value of ["util:nope", "web:nope"]) {
+      const sysName = value.split(":")[0];
+      await expect(
+        getInternalArgumentValue(
+          { key: "", idx: 0, type: "Module" },
+          value,
+          workspace,
+          rerunCommandOf(["create-view", value], [value], 0),
+        ),
+      ).rejects.toThrow(
+        `Unknown module '${value}': ${sysName} has no such module, so rerun it as \`akan create-view <sys:module>\` (choices: web:card, util:photo).`,
+      );
+    }
+    expect(asked).toEqual([]);
+    const photo = await getInternalArgumentValue({ key: "", idx: 0, type: "Module" }, "util:photo", workspace);
+    expect(photo instanceof ModuleExecutor ? `${photo.sys.name}:${photo.name}` : null).toBe("util:photo");
+  });
+
+  test("a service module is taken by its exact name where the target opts in, as remove-module does", async () => {
+    setTTY(true);
+    const workspace = await moduleWorkspace();
+    const services = { key: "", idx: 0, type: "Module", option: { services: true } } as const;
+    const billing = await getInternalArgumentValue(services, "web:_billing", workspace, undefined, {
+      destructive: true,
+    });
+    expect(billing instanceof ModuleExecutor ? `${billing.sys.name}:${billing.name}` : null).toBe("web:_billing");
+    await expect(
+      getInternalArgumentValue(services, undefined, workspace, rerunCommandOf(["remove-module"], [undefined], 0), {
+        destructive: true,
+      }),
+    ).rejects.toThrow(
+      "so rerun it as `akan remove-module <sys:module>` (choices: web:card, web:_billing, util:photo).",
+    );
+    await expect(
+      getInternalArgumentValue({ key: "", idx: 0, type: "Module" }, "web:_billing", workspace),
+    ).rejects.toThrow("Unknown module 'web:_billing': web has no such module");
+    expect(asked).toEqual([]);
+  });
 });
 
 describe("the line a refused target is rerun with", () => {
@@ -573,7 +695,7 @@ describe("the line a refused target is rerun with", () => {
 
 describe("a target left out where no terminal can ask for it", () => {
   const track = tempRoots();
-  const run = async (apps: string[]) => {
+  const run = async (apps: string[], args = ["create-thing", "photo", "--force"]) => {
     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");
@@ -582,7 +704,7 @@ describe("a target left out where no terminal can ask for it", () => {
     await writeText(
       entry,
       [
-        `import { command, runCommands, Sys } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        `import { App, command, runCommands, Sys } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
         'class ThingCommand extends command("thing", ({ public: target }) => ({',
         '  createThing: target({ desc: "creates a thing" })',
         '    .arg("thing", String, { desc: "name of the thing" })',
@@ -591,12 +713,17 @@ describe("a target left out where no terminal can ask for it", () => {
         "    .exec(async function (thing, sys, force) {",
         '      process.stdout.write(thing + " in " + sys.name + ", force " + force + "\\n");',
         "    }),",
+        '  removeThing: target({ desc: "removes an app", destructive: true })',
+        "    .with(App)",
+        "    .exec(async function (app) {",
+        '      process.stdout.write("removed " + app.name + "\\n");',
+        "    }),",
         "})) {}",
         "await runCommands(ThingCommand);",
         "",
       ].join("\n"),
     );
-    const proc = Bun.spawn(["bun", entry, "create-thing", "photo", "--force"], {
+    const proc = Bun.spawn(["bun", entry, ...args], {
       cwd: root,
       stdin: "ignore",
       stdout: "pipe",
@@ -621,18 +748,31 @@ describe("a target left out where no terminal can ask for it", () => {
 
   test("exits at once with the choices and the line to rerun when there are several", async () => {
     const refused = await run(["web", "admin"]);
-    expect(refused.code).toBe(1);
+    expect(refused.code).toBe(2);
     expect(refused.stdout).toContain(
       "Missing app or lib: stdin is not a terminal to prompt on, so rerun it as `akan create-thing photo <app-or-lib> --force`",
     );
     expect(refused.stdout).toMatch(/\(choices: (web, admin|admin, web)\)\./);
     expect(refused.stdout).not.toContain("photo in");
   }, 30_000);
+
+  test("a destructive command exits with the line to rerun even when the workspace has one app", async () => {
+    const refused = await run(["web"], ["remove-thing"]);
+    expect(refused.code).toBe(2);
+    expect(refused.stdout).toContain(
+      "Missing app: this command deletes files and never picks its target, so rerun it as `akan remove-thing <app>` (choices: web).",
+    );
+    expect(refused.stdout).not.toContain("removed");
+    expect((await run(["web"], ["remove-thing", "web"])).stdout).toContain("removed web\n");
+  }, 30_000);
 });
 
 describe("the exit code of a command that failed", () => {
   const track = tempRoots();
-  const run = async (failure: string, { option = "", args = [] as string[] } = {}) => {
+  const run = async (
+    failure: string,
+    { option = "", args = [], argv = ["verdict", ...args] }: { option?: string; args?: string[]; argv?: 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");
@@ -640,7 +780,8 @@ describe("the exit code of a command that failed", () => {
     await writeText(
       entry,
       [
-        `import { command, ExitCodeError, markCliErrorPrinted, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        `import { AkanError } from ${JSON.stringify(Bun.resolveSync("akanjs/base", import.meta.dir))};`,
+        `import { CliError, command, ExitCodeError, markCliErrorPrinted, 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 }) => ({',
@@ -652,7 +793,7 @@ describe("the exit code of a command that failed", () => {
         "",
       ].join("\n"),
     );
-    const proc = Bun.spawn(["bun", entry, "verdict", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const proc = Bun.spawn(["bun", entry, ...argv], { cwd: root, stdout: "pipe", stderr: "pipe" });
     const [stdout, stderr, code] = await Promise.all([
       new Response(proc.stdout).text(),
       new Response(proc.stderr).text(),
@@ -668,6 +809,28 @@ describe("the exit code of a command that failed", () => {
     expect((await run('new Error("broke")')).code).toBe(1);
   }, 30_000);
 
+  test("is the table's for a CliError's code, and 1 for an AkanError of any other code", async () => {
+    const [checked, unknown, gone] = await Promise.all([
+      run('new CliError("checkFailed", "found problems")'),
+      run('new CliError("unknownTarget", "no app shop")'),
+      run('new AkanError("documentNotFound", "gone")'),
+    ]);
+    expect([checked.code, unknown.code, gone.code]).toEqual([3, 2, 1]);
+    expect(checked.stdout).toContain("found problems");
+  }, 30_000);
+
+  test("is 2 for a flag commander refuses, a value outside the choices and an unknown command", async () => {
+    const choice = ' }).option("mode", String, { enum: ["a", "b"]';
+    const [flag, outside, unknownCommand] = await Promise.all([
+      run('new Error("broke")', { args: ["--nope"] }),
+      run('new Error("broke")', { option: choice, args: ["--mode", "c"] }),
+      run('new Error("broke")', { argv: ["verdikt"] }),
+    ]);
+    expect([flag.code, outside.code, unknownCommand.code]).toEqual([2, 2, 2]);
+    expect(outside.stdout).toContain("option '--mode' argument 'c' is invalid");
+    expect(unknownCommand.stderr).toContain("unknown command 'verdikt'");
+  }, 30_000);
+
   test("is usageExitCode for a flag commander refuses before the command runs, failureExitCode after", async () => {
     const option = ", failureExitCode: 4, usageExitCode: 2";
     expect((await run('new Error("broke")', { option, args: ["--nope"] })).code).toBe(2);
@@ -695,7 +858,7 @@ describe("the exit code of a command that failed", () => {
 
     const thrown = await run('new Error("broke")', { option, args: ["--json"] });
     expect(thrown.code).toBe(1);
-    expect(thrown.stdout).toContain("broke\n");
+    expect(thrown.stderr).toContain("broke\n");
     expect(lastOf(thrown.stdout)).toEqual({ message: "broke", usage: false, given: { json: true } });
 
     const help = await run('new Error("broke")', { option, args: ["--help"] });
@@ -703,6 +866,66 @@ describe("the exit code of a command that failed", () => {
     expect(help.stdout).not.toContain('"usage"');
   }, 60_000);
 
+  test("with JSON asked for, ends stdout with ok, error and code, and prints the message to stderr", async () => {
+    const json = ' }).option("json", Boolean, { default: false';
+    const format = ' }).option("format", String, { default: "text", enum: ["text", "json"]';
+    const marked =
+      '(() => { const error = new CliError("checkFailed", "verify failed"); markCliErrorPrinted(error); return error; })()';
+    const [unknown, plain, refused, answered, text] = await Promise.all([
+      run('new CliError("unknownTarget", "no app shop")', { option: json, args: ["--json"] }),
+      run('new Error("broke")', { option: format, args: ["--format", "json"] }),
+      run('new Error("broke")', { option: json, args: ["--json", "--nope"] }),
+      run(marked, { option: format, args: ["--format", "json"] }),
+      run('new Error("broke")', { option: format }),
+    ]);
+    expect(unknown.code).toBe(2);
+    expect(JSON.parse(unknown.stdout)).toEqual({ ok: false, error: "no app shop", code: "unknownTarget" });
+    expect(unknown.stderr).toContain("no app shop");
+    expect(plain.code).toBe(1);
+    expect(JSON.parse(plain.stdout)).toEqual({ ok: false, error: "broke", code: "failed" });
+    expect(refused.code).toBe(2);
+    expect(JSON.parse(refused.stdout)).toEqual({ ok: false, error: "unknown option '--nope'", code: "usage" });
+    expect(answered.code).toBe(3);
+    expect(answered.stdout.trim()).toBe("");
+    expect(text.stdout).toContain("broke\n");
+    expect(text.stdout).not.toContain('"code"');
+  }, 60_000);
+
+  test("is usageExitCode for a usage or unknown-target failure where 2 answers something else", async () => {
+    const option = ", usageExitCode: 1";
+    const [flag, unknown, verdict] = await Promise.all([
+      run('new Error("broke")', { option, args: ["--nope"] }),
+      run('new CliError("unknownTarget", "Unknown app \'shop\'")', { option }),
+      run('new ExitCodeError("needs a new store build", 2)', { option }),
+    ]);
+    expect([flag.code, unknown.code, verdict.code]).toEqual([1, 1, 2]);
+  }, 30_000);
+
+  test("is 130 for a prompt closed with Ctrl+C", async () => {
+    const closed = await run(
+      'Object.assign(new Error("User force closed the prompt with SIGINT"), { name: "ExitPromptError" })',
+    );
+    expect(closed.code).toBe(130);
+  }, 30_000);
+
+  test("answers JSON for an ExitCodeError, a thrown object and an unhandled rejection", async () => {
+    const json = ' }).option("json", Boolean, { default: false';
+    const late = 'await (void Promise.reject(new CliError("refused", "late")), new Promise(() => {}))';
+    const [verdict, checked, thrown, rejected] = await Promise.all([
+      run('new ExitCodeError("needs a new store build", 2)', { option: json, args: ["--json"] }),
+      run('new ExitCodeError("found problems", 3)', { option: json, args: ["--json"] }),
+      run('{ reason: "an object" }', { option: json, args: ["--json"] }),
+      run(late, { option: json, args: ["--json"] }),
+    ]);
+    expect(JSON.parse(verdict.stdout)).toEqual({ ok: false, error: "needs a new store build", code: "refused" });
+    expect(verdict.code).toBe(2);
+    expect(JSON.parse(checked.stdout)).toEqual({ ok: false, error: "found problems", code: "checkFailed" });
+    expect(checked.code).toBe(3);
+    expect(JSON.parse(thrown.stdout)).toEqual({ ok: false, error: '{"reason":"an object"}', code: "failed" });
+    expect(JSON.parse(rejected.stdout)).toEqual({ ok: false, error: "late", code: "refused" });
+    expect(rejected.code).toBe(2);
+  }, 60_000);
+
   test("prints nothing more for an error the command marked as printed", async () => {
     const marked = await run(
       '(() => { const error = new Error("printed already"); markCliErrorPrinted(error); return error; })()',

package/commandDecorators/exitCodeError.ts

@@ -1,15 +1,14 @@
+import { CliError } from "./cliError";
+
 //* 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 {
+export class ExitCodeError extends CliError {
   override readonly name = "ExitCodeError";
 
-  constructor(
-    message: string,
-    readonly exitCode: number,
-  ) {
-    super(message);
+  constructor(message: string, exitCode: number) {
+    super(exitCode === 2 ? "refused" : exitCode === 3 ? "checkFailed" : "failed", message, { exitCode });
   }
 
   static codeOf(error: unknown): number | null {
-    return error instanceof ExitCodeError ? error.exitCode : null;
+    return CliError.exitCodeOf(error);
   }
 }

package/commandDecorators/index.ts

@@ -1,4 +1,5 @@
 export * from "./argMeta";
+export * from "./cliError";
 export * from "./command";
 export * from "./commandBuilder";
 export * from "./dependencyBuilder";

package/commandDecorators/targetMeta.ts

@@ -44,7 +44,10 @@ export interface TargetOption {
   runsOnWorkspaceRoot?: boolean;
   stdio?: boolean;
   failureExitCode?: number;
+  /** The exit of a `usage` or `unknownTarget` failure, for a command whose 2 already answers something else. */
   usageExitCode?: number;
+  /** It deletes files in its app, lib, pkg or module, so one left out or unknown is refused, never picked or asked. */
+  destructive?: boolean;
   /** Runs after the CLI printed a failure and before it exits, so what it writes ends the output. */
   onFailure?: (error: unknown, failure: TargetFailure) => void | Promise<void>;
 }

package/conventionSet.test.ts

@@ -3,6 +3,7 @@ import fsPromise from "node:fs/promises";
 import path from "node:path";
 import { ConventionSet } from "./conventionSet";
 import { MaintainabilityContract } from "./maintainabilityContract";
+import { MaintainabilityLimits } from "./maintainabilityLimits";
 import { Prompter } from "./prompter";
 
 describe("ConventionSet", () => {
@@ -49,7 +50,7 @@ describe("ConventionSet", () => {
     }
   });
 
-  test("names only checks that exist, and names every lint plugin and maintainability gate somewhere", async () => {
+  test("names only checks that exist, and names every lint plugin and maintainability gate a workspace runs", async () => {
     const set = await Prompter.getConventionSet();
     const named = new Set(
       [set.core, ...set.rules.map((rule) => rule.body)].flatMap((text) =>
@@ -59,7 +60,9 @@ describe("ConventionSet", () => {
     const plugins = (await fsPromise.readdir(path.join(import.meta.dir, "lint")))
       .filter((file) => file.endsWith(".grit"))
       .map((file) => file.slice(0, -".grit".length));
-    const gates: readonly string[] = MaintainabilityContract.ruleIds;
+    const gates: readonly string[] = MaintainabilityContract.ruleIds.filter(
+      (id) => !MaintainabilityLimits.repoOnlyRules.has(id),
+    );
     const gateAreas = new Set(gates.map((id) => id.split(".").slice(0, 2).join(".")));
     const isPluginName = (name: string) => /^non?-[a-z]+(-[a-z]+)+$/.test(name);
     const isGateName = (name: string) =>

package/csrE2e/csrE2eHarness.fixture.ts

@@ -43,7 +43,7 @@ interface CsrE2eServer {
 
 const DEFAULT_PORT = 8391;
 const RELOAD_MARKER = "__akanE2eBootMarker";
-//? Longer than the frame's navigation lock (360ms after a transition commits, `webkit/useCsrValues.ts`).
+//? Longer than the frame's navigation lock (360ms after a transition commits, `webkit/useCsrNavigation.ts`).
 const SETTLE_MS = 450;
 
 /** Drives a page of a running `akan start` in a headless `Bun.WebView`: CSR (`?csr=true` + a mobile target) or SSR. */