linear-sdk-cli 0.1.0

package/src/commands/comment.ts

@@ -0,0 +1,225 @@
+/**
+ * `linear comment` (alias `cm`) — manage comments by id beyond the basic
+ * `linear issue comment` add (Phase 1). Adds reply, update, delete, and
+ * resolve/unresolve, plus a standalone `list <issue>`.
+ *
+ * Comment ids are UUIDs; the `<issue>` argument accepts an identifier (TES-123)
+ * or a UUID and is resolved via resolveIssue.
+ *
+ * The four core verbs are built by factories rather than registered inline, so
+ * the `linear issue comment {add,list,update,delete}` subgroup (the reference
+ * CLI's layout) can mount the *same* handlers under `issue` without a second
+ * copy of the logic. Commander commands carry a parent pointer, so each mount
+ * point needs its own instance — hence factories, not shared constants.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { resolveBody } from "../lib/body.js";
+import { confirmDestructive } from "../lib/prompt.js";
+import { usageError } from "../lib/errors.js";
+import { collectArray } from "../lib/options.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/comment.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.CommentRow>[] = [
+  { key: "createdAt", header: "Date", value: (r) => r.createdAt.slice(0, 10) },
+  { key: "author", header: "Author", value: (r) => r.user?.displayName ?? "—", max: 18 },
+  { key: "body", header: "Body", value: (r) => r.body.replace(/\n/g, " "), max: 70 },
+];
+
+/** Options for a mounted copy of the shared verbs. */
+interface MountOptions {
+  /** Register the short aliases (`ls`, `edit`, `rm`). Off under `issue comment`. */
+  aliases?: boolean;
+}
+
+function buildList(o: MountOptions): Command {
+  const cmd = new Command("list").argument("<issue>").description("List comments on an issue");
+  if (o.aliases !== false) cmd.alias("ls");
+  return cmd.action(
+    action(async (ctx: Context, _opts, issueArg: string) => {
+      const rows = await svc.listComments(ctx.client, issueArg, ctx.limit);
+      ctx.output.list(rows, ROW_COLUMNS, rows);
+    }),
+  );
+}
+
+function buildAdd(_o: MountOptions): Command {
+  return new Command("add")
+    .argument("<issue>")
+    .argument("[body]")
+    .description("Add a comment to an issue (images uploaded with --attach render inline)")
+    .option("--body-file <path>", "read comment body from a file ('-' = stdin)")
+    .option(
+      "--attach <file>",
+      "upload a file and embed it in the comment (images inline; repeatable; private by default)",
+      collectArray,
+    )
+    .option(
+      "--public",
+      "upload the attachments to public, world-readable URLs (raster images only)",
+    )
+    .action(
+      action(async (ctx: Context, opts, issueArg: string, bodyArg?: string) => {
+        const attachments: string[] = opts.attach ?? [];
+        if (opts.public && attachments.length === 0) {
+          throw usageError("--public applies to uploads; add --attach <file>, or drop --public.");
+        }
+        // With attachments the body is optional (the embeds are the comment),
+        // so the editor is not opened for one — the reference CLI's rule too.
+        const body = resolveBody({
+          arg: bodyArg,
+          file: opts.bodyFile,
+          interactive: ctx.isTTY && attachments.length === 0,
+        });
+        if (!body && attachments.length === 0) throw usageError("No comment body provided.");
+        const {
+          issue,
+          comment: created,
+          uploads,
+        } = await svc.addComment(ctx.client, issueArg, body ?? "", {
+          attachments,
+          public: opts.public === true,
+        });
+        for (const u of uploads) {
+          if (u.public)
+            ctx.output.warn(`${u.filename} is on a public URL, readable by anyone: ${u.assetUrl}`);
+        }
+        ctx.output.emit(
+          {
+            id: created.id,
+            issue: issue.identifier,
+            url: created.url,
+            ...(uploads.length
+              ? {
+                  attachments: uploads.map((u) => ({
+                    filename: u.filename,
+                    assetUrl: u.assetUrl,
+                    contentType: u.contentType,
+                    size: u.size,
+                  })),
+                }
+              : {}),
+          },
+          () => ctx.output.success(`Commented on ${issue.identifier}`),
+        );
+      }),
+    );
+}
+
+function buildUpdate(o: MountOptions): Command {
+  const cmd = new Command("update")
+    .argument("<commentId>")
+    .argument("[body]")
+    .description("Update a comment's body")
+    .option("--body-file <path>", "read new body from a file ('-' = stdin)");
+  if (o.aliases !== false) cmd.alias("edit");
+  return cmd.action(
+    action(async (ctx: Context, opts, commentId: string, bodyArg?: string) => {
+      // Fetch the comment first: the editor opens ON the current body (so
+      // quitting without typing cannot blank it), a missing id fails before
+      // anyone writes anything, and the service can refuse a no-op update.
+      const current = await svc.getComment(ctx.client, commentId);
+      const body = resolveBody({
+        arg: bodyArg,
+        file: opts.bodyFile,
+        interactive: ctx.isTTY,
+        template: current.body,
+      });
+      if (body === undefined) throw usageError("No comment body provided.");
+      // The editor path hands back a trimmed body, so compare against the
+      // trimmed original: an untouched session must read as "unchanged".
+      const updated = await svc.updateComment(ctx.client, commentId, body, current.body.trim());
+      ctx.output.emit({ id: updated.id, url: updated.url }, () =>
+        ctx.output.success(`Updated comment ${updated.id}`),
+      );
+    }),
+  );
+}
+
+function buildDelete(o: MountOptions): Command {
+  const cmd = new Command("delete").argument("<commentId>").description("Delete a comment");
+  if (o.aliases !== false) cmd.alias("rm");
+  return cmd.action(
+    action(async (ctx: Context, _opts, commentId: string) => {
+      if (!(await confirmDestructive(ctx, `Delete comment ${commentId}?`))) return;
+      const deleted = await svc.deleteComment(ctx.client, commentId);
+      ctx.output.emit({ id: deleted.id, deleted: true }, () =>
+        ctx.output.success(`Deleted comment ${deleted.id}`),
+      );
+    }),
+  );
+}
+
+/** The four verbs the reference CLI mounts under `issue comment`. */
+export const SHARED_COMMENT_VERBS = {
+  add: buildAdd,
+  list: buildList,
+  update: buildUpdate,
+  delete: buildDelete,
+} as const;
+
+export function registerComment(program: Command): void {
+  const comment = program.command("comment").alias("cm").description("Manage comments");
+
+  // add / list / update / delete — shared with `issue comment` -----------------
+  for (const build of Object.values(SHARED_COMMENT_VERBS)) comment.addCommand(build({}));
+
+  // reply -------------------------------------------------------------------
+  comment
+    .command("reply <commentId> [body]")
+    .description("Reply to a comment (nested under it)")
+    .option("--body-file <path>", "read reply body from a file ('-' = stdin)")
+    .action(
+      action(async (ctx: Context, opts, commentId: string, bodyArg?: string) => {
+        const body = resolveBody({ arg: bodyArg, file: opts.bodyFile, interactive: ctx.isTTY });
+        if (!body) throw usageError("No reply body provided.");
+        const { comment: created, issue } = await svc.replyToComment(ctx.client, commentId, body);
+        ctx.output.emit(
+          { id: created.id, parent: commentId, issue: issue?.identifier ?? null, url: created.url },
+          () => ctx.output.success(`Replied to comment${issue ? ` on ${issue.identifier}` : ""}`),
+        );
+      }),
+    );
+
+  // resolve / unresolve -----------------------------------------------------
+  comment
+    .command("resolve <commentId>")
+    .description("Resolve a comment thread")
+    .action(
+      action(async (ctx: Context, _opts, commentId: string) => {
+        const c = await svc.setResolved(ctx.client, commentId, true);
+        ctx.output.emit({ id: c.id, resolved: true }, () =>
+          ctx.output.success(`Resolved comment ${c.id}`),
+        );
+      }),
+    );
+
+  comment
+    .command("unresolve <commentId>")
+    .description("Unresolve a comment thread")
+    .action(
+      action(async (ctx: Context, _opts, commentId: string) => {
+        const c = await svc.setResolved(ctx.client, commentId, false);
+        ctx.output.emit({ id: c.id, resolved: false }, () =>
+          ctx.output.success(`Unresolved comment ${c.id}`),
+        );
+      }),
+    );
+}
+
+/**
+ * Mount `add`/`list`/`update`/`delete` under the existing `issue comment`
+ * command, which keeps its own `[id] [body]` "add a comment" behavior for every
+ * other operand. The short aliases (`ls`, `edit`, `rm`) are deliberately NOT
+ * registered here: each subcommand name shadows a one-word comment body under
+ * the parent, so the collision surface stays at the four names the reference
+ * actually ships.
+ */
+export function registerIssueCommentGroup(issueComment: Command): void {
+  for (const build of Object.values(SHARED_COMMENT_VERBS)) {
+    issueComment.addCommand(build({ aliases: false }));
+  }
+}

package/src/commands/completion.ts

@@ -0,0 +1,69 @@
+/**
+ * `linear completion <shell>` — print a shell completion script to stdout.
+ *
+ * These are static, hand-written completions that defer to the binary for help.
+ * Kept intentionally simple (top-level commands + common flags); they are
+ * generated from the live command tree so they don't drift.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { usageError } from "../lib/errors.js";
+
+export type Shell = "bash" | "zsh" | "fish";
+
+/** Collect top-level command names from the root program. */
+export function topLevelCommands(program: Command): string[] {
+  return program.commands
+    .map((c) => c.name())
+    .filter((n) => n && n !== "completion")
+    .sort();
+}
+
+export function completionScript(shell: Shell, commands: string[]): string {
+  const list = commands.join(" ");
+  switch (shell) {
+    case "bash":
+      return `# linear bash completion. Add to ~/.bashrc:  source <(linear completion bash)
+_linear_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${list}" -- "$cur") )
+  fi
+}
+complete -F _linear_completions linear lin
+`;
+    case "zsh":
+      return `#compdef linear lin
+# linear zsh completion. Add to your fpath or:  source <(linear completion zsh)
+_linear() {
+  local -a cmds
+  cmds=(${commands.map((c) => `'${c}'`).join(" ")})
+  if (( CURRENT == 2 )); then
+    _describe 'command' cmds
+  fi
+}
+compdef _linear linear lin
+`;
+    case "fish":
+      return `# linear fish completion:  linear completion fish > ~/.config/fish/completions/linear.fish
+${commands.map((c) => `complete -c linear -n '__fish_use_subcommand' -a '${c}'`).join("\n")}
+${commands.map((c) => `complete -c lin -n '__fish_use_subcommand' -a '${c}'`).join("\n")}
+`;
+  }
+}
+
+export function registerCompletion(program: Command): void {
+  program
+    .command("completion <shell>")
+    .description("Output a shell completion script (bash|zsh|fish)")
+    .action(
+      action(async (ctx, _opts, shell: string) => {
+        if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+          throw usageError(`Unsupported shell '${shell}'. Use bash, zsh, or fish.`);
+        }
+        const script = completionScript(shell, topLevelCommands(program));
+        process.stdout.write(script);
+      }),
+    );
+}

package/src/commands/cycle.ts

@@ -0,0 +1,125 @@
+/**
+ * `linear cycle` (alias `c`) — work with team cycles (sprints).
+ *
+ * A team is required for list/current/create; it defaults to ctx.defaultTeam
+ * when the optional [team] argument is omitted. `view`/`update` take a cycle id
+ * (UUID), or a number/`current` when a team is in scope.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/cycle.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.CycleRow>[] = [
+  { key: "number", header: "#", value: (r) => r.number },
+  { key: "name", header: "Name", value: (r) => r.name ?? "—", max: 24 },
+  { key: "startsAt", header: "Starts", value: (r) => r.startsAt.slice(0, 10) },
+  { key: "endsAt", header: "Ends", value: (r) => r.endsAt.slice(0, 10) },
+  { key: "progress", header: "Progress", value: (r) => svc.formatProgress(r.progress) },
+];
+
+export function registerCycle(program: Command): void {
+  const cycle = program.command("cycle").alias("c").description("Work with cycles");
+
+  // list --------------------------------------------------------------------
+  cycle
+    .command("list [team]")
+    .alias("ls")
+    .description("List cycles for a team (defaults to the configured team)")
+    .action(
+      action(async (ctx: Context, _opts, teamArg?: string) => {
+        const rows = await svc.listCycles(ctx.client, teamArg, ctx.limit, ctx.defaultTeam);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  cycle
+    .command("view <id>")
+    .description("Show a cycle (by id, number, or 'current')")
+    .action(
+      action(async (ctx: Context, opts, id: string) => {
+        const detail = await svc.getCycleDetail(
+          ctx.client,
+          id,
+          opts.team ?? ctx.defaultTeam,
+          ctx.defaultTeam,
+        );
+        emitDetail(ctx, detail);
+      }),
+    );
+
+  // current -----------------------------------------------------------------
+  cycle
+    .command("current [team]")
+    .description("Show the team's currently active cycle")
+    .action(
+      action(async (ctx: Context, _opts, teamArg?: string) => {
+        const detail = await svc.getCurrentCycle(ctx.client, teamArg, ctx.defaultTeam);
+        emitDetail(ctx, detail);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  cycle
+    .command("create [team]")
+    .alias("new")
+    .description("Create a cycle")
+    .requiredOption("--start <date>", "start date/time (ISO, e.g. 2026-07-01)")
+    .requiredOption("--end <date>", "end date/time (ISO, e.g. 2026-07-14)")
+    .option("--name <name>", "custom cycle name")
+    .action(
+      action(async (ctx: Context, opts, teamArg?: string) => {
+        const created = await svc.createCycle(
+          ctx.client,
+          {
+            team: teamArg ?? opts.team,
+            name: opts.name,
+            startsAt: opts.start,
+            endsAt: opts.end,
+          },
+          ctx.defaultTeam,
+        );
+        ctx.output.emit({ id: created.id, number: created.number }, () =>
+          ctx.output.success(`Created cycle #${created.number}`),
+        );
+      }),
+    );
+
+  // update ------------------------------------------------------------------
+  cycle
+    .command("update <id>")
+    .alias("edit")
+    .description("Update a cycle (by id, number, or 'current')")
+    .option("--name <name>", "custom cycle name")
+    .option("--start <date>", "start date/time (ISO)")
+    .option("--end <date>", "end date/time (ISO)")
+    .action(
+      action(async (ctx: Context, opts, id: string) => {
+        const updated = await svc.updateCycle(
+          ctx.client,
+          id,
+          { name: opts.name, startsAt: opts.start, endsAt: opts.end },
+          opts.team ?? ctx.defaultTeam,
+          ctx.defaultTeam,
+        );
+        ctx.output.emit({ id: updated.id, number: updated.number }, () =>
+          ctx.output.success(`Updated cycle #${updated.number}`),
+        );
+      }),
+    );
+}
+
+function emitDetail(ctx: Context, detail: svc.CycleDetail): void {
+  ctx.output.detail(detail, [
+    ["Cycle", `#${detail.number}${detail.name ? `  ${detail.name}` : ""}`],
+    ["Team", detail.team],
+    ["Starts", detail.startsAt],
+    ["Ends", detail.endsAt],
+    ["Completed", detail.completedAt],
+    ["Progress", svc.formatProgress(detail.progress)],
+    ["Description", detail.description ? `\n${detail.description}` : null],
+  ]);
+}

package/src/commands/discover.ts

@@ -0,0 +1,170 @@
+/**
+ * Discovery commands for agents and scripts:
+ *   - `linear commands` — a machine-readable tree of every (sub)command.
+ *   - `linear schema`   — the Linear GraphQL schema as SDL (or raw introspection
+ *     with --json). `-o <file>` chooses the destination for either format.
+ *
+ * Both are registered last (in cli.ts) so they can introspect the full program.
+ */
+
+import { Command } from "commander";
+import { writeFileSync } from "node:fs";
+import { buildClientSchema, getIntrospectionQuery, printSchema } from "graphql";
+import { action } from "../lib/action.js";
+import { withRetry } from "../client.js";
+import { walkCommands, type CommandNode } from "../lib/introspect.js";
+import { renderOutputShape } from "../lib/shape.js";
+import { usageError, notFound, CliError } from "../lib/errors.js";
+import type { Context } from "../context.js";
+
+/**
+ * `linear commands [path...]` — the command tree (bare array in --json), or one
+ * command by path (bare object) with its options and, since TES-610, the shape
+ * of what it prints under `--json`: `linear commands issue list --json | jq
+ * .output.fields` says a row has `.state.name` before anything is run.
+ */
+export function registerCommands(program: Command): void {
+  program
+    .command("commands [path...]")
+    .description(
+      "List every command in a machine-readable tree, or describe one (for scripts/agents)",
+    )
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear commands --json | jq -r '.[].path'",
+        "  linear commands issue list                       # options + the --json row shape",
+        "  linear commands issue view --json | jq '.output.fields'",
+        "  linear commands --json | jq '.[] | select(.output.kind==\"list\") | .path'",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, _opts, pathWords: string[] = []) => {
+        const nodes = walkCommands(program);
+        if (pathWords.length === 0) {
+          // Bare array in --json; a compact indented listing otherwise.
+          ctx.output.emit(nodes, () => renderTree(ctx, nodes));
+          return;
+        }
+        const path = pathWords.join(" ");
+        const node = nodes.find((n) => n.path === path);
+        if (!node) {
+          const near = nodes.filter((n) => n.path.startsWith(path)).map((n) => n.path);
+          throw notFound(
+            `No command '${path}'.${near.length ? ` Did you mean: ${near.slice(0, 5).join(", ")}?` : " Try 'linear commands' for the list."}`,
+          );
+        }
+        // One command → a bare object in --json (its `output` is the shape a
+        // script wants), a full description otherwise.
+        ctx.output.emit(node, () => {
+          renderOne(ctx, node);
+          const children = nodes.filter((n) => n.path.startsWith(`${path} `));
+          if (children.length) {
+            ctx.output.line();
+            ctx.output.line("Subcommands:");
+            renderTree(ctx, children, path.split(" ").length);
+          }
+        });
+      }),
+    );
+}
+
+/** `<id> [extra...]` from a node's arguments. */
+function usageArgs(n: CommandNode): string {
+  return n.arguments
+    .map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`) + (a.variadic ? "..." : ""))
+    .join(" ");
+}
+
+function renderTree(ctx: Context, nodes: CommandNode[], baseDepth = 0): void {
+  for (const n of nodes) {
+    const depth = n.path.split(" ").length - 1 - baseDepth;
+    const indent = "  ".repeat(depth);
+    const head = [n.path, usageArgs(n)].filter(Boolean).join(" ");
+    const alias = n.aliases.length ? ` (${n.aliases.join(", ")})` : "";
+    ctx.output.line(`${indent}${head}${alias}`);
+    if (n.description) ctx.output.line(`${indent}  ${n.description}`);
+  }
+}
+
+/** One command in full: usage, aliases, options, and the `--json` output shape. */
+function renderOne(ctx: Context, n: CommandNode): void {
+  ctx.output.line(
+    `Usage: linear ${[n.path, n.options.length ? "[options]" : "", usageArgs(n)].filter(Boolean).join(" ")}`,
+  );
+  if (n.description) ctx.output.line(`  ${n.description}`);
+  if (n.aliases.length) ctx.output.line(`Aliases: ${n.aliases.join(", ")}`);
+  if (n.options.length) {
+    ctx.output.line();
+    ctx.output.line("Options:");
+    const width = Math.max(...n.options.map((o) => o.flags.length));
+    for (const o of n.options) ctx.output.line(`  ${o.flags.padEnd(width)}  ${o.description}`);
+  }
+  ctx.output.line();
+  if (n.output) {
+    const [head, ...rest] = renderOutputShape(n.output);
+    ctx.output.line(`Output (--json): ${head}`);
+    for (const line of rest) ctx.output.line(line);
+  } else {
+    ctx.output.line("Output (--json): none of its own (see its subcommands)");
+  }
+}
+
+/** `linear schema` — dump the GraphQL schema as SDL (or raw introspection). */
+export function registerSchema(program: Command): void {
+  program
+    .command("schema")
+    .description("Print the Linear GraphQL schema as SDL (--json prints raw introspection)")
+    .option("-o, --output <file>", "write to a file instead of stdout")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear schema -o /tmp/linear.graphql && grep 'type Issue' /tmp/linear.graphql",
+        "  linear schema | less",
+        "  linear schema --json | jq '.__schema.types | length'",
+        "  linear schema --json -o /tmp/introspection.json",
+      ].join("\n"),
+    )
+    .action(action(runSchema));
+}
+
+/** The `schema` action body, exported so tests can drive it against a fake client. */
+export async function runSchema(ctx: Context, opts: Record<string, any>): Promise<void> {
+  const result: any = await withRetry(() =>
+    (ctx.client.client as any).rawRequest(getIntrospectionQuery()),
+  );
+  const introspection = result.data;
+  if (!introspection) throw usageError("Introspection returned no schema data.");
+
+  // Format and destination are independent: --json picks the format, -o picks
+  // where it lands. (The JSON branch used to return before reaching the write,
+  // so `--json -o file` printed to stdout and left no file.)
+  const json = ctx.output.json;
+  if (opts.output) {
+    const body = json
+      ? JSON.stringify(introspection, null, 2)
+      : printSchema(buildClientSchema(introspection));
+    writeSchemaFile(opts.output, body + "\n");
+    ctx.output.success(`Wrote ${json ? "introspection JSON" : "schema"} to ${opts.output}`);
+    return;
+  }
+
+  if (json) {
+    // Raw introspection result — bare object on stdout.
+    ctx.output.emit(introspection, () => {});
+    return;
+  }
+  ctx.output.line(printSchema(buildClientSchema(introspection)));
+}
+
+function writeSchemaFile(path: string, body: string): void {
+  try {
+    writeFileSync(path, body, "utf8");
+  } catch (err) {
+    throw new CliError(`Cannot write to '${path}': ${(err as Error).message}`, "runtime");
+  }
+}