@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/commands/introspect.js

@@ -0,0 +1,178 @@
+/**
+ * `el-linear introspect` and `el-linear validate-flag` — expose the
+ * commander command tree so external linters (e.g. CI steps that scan
+ * SKILL.md files for `el-linear <cmd> --<flag>` references) can verify
+ * that hardcoded flag names actually exist on the current binary.
+ *
+ * Without this, a flag rename inside `el-linear` (say `--parent-ticket`
+ * → `--parent`) silently breaks every skill that prose-references the
+ * old name. Skills then fail at runtime, far from the rename commit.
+ *
+ * `introspect` dumps the full tree — name, description, version,
+ * options, aliases, and recursively nested subcommands.
+ *
+ * `validate-flag` is a thin ergonomic wrapper for the CI-lint use case:
+ *
+ *   $ el-linear validate-flag issues create --parent-ticket
+ *   { "ok": true, "command": ["issues", "create"], "flag": "--parent-ticket" }
+ *   $ el-linear validate-flag issues create --does-not-exist
+ *   { "ok": false, ... "error": "..." }   # exit code 1
+ *
+ * Both commands ignore root-level flags (`--api-token`, `--json`, etc.)
+ * when walking subcommand options; those are dumped at the root, not
+ * under every command. `validate-flag` walks ancestors so a global flag
+ * (e.g. `--format`) validates on any subcommand.
+ */
+import { outputSuccess } from "../utils/output.js";
+function describeOption(opt) {
+    return {
+        flags: opt.flags,
+        long: opt.long ?? null,
+        short: opt.short ?? null,
+        description: opt.description,
+        required: opt.required,
+        optional: opt.optional,
+        variadic: opt.variadic,
+        defaultValue: opt.defaultValue,
+        negated: opt.negate,
+    };
+}
+function describeCommand(cmd) {
+    return {
+        name: cmd.name(),
+        aliases: cmd.aliases(),
+        description: cmd.description(),
+        usage: cmd.usage(),
+        options: cmd.options.map(describeOption),
+        commands: cmd.commands.map(describeCommand),
+    };
+}
+/**
+ * Walk the command tree to find the command at `path`. Returns null if
+ * any segment doesn't resolve. Matches both canonical name and aliases
+ * so `el-linear validate-flag issue get --foo` works the same as
+ * `el-linear validate-flag issues read --foo`.
+ */
+function findCommand(root, path) {
+    let current = root;
+    for (const segment of path) {
+        // Match by canonical name or alias. Commander throws on
+        // duplicate aliases at registration time, so first-match-wins is
+        // only meaningful for the name/alias choice within a single
+        // command, not for ambiguity across siblings.
+        const next = current.commands.find((c) => c.name() === segment || c.aliases().includes(segment));
+        if (!next)
+            return null;
+        current = next;
+    }
+    return current;
+}
+export function setupIntrospectCommand(program) {
+    program
+        .command("cli-introspect [path...]")
+        .description("Dump the el-linear CLI command tree as JSON so external linters can verify flag references in prose (e.g. SKILL.md). Pass a path (`cli-introspect issues create`) to dump a specific subtree. Distinct from `introspect` (which queries the Linear GraphQL schema).")
+        .action((path) => {
+        const target = path.length === 0 ? program : findCommand(program, path);
+        if (!target) {
+            outputSuccess({
+                error: `Command not found: ${path.join(" ")}`,
+                path,
+            });
+            process.exit(1);
+            return; // Defense: explicit so test correctness doesn't
+            // depend on the vi.spyOn(process.exit) mock throwing.
+        }
+        if (path.length === 0) {
+            outputSuccess({
+                name: program.name(),
+                description: program.description(),
+                version: program.version() ?? null,
+                options: program.options.map(describeOption),
+                commands: program.commands.map(describeCommand),
+            });
+        }
+        else {
+            outputSuccess(describeCommand(target));
+        }
+    });
+    program
+        .command("validate-flag [args...]")
+        .description("Verify a flag exists on a command. Two equivalent forms:\n" +
+        "  $ el-linear validate-flag --check-flag --parent-ticket issues create\n" +
+        "  $ el-linear validate-flag issues create --parent-ticket\n" +
+        "The first form is unambiguous regardless of whether the flag-to-check " +
+        "takes an argument; the positional form needs `--` before flags that " +
+        "take args (e.g. `validate-flag -- issues create --jq`) so commander " +
+        "doesn't try to consume the next positional as the flag's value. " +
+        "Exits 0 if the flag is defined on the target command (or any " +
+        "ancestor for inherited globals), 1 otherwise.")
+        // Without these, commander tries to parse `--parent-ticket` (the
+        // flag we want to *check*) as if it were an option OF validate-flag
+        // itself. We need it to pass through as a positional arg.
+        .allowUnknownOption(true)
+        .option("--check-flag <flag>", "the flag to look up (unambiguous alternative to passing it positionally — use this when the flag-being-checked is one that takes an argument)")
+        .action((args, options) => {
+        // Resolve the flag-to-check from either `--check-flag <flag>` or
+        // the first positional arg that starts with `-`. The explicit
+        // option form sidesteps commander's positional ambiguity for
+        // flags that take arguments (e.g. `--jq <filter>`).
+        let flag;
+        let path;
+        if (options.checkFlag) {
+            flag = options.checkFlag;
+            path = args; // all positionals are the command path
+        }
+        else {
+            const flagIdx = args.findIndex((a) => a.startsWith("-"));
+            if (flagIdx === -1) {
+                outputSuccess({
+                    ok: false,
+                    error: "No flag argument found. Pass `--check-flag <flag>` or include `--<flag>` in the positional args.",
+                    args,
+                });
+                process.exit(1);
+                return;
+            }
+            path = args.slice(0, flagIdx);
+            flag = args[flagIdx];
+        }
+        const target = path.length === 0 ? program : findCommand(program, path);
+        if (!target) {
+            outputSuccess({
+                ok: false,
+                error: `Command not found: ${path.join(" ") || "(root)"}`,
+                command: path,
+                flag,
+            });
+            process.exit(1);
+            return;
+        }
+        // Walk the target + ancestors so root-level globals
+        // (--api-token, --format, etc.) validate when a skill writes
+        // `el-linear issues create --format summary`.
+        const ancestors = [];
+        for (let c = target; c; c = c.parent) {
+            ancestors.push(c);
+        }
+        const allOptions = ancestors.flatMap((c) => c.options);
+        const found = allOptions.find((opt) => opt.long === flag || opt.short === flag);
+        if (!found) {
+            outputSuccess({
+                ok: false,
+                error: `Flag not found: ${flag}`,
+                command: path,
+                flag,
+                availableOptions: target.options.map((o) => o.long ?? o.short),
+            });
+            process.exit(1);
+            return;
+        }
+        outputSuccess({
+            ok: true,
+            command: path,
+            flag,
+            flags: found.flags,
+            description: found.description,
+        });
+    });
+}

package/dist/commands/issue-id.js

@@ -75,9 +75,7 @@ export function setupIssueIdCommand(program) {
         const service = await createGraphQLService({
             apiToken: rootOpts.apiToken,
         });
-        const result = (await service.rawRequest(ISSUE_QUERY, {
-            id: parsed.issueId,
-        }));
+        const result = await service.rawRequest(ISSUE_QUERY, { id: parsed.issueId });
         outputSuccess({ ...parsed, issue: result.issue ?? null });
     }));
 }

package/dist/commands/issues/branch.js

@@ -36,5 +36,13 @@ export function gitCheckoutBranch(branchName) {
         outputWarning("Not inside a git repository — skipping branch checkout.");
         return;
     }
-    execFileSync("git", ["checkout", "-b", branchName], { stdio: "pipe" });
+    // `--` separates the new-branch name from any ref. Without it, a
+    // branch name starting with `-` (server bug, malicious team member
+    // crafting an issue title that survives slugification, or a forked
+    // Linear-compatible API) would be parsed as a git flag rather than
+    // a ref. The default `feature/` prefix from `toBranchName` already
+    // blocks the common case, but the prefix is configurable — empty-
+    // prefix callers would lose the defense without this terminator.
+    // Defense-in-depth (DEV-4064).
+    execFileSync("git", ["checkout", "-b", branchName, "--"], { stdio: "pipe" });
 }

package/dist/commands/issues/description.js

@@ -147,12 +147,8 @@ export async function prepareDescriptionRewrite(description, selfIdentifier, lin
     };
 }
 export async function pushDescriptionUpdate(issueUuid, description, graphQLService) {
-    const updateResult = await graphQLService.rawRequest(UPDATE_ISSUE_MUTATION, {
-        id: issueUuid,
-        input: { description },
-    });
-    const mutation = updateResult.issueUpdate;
-    if (!mutation?.success) {
+    const updateResult = await graphQLService.rawRequest(UPDATE_ISSUE_MUTATION, { id: issueUuid, input: { description } });
+    if (!updateResult.issueUpdate.success) {
         throw new Error("Failed to rewrite description");
     }
 }

package/dist/commands/issues/link-references.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `el-linear issues link-references` handler.
+ *
+ * Two modes:
+ *   - Single-issue (`<issueId>`): scan one issue's description (and
+ *     optionally its comments) for issue refs, create sidebar
+ *     relations for any that aren't already linked, optionally
+ *     rewrite the description to wrap the bare refs as markdown
+ *     links.
+ *   - Batch (`--team <key>`): walk the team's recent issues and run
+ *     the same auto-link pass on each. Description rewrite is
+ *     intentionally disabled in batch mode — bulk rewrites
+ *     bot-author every issue's revision history, which makes
+ *     "who edited this?" attribution noisy.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + the create / update / read / search
+ * handlers.
+ */
+import type { Command, OptionValues } from "commander";
+export declare function handleLinkReferencesIssue(issueIdOrTeamFlag: string | undefined, options: OptionValues, command: Command): Promise<void>;

package/dist/commands/issues/link-references.js

@@ -0,0 +1,171 @@
+/**
+ * `el-linear issues link-references` handler.
+ *
+ * Two modes:
+ *   - Single-issue (`<issueId>`): scan one issue's description (and
+ *     optionally its comments) for issue refs, create sidebar
+ *     relations for any that aren't already linked, optionally
+ *     rewrite the description to wrap the bare refs as markdown
+ *     links.
+ *   - Batch (`--team <key>`): walk the team's recent issues and run
+ *     the same auto-link pass on each. Description rewrite is
+ *     intentionally disabled in batch mode — bulk rewrites
+ *     bot-author every issue's revision history, which makes
+ *     "who edited this?" attribution noisy.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + the create / update / read / search
+ * handlers.
+ */
+import { resolveTeam } from "../../config/resolver.js";
+import { LIST_COMMENTS_QUERY } from "../../queries/comments.js";
+import { GET_ISSUE_RELATIONS_QUERY, SCAN_ISSUES_QUERY, } from "../../queries/issues.js";
+import { autoLinkReferences, } from "../../utils/auto-link-references.js";
+import { createGraphQLService, } from "../../utils/graphql-service.js";
+import { createLinearService, } from "../../utils/linear-service.js";
+import { outputSuccess } from "../../utils/output.js";
+import { getRootOpts } from "../../utils/root-opts.js";
+import { parsePositiveInt } from "../../utils/validators.js";
+import { prepareDescriptionRewrite, pushDescriptionUpdate, } from "./description.js";
+async function fetchCommentBodies(issueUuid, graphQLService) {
+    const result = await graphQLService.rawRequest(LIST_COMMENTS_QUERY, {
+        issueId: issueUuid,
+        first: 250,
+    });
+    const nodes = result.issue?.comments.nodes ?? [];
+    return nodes.map((c) => c.body).filter((b) => b.length > 0);
+}
+async function linkReferencesForIssue(args) {
+    const comments = args.includeComments
+        ? await fetchCommentBodies(args.issueUuid, args.graphQLService)
+        : undefined;
+    return autoLinkReferences({
+        issueId: args.issueUuid,
+        identifier: args.identifier,
+        description: args.description,
+        comments,
+        dryRun: args.dryRun,
+        graphQLService: args.graphQLService,
+        linearService: args.linearService,
+        preResolved: args.preResolved,
+    });
+}
+async function handleLinkReferencesSingle(issueId, options, graphQLService, linearService) {
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    // GET_ISSUE_RELATIONS_QUERY also returns description, so this single call gives us everything
+    // we need for the description-only path. Comments are fetched separately on demand.
+    const issueResult = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, { id: resolvedId });
+    if (!issueResult.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const issue = issueResult.issue;
+    const identifier = issue.identifier;
+    const description = issue.description ?? "";
+    const dryRun = Boolean(options.dryRun);
+    const includeComments = Boolean(options.includeComments);
+    const rewriteDescription = Boolean(options.rewriteDescription);
+    // If rewriting, validate refs once up front so we can both wrap the description and
+    // pass the resolved map down to autoLink — avoids a second resolve round trip.
+    const rewrite = rewriteDescription
+        ? await prepareDescriptionRewrite(description, identifier, linearService, graphQLService)
+        : { preResolved: undefined, wrapped: undefined };
+    const autoLinked = await linkReferencesForIssue({
+        issueUuid: resolvedId,
+        identifier,
+        description,
+        includeComments,
+        dryRun,
+        graphQLService,
+        linearService,
+        preResolved: rewrite.preResolved,
+    });
+    let descriptionRewritten = false;
+    if (rewriteDescription && rewrite.wrapped && !dryRun) {
+        await pushDescriptionUpdate(resolvedId, rewrite.wrapped, graphQLService);
+        descriptionRewritten = true;
+    }
+    outputSuccess({
+        id: resolvedId,
+        identifier,
+        title: issue.title,
+        autoLinked,
+        ...(rewriteDescription
+            ? {
+                descriptionRewritten,
+                ...(dryRun && rewrite.wrapped
+                    ? { descriptionPreview: rewrite.wrapped }
+                    : {}),
+            }
+            : {}),
+        meta: {
+            dryRun,
+            includeComments,
+            ...(rewriteDescription ? { rewriteDescription: true } : {}),
+        },
+    });
+}
+async function handleLinkReferencesBatch(teamInput, options, graphQLService, linearService) {
+    const teamId = resolveTeam(teamInput);
+    const limit = options.limit
+        ? parsePositiveInt(options.limit, "--limit")
+        : 100;
+    const dryRun = Boolean(options.dryRun);
+    const includeComments = Boolean(options.includeComments);
+    const scan = await graphQLService.rawRequest(SCAN_ISSUES_QUERY, {
+        filter: { team: { id: { eq: teamId } } },
+        first: limit,
+    });
+    const nodes = scan.issues.nodes;
+    const entries = [];
+    for (const node of nodes) {
+        const issueUuid = node.id;
+        const identifier = node.identifier;
+        const description = node.description ?? "";
+        const autoLinked = await linkReferencesForIssue({
+            issueUuid,
+            identifier,
+            description,
+            includeComments,
+            dryRun,
+            graphQLService,
+            linearService,
+        });
+        entries.push({ identifier, autoLinked });
+    }
+    // Summary counts across the batch
+    const totalLinked = entries.reduce((n, e) => n + e.autoLinked.linked.length, 0);
+    const totalSkipped = entries.reduce((n, e) => n + e.autoLinked.skipped.length, 0);
+    const totalFailed = entries.reduce((n, e) => n + e.autoLinked.failed.length, 0);
+    outputSuccess({
+        data: entries,
+        meta: {
+            count: entries.length,
+            team: teamInput,
+            dryRun,
+            includeComments,
+            totals: {
+                linked: totalLinked,
+                skipped: totalSkipped,
+                failed: totalFailed,
+            },
+        },
+    });
+}
+export async function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    if (options.team) {
+        if (issueIdOrTeamFlag) {
+            throw new Error("Provide either an issueId positional argument OR --team, not both. With --team, omit the issueId.");
+        }
+        if (options.rewriteDescription) {
+            throw new Error("--rewrite-description is single-issue only. Use it case by case (one issueId per invocation) — bulk description rewrites bot-author the whole team's history.");
+        }
+        return handleLinkReferencesBatch(options.team, options, graphQLService, linearService);
+    }
+    if (!issueIdOrTeamFlag) {
+        throw new Error("issueId is required (or use --team <key> to scan a whole team)");
+    }
+    return handleLinkReferencesSingle(issueIdOrTeamFlag, options, graphQLService, linearService);
+}

package/dist/commands/issues/relations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Issue-relation helpers — `transformIssueRelation` for the create
+ * path, plus the `RelatedIssueEntry` builders used by the
+ * `issues related` query path.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import type { RelationIncomingNode, RelationOutgoingNode } from "../../queries/issues-types.js";
+import type { LinearIssueRelation, LinearPriority } from "../../types/linear.js";
+import type { GraphQLService } from "../../utils/graphql-service.js";
+import type { LinearService } from "../../utils/linear-service.js";
+/**
+ * Walk the `--related-to` / `--blocks` / `--blocked-by` /
+ * `--duplicate-of` flags and create the corresponding
+ * IssueRelation rows. Used by `issues create`.
+ */
+export declare function createRelations(sourceId: string, options: Record<string, unknown>, graphQLService: GraphQLService, linearService: LinearService): Promise<LinearIssueRelation[]>;
+export interface RelatedIssueEntry {
+    direction: "outgoing" | "incoming";
+    id: string;
+    issue: {
+        id: string;
+        identifier: string;
+        title: string;
+        state?: {
+            id: string;
+            name: string;
+        };
+        priority?: LinearPriority;
+        assignee?: {
+            id: string;
+            name: string;
+        };
+        team?: {
+            id: string;
+            key: string;
+            name: string;
+        };
+    };
+    type: string;
+}
+export declare function buildOutgoingRelationEntries(nodes: RelationOutgoingNode[] | undefined): RelatedIssueEntry[];
+export declare function buildIncomingRelationEntries(nodes: RelationIncomingNode[] | undefined): RelatedIssueEntry[];

package/dist/commands/issues/relations.js

@@ -0,0 +1,132 @@
+/**
+ * Issue-relation helpers — `transformIssueRelation` for the create
+ * path, plus the `RelatedIssueEntry` builders used by the
+ * `issues related` query path.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import { ISSUE_RELATION_CREATE_MUTATION } from "../../queries/issues.js";
+import { splitList } from "../../utils/validators.js";
+function transformIssueRelation(rel) {
+    return {
+        id: rel.id,
+        type: rel.type,
+        issue: {
+            id: rel.issue.id,
+            identifier: rel.issue.identifier,
+            title: rel.issue.title,
+        },
+        relatedIssue: {
+            id: rel.relatedIssue.id,
+            identifier: rel.relatedIssue.identifier,
+            title: rel.relatedIssue.title,
+        },
+    };
+}
+/**
+ * Walk the `--related-to` / `--blocks` / `--blocked-by` /
+ * `--duplicate-of` flags and create the corresponding
+ * IssueRelation rows. Used by `issues create`.
+ */
+export async function createRelations(sourceId, options, graphQLService, linearService) {
+    const relations = [];
+    const relationSpecs = [
+        { option: "relatedTo", type: "related" },
+        { option: "blocks", type: "blocks" },
+        { option: "blockedBy", type: "blocks", reverse: true },
+        { option: "duplicateOf", type: "duplicate" },
+    ];
+    for (const spec of relationSpecs) {
+        const value = options[spec.option];
+        if (!value) {
+            continue;
+        }
+        for (const id of splitList(value)) {
+            const targetId = await linearService.resolveIssueId(id);
+            const result = await graphQLService.rawRequest(ISSUE_RELATION_CREATE_MUTATION, {
+                input: {
+                    issueId: spec.reverse ? targetId : sourceId,
+                    relatedIssueId: spec.reverse ? sourceId : targetId,
+                    type: spec.type,
+                },
+            });
+            const issueRelation = result.issueRelationCreate.issueRelation;
+            if (!issueRelation) {
+                throw new Error(`Failed to create ${spec.type} relation from ${sourceId} to ${id}`);
+            }
+            relations.push(transformIssueRelation(issueRelation));
+        }
+    }
+    return relations;
+}
+/**
+ * Invert relation type for incoming (inverse) relations so the output
+ * reads naturally from the perspective of the queried issue. E.g. if
+ * DEV-100 "blocks" DEV-200, and we query DEV-200, the inverse relation
+ * type is "blocks" but direction is incoming → "blockedBy".
+ */
+function normalizeInverseType(type) {
+    if (type === "blocks") {
+        return "blockedBy";
+    }
+    return type;
+}
+function buildRelatedIssueSummary(peer) {
+    return {
+        id: peer.id,
+        identifier: peer.identifier,
+        title: peer.title,
+        ...(peer.state
+            ? { state: { id: peer.state.id, name: peer.state.name } }
+            : {}),
+        ...(peer.priority == null ? {} : { priority: peer.priority }),
+        ...(peer.assignee
+            ? {
+                assignee: {
+                    id: peer.assignee.id,
+                    name: peer.assignee.name,
+                },
+            }
+            : {}),
+        ...(peer.team
+            ? {
+                team: {
+                    id: peer.team.id,
+                    key: peer.team.key,
+                    name: peer.team.name,
+                },
+            }
+            : {}),
+    };
+}
+export function buildOutgoingRelationEntries(nodes) {
+    const entries = [];
+    for (const rel of nodes ?? []) {
+        if (!rel.relatedIssue) {
+            continue;
+        }
+        entries.push({
+            id: rel.id,
+            type: rel.type,
+            direction: "outgoing",
+            issue: buildRelatedIssueSummary(rel.relatedIssue),
+        });
+    }
+    return entries;
+}
+export function buildIncomingRelationEntries(nodes) {
+    const entries = [];
+    for (const rel of nodes ?? []) {
+        if (!rel.issue) {
+            continue;
+        }
+        entries.push({
+            id: rel.id,
+            type: normalizeInverseType(rel.type),
+            direction: "incoming",
+            issue: buildRelatedIssueSummary(rel.issue),
+        });
+    }
+    return entries;
+}