@toggld/js 0.0.0-stage → 0.9.0

package/dist/cli.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import { l as apiUrl, o as decodeSnapshot } from "./wire-CrkBeqnM.mjs";
+import { readFile, writeFile } from "node:fs/promises";
+// src/internal/cli.ts
+/**
+* The `toggld` CLI (ADR-0013). Today it has one command:
+*
+*   toggld pull [--sdk-key <key>] [--api <url>] [--out <path>] [--env-name <name>] [--force]
+*
+* `pull` does exactly what a sync-mode SDK does on bootstrap — `GET
+* /sync/v1/flags` with the SDK key — then writes the validated `FlagSnapshot` to
+* disk as a local flag file (the wire snapshot plus a small provenance
+* envelope). Point a file-mode client at it for offline evaluation.
+*
+* This module is side-effect-free on import: {@link runPull} performs the fetch
+* and write, and {@link runMain} parses argv and prints. The executable entry
+* (`../cli.ts`) is a one-line wrapper. Keeping the logic here lets tests call it
+* directly instead of spawning a process.
+*/
+const SCHEMA_URL = "https://toggld.dev/schema/local-flags.v1.json";
+const DEFAULT_OUT = "./toggld.flags.json";
+/** Hosted Toggld. To go through a proxy, pass `--api` or set `TOGGLD_API_URL`. */
+const DEFAULT_ENDPOINT = "https://api.toggld.io";
+/** A user-facing failure: printed as a clean message, never a stack trace. */
+var CliError = class extends Error {
+	/** An optional follow-up line with remediation guidance. */
+	hint;
+	constructor(message, hint) {
+		super(message);
+		this.name = "CliError";
+		this.hint = hint;
+	}
+};
+const normalizeEndpoint = (endpoint) => endpoint.replace(/\/+$/, "");
+/** The version already on disk at `out`, if it is a readable local flag file. */
+const existingVersion = async (out) => {
+	try {
+		const parsed = JSON.parse(await readFile(out, "utf8"));
+		return typeof parsed.version === "string" ? parsed.version : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* Fetch the environment's current snapshot for `sdkKey` and write it to `out` as
+* a local flag file. Idempotent: an unchanged version is a no-op unless `force`.
+*/
+const runPull = async (options) => {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const endpoint = normalizeEndpoint(options.endpoint);
+	let url;
+	try {
+		url = apiUrl(options.endpoint, "/sync/v1/flags").toString();
+	} catch {
+		url = `${endpoint}/sync/v1/flags`;
+	}
+	let response;
+	try {
+		response = await fetchImpl(url, { headers: {
+			authorization: `Bearer ${options.sdkKey}`,
+			accept: "application/json"
+		} });
+	} catch (error) {
+		throw new CliError(`Could not reach the flag API at ${endpoint}: ${describe(error)}`, "Check --api / TOGGLD_API_URL and that the server is running.");
+	}
+	if (response.status === 401) throw new CliError("The flag API rejected the SDK key (401 Unauthorized).", "Check the key.");
+	if (response.status === 403) throw new CliError("This key cannot read flag definitions (403 Forbidden).", "`pull` needs a secret SDK key (ffk_…); public browser tokens (ffp_…) can't read definitions.");
+	if (!response.ok) throw new CliError(`The flag API returned ${response.status} ${response.statusText}.`);
+	const body = await response.json().catch(() => {
+		throw new CliError("The flag API response was not valid JSON.");
+	});
+	let snapshot;
+	try {
+		snapshot = decodeSnapshot(body);
+	} catch {
+		throw new CliError("The flag API response did not match the expected snapshot format.");
+	}
+	if (!options.force && await existingVersion(options.out) === snapshot.version) return {
+		out: options.out,
+		version: snapshot.version,
+		flagCount: snapshot.flags.length,
+		segmentCount: snapshot.segments?.length ?? 0,
+		unchanged: true
+	};
+	const envelope = {
+		$schema: SCHEMA_URL,
+		toggld: {
+			...options.envName ? { environment: options.envName } : {},
+			apiBase: endpoint,
+			generatedAt: now(),
+			generatedBy: "toggld pull"
+		},
+		version: snapshot.version,
+		flags: snapshot.flags,
+		...snapshot.segments ? { segments: snapshot.segments } : {}
+	};
+	await writeFile(options.out, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+	return {
+		out: options.out,
+		version: snapshot.version,
+		flagCount: snapshot.flags.length,
+		segmentCount: snapshot.segments?.length ?? 0,
+		unchanged: false
+	};
+};
+const describe = (e) => typeof e === "object" && e !== null && "message" in e && typeof e.message === "string" ? e.message : String(e);
+const USAGE = `toggld — Toggld feature-flag CLI
+
+Usage:
+  toggld pull [options]      Fetch an environment's flags into a local file
+
+Options for "pull":
+  -k, --sdk-key <key>   Secret SDK key (ffk_…). Falls back to TOGGLD_SDK_KEY,
+                        then prompts. Required.
+  -a, --api <url>       Flag API base URL. Falls back to TOGGLD_API_URL
+                        (or the older TOGGLD_FLAG_API_URL), then
+                        ${DEFAULT_ENDPOINT}.
+  -o, --out <path>      Output file. Default ${DEFAULT_OUT}.
+      --env-name <name> Label recorded in the file's provenance envelope.
+  -f, --force           Rewrite even if the file already has this version.
+  -h, --help            Show this help.
+
+Evaluate from the file with { mode: "file", file: "<path>" }, or set
+TOGGLD_FLAGS_FILE to redirect any client to it.`;
+const BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+	"force",
+	"f",
+	"help",
+	"h"
+]);
+const ALIASES = {
+	k: "sdk-key",
+	a: "api",
+	o: "out",
+	f: "force",
+	h: "help"
+};
+const parseArgs = (argv) => {
+	const flags = {};
+	let command;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (!arg.startsWith("-")) {
+			command ??= arg;
+			continue;
+		}
+		const eq = arg.indexOf("=");
+		const rawName = (eq === -1 ? arg : arg.slice(0, eq)).replace(/^-+/, "");
+		const name = ALIASES[rawName] ?? rawName;
+		const canonical = ALIASES[rawName] ?? rawName;
+		if (BOOLEAN_FLAGS.has(rawName) || BOOLEAN_FLAGS.has(canonical)) {
+			flags[name] = true;
+			continue;
+		}
+		if (eq !== -1) flags[name] = arg.slice(eq + 1);
+		else flags[name] = argv[++i] ?? "";
+	}
+	return {
+		command,
+		flags
+	};
+};
+/** Read a secret without echoing it, from an interactive terminal. */
+const promptSecret = async (label) => {
+	if (!process.stdin.isTTY) throw new CliError("No SDK key provided.", "Pass --sdk-key, set TOGGLD_SDK_KEY, or run in an interactive terminal.");
+	const { createInterface } = await import("node:readline");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		terminal: true
+	});
+	const internals = rl;
+	const write = internals.output.write.bind(internals.output);
+	let muted = false;
+	internals._writeToOutput = (s) => {
+		if (!muted || s.includes(label)) write(s);
+	};
+	try {
+		const answer = await new Promise((resolve) => {
+			rl.question(label, resolve);
+			muted = true;
+		});
+		write("\n");
+		return answer.trim();
+	} finally {
+		rl.close();
+	}
+};
+/**
+* Parse argv, run the requested command, and return a process exit code. Prints
+* results to stdout and {@link CliError}s to stderr; unexpected errors rethrow.
+*/
+const runMain = async (argv) => {
+	const { command, flags } = parseArgs(argv);
+	if (flags["help"] || command === void 0 || command === "help") {
+		process.stdout.write(`${USAGE}\n`);
+		return command === void 0 && !flags["help"] ? 1 : 0;
+	}
+	if (command !== "pull") {
+		process.stderr.write(`Unknown command "${command}".\n\n${USAGE}\n`);
+		return 1;
+	}
+	try {
+		const endpoint = asString(flags["api"]) ?? (process.env.TOGGLD_API_URL || void 0) ?? (process.env.TOGGLD_FLAG_API_URL || void 0) ?? DEFAULT_ENDPOINT;
+		const out = asString(flags["out"]) ?? DEFAULT_OUT;
+		const envName = asString(flags["env-name"]);
+		const sdkKey = asString(flags["sdk-key"]) ?? (process.env.TOGGLD_SDK_KEY || void 0) ?? await promptSecret("Toggld SDK key: ");
+		if (!sdkKey) throw new CliError("No SDK key provided.");
+		const result = await runPull({
+			sdkKey,
+			endpoint,
+			out,
+			force: Boolean(flags["force"]),
+			...envName ? { envName } : {}
+		});
+		if (result.unchanged) process.stdout.write(`✓ ${result.out} already up to date (version ${short(result.version)}).\n`);
+		else {
+			const segs = result.segmentCount > 0 ? `, ${result.segmentCount} segments` : "";
+			process.stdout.write(`✓ Wrote ${result.out} — ${result.flagCount} flags${segs} (version ${short(result.version)}).\n`);
+		}
+		return 0;
+	} catch (error) {
+		if (error instanceof CliError) {
+			process.stderr.write(`✗ ${error.message}\n`);
+			if (error.hint) process.stderr.write(`  ${error.hint}\n`);
+			return 1;
+		}
+		throw error;
+	}
+};
+const asString = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
+const short = (version) => version.length > 12 ? `${version.slice(0, 12)}…` : version;
+// src/cli.ts
+/**
+* The `toggld` executable. All logic lives in `./internal/cli.ts` (so tests can
+* call it without spawning a process); this is just the entry that runs it.
+*/
+runMain(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+	console.error(error);
+	process.exit(1);
+});
+export {};