@tailglow/cli 0.2.0

package/src/config-command.js

@@ -0,0 +1,169 @@
+import {
+  CLI_CONFIGS,
+  CONFIG_KEYS,
+  isSecretSetting,
+  loadConfig,
+  loadConfigForWrite,
+  redactSetting,
+  saveConfig
+} from "./config.js";
+import { RESERVED_FLAGS } from "./flags.js";
+import { shouldEmitJson } from "./output.js";
+
+/**
+ * @param {string} message
+ * @param {{ json?: unknown }} flags
+ */
+function fail(message, flags) {
+  return { output: shouldEmitJson(flags) ? JSON.stringify({ error: message }) : message, code: 1 };
+}
+
+/**
+ * @param {string} message
+ * @param {Record<string, unknown>} fields
+ * @param {{ json?: unknown }} flags
+ */
+function succeed(message, fields, flags) {
+  return { output: shouldEmitJson(flags) ? JSON.stringify(fields, null, 2) : message, code: 0 };
+}
+
+/**
+ * What `tglow config` can do, described once.
+ *
+ * Both help forms render from this. The machine form used to list the SETTINGS without the verbs,
+ * so an agent saw four things it could store and no way to store them, and concluded the command
+ * did nothing. Same failure as the root help listing resources with no global flags.
+ */
+const CONFIG_COMMANDS = [
+  { command: "list", usage: "tglow config list", description: "Show every stored setting." },
+  { command: "get", usage: "tglow config get <key>", description: "Print one setting." },
+  {
+    command: "set",
+    usage: "tglow config set <key> <value>",
+    description: "Store a setting, so commands stop needing the flag."
+  },
+  { command: "unset", usage: "tglow config unset <key>", description: "Remove a setting." }
+];
+
+function renderConfigHelp() {
+  const key_width = Math.max(...Object.keys(CONFIG_KEYS).map((key) => key.length));
+  const usage_width = Math.max(...CONFIG_COMMANDS.map((entry) => entry.usage.length));
+
+  return [
+    "tglow config: stored defaults and credentials",
+    "",
+    "Commands:",
+    ...CONFIG_COMMANDS.map((entry) => `  ${entry.usage.padEnd(usage_width)}  ${entry.description}`),
+    "",
+    "Keys:",
+    ...Object.entries(CONFIG_KEYS).map(([key, note]) => `  ${key.padEnd(key_width)}  ${note}`),
+    "",
+    `Stored in ${CLI_CONFIGS.CONFIG_PATH}, readable only by you.`,
+    "A flag beats an environment variable, which beats this file."
+  ].join("\n");
+}
+
+/**
+ * `tglow config ...` is the one resource the registry does not supply, because the settings it
+ * holds are the CLI's own rather than the API's.
+ *
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @returns {Promise<{ output: string; code: number }>}
+ */
+export async function runConfigCommand(words, flags) {
+  const [action, key, value, ...rest] = words;
+  const json = shouldEmitJson(flags);
+
+  // Config dispatch happens before the command-wide checks, so it has to do its own. Without this,
+  // `config set project prj_x --jsoon` writes the setting and silently drops the typo, and a
+  // trailing word is ignored rather than questioned.
+  const unknown = Object.keys(flags).filter((flag) => !RESERVED_FLAGS.has(flag));
+  if (unknown.length > 0) {
+    return fail(
+      `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown.map((flag) => `--${flag}`).join(", ")}.`,
+      flags
+    );
+  }
+  if (rest.length > 0) {
+    return fail(`Unexpected argument${rest.length === 1 ? "" : "s"}: ${rest.join(", ")}.`, flags);
+  }
+
+  if (!action || flags.help) {
+    return succeed(
+      renderConfigHelp(),
+      {
+        usage: "tglow config <command> [key] [value]",
+        commands: CONFIG_COMMANDS,
+        keys: Object.entries(CONFIG_KEYS).map(([name, description]) => ({ name, description })),
+        path: CLI_CONFIGS.CONFIG_PATH,
+        precedence: "A flag beats an environment variable, which beats this file."
+      },
+      flags
+    );
+  }
+
+  if (action === "list") {
+    const stored = await loadConfig();
+    const entries = Object.keys(CONFIG_KEYS)
+      .filter((name) => typeof stored[name] === "string")
+      .map((name) => [name, redactSetting(name, stored[name])]);
+
+    if (json) return { output: JSON.stringify(Object.fromEntries(entries), null, 2), code: 0 };
+    if (entries.length === 0) {
+      return { output: `Nothing stored in ${CLI_CONFIGS.CONFIG_PATH}.`, code: 0 };
+    }
+
+    const width = Math.max(...entries.map(([name]) => name.length));
+    return {
+      output: entries.map(([name, shown]) => `${name.padEnd(width)}  ${shown}`).join("\n"),
+      code: 0
+    };
+  }
+
+  if (!key) return fail("Which setting? Run `tglow config` for the list.", flags);
+  // A plain property lookup is truthy for every inherited name, so `config set constructor x` would
+  // report success and persist a setting that nothing ever reads.
+  if (!Object.hasOwn(CONFIG_KEYS, key)) {
+    return fail(
+      `Unknown setting "${key}". Known settings: ${Object.keys(CONFIG_KEYS).join(", ")}.`,
+      flags
+    );
+  }
+
+  if (action === "get") {
+    // A key is never printed, even on request. No workflow needs it echoed that the environment
+    // variable does not already serve, and stdout is captured by shell history, logs and agent
+    // transcripts alike.
+    if (isSecretSetting(key)) {
+      return fail(
+        `${key} is never printed. Read ${CLI_CONFIGS.CONFIG_PATH} directly if you need the value.`,
+        flags
+      );
+    }
+
+    const current = (await loadConfig())[key];
+    if (typeof current !== "string") return fail(`${key} is not set.`, flags);
+    return succeed(current, { [key]: current }, flags);
+  }
+
+  if (action === "set") {
+    if (!value) return fail(`Missing a value for ${key}.`, flags);
+    const stored = await loadConfigForWrite();
+    await saveConfig({ ...stored, [key]: value });
+    return succeed(
+      `Set ${key} to ${redactSetting(key, value)}.`,
+      { ok: true, key, value: redactSetting(key, value) },
+      flags
+    );
+  }
+
+  if (action === "unset") {
+    const stored = await loadConfigForWrite();
+    const { [key]: _removed, ...rest } = stored;
+    await saveConfig(rest);
+    return succeed(`Removed ${key}.`, { ok: true, key, removed: true }, flags);
+  }
+
+  return fail(`Unknown config command "${action}". Run \`tglow config\` for the list.`, flags);
+}

package/src/config.js

@@ -0,0 +1,182 @@
+import fs from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const CLI_CONFIGS = {
+  DEFAULT_API_URL: "https://api.tailglow.io",
+  CONFIG_PATH: join(homedir(), ".tailglow", "config.json"),
+  // The API caps a page at 200, so the default is 50 requests. Deliberately a guardrail rather than
+  // a ceiling: `--max` moves it, and hitting it always prints the cursor to continue from.
+  DEFAULT_MAX_RECORDS: 10_000,
+  PAGE_SIZE: 200,
+  // Nobody else may read the file: it holds an API key. 0700 on the directory for the same reason.
+  FILE_MODE: 0o600,
+  DIRECTORY_MODE: 0o700
+};
+
+/**
+ * The settings the config file may hold. An allowlist so a typo fails loudly at `config set` rather
+ * than writing a key nothing ever reads.
+ *
+ * @type {Record<string, string>}
+ */
+export const CONFIG_KEYS = {
+  api_key: "API key used to authenticate. Create one under Team settings.",
+  api_url: "API origin to call. Defaults to the production API.",
+  project: "Project used when a command needs one and no --project is given.",
+  team: "Team used when a command needs one and no --team is given."
+};
+
+/** Settings whose value must never be printed back. */
+const SECRET_KEYS = new Set(["api_key"]);
+
+/** @param {string} key */
+export function isSecretSetting(key) {
+  return SECRET_KEYS.has(key);
+}
+
+/**
+ * Reads the stored config, if there is one.
+ *
+ * Missing, unreadable, and malformed are all the same answer on purpose: the file is a convenience
+ * over environment variables, so a broken one must not stop a command that had its credentials
+ * another way. That includes a file holding a bare `null`, which parses fine and is not an object.
+ *
+ * @param {string} [path]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function loadConfig(path = CLI_CONFIGS.CONFIG_PATH) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Reads the stored config, refusing to guess when the file is unreadable.
+ *
+ * `loadConfig` answers "no settings" for a broken file so a command that had its credentials
+ * another way still runs. A MUTATION cannot do that: it would write its own view back and erase
+ * whatever the file actually held, which for a file holding an API key is silent credential loss.
+ *
+ * @param {string} [path]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function loadConfigForWrite(path = CLI_CONFIGS.CONFIG_PATH) {
+  /** @type {string} */
+  let contents;
+  try {
+    contents = await fs.readFile(path, "utf-8");
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT") return {};
+    throw new Error(`Cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    throw new Error(
+      `${path} is not valid JSON, so changing a setting would erase whatever it holds.\n` +
+        "Fix or delete the file, then try again."
+    );
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `${path} does not hold a JSON object, so changing a setting would erase it.\n` +
+        "Fix or delete the file, then try again."
+    );
+  }
+
+  return /** @type {Record<string, string>} */ (parsed);
+}
+
+/**
+ * Writes the config, never widening what can read it.
+ *
+ * The `mode` options to `mkdir` and `writeFile` only apply when they CREATE, so an existing
+ * world-readable directory or file keeps its permissions. Writing the key straight into such a file
+ * and chmodding afterwards leaves a window where the key is on disk and readable; a temp file
+ * created at 0600 and renamed into place never has one.
+ *
+ * @param {Record<string, string>} values
+ * @param {string} [path]
+ */
+export async function saveConfig(values, path = CLI_CONFIGS.CONFIG_PATH) {
+  const directory = dirname(path);
+  await fs.mkdir(directory, { recursive: true, mode: CLI_CONFIGS.DIRECTORY_MODE });
+  await fs.chmod(directory, CLI_CONFIGS.DIRECTORY_MODE);
+
+  const staged = `${path}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(staged, `${JSON.stringify(values, null, 2)}\n`, {
+      mode: CLI_CONFIGS.FILE_MODE,
+      flag: "wx"
+    });
+    await fs.chmod(staged, CLI_CONFIGS.FILE_MODE);
+    await fs.rename(staged, path);
+  } catch (err) {
+    await fs.rm(staged, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {string} value
+ */
+export function redactSetting(key, value) {
+  if (!SECRET_KEYS.has(key)) return value;
+  return value.length <= 8 ? "********" : `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+/**
+ * Resolves one setting.
+ *
+ * Precedence is flag, then environment, then stored config. A flag is the most specific statement
+ * of intent and an env var is how CI supplies things, so neither may be overridden by a file the
+ * user configured months ago.
+ *
+ * @param {string} name
+ * @param {{
+ *   flags?: Record<string, unknown>;
+ *   env?: NodeJS.ProcessEnv;
+ *   config?: Record<string, string>;
+ * }} [sources]
+ * @returns {string | null}
+ */
+export function resolveSetting(name, { flags = {}, env = process.env, config = {} } = {}) {
+  const flag = flags[name.replaceAll("_", "-")] ?? flags[name];
+  if (typeof flag === "string" && flag.length > 0) return flag;
+
+  const from_env = env[`TAILGLOW_${name.toUpperCase()}`];
+  if (typeof from_env === "string" && from_env.length > 0) return from_env;
+
+  const stored = config[name];
+  return typeof stored === "string" && stored.length > 0 ? stored : null;
+}
+
+/** @param {{ flags?: Record<string, unknown>; config?: Record<string, string> }} [options] */
+export function resolveApiUrl(options = {}) {
+  return resolveSetting("api_url", options) ?? CLI_CONFIGS.DEFAULT_API_URL;
+}
+
+/**
+ * @param {{ flags?: Record<string, unknown>; config?: Record<string, string> }} [options]
+ * @returns {string}
+ */
+export function resolveApiKey(options = {}) {
+  const key = resolveSetting("api_key", options);
+  if (!key) {
+    throw new Error(
+      "No API key. Set TAILGLOW_API_KEY, or run `tglow config set api_key <key>`.\n" +
+        "Create a key in the dashboard under Team settings."
+    );
+  }
+  return key;
+}

package/src/flags.js

@@ -0,0 +1,299 @@
+/**
+ * Field names are snake_case on the wire and kebab-case on a command line, so the mapping is
+ * mechanical in both directions and no command has to declare it.
+ *
+ * @param {string} field
+ */
+export function toFlagName(field) {
+  return field.replaceAll("_", "-");
+}
+
+/** @param {string} flag */
+export function toFieldName(flag) {
+  return flag.replaceAll("-", "_");
+}
+
+/**
+ * Options the runtime owns, and whether each consumes the token after it.
+ *
+ * `after` is deliberately absent: it is a real cursor query parameter on every paginated list, so
+ * reserving it would make the cursor that `--all` prints unusable.
+ *
+ * @type {Record<string, "string" | "boolean">}
+ */
+const GLOBAL_OPTIONS = {
+  json: "boolean",
+  all: "boolean",
+  help: "boolean",
+  version: "boolean",
+  yes: "boolean",
+  max: "string",
+  "api-key": "string",
+  "api-url": "string",
+  project: "string",
+  team: "string"
+};
+
+/**
+ * Flags the runtime owns. They are refused as field names so a future API field called `json` can
+ * never quietly shadow the output flag.
+ */
+export const RESERVED_FLAGS = new Set(Object.keys(GLOBAL_OPTIONS));
+
+/**
+ * Declares every option `parseArgs` may encounter, so it knows which ones consume the token that
+ * follows them.
+ *
+ * This has to cover the WHOLE registry rather than one command's fields, because the flags are
+ * parsed before the command is known. Getting it wrong is not a cosmetic problem: an undeclared
+ * `--api-key` becomes a bare boolean and leaves the key sitting in the positionals, where it is
+ * read as a resource name and echoed back in an error.
+ *
+ * A field name never carries two different types across commands, so first-wins is unambiguous.
+ *
+ * @param {import("./types.d.ts").CliCommand[]} commands
+ */
+export function buildParserOptions(commands) {
+  /** @type {Record<string, { type: "string" | "boolean" }>} */
+  const options = {};
+
+  for (const [flag, type] of Object.entries(GLOBAL_OPTIONS)) options[flag] = { type };
+
+  for (const command of commands) {
+    const fields = [...command.path_params, ...command.query_params, ...command.body_fields];
+    for (const field of fields) {
+      const flag = toFlagName(field.name);
+      if (options[flag]) continue;
+      options[flag] = { type: field.type === "boolean" ? "boolean" : "string" };
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Turns the runtime's own switches into real booleans.
+ *
+ * Under `strict: false` a declared boolean written as `--yes=false` comes back as the STRING
+ * `"false"`, which is truthy. Left alone, `--yes=false` would skip the delete confirmation and
+ * `--json=false` would still emit JSON: the opposite of what was typed, on the two flags where
+ * being wrong costs the most.
+ *
+ * @param {Record<string, unknown>} flags
+ */
+export function normalizeSwitches(flags) {
+  for (const [flag, type] of Object.entries(GLOBAL_OPTIONS)) {
+    if (type !== "boolean") continue;
+
+    const raw = flags[flag];
+    if (raw === undefined || typeof raw === "boolean") continue;
+    if (raw === "true" || raw === "false") {
+      flags[flag] = raw === "true";
+      continue;
+    }
+
+    throw new Error(`--${flag} takes no value, or =true / =false. Received "${raw}".`);
+  }
+
+  return flags;
+}
+
+/**
+ * Refuses a flag that was written but carries no value.
+ *
+ * `--project` bare parses as `true` and `--project=` as `""`; both read as "not supplied", so the
+ * value would come from `TAILGLOW_PROJECT` or the stored config instead. `--api-url=` would fall
+ * back to PRODUCTION and `--api-key=` to a stored credential. A flag someone typed must never
+ * resolve to ambient state.
+ *
+ * Runs over every declared string option at once, so path parameters are covered as well as the
+ * runtime's own flags; `coerceValue` only sees query and body fields.
+ *
+ * @param {Record<string, unknown>} flags
+ * @param {Record<string, { type: "string" | "boolean" }>} options
+ */
+export function assertSuppliedValuesArePresent(flags, options) {
+  for (const [flag, value] of Object.entries(flags)) {
+    if (options[flag]?.type !== "string") continue;
+    if (typeof value === "string" && value.length > 0) continue;
+
+    throw new Error(`--${flag} was given no value.`);
+  }
+}
+
+/** @param {string} type */
+function isStructuredType(type) {
+  return type === "Scopes" || type.startsWith("object");
+}
+
+/**
+ * How to actually type this flag.
+ *
+ * `--output-schema <object[]>` names a type without saying how to encode it, which is not a
+ * contract anyone can satisfy: a reviewer guessed JSON and guessed the member shape, and said it
+ * was the moment they most wanted to read the source. A boolean has the same problem from the other
+ * side, because the value has to be attached rather than spaced.
+ *
+ * @param {string} flag
+ * @param {string} type
+ */
+export function describeFlagSyntax(flag, type) {
+  if (type === "boolean") return `--${flag} | --${flag}=false`;
+  if (isStructuredType(type)) return `--${flag} '<json ${type}>'`;
+  if (type.endsWith("[]")) return `--${flag} <comma,separated | json array>`;
+
+  return `--${flag} <${type}>`;
+}
+
+/**
+ * Whether the text spells a whole number that survives the round trip through a JSON number.
+ *
+ * `Number()` is lossy in both directions. `Number("1e-400")` is `0` and
+ * `Number("1.0000000000000001")` is `1`, so checking the RESULT with `Number.isInteger` accepts
+ * fractional input and silently sends a different value: `servers scale --count 1e-400` would send
+ * `count: 0` and take a fleet down. In the other direction a long-enough run of digits becomes
+ * `Infinity`, which passes any `< n` guard and which `JSON.stringify` writes as `null`, and
+ * anything past 2^53 arrives rounded.
+ *
+ * @param {string} raw
+ */
+export function isIntegerText(raw) {
+  const trimmed = raw.trim();
+  return /^[+-]?\d+$/.test(trimmed) && Number.isSafeInteger(Number(trimmed));
+}
+
+/**
+ * The value is never echoed back here, unlike the scalar branches below.
+ *
+ * Structured fields are exactly the ones that carry secrets: `drains create --headers` takes
+ * authorization headers, and `roles create --scopes` a permission map. A typo would otherwise put
+ * the whole object into stderr, and from there into a CI log or an agent transcript.
+ *
+ * @param {string} raw
+ * @param {string} type
+ * @param {string} [named]
+ */
+function parseStructuredValue(raw, type, named = "") {
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(`${named}expected JSON for a ${type} value`);
+  }
+
+  if (type.startsWith("object[]") && !Array.isArray(value)) {
+    throw new Error(`${named}expected a JSON array for a ${type} value`);
+  }
+  if (!type.startsWith("object[]") && Array.isArray(value)) {
+    throw new Error(`${named}expected a JSON object for a ${type} value`);
+  }
+
+  return value;
+}
+
+/**
+ * Coerces a flag string into the type the field declares.
+ *
+ * The registry gives the wire type, so a caller never has to think about quoting: `--limit 5` is a
+ * number and `--is-public true` is a boolean, both because the API said so. Anything unrecognised
+ * stays a string, which is what the API validates anyway.
+ *
+ * Numeric fields reject anything non-finite rather than passing it along. `Infinity` survives
+ * `Number()` but `JSON.stringify` turns it into `null`, so an unchecked value does not fail — it
+ * silently sends a different field than the one that was typed.
+ *
+ * @param {string | boolean} raw
+ * @param {string} type
+ * @param {string} [flag]
+ */
+export function coerceValue(raw, type, flag = "") {
+  const named = flag ? `--${flag}: ` : "";
+
+  if (typeof raw === "boolean") {
+    // A flag written bare parses as `true`. On a boolean field that IS the value; anywhere else the
+    // value was left off, and sending `true` would make the API reject a request that reads as fine.
+    if (type.includes("boolean")) return raw;
+    throw new Error(`${named}expected a ${type} value after the flag, received none`);
+  }
+
+  if (raw === "null" && type.includes("null")) return null;
+
+  if (isStructuredType(type)) return parseStructuredValue(raw, type, named);
+
+  if (type.includes("integer")) {
+    if (!isIntegerText(raw)) throw new Error(`${named}expected a whole number, received "${raw}"`);
+    return Number(raw);
+  }
+
+  if (type.includes("number")) {
+    const value = Number(raw);
+    if (raw.trim() === "" || !Number.isFinite(value)) {
+      throw new Error(`${named}expected a number, received "${raw}"`);
+    }
+    return value;
+  }
+
+  if (type.includes("boolean")) {
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+    throw new Error(`${named}expected true or false, received "${raw}"`);
+  }
+
+  if (type.endsWith("[]")) {
+    if (raw.trimStart().startsWith("[")) return parseStructuredValue(raw, "object[]");
+    return raw
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+
+  return raw;
+}
+
+/**
+ * Splits the parsed flags into the three places a request can carry a value.
+ *
+ * `consumed_path_fields` is the set the resolved path actually substituted, NOT every field the
+ * registry lists as a path parameter. A field can be a path parameter on an alternate path only
+ * (`metric_id` for `monitors list`) while also being a query filter on the primary one; skipping it
+ * by name would drop the filter and quietly return everything.
+ *
+ * @param {import("./types.d.ts").CliCommand} command
+ * @param {Record<string, unknown>} flags
+ * @param {{ consumed_path_fields?: Set<string> }} [options]
+ */
+export function buildRequestParts(command, flags, { consumed_path_fields = new Set() } = {}) {
+  /** @type {Record<string, unknown>} */
+  const query = {};
+  /** @type {Record<string, unknown>} */
+  const body = {};
+  /** @type {string[]} */
+  const unknown = [];
+
+  const query_by_flag = new Map(
+    command.query_params.map((field) => [toFlagName(field.name), field])
+  );
+  const body_by_flag = new Map(command.body_fields.map((field) => [toFlagName(field.name), field]));
+  const consumed_flags = new Set([...consumed_path_fields].map(toFlagName));
+
+  for (const [flag, raw] of Object.entries(flags)) {
+    if (RESERVED_FLAGS.has(flag) || consumed_flags.has(flag)) continue;
+
+    const query_field = query_by_flag.get(flag);
+    if (query_field) {
+      query[query_field.name] = coerceValue(/** @type {string} */ (raw), query_field.type, flag);
+      continue;
+    }
+
+    const body_field = body_by_flag.get(flag);
+    if (body_field) {
+      body[body_field.name] = coerceValue(/** @type {string} */ (raw), body_field.type, flag);
+      continue;
+    }
+
+    unknown.push(flag);
+  }
+
+  return { query, body, unknown };
+}