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

package/cloud/updatePackUpload.ts

@@ -1,9 +1,11 @@
 import { Logger, sleep } from "akanjs/common";
 import type { BunFile } from "bun";
-import { CloudApi, type CloudRecord, type UpdateUploadRequest } from "./cloudApi";
+import type { CloudApi, CloudRecord, UpdateUploadRequest } from "./cloudApi";
+import { CloudHttpError } from "./cloudHttpError";
 
 interface UpdatePackUploadOptions {
   putRetryMs?: number;
+  putTimeoutMs?: number;
   commitRetryMs?: number;
   cutOffWindowMs?: number;
   commitLimitMs?: number;
@@ -15,9 +17,14 @@ interface UpdatePackUploadOptions {
 export class UpdatePackUpload {
   static readonly maxBytes = 200 * 1024 * 1024;
   static readonly #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
+  //? A stalled PUT never fails on its own, so each try ends once the pack would be through even at this crawl.
+  static readonly #putFloorBytesPerSecond = 64 * 1024;
+  //? Storage's Retry-After is honoured up to this: past it the presigned URL may lapse, and a fresh one is asked for.
+  static readonly #maxPutRetryAfterMs = 60_000;
   readonly #api: CloudApi;
   readonly #devProjectId: string;
   readonly #putRetryMs: number;
+  readonly #putTimeoutMs: number;
   readonly #commitRetryMs: number;
   readonly #cutOffWindowMs: number;
   readonly #commitLimitMs: number;
@@ -27,6 +34,7 @@ export class UpdatePackUpload {
     devProjectId: string,
     {
       putRetryMs = 1_000,
+      putTimeoutMs = 60_000,
       commitRetryMs = 10_000,
       cutOffWindowMs = 15 * 60_000,
       commitLimitMs = 60 * 60_000,
@@ -35,12 +43,12 @@ export class UpdatePackUpload {
     this.#api = api;
     this.#devProjectId = devProjectId;
     this.#putRetryMs = putRetryMs;
+    this.#putTimeoutMs = putTimeoutMs;
     this.#commitRetryMs = commitRetryMs;
     this.#cutOffWindowMs = cutOffWindowMs;
     this.#commitLimitMs = commitLimitMs;
   }
 
-  /** Stages the pack and commits it as a release of `fields.channel`. */
   async send(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<CloudRecord> {
     const uploadId = await this.stage(archive, fields);
     return await this.settle(() => this.#api.commitUpdateUpload(this.#devProjectId, uploadId));
@@ -67,10 +75,9 @@ export class UpdatePackUpload {
   async #request(upload: UpdateUploadRequest) {
     return await this.#api.requestUpdateUpload(this.#devProjectId, upload).catch((error: unknown) => {
       //? A server older than staged uploads has no such route: its 404 is a page, where every refusal is an Err key.
-      const message = error instanceof Error ? error.message : String(error);
-      if (CloudApi.statusOf(error) === 404 && !/"error"\s*:\s*"[\w$-]+\.error\.[\w$-]+"/.test(message))
+      if (error instanceof CloudHttpError && error.status === 404 && !error.errKey)
         throw new Error(
-          "The project's server does not take direct pack uploads yet: update akasys and try again, or upload the pack from the project's release screen.",
+          "The project's server does not take direct pack uploads yet: update Akan Cloud and try again, or upload the pack from the project's release screen.",
         );
       throw error;
     });
@@ -79,15 +86,26 @@ export class UpdatePackUpload {
   // The URL signs only its host: an unsigned x-amz-* header (a checksum included) makes storage refuse the PUT.
   // A Bun fetch error names the URL, a bearer credential, so nothing but the status leaves this method.
   async #put(url: string, contentType: string, file: BunFile) {
+    const timeoutMs = this.#putTimeoutMs + Math.ceil((file.size / UpdatePackUpload.#putFloorBytesPerSecond) * 1000);
     for (let retry = 0; ; retry++) {
-      const status = await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": contentType } })
+      const { status, retryAfterMs } = await fetch(url, {
+        method: "PUT",
+        body: file,
+        headers: { "Content-Type": contentType },
+        signal: AbortSignal.timeout(timeoutMs),
+      })
         .then(async (response) => {
           await response.arrayBuffer().catch(() => undefined);
-          return response.status;
+          return {
+            status: response.status,
+            retryAfterMs: CloudHttpError.retryAfterMs(response.headers.get("retry-after")),
+          };
         })
-        .catch(() => 0);
+        .catch(() => ({ status: 0, retryAfterMs: null }));
       if (retry === 3 || !UpdatePackUpload.#transientPut.has(status)) return status;
-      await sleep(this.#putRetryMs * (retry + 1));
+      await sleep(
+        Math.max(this.#putRetryMs * (retry + 1), Math.min(retryAfterMs ?? 0, UpdatePackUpload.#maxPutRetryAfterMs)),
+      );
     }
   }
 
@@ -109,24 +127,26 @@ export class UpdatePackUpload {
         else if (UpdatePackUpload.#cutOff(error)) cutOffSince ??= now;
         else throw error;
         const deadline = cutOffSince === null ? limit : Math.min(limit, cutOffSince + this.#cutOffWindowMs);
-        if (now + this.#commitRetryMs > deadline) throw error;
-        Logger.rawLog(
-          `The project is still taking the pack; asking again in ${Math.round(this.#commitRetryMs / 1000)}s.`,
-        );
-        await sleep(this.#commitRetryMs);
+        const waitMs = Math.max(this.#commitRetryMs, (error instanceof CloudHttpError && error.retryAfterMs) || 0);
+        if (now + waitMs > deadline) throw error;
+        Logger.rawLog(`The project is still taking the pack; asking again in ${Math.round(waitMs / 1000)}s.`);
+        await sleep(waitMs);
       }
     }
   }
 
   //? Not every 409: an upload already committed or embedded is answered 409 too, and asking again changes nothing.
   static #inProgress(error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    return CloudApi.statusOf(error) === 409 && message.includes("uploadCommitInProgress");
+    return (
+      error instanceof CloudHttpError && error.status === 409 && !!error.errKey?.endsWith(".uploadCommitInProgress")
+    );
   }
 
   static #cutOff(error: unknown) {
-    const status = CloudApi.statusOf(error);
-    if (status === null) return !(error instanceof SyntaxError);
+    if (!(error instanceof CloudHttpError)) return !(error instanceof SyntaxError);
+    const { status, errKey } = error;
+    //? A gateway with no replica ready answers 503; the server's own 503 names an Err key and is a final refusal.
+    if (status === 503) return errKey === null || errKey === "base.error.serverUnavailable";
     return status === 502 || status === 504 || (status >= 520 && status <= 527);
   }
 }

package/codeAgent/agent/CodeAgentProxy.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentProfile } from "akanjs/common";
+import { type CodeAgentProfile, trimTrailingSlashes } from "akanjs/common";
 import { akanCodeDefaultModel } from "./akanCodeModel";
 
 interface PreparedRequest {
@@ -27,7 +27,7 @@ export class CodeAgentProxy {
   readonly #token?: string;
 
   constructor({ baseUrl, providers, tokenFile, token }: CodeAgentProxyOptions) {
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.baseUrl = trimTrailingSlashes(baseUrl);
     this.providers = providers;
     this.#tokenFile = tokenFile;
     this.#token = token;

package/codeAgent/agent/akanCodeModel.ts

@@ -8,7 +8,7 @@ export interface CodeAgentModelRef {
   id: string;
 }
 
-/** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
+/** DeepSeek's million-token window is what makes the always-loaded `AGENTS.md` affordable on every turn. */
 export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
 
 // Declared text-only by the catalogue, yet verified against the provider to see images.

package/codeAgent/agent/akanContextFiles.test.ts

@@ -73,7 +73,9 @@ describe("workspace context files", () => {
   test("a rule with no frontmatter at all is unconditional, and so is .cursorrules", () => {
     const root = workspace({ ".cursor/rules/plain.mdc": "just do it", ".cursorrules": "the legacy file" });
     const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
-    expect(namesOf(files, root).sort()).toEqual([".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort());
+    expect(namesOf(files, root).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort(),
+    );
   });
 
   test("rules nested under the rules directory are found, in a stable order", () => {

package/codeAgent/tools/WebToolPack.ts

@@ -132,14 +132,14 @@ export class WebToolPack {
   /** Enough to read a documentation page; a full HTML parser is not worth a dependency for that. */
   static #readable(html: string) {
     return html
-      .replace(/<script[\s\S]*?<\/script>/gi, " ")
-      .replace(/<style[\s\S]*?<\/style>/gi, " ")
-      .replace(/<[^>]+>/g, " ")
+      .replace(/<script[\s\S]*?<\/script[^<>]*>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style[^<>]*>/gi, " ")
+      .replace(/<[^<>]+>/g, " ")
       .replace(/&nbsp;/g, " ")
-      .replace(/&amp;/g, "&")
       .replace(/&lt;/g, "<")
       .replace(/&gt;/g, ">")
       .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, "&")
       .replace(/[ \t]+/g, " ")
       .replace(/\n{3,}/g, "\n\n")
       .trim();

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -247,22 +247,26 @@ describe("PreviewView", () => {
     expect(typeof PreviewView.available).toBe("boolean");
   });
 
-  test.skipIf(!PreviewView.available)("finds an empty body and a console error on a real page", async () => {
-    const server = Bun.serve({
-      port: 0,
-      fetch: () =>
-        new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
-          headers: { "content-type": "text/html" },
-        }),
-    });
-    try {
-      const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
-      expect(probe.pageErrors.join(" ")).toContain("rendered empty");
-      expect(probe.consoleErrors.join(" ")).toContain("boom");
-    } finally {
-      server.stop(true);
-    }
-  });
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = Bun.serve({
+        port: 0,
+        fetch: () =>
+          new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
+            headers: { "content-type": "text/html" },
+          }),
+      });
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
 });
 
 describe("SubagentPool", () => {

package/commandDecorators/argMeta.ts

@@ -49,11 +49,15 @@ export interface ArgMeta<Context = CommandContext> {
   idx: number;
   type: ArgType;
 }
+export interface InternalArgOption {
+  nullable?: boolean;
+  onlyApp?: boolean;
+}
 export interface InternalArgMeta {
   key: string;
   idx: number;
   type: InternalArgType;
-  option?: { nullable?: boolean };
+  option?: InternalArgOption;
 }
 
 export const getArgMetas = (
@@ -69,9 +73,11 @@ export const getArgMetas = (
 export interface InternalArgToken<T = unknown, Type extends InternalArgType = InternalArgType> {
   type: Type;
   _value: T;
+  option?: InternalArgOption;
 }
 
-const createInternalArgToken = <T, Type extends InternalArgType>(type: Type) => ({ type }) as InternalArgToken<T, Type>;
+const createInternalArgToken = <T, Type extends InternalArgType>(type: Type, option?: InternalArgOption) =>
+  (option ? { type, option } : { type }) as InternalArgToken<T, Type>;
 
 export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPrimitiveArgType => {
   if (type === String) return "string";
@@ -93,6 +99,9 @@ export type Lib = LibExecutor;
 export const Sys = createInternalArgToken<SysExecutor, "Sys">("Sys");
 export type Sys = SysExecutor;
 
+/** Sys, except that a one-app workspace given no name means its app, as with App. */
+export const SysOrOnlyApp = createInternalArgToken<SysExecutor, "Sys">("Sys", { onlyApp: true });
+
 export const Exec = createInternalArgToken<Executor, "Exec">("Exec");
 export type Exec = Executor;
 

package/commandDecorators/command.ts

@@ -23,6 +23,7 @@ import {
 } from "./argMeta";
 import { camelToKebabCase } from "./camelToKebabCase";
 import { CommandContainer } from "./dependencyBuilder";
+import { ExitCodeError } from "./exitCodeError";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetCommandNames, getTargetMetas } from "./targetMeta";
 
@@ -102,6 +103,9 @@ const confirm = ((config, context) => prompts().then((m) => m.confirm(config, co
 const input = ((config, context) => prompts().then((m) => m.input(config, context))) as typeof inquirerInput;
 const checkbox = ((config, context) => prompts().then((m) => m.checkbox(config, context))) as typeof inquirerCheckbox;
 
+const argLabelOf = (argMeta: ArgMeta) =>
+  argMeta.type === "Option" ? `option '--${camelToKebabCase(argMeta.name)}'` : `argument '${argMeta.name}'`;
+
 // A DynamicEnum is not checked: it resolves against a context the internal args have not populated yet.
 // Compared as strings: the value is still commander's raw string while a numeric choice list holds numbers.
 const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
@@ -109,10 +113,19 @@ const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
   if (!enumChoices || typeof enumChoices === "function") return;
   const choices = normalizeEnumChoices(enumChoices);
   if (choices.some((choice) => String(choice.value) === String(value))) return;
-  const label =
-    argMeta.type === "Option" ? `option '--${camelToKebabCase(argMeta.name)}'` : `argument '${argMeta.name}'`;
   throw new Error(
-    `${label} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
+    `${argLabelOf(argMeta)} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
+  );
+};
+
+// On a piped stdin a prompt takes the pipe as its answer and echoes it: a piped secret printed as the secret's name.
+export const assertPromptable = (
+  problem: string,
+  { choices = [], remedy = "pass it on the command line" }: { choices?: readonly unknown[]; remedy?: string } = {},
+) => {
+  if (process.stdin.isTTY) return;
+  throw new Error(
+    `${problem}: stdin is not a terminal to prompt on, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`,
   );
 };
 
@@ -136,8 +149,11 @@ export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unkno
       (typeof enumChoices === "function" ? await enumChoices(context) : enumChoices) ?? [],
     );
     if (choices.length === 1) return choices[0]?.value;
+    assertPromptable(`Missing ${argLabelOf(argMeta)}`, { choices: choices.map((choice) => choice.value) });
     return await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
-  } else if (type === "boolean") {
+  }
+  assertPromptable(`Missing ${argLabelOf(argMeta)}`);
+  if (type === "boolean") {
     const message = ask ?? desc ?? `Do you want to set ${name}? ${desc ? ` (${desc})` : ""}: `;
     return await confirm({ message });
   } else return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
@@ -150,6 +166,13 @@ export const getArgumentValue = async (argMeta: ArgMeta, value: string | undefin
     return convertArgValue(value, type ?? "string");
   } else if (defaultValue !== undefined) return defaultValue;
   else if (nullable) return null;
+  const { enum: enumChoices } = argMeta.argsOption;
+  assertPromptable(`Missing ${argLabelOf(argMeta)}`, {
+    choices:
+      enumChoices && typeof enumChoices !== "function"
+        ? normalizeEnumChoices(enumChoices).map(({ value }) => value)
+        : [],
+  });
   return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
 };
 
@@ -163,20 +186,21 @@ const assignCommandContext = (context: CommandContext, argMeta: ArgMeta | Intern
   else context.values[argMeta.type.toLowerCase()] = value;
 };
 
+//? Not `.env`, which a fresh clone lacks; an app or a package folder has a package.json and tsconfig.json of its own.
 const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   const cwd = process.cwd();
-  const [hasPackageJson, hasTsConfig, hasEnv] = await Promise.all([
+  const [hasPackageJson, hasTsConfig, ...hasMemberDirs] = await Promise.all([
     FileSys.fileExists(`${cwd}/package.json`),
     FileSys.fileExists(`${cwd}/tsconfig.json`),
-    FileSys.fileExists(`${cwd}/.env`),
+    ...["apps", "libs", "pkgs"].map((dir) => FileSys.dirExists(`${cwd}/${dir}`)),
   ]);
-  if (hasPackageJson && hasTsConfig && hasEnv) return;
+  if (hasPackageJson && hasTsConfig && hasMemberDirs.some(Boolean)) return;
 
   throw new Error(
     [
       "Akan CLI commands must be run from the workspace root.",
       `Current directory: ${cwd}`,
-      "Move to the directory that contains package.json, tsconfig.json, and .env, then run the command again.",
+      "Move to the directory that contains package.json, tsconfig.json, and an apps/, libs/ or pkgs/ folder, then run the command again.",
     ].join("\n"),
   );
 };
@@ -205,6 +229,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"] });
   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)",
@@ -224,6 +249,7 @@ export const getInternalArgumentValue = async (
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
   const [appNames, libNames, pkgNames] = await workspace.getExecs();
+  const problemOf = (kind: string) => (value ? `Unknown ${kind} '${value}'` : `Missing ${kind}`);
   if (sysType === "sys" || sysType === "exec") {
     const pkgChoices = sysType === "exec" ? pkgNames : [];
     const execOf = (name: string) => {
@@ -234,6 +260,11 @@ export const getInternalArgumentValue = async (
     };
     const found = value ? execOf(value) : null;
     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 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],
@@ -244,15 +275,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 });
     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 });
     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 });
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
@@ -270,6 +304,7 @@ 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 { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -291,7 +326,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
   let failureExitCode = 1;
   process.on("unhandledRejection", (error) => {
     printCliError(error);
-    process.exit(failureExitCode);
+    process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
   });
   const __dirname = getDirname(import.meta.url);
   const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname}/../package.json`];
@@ -419,6 +454,6 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
   // Handled here, not by the handler above: a rejection reaching the entry's top-level await prints Bun's own trace.
   await program.parseAsync(process.argv).catch((error: unknown) => {
     printCliError(error);
-    process.exit(failureExitCode);
+    process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
   });
 };

package/commandDecorators/commandBuilder.ts

@@ -115,7 +115,12 @@ class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknow
 
   with<const Tokens extends readonly InternalArgToken[]>(...tokens: Tokens) {
     return this.#add<AddInternalArgs<Params, Tokens>, AddInternalContext<Context, Tokens>>(
-      ...tokens.map((token, offset) => ({ key: "", idx: this.#args.length + offset, type: token.type })),
+      ...tokens.map((token, offset) => ({
+        key: "",
+        idx: this.#args.length + offset,
+        type: token.type,
+        ...(token.option ? { option: token.option } : {}),
+      })),
     );
   }