@asteroidai/cli 1.8.197 → 1.8.204

package/dist/asteroid.js

@@ -4875,16 +4875,25 @@ function defineCommands(root, options, dotted = /* @__PURE__ */ new Map(), onInv
     const defaults = command.args.map(
       (arg) => options.defaultArg?.(command, arg)
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== void 0;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === void 0 ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
-    if (defaults.some((value2) => value2 !== void 0) && options.defaultArgNote) {
-      leaf.addHelpText("after", `
-${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map(
+        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value2) => value2 !== void 0) ? options.defaultArgNote : void 0,
+      options.helpNote?.(command)
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `
+${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args) => {
       const cmd = args.at(-1);
@@ -4893,7 +4902,7 @@ ${options.defaultArgNote}`);
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -5303,7 +5312,7 @@ var ApiError = class extends Error {
   status;
   body;
 };
-var VERSION = "1.8.197";
+var VERSION = "1.8.204";
 function problem(status, body, fallback) {
   if (body && typeof body === "object") {
     const record2 = body;

package/dist/core.js

@@ -4808,16 +4808,25 @@ function defineCommands(root, options, dotted = /* @__PURE__ */ new Map(), onInv
     const defaults = command.args.map(
       (arg) => options.defaultArg?.(command, arg)
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== void 0;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === void 0 ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
-    if (defaults.some((value2) => value2 !== void 0) && options.defaultArgNote) {
-      leaf.addHelpText("after", `
-${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map(
+        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value2) => value2 !== void 0) ? options.defaultArgNote : void 0,
+      options.helpNote?.(command)
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `
+${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args) => {
       const cmd = args.at(-1);
@@ -4826,7 +4835,7 @@ ${options.defaultArgNote}`);
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.8.197",
+  "version": "1.8.204",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",

package/src/program.test.ts

@@ -96,4 +96,41 @@ describe("parseInvocation", () => {
     );
     expect(got.parsed.positionals).toEqual(["chat-wf"]);
   });
+
+  it("adds a per-command help note", async () => {
+    const help = await parseInvocation(["workflow", "get", "--help"], {
+      commands: COMMANDS,
+      helpNote: (command) =>
+        command.tool === "workflow_get" ? "Note for get." : undefined,
+    });
+
+    expect(help.kind === "exit" && help.stdout).toContain("Note for get.");
+  });
+
+  it("fills a defaulted first argument ahead of a required one", async () => {
+    const options = {
+      commands: COMMANDS,
+      defaultArg: (_: unknown, arg: { name: string }) =>
+        arg.name === "workflowId" ? "chat-wf" : undefined,
+    };
+
+    const short = command(
+      await parseInvocation(["schedule", "get", "s-1"], options),
+    );
+    expect(short.parsed.positionals).toEqual(["chat-wf", "s-1"]);
+
+    const full = command(
+      await parseInvocation(["schedule", "get", "wf-2", "s-1"], options),
+    );
+    expect(full.parsed.positionals).toEqual(["wf-2", "s-1"]);
+
+    const help = await parseInvocation(["schedule", "get", "--help"], options);
+    expect(help.kind === "exit" && help.stdout).toContain(
+      "[workflow-id] <schedule-id>",
+    );
+
+    await expect(parseInvocation(["schedule", "get"], options)).rejects.toThrow(
+      "expected [workflow-id] <schedule-id>, got 0 argument(s)",
+    );
+  });
 });

package/src/program.ts

@@ -16,6 +16,7 @@ export interface ProgramOptions {
   description?: string;
   defaultArg?: (command: CliCommand, arg: Option) => string | undefined;
   defaultArgNote?: string;
+  helpNote?: (command: CliCommand) => string | undefined;
 }
 
 const DOTTED = /^--([a-z0-9-]+\.[a-z0-9.-]+)(?:=(.*))?$/;
@@ -155,18 +156,26 @@ export function defineCommands(
     const defaults = command.args.map((arg) =>
       options.defaultArg?.(command, arg),
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== undefined;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === undefined ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? "",
       );
     });
-    if (
-      defaults.some((value) => value !== undefined) &&
-      options.defaultArgNote
-    ) {
-      leaf.addHelpText("after", `\n${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map((arg, i) =>
+        i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`,
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value) => value !== undefined)
+        ? options.defaultArgNote
+        : undefined,
+      options.helpNote?.(command),
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `\n${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args: unknown[]) => {
       const cmd = args.at(-1) as Command;
@@ -178,7 +187,9 @@ export function defineCommands(
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args
+          .map((a, i) => (i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`))
+          .join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`,
         );