@fluid-app/fluid-cli 0.1.35 → 0.1.37

package/README.md

@@ -50,13 +50,61 @@ Plugins are auto-discovered from:
 2. `node_modules/@fluid-app/` where the CLI itself is installed (global installs)
 3. Sibling packages in a pnpm workspace (monorepo development)
 
+## Discovering commands
+
+```bash
+fluid commands                 # every installed command, one line each
+fluid commands domains         # only `fluid domains` and its subcommands
+fluid commands --json          # the full catalog, for agents and doc generators
+```
+
+The JSON catalog lists every command with its arguments, flags (and the
+parent commands whose flags it also accepts), whether it changes data, and
+the API endpoints it calls. `writes` is `true` or `false` when the plugin
+declares it or the command confirms with `--yes`, and `null` when unknown.
+`endpoints` is `null` until a plugin declares them: unknown, not "calls no
+API". Plugins declare endpoints with `describeCommand`:
+
+```ts
+import { describeCommand } from "@fluid-app/fluid-cli";
+
+describeCommand(parent.command("status <domain>"), {
+  endpoints: [{ method: "GET", path: "/api/domains/{id}" }],
+  writes: false,
+});
+```
+
+## Shell completion
+
+```bash
+echo 'eval "$(fluid completion bash)"' >> ~/.bashrc
+fluid completion zsh > "${fpath[1]}/_fluid"
+fluid completion fish > ~/.config/fish/completions/fluid.fish
+```
+
+Completion asks the installed CLI on each tab, so new plugins complete
+without reinstalling the script. It completes commands, aliases, flags and
+values that have a fixed set of choices. The scripts pipe the typed words to
+the CLI on stdin rather than as arguments, so a typed `--token` never shows
+in the process list.
+
+## Updates
+
+Once a day an interactive run starts a detached background check of npm for
+a newer `@fluid-app/fluid-cli`; no command waits on it. When the last check
+found one, a short notice prints on stderr after the command finishes.
+A failed check is retried the next day. It never runs in CI, when output is piped, or for a
+workspace build. Set `FLUID_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`)
+to turn it off.
+
 ## Environment Variables
 
-| Variable           | Description                                      |
-| ------------------ | ------------------------------------------------ |
-| `FLUID_TOKEN`      | API token (alternative to `fluid login`)         |
-| `FLUID_API_BASE`   | API base URL (default: `https://api.fluid.app`)  |
-| `FLUID_CONFIG_DIR` | Override config directory (default: `~/.fluid/`) |
+| Variable                | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `FLUID_TOKEN`           | API token (alternative to `fluid login`)         |
+| `FLUID_API_BASE`        | API base URL (default: `https://api.fluid.app`)  |
+| `FLUID_CONFIG_DIR`      | Override config directory (default: `~/.fluid/`) |
+| `FLUID_NO_UPDATE_CHECK` | Turn off the daily update notice                 |
 
 ## Development
 

package/dist/bin/fluid.mjs

@@ -1,13 +1,249 @@
 #!/usr/bin/env node
-import { _ as validateToken, a as readConfig, c as getConfigDir, d as FLUID_API_ERROR, f as confirmMfa, g as switchCompany, h as sendMfa, m as getFluidApiBase, n as getAuthToken, o as updateConfig, p as fetchUserCompanies, s as writeConfig, t as getActiveProfile } from "../token--hQqx3DU.mjs";
+import { F as walkCommands, M as rootCommand, N as visibleOptions, P as visibleSubcommands, _ as validateToken, a as readConfig, c as getConfigDir, d as FLUID_API_ERROR, f as confirmMfa, g as switchCompany, h as sendMfa, j as filterCatalog, m as getFluidApiBase, n as getAuthToken, o as updateConfig, p as fetchUserCompanies, s as writeConfig, t as getActiveProfile } from "../token-6SEVoGMw.mjs";
 import { createRequire } from "node:module";
-import { Command } from "commander";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Argument, Command, Option } from "commander";
 import chalk from "chalk";
 import prompts from "prompts";
 import ora from "ora";
-import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+//#region src/commands/commands.ts
+/**
+* fluid commands — list every installed command, or print the catalog as
+* JSON for agents and documentation generators.
+*/
+const { version: version$1 } = createRequire(import.meta.url)("../../package.json");
+function usage(entry) {
+	const args = entry.arguments.map((arg) => {
+		const name = arg.variadic ? `${arg.name}...` : arg.name;
+		return arg.required ? `<${name}>` : `[${name}]`;
+	});
+	return [entry.command, ...args].join(" ");
+}
+function formatCatalogText(entries) {
+	const runnable = entries.filter((entry) => entry.runnable);
+	const width = Math.min(48, Math.max(0, ...runnable.map((entry) => usage(entry).length)));
+	return runnable.map((entry) => {
+		const line = usage(entry);
+		const summary = entry.description.split("\n", 1)[0] ?? "";
+		return summary ? `${line.padEnd(width)}  ${summary}` : line;
+	}).join("\n");
+}
+const commandsCommand = new Command("commands").description("List installed commands; --json prints the full catalog").argument("[prefix...]", "Only list commands under this one, e.g. `domains`").option("--json", "Print the catalog as JSON", false).action((prefix, opts, command) => {
+	const root = rootCommand(command);
+	const entries = filterCatalog(walkCommands(root), root, prefix);
+	if (entries.length === 0) {
+		process.stderr.write(JSON.stringify({ error: `No command named "${prefix.join(" ")}".` }) + "\n");
+		process.exitCode = 1;
+		return;
+	}
+	if (opts.json) {
+		process.stdout.write(JSON.stringify({
+			cli: root.name(),
+			version: version$1,
+			commands: entries
+		}, null, 2) + "\n");
+		return;
+	}
+	process.stdout.write(formatCatalogText(entries) + "\n");
+});
+//#endregion
+//#region src/completion/complete.ts
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+function findOption(chain, word) {
+	const flag = word.split("=", 1)[0] ?? word;
+	for (const command of [...chain].reverse()) {
+		const match = command.options.find((option) => option.long === flag || option.short === flag);
+		if (match) return match;
+	}
+	return null;
+}
+function splitAssignment(word) {
+	const at = word.indexOf("=");
+	return [word.slice(0, at), word.slice(at + 1)];
+}
+function choicesFor(option, typed) {
+	return (option.argChoices ?? []).filter((choice) => choice.startsWith(typed)).map((choice) => ({
+		value: choice,
+		description: ""
+	}));
+}
+function findSubcommand(command, word) {
+	return visibleSubcommands(command).find((sub) => sub.name() === word || sub.aliases().includes(word)) ?? null;
+}
+/**
+* Complete the last of `words`, the words after the program name.
+* Where a flag's value is expected, offers the flag's choices if it has
+* any; otherwise returns nothing so the shell falls back to files.
+*/
+function completeWords(root, words) {
+	const partial = words.at(-1) ?? "";
+	const chain = [root];
+	let current = root;
+	let awaitingValue = null;
+	let operandsOnly = false;
+	let operands = 0;
+	const prior = words.slice(0, -1);
+	for (const [index, word] of prior.entries()) {
+		if (awaitingValue) {
+			if (word !== "=" || prior[index - 1] === "=") awaitingValue = null;
+			continue;
+		}
+		if (!operandsOnly && word === "--") {
+			operandsOnly = true;
+			continue;
+		}
+		if (!operandsOnly && word.startsWith("-")) {
+			const option = findOption(chain, word);
+			awaitingValue = option?.required && !word.includes("=") ? option : null;
+			continue;
+		}
+		const sub = operands === 0 ? findSubcommand(current, word) : null;
+		if (sub) {
+			current = sub;
+			chain.push(sub);
+		} else operands += 1;
+	}
+	if (awaitingValue) return choicesFor(awaitingValue, partial === "=" ? "" : partial);
+	if (!operandsOnly && partial.startsWith("--") && partial.includes("=")) {
+		const [flag = "", typed = ""] = splitAssignment(partial);
+		const option = findOption(chain, flag);
+		if (!option?.required && !option?.optional) return [];
+		return choicesFor(option, typed).map((choice) => ({
+			...choice,
+			value: `${flag}=${choice.value}`
+		}));
+	}
+	if (!operandsOnly && partial.startsWith("-")) {
+		const seen = /* @__PURE__ */ new Set();
+		const candidates = [];
+		for (const command of [...chain].reverse()) for (const option of visibleOptions(command)) {
+			if (option.long === "--version" && command !== current) continue;
+			for (const value of [option.long, option.short]) {
+				if (!value || seen.has(value)) continue;
+				seen.add(value);
+				candidates.push({
+					value,
+					description: option.description
+				});
+			}
+		}
+		candidates.push({
+			value: "--help",
+			description: "Show help"
+		});
+		return candidates.filter((c) => c.value.startsWith(partial));
+	}
+	const candidates = [];
+	if (operands === 0) for (const sub of visibleSubcommands(current)) for (const name of [sub.name(), ...sub.aliases()]) candidates.push({
+		value: name,
+		description: sub.description()
+	});
+	const args = current.registeredArguments;
+	const last = args.at(-1);
+	const argument = args[operands] ?? (last?.variadic ? last : void 0);
+	for (const choice of argument?.argChoices ?? []) candidates.push({
+		value: choice,
+		description: argument?.description ?? ""
+	});
+	return candidates.filter((c) => c.value.startsWith(partial));
+}
+/**
+* The words the scripts pipe in: each followed by a NUL, the program name
+* first. Returns the words after the program name, at least one.
+*/
+function parseCompletionInput(input) {
+	const words = input.split("\0");
+	words.pop();
+	const typed = words.slice(1);
+	return typed.length > 0 ? typed : [""];
+}
+function firstLine(text) {
+	return text.split("\n", 1)[0]?.trim() ?? "";
+}
+/** One candidate per line, in the shape each shell's script reads. */
+function formatCandidates(candidates, shell) {
+	const lines = candidates.map(({ value, description }) => {
+		const summary = firstLine(description);
+		switch (shell) {
+			case "bash": return value;
+			case "zsh": return summary ? `${value.replaceAll(":", "\\:")}:${summary}` : value.replaceAll(":", "\\:");
+			case "fish": return summary ? `${value}\t${summary}` : value;
+		}
+	});
+	return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+function completionScript(shell) {
+	switch (shell) {
+		case "bash": return `# fluid bash completion
+_fluid_complete() {
+  local -a words
+  local i
+  for ((i = 0; i <= COMP_CWORD; i++)); do words+=("\${COMP_WORDS[i]}"); done
+  local IFS=$'\\n'
+  COMPREPLY=($(printf '%s\\0' "\${words[@]}" | fluid __complete --shell bash 2>/dev/null))
+}
+complete -o default -F _fluid_complete fluid
+`;
+		case "zsh": return `#compdef fluid
+# fluid zsh completion
+_fluid() {
+  local -a candidates
+  candidates=("\${(@f)$(printf '%s\\0' "\${(@)words[1,CURRENT]}" | fluid __complete --shell zsh 2>/dev/null)}")
+  candidates=(\${candidates:#})
+  if (( \${#candidates} )); then
+    _describe -t fluid 'fluid' candidates
+  else
+    _files
+  fi
+}
+if [[ \${zsh_eval_context[-1]} == loadautofunc ]]; then
+  _fluid "$@"
+else
+  compdef _fluid fluid
+fi
+`;
+		case "fish": return `# fluid fish completion
+function __fluid_complete
+    set -l current (commandline -ct)
+    set -l candidates (string join0 -- (commandline -opc) "$current" | fluid __complete --shell fish 2>/dev/null)
+    if set -q candidates[1]
+        printf '%s\\n' $candidates
+    else
+        __fish_complete_path "$current"
+    end
+end
+complete -c fluid -f -a '(__fluid_complete)'
+`;
+	}
+}
+//#endregion
+//#region src/commands/completion.ts
+/**
+* fluid completion <shell> — print a shell completion script.
+* fluid __complete — the hidden command that script pipes the typed words
+* into on each tab.
+*/
+const completionCommand = new Command("completion").description("Print a shell completion script for bash, zsh or fish").addArgument(new Argument("<shell>", "Shell to complete in").choices(SHELLS)).addHelpText("after", `
+Install:
+  bash  echo 'eval "$(fluid completion bash)"' >> ~/.bashrc
+  zsh   fluid completion zsh > "\${fpath[1]}/_fluid"   (or eval "$(fluid completion zsh)" in ~/.zshrc)
+  fish  fluid completion fish > ~/.config/fish/completions/fluid.fish
+`).action((shell) => {
+	process.stdout.write(completionScript(shell));
+});
+const completeCommand = new Command("__complete").description("Print completions for the words typed so far").addOption(new Option("--shell <shell>", "Output format").choices(SHELLS).default("bash")).action((opts, command) => {
+	const typed = parseCompletionInput(readFileSync(0, "utf8"));
+	process.stdout.write(formatCandidates(completeWords(rootCommand(command), typed), opts.shell));
+});
+//#endregion
 //#region src/auth/profiles.ts
 function createFluidProfile({ name, token, companyName, baseUrl, storedAt }) {
 	return {
@@ -653,8 +889,232 @@ async function loadPlugins(program, basePath) {
 	}
 }
 //#endregion
+//#region src/update/notifier.ts
+/**
+* Tell an interactive user, at most once a day, that a newer fluid CLI is
+* on npm. The check never holds a command open: a run prints what the last
+* check found, and a stale cache is refreshed by a detached child process
+* for next time.
+*/
+const PACKAGE_NAME = "@fluid-app/fluid-cli";
+/** The argument the CLI entry point treats as "refresh the cache and exit". */
+const REFRESH_ARG = "__refresh-update-check";
+const FETCH_TIMEOUT_MS = 5e3;
+const CACHE_FILE = "update-check.json";
+/** Whether an Electron app, such as Mist, is running the CLI it bundles. */
+function isElectronRun(env, versions = {}) {
+	return Boolean(env["ELECTRON_RUN_AS_NODE"] || versions["electron"]);
+}
+/**
+* Only an installed CLI used by a person checks. Scripts, CI, piped output
+* (completion and `--json` among them), a workspace build and a copy an
+* Electron app bundles (the app updates it) stay quiet.
+*/
+function shouldCheckForUpdates({ env, stdoutIsTTY, stderrIsTTY, entryPath, versions }) {
+	if (env["FLUID_NO_UPDATE_CHECK"] || env["NO_UPDATE_NOTIFIER"]) return false;
+	if (env["CI"]) return false;
+	if (isElectronRun(env, versions)) return false;
+	if (!stdoutIsTTY || !stderrIsTTY) return false;
+	return entryPath.includes(`${sep}node_modules${sep}`);
+}
+function parseVersion(version) {
+	const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+	if (!match) return null;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+}
+/** True when `latest` is a newer release than `current`. Prereleases never count. */
+function isNewer(current, latest) {
+	const a = parseVersion(current);
+	const b = parseVersion(latest);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i += 1) if (b[i] !== a[i]) return b[i] > a[i];
+	return false;
+}
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"],
+	["npm-shrinkwrap.json", "npm"]
+];
+function projectManager(projectDir, exists) {
+	for (let dir = projectDir;; dir = dirname(dir)) {
+		for (const [file, manager] of LOCKFILES) {
+			if (!exists(join(dir, file))) continue;
+			if (manager !== "yarn") return manager;
+			return exists(join(dir, ".yarnrc.yml")) ? "yarn" : "yarn-classic";
+		}
+		if (dirname(dir) === dir) return "npm";
+	}
+}
+/**
+* Work out from the entry point's real path how the CLI was installed: an
+* npx cache run, a global install (npm's `lib/node_modules`, or npm on
+* Windows, pnpm's and yarn's global directories), or else a project's own
+* `node_modules`.
+*/
+function detectInstallKind(entryPath, exists = existsSync) {
+	const path = entryPath.replaceAll("\\", "/");
+	if (path.includes("/_npx/")) return { kind: "npx" };
+	if (/\/pnpm\/global\//i.test(path)) return {
+		kind: "global",
+		manager: "pnpm"
+	};
+	if (/\/yarn\/global\//i.test(path) || path.includes("/.yarn-global/")) return {
+		kind: "global",
+		manager: "yarn-classic"
+	};
+	if (/\/\.bun\/install\/global\//.test(path)) return {
+		kind: "global",
+		manager: "bun"
+	};
+	const modules = path.indexOf("/node_modules/");
+	const before = modules === -1 ? path : path.slice(0, modules);
+	const projectDir = entryPath.slice(0, modules === -1 ? 0 : modules);
+	if ((before.endsWith("/lib") || /\/npm$/i.test(before)) && !exists(join(projectDir, "package.json"))) return {
+		kind: "global",
+		manager: "npm"
+	};
+	return {
+		kind: "local",
+		manager: projectManager(projectDir, exists),
+		projectDir
+	};
+}
+const PLUGINS_NOTE = "(and any @fluid-app/fluid-cli-* plugins you use)";
+function globalCommand(manager) {
+	switch (manager) {
+		case "npm": return `npm install -g ${PACKAGE_NAME}`;
+		case "pnpm": return `pnpm add -g ${PACKAGE_NAME}@latest`;
+		case "yarn":
+		case "yarn-classic": return `yarn global add ${PACKAGE_NAME}@latest`;
+		case "bun": return `bun add -g ${PACKAGE_NAME}@latest`;
+	}
+}
+function localCommand(manager) {
+	switch (manager) {
+		case "npm": return `npm install ${PACKAGE_NAME}@latest`;
+		case "pnpm": return `pnpm update --latest ${PACKAGE_NAME}`;
+		case "yarn": return `yarn up ${PACKAGE_NAME}@latest`;
+		case "yarn-classic": return `yarn upgrade --latest ${PACKAGE_NAME}`;
+		case "bun": return `bun update --latest ${PACKAGE_NAME}`;
+	}
+}
+function updateInstruction(install) {
+	switch (install.kind) {
+		case "global": return `Run: ${globalCommand(install.manager)} ${PLUGINS_NOTE}\n`;
+		case "npx": return `Run: npx ${PACKAGE_NAME}@latest to use the latest version\n`;
+		case "local": return `Run in ${install.projectDir}: ${localCommand(install.manager)} ${PLUGINS_NOTE}\n`;
+	}
+}
+function updateNotice(current, latest, install = {
+	kind: "global",
+	manager: "npm"
+}) {
+	if (!isNewer(current, latest)) return null;
+	return `\nUpdate available for fluid: ${current} → ${latest}\n` + updateInstruction(install) + `Set FLUID_NO_UPDATE_CHECK=1 to stop these notices.\n`;
+}
+function readUpdateCache(configDir) {
+	try {
+		const data = JSON.parse(readFileSync(join(configDir, CACHE_FILE), "utf8"));
+		if (typeof data.checkedAt !== "string") return null;
+		const latest = typeof data.latest === "string" ? data.latest : null;
+		return {
+			checkedAt: data.checkedAt,
+			latest
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Write the cache, reporting whether it landed. The JSON goes to a fresh
+* file opened exclusively, then is renamed over the cache: a rename replaces
+* a symlink planted at the cache path instead of writing through it, so a
+* shared FLUID_CONFIG_DIR can't aim this write at another of the user's files.
+*/
+function writeUpdateCache(configDir, cache) {
+	const temp = join(configDir, `.${CACHE_FILE}.${randomBytes(6).toString("hex")}`);
+	try {
+		mkdirSync(configDir, { recursive: true });
+		writeFileSync(temp, JSON.stringify(cache) + "\n", { flag: "wx" });
+		renameSync(temp, join(configDir, CACHE_FILE));
+		return true;
+	} catch {
+		try {
+			rmSync(temp, { force: true });
+		} catch {}
+		return false;
+	}
+}
+function isStale(cache, now) {
+	if (!cache) return true;
+	const checkedAt = Date.parse(cache.checkedAt);
+	return Number.isNaN(checkedAt) || now.getTime() - checkedAt >= 864e5;
+}
+async function fetchLatestVersion(fetchImpl = fetch) {
+	try {
+		const response = await fetchImpl(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		if (!response.ok) return null;
+		const body = await response.json();
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Ask npm for the latest version and record it. Runs in the detached child;
+* a failure leaves the last known version and the throttle stamp in place.
+*/
+async function refreshUpdateCache(configDir, fetchImpl = fetch, now = /* @__PURE__ */ new Date()) {
+	const latest = await fetchLatestVersion(fetchImpl);
+	if (latest) writeUpdateCache(configDir, {
+		checkedAt: now.toISOString(),
+		latest
+	});
+}
+/** Start `node <entry> __refresh-update-check` detached, so this run never waits on npm. */
+function spawnRefresh(entryPath) {
+	try {
+		const child = spawn(process.execPath, [entryPath, REFRESH_ARG], {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+/**
+* Print the cached notice when the command finishes and, when the last
+* check started a day ago or more, stamp the cache and refresh it in a
+* detached process. The stamp throttles failed and concurrent checks to one
+* a day while keeping the last known version, and its notice, in place.
+*/
+function startUpdateCheck(options) {
+	if (!shouldCheckForUpdates(options)) return;
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const cache = readUpdateCache(options.configDir);
+	const notice = cache?.latest ? updateNotice(options.currentVersion, cache.latest, detectInstallKind(options.entryPath)) : null;
+	if (notice) (options.onExit ?? ((listener) => process.once("exit", listener)))(() => process.stderr.write(notice));
+	if (!isStale(cache, now)) return;
+	if (writeUpdateCache(options.configDir, {
+		checkedAt: now.toISOString(),
+		latest: cache?.latest ?? null
+	})) (options.refresh ?? spawnRefresh)(options.entryPath);
+}
+//#endregion
 //#region src/bin/fluid.ts
 const { version } = createRequire(import.meta.url)("../../package.json");
+if (process.argv[2] === "__refresh-update-check") {
+	await refreshUpdateCache(getConfigDir());
+	process.exit(0);
+}
 const packageRoot = process.cwd();
 const program = new Command();
 program.name("fluid").description("Fluid Commerce CLI").version(version);
@@ -662,6 +1122,18 @@ program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(whoamiCommand);
 program.addCommand(switchCommand);
+program.addCommand(commandsCommand);
+program.addCommand(completionCommand);
+program.addCommand(completeCommand, { hidden: true });
+startUpdateCheck({
+	currentVersion: version,
+	configDir: getConfigDir(),
+	env: process.env,
+	stdoutIsTTY: Boolean(process.stdout.isTTY),
+	stderrIsTTY: Boolean(process.stderr.isTTY),
+	entryPath: realpathSync(fileURLToPath(import.meta.url)),
+	versions: process.versions
+});
 await loadPlugins(program, packageRoot);
 program.parse(process.argv, { from: "node" });
 //#endregion