@tailglow/cli 0.5.1 → 0.6.0

package/src/help.js

@@ -1,6 +1,7 @@
 import { CLI_COMMANDS } from "./commands.generated.js";
 import { CLI_CONFIGS, CONFIG_KEYS } from "./config.js";
 import { describeFlagSyntax, toFlagName } from "./flags.js";
+import { describeLoginForMachines } from "./login-command.js";
 
 /**
  * The runtime's own flags, described once.
@@ -17,7 +18,8 @@ export const GLOBAL_FLAGS = [
     flag: "--json",
     argument: null,
     env: null,
-    description: "Emit JSON. Implied whenever output is piped or redirected."
+    description:
+      "Emit JSON. Implied whenever output is piped or redirected, except by `tglow docs`, which prints markdown unless this is given."
   },
   {
     flag: "--all",
@@ -55,14 +57,15 @@ export const GLOBAL_FLAGS = [
     flag: "--team",
     argument: "<id>",
     env: "TAILGLOW_TEAM",
-    description: "Team to act on, when a command needs one and --team-id is not given."
+    description:
+      "Team to act on, when a command needs one and --team-id is not given. With a `tglow login` session, also the team it acts in."
   },
   {
     flag: "--api-key",
     argument: "<key>",
     env: "TAILGLOW_API_KEY",
     description:
-      "Credential to authenticate with. Prefer the environment variable: a key passed as a flag is visible in the process list and in shell history."
+      "API key to authenticate with, ahead of the environment variable and `tglow login`. Prefer the environment variable: a key passed as a flag is visible in the process list and in shell history."
   },
   {
     flag: "--api-url",
@@ -81,16 +84,19 @@ export const GLOBAL_FLAGS = [
  * machine form was missing all of it.
  */
 export const USAGE_NOTES = [
+  "In a terminal, `tglow` offers sign-in when no credential is configured. `tglow help` always shows help.",
   "Flags are the field name in kebab-case: a field named `time_window_minutes` is `--time-window-minutes`.",
   "Path parameters are flags too, never positional: `--project-id prj_x`, not `tglow ... prj_x`.",
   "A true/false flag is passed alone for true, or written attached for false: `--is-public` or `--is-public=false`.",
-  'A field typed `object`, `object[]` or `Scopes` takes JSON as a single argument: --joins \'[{"view_id":"view_b"}]\'.',
+  'A field typed `object`, `object[]` or `Scopes` takes JSON as a single argument: --joins \'[{"lookup_view_id":"view_b","alias":"b","base_field":"user_id","lookup_field":"id"}]\'. Its keys are listed under it in the command\'s help.',
   "A field typed `string[]` takes a comma-separated list or a JSON array.",
   "JSON output is the API response as it was sent: read `.data` for results and `.pagination.next_cursor` to continue.",
   "Under --all, JSON output is instead { data, truncated, next_cursor }, so a capped run can resume with --after.",
   "`--all` replaces `--limit` and `--before` rather than combining with them: use `--max` for the total, or `--limit` alone for one page.",
   "Deletes are immediate and unconfirmed when there is no terminal attached. Many resources delete softly; the response says so.",
-  "Precedence for anything that has a default is flag, then environment variable, then `tglow config`."
+  "Precedence for anything that has a default is flag, then environment variable, then `tglow config`.",
+  "Credentials are tried in order: --api-key, TAILGLOW_API_KEY, the `tglow login` credential, then `tglow config set api_key`.",
+  "Without a terminal, `tglow login` prints a link and exits 0. Approve it, then `tglow login --wait` finishes (exit 75 means still waiting: run it again)."
 ];
 
 /** @param {import("./types.d.ts").CliCommand[]} commands */
@@ -134,7 +140,8 @@ export function describeCommandFlags(command) {
       description: field.description,
       allowed_values: field.allowed_values,
       syntax: describeFlagSyntax(toFlagName(field.name), field.type),
-      deprecated: field.deprecated
+      deprecated: field.deprecated,
+      ...(field.fields ? { fields: field.fields } : {})
     }));
 
   const path_flags = describe(
@@ -217,6 +224,12 @@ export function describeForMachines({ resource, command } = {}) {
       path: CLI_CONFIGS.CONFIG_PATH,
       keys: Object.keys(CONFIG_KEYS)
     },
+    docs: {
+      command: "tglow docs [path]",
+      description:
+        "Every guide and API reference page as markdown, shipped with this CLI. Start with `tglow docs guides/agents`."
+    },
+    account: describeLoginForMachines(),
     global_flags: globals,
     usage_notes: USAGE_NOTES
   };
@@ -236,8 +249,15 @@ export function renderRootHelp() {
     "Resources:",
     ...resources.map((resource) => `  ${resource}`),
     "  config  (stored defaults and credentials)",
+    "  docs    (every guide and API reference page, as markdown)",
+    "",
+    "Account:",
+    "  tglow login   Sign in through the browser. `tglow login --help` for agents and scripts.",
+    "  tglow logout  Remove the credential tglow login stored.",
+    "  tglow whoami  Show who the CLI is acting as.",
     "",
     "Run `tglow <resource>` to list its commands, or `tglow <resource> <command> --help`.",
+    "New to Tailglow? Run `tglow docs guides/agents`.",
     "",
     "Global flags:",
     ...globals.map((entry) => `  ${entry.left.padEnd(width)}  ${entry.description}`),
@@ -274,19 +294,44 @@ function renderFields({ fields, title }) {
   return [
     "",
     `${title}:`,
-    ...fields.map((field) => {
-      const flag = toFlagName(field.name);
-      const required = field.required ? " (required)" : "";
-      const allowed =
-        field.allowed_values.length > 0 ? ` [${field.allowed_values.join(", ")}]` : "";
+    ...fields
+      .map((field) => {
+        const flag = toFlagName(field.name);
+        const required = field.required ? " (required)" : "";
+        const allowed =
+          field.allowed_values.length > 0 ? ` [${field.allowed_values.join(", ")}]` : "";
 
-      const description = field.description ? `  ${field.description}` : "";
+        const description = field.description ? `  ${field.description}` : "";
 
-      return `  ${describeFlagSyntax(flag, field.type)}${required}${allowed}${description}`;
-    })
+        return [
+          `  ${describeFlagSyntax(flag, field.type)}${required}${allowed}${description}`,
+          ...renderNestedFields(field.fields ?? [], 2)
+        ];
+      })
+      .flat()
   ];
 }
 
+/**
+ * The keys a JSON flag takes, indented under it one level per nesting.
+ *
+ * @param {import("./types.d.ts").CliField[]} fields
+ * @param {number} depth
+ * @returns {string[]}
+ */
+function renderNestedFields(fields, depth) {
+  const indent = "  ".repeat(depth + 1);
+  return fields.flatMap((field) => {
+    const required = field.required ? " (required)" : "";
+    const allowed = field.allowed_values.length > 0 ? ` [${field.allowed_values.join(", ")}]` : "";
+    const description = field.description ? `  ${field.description}` : "";
+    return [
+      `${indent}${field.name} <${field.type}>${required}${allowed}${description}`,
+      ...renderNestedFields(field.fields ?? [], depth + 1)
+    ];
+  });
+}
+
 /** @param {import("./types.d.ts").CliCommand} command */
 export function renderCommandHelp(command) {
   const paths = [command.path, ...command.alternate_paths];

package/src/index.js

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import fs from "node:fs/promises";
-import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { confirm, isCancel } from "@clack/prompts";
 import { CLI_COMMANDS } from "./commands.generated.js";
 import { runConfigCommand } from "./config-command.js";
-import { CLI_CONFIGS, loadConfig, resolveSetting } from "./config.js";
+import { CLI_CONFIGS, loadConfig, readCliVersion, resolveSetting } from "./config.js";
 import {
   assertSuppliedValuesArePresent,
   buildParserOptions,
@@ -22,7 +20,20 @@ import {
   renderResourceHelp,
   renderRootHelp
 } from "./help.js";
-import { renderPagedResult, renderResponse, sanitizeText, shouldEmitJson } from "./output.js";
+import {
+  createLoginContext,
+  runLoginCommand,
+  runLogoutCommand,
+  runWhoamiCommand,
+  shouldOfferLogin
+} from "./login-command.js";
+import {
+  renderPagedResult,
+  renderResponse,
+  sanitizeText,
+  shouldEmitJson,
+  writeCommandResult
+} from "./output.js";
 import { requestAllPages, requestApi } from "./request.js";
 
 /** Path parameters people refer to by the shorter name they actually type. */
@@ -37,10 +48,22 @@ const PATH_ALIASES = { project_id: "project", team_id: "team" };
  */
 const UNSAFE_PATH_VALUES = new Set([".", ".."]);
 
-const PARSER_OPTIONS = buildParserOptions(CLI_COMMANDS);
+/**
+ * `tglow login`'s own flags, declared so `--method api-key` keeps its value instead of the value
+ * becoming a positional. The registry's own `method` field is a string too, so they agree.
+ *
+ * @type {Record<string, { type: "string" | "boolean" }>}
+ */
+const LOGIN_PARSER_OPTIONS = {
+  method: { type: "string" },
+  wait: { type: "boolean" },
+  new: { type: "boolean" }
+};
+
+const PARSER_OPTIONS = { ...LOGIN_PARSER_OPTIONS, ...buildParserOptions(CLI_COMMANDS) };
 
 /** @param {string[]} argv */
-function parseFlags(argv) {
+export function parseFlags(argv) {
   return parseArgs({
     args: argv,
     strict: false,
@@ -103,7 +126,7 @@ function readFlag(flags, flag) {
  * uses and one they wrap in a shell function.
  *
  * @param {import("./types.d.ts").CliCommand} command
- * @param {{ flags: Record<string, unknown>; config: Record<string, string> }} sources
+ * @param {{ flags: Record<string, unknown>; config: import("./types.d.ts").CliConfig }} sources
  */
 function resolvePath(command, { flags, config }) {
   const placeholders = [...command.path.matchAll(/:([a-z_]+)/g)].map(([, name]) => name);
@@ -113,6 +136,8 @@ function resolvePath(command, { flags, config }) {
   const unsafe = [];
   /** @type {Set<string>} */
   const consumed = new Set();
+  /** @type {Record<string, string>} */
+  const values = {};
 
   const path = placeholders.reduce((current, name) => {
     // Only project and team fall back to configuration. Resolving EVERY placeholder that way would
@@ -133,10 +158,11 @@ function resolvePath(command, { flags, config }) {
     }
 
     consumed.add(name);
+    values[name] = value;
     return current.replace(`:${name}`, encodeURIComponent(value));
   }, command.path);
 
-  return { path, missing, unsafe, consumed };
+  return { path, missing, unsafe, consumed, values };
 }
 
 /** @param {import("./types.d.ts").CliCommand} command */
@@ -144,12 +170,6 @@ function isPaginated(command) {
   return command.method === "GET" && command.query_params.some((field) => field.name === "after");
 }
 
-async function readVersion() {
-  const manifest = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-  const { version } = JSON.parse(await fs.readFile(manifest, "utf-8"));
-  return version;
-}
-
 /**
  * @param {string} message
  * @param {{ json?: unknown }} flags
@@ -181,16 +201,17 @@ async function confirmDestructive(command, flags) {
 
 /**
  * @param {string[]} argv
+ * @param {import("./login-command.js").LoginContext} [login_context]
  * @returns {Promise<{ output: string; code: number }>}
  */
-export async function run(argv) {
+export async function run(argv, login_context = createLoginContext()) {
   const { values: flags, positionals } = parseFlags(argv);
 
   try {
     normalizeSwitches(flags);
     assertSuppliedValuesArePresent(flags, PARSER_OPTIONS);
 
-    const describe = shouldEmitJson(flags);
+    const describe = login_context.emits_json(flags);
     /** @param {string} text @param {unknown} machine_readable */
     const inform = (text, machine_readable) => ({
       output: describe ? JSON.stringify(machine_readable, null, 2) : text,
@@ -198,17 +219,34 @@ export async function run(argv) {
     });
 
     if (flags.version) {
-      const version = await readVersion();
+      const version = await readCliVersion();
       return inform(version, { version });
     }
 
     const [resource, name, ...rest] = positionals;
-    if (!resource) return inform(renderRootHelp(), describeForMachines());
+    if (resource === "help") {
+      if (name) return fail("Run `tglow <resource> <command> --help` for command help.", flags);
+      return inform(renderRootHelp(), describeForMachines());
+    }
+    if (!resource) {
+      if (await shouldOfferLogin(flags, login_context)) {
+        return await runLoginCommand([], flags, login_context);
+      }
+      return inform(renderRootHelp(), describeForMachines());
+    }
     if (resource === "config") return await runConfigCommand([name, ...rest], flags);
+    if (resource === "login") return await runLoginCommand([name, ...rest], flags, login_context);
+    if (resource === "logout") return await runLogoutCommand([name, ...rest], flags);
+    if (resource === "whoami") return await runWhoamiCommand([name, ...rest], flags);
+    if (resource === "docs") {
+      // Loaded only here: the bundled docs are about 600 KB that every other command would parse.
+      const { runDocsCommand } = await import("./docs-command.js");
+      return runDocsCommand([name, ...rest], flags);
+    }
 
     const commands = CLI_COMMANDS.filter((entry) => entry.resource === resource);
     if (commands.length === 0) {
-      return fail(`Unknown resource "${resource}". Run \`tglow\` for the list.`, flags);
+      return fail(`Unknown resource "${resource}". Run \`tglow help\` for the list.`, flags);
     }
 
     if (!name) {
@@ -226,7 +264,8 @@ export async function run(argv) {
     if (flags.help) return inform(renderCommandHelp(command), describeForMachines({ command }));
 
     const config = await loadConfig();
-    const { path, missing, unsafe, consumed } = resolvePath(command, { flags, config });
+    const { path, missing, unsafe, consumed, values } = resolvePath(command, { flags, config });
+    const path_team_id = values.team_id ?? null;
 
     if (unsafe.length > 0) {
       const named = unsafe.map((entry) => `--${toFlagName(entry)}`).join(", ");
@@ -307,6 +346,7 @@ export async function run(argv) {
         query,
         flags,
         config,
+        path_team_id,
         max: Number(raw_max)
       });
 
@@ -330,10 +370,27 @@ export async function run(argv) {
 
     if (!(await confirmDestructive(command, flags))) return fail("Cancelled.", flags);
 
-    const payload = await requestApi({ method: command.method, path, query, body, flags, config });
+    const payload = await requestApi({
+      method: command.method,
+      path,
+      query,
+      body,
+      flags,
+      config,
+      path_team_id
+    });
     return { output: renderResponse(payload, flags), code: 0 };
   } catch (err) {
-    return fail(err instanceof Error ? err.message : String(err), flags);
+    const message = err instanceof Error ? err.message : String(err);
+    // `tglow docs` answers in text unless --json was given, including for a flag the shared checks
+    // above rejected before it was dispatched.
+    if (positionals[0] === "docs") {
+      return {
+        output: flags.json === true ? JSON.stringify({ error: message }) : message,
+        code: 1
+      };
+    }
+    return fail(message, flags);
   }
 }
 
@@ -357,14 +414,25 @@ if (isEntrypoint()) {
   // `process.exit` discards whatever is still buffered for a pipe, and a pipe's buffer is 64 KB.
   // `tglow records list --all --json | jq` would receive a JSON document cut off mid-value, which
   // is exactly the invariant this CLI sells. Set the code and let the write drain instead.
+  let json = shouldEmitJson({});
   try {
-    const { output, code } = await run(process.argv.slice(2));
-    // Anything that failed belongs on stderr, so a `--json` pipeline reading stdout never has to
-    // tell a result apart from an explanation of why there is none.
-    process.exitCode = code;
-    (code === 0 ? process.stdout : process.stderr).write(`${output}\n`);
+    const argv = process.argv.slice(2);
+    const { values: flags, positionals } = parseFlags(argv);
+    json = shouldEmitJson({ json: flags.json === true || flags.json === "true" });
+    const result = await run(argv);
+    const message =
+      !flags.help &&
+      ((!positionals[0] && result.output !== renderRootHelp()) ||
+        ["login", "logout", "whoami"].includes(positionals[0]) ||
+        (positionals[0] === "config" && ["set", "unset"].includes(positionals[1])));
+    process.exitCode = result.code;
+    writeCommandResult(result, { json, message });
   } catch (err) {
     process.exitCode = 1;
-    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    const message = err instanceof Error ? err.message : String(err);
+    writeCommandResult(
+      { output: json ? JSON.stringify({ error: message }) : message, code: 1 },
+      { json }
+    );
   }
 }