@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/commandDecorators/command.ts

@@ -229,6 +229,28 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   );
 };
 
+export type RerunOf = (target: string) => string;
+
+const shellWordOf = (word: string) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
+
+//? Commander fills operands left to right, so every operand before an empty slot was given.
+export const rerunCommandOf =
+  (argv: readonly string[], operands: readonly unknown[], slot: number): RerunOf =>
+  (target) => {
+    const [commandName = "", ...words] = argv;
+    let at = 0;
+    for (const operand of operands.slice(0, slot)) if (typeof operand === "string") at = words.indexOf(operand, at) + 1;
+    const given = operands[slot];
+    const givenAt = typeof given === "string" ? words.indexOf(given, at) : -1;
+    const rerun = words.map(shellWordOf);
+    if (givenAt >= 0) rerun.splice(givenAt, 1, target);
+    else rerun.splice(at, 0, target);
+    return ["akan", commandName, ...rerun].join(" ");
+  };
+
+const rerunRemedyOf = (rerun: RerunOf | undefined, placeholder: string) =>
+  rerun ? { remedy: `rerun it as \`${rerun(placeholder)}\`` } : {};
+
 const parseAppNameList = (value: string | string[] | undefined): string[] =>
   (Array.isArray(value) ? value : value === undefined ? [] : [value])
     .flatMap((entry) => entry.split(","))
@@ -239,6 +261,7 @@ const parseAppNameList = (value: string | string[] | undefined): string[] =>
 export const getAppsArgumentValue = async (
   value: string | string[] | undefined,
   workspace: WorkspaceExecutor,
+  rerun?: RerunOf,
 ): Promise<AppExecutor[]> => {
   const appNames = await workspace.getApps();
   if (appNames.length === 0) throw new Error("No apps found in this workspace (apps/<appName>/akan.config.ts)");
@@ -253,7 +276,7 @@ export const getAppsArgumentValue = async (
     return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
   }
   if (appNames.length === 1 && appNames[0]) return [AppExecutor.from(workspace, appNames[0])];
-  assertPromptable("Missing apps", { choices: [...appNames, "all"] });
+  assertPromptable("Missing apps", { choices: [...appNames, "all"], ...rerunRemedyOf(rerun, "<apps...>") });
   const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
   const picked = await checkbox<string>({
     message: "Select the apps to run (space to toggle, enter to confirm)",
@@ -269,6 +292,7 @@ export const getInternalArgumentValue = async (
   argMeta: InternalArgMeta,
   value: string | undefined,
   workspace: WorkspaceExecutor,
+  rerun?: RerunOf,
 ) => {
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
@@ -286,12 +310,24 @@ export const getInternalArgumentValue = async (
     if (found) return found;
     if (!value && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
       return AppExecutor.from(workspace, appNames[0]);
-    assertPromptable(problemOf(sysType === "exec" ? "app, lib or pkg" : "app or lib"), {
-      choices: [...appNames, ...libNames, ...pkgChoices],
-    });
+    const [kind, placeholder] =
+      sysType === "exec" ? ["app, lib or pkg", "<app-lib-or-pkg>"] : ["app or lib", "<app-or-lib>"];
+    const choices = [...appNames, ...libNames, ...pkgChoices];
+    const only = choices.length === 1 ? execOf(choices[0] ?? "") : null;
+    //? Not for Lib, Pkg or Module, which name what a command acts on: `akan remove-library` would delete the only one.
+    if (!value && only && !process.stdin.isTTY) {
+      const how = rerun ? `: ${rerun(only.name)}` : "";
+      Logger.rawLog(
+        `No ${kind} named, so this runs on '${only.name}', the only one in this workspace${how}`,
+        undefined,
+        "error",
+      );
+      return only;
+    }
+    assertPromptable(problemOf(kind), { choices, ...rerunRemedyOf(rerun, placeholder) });
     const name = await select<string>({
       message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
-      choices: [...appNames, ...libNames, ...pkgChoices],
+      choices,
     });
     const picked = execOf(name);
     if (!picked) throw new Error(`Invalid system name: ${name}`);
@@ -299,18 +335,18 @@ export const getInternalArgumentValue = async (
   } else if (sysType === "app") {
     if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
     if (!value && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
-    assertPromptable(problemOf("app"), { choices: appNames });
+    assertPromptable(problemOf("app"), { choices: appNames, ...rerunRemedyOf(rerun, "<app>") });
     const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
     return AppExecutor.from(workspace, appName);
   } else if (sysType === "lib") {
     if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
-    assertPromptable(problemOf("lib"), { choices: libNames });
+    assertPromptable(problemOf("lib"), { choices: libNames, ...rerunRemedyOf(rerun, "<lib>") });
     const libName = await select<string>({ message: `Select the ${sysType} name`, choices: libNames });
     return LibExecutor.from(workspace, libName);
   } else if (sysType === "pkg") {
     const pkgs = await workspace.getPkgs();
     if (value && pkgs.includes(value)) return PkgExecutor.from(workspace, value);
-    assertPromptable(problemOf("pkg"), { choices: pkgs });
+    assertPromptable(problemOf("pkg"), { choices: pkgs, ...rerunRemedyOf(rerun, "<pkg>") });
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
@@ -328,7 +364,14 @@ export const getInternalArgumentValue = async (
         if (modules.includes(moduleName)) return ModuleExecutor.from(lib, moduleName);
       } else throw new Error(`Invalid system name: ${sysName}`);
     }
-    assertPromptable(problemOf("module"));
+    const systems = [
+      ...appNames.map((name) => AppExecutor.from(workspace, name)),
+      ...libNames.map((name) => LibExecutor.from(workspace, name)),
+    ];
+    const choices = process.stdin.isTTY
+      ? []
+      : (await Promise.all(systems.map(async (sys) => (await sys.getModules()).map((m) => `${sys.name}:${m}`)))).flat();
+    assertPromptable(problemOf("module"), { choices, ...rerunRemedyOf(rerun, "<sys:module>") });
     const { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -443,6 +486,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
           const workspace = WorkspaceExecutor.fromRoot();
           const commandContext: CommandContext = { values: {} };
           for (const argMeta of allArgMetas) {
+            const rerun = rerunCommandOf(process.argv.slice(2), cmdArgs, argMeta.idx);
             if (argMeta.type === "Option")
               commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt, commandContext);
             else if (argMeta.type === "Argument")
@@ -451,12 +495,14 @@ export const runCommands = async (...commands: CommandCls[]) => {
               commandArgs[argMeta.idx] = await getAppsArgumentValue(
                 cmdArgs[argMeta.idx] as string | string[] | undefined,
                 workspace,
+                rerun,
               );
             else
               commandArgs[argMeta.idx] = await getInternalArgumentValue(
                 argMeta as InternalArgMeta,
                 cmdArgs[argMeta.idx] as string,
                 workspace,
+                rerun,
               );
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;

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, WorkspaceExecutor } from "../executors";
+import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
 import { makeCliTempWorkspace, tempRoots, writeText } from "../testHelpers";
 import {
   App,
@@ -15,7 +15,13 @@ import {
   SysOrOnlyApp,
   Workspace,
 } from "./argMeta";
-import { getAppsArgumentValue, getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
+import {
+  getAppsArgumentValue,
+  getArgumentValue,
+  getInternalArgumentValue,
+  getOptionValue,
+  rerunCommandOf,
+} from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -499,6 +505,129 @@ describe("a Sys that defaults to the only app", () => {
     expect(app instanceof AppExecutor ? app.name : null).toBe("admin");
     expect(asked).toEqual([["web", "admin", "util"]]);
   });
+
+  test("a terminal is still asked when the workspace holds a single app or lib", async () => {
+    setTTY(true);
+    answer = "web";
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    const app = await getInternalArgumentValue(sysMetaOf("sync"), undefined, workspace);
+    expect(app instanceof AppExecutor ? app.name : null).toBe("web");
+    expect(asked).toEqual([["web"]]);
+  });
+
+  test("without a terminal, an Exec takes the workspace's only app, lib or pkg", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [[], [], ["tools"]];
+    const pkg = await getInternalArgumentValue({ key: "", idx: 0, type: "Exec" }, undefined, workspace);
+    expect(pkg instanceof PkgExecutor ? pkg.name : null).toBe("tools");
+    expect(asked).toEqual([]);
+  });
+
+  test("without a terminal, the only lib, pkg or module is not taken, as a command may be removing it", 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).");
+    expect(asked).toEqual([]);
+  });
+
+  test("without a terminal, a named target the workspace lacks is refused, not swapped for the only one", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    await expect(
+      getInternalArgumentValue(sysMetaOf("sync"), "webb", workspace, rerunCommandOf(["sync", "webb"], ["webb"], 0)),
+    ).rejects.toThrow(
+      "Unknown app or lib 'webb': stdin is not a terminal to prompt on, so rerun it as `akan sync <app-or-lib>` (choices: web).",
+    );
+    expect(asked).toEqual([]);
+  });
+});
+
+describe("the line a refused target is rerun with", () => {
+  test("puts the target in its operand slot, after the operands before it, keeping every option", () => {
+    expect(rerunCommandOf(["test", "--write", "false"], [undefined, undefined], 0)("<t>")).toBe(
+      "akan test <t> --write false",
+    );
+    expect(rerunCommandOf(["create-module", "--page", "true", "photo"], ["photo", undefined], 1)("web")).toBe(
+      "akan create-module --page true photo web",
+    );
+    expect(rerunCommandOf(["build", "--env", "it's main"], [undefined], 0)("web")).toBe(
+      "akan build web --env 'it'\\''s main'",
+    );
+  });
+
+  test("takes the place of a target that was given but is not in the workspace", () => {
+    expect(rerunCommandOf(["sync", "nope"], ["nope"], 0)("<app-or-lib>")).toBe("akan sync <app-or-lib>");
+  });
+});
+
+describe("a target left out where no terminal can ask for it", () => {
+  const track = tempRoots();
+  const run = async (apps: 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");
+    for (const app of apps) await writeText(path.join(root, "apps", app, "akan.config.ts"), "export default {};\n");
+    const entry = path.join(root, "cli.ts");
+    await writeText(
+      entry,
+      [
+        `import { 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" })',
+        "    .with(Sys)",
+        '    .option("force", Boolean, { default: false })',
+        "    .exec(async function (thing, sys, force) {",
+        '      process.stdout.write(thing + " in " + sys.name + ", force " + force + "\\n");',
+        "    }),",
+        "})) {}",
+        "await runCommands(ThingCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "create-thing", "photo", "--force"], {
+      cwd: root,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, code };
+  };
+
+  test("runs on the workspace's only app or lib, naming it on stderr", async () => {
+    const ran = await run(["web"]);
+    expect(ran.code).toBe(0);
+    expect(ran.stdout).toContain("photo in web, force true\n");
+    expect(ran.stderr).toContain(
+      "No app or lib named, so this runs on 'web', the only one in this workspace: akan create-thing photo web --force",
+    );
+  }, 30_000);
+
+  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.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);
 });
 
 describe("the exit code of a command that failed", () => {

package/createTunnel.test.ts

@@ -20,10 +20,20 @@ const publicBlobOf = (publicKey: string) => {
   return parsed.getPublicSSH();
 };
 
+//? ssh2 1.17's keygen strips a leading zero byte off an ed25519 public key, so 1 pair in 256 cannot be read back.
+const ed25519Pair = () => {
+  for (let tries = 1; ; tries++) {
+    const pair = utils.generateKeyPairSync("ed25519");
+    const parsed = utils.parseKey(pair.private);
+    if (!(parsed instanceof Error)) return pair;
+    if (tries === 8) throw parsed;
+  }
+};
+
 const sshServers: { server: Server; clients: Set<Connection> }[] = [];
 
 const startSshServer = async () => {
-  const hostKey = utils.generateKeyPairSync("ed25519");
+  const hostKey = ed25519Pair();
   const methods: string[] = [];
   const clients = new Set<Connection>();
   const server = new Server({ hostKeys: [hostKey.private] }, (client) => {
@@ -136,7 +146,7 @@ describe("createTunnel", () => {
     const ssh = await startSshServer();
     const knownHosts = path.join(root, "known_hosts.json");
     const keyPath = path.join(root, "id_tunnel");
-    await writeFile(keyPath, utils.generateKeyPairSync("ed25519").private);
+    await writeFile(keyPath, ed25519Pair().private);
     Object.assign(process.env, {
       SSH_TUNNEL_PORT: String(ssh.port),
       SSH_TUNNEL_KNOWN_HOSTS: knownHosts,

package/declarationReader.ts

@@ -0,0 +1,211 @@
+import path from "node:path";
+import ts from "typescript";
+
+export interface MemberFilter {
+  only?: string[];
+  omit?: string[];
+  prefix?: string;
+}
+
+const nodeFlags =
+  ts.NodeBuilderFlags.NoTruncation |
+  ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope |
+  ts.NodeBuilderFlags.OmitParameterModifiers;
+const typeFlags = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+
+export class DeclarationReader {
+  static readonly #printer = ts.createPrinter({ removeComments: true, omitTrailingSemicolon: true });
+  readonly #dir: string;
+  readonly #program: ts.Program;
+  readonly #checker: ts.TypeChecker;
+  readonly #entries: Map<string, string>;
+  readonly #scratch: ts.SourceFile;
+
+  constructor(akanjsDir: string) {
+    this.#dir = akanjsDir;
+    const configPath = path.join(akanjsDir, "tsconfig.json");
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, akanjsDir, undefined, configPath);
+    this.#entries = DeclarationReader.#entryFiles(akanjsDir);
+    this.#program = ts.createProgram({
+      rootNames: [...new Set(this.#entries.values())],
+      options: { ...parsed.options, noEmit: true },
+    });
+    this.#checker = this.#program.getTypeChecker();
+    this.#scratch = ts.createSourceFile("reference.ts", "", ts.ScriptTarget.Latest);
+  }
+
+  static #entryFiles(akanjsDir: string) {
+    const manifest = JSON.parse(ts.sys.readFile(path.join(akanjsDir, "package.json")) ?? "{}") as {
+      exports: Record<string, unknown>;
+    };
+    const entries = new Map<string, string>();
+    for (const [key, value] of Object.entries(manifest.exports)) {
+      const target = typeof value === "string" ? value : (value as { types?: string; import?: string }).types;
+      if (key.includes("*") || typeof target !== "string" || !/\.tsx?$/.test(target)) continue;
+      entries.set(key === "." ? "akanjs" : `akanjs/${key.slice(2)}`, path.join(akanjsDir, target));
+    }
+    return entries;
+  }
+
+  exported(from: string, name: string): ts.Symbol {
+    const file = this.#entries.get(from);
+    const source = file ? this.#program.getSourceFile(file) : undefined;
+    const module = source ? this.#checker.getSymbolAtLocation(source) : undefined;
+    const symbol = module ? this.#checker.getExportsOfModule(module).find((each) => each.name === name) : undefined;
+    if (!symbol) throw new Error(`${name} is not exported from ${from}: update the API reference manifest`);
+    return symbol.flags & ts.SymbolFlags.Alias ? this.#checker.getAliasedSymbol(symbol) : symbol;
+  }
+
+  declared(file: string, name: string): ts.Symbol {
+    const source = this.#program.getSourceFile(path.join(this.#dir, file));
+    const statement = source?.statements.find(
+      (each) =>
+        (ts.isClassDeclaration(each) || ts.isInterfaceDeclaration(each) || ts.isTypeAliasDeclaration(each)) &&
+        each.name?.text === name,
+    ) as ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined;
+    const symbol = statement?.name ? this.#checker.getSymbolAtLocation(statement.name) : undefined;
+    if (!symbol) throw new Error(`${name} is not declared in ${file}: update the API reference manifest`);
+    return symbol;
+  }
+
+  declaredType(symbol: ts.Symbol): ts.Type {
+    return this.#checker.getDeclaredTypeOfSymbol(symbol);
+  }
+
+  instanceType(symbol: ts.Symbol): ts.Type {
+    if (symbol.flags & (ts.SymbolFlags.Class | ts.SymbolFlags.Interface | ts.SymbolFlags.TypeAlias))
+      return this.declaredType(symbol);
+    const type = this.#checker.getTypeOfSymbol(symbol);
+    const [signature] = type.getCallSignatures();
+    return signature ? signature.getReturnType() : type;
+  }
+
+  declarationText(symbol: ts.Symbol): string {
+    const [declaration] = symbol.declarations ?? [];
+    if (!declaration) throw new Error(`${symbol.name} has no declaration`);
+    return DeclarationReader.#print(declaration, declaration.getSourceFile()).replace(/^export /, "");
+  }
+
+  signatures(symbol: ts.Symbol, name: string): string[] {
+    const type = this.#checker.getTypeOfSymbol(symbol);
+    const signatures = type.getCallSignatures();
+    if (signatures.length === 0) throw new Error(`${name} is not callable`);
+    return signatures.map((signature) => `${name}${this.#checker.signatureToString(signature, undefined, typeFlags)}`);
+  }
+
+  props(type: ts.Type, omit: string[] = []): string[] {
+    const lines: string[] = [];
+    const properties = this.#checker.getPropertiesOfType(type);
+    DeclarationReader.#assertNamed(properties, omit);
+    for (const property of properties) {
+      if (omit.includes(property.name) || DeclarationReader.#isInternalName(property.name)) continue;
+      const [declaration] = property.declarations ?? [];
+      if (declaration && !this.#isOwn(declaration)) continue;
+      const optional = property.flags & ts.SymbolFlags.Optional ? "?" : "";
+      const propertyType = declaration
+        ? this.#checker.getTypeOfSymbolAtLocation(property, declaration)
+        : this.#checker.getTypeOfSymbol(property);
+      const shown = this.#checker.typeToString(
+        optional ? this.#checker.getNonNullableType(propertyType) : propertyType,
+        undefined,
+        typeFlags,
+      );
+      const doc = this.#firstSentence(property);
+      if (doc) lines.push(`/** ${doc} */`);
+      lines.push(`${property.name}${optional}: ${shown};`);
+    }
+    return lines;
+  }
+
+  members(type: ts.Type, { only, omit = [], prefix = "." }: MemberFilter): [string, string][] {
+    const properties = this.#checker.getPropertiesOfType(type);
+    DeclarationReader.#assertNamed(properties, [...(only ?? []), ...omit]);
+    const found: [string, string][] = [];
+    for (const property of properties) {
+      const name = property.name;
+      if ((only && !only.includes(name)) || omit.includes(name) || DeclarationReader.#isInternalName(name)) continue;
+      const [declaration] = property.declarations ?? [];
+      if (!declaration || DeclarationReader.#isHidden(declaration)) continue;
+      const signatures = this.#checker.getTypeOfSymbolAtLocation(property, declaration).getCallSignatures();
+      for (const signature of signatures)
+        found.push([name, `${prefix}${name}${this.#withoutReturn(signature, declaration)}`]);
+    }
+    return found;
+  }
+
+  static #assertNamed(properties: ts.Symbol[], names: string[]) {
+    for (const name of names)
+      if (!properties.some((property) => property.name === name))
+        throw new Error(`${name} is not a member any more: update the API reference manifest`);
+  }
+
+  static #isInternalName(name: string) {
+    return name.startsWith("_") || name.startsWith("#");
+  }
+
+  #isOwn(declaration: ts.Declaration) {
+    return !path.relative(this.#dir, declaration.getSourceFile().fileName).startsWith("..");
+  }
+
+  static #isHidden(declaration: ts.Declaration) {
+    const flags = ts.getCombinedModifierFlags(declaration);
+    return (
+      (flags & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected | ts.ModifierFlags.Static)) !== 0 ||
+      (ts.isPropertyDeclaration(declaration) && !declaration.type && !declaration.initializer) ||
+      ts.isConstructorDeclaration(declaration)
+    );
+  }
+
+  #withoutReturn(signature: ts.Signature, enclosing: ts.Declaration) {
+    const node = this.#checker.signatureToSignatureDeclaration(
+      signature,
+      ts.SyntaxKind.MethodSignature,
+      enclosing,
+      nodeFlags,
+    ) as ts.MethodSignature | undefined;
+    if (!node) throw new Error(`${this.#checker.signatureToString(signature)} cannot be printed`);
+    const typeParameters = node.typeParameters?.filter((each) => !each.name.text.startsWith("_"));
+    const parameters = node.parameters.map((parameter) =>
+      parameter.questionToken && parameter.type && ts.isUnionTypeNode(parameter.type)
+        ? ts.factory.updateParameterDeclaration(
+            parameter,
+            parameter.modifiers,
+            parameter.dotDotDotToken,
+            parameter.name,
+            parameter.questionToken,
+            DeclarationReader.#withoutUndefined(parameter.type),
+            parameter.initializer,
+          )
+        : parameter,
+    );
+    const stripped = ts.factory.createMethodSignature(
+      undefined,
+      "x",
+      undefined,
+      typeParameters?.length ? typeParameters : undefined,
+      parameters,
+      undefined,
+    );
+    return DeclarationReader.#print(stripped, this.#scratch)
+      .replace(/^x/, "")
+      .replace(/;$/, "")
+      .replaceAll(" & Record<never, never>", "");
+  }
+
+  static #print(node: ts.Node, source: ts.SourceFile) {
+    return DeclarationReader.#printer.printNode(ts.EmitHint.Unspecified, node, source).replace(/\s+/g, " ");
+  }
+
+  static #withoutUndefined(type: ts.UnionTypeNode): ts.TypeNode {
+    const kept = type.types.filter((each) => each.kind !== ts.SyntaxKind.UndefinedKeyword);
+    return kept.length === 1 ? kept[0] : ts.factory.createUnionTypeNode(kept);
+  }
+
+  #firstSentence(symbol: ts.Symbol) {
+    const text = ts.displayPartsToString(symbol.getDocumentationComment(this.#checker)).replace(/\s+/g, " ").trim();
+    if (!text) return "";
+    const end = text.search(/\.(\s|$)/);
+    return (end === -1 ? text : text.slice(0, end + 1)).replace(/\*\//g, "*\\/");
+  }
+}

package/executors.test.ts

@@ -304,8 +304,8 @@ describe("Executor filesystem helpers", () => {
 
     await exec.applyTemplate({ basePath: "app", template: "app", dict: { appName: "demo" }, options: { libs: [] } });
     const templateRoot = path.resolve(import.meta.dir, "../cli/templates/app/public");
-    await expect(readFile(path.join(root, "app/public/logo.png"))).resolves.toEqual(
-      await readFile(path.join(templateRoot, "logo.png")),
+    await expect(readFile(path.join(root, "app/public/apple-touch-icon.png"))).resolves.toEqual(
+      await readFile(path.join(templateRoot, "apple-touch-icon.png")),
     );
     await expect(readFile(path.join(root, "app/public/favicon.ico"))).resolves.toEqual(
       await readFile(path.join(templateRoot, "favicon.ico")),
@@ -315,22 +315,32 @@ describe("Executor filesystem helpers", () => {
   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");
+    await writeText(path.join(root, "app/public/favicon.ico"), "the app's own icon");
 
     const applied = await exec.applyTemplate({
       basePath: "app/public",
-      template: "app/public/logo.png",
+      template: "app/public/favicon.ico",
       overwrite: false,
     });
 
-    expect(await readFile(path.join(root, "app/public/logo.png"), "utf8")).toBe("the app's own logo");
+    expect(await readFile(path.join(root, "app/public/favicon.ico"), "utf8")).toBe("the app's own icon");
     expect(applied).toEqual([
-      expect.objectContaining({ filePath: path.join(root, "app/public/logo.png"), written: false }),
+      expect.objectContaining({ filePath: path.join(root, "app/public/favicon.ico"), written: false }),
     ]);
   });
 });
 
 describe("Workspace and app executor environment contracts", () => {
+  const baseDevEnvKeys = [
+    "AKAN_PUBLIC_APP_NAME",
+    "AKAN_WORKSPACE_ROOT",
+    "AKAN_WORKSPACE_ID",
+    "AKAN_PUBLIC_REPO_NAME",
+    "AKAN_PUBLIC_SERVE_DOMAIN",
+    "AKAN_PUBLIC_ENV",
+    "PORT_OFFSET",
+  ];
+
   test("reads base development environment", () => {
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -427,8 +437,7 @@ describe("Workspace and app executor environment contracts", () => {
         "",
       ].join("\n"),
     );
-    delete process.env.AKAN_PUBLIC_REPO_NAME;
-    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    for (const key of baseDevEnvKeys) delete process.env[key];
 
     expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
       appName: "file-app",
@@ -458,6 +467,7 @@ describe("Workspace and app executor environment contracts", () => {
         "",
       ].join("\r\n"),
     );
+    for (const key of baseDevEnvKeys) delete process.env[key];
 
     expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
       appName: 'say \\"hi\\"\nagain',
@@ -471,6 +481,53 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  test("the shell outranks the workspace .env key by key, and a default stands in for what neither sets", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      [
+        "AKAN_PUBLIC_ENV=local",
+        "AKAN_PUBLIC_REPO_NAME=file-repo",
+        "AKAN_PUBLIC_SERVE_DOMAIN=file.example.com",
+        "",
+      ].join("\n"),
+    );
+    for (const key of baseDevEnvKeys) delete process.env[key];
+    Object.assign(process.env, { AKAN_PUBLIC_ENV: "main", AKAN_PUBLIC_SERVE_DOMAIN: "shell.example.com" });
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "main",
+      repoName: "file-repo",
+      serveDomain: "shell.example.com",
+      defaulted: [],
+    });
+
+    delete process.env.AKAN_PUBLIC_ENV;
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_ENV=local\n");
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "local",
+      serveDomain: "shell.example.com",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME"],
+    });
+  });
+
+  test("an empty export reads as unset, so the .env's value stands", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      "AKAN_PUBLIC_ENV=main\nAKAN_PUBLIC_REPO_NAME=file-repo\nAKAN_PUBLIC_SERVE_DOMAIN=file.example.com\n",
+    );
+    for (const key of baseDevEnvKeys) delete process.env[key];
+    Object.assign(process.env, { AKAN_PUBLIC_ENV: "", AKAN_PUBLIC_REPO_NAME: "", AKAN_PUBLIC_SERVE_DOMAIN: "" });
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "main",
+      repoName: "file-repo",
+      serveDomain: "file.example.com",
+      defaulted: [],
+    });
+  });
+
   test("builds app command environment and prepareCommand artifacts", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";