specli 0.0.31 → 0.0.33

package/dist/ai/tools.d.ts

@@ -25,7 +25,7 @@ import { type SpecliOptions } from "../client/index.js";
  * tool already has the spec loaded and ready to use.
  */
 export declare function specliTool(options: SpecliOptions): Promise<import("ai").Tool<{
-    command: "list" | "exec" | "help";
+    command: "list" | "help" | "exec";
     resource?: string | undefined;
     action?: string | undefined;
     args?: string[] | undefined;

package/dist/cli/main.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { getArgValue, hasAnyArg } from "./runtime/argv.js";
 import { collectRepeatable } from "./runtime/collect.js";
 /**
@@ -28,6 +28,7 @@ import { deleteToken, getToken, setToken } from "./runtime/profile/secrets.js";
 import { readProfiles, upsertProfile, writeProfiles, } from "./runtime/profile/store.js";
 export async function main(argv, options = {}) {
     const program = new Command();
+    const defaultHelp = new Help();
     // Get version - use embedded version if available, otherwise read from package.json
     const cliVersion = options.version ?? getPackageVersion();
     program
@@ -45,7 +46,6 @@ export async function main(argv, options = {}) {
         .option("--api-key <key>", "API key value")
         .option("--json", "Machine-readable output")
         .showHelpAfterError();
-    program.addHelpText("after", `\nAgent workflow:\n  1) ${options.cliName ?? "specli"} __schema --json --min\n  2) ${options.cliName ?? "specli"} <resource> --help\n  3) ${options.cliName ?? "specli"} <resource> <action> --help\n`);
     // If user asks for help and we have no embedded spec and no --spec, show minimal help.
     const spec = getArgValue(argv, "--spec");
     const wantsHelp = hasAnyArg(argv, ["-h", "--help"]);
@@ -152,6 +152,7 @@ export async function main(argv, options = {}) {
         .description("Print indexed operations (machine-readable when --json)")
         .option("--pretty", "Pretty-print JSON when used with --json")
         .option("--min", "Minimal JSON output (commands + metadata only)")
+        .option("--commands", "List all <resource> <action> commands (can be large)")
         .action(async (_opts, command) => {
         const flags = command.optsWithGlobals();
         if (flags.json) {
@@ -165,11 +166,17 @@ export async function main(argv, options = {}) {
         }
         process.stdout.write(`${ctx.schema.openapi.title ?? "(untitled)"}\n`);
         process.stdout.write(`OpenAPI: ${ctx.schema.openapi.version}\n`);
-        process.stdout.write(`Spec: ${ctx.schema.spec.id} (${ctx.schema.spec.source})\n`);
-        process.stdout.write(`Fingerprint: ${ctx.schema.spec.fingerprint}\n`);
         process.stdout.write(`Servers: ${ctx.schema.servers.length}\n`);
         process.stdout.write(`Auth Schemes: ${ctx.schema.authSchemes.length}\n`);
-        if (ctx.schema.planned?.length) {
+        process.stdout.write(`Spec: ${ctx.schema.spec.id} (${ctx.schema.spec.source})\n`);
+        // Token-efficient default output: list resources (top-level commands)
+        // and push the user/agent toward --help for details.
+        process.stdout.write(`\nResources: ${ctx.commands.resources.length}\n\n`);
+        const resources = [...ctx.commands.resources].sort((a, b) => a.resource.localeCompare(b.resource));
+        for (const r of resources) {
+            process.stdout.write(`- ${r.resource} (${r.actions.length} actions)\n`);
+        }
+        if (flags.commands && ctx.schema.planned?.length) {
             process.stdout.write(`\nCommands: ${ctx.schema.planned.length}\n\n`);
             for (const op of ctx.schema.planned) {
                 const args = op.pathArgs.length
@@ -178,10 +185,10 @@ export async function main(argv, options = {}) {
                 process.stdout.write(`- ${program.name()} ${op.resource} ${op.action}${args}\n`);
             }
         }
-        process.stdout.write("\nTip: explore required flags with --help at each level:\n" +
-            `- ${program.name()} --help\n` +
+        process.stdout.write("\nNext:\n" +
             `- ${program.name()} <resource> --help\n` +
-            `- ${program.name()} <resource> <action> --help\n`);
+            `- ${program.name()} <resource> <action> --help\n` +
+            "\nNote: Use --help to discover required flags; avoid __schema --json for agent use (too verbose).\n");
     });
     addGeneratedCommands(program, {
         servers: ctx.servers,
@@ -194,6 +201,76 @@ export async function main(argv, options = {}) {
             auth: options.auth,
         },
     });
+    program.configureHelp({
+        formatHelp: (cmd, _helper) => {
+            // Only customize the top-level help. Subcommands should keep
+            // their own default or explicitly configured help.
+            if (cmd !== program)
+                return defaultHelp.formatHelp(cmd, defaultHelp);
+            const lines = [];
+            const name = program.name();
+            const embedded = Boolean(options.embeddedSpecText);
+            lines.push(`Usage: ${name} [options] [command]`);
+            lines.push("");
+            lines.push(program.description());
+            lines.push("");
+            // OpenAPI-derived commands first (resources)
+            if (ctx.commands.resources.length > 0) {
+                lines.push("OpenAPI Commands:");
+                const resources = [...ctx.commands.resources]
+                    .map((r) => r.resource)
+                    .sort((a, b) => a.localeCompare(b));
+                for (const r of resources) {
+                    lines.push(`  ${r}`);
+                }
+                lines.push("");
+            }
+            // Non-OpenAPI commands (built-ins)
+            lines.push("Global Commands:");
+            const globalCommands = ["login", "logout", "whoami", "__schema", "help"];
+            const maxCmdLen = Math.max(...globalCommands.map((c) => c.length));
+            for (const cmdName of globalCommands) {
+                const c = program.commands.find((c) => c.name() === cmdName);
+                if (!c)
+                    continue;
+                const term = cmdName === "login"
+                    ? "login [token]"
+                    : cmdName === "help"
+                        ? "help [command]"
+                        : cmdName;
+                const desc = c.description();
+                const pad = " ".repeat(Math.max(1, maxCmdLen - cmdName.length + 2));
+                lines.push(`  ${term}${pad}${desc}`);
+            }
+            lines.push("");
+            // Global options last
+            lines.push("Global Options:");
+            const optionRows = [];
+            for (const opt of program.options) {
+                // In compiled binaries the spec is embedded; --spec is meaningless.
+                if (embedded && opt.long === "--spec")
+                    continue;
+                optionRows.push({ flags: opt.flags, desc: opt.description });
+            }
+            optionRows.push({
+                flags: "-h, --help",
+                desc: "display help for command",
+            });
+            const maxOptLen = Math.max(...optionRows.map((o) => o.flags.length));
+            for (const row of optionRows) {
+                const pad = " ".repeat(Math.max(1, maxOptLen - row.flags.length + 2));
+                lines.push(`  ${row.flags}${pad}${row.desc}`);
+            }
+            lines.push("");
+            lines.push("Agent workflow:");
+            lines.push(`  1) ${name} __schema`);
+            lines.push(`  2) ${name} <resource> --help`);
+            lines.push(`  3) ${name} <resource> <action> --help`);
+            lines.push(`  4) ${name} <resource> <action> --curl`);
+            lines.push("");
+            return lines.join("\n");
+        },
+    });
     if (argv.length <= 2) {
         program.outputHelp();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "specli",
-	"version": "0.0.31",
+	"version": "0.0.33",
 	"description": "Run any OpenAPI spec as a CLI. Built for Agents.",
 	"repository": {
 		"type": "git",
@@ -31,7 +31,7 @@
 	],
 	"scripts": {
 		"build": "tsc",
-		"prepublishOnly": "tsc",
+		"prepublishOnly": "rm -rf dist && tsc",
 		"lint": "biome ci",
 		"lint:check": "biome check --write --unsafe",
 		"lint:format": "biome format --write",
@@ -54,7 +54,7 @@
 		"@tsconfig/node22": "^22.0.5",
 		"@types/bun": "^1.3.6",
 		"@types/node": "^22.19.7",
-		"@typescript/native-preview": "^7.0.0-dev.20260122.3",
+		"@typescript/native-preview": "^7.0.0-dev.20260122.4",
 		"typescript": "^5.9.3"
 	}
 }