@recur-tw/cli 0.1.4 → 0.2.0

package/AGENT.md

@@ -15,6 +15,9 @@ capabilities:
   - checkout-sessions
   - schema-introspection
   - dry-run-validation
+  - command-discovery
+  - agent-help
+  - breadcrumb-hints
 ---
 
 # Recur CLI — Agent Instructions
@@ -27,16 +30,19 @@ capabilities:
 # 1. Auth (once)
 export RECUR_SECRET_KEY=sk_test_xxx
 
-# 2. Discover API shape
+# 2. Discover all CLI commands (structured JSON)
+recur commands --output json
+
+# 3. Discover API shape
 recur schema --output json
 
-# 3. Drill into a specific action
+# 4. Drill into a specific action
 recur schema products.create --output json
 
-# 4. Dry-run first (validates locally, no API call)
+# 5. Dry-run first (validates locally, no API call)
 recur products create --json '{"name":"Test","price":299}' --dry-run --output json
 
-# 5. Execute
+# 6. Execute
 recur products create --json '{"name":"Test","price":299}' --output json
 ```
 
@@ -63,6 +69,63 @@ export RECUR_SECRET_KEY=sk_test_xxx
 recur --key sk_test_xxx products list --output json
 ```
 
+## Discovery
+
+The CLI provides three levels of programmatic discovery:
+
+### 1. Command Inventory (`recur commands`)
+
+Lists all CLI commands, options, and arguments as structured JSON:
+
+```bash
+recur commands --output json
+# Returns: { name, version, global_options, commands: [{ name, description, subcommands }] }
+```
+
+### 2. Machine-Readable Help (`--agent`)
+
+Get structured JSON help for any command:
+
+```bash
+recur products --help --agent          # Parent command: lists subcommands
+recur products list --help --agent     # Leaf command: lists options, arguments, api_schema ref
+```
+
+Returns: `{ command, description, options, arguments, subcommands?, global_options, api_schema? }`
+
+### 3. Breadcrumb Hints (`_hints`)
+
+JSON responses from get/create/update/cancel include a `_hints` array suggesting next commands:
+
+```bash
+recur products get <id> --output json
+# Response includes:
+# "_hints": [
+#   { "description": "List subscriptions for this product", "command": "recur subscriptions list --product-id <id>" },
+#   { "description": "Create a checkout session", "command": "recur checkouts create --product-id <id>" }
+# ]
+```
+
+Hints only appear in `--output json`. Use `--fields` to exclude them if not needed.
+
+### Recommended Agent Workflow: Discovery → Schema → Action
+
+```bash
+# Step 1: What commands exist?
+recur commands --output json
+
+# Step 2: What does this specific command need?
+recur products create --help --agent
+
+# Step 3: What does the API expect?
+recur schema products.create --output json
+
+# Step 4: Dry-run → Execute → Follow hints
+recur products create --json '...' --dry-run --output json
+recur products create --json '...' --output json
+# → _hints will suggest next steps
+```
+
 ## Schema Introspection
 
 The CLI is self-describing. Use `recur schema` to discover everything at runtime.

package/dist/cli.mjs

@@ -920,7 +920,7 @@ var RecurClient = class {
 		}
 		const headers = {
 			Authorization: `Bearer ${this.secretKey}`,
-			"User-Agent": `@recur-tw/cli/0.1.4`
+			"User-Agent": `@recur-tw/cli/0.2.0`
 		};
 		const hasBody = opts?.body !== void 0;
 		if (hasBody) headers["Content-Type"] = "application/json";
@@ -996,7 +996,8 @@ const TABLE_HIDDEN_FIELDS = new Set([
 	"product_family",
 	"livemode",
 	"created_at",
-	"updated_at"
+	"updated_at",
+	"_hints"
 ]);
 /**
 * Render data in the specified format.
@@ -1347,6 +1348,181 @@ function extractPaginatedList(response) {
 	};
 }
 //#endregion
+//#region src/hints.ts
+const rules = {
+	"products.get": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "List subscriptions for this product",
+			command: `recur subscriptions list --product-id ${id}`
+		}, {
+			description: "Create a checkout session",
+			command: `recur checkouts create --product-id ${id}`
+		}];
+	},
+	"products.create": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "View created product",
+			command: `recur products get ${id}`
+		}, {
+			description: "Create a checkout session",
+			command: `recur checkouts create --product-id ${id}`
+		}];
+	},
+	"products.update": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "View updated product",
+			command: `recur products get ${id}`
+		}];
+	},
+	"products.archive": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "Verify archived status",
+			command: `recur products get ${id}`
+		}, {
+			description: "List archived products",
+			command: "recur products list --status archived"
+		}];
+	},
+	"customers.get": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [
+			{
+				description: "List subscriptions",
+				command: `recur subscriptions list --customer-id ${id}`
+			},
+			{
+				description: "List orders",
+				command: `recur orders list --customer-id ${id}`
+			},
+			{
+				description: "List invoices",
+				command: `recur invoices list --customer-id ${id}`
+			}
+		];
+	},
+	"customers.update": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "View updated customer",
+			command: `recur customers get ${id}`
+		}];
+	},
+	"subscriptions.get": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		const hints = [{
+			description: "List invoices for this subscription",
+			command: `recur invoices list --subscription-id ${id}`
+		}];
+		if (data["status"] === "active" || data["status"] === "trialing") hints.push({
+			description: "Preview cancellation",
+			command: `recur subscriptions cancel ${id} --dry-run`
+		});
+		return hints;
+	},
+	"subscriptions.cancel": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "Verify canceled status",
+			command: `recur subscriptions get ${id}`
+		}];
+	},
+	"orders.get": (data) => {
+		const customerId = data["customer_id"];
+		const hints = [];
+		if (customerId) hints.push({
+			description: "View customer",
+			command: `recur customers get ${customerId}`
+		});
+		return hints;
+	},
+	"invoices.get": (data) => {
+		const hints = [];
+		const subscriptionId = data["subscription_id"];
+		if (subscriptionId) hints.push({
+			description: "View subscription",
+			command: `recur subscriptions get ${subscriptionId}`
+		});
+		const customerId = data["customer_id"];
+		if (customerId) hints.push({
+			description: "View customer",
+			command: `recur customers get ${customerId}`
+		});
+		return hints;
+	},
+	"checkouts.create": (data) => {
+		const id = data["id"];
+		if (!id) return [];
+		return [{
+			description: "Check session status",
+			command: `recur checkouts get ${id}`
+		}];
+	},
+	"checkouts.get": (data) => {
+		const hints = [];
+		const customerId = data["customer_id"];
+		if (customerId) hints.push({
+			description: "View customer",
+			command: `recur customers get ${customerId}`
+		});
+		return hints;
+	},
+	"webhooks.create": (data) => {
+		const id = data["id"];
+		const url = data["url"];
+		const hints = [];
+		if (id) hints.push({
+			description: "Send a test event",
+			command: `recur webhooks test ${id}`
+		});
+		if (url) hints.push({
+			description: "Listen for events locally",
+			command: `recur webhooks listen ${url}`
+		});
+		return hints;
+	},
+	"webhooks.test": (data) => {
+		if (!(data["webhook_id"] ?? data["id"])) return [];
+		return [{
+			description: "View webhook details",
+			command: `recur webhooks list`
+		}];
+	}
+};
+/**
+* Generate contextual hints suggesting next commands.
+*/
+function generateHints(resource, action, data) {
+	const rule = rules[`${resource}.${action}`];
+	return rule ? rule(data) : [];
+}
+/**
+* Attach _hints to a single-object response when format is json.
+* Returns data unchanged for non-json formats or if no hints apply.
+*/
+function attachHints(data, resource, action, format) {
+	if (format !== "json") return data;
+	if (typeof data !== "object" || data === null || Array.isArray(data)) return data;
+	const record = data;
+	const hints = generateHints(resource, action, record);
+	if (hints.length === 0) return data;
+	return {
+		...record,
+		_hints: hints
+	};
+}
+//#endregion
 //#region src/commands/products.ts
 function getClient$6(opts) {
 	return new RecurClient({
@@ -1395,7 +1571,7 @@ Examples:
 			const client = getClient$6(opts);
 			const validId = validateResourceId(id);
 			const path = id.includes("-") ? `/v1/products/by-slug/${validId}` : `/v1/products/${validId}`;
-			const data = await client.get(path);
+			const data = attachHints(await client.get(path), "products", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts$6(opts));
 		} catch (err) {
 			handleError(err);
@@ -1437,7 +1613,7 @@ Examples:
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient$6(opts).post("/v1/products", body), getOutputOpts$6(opts));
+			render(attachHints(await getClient$6(opts).post("/v1/products", body), "products", "create", opts.output), getOutputOpts$6(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1470,7 +1646,7 @@ Examples:
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient$6(opts).patch(`/v1/products/${validId}`, body), getOutputOpts$6(opts));
+			render(attachHints(await getClient$6(opts).patch(`/v1/products/${validId}`, body), "products", "update", opts.output), getOutputOpts$6(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1483,7 +1659,7 @@ Examples:
 				console.error(pc.yellow(`[dry-run] Would archive product ${validId}`));
 				return;
 			}
-			render(await getClient$6(opts).post(`/v1/products/${validId}/archive`), getOutputOpts$6(opts));
+			render(attachHints(await getClient$6(opts).post(`/v1/products/${validId}/archive`), "products", "archive", opts.output), getOutputOpts$6(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1575,7 +1751,7 @@ Examples:
 		try {
 			const opts = customers.optsWithGlobals();
 			const validId = validateResourceId(id);
-			const data = await getClient$5(opts).get(`/v1/customers/${validId}`);
+			const data = attachHints(await getClient$5(opts).get(`/v1/customers/${validId}`), "customers", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts$5(opts));
 		} catch (err) {
 			handleError(err);
@@ -1600,7 +1776,7 @@ Examples:
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient$5(opts).patch(`/v1/customers/${validId}`, body), getOutputOpts$5(opts));
+			render(attachHints(await getClient$5(opts).patch(`/v1/customers/${validId}`, body), "customers", "update", opts.output), getOutputOpts$5(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1670,7 +1846,7 @@ Note: --immediately is a flag (no value). Do NOT use --immediately false; omit t
 		try {
 			const opts = subscriptions.optsWithGlobals();
 			const validId = validateResourceId(id);
-			const data = await getClient$4(opts).get(`/v1/subscriptions/${validId}`);
+			const data = attachHints(await getClient$4(opts).get(`/v1/subscriptions/${validId}`), "subscriptions", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts$4(opts));
 		} catch (err) {
 			handleError(err);
@@ -1690,7 +1866,7 @@ Note: --immediately is a flag (no value). Do NOT use --immediately false; omit t
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient$4(opts).post(`/v1/subscriptions/${validId}/cancel`, body), getOutputOpts$4(opts));
+			render(attachHints(await getClient$4(opts).post(`/v1/subscriptions/${validId}/cancel`, body), "subscriptions", "cancel", opts.output), getOutputOpts$4(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1946,7 +2122,7 @@ Examples:
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient$3(opts).post("/v1/webhooks", body), getOutputOpts$3(opts));
+			render(attachHints(await getClient$3(opts).post("/v1/webhooks", body), "webhooks", "create", opts.output), getOutputOpts$3(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -1959,7 +2135,7 @@ Examples:
 				console.error(pc.yellow(`[dry-run] Would send test event "${cmdOpts.event}" to webhook ${validId}`));
 				return;
 			}
-			render(await getClient$3(opts).post(`/v1/webhooks/${validId}/test`, { eventType: cmdOpts.event }), getOutputOpts$3(opts));
+			render(attachHints(await getClient$3(opts).post(`/v1/webhooks/${validId}/test`, { eventType: cmdOpts.event }), "webhooks", "test", opts.output), getOutputOpts$3(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -2037,7 +2213,7 @@ Examples:
 		try {
 			const opts = orders.optsWithGlobals();
 			const validId = validateResourceId(id);
-			const data = await getClient$2(opts).get(`/v1/orders/${validId}`);
+			const data = attachHints(await getClient$2(opts).get(`/v1/orders/${validId}`), "orders", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts$2(opts));
 		} catch (err) {
 			handleError(err);
@@ -2103,7 +2279,7 @@ Examples:
 		try {
 			const opts = invoices.optsWithGlobals();
 			const validId = validateResourceId(id);
-			const data = await getClient$1(opts).get(`/v1/invoices/${validId}`);
+			const data = attachHints(await getClient$1(opts).get(`/v1/invoices/${validId}`), "invoices", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts$1(opts));
 		} catch (err) {
 			handleError(err);
@@ -2166,7 +2342,7 @@ Examples:
 				render(body, { format: "json" });
 				return;
 			}
-			render(await getClient(opts).post("/v1/checkouts", body), getOutputOpts(opts));
+			render(attachHints(await getClient(opts).post("/v1/checkouts", body), "checkouts", "create", opts.output), getOutputOpts(opts));
 		} catch (err) {
 			handleError(err);
 		}
@@ -2175,7 +2351,7 @@ Examples:
 		try {
 			const opts = checkouts.optsWithGlobals();
 			const validId = validateResourceId(id);
-			const data = await getClient(opts).get(`/v1/checkouts/${validId}`);
+			const data = attachHints(await getClient(opts).get(`/v1/checkouts/${validId}`), "checkouts", "get", opts.output);
 			render(opts.fields ? pickFields(data, opts.fields.split(",")) : data, getOutputOpts(opts));
 		} catch (err) {
 			handleError(err);
@@ -2564,7 +2740,7 @@ Requires a Secret Key (sk_test_* or sk_live_*) via --key, RECUR_SECRET_KEY, or r
 			});
 			const server = new McpServer({
 				name: "recur",
-				version: "0.1.4"
+				version: "0.2.0"
 			}, { capabilities: { tools: {} } });
 			registerTools(server, client);
 			const transport = new StdioServerTransport();
@@ -2578,9 +2754,146 @@ Requires a Secret Key (sk_test_* or sk_live_*) via --key, RECUR_SECRET_KEY, or r
 	});
 }
 //#endregion
+//#region src/commands/commands.ts
+function extractOptions$1(cmd) {
+	return cmd.options.filter((o) => !o.hidden).map((o) => {
+		const def = {
+			flags: o.flags,
+			description: o.description
+		};
+		if (o.defaultValue !== void 0) def.default = o.defaultValue;
+		return def;
+	});
+}
+function extractArguments$1(cmd) {
+	return cmd.registeredArguments.map((a) => ({
+		name: a.name(),
+		required: a.required,
+		description: a.description
+	}));
+}
+/**
+* Walk the Commander.js command tree and return a structured inventory.
+* Exported for reuse by --agent help.
+*/
+function walkCommandTree(program) {
+	const globalOptions = extractOptions$1(program);
+	const commands = program.commands.filter((cmd) => !cmd.hidden).map((cmd) => {
+		const subcommands = cmd.commands.filter((sub) => !sub.hidden).map((sub) => ({
+			name: sub.name(),
+			full_command: `recur ${cmd.name()} ${sub.name()}`,
+			description: sub.description(),
+			options: extractOptions$1(sub),
+			arguments: extractArguments$1(sub)
+		}));
+		return {
+			name: cmd.name(),
+			description: cmd.description(),
+			options: extractOptions$1(cmd),
+			arguments: extractArguments$1(cmd),
+			subcommands
+		};
+	});
+	return {
+		name: program.name(),
+		version: "0.2.0",
+		global_options: globalOptions,
+		commands
+	};
+}
+function registerCommandsCommand(program) {
+	program.command("commands").description("List all CLI commands as structured JSON (for AI agents and automation)").action(() => {
+		try {
+			const opts = program.opts();
+			render(walkCommandTree(program), { format: opts.output });
+		} catch (err) {
+			handleError(err);
+		}
+	});
+}
+//#endregion
+//#region src/agent-help.ts
+function extractOptions(cmd) {
+	return cmd.options.filter((o) => !o.hidden).map((o) => {
+		const def = {
+			flags: o.flags,
+			description: o.description
+		};
+		if (o.defaultValue !== void 0) def.default = o.defaultValue;
+		return def;
+	});
+}
+function extractArguments(cmd) {
+	return cmd.registeredArguments.map((a) => ({
+		name: a.name(),
+		required: a.required,
+		description: a.description
+	}));
+}
+function getFullCommand(cmd) {
+	const parts = [];
+	let current = cmd;
+	while (current) {
+		parts.unshift(current.name());
+		current = current.parent;
+	}
+	return parts.join(" ");
+}
+function findRoot(cmd) {
+	let current = cmd;
+	while (current.parent) current = current.parent;
+	return current;
+}
+/**
+* Extract structured metadata from a Commander.js command.
+*/
+function extractCommandMeta(cmd) {
+	const fullCommand = getFullCommand(cmd);
+	const root = findRoot(cmd);
+	const meta = {
+		command: fullCommand,
+		description: cmd.description(),
+		arguments: extractArguments(cmd),
+		options: extractOptions(cmd),
+		global_options: extractOptions(root)
+	};
+	const visibleSubs = cmd.commands.filter((sub) => !sub.hidden);
+	if (visibleSubs.length > 0) meta.subcommands = visibleSubs.map((sub) => ({
+		name: sub.name(),
+		description: sub.description(),
+		full_command: `${fullCommand} ${sub.name()}`
+	}));
+	const parts = fullCommand.split(" ");
+	if (parts.length >= 3) {
+		const resource = parts[1];
+		const action = parts[2];
+		if (getAction(`${resource}.${action}`)) meta.api_schema = `recur schema ${resource}.${action}`;
+	}
+	return meta;
+}
+/**
+* Configure Commander.js to output structured JSON when --agent is in argv.
+* Overrides helpInformation() on every command so that --agent suppresses
+* both the main help body and addHelpText('after', ...) output.
+*/
+function configureAgentHelp(program) {
+	if (!process.argv.includes("--agent")) return;
+	function applyRecursive(cmd) {
+		cmd.helpInformation.bind(cmd);
+		cmd.helpInformation = function(contextOptions) {
+			return JSON.stringify(extractCommandMeta(cmd), null, 2) + "\n";
+		};
+		const emitter = cmd;
+		emitter.removeAllListeners("afterHelp");
+		emitter.removeAllListeners("afterAllHelp");
+		for (const sub of cmd.commands) applyRecursive(sub);
+	}
+	applyRecursive(program);
+}
+//#endregion
 //#region src/cli.ts
 const program = new Command();
-program.name("recur").description("Recur CLI — Taiwan subscription payment platform.\nManage products, customers, subscriptions, webhooks, and more.\nAll commands require a Secret Key (sk_test_* or sk_live_*).").version("0.1.4").option("--key <secret-key>", "API secret key (sk_test_* or sk_live_*)").option("--profile <name>", "Use a named profile from ~/.recur/credentials.json").option("--base-url <url>", "API base URL (default: https://api.recur.tw)").option("--output <format>", "Output format: json, table, csv, ndjson (default: json when piped, table otherwise)").hook("preAction", (thisCommand) => {
+program.name("recur").description("Recur CLI — Taiwan subscription payment platform.\nManage products, customers, subscriptions, webhooks, and more.\nAll commands require a Secret Key (sk_test_* or sk_live_*).").version("0.2.0").option("--key <secret-key>", "API secret key (sk_test_* or sk_live_*)").option("--profile <name>", "Use a named profile from ~/.recur/credentials.json").option("--base-url <url>", "API base URL (default: https://api.recur.tw)").option("--output <format>", "Output format: json, table, csv, ndjson (default: json when piped, table otherwise)").hook("preAction", (thisCommand) => {
 	const opts = thisCommand.opts();
 	if (!opts.output) opts.output = process.stdout.isTTY ? "table" : "json";
 	if (![
@@ -2592,7 +2905,7 @@ program.name("recur").description("Recur CLI — Taiwan subscription payment pla
 		console.error(`Error: unsupported output format "${opts.output}". Use json, table, csv, or ndjson.`);
 		process.exit(1);
 	}
-}).option("--fields <fields>", "Comma-separated fields to include (e.g. id,name,price)").option("--dry-run", "Validate locally without making API calls (write commands only)").option("--json <payload>", "Raw JSON request body, maps directly to API (e.g. '{\"name\":\"Pro\"}')");
+}).option("--fields <fields>", "Comma-separated fields to include (e.g. id,name,price)").option("--dry-run", "Validate locally without making API calls (write commands only)").option("--json <payload>", "Raw JSON request body, maps directly to API (e.g. '{\"name\":\"Pro\"}')").option("--agent", "Output help as structured JSON for AI agents (use with --help)");
 program.addHelpText("after", `
 Global options (--output, --fields, --json, --dry-run) work with ALL subcommands.
 
@@ -2620,6 +2933,8 @@ registerInvoicesCommand(program);
 registerCheckoutsCommand(program);
 registerSchemaCommand(program);
 registerMcpCommand(program);
+registerCommandsCommand(program);
+configureAgentHelp(program);
 program.parse();
 //#endregion
 export {};

package/dist/index.mjs

@@ -195,7 +195,8 @@ const TABLE_HIDDEN_FIELDS = new Set([
 	"product_family",
 	"livemode",
 	"created_at",
-	"updated_at"
+	"updated_at",
+	"_hints"
 ]);
 /**
 * Render data in the specified format.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recur-tw/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "CLI for Recur - Taiwan's subscription payment platform",
   "keywords": [
     "recur",
@@ -41,14 +41,6 @@
     "AGENT.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "commander": "^12.1.0",
@@ -57,15 +49,22 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@workspace/core": "workspace:*",
     "tsdown": "^0.21.1",
     "typescript": "^5.7.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "@workspace/core": "0.0.1"
   },
   "engines": {
     "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}