linear-sdk-cli 0.1.0

package/src/commands/team.ts

@@ -0,0 +1,243 @@
+/**
+ * `linear team` (alias `t`) — inspect and manage teams.
+ *
+ * The team key argument is optional on the sub-resource and view commands and
+ * falls back to the configured default team (ctx.defaultTeam) when omitted.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/team.js";
+import { noteAllIsPagination, ALL_VS_INCLUDE_DISABLED_HELP } from "./user.js";
+import type { Column } from "../output/table.js";
+
+const TEAM_COLUMNS: Column<svc.TeamRow>[] = [
+  { key: "key", header: "Key", value: (r) => r.key },
+  { key: "name", header: "Name", value: (r) => r.name, max: 40 },
+  { key: "id", header: "ID", value: (r) => r.id },
+];
+
+const MEMBER_COLUMNS: Column<svc.MemberRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.displayName, max: 24 },
+  { key: "email", header: "Email", value: (r) => r.email, max: 40 },
+  { key: "active", header: "Active", value: (r) => (r.active ? "yes" : "no") },
+];
+
+const STATE_COLUMNS: Column<svc.StateRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.name, max: 24 },
+  { key: "type", header: "Type", value: (r) => r.type },
+  { key: "color", header: "Color", value: (r) => r.color },
+  { key: "position", header: "Pos", value: (r) => r.position },
+];
+
+const LABEL_COLUMNS: Column<svc.LabelRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.name, max: 30 },
+  { key: "color", header: "Color", value: (r) => r.color },
+];
+
+const CYCLE_COLUMNS: Column<svc.CycleRow>[] = [
+  { key: "number", header: "#", value: (r) => r.number },
+  { key: "name", header: "Name", value: (r) => r.name ?? "—", max: 30 },
+  { key: "startsAt", header: "Starts", value: (r) => (r.startsAt ? r.startsAt.slice(0, 10) : "—") },
+  { key: "endsAt", header: "Ends", value: (r) => (r.endsAt ? r.endsAt.slice(0, 10) : "—") },
+];
+
+export function registerTeam(program: Command): void {
+  const team = program.command("team").alias("t").description("Inspect and manage teams");
+
+  // list --------------------------------------------------------------------
+  team
+    .command("list")
+    .alias("ls")
+    .description("List all teams")
+    .action(
+      action(async (ctx: Context) => {
+        const rows = await svc.listTeams(ctx.client, ctx.limit);
+        ctx.output.list(rows, TEAM_COLUMNS, rows);
+      }),
+    );
+
+  // id ----------------------------------------------------------------------
+  team
+    .command("id [key]")
+    .description("Print a team's UUID (defaults to the configured team)")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const resolved = await svc.getTeamIdentity(ctx.client, keyArg, ctx.defaultTeam);
+        // Human mode is deliberately a single UUID for command substitution;
+        // JSON retains the resolved key and name as useful context.
+        ctx.output.emit(resolved, () => process.stdout.write(resolved.id + "\n"));
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  team
+    .command("view [key]")
+    .description("Show a team (defaults to the configured team)")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const detail = await svc.getTeamDetail(ctx.client, keyArg, ctx.defaultTeam);
+        ctx.output.detail(detail, [
+          ["Team", `${detail.key}  ${detail.name}`],
+          ["ID", detail.id],
+          ["Description", detail.description],
+          ["Members", detail.memberCount],
+          ["Issues", detail.issueCount],
+          ["Cycles enabled", detail.cyclesEnabled ? "yes" : "no"],
+          ["Private", detail.private ? "yes" : "no"],
+          ["Timezone", detail.timezone],
+          ["Color", detail.color],
+          ["Created", detail.createdAt],
+          ["Updated", detail.updatedAt],
+        ]);
+      }),
+    );
+
+  // members -----------------------------------------------------------------
+  team
+    .command("members [key]")
+    .description("List a team's members")
+    .option("--include-disabled", "include deactivated users (excluded by default)")
+    .addHelpText("after", ALL_VS_INCLUDE_DISABLED_HELP)
+    .action(
+      action(async (ctx: Context, opts, keyArg?: string) => {
+        // schpet's `--all` here means "inactive too"; ours is pagination. Say so.
+        noteAllIsPagination(ctx, !!opts.includeDisabled);
+        const rows = await svc.listMembers(
+          ctx.client,
+          keyArg,
+          ctx.defaultTeam,
+          ctx.limit,
+          !!opts.includeDisabled,
+        );
+        ctx.output.list(rows, MEMBER_COLUMNS, rows);
+      }),
+    );
+
+  // states ------------------------------------------------------------------
+  team
+    .command("states [key]")
+    .description("List a team's workflow states")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const rows = await svc.listStates(ctx.client, keyArg, ctx.defaultTeam, ctx.limit);
+        ctx.output.list(rows, STATE_COLUMNS, rows);
+      }),
+    );
+
+  // labels ------------------------------------------------------------------
+  team
+    .command("labels [key]")
+    .description("List a team's labels")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const rows = await svc.listLabels(ctx.client, keyArg, ctx.defaultTeam, ctx.limit);
+        ctx.output.list(rows, LABEL_COLUMNS, rows);
+      }),
+    );
+
+  // cycles ------------------------------------------------------------------
+  team
+    .command("cycles [key]")
+    .description("List a team's cycles")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const rows = await svc.listCycles(ctx.client, keyArg, ctx.defaultTeam, ctx.limit);
+        ctx.output.list(rows, CYCLE_COLUMNS, rows);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  team
+    .command("create")
+    .alias("new")
+    .description("Create a new team")
+    .option("--name <name>", "team name")
+    .option("--key <key>", "team key (e.g. ENG); generated from the name if omitted")
+    .option("-d, --description <text>", "team description")
+    .option("--private", "make the team private (members only)")
+    .action(
+      action(async (ctx: Context, opts) => {
+        let name: string | undefined = opts.name;
+        if (!name) name = await promptInput(ctx, "Name:", { required: true });
+        const created = await svc.createTeam(ctx.client, {
+          name,
+          key: opts.key,
+          description: opts.description,
+          private: !!opts.private,
+        });
+        ctx.output.emit({ id: created.id, key: created.key, name: created.name }, () =>
+          ctx.output.success(`Created team ${created.key} (${created.name})`),
+        );
+      }),
+    );
+
+  // update ------------------------------------------------------------------
+  team
+    .command("update [key]")
+    .alias("edit")
+    .description("Update a team (defaults to the configured team)")
+    .option("--name <name>", "new team name")
+    .option("--key <key>", "new team key")
+    .option("-d, --description <text>", "new team description")
+    .action(
+      action(async (ctx: Context, opts, keyArg?: string) => {
+        const updated = await svc.updateTeam(ctx.client, keyArg, ctx.defaultTeam, {
+          name: opts.name,
+          key: opts.key,
+          description: opts.description,
+        });
+        ctx.output.emit({ id: updated.id, key: updated.key, name: updated.name }, () =>
+          ctx.output.success(`Updated team ${updated.key}`),
+        );
+      }),
+    );
+
+  // delete ------------------------------------------------------------------
+  // The key is required here, unlike the other team commands: a delete that
+  // silently fell back to the configured default team would be a disaster.
+  team
+    .command("delete <key>")
+    .alias("rm")
+    .description("Delete a team (admin); its issues go with it unless --move-issues")
+    .option("--move-issues <team>", "move the team's issues to another team first")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear team delete OLD --move-issues ENG",
+        "  linear team delete SCRATCH --yes",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts, keyArg: string) => {
+        const plan = await svc.planDeleteTeam(ctx.client, keyArg, opts.moveIssues);
+        const { team: t, issueCount, moveTo } = plan;
+        const issues = `${issueCount} issue${issueCount === 1 ? "" : "s"}`;
+        const question = moveTo
+          ? `Delete team ${t.key} (${t.name}), moving its ${issues} to ${moveTo.key} first?`
+          : `Delete team ${t.key} (${t.name}) and its ${issues}?`;
+        if (!(await confirmDestructive(ctx, question))) return;
+        let moved = 0;
+        if (moveTo && issueCount > 0) {
+          moved = await svc.moveTeamIssues(ctx.client, t, moveTo);
+          ctx.output.info(`Moved ${moved} issue${moved === 1 ? "" : "s"} to ${moveTo.key}`);
+        }
+        await svc.deleteTeam(ctx.client, t);
+        ctx.output.emit(
+          {
+            id: t.id,
+            key: t.key,
+            name: t.name,
+            deleted: true,
+            movedIssues: moved,
+            movedTo: moveTo ? { id: moveTo.id, key: moveTo.key, name: moveTo.name } : null,
+          },
+          () => ctx.output.success(`Deleted team ${t.key} (${t.name})`),
+        );
+      }),
+    );
+}

package/src/commands/user.ts

@@ -0,0 +1,107 @@
+/**
+ * `linear user` (alias `u`) — inspect workspace users. Read-only group.
+ *
+ * `view` accepts `me`, an email, a display/full name, or an id (all handled by
+ * `resolveUserId`); `me` is a convenience alias for `view me`.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/user.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.UserRow>[] = [
+  { key: "displayName", header: "Name", value: (r) => r.displayName, max: 24 },
+  { key: "email", header: "Email", value: (r) => r.email, max: 40 },
+  { key: "active", header: "Active", value: (r) => (r.active ? "yes" : "no") },
+  { key: "admin", header: "Admin", value: (r) => (r.admin ? "yes" : "no") },
+];
+
+/**
+ * `--all` on a member listing, without `--include-disabled`.
+ *
+ * schpet/linear-cli spells "include inactive members" as `-a/--all` on `user
+ * list` and `team members`. Ours is the global `--all` — exhaust pagination —
+ * so a transplanted `linear user list --all` succeeds, and the deactivated
+ * users it was asking for are quietly missing (TES-637 item 1). The global
+ * keeps its one meaning (making it mean "and deactivated" here alone would be a
+ * second meaning for one flag, the thing ALIGNMENT.md refuses); instead the
+ * combination says what it did and names the flag that does the other thing.
+ * A warning, not `info`: it survives `--quiet`, because a script is exactly
+ * where a wrong result set goes unnoticed. Shared with `team members`.
+ */
+export function noteAllIsPagination(ctx: Context, includeDisabled: boolean): void {
+  if (ctx.options.all === true && !includeDisabled) {
+    ctx.output.warn(
+      "--all exhausts pagination here; deactivated users are still excluded — pass --include-disabled to list them.",
+    );
+  }
+}
+
+/** The help footer both member listings carry, so the difference is loud before it is hit. */
+export const ALL_VS_INCLUDE_DISABLED_HELP = [
+  "",
+  "Note: --all is the global 'fetch every page'. Deactivated users need --include-disabled",
+  "(schpet/linear-cli's --all).",
+].join("\n");
+
+export function registerUser(program: Command): void {
+  const user = program.command("user").alias("u").description("Inspect workspace users");
+
+  // list --------------------------------------------------------------------
+  user
+    .command("list")
+    .alias("ls")
+    .description("List workspace users")
+    .option("--include-disabled", "include deactivated users (excluded by default)")
+    .addHelpText("after", ALL_VS_INCLUDE_DISABLED_HELP)
+    .action(
+      action(async (ctx: Context, opts) => {
+        noteAllIsPagination(ctx, !!opts.includeDisabled);
+        const rows = await svc.listUsers(ctx.client, ctx.limit, !!opts.includeDisabled);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  user
+    .command("view <who>")
+    .description("Show a user (me, email, name, or id)")
+    .action(
+      action(async (ctx: Context, _opts, who: string) => {
+        const detail = await svc.getUserDetail(ctx.client, who);
+        emitDetail(ctx, detail);
+      }),
+    );
+
+  // me ----------------------------------------------------------------------
+  user
+    .command("me")
+    .description("Show the authenticated viewer")
+    .action(
+      action(async (ctx: Context) => {
+        const detail = await svc.getViewer(ctx.client);
+        emitDetail(ctx, detail);
+      }),
+    );
+}
+
+function emitDetail(ctx: Context, detail: svc.UserDetail): void {
+  ctx.output.detail(detail, [
+    ["User", `${detail.displayName}  ${detail.name}`],
+    ["ID", detail.id],
+    ["Email", detail.email],
+    ["Active", detail.active ? "yes" : "no"],
+    ["Admin", detail.admin ? "yes" : "no"],
+    ["Guest", detail.guest ? "yes" : "no"],
+    ["You", detail.isMe ? "yes" : null],
+    ["Status", detail.statusLabel],
+    ["Description", detail.description],
+    ["Timezone", detail.timezone],
+    ["Last seen", detail.lastSeen],
+    ["URL", detail.url],
+    ["Created", detail.createdAt],
+    ["Updated", detail.updatedAt],
+  ]);
+}

package/src/commands/webhook.ts

@@ -0,0 +1,156 @@
+/**
+ * `linear webhook` (alias `wh`) — manage workspace webhooks.
+ *
+ * Webhooks are workspace-scoped; `create` may scope one to a single team via the
+ * global -t/--team (read from ctx.defaultTeam — there is no local --team option,
+ * which would collide). `--resource` is repeatable (collectArray) and required.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { collectArray } from "../lib/options.js";
+import { confirmDestructive } from "../lib/prompt.js";
+import { usageError } from "../lib/errors.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/webhook.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.WebhookRow>[] = [
+  { key: "id", header: "ID", value: (r) => r.id },
+  { key: "url", header: "URL", value: (r) => r.url ?? "—", max: 40 },
+  { key: "enabled", header: "Enabled", value: (r) => (r.enabled ? "yes" : "no") },
+  {
+    key: "resourceTypes",
+    header: "Resources",
+    value: (r) => (r.resourceTypes.length ? r.resourceTypes.join(", ") : "—"),
+    max: 40,
+  },
+];
+
+export function registerWebhook(program: Command): void {
+  const webhook = program.command("webhook").alias("wh").description("Manage workspace webhooks");
+
+  // list --------------------------------------------------------------------
+  webhook
+    .command("list")
+    .alias("ls")
+    .description("List webhooks")
+    .action(
+      action(async (ctx: Context) => {
+        const rows = await svc.listWebhooks(ctx.client, ctx.limit);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  webhook
+    .command("view <id>", { isDefault: true })
+    .alias("show")
+    .description("Show a webhook")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const detail = await svc.getWebhookDetail(ctx.client, idArg);
+        ctx.output.detail(detail, [
+          ["Webhook", detail.id],
+          ["URL", detail.url],
+          ["Enabled", detail.enabled ? "yes" : "no"],
+          ["Resources", detail.resourceTypes.length ? detail.resourceTypes.join(", ") : null],
+          ["Label", detail.label],
+          ["All public teams", detail.allPublicTeams ? "yes" : "no"],
+          ["Team", detail.team],
+          ["Creator", detail.creator],
+          ["Created", detail.createdAt],
+          ["Updated", detail.updatedAt],
+        ]);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  webhook
+    .command("create")
+    .alias("new")
+    .description("Create a webhook (scope to the global --team, or --all-public)")
+    .option("--url <url>", "destination URL that receives event payloads")
+    .option("--resource <type...>", "resource type to subscribe to (repeatable)", collectArray)
+    .option("--label <label>", "human-readable label for the webhook")
+    .option("--all-public", "subscribe to all public teams in the workspace")
+    .option("--secret <secret>", "secret used to sign webhook payloads")
+    .action(
+      action(async (ctx: Context, opts) => {
+        if (!opts.url) throw usageError("A webhook needs a --url.");
+        const resourceTypes: string[] = opts.resource ?? [];
+        if (!resourceTypes.length)
+          throw usageError("Pass at least one --resource (e.g. Issue, Comment, Project).");
+        const created = await svc.createWebhook(ctx.client, {
+          url: opts.url,
+          resourceTypes,
+          // The global -t/--team scopes the webhook; never combined with --all-public.
+          team: opts.allPublic ? undefined : ctx.defaultTeam,
+          label: opts.label,
+          allPublicTeams: opts.allPublic,
+          secret: opts.secret,
+        });
+        ctx.output.emit(
+          {
+            id: created.id,
+            url: created.url,
+            enabled: created.enabled,
+            resourceTypes: created.resourceTypes,
+          },
+          () => ctx.output.success(`Created webhook ${created.id}`),
+        );
+      }),
+    );
+
+  // update ------------------------------------------------------------------
+  webhook
+    .command("update <id>")
+    .alias("edit")
+    .description("Update a webhook")
+    .option("--url <url>", "new destination URL")
+    .option("--enabled", "enable the webhook")
+    .option("--disabled", "disable the webhook")
+    .option("--resource <type...>", "set resource types (repeatable)", collectArray)
+    .option("--label <label>", "new label")
+    .option("--secret <secret>", "new signing secret")
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        if (opts.enabled && opts.disabled)
+          throw usageError("Pass only one of --enabled / --disabled.");
+        const enabled = opts.enabled ? true : opts.disabled ? false : undefined;
+        const updated = await svc.updateWebhook(ctx.client, idArg, {
+          url: opts.url,
+          enabled,
+          resourceTypes: opts.resource,
+          label: opts.label,
+          secret: opts.secret,
+        });
+        ctx.output.emit(
+          {
+            id: updated.id,
+            url: updated.url,
+            enabled: updated.enabled,
+            resourceTypes: updated.resourceTypes,
+          },
+          () => ctx.output.success(`Updated webhook ${updated.id}`),
+        );
+      }),
+    );
+
+  // delete ------------------------------------------------------------------
+  webhook
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete a webhook")
+    .action(
+      action(async (ctx: Context, _opts, idArg: string) => {
+        const wh = await svc.getWebhookDetail(ctx.client, idArg);
+        if (!(await confirmDestructive(ctx, `Delete webhook ${wh.id} (${wh.url ?? "no url"})?`)))
+          return;
+        const deleted = await svc.deleteWebhook(ctx.client, wh.id);
+        ctx.output.emit({ id: deleted.id, deleted: true }, () =>
+          ctx.output.success(`Deleted webhook ${deleted.id}`),
+        );
+      }),
+    );
+}