@hardfin/cli 0.0.2-dev.6 → 0.0.2-dev.7

package/README.md

@@ -85,6 +85,54 @@ npm run generate-surface -- ../api-spec/reference/core.openapi.yaml
 The document is bundled, meaning its external files are inlined, but `$ref` pointers within
 it remain. The generator follows those pointers itself.
 
+## Local configuration
+
+A local build reaches a local server without editing code. Four layers supply the same
+settings, and the one nearest the top wins.
+
+| Layer | Where | Beats |
+| --- | --- | --- |
+| Flag | `--api-url` | everything below |
+| Environment | an exported `HARDFIN_*` variable | the files below |
+| Env file | `.env` in the working directory, or the file `HARDFIN_ENV_FILE` names | the config file |
+| Config file | `config.local.json` in the working directory | the defaults |
+| Default | the published API | nothing |
+
+An exported variable beats `.env` because Node leaves a variable that is already set alone.
+
+### What a local build writes
+
+```json
+{
+    "apiUrl": "http://localhost:8080/v2",
+    "auth": { "tokenUrl": "http://localhost:9000/oauth/token" }
+}
+```
+
+The authentication endpoints follow `apiUrl`, so pointing at a local server moves the whole
+flow. Name one under `auth` to move only that one. The keys are `apiUrl`, `apiKey`,
+`clientId`, and `auth` holding `authorizeUrl`, `tokenUrl`, `deviceUrl`, and `revokeUrl`.
+
+A key the file does not define fails the command with exit code 2. A typo that was silently
+ignored would look like a setting that never applied.
+
+`config.local.json` and `.env` are both gitignored.
+
+### Seeing what won
+
+```sh
+hardfin config
+```
+
+It prints each setting, its value, and the layer that supplied it. The API key is reported
+as set or not set, never printed.
+
+### Both files are read from the working directory
+
+The CLI reads whatever `config.local.json` and `.env` sit in the directory you run it from.
+A directory you do not control can therefore point the CLI at a server you do not expect, so
+run `hardfin config` when a command reaches somewhere surprising.
+
 ## Releasing
 
 This section is for anyone who merges a pull request in this repository. It tells you where

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { createRequire } from "node:module";
 import { Command, Option } from "commander";
 import { z } from "zod";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
 const ExitCode = {
@@ -19,14 +20,93 @@ function defineCommand(command) {
 //#region src/config/settings.ts
 /** The API version this build was written against, sent on every request. */
 const API_VERSION = "2026-09-17";
+/** The file a local build reads its overrides from, in the working directory. */
+const CONFIG_FILE = "config.local.json";
 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(/\/+$/, "");
+const DEFAULT_ENV_FILE = ".env";
+const FileSettings = z.strictObject({
+	apiUrl: z.string().optional(),
+	apiKey: z.string().optional(),
+	clientId: z.string().optional(),
+	auth: z.strictObject({
+		authorizeUrl: z.string().optional(),
+		tokenUrl: z.string().optional(),
+		deviceUrl: z.string().optional(),
+		revokeUrl: z.string().optional()
+	}).optional()
+});
+/** ConfigFailure is a config file that cannot be read or does not match the schema. */
+var ConfigFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigFailure";
+	}
+};
+/** toSettings resolves what this invocation talks to, and where each value came from. */
+function toSettings(flags = {}, directory = process.cwd()) {
+	const fromEnvFile = loadEnvFile(directory);
+	const file = toFileSettings(directory);
+	const sources = {};
+	const pick = (key, flag, variable, fromFile, fallback) => {
+		const [value, source] = toLayer(flag, process.env[variable], fromEnvFile.has(variable), fromFile, fallback);
+		sources[key] = source;
+		return value;
+	};
+	const apiUrl = toTrimmedUrl(pick("apiUrl", flags.apiUrl, "HARDFIN_API_URL", file.apiUrl, DEFAULT_API_URL) ?? DEFAULT_API_URL);
+	return {
+		settings: {
+			apiUrl,
+			apiKey: pick("apiKey", flags.apiKey, "HARDFIN_API_KEY", file.apiKey),
+			clientId: pick("clientId", flags.clientId, "HARDFIN_CLIENT_ID", file.clientId),
+			authorizeUrl: pick("authorizeUrl", flags.authorizeUrl, "HARDFIN_AUTHORIZE_URL", file.auth?.authorizeUrl, `${apiUrl}/auth/authorize`) ?? "",
+			tokenUrl: pick("tokenUrl", flags.tokenUrl, "HARDFIN_TOKEN_URL", file.auth?.tokenUrl, `${apiUrl}/auth/token`) ?? "",
+			deviceUrl: pick("deviceUrl", flags.deviceUrl, "HARDFIN_DEVICE_URL", file.auth?.deviceUrl, `${apiUrl}/auth/device`) ?? "",
+			revokeUrl: pick("revokeUrl", flags.revokeUrl, "HARDFIN_REVOKE_URL", file.auth?.revokeUrl, `${apiUrl}/auth/revoke`) ?? ""
+		},
+		sources
+	};
+}
+function toLayer(flag, environment, isFromEnvFile, file, fallback) {
+	if (flag) return [flag, "flag"];
+	if (environment) return [environment, isFromEnvFile ? "env file" : "environment"];
+	if (file) return [file, "config file"];
+	return [fallback, "default"];
+}
+/** toFileSettings reads the local override file, which a local build is expected to have. */
+function toFileSettings(directory) {
+	const path = resolve(directory, CONFIG_FILE);
+	if (!existsSync(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new ConfigFailure(`${CONFIG_FILE} does not hold JSON`);
+	}
+	const result = FileSettings.safeParse(parsed);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		throw new ConfigFailure(`${CONFIG_FILE} is not valid: ${issue?.path.join(".") || "root"} ${issue?.message ?? ""}`.trim());
+	}
+	return result.data;
+}
+/**
+* loadEnvFile reads a .env beside the command, so a local build needs no exports, and
+* answers which variables it supplied. Node leaves an exported variable alone, so a
+* shell export still wins over the file.
+*/
+function loadEnvFile(directory) {
+	const path = process.env["HARDFIN_ENV_FILE"] ?? resolve(directory, DEFAULT_ENV_FILE);
+	if (!existsSync(path)) return /* @__PURE__ */ new Set();
+	const before = new Set(Object.keys(process.env));
+	try {
+		process.loadEnvFile(path);
+	} catch {
+		throw new ConfigFailure(`${path} cannot be read as an env file`);
+	}
+	return new Set(Object.keys(process.env).filter((name) => !before.has(name)));
 }
-/** toApiKey reads the API key an unattended caller set. */
-function toApiKey() {
-	return process.env["HARDFIN_API_KEY"] || void 0;
+function toTrimmedUrl(url) {
+	return url.replace(/\/+$/, "");
 }
 //#endregion
 //#region src/output/writer.ts
@@ -272,7 +352,7 @@ const apiCommand = defineCommand({
 	run: runApi
 });
 async function runApi(input) {
-	const apiKey = toApiKey();
+	const apiKey = input.resolved.settings.apiKey;
 	if (!apiKey) {
 		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
 		return ExitCode.NOT_AUTHENTICATED;
@@ -297,7 +377,7 @@ async function runApi(input) {
 	}
 	try {
 		writeData((await request({
-			apiUrl: toApiUrl(),
+			apiUrl: input.resolved.settings.apiUrl,
 			apiKey,
 			method: String(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
@@ -333,6 +413,56 @@ function toBody$1(source) {
 	}
 }
 //#endregion
+//#region src/command/config.ts
+const configCommand = defineCommand({
+	name: "config",
+	summary: "Print what this invocation talks to, and where each value came from",
+	description: `Resolves the API and authentication endpoints from the flags, the environment, a .env file, and ${CONFIG_FILE} in the working directory. Use it when a local build reaches the wrong server.`,
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "See what a local build is pointed at",
+		command: "hardfin config"
+	}, {
+		description: "Read one value from a script",
+		command: "hardfin config --json | jq -r .apiUrl"
+	}],
+	run: runConfig
+});
+/** toReport pairs each setting with the layer that supplied it. */
+function toReport(resolved) {
+	const report = { apiVersion: API_VERSION };
+	for (const [key, value] of Object.entries(resolved.settings)) {
+		const source = resolved.sources[key];
+		report[key] = key === "apiKey" ? {
+			set: value !== void 0,
+			from: source
+		} : {
+			value: value ?? null,
+			from: source
+		};
+	}
+	return report;
+}
+async function runConfig(input) {
+	const report = toReport(input.resolved);
+	if (input.isJSON) {
+		writeData(report);
+		return ExitCode.OK;
+	}
+	writeData(Object.entries(report).map(([key, entry]) => {
+		if (typeof entry !== "object" || entry === null) return `${key.padEnd(14)} ${String(entry)}`;
+		const holder = entry;
+		const shown = holder.value ?? (holder.set ? "set" : "not set");
+		return `${key.padEnd(14)} ${shown}  (${holder.from})`;
+	}).join("\n"));
+	return ExitCode.OK;
+}
+//#endregion
 //#region src/command/operation.ts
 const INPUT_FLAG = {
 	name: "input",
@@ -360,7 +490,7 @@ function defineOperation(operation) {
 	};
 }
 async function runOperation(operation, input) {
-	const apiKey = toApiKey();
+	const apiKey = input.resolved.settings.apiKey;
 	if (!apiKey) {
 		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
 		return ExitCode.NOT_AUTHENTICATED;
@@ -380,7 +510,7 @@ async function runOperation(operation, input) {
 	}
 	try {
 		writeData((await request({
-			apiUrl: toApiUrl(),
+			apiUrl: input.resolved.settings.apiUrl,
 			apiKey,
 			method: operation.method,
 			path,
@@ -1479,6 +1609,7 @@ const commands = [
 		}
 	],
 	apiCommand,
+	configCommand,
 	agentGuideCommand
 ];
 //#endregion
@@ -1494,7 +1625,7 @@ function toRejectedFlag(command, flags) {
 //#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();
+program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version, "-v, --version").option("--api-url <url>", "The API to call, which also moves the authentication endpoints").showHelpAfterError().enablePositionalOptions();
 for (const command of commands) program.addCommand(toProgram(command));
 await program.parseAsync(process.argv);
 /** toProgram wires one registry command into the parser. */
@@ -1530,15 +1661,17 @@ async function toExitCode(command, args, flags) {
 		return ExitCode.USAGE;
 	}
 	try {
+		const resolved = toSettings({ apiUrl: program.opts()["apiUrl"] });
 		return await command.run?.({
 			args,
 			flags,
 			isJSON,
-			commands
+			commands,
+			resolved
 		}) ?? ExitCode.OK;
 	} catch (error) {
 		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
-		return ExitCode.ERROR;
+		return error instanceof ConfigFailure ? ExitCode.USAGE : ExitCode.ERROR;
 	}
 }
 function toArgumentList(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.6",
+    "version": "0.0.2-dev.7",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",