@hardfin/cli 0.0.2-dev.2 → 0.0.2-dev.5

package/dist/cli.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+//#region src/command/registry.ts
+/** ExitCode is what the process returns, and what an agent branches on. */
+const ExitCode = {
+	OK: 0,
+	ERROR: 1,
+	USAGE: 2,
+	NOT_AUTHENTICATED: 4
+};
+/** defineCommand records one command so every surface reads the same declaration. */
+function defineCommand(command) {
+	return command;
+}
+//#endregion
+//#region src/config/settings.ts
+/** The API version this build was written against, sent on every request. */
+const API_VERSION = "2026-09-17";
+const DEFAULT_API_URL = "https://api.hardfin.com/v2";
+/** toApiUrl picks the API this invocation talks to. */
+function toApiUrl(override) {
+	return (override ?? process.env["HARDFIN_API_URL"] ?? DEFAULT_API_URL).replace(/\/+$/, "");
+}
+/** toApiKey reads the API key an unattended caller set. */
+function toApiKey() {
+	return process.env["HARDFIN_API_KEY"] || void 0;
+}
+//#endregion
+//#region src/output/writer.ts
+/** writeData prints a command's result on stdout. */
+function writeData(value) {
+	if (typeof value === "string") {
+		process.stdout.write(value.endsWith("\n") ? value : `${value}\n`);
+		return;
+	}
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** writeFailure prints why a command failed on stderr, as text or as JSON. */
+function writeFailure(message, isJSON, errors, requestId) {
+	if (!isJSON) {
+		process.stderr.write(`error: ${message}\n`);
+		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${entry.error} (${entry.statusCode})\n`);
+		if (requestId) process.stderr.write(`  request ${requestId}\n`);
+		return;
+	}
+	const payload = {
+		errors: errors ?? [{
+			error: message,
+			statusCode: 0
+		}],
+		requestId: requestId ?? null
+	};
+	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+/** isJSONOutput decides whether this invocation prints machine-readable output. */
+function isJSONOutput(flags) {
+	if (flags["json"] === true) return true;
+	return !process.stdout.isTTY;
+}
+/** version is what this build reports, read from the published package manifest. */
+const version = createRequire(import.meta.url)("../package.json").version;
+//#endregion
+//#region src/command/agent-guide.ts
+const agentGuideCommand = defineCommand({
+	name: "agent-guide",
+	summary: "Print instructions an agent can follow to use this CLI",
+	description: "Writes Markdown describing every command, its flags, and its exit codes. Save it as a skill file, an AGENTS.md section, or paste it into a system prompt.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print the command registry as JSON instead of Markdown",
+		schema: z.boolean().optional()
+	}],
+	examples: [{
+		description: "Write a skill file",
+		command: "hardfin agent-guide > SKILL.md"
+	}, {
+		description: "Inspect the registry",
+		command: "hardfin agent-guide --json"
+	}],
+	run: runAgentGuide
+});
+/** toGuide renders the registry as the Markdown an agent reads. */
+function toGuide(commands, version) {
+	const lines = [
+		"# Hardfin CLI",
+		"",
+		`The \`hardfin\` command calls the Hardfin API. This guide describes version ${version} of the CLI, which speaks API version ${API_VERSION}.`,
+		"",
+		"## Before calling",
+		"",
+		"- Authenticate by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
+		"- Every command prints JSON on stdout and diagnostics on stderr",
+		"- Output is JSON whenever stdout is not a terminal, so no flag is needed when calling from code",
+		"",
+		"## Exit codes",
+		"",
+		"| Code | Means |",
+		"| --- | --- |",
+		"| 0 | The command succeeded |",
+		"| 1 | The command failed |",
+		"| 2 | The command was called wrongly |",
+		"| 4 | No usable credential |",
+		"",
+		"## Commands",
+		""
+	];
+	for (const command of commands) {
+		lines.push(`### \`hardfin ${command.name}\``, "", command.description ?? command.summary, "");
+		if (command.arguments.length > 0) {
+			lines.push("| Argument | Required | Holds |", "| --- | --- | --- |");
+			for (const argument of command.arguments) lines.push(`| \`${argument.name}\` | ${argument.required ? "yes" : "no"} | ${argument.description} |`);
+			lines.push("");
+		}
+		if (command.flags.length > 0) {
+			lines.push("| Flag | Takes | Does |", "| --- | --- | --- |");
+			for (const flag of command.flags) {
+				const name = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
+				lines.push(`| \`${name}\` | ${flag.valueName ?? "nothing"} | ${flag.description} |`);
+			}
+			lines.push("");
+		}
+		for (const example of command.examples) lines.push(`${example.description}:`, "", "```sh", example.command, "```", "");
+	}
+	return lines.join("\n");
+}
+async function runAgentGuide(input) {
+	if (input.flags["json"] === true) {
+		writeData(input.commands.map(toSummary));
+		return ExitCode.OK;
+	}
+	writeData(toGuide(input.commands, version));
+	return ExitCode.OK;
+}
+function toSummary(command) {
+	return {
+		name: command.name,
+		summary: command.summary,
+		description: command.description ?? command.summary,
+		arguments: command.arguments,
+		flags: command.flags.map((flag) => ({
+			name: flag.name,
+			short: flag.short ?? null,
+			description: flag.description,
+			valueName: flag.valueName ?? null,
+			repeatable: flag.repeatable ?? false
+		})),
+		examples: command.examples
+	};
+}
+//#endregion
+//#region src/http/client.ts
+/** RequestFailure is a call the API refused, carrying what the envelope said. */
+var RequestFailure = class extends Error {
+	status;
+	errors;
+	requestId;
+	constructor(status, errors, requestId) {
+		super(errors[0]?.error ?? `the request failed with status ${status}`);
+		this.name = "RequestFailure";
+		this.status = status;
+		this.errors = errors;
+		this.requestId = requestId;
+	}
+};
+/** request calls one /v2 endpoint and returns the envelope it answered with. */
+async function request(options) {
+	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
+	if (options.query) url.search = options.query.toString();
+	const headers = {
+		"X-API-Key": options.apiKey,
+		"X-API-Version": API_VERSION,
+		Accept: "application/json"
+	};
+	if (options.body !== void 0) headers["Content-Type"] = "application/json";
+	const response = await fetch(url, {
+		method: options.method,
+		headers,
+		body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+	});
+	const envelope = toEnvelope(await response.text());
+	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
+		error: toStatusMessage(response.status),
+		statusCode: response.status
+	}]);
+	if (!response.ok) {
+		const errors = envelope?.metadata?.errors ?? [];
+		throw new RequestFailure(response.status, errors.length > 0 ? errors : [{
+			error: toStatusMessage(response.status),
+			statusCode: response.status
+		}], envelope?.metadata?.requestId);
+	}
+	return envelope ?? { data: null };
+}
+function toLeadingSlash(path) {
+	return path.startsWith("/") ? path : `/${path}`;
+}
+function toEnvelope(text) {
+	if (text.trim() === "") return;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function toStatusMessage(status) {
+	if (status === 401) return "the credential is missing or is not valid";
+	if (status === 403) return "the organization is deactivated, or its access has ended";
+	return `the request failed with status ${status}`;
+}
+const apiCommand = defineCommand({
+	name: "api",
+	summary: "Call a Hardfin API endpoint and print what it answers",
+	description: "Reaches every endpoint the API publishes. The path is everything after /v2, and the response envelope is printed as it arrived.",
+	arguments: [{
+		name: "path",
+		description: "The endpoint path, such as /customer or /item/item_V1StGXR8Z5jdHi6B",
+		required: true
+	}],
+	flags: [
+		{
+			name: "method",
+			short: "X",
+			description: "The HTTP method to use",
+			valueName: "method",
+			schema: z.enum([
+				"GET",
+				"POST",
+				"PATCH",
+				"PUT",
+				"DELETE"
+			]),
+			defaultValue: "GET"
+		},
+		{
+			name: "field",
+			short: "f",
+			description: "A query parameter as key=value, repeatable",
+			valueName: "key=value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "input",
+			description: "A file holding the JSON request body, or - for stdin",
+			valueName: "file",
+			schema: z.string().optional()
+		},
+		{
+			name: "json",
+			description: "Print machine-readable output, which is the default when stdout is not a terminal",
+			schema: z.boolean().optional()
+		}
+	],
+	examples: [
+		{
+			description: "List customers",
+			command: "hardfin api /customer"
+		},
+		{
+			description: "Take the second page",
+			command: "hardfin api /customer -f page=2 -f limit=50"
+		},
+		{
+			description: "Change an item",
+			command: "hardfin api -X PATCH /item/item_V1StGXR8Z5jdHi6B --input body.json"
+		}
+	],
+	run: runApi
+});
+async function runApi(input) {
+	const apiKey = toApiKey();
+	if (!apiKey) {
+		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
+		return ExitCode.NOT_AUTHENTICATED;
+	}
+	const path = input.args[0];
+	if (!path) {
+		writeFailure("a path is required, such as /customer", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const query = toQuery(input.flags["field"]);
+	if (query === void 0) {
+		writeFailure("each --field is key=value, such as -f limit=50", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let body;
+	if (typeof input.flags["input"] === "string") {
+		body = toBody(input.flags["input"]);
+		if (body === void 0) {
+			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
+			return ExitCode.USAGE;
+		}
+	}
+	try {
+		writeData((await request({
+			apiUrl: toApiUrl(),
+			apiKey,
+			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			path,
+			query,
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof RequestFailure) {
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
+		return ExitCode.ERROR;
+	}
+}
+/** toQuery folds the repeated --field flags into query parameters. */
+function toQuery(fields) {
+	const query = new URLSearchParams();
+	for (const field of Array.isArray(fields) ? fields : []) {
+		const split = field.indexOf("=");
+		if (split < 1) return;
+		query.append(field.slice(0, split), field.slice(split + 1));
+	}
+	return query;
+}
+function toBody(source) {
+	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/command/commands.ts
+/** commands is every command the CLI offers, and drives help and the agent guide. */
+const commands = [apiCommand, agentGuideCommand];
+//#endregion
+//#region src/cli.ts
+const program = new Command();
+program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version, "-v, --version").showHelpAfterError().enablePositionalOptions();
+for (const command of commands) program.addCommand(toProgram(command));
+await program.parseAsync(process.argv);
+/** toProgram wires one registry command into the parser. */
+function toProgram(command) {
+	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
+	for (const argument of command.arguments) {
+		const name = argument.variadic ? `${argument.name}...` : argument.name;
+		program.argument(argument.required ? `<${name}>` : `[${name}]`, argument.description);
+	}
+	for (const flag of command.flags) {
+		const short = flag.short ? `-${flag.short}, ` : "";
+		const value = flag.valueName ? ` <${flag.valueName}>` : "";
+		const option = new Option(`${short}--${flag.name}${value}`, flag.description);
+		if (flag.repeatable) option.argParser(collect);
+		if (flag.defaultValue !== void 0) option.default(flag.defaultValue);
+		program.addOption(option);
+	}
+	for (const example of command.examples) program.addHelpText("after", `\n${example.description}:\n  $ ${example.command}`);
+	program.action(async (...parsed) => {
+		const flags = parsed[parsed.length - 2] ?? {};
+		const args = parsed.slice(0, parsed.length - 2).flatMap(toArgumentList);
+		process.exitCode = await toExitCode(command, args, flags);
+	});
+	return program;
+}
+async function toExitCode(command, args, flags) {
+	const isJSON = isJSONOutput(flags);
+	try {
+		return await command.run({
+			args,
+			flags,
+			isJSON,
+			commands
+		});
+	} catch (error) {
+		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
+		return ExitCode.ERROR;
+	}
+}
+function toArgumentList(value) {
+	if (Array.isArray(value)) return value.map(String);
+	return value === void 0 ? [] : [String(value)];
+}
+function collect(value, previous) {
+	return [...previous ?? [], value];
+}
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.2",
+    "version": "0.0.2-dev.5",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -20,15 +20,33 @@
     ],
     "type": "module",
     "bin": {
-        "hardfin": "bin/hardfin.js"
+        "hardfin": "dist/cli.js"
     },
     "files": [
-        "bin"
+        "dist"
     ],
     "engines": {
         "node": ">=20"
     },
     "publishConfig": {
         "access": "public"
+    },
+    "scripts": {
+        "build": "tsdown",
+        "check-types": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "commander": "^15.0.0",
+        "zod": "^4.6.5"
+    },
+    "devDependencies": {
+        "@types/node": "^22.15.0",
+        "tsdown": "^0.23.0",
+        "typescript": "^5.9.0",
+        "unrun": "^0.3.1",
+        "vitest": "^5.0.1"
     }
 }

package/bin/hardfin.js

@@ -1,27 +0,0 @@
-#!/usr/bin/env node
-// Copyright (c) 2026. Hardfin, Inc. All rights reserved.
-
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
-
-const arg = process.argv[2];
-
-if (arg === "--version" || arg === "-v" || arg === "version") {
-    process.stdout.write(`${version}\n`);
-    process.exit(0);
-}
-
-process.stderr.write(
-    [
-        `hardfin ${version}`,
-        "",
-        "This release is a placeholder that reserves the package name",
-        "No commands are available yet",
-        "",
-        "https://github.com/hardfinhq/hardfin-cli",
-        "",
-    ].join("\n"),
-);
-process.exit(1);