@enrichlayer/el-linear 1.2.0

package/dist/commands/batch.js

@@ -0,0 +1,309 @@
+import { resolveAssignee, resolveLabels, resolveTeam, } from "../config/resolver.js";
+import { GraphQLIssuesService } from "../utils/graphql-issues-service.js";
+import { createGraphQLService } from "../utils/graphql-service.js";
+import { createLinearService } from "../utils/linear-service.js";
+import { logger } from "../utils/logger.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { splitList } from "../utils/validators.js";
+/**
+ * Parse the --filter string into structured search arguments.
+ * Format: "status:Backlog team:DEV label:Bug assignee:Alice project:Sprint12"
+ */
+function parseFilterString(filter) {
+    const result = {};
+    const parts = filter.match(/(\w+):("[^"]+"|[^\s]+)/g);
+    if (!parts) {
+        throw new Error(`Invalid filter format: "${filter}". ` +
+            'Expected key:value pairs, e.g. "status:Backlog team:DEV label:Bug"');
+    }
+    for (const part of parts) {
+        const colonIndex = part.indexOf(":");
+        const key = part.slice(0, colonIndex);
+        const value = part.slice(colonIndex + 1).replace(/^"|"$/g, "");
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Resolve issue identifiers from --issues or --filter.
+ * Returns LinearIssue[] so we can show a preview.
+ */
+async function resolveTargetIssues(options, rootOpts) {
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    if (options.issues) {
+        const ids = splitList(options.issues);
+        return Promise.all(ids.map((id) => issuesService.getIssueById(id)));
+    }
+    if (options.filter) {
+        const filters = parseFilterString(options.filter);
+        const searchArgs = {
+            teamId: filters.team ? resolveTeam(filters.team) : undefined,
+            assigneeId: filters.assignee
+                ? await resolveAssignee(filters.assignee, rootOpts)
+                : undefined,
+            projectId: filters.project || undefined,
+            labelNames: filters.label ? splitList(filters.label) : undefined,
+            status: filters.status ? splitList(filters.status) : undefined,
+            limit: 50,
+        };
+        return issuesService.searchIssues(searchArgs);
+    }
+    throw new Error("Specify --issues (comma-separated IDs) or --filter to select issues.");
+}
+/**
+ * Print a preview table of issues that will be affected.
+ * Returns false if no issues were found.
+ */
+function printPreview(issues, action) {
+    if (issues.length === 0) {
+        logger.error("No issues matched the given criteria.");
+        return false;
+    }
+    logger.error(`\n${action}\n`);
+    logger.error(`  ${"Identifier".padEnd(14)} ${"Status".padEnd(16)} Title`);
+    logger.error(`  ${"─".repeat(14)} ${"─".repeat(16)} ${"─".repeat(40)}`);
+    for (const issue of issues) {
+        const id = issue.identifier.padEnd(14);
+        const status = (issue.state?.name ?? "—").padEnd(16);
+        const title = issue.title.length > 50 ? `${issue.title.slice(0, 47)}...` : issue.title;
+        logger.error(`  ${id} ${status} ${title}`);
+    }
+    logger.error(`\n  ${issues.length} issue${issues.length === 1 ? "" : "s"} will be affected.\n`);
+    return true;
+}
+/**
+ * Execute a batch operation on each issue, collecting results.
+ */
+async function executeBatch(issues, operation) {
+    const results = [];
+    for (const issue of issues) {
+        try {
+            await operation(issue);
+            results.push({ identifier: issue.identifier, success: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push({
+                identifier: issue.identifier,
+                success: false,
+                error: message,
+            });
+        }
+    }
+    return { results };
+}
+async function handleBatchAssign(options, command) {
+    const rootOpts = command.parent.parent.opts();
+    if (!options.assignee) {
+        throw new Error("--assignee is required.");
+    }
+    const issues = await resolveTargetIssues(options, rootOpts);
+    const assigneeId = await resolveAssignee(options.assignee, rootOpts);
+    if (!options.yes) {
+        const hasPreview = printPreview(issues, `Assign ${issues.length} issues to "${options.assignee}":`);
+        if (!hasPreview) {
+            return;
+        }
+        outputWarning("Dry run — pass --yes to execute.");
+        outputSuccess({
+            dryRun: true,
+            action: "assign",
+            assignee: options.assignee,
+            issues: issues.map((i) => i.identifier),
+            count: issues.length,
+        });
+        return;
+    }
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, assigneeId }, "adding"));
+    outputSuccess({
+        action: "assign",
+        assignee: options.assignee,
+        results,
+        meta: {
+            total: results.length,
+            succeeded: results.filter((r) => r.success).length,
+            failed: results.filter((r) => !r.success).length,
+        },
+    });
+}
+async function handleBatchLabel(options, command) {
+    const rootOpts = command.parent.parent.opts();
+    if (!(options.add || options.remove)) {
+        throw new Error("Specify --add and/or --remove for labels.");
+    }
+    const issues = await resolveTargetIssues(options, rootOpts);
+    const addLabels = options.add ? splitList(options.add) : [];
+    const removeLabels = options.remove ? splitList(options.remove) : [];
+    const actionParts = [];
+    if (addLabels.length > 0) {
+        actionParts.push(`add [${addLabels.join(", ")}]`);
+    }
+    if (removeLabels.length > 0) {
+        actionParts.push(`remove [${removeLabels.join(", ")}]`);
+    }
+    const actionDesc = `Labels: ${actionParts.join(", ")} on ${issues.length} issues:`;
+    if (!options.yes) {
+        const hasPreview = printPreview(issues, actionDesc);
+        if (!hasPreview) {
+            return;
+        }
+        outputWarning("Dry run — pass --yes to execute.");
+        outputSuccess({
+            dryRun: true,
+            action: "label",
+            add: addLabels,
+            remove: removeLabels,
+            issues: issues.map((i) => i.identifier),
+            count: issues.length,
+        });
+        return;
+    }
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const removeLower = removeLabels.map((l) => l.toLowerCase());
+    const { results } = await executeBatch(issues, (issue) => {
+        // Filter out labels to remove (by name, case-insensitive)
+        const keepIds = issue.labels
+            .filter((l) => !removeLower.includes(l.name.toLowerCase()))
+            .map((l) => l.id);
+        // Resolve labels to add (may be names that need resolution)
+        const teamKey = issue.team?.key;
+        const addIds = teamKey ? resolveLabels(addLabels, teamKey) : addLabels;
+        // Merge: keep existing (minus removed) + add new (avoiding duplicates)
+        const finalLabelIds = [...keepIds];
+        for (const id of addIds) {
+            if (!finalLabelIds.includes(id)) {
+                finalLabelIds.push(id);
+            }
+        }
+        return issuesService.updateIssue({ id: issue.identifier, labelIds: finalLabelIds }, "overwriting");
+    });
+    outputSuccess({
+        action: "label",
+        add: addLabels,
+        remove: removeLabels,
+        results,
+        meta: {
+            total: results.length,
+            succeeded: results.filter((r) => r.success).length,
+            failed: results.filter((r) => !r.success).length,
+        },
+    });
+}
+async function handleBatchMove(options, command) {
+    const rootOpts = command.parent.parent.opts();
+    if (!options.project) {
+        throw new Error("--project is required.");
+    }
+    const issues = await resolveTargetIssues(options, rootOpts);
+    if (!options.yes) {
+        const hasPreview = printPreview(issues, `Move ${issues.length} issues to project "${options.project}":`);
+        if (!hasPreview) {
+            return;
+        }
+        outputWarning("Dry run — pass --yes to execute.");
+        outputSuccess({
+            dryRun: true,
+            action: "move",
+            project: options.project,
+            issues: issues.map((i) => i.identifier),
+            count: issues.length,
+        });
+        return;
+    }
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, projectId: options.project }, "adding"));
+    outputSuccess({
+        action: "move",
+        project: options.project,
+        results,
+        meta: {
+            total: results.length,
+            succeeded: results.filter((r) => r.success).length,
+            failed: results.filter((r) => !r.success).length,
+        },
+    });
+}
+async function handleBatchStatus(options, command) {
+    const rootOpts = command.parent.parent.opts();
+    if (!options.status) {
+        throw new Error("--status is required.");
+    }
+    const issues = await resolveTargetIssues(options, rootOpts);
+    if (!options.yes) {
+        const hasPreview = printPreview(issues, `Change status to "${options.status}" on ${issues.length} issues:`);
+        if (!hasPreview) {
+            return;
+        }
+        outputWarning("Dry run — pass --yes to execute.");
+        outputSuccess({
+            dryRun: true,
+            action: "status",
+            status: options.status,
+            issues: issues.map((i) => i.identifier),
+            count: issues.length,
+        });
+        return;
+    }
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, statusId: options.status }, "adding"));
+    outputSuccess({
+        action: "status",
+        status: options.status,
+        results,
+        meta: {
+            total: results.length,
+            succeeded: results.filter((r) => r.success).length,
+            failed: results.filter((r) => !r.success).length,
+        },
+    });
+}
+export function setupBatchCommands(program) {
+    const batch = program
+        .command("batch")
+        .description("Batch operations on multiple issues");
+    batch.action(() => batch.help());
+    batch
+        .command("assign")
+        .description("Assign multiple issues to a user")
+        .option("--issues <issues>", "comma-separated issue IDs (e.g. DEV-100,DEV-101)")
+        .option("--filter <filter>", 'query filter (e.g. "status:Backlog team:DEV label:Bug")')
+        .requiredOption("--assignee <assignee>", "assignee (name, alias, or UUID)")
+        .option("--yes", "skip confirmation preview and execute immediately")
+        .action(handleAsyncCommand(handleBatchAssign));
+    batch
+        .command("label")
+        .description("Add or remove labels on multiple issues")
+        .option("--issues <issues>", "comma-separated issue IDs (e.g. DEV-100,DEV-101)")
+        .option("--filter <filter>", 'query filter (e.g. "status:Backlog team:DEV label:Bug")')
+        .option("--add <labels>", "labels to add (comma-separated names)")
+        .option("--remove <labels>", "labels to remove (comma-separated names)")
+        .option("--yes", "skip confirmation preview and execute immediately")
+        .action(handleAsyncCommand(handleBatchLabel));
+    batch
+        .command("move")
+        .description("Move multiple issues to a project")
+        .option("--issues <issues>", "comma-separated issue IDs (e.g. DEV-100,DEV-101)")
+        .option("--filter <filter>", 'query filter (e.g. "status:Backlog team:DEV label:Bug")')
+        .requiredOption("--project <project>", "project name or ID")
+        .option("--yes", "skip confirmation preview and execute immediately")
+        .action(handleAsyncCommand(handleBatchMove));
+    batch
+        .command("status")
+        .description("Change status on multiple issues")
+        .option("--issues <issues>", "comma-separated issue IDs (e.g. DEV-100,DEV-101)")
+        .option("--filter <filter>", 'query filter (e.g. "status:Backlog team:DEV label:Bug")')
+        .requiredOption("-s, --status <status>", "new status name or ID")
+        .option("--yes", "skip confirmation preview and execute immediately")
+        .action(handleAsyncCommand(handleBatchStatus));
+}

package/dist/commands/comments.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupCommentsCommands(program: Command): void;

package/dist/commands/comments.js

@@ -0,0 +1,272 @@
+import { readFileSync } from "node:fs";
+import { resolveUserDisplayName } from "../config/resolver.js";
+import { CREATE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
+import { autoLinkReferences, } from "../utils/auto-link-references.js";
+import { createGraphQLService, } from "../utils/graphql-service.js";
+import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
+import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js";
+import { createLinearService, } from "../utils/linear-service.js";
+import { resolveMentions } from "../utils/mention-resolver.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { validateReferences } from "../utils/validate-references.js";
+import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
+// Match Linear's bodyData validation error in multiple phrasings so a wording
+// tweak on their side doesn't silently regress the fallback path.
+const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
+const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
+function readBody(options) {
+    if (options.file) {
+        return readFileSync(options.file, "utf-8");
+    }
+    if (options.body) {
+        return options.body;
+    }
+    throw new Error("Either --body or --file is required");
+}
+async function fetchSelfUserId(graphQLService) {
+    try {
+        const result = await graphQLService.rawRequest("{ viewer { id } }");
+        const viewer = result.viewer;
+        return viewer?.id;
+    }
+    catch {
+        return;
+    }
+}
+function transformComment(comment) {
+    const user = comment.user;
+    return {
+        id: comment.id,
+        body: comment.body,
+        user: {
+            id: user.id,
+            name: resolveUserDisplayName(user.id, user.name),
+            url: user.url || undefined,
+        },
+        createdAt: comment.createdAt,
+        updatedAt: comment.updatedAt,
+    };
+}
+/**
+ * Wrap valid issue references in a comment body as markdown links — same logic as for
+ * issue descriptions. Returns the rewritten body plus the validated identifier→UUID map
+ * so the caller can reuse it for sidebar relation creation without re-resolving.
+ *
+ * No-op (returns the original body with an empty map) when:
+ * - body has no candidate refs
+ * - the user passed `--no-auto-link`
+ */
+async function prepareCommentBodyWithLinks(body, options, linearService, graphQLService) {
+    if (options.autoLink === false || !body) {
+        return { body, preResolved: new Map() };
+    }
+    const refs = extractIssueReferences(body);
+    if (refs.length === 0) {
+        return { body, preResolved: new Map() };
+    }
+    const preResolved = await validateReferences(refs.map((r) => r.identifier), linearService);
+    if (preResolved.size === 0) {
+        return { body, preResolved };
+    }
+    const validIds = new Set(preResolved.keys());
+    const urlKey = await getWorkspaceUrlKey(graphQLService);
+    const wrapped = wrapIssueReferencesAsLinks(body, validIds, urlKey);
+    return { body: wrapped, preResolved };
+}
+/**
+ * After a comment is saved, create sidebar relations on the parent issue for the
+ * referenced issues — same de-dup and prose-keyword inference logic as descriptions.
+ * Returns undefined when nothing was linked, skipped, or failed.
+ */
+async function autoLinkCommentReferences(args) {
+    if (args.options.autoLink === false) {
+        return;
+    }
+    const result = await autoLinkReferences({
+        issueId: args.parentIssueUuid,
+        identifier: args.parentIssueIdentifier,
+        description: args.body,
+        preResolved: args.preResolved,
+        graphQLService: args.graphQLService,
+        linearService: args.linearService,
+    });
+    if (result.linked.length === 0 &&
+        result.skipped.length === 0 &&
+        result.failed.length === 0) {
+        return;
+    }
+    return result;
+}
+async function handleCreateComment(issueId, options, command) {
+    const rootOpts = command.parent.parent.opts();
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const rawBody = readBody(options);
+    const resolvedIssueId = await linearService.resolveIssueId(issueId);
+    // Wrap valid refs as markdown links before mention resolution. Idempotent against
+    // already-wrapped refs.
+    const { body, preResolved } = await prepareCommentBodyWithLinks(rawBody, options, linearService, graphQLService);
+    const autoMention = options.autoMention !== false;
+    const selfUserId = autoMention
+        ? await fetchSelfUserId(graphQLService)
+        : undefined;
+    const mentionResult = await resolveMentions(body, linearService, {
+        autoMention,
+        selfUserId,
+    });
+    const input = { issueId: resolvedIssueId };
+    if (mentionResult) {
+        input.bodyData = mentionResult.bodyData;
+    }
+    else {
+        input.body = body;
+    }
+    let result;
+    try {
+        result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, {
+            input,
+        });
+    }
+    catch (err) {
+        // If the bodyData ProseMirror document is rejected (invalid shape,
+        // unsupported node, schema change), fall back to raw body text and let
+        // Linear handle the conversion server-side.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            const fallbackInput = {
+                issueId: resolvedIssueId,
+                body,
+            };
+            result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, {
+                input: fallbackInput,
+            });
+        }
+        else {
+            throw err;
+        }
+    }
+    const mutation = result.commentCreate;
+    if (!mutation.success) {
+        throw new Error("Failed to create comment");
+    }
+    // We don't have the parent issue's identifier from the create mutation response,
+    // but we don't need it for self-exclusion in comments — wrapping a self-ref in a
+    // comment body is harmless. Use the user-provided issueId if it looks like one.
+    const parentIdentifier = ISSUE_IDENTIFIER_REGEX.test(issueId)
+        ? issueId.toUpperCase()
+        : "";
+    // Pass rawBody (pre-wrap) to autoLink so prose-keyword inference ("blocked by", etc.)
+    // sees `keyword DEV-100` rather than `keyword [DEV-100](url)`. After wrapping the inserted
+    // `[` defeats the trailing-whitespace anchor and inference falls back to "related".
+    const autoLinked = await autoLinkCommentReferences({
+        parentIssueUuid: resolvedIssueId,
+        parentIssueIdentifier: parentIdentifier,
+        body: rawBody,
+        preResolved,
+        options,
+        graphQLService,
+        linearService,
+    });
+    const output = transformComment(mutation.comment);
+    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+}
+async function handleUpdateComment(commentId, options, command) {
+    const rootOpts = command.parent.parent.opts();
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const rawBody = readBody(options);
+    const { body, preResolved } = await prepareCommentBodyWithLinks(rawBody, options, linearService, graphQLService);
+    const autoMention = options.autoMention !== false;
+    const selfUserId = autoMention
+        ? await fetchSelfUserId(graphQLService)
+        : undefined;
+    const mentionResult = await resolveMentions(body, linearService, {
+        autoMention,
+        selfUserId,
+    });
+    const input = {};
+    if (mentionResult) {
+        input.bodyData = mentionResult.bodyData;
+    }
+    else {
+        input.body = body;
+    }
+    const result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, {
+        id: commentId,
+        input,
+    });
+    const mutation = result.commentUpdate;
+    if (!mutation.success) {
+        throw new Error("Failed to update comment");
+    }
+    const comment = mutation.comment;
+    const issue = comment.issue;
+    let autoLinked;
+    if (issue) {
+        // rawBody (pre-wrap) — see note in handleCreateComment about keyword inference
+        autoLinked = await autoLinkCommentReferences({
+            parentIssueUuid: issue.id,
+            parentIssueIdentifier: issue.identifier ?? "",
+            body: rawBody,
+            preResolved,
+            options,
+            graphQLService,
+            linearService,
+        });
+    }
+    const output = transformComment(comment);
+    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+}
+async function handleListComments(issueId, options, command) {
+    const rootOpts = command.parent.parent.opts();
+    const graphQLService = createGraphQLService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    const result = await graphQLService.rawRequest(LIST_COMMENTS_QUERY, {
+        issueId: resolvedId,
+        first: Number.parseInt(options.limit, 10),
+    });
+    const issue = result.issue;
+    if (!issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const commentsData = issue.comments;
+    const nodes = commentsData.nodes.map(transformComment);
+    outputSuccess({
+        data: nodes,
+        meta: {
+            count: nodes.length,
+            issue: issue.identifier,
+        },
+    });
+}
+export function setupCommentsCommands(program) {
+    const comments = program
+        .command("comments")
+        .alias("comment")
+        .description("Comment operations");
+    comments.action(() => comments.help());
+    comments
+        .command("create <issueId>")
+        .description("Create new comment on issue.")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.\nBare references to known team members (e.g. 'Dima') are auto-converted to @mentions — pass --no-auto-mention to disable.\nIssue identifiers (e.g. DEV-123) are wrapped as markdown links and added as 'related' relations on the parent issue — pass --no-auto-link to disable.")
+        .option("--body <body>", "comment body (inline)")
+        .option("--file <path>", "read comment body from file")
+        .option("--no-auto-mention", "do not auto-convert bare team-member names to @mentions")
+        .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
+        .action(handleAsyncCommand(handleCreateComment));
+    comments
+        .command("update <commentId>")
+        .description("Update an existing comment.")
+        .option("--body <body>", "new comment body (inline)")
+        .option("--file <path>", "read new comment body from file")
+        .option("--no-auto-mention", "do not auto-convert bare team-member names to @mentions")
+        .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
+        .action(handleAsyncCommand(handleUpdateComment));
+    comments
+        .command("list <issueId>")
+        .description("List comments on an issue.")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
+        .option("-l, --limit <number>", "limit results", "25")
+        .action(handleAsyncCommand(handleListComments));
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupConfigCommands(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,15 @@
+import { loadConfig } from "../config/config.js";
+import { outputSuccess } from "../utils/output.js";
+export function setupConfigCommands(program) {
+    const config = program
+        .command("config")
+        .description("Configuration introspection");
+    config.action(() => config.help());
+    config
+        .command("show")
+        .description("Show resolved configuration")
+        .addHelpText("after", "\nDumps the merged config from ~/.config/el-linear/config.json.\n\nExamples:\n  el-linear config show")
+        .action(() => {
+        outputSuccess({ data: loadConfig() });
+    });
+}

package/dist/commands/cycles.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupCyclesCommands(program: Command): void;

package/dist/commands/cycles.js

@@ -0,0 +1,63 @@
+import { resolveTeam } from "../config/resolver.js";
+import { invalidParameterError, notFoundError, requiresParameterError, } from "../utils/error-messages.js";
+import { createLinearService } from "../utils/linear-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+export function setupCyclesCommands(program) {
+    const cycles = program
+        .command("cycles")
+        .alias("cycle")
+        .description("Cycle operations");
+    cycles.action(() => cycles.help());
+    cycles
+        .command("list")
+        .description("List cycles")
+        .option("--team <team>", "team key, name, or ID")
+        .option("--active", "only active cycles")
+        .option("--around-active <n>", "return active +/- n cycles (requires --team)")
+        .option("-l, --limit <number>", "limit results", "50")
+        .action(handleAsyncCommand(async (options, command) => {
+        if (options.aroundActive && !options.team) {
+            throw requiresParameterError("--around-active", "--team");
+        }
+        const rootOpts = command.parent.parent.opts();
+        const teamFilter = options.team ? resolveTeam(options.team) : undefined;
+        const linearService = createLinearService(rootOpts);
+        const allCycles = await linearService.getCycles(teamFilter, options.active || undefined, Number.parseInt(options.limit, 10));
+        if (options.aroundActive) {
+            const n = Number.parseInt(options.aroundActive, 10);
+            if (Number.isNaN(n) || n < 0) {
+                throw invalidParameterError("--around-active", "requires a non-negative integer");
+            }
+            const activeCycle = allCycles.find((c) => c.isActive);
+            if (!activeCycle) {
+                throw notFoundError("Active cycle", options.team, "for team");
+            }
+            const activeNumber = Number(activeCycle.number || 0);
+            const min = activeNumber - n;
+            const max = activeNumber + n;
+            const filtered = allCycles
+                .filter((c) => typeof c.number === "number" &&
+                c.number >= min &&
+                c.number <= max)
+                .sort((a, b) => a.number - b.number);
+            outputSuccess({ data: filtered, meta: { count: filtered.length } });
+            return;
+        }
+        outputSuccess({ data: allCycles, meta: { count: allCycles.length } });
+    }));
+    cycles
+        .command("read <cycleIdOrName>")
+        .description("Get cycle details including issues.")
+        .option("--team <team>", "team key, name, or ID to scope name lookup")
+        .option("--issues-first <n>", "how many issues to fetch (default 50)", "50")
+        .action(handleAsyncCommand(async (cycleIdOrName, options, command) => {
+        const rootOpts = command.parent.parent.opts();
+        const teamFilter = options.team
+            ? resolveTeam(options.team)
+            : undefined;
+        const linearService = createLinearService(rootOpts);
+        const cycleId = await linearService.resolveCycleId(cycleIdOrName, teamFilter);
+        const cycle = await linearService.getCycleById(cycleId, Number.parseInt(options.issuesFirst || "50", 10));
+        outputSuccess(cycle);
+    }));
+}

package/dist/commands/documents.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupDocumentsCommands(program: Command): void;