linear-sdk-cli 0.8.3 → 0.9.0

package/src/commands/release-pipeline.ts

@@ -0,0 +1,122 @@
+import { Command, Option } from "commander";
+import { action } from "../lib/action.js";
+import { booleanValue, repeat, PIPELINE_TYPES } from "../lib/release-input.js";
+import * as svc from "../services/release.js";
+
+function options(command: Command, creating = false): Command {
+  const result = command
+    .option("--name <name>", "pipeline name")
+    .addOption(new Option("--type <type>", "pipeline type").choices(PIPELINE_TYPES))
+    .option(
+      "--production <boolean>",
+      "whether pipeline targets production (true|false)",
+      booleanValue,
+    )
+    .option(
+      "--auto-release-notes <boolean>",
+      "automatically generate notes on completion (true|false)",
+      booleanValue,
+    )
+    .option(
+      "--rollover-issues <boolean>",
+      "move open issues to the next scheduled release on completion (true|false)",
+      booleanValue,
+    )
+    .addOption(
+      new Option("--include-path <glob>", "replace path patterns with these globs (repeatable)")
+        .argParser(repeat)
+        .conflicts("clearPaths"),
+    )
+    .addOption(new Option("--clear-paths", "clear all path filters").conflicts("includePath"))
+    .addOption(
+      new Option("--team-id <uuid>", "replace associated teams with these UUIDs (repeatable)")
+        .argParser(repeat)
+        .conflicts("clearTeams"),
+    )
+    .addOption(new Option("--clear-teams", "clear team associations").conflicts("teamId"));
+  if (creating)
+    for (const flag of ["--name", "--type"])
+      result.options.find((o) => o.long === flag)!.makeOptionMandatory();
+  return result;
+}
+function input(opts: Record<string, any>): svc.PipelineInput {
+  return {
+    name: opts.name,
+    type: opts.type,
+    isProduction: opts.production,
+    autoGenerateReleaseNotesOnCompletion: opts.autoReleaseNotes,
+    rolloverIssuesOnCompletion: opts.rolloverIssues,
+    includePathPatterns: opts.clearPaths ? [] : opts.includePath,
+    teamIds: opts.clearTeams ? [] : opts.teamId,
+  };
+}
+export function registerReleasePipeline(program: Command): void {
+  const group = program
+    .command("release-pipeline")
+    .description("Manage release pipelines (Business/Enterprise)")
+    .addHelpText(
+      "after",
+      "\nUse normal Linear OAuth/API credentials. Pipeline access keys belong to\nlinear-release and cannot replace these credentials. Creating a pipeline\ncreates default stages; entitlement and workspace permissions are enforced by Linear.",
+    );
+  group
+    .command("list")
+    .alias("ls")
+    .description("List workspace release pipelines")
+    .option("--include-archived", "include archived pipelines")
+    .action(
+      action(async (ctx, opts) => {
+        const rows = await svc.listPipelines(ctx.client, ctx.limit, opts.includeArchived);
+        ctx.output.list(
+          rows,
+          [
+            { key: "id", header: "ID", value: (r) => r.id },
+            { key: "name", header: "Name", value: (r) => r.name },
+            { key: "type", header: "Type", value: (r) => r.type },
+            { key: "slugId", header: "Slug", value: (r) => r.slugId },
+          ],
+          rows,
+        );
+      }),
+    );
+  group
+    .command("view <id>")
+    .description("Show pipeline settings by UUID or slug")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const p = await svc.getPipeline(ctx.client, id);
+        ctx.output.detail(p, [
+          ["ID", p.id],
+          ["Name", p.name],
+          ["Slug", p.slugId],
+          ["Type", p.type],
+          ["Production", p.isProduction],
+          ["Auto release notes", p.autoGenerateReleaseNotesOnCompletion],
+          ["Rollover issues", p.rolloverIssuesOnCompletion],
+          ["Path patterns", p.includePathPatterns.join(", ")],
+          ["Archived", p.archivedAt],
+          ["URL", p.url],
+        ]);
+      }),
+    );
+  options(
+    group.command("create").description("Create a pipeline with default stages"),
+    true,
+  ).action(
+    action(async (ctx, opts) => {
+      const p = await svc.createPipeline(ctx.client, {
+        ...input(opts),
+        name: opts.name,
+        type: opts.type,
+      });
+      ctx.output.emit(p, () => ctx.output.success(`Created release pipeline ${p.name} (${p.id})`));
+    }),
+  );
+  options(
+    group.command("update <id>").description("Update pipeline settings by UUID or slug"),
+  ).action(
+    action(async (ctx, opts, id: string) => {
+      const p = await svc.updatePipeline(ctx.client, id, input(opts));
+      ctx.output.emit(p, () => ctx.output.success(`Updated release pipeline ${p.name} (${p.id})`));
+    }),
+  );
+}

package/src/commands/release-stage.ts

@@ -0,0 +1,100 @@
+import { Command, Option } from "commander";
+import { action } from "../lib/action.js";
+import { booleanValue, finiteNumber, STAGE_TYPES } from "../lib/release-input.js";
+import * as svc from "../services/release.js";
+
+function options(command: Command, creating = false): Command {
+  const result = command
+    .option("--name <name>", "stage name")
+    .option("--color <hex>", "six-digit HEX color")
+    .option("--position <number>", "stage ordering position", finiteNumber)
+    .option(
+      "--frozen <boolean>",
+      "exclude this started stage from automated sync (true|false)",
+      booleanValue,
+    );
+  if (creating)
+    for (const flag of ["--name", "--color", "--position"])
+      result.options.find((o) => o.long === flag)!.makeOptionMandatory();
+  return result;
+}
+function input(opts: Record<string, any>): svc.StageInput {
+  return { name: opts.name, color: opts.color, position: opts.position, frozen: opts.frozen };
+}
+export function registerReleaseStage(program: Command): void {
+  const group = program
+    .command("release-stage")
+    .description("Manage release stages and freeze scheduled release scope")
+    .addHelpText(
+      "after",
+      "\nOnly started stages can be frozen. Frozen stages exclude their releases from\nautomated sync; at least one started stage must remain unfrozen. Stage types\nare immutable. Linear enforces pipeline stage invariants.",
+    );
+  group
+    .command("list <pipeline>")
+    .alias("ls")
+    .description("List stages for a pipeline UUID or slug")
+    .option("--include-archived", "include archived stages")
+    .action(
+      action(async (ctx, opts, pipeline: string) => {
+        const rows = await svc.listStages(ctx.client, pipeline, ctx.limit, opts.includeArchived);
+        ctx.output.list(
+          rows,
+          [
+            { key: "id", header: "ID", value: (r) => r.id },
+            { key: "name", header: "Name", value: (r) => r.name },
+            { key: "type", header: "Type", value: (r) => r.type },
+            { key: "position", header: "Position", value: (r) => r.position },
+            { key: "frozen", header: "Frozen", value: (r) => r.frozen },
+          ],
+          rows,
+        );
+      }),
+    );
+  group
+    .command("view <id>")
+    .description("Show a release stage by UUID")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const s = await svc.getStage(ctx.client, id);
+        ctx.output.detail(s, [
+          ["ID", s.id],
+          ["Name", s.name],
+          ["Type", s.type],
+          ["Color", s.color],
+          ["Position", s.position],
+          ["Frozen", s.frozen],
+          ["Pipeline", s.pipeline.name],
+          ["Archived", s.archivedAt],
+        ]);
+      }),
+    );
+  options(group.command("create").description("Create a stage in a release pipeline"), true)
+    .requiredOption("--pipeline <id|slug>", "pipeline UUID or slug")
+    .addOption(
+      new Option("--type <type>", "lifecycle stage type")
+        .choices(STAGE_TYPES)
+        .makeOptionMandatory(),
+    )
+    .action(
+      action(async (ctx, opts) => {
+        const s = await svc.createStage(ctx.client, opts.pipeline, {
+          ...input(opts),
+          name: opts.name,
+          color: opts.color,
+          position: opts.position,
+          type: opts.type,
+        });
+        ctx.output.emit(s, () => ctx.output.success(`Created release stage ${s.name} (${s.id})`));
+      }),
+    );
+  options(
+    group
+      .command("update <id>")
+      .description("Update name, color, order, or frozen state by stage UUID"),
+  ).action(
+    action(async (ctx, opts, id: string) => {
+      const s = await svc.updateStage(ctx.client, id, input(opts));
+      ctx.output.emit(s, () => ctx.output.success(`Updated release stage ${s.name} (${s.id})`));
+    }),
+  );
+}

package/src/commands/release.ts

@@ -0,0 +1,254 @@
+import { Command, Option } from "commander";
+import { action } from "../lib/action.js";
+import {
+  descriptionOptions,
+  releaseInput,
+  lifecycleOptions,
+  lifecycleInput,
+  issueReferences,
+  repeat,
+  STAGE_TYPES,
+} from "../lib/release-input.js";
+import { confirmDestructive } from "../lib/prompt.js";
+import * as svc from "../services/release.js";
+import type { Context } from "../context.js";
+import type { Column } from "../output/table.js";
+
+const COLUMNS: Column<svc.ReleaseRow>[] = [
+  { key: "id", header: "ID", value: (r) => r.id },
+  { key: "name", header: "Name", value: (r) => r.name },
+  { key: "version", header: "Version", value: (r) => r.version ?? "—" },
+  { key: "pipeline", header: "Pipeline", value: (r) => r.pipeline.name },
+  { key: "stage", header: "Stage", value: (r) => r.stage.name },
+];
+function emit(ctx: Context, value: svc.ReleaseDetail, verb: string): void {
+  ctx.output.emit(value, () => ctx.output.success(`${verb} release ${value.name} (${value.id})`));
+}
+function editOptions(command: Command, creating = false): Command {
+  const result = descriptionOptions(command)
+    .option("--name <name>", "release name")
+    .option("--release-version <version>", "release version (unique within the pipeline)")
+    .option("--commit-sha <sha>", "full Git commit SHA")
+    .option("--stage <id>", "stage UUID from the same pipeline")
+    .option("--start-date <date>", "estimated start date (YYYY-MM-DD)")
+    .option("--target-date <date>", "estimated completion date (YYYY-MM-DD)");
+  if (creating) result.options.find((o) => o.long === "--name")!.makeOptionMandatory();
+  return result;
+}
+export function registerRelease(program: Command): void {
+  const group = program
+    .command("release")
+    .description("Track releases and issue membership (Business/Enterprise)")
+    .addHelpText(
+      "after",
+      "\nUse pipeline UUIDs/slugs and explicit versions for lifecycle operations.\nGit scanning and pipeline access keys: https://github.com/linear/linear-release\nCompleting a scheduled release may move open issues to the next release.",
+    );
+  group
+    .command("list")
+    .alias("ls")
+    .description("List releases, optionally scoped to a pipeline")
+    .option("--pipeline <id|slug>", "filter by pipeline UUID or slug")
+    .option("--release-version <version>", "filter by exact version")
+    .addOption(
+      new Option("--stage-type <type>", "filter by lifecycle stage type").choices(STAGE_TYPES),
+    )
+    .option("--include-archived", "include archived releases")
+    .action(
+      action(async (ctx, opts) => {
+        const rows = await svc.listReleases(ctx.client, ctx.limit, {
+          pipeline: opts.pipeline,
+          version: opts.releaseVersion,
+          stageType: opts.stageType,
+          includeArchived: opts.includeArchived,
+        });
+        ctx.output.list(rows, COLUMNS, rows);
+      }),
+    );
+  group
+    .command("view <id>")
+    .description("Show a release by UUID or slug")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const r = await svc.getRelease(ctx.client, id);
+        ctx.output.detail(r, [
+          ["ID", r.id],
+          ["Name", r.name],
+          ["Version", r.version],
+          ["Commit SHA", r.commitSha],
+          ["Pipeline", r.pipeline.name],
+          ["Stage", r.stage.name],
+          ["Start date", r.startDate],
+          ["Target date", r.targetDate],
+          ["Started", r.startedAt],
+          ["Completed", r.completedAt],
+          ["Canceled", r.canceledAt],
+          ["Archived", r.archivedAt],
+          ["Issues", r.issueCount],
+          ["URL", r.url],
+          ["Description", r.description],
+        ]);
+      }),
+    );
+  editOptions(
+    group
+      .command("create")
+      .alias("new")
+      .description("Create a release (stage defaults depend on pipeline type)"),
+    true,
+  )
+    .requiredOption("--pipeline <id|slug>", "pipeline UUID or slug")
+    .action(
+      action(async (ctx, opts) =>
+        emit(
+          ctx,
+          await svc.createRelease(ctx.client, opts.pipeline, {
+            ...releaseInput(opts),
+            name: opts.name,
+          }),
+          "Created",
+        ),
+      ),
+    );
+  editOptions(
+    group
+      .command("update <id>")
+      .alias("edit")
+      .description("Update exact release metadata or stage by UUID/slug"),
+  ).action(
+    action(async (ctx, opts, id: string) =>
+      emit(ctx, await svc.updateRelease(ctx.client, id, releaseInput(opts)), "Updated"),
+    ),
+  );
+  lifecycleOptions(
+    group
+      .command("sync")
+      .description("Sync explicit issue references; continuous pipelines complete immediately"),
+  )
+    .requiredOption("--commit-sha <sha>", "full Git commit SHA (no implicit checkout scanning)")
+    .option(
+      "--issue <key[=sha]>",
+      "issue reference, defaulting to --commit-sha (repeatable)",
+      repeat,
+    )
+    .option(
+      "--reverted-issue <key[=sha]>",
+      "reverted issue reference to remove (repeatable)",
+      repeat,
+    )
+    .addHelpText(
+      "after",
+      "\nScheduled sync may label an unversioned started release or create a release.\nIssue references accumulate; omitted issues are not removed. Use --reverted-issue\nor release remove-issue for removal. Use linear-release for Git/PR attribution.",
+    )
+    .action(
+      action(async (ctx, opts) =>
+        emit(
+          ctx,
+          await svc.syncRelease(ctx.client, opts.pipeline, opts.releaseVersion, {
+            ...lifecycleInput(opts),
+            commitSha: opts.commitSha,
+            issueReferences: issueReferences(opts.issue, opts.commitSha),
+            revertedIssueReferences: issueReferences(opts.revertedIssue, opts.commitSha),
+          }),
+          "Synced",
+        ),
+      ),
+    );
+  lifecycleOptions(
+    group
+      .command("update-version")
+      .description("Update stage/name/links for an explicit pipeline and release version"),
+  )
+    .option("--stage <name>", "stage name (Linear matches exact name, then normalized name)")
+    .action(
+      action(async (ctx, opts) =>
+        emit(
+          ctx,
+          await svc.updateReleaseVersion(ctx.client, opts.pipeline, opts.releaseVersion, {
+            ...lifecycleInput(opts),
+            stage: opts.stage,
+          }),
+          "Updated",
+        ),
+      ),
+    );
+  lifecycleOptions(
+    group
+      .command("complete")
+      .description("Complete an explicit scheduled release; may roll open issues forward"),
+  )
+    .option(
+      "--commit-sha <sha>",
+      "full SHA (Linear preserves an existing SHA when targeting a version)",
+    )
+    .addHelpText(
+      "after",
+      "\nComplete only after your deployment and verification gates pass. This command\nrecords lifecycle state; it does not deploy or verify code.",
+    )
+    .action(
+      action(async (ctx, opts) =>
+        emit(
+          ctx,
+          await svc.completeRelease(ctx.client, opts.pipeline, opts.releaseVersion, {
+            ...lifecycleInput(opts),
+            commitSha: opts.commitSha,
+          }),
+          "Completed",
+        ),
+      ),
+    );
+  group
+    .command("issues <id>")
+    .description("List issues in a release (UUID or slug)")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const rows = await svc.listReleaseIssues(ctx.client, id, ctx.limit);
+        ctx.output.list(
+          rows,
+          [
+            { key: "identifier", header: "Issue", value: (r) => r.identifier },
+            { key: "title", header: "Title", value: (r) => r.title },
+          ],
+          rows,
+        );
+      }),
+    );
+  group
+    .command("links <id>")
+    .description("List external links on a release (UUID or slug)")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const rows = await svc.listReleaseLinks(ctx.client, id, ctx.limit);
+        ctx.output.list(
+          rows,
+          [
+            { key: "label", header: "Label", value: (r) => r.label ?? "—" },
+            { key: "url", header: "URL", value: (r) => r.url },
+          ],
+          rows,
+        );
+      }),
+    );
+  group
+    .command("add-issue <id> <issue>")
+    .description("Add an issue (KEY-123 or UUID) to an exact release")
+    .action(
+      action(async (ctx, _opts, id: string, issue: string) => {
+        const receipt = await svc.addIssue(ctx.client, id, issue);
+        ctx.output.emit(receipt, () =>
+          ctx.output.success(`Added ${receipt.identifier} to release ${receipt.releaseId}`),
+        );
+      }),
+    );
+  group
+    .command("remove-issue <id> <issue>")
+    .description("Remove an issue from an exact release")
+    .action(
+      action(async (ctx, _opts, id: string, issue: string) => {
+        if (!(await confirmDestructive(ctx, `Remove ${issue} from release ${id}?`))) return;
+        const receipt = await svc.removeIssue(ctx.client, id, issue);
+        ctx.output.emit(receipt, () =>
+          ctx.output.success(`Removed ${issue} from release ${receipt.releaseId}`),
+        );
+      }),
+    );
+}