linear-sdk-cli 0.1.0

package/src/commands/document.ts

@@ -0,0 +1,211 @@
+/**
+ * `linear document` (alias `doc`) — work with documents.
+ *
+ * A document is attached to exactly one target: a project, issue, initiative,
+ * team, cycle or release. `create` needs one (`--project`, `--issue`,
+ * `--initiative`, `--team`, `--cycle`, `--release`; the configured team is the
+ * fallback), `list` can filter by one, and `update` can re-point to one.
+ * `--team` is the global flag: alone it names the team; with `--cycle` it
+ * scopes the cycle lookup, as on the issue commands.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { resolveBody } from "../lib/body.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import { CYCLE_FLAG } from "../lib/options.js";
+import { firstTeam, type Context } from "../context.js";
+import * as svc from "../services/document.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.DocumentRow>[] = [
+  { key: "title", header: "Title", value: (r) => r.title, max: 50 },
+  { key: "target", header: "Attached to", value: (r) => svc.describeTarget(r) ?? "—", max: 40 },
+  { key: "updatedAt", header: "Updated", value: (r) => r.updatedAt.slice(0, 10) },
+];
+
+/**
+ * The six target flags, on `create`/`list`/`update` alike, worded for the verb.
+ * `--team` is not declared here: it is the global `-t, --team`, read back off
+ * the merged options so it works in either position (`linear -t ENG doc …`).
+ */
+function addTargetOptions(cmd: Command, verb: string): Command {
+  return cmd
+    .option("-p, --project <name>", `${verb} a project (name or id)`)
+    .option("--issue <id>", `${verb} an issue (identifier or id)`)
+    .option("--initiative <name>", `${verb} an initiative (name or id)`)
+    .option(
+      CYCLE_FLAG,
+      `${verb} a cycle (number, name, id, or 'current'; team from --team or config)`,
+    )
+    .option("--release <name>", `${verb} a release (name, version, or id)`);
+}
+
+/** The target flags as typed, with `--team` taken from wherever on the command line it sat. */
+function targetOptions(ctx: Context, opts: Record<string, any>): svc.DocumentTargetOptions {
+  return {
+    project: opts.project,
+    issue: opts.issue,
+    initiative: opts.initiative,
+    team: firstTeam(ctx.options.team),
+    cycle: opts.cycle,
+    release: opts.release,
+  };
+}
+
+export function registerDocument(program: Command): void {
+  const document = program.command("document").alias("doc").description("Work with documents");
+
+  // list --------------------------------------------------------------------
+  const list = document
+    .command("list")
+    .alias("ls")
+    .description("List workspace documents (optionally only those attached to one target)")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear document list --project Roadmap",
+        "  linear document list --issue TES-42",
+        "  linear document list --team ENG            # the team's own documents",
+        "  linear document list --cycle current       # in the configured team's active cycle",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts) => {
+        // A configured default team does not filter here — documents are
+        // workspace-wide, and hiding project documents behind a repo's team
+        // would be a surprise. Only an explicit --team narrows.
+        const rows = await svc.listDocuments(
+          ctx.client,
+          ctx.limit,
+          targetOptions(ctx, opts),
+          ctx.config.team,
+        );
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+  addTargetOptions(list, "only documents attached to");
+
+  // view --------------------------------------------------------------------
+  document
+    .command("view <id>", { isDefault: true })
+    .alias("show")
+    .description("Show a document, including its markdown content")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const detail = await svc.getDocumentDetail(ctx.client, idArg);
+        ctx.output.detail(detail, [
+          ["Document", detail.title],
+          ["Attached to", svc.describeTarget(detail)],
+          ["Creator", detail.creator?.displayName ?? null],
+          ["URL", detail.url],
+          ["Updated", detail.updatedAt],
+          ["Content", detail.content ? `\n${detail.content}` : null],
+        ]);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  const create = document
+    .command("create")
+    .alias("new")
+    .description(
+      "Create a new document, attached to one target (--project, --issue, --initiative, --team, --cycle, or --release; default: the configured team)",
+    )
+    .option("--title <title>", "document title")
+    .option("--content <text>", "document content (markdown body)")
+    .option("--content-file <path>", "read content from a file ('-' = stdin)")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear document create --title 'Spec' --project Roadmap --content-file spec.md",
+        "  linear document create --title 'Notes' --issue TES-42",
+        "  linear document create --title 'Retro' --cycle current --team ENG",
+        "  linear document create --title 'Handbook'          # attached to the configured team",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts) => {
+        // Validate the target flags before the title prompt or any file read.
+        const target = targetOptions(ctx, opts);
+        // The configured team is the fallback target — for create only — when
+        // no target flag names one; it never overrides one that does.
+        if (!svc.selectTarget(target) && ctx.config.team) target.team = ctx.config.team;
+        let title: string | undefined = opts.title;
+        if (!title) title = await promptInput(ctx, "Title:", { required: true });
+        const content = resolveBody({
+          arg: opts.content,
+          file: opts.contentFile,
+          interactive: false,
+        });
+        const created = await svc.createDocument(
+          ctx.client,
+          { title, content, ...target },
+          ctx.config.team,
+        );
+        ctx.output.emit({ id: created.id, title: created.title, url: created.url }, () =>
+          ctx.output.success(`Created ${created.title}: ${created.url}`),
+        );
+      }),
+    );
+  addTargetOptions(create, "attach to");
+
+  // update ------------------------------------------------------------------
+  const update = document
+    .command("update <id>")
+    .alias("edit")
+    .description("Update a document's title or content, or re-point it to another target")
+    .option("--title <title>", "new title")
+    .option("--content <text>", "new content (markdown body)")
+    .option("--content-file <path>", "read content from a file ('-' = stdin)")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear document update <id> --title 'Spec v2'",
+        "  linear document update <id> --content-file spec.md",
+        "  linear document update <id> --issue TES-42       # move it onto the issue (replaces the old target)",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        const content = resolveBody({
+          arg: opts.content,
+          file: opts.contentFile,
+          interactive: false,
+        });
+        // Only the explicit --team re-points; a configured team never does.
+        const updated = await svc.updateDocument(
+          ctx.client,
+          idArg,
+          { title: opts.title, content, ...targetOptions(ctx, opts) },
+          ctx.config.team,
+        );
+        ctx.output.emit({ id: updated.id, title: updated.title, url: updated.url }, () =>
+          ctx.output.success(`Updated ${updated.title}`),
+        );
+      }),
+    );
+  addTargetOptions(update, "re-point to");
+
+  // delete ------------------------------------------------------------------
+  document
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete (trash) a document")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const doc = await svc.getDocumentDetail(ctx.client, idArg);
+        if (!(await confirmDestructive(ctx, `Delete document ${doc.title}?`))) return;
+        const deleted = await svc.deleteDocument(ctx.client, doc.id);
+        ctx.output.emit({ id: deleted.id, title: deleted.title, deleted: true }, () =>
+          ctx.output.success(`Deleted ${deleted.title}`),
+        );
+      }),
+    );
+}

package/src/commands/favorite.ts

@@ -0,0 +1,72 @@
+/**
+ * `linear favorite` (alias `fav`) — manage the viewer's favorites.
+ *
+ * `list` shows each favorite's type and the referenced thing's title. `add`
+ * takes exactly one of --issue / --project / --document. `remove` deletes a
+ * favorite by its id (confirmed when destructive).
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { confirmDestructive } from "../lib/prompt.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/favorite.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.FavoriteRow>[] = [
+  { key: "type", header: "Type", value: (r) => r.type, max: 16 },
+  { key: "name", header: "Name", value: (r) => r.name, max: 60 },
+  { key: "id", header: "ID", value: (r) => r.id },
+];
+
+export function registerFavorite(program: Command): void {
+  const favorite = program.command("favorite").alias("fav").description("Manage your favorites");
+
+  // list --------------------------------------------------------------------
+  favorite
+    .command("list")
+    .alias("ls")
+    .description("List your favorites")
+    .action(
+      action(async (ctx: Context) => {
+        const rows = await svc.listFavorites(ctx.client, ctx.limit);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // add ---------------------------------------------------------------------
+  favorite
+    .command("add")
+    .alias("new")
+    .description("Favorite an issue, project, or document (exactly one)")
+    .option("--issue <id>", "issue id or identifier (e.g. TES-123)")
+    .option("--project <id|name>", "project name or id")
+    .option("--document <id>", "document id (UUID)")
+    .action(
+      action(async (ctx: Context, opts) => {
+        const created = await svc.addFavorite(ctx.client, {
+          issue: opts.issue,
+          project: opts.project,
+          document: opts.document,
+        });
+        ctx.output.emit({ id: created.id, type: created.type }, () =>
+          ctx.output.success(`Favorited ${created.type} (${created.id})`),
+        );
+      }),
+    );
+
+  // remove ------------------------------------------------------------------
+  favorite
+    .command("remove <favoriteId>")
+    .alias("rm")
+    .description("Remove a favorite by id")
+    .action(
+      action(async (ctx: Context, _opts, favoriteId: string) => {
+        if (!(await confirmDestructive(ctx, `Remove favorite ${favoriteId}?`))) return;
+        const removed = await svc.removeFavorite(ctx.client, favoriteId);
+        ctx.output.emit({ id: removed.id, removed: true }, () =>
+          ctx.output.success(`Removed favorite ${removed.id}`),
+        );
+      }),
+    );
+}

package/src/commands/initiative-update.ts

@@ -0,0 +1,47 @@
+/**
+ * `linear initiative-update` (alias `iu`) — post and list initiative status updates.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { addUpdateFlags, resolveUpdateBody, UPDATE_COLUMNS } from "../lib/status-update.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/initiative-update.js";
+
+export function registerInitiativeUpdate(program: Command): void {
+  const group = program
+    .command("initiative-update")
+    .alias("iu")
+    .description("Post and list initiative status updates");
+
+  // create ------------------------------------------------------------------
+  addUpdateFlags(
+    group
+      .command("create <initiative>")
+      .alias("new")
+      .description("Post a status update on an initiative (by name or id)"),
+  ).action(
+    action(async (ctx: Context, opts, initiativeArg: string) => {
+      const body = resolveUpdateBody(ctx, opts);
+      const created = await svc.createInitiativeUpdate(ctx.client, initiativeArg, {
+        body,
+        health: opts.health,
+      });
+      ctx.output.emit(created, () =>
+        ctx.output.success(`Posted initiative update${opts.health ? ` (${opts.health})` : ""}`),
+      );
+    }),
+  );
+
+  // list --------------------------------------------------------------------
+  group
+    .command("list <initiative>")
+    .alias("ls")
+    .description("List an initiative's status updates")
+    .action(
+      action(async (ctx: Context, _opts, initiativeArg: string) => {
+        const rows = await svc.listInitiativeUpdates(ctx.client, initiativeArg, ctx.limit);
+        ctx.output.list(rows, UPDATE_COLUMNS, rows);
+      }),
+    );
+}

package/src/commands/initiative.ts

@@ -0,0 +1,261 @@
+/**
+ * `linear initiative` (alias `init`) — work with workspace initiatives.
+ *
+ * Initiatives are workspace-scoped (no team). `view`/`update`/`archive`/`delete`
+ * take an initiative id (UUID) or name; `create` needs a name and optionally a
+ * description, target date, owner, and status.
+ */
+
+import { Command, Option } from "commander";
+import { action } from "../lib/action.js";
+import { resolveBody } from "../lib/body.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import { parseList, parseIntOption, addAliasOption, readAlias } from "../lib/options.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/initiative.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.InitiativeRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.name, max: 40 },
+  { key: "status", header: "Status", value: (r) => r.status ?? "—", max: 12 },
+  {
+    key: "priority",
+    header: "Pri",
+    value: (r) => (r.priority ? svc.priorityLabel(r.priority) : "—"),
+  },
+  { key: "targetDate", header: "Target", value: (r) => r.targetDate ?? "—" },
+  { key: "health", header: "Health", value: (r) => r.health ?? "—", max: 12 },
+];
+
+export function registerInitiative(program: Command): void {
+  const initiative = program
+    .command("initiative")
+    .alias("init")
+    .description("Work with initiatives");
+
+  // list --------------------------------------------------------------------
+  initiative
+    .command("list")
+    .alias("ls")
+    .description("List workspace initiatives (every status unless --status narrows)")
+    // No `-s`/`-o` shorts: `-s` is `--state` and `-o` is `--output` elsewhere
+    // in the tree, and a short flag means one thing everywhere here.
+    .option("--status <name>", "filter by status (Planned, Active, Completed, Canceled, Proposed)")
+    .option("--owner <who>", "filter by owner (me|email|name|id)")
+    .option("--archived", "include archived initiatives")
+    // The reference CLI lists Active only and needs `--all-statuses` to widen;
+    // this list is every status already, so the flag is accepted as the no-op
+    // it is here rather than failing a transplanted script.
+    .addOption(new Option("--all-statuses", "no-op: the list is all statuses").hideHelp())
+    .action(
+      action(async (ctx: Context, opts) => {
+        const rows = await svc.listInitiatives(ctx.client, ctx.limit, {
+          status: opts.status,
+          owner: opts.owner,
+          archived: !!opts.archived,
+        });
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  initiative
+    .command("view <id>", { isDefault: true })
+    .alias("show")
+    .description("Show an initiative (by name or id)")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const detail = await svc.getInitiativeDetail(ctx.client, idArg);
+        ctx.output.detail(detail, [
+          ["Initiative", detail.name],
+          ["Archived", detail.archivedAt ? `YES (${detail.archivedAt})` : null],
+          ["Status", detail.status],
+          ["Priority", detail.priority ? detail.priorityLabel : null],
+          ["Labels", detail.labels.length ? detail.labels.join(", ") : null],
+          ["Health", detail.health],
+          ["Owner", detail.owner],
+          ["Creator", detail.creator],
+          ["Target", detail.targetDate],
+          ["Icon", detail.icon],
+          ["Color", detail.color],
+          [
+            "Projects",
+            detail.projects.length
+              ? detail.projects
+                  .map((p) => `${p.name}${p.status ? ` (${p.status.name})` : ""}`)
+                  .join(", ")
+              : null,
+          ],
+          ["URL", detail.url],
+          ["Updated", detail.updatedAt],
+          ["Description", detail.description ? `\n${detail.description}` : null],
+        ]);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  const create = initiative
+    .command("create")
+    .alias("new")
+    .description("Create a new initiative")
+    .option("--name <name>", "initiative name")
+    .option("-d, --description <text>", "initiative description")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--target <date>", "estimated completion date (YYYY-MM-DD)")
+    .option("--owner <who>", "initiative owner (me|email|name|id)")
+    .option("--status <name>", "status (Planned, Active, Completed, Canceled, Proposed)")
+    .option("-P, --priority <0-4>", "priority (0 none, 1 urgent … 4 low)", parseIntOption)
+    .option("-l, --label <name>", "initiative label (repeatable / comma-separated)", parseList)
+    .option("--icon <name>", "Linear icon name, capitalized (e.g. Rocket)")
+    .option("--color <hex>", "initiative color (e.g. #5E6AD2)")
+    .action(
+      action(async (ctx: Context, opts) => {
+        let name: string | undefined = opts.name;
+        if (!name) name = await promptInput(ctx, "Name:", { required: true });
+        const description = resolveBody({
+          arg: opts.description,
+          file: opts.descriptionFile,
+          interactive: false,
+        });
+        const created = await svc.createInitiative(ctx.client, {
+          name,
+          description,
+          targetDate: readAlias(opts, "--target", "--target-date"),
+          owner: opts.owner,
+          status: opts.status,
+          priority: opts.priority,
+          label: opts.label,
+          icon: opts.icon,
+          color: opts.color,
+        });
+        ctx.output.emit({ id: created.id, name: created.name, url: created.url }, () =>
+          ctx.output.success(`Created ${created.name}: ${created.url}`),
+        );
+      }),
+    );
+  addAliasOption(create, "--target-date <date>", "--target");
+
+  // update ------------------------------------------------------------------
+  const update = initiative
+    .command("update <id>")
+    .alias("edit")
+    .description("Update an initiative")
+    .option("--name <name>", "new name")
+    .option("-d, --description <text>", "new description")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--target <date>", "estimated completion date (YYYY-MM-DD)")
+    .option("--owner <who>", "initiative owner (me|email|name|id)")
+    .option("--status <name>", "status (Planned, Active, Completed, Canceled, Proposed)")
+    .option("-P, --priority <0-4>", "priority (0 none, 1 urgent … 4 low)", parseIntOption)
+    .option("-l, --label <name>", "replace the labels (repeatable / comma-separated)", parseList)
+    .option("--icon <name>", "Linear icon name, capitalized (e.g. Rocket)")
+    .option("--color <hex>", "initiative color (e.g. #5E6AD2)")
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        const description = resolveBody({
+          arg: opts.description,
+          file: opts.descriptionFile,
+          interactive: false,
+        });
+        const updated = await svc.updateInitiative(ctx.client, idArg, {
+          name: opts.name,
+          description,
+          targetDate: readAlias(opts, "--target", "--target-date"),
+          owner: opts.owner,
+          status: opts.status,
+          priority: opts.priority,
+          label: opts.label,
+          icon: opts.icon,
+          color: opts.color,
+        });
+        ctx.output.emit({ id: updated.id, name: updated.name, url: updated.url }, () =>
+          ctx.output.success(`Updated ${updated.name}`),
+        );
+      }),
+    );
+  addAliasOption(update, "--target-date <date>", "--target");
+
+  // archive -----------------------------------------------------------------
+  initiative
+    .command("archive <id>")
+    .description("Archive an initiative")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const init = await svc.getInitiativeDetail(ctx.client, idArg);
+        if (!(await confirmDestructive(ctx, `Archive initiative ${init.name}?`))) return;
+        const archived = await svc.archiveInitiative(ctx.client, init.id);
+        ctx.output.emit({ id: archived.id, name: archived.name, archived: true }, () =>
+          ctx.output.success(`Archived ${archived.name}`),
+        );
+      }),
+    );
+
+  // unarchive ---------------------------------------------------------------
+  initiative
+    .command("unarchive <id>")
+    .description("Unarchive an initiative")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const restored = await svc.unarchiveInitiative(ctx.client, idArg);
+        ctx.output.emit({ id: restored.id, name: restored.name, archived: false }, () =>
+          ctx.output.success(`Unarchived ${restored.name}`),
+        );
+      }),
+    );
+
+  // add-project / remove-project --------------------------------------------
+  initiative
+    .command("add-project <initiative> <project>")
+    .description("Link a project to an initiative")
+    .option("--sort-order <n>", "position among the initiative's projects", parseIntOption)
+    .addHelpText(
+      "after",
+      ["", "Examples:", "  linear initiative add-project 'Q3 Bets' 'API v2'"].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts, initiativeArg: string, projectArg: string) => {
+        const link = await svc.addProject(ctx.client, initiativeArg, projectArg, {
+          sortOrder: opts.sortOrder,
+        });
+        ctx.output.emit(link, () =>
+          ctx.output.success(`Linked ${link.project.name} to ${link.initiative.name}`),
+        );
+      }),
+    );
+
+  initiative
+    .command("remove-project <initiative> <project>")
+    .description("Unlink a project from an initiative")
+    .action(
+      action(async (ctx: Context, _opts, initiativeArg: string, projectArg: string) => {
+        const link = await svc.findProjectLink(ctx.client, initiativeArg, projectArg);
+        if (
+          !(await confirmDestructive(
+            ctx,
+            `Remove ${link.project.name} from initiative ${link.initiative.name}?`,
+          ))
+        )
+          return;
+        await svc.removeProjectLink(ctx.client, link);
+        ctx.output.emit({ ...link, removed: true }, () =>
+          ctx.output.success(`Removed ${link.project.name} from ${link.initiative.name}`),
+        );
+      }),
+    );
+
+  // delete ------------------------------------------------------------------
+  initiative
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete (trash) an initiative")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const init = await svc.getInitiativeDetail(ctx.client, idArg);
+        if (!(await confirmDestructive(ctx, `Delete initiative ${init.name}?`))) return;
+        const deleted = await svc.deleteInitiative(ctx.client, init.id);
+        ctx.output.emit({ id: deleted.id, name: deleted.name, deleted: true }, () =>
+          ctx.output.success(`Deleted ${deleted.name}`),
+        );
+      }),
+    );
+}