@enrichlayer/el-linear 1.15.0 → 1.17.0

package/dist/commands/comments.js

@@ -196,7 +196,28 @@ async function handleUpdateComment(commentId, options, command) {
     else {
         input.body = body;
     }
-    const result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
+    let result;
+    try {
+        result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
+    }
+    catch (err) {
+        // Same defense-in-depth fallback as `handleCreateComment` above: when
+        // Linear rejects `bodyData` (schema drift, unsupported node, validator
+        // quirk), retry the mutation with raw markdown `body` so the update
+        // goes through even if our prosemirror converter has fallen behind a
+        // schema change. The asymmetry between create and update used to mean
+        // any future drift would silently break updates while creates kept
+        // working — DEV-4261 closes that gap. Two call sites is the floor for
+        // extraction; copy-then-refactor on the third per the repo convention.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            const fallbackInput = { body };
+            result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input: fallbackInput });
+        }
+        else {
+            throw err;
+        }
+    }
     const mutation = result.commentUpdate;
     if (!mutation.success || !mutation.comment) {
         throw new Error("Failed to update comment");

package/dist/commands/documents.js

@@ -34,7 +34,7 @@ async function handleCreateDocument(options, command) {
         title: options.title,
         content: options.content,
         projectId: options.project
-            ? await linearService.resolveProjectId(options.project)
+            ? await linearService.resolveProjectId(options.project, options.team)
             : undefined,
         teamId: options.team
             ? await linearService.resolveTeamId(options.team)

package/dist/commands/issues.js

@@ -292,6 +292,10 @@ async function resolveCreateInputs(title, options, rootOpts) {
             title,
             assignee: effectiveAssignee,
             project: options.project,
+            // DEV-4084: scope the accepted type-label set to the team so the
+            // DEV team's `research` label validates without `--skip-validation`.
+            // Falls back to the workspace default when no team is provided.
+            team: options.team || config.defaultTeam || undefined,
         });
         // Apply normalized labels back so resolution uses the canonical names
         if (validationResult.normalizedLabels) {

package/dist/config/config.d.ts

@@ -47,6 +47,14 @@ export interface ElLinearConfig {
     validation?: {
         enabled: boolean;
         typeLabels?: string[];
+        /**
+         * Per-team overrides of the canonical type-label set. Keys are Linear
+         * team keys (uppercase, e.g. `DEV`). When set, an `issues create
+         * --team X` call validates labels against the team-scoped set rather
+         * than the workspace default — see `issue-validation.ts` for the
+         * built-in overrides (DEV-4084).
+         */
+        teamTypeLabels?: Record<string, string[]>;
     };
     /**
      * Optional override for the Linear workspace URL key (the part after

package/dist/config/error-enrichment.js

@@ -232,8 +232,13 @@ export async function enrichValidationErrors(result, options, services) {
     const projects = teamData.projects?.nodes ?? [];
     const members = teamData.members?.nodes ?? [];
     const labels = teamData.labels?.nodes ?? [];
-    const typeLabels = getCanonicalTypeLabels();
-    const inferred = options.title ? inferTypeFromTitle(options.title) : null;
+    // DEV-4084: scope the suggested type-label set to the team when one is
+    // known so the retry hint surfaces (e.g.) `research` instead of `spike`
+    // on the Dev team.
+    const typeLabels = getCanonicalTypeLabels(options.team);
+    const inferred = options.title
+        ? inferTypeFromTitle(options.title, options.team)
+        : null;
     for (let i = 0; i < result.errors.length; i++) {
         result.errors[i] = decorateError(result.errors[i], classifications[i], {
             projects,

package/dist/config/issue-validation.d.ts

@@ -13,6 +13,14 @@
  *
  * Exported so error-enrichment can reuse the same mapping when inferring a
  * type label from a title's first word.
+ *
+ * **Ambiguous-verb resolution.** When a verb belongs to multiple type sets
+ * (e.g. `Research` appears under both `spike` and `research`), the first
+ * declared type wins — `Object.entries` preserves insertion order, and
+ * `inferTypeFromTitle` filters by the team's accepted set before iterating.
+ * In practice no team accepts both `spike` and `research` (the synonyms),
+ * so the first-declared-wins rule never bites; if a future team accepts
+ * both, list the preferred one earlier in this map.
  */
 export declare const TYPE_VERB_MAP: Record<string, string[]>;
 export interface ValidationResult {
@@ -27,12 +35,23 @@ export interface ValidationInput {
     title: string;
     assignee: string | undefined;
     project: string | undefined;
+    /**
+     * Team key (e.g. `DEV`) the issue is being created on. When set, the
+     * validator consults the team-scoped `typeLabels` override (DEV-4084) so
+     * a team whose taxonomy doesn't include the workspace default (`spike`)
+     * can validate its own equivalent (`research`) without `--skip-validation`.
+     *
+     * `team` is otherwise advisory: it does not affect description/title/
+     * assignee/project requirements.
+     */
+    team?: string;
 }
 /**
- * Public accessor for the canonical type labels.
- * Used by error-enrichment when suggesting labels.
+ * Public accessor for the canonical type labels. Pass the team key to get
+ * the team-scoped set (DEV-4084); omit for the workspace default. Used by
+ * error-enrichment when suggesting labels.
  */
-export declare function getCanonicalTypeLabels(): string[];
+export declare function getCanonicalTypeLabels(team?: string): string[];
 /**
  * Find the canonical type label for a title's first word, if it matches a
  * known verb in TYPE_VERB_MAP. Returns the matched verb and inferred type,
@@ -53,7 +72,7 @@ export declare function getCanonicalTypeLabels(): string[];
  * conflate "warn about mismatch" with "suggest a default" and produce
  * subtle bugs (e.g. inferring a type the alignment check just rejected).
  */
-export declare function inferTypeFromTitle(title: string): {
+export declare function inferTypeFromTitle(title: string, team?: string): {
     verb: string;
     type: string;
 } | null;

package/dist/config/issue-validation.js

@@ -11,12 +11,54 @@ import { outputWarning } from "../utils/output.js";
 import { loadConfig } from "./config.js";
 /** Canonical type labels. Stored in config so they can be updated without code changes. */
 const DEFAULT_TYPE_LABELS = ["bug", "feature", "refactor", "chore", "spike"];
+/**
+ * Built-in per-team overrides for the canonical type-label set. Teams whose
+ * taxonomy diverges from the workspace default ship here so the CLI accepts
+ * their labels out of the box without forcing every operator to maintain a
+ * personal config override.
+ *
+ * DEV-4084: the Dev team uses `research` instead of `spike` (and has no
+ * `spike` label) — the DEV-3768 fix removed the silent `research → spike`
+ * alias correctly, but left the validator's accepted set workspace-wide,
+ * so DEV creators were forced into `--skip-validation` (which also drops
+ * title-verb, label-count, and description checks).
+ *
+ * This widens the accepted set for DEV (no rewrite — DEV-3768's no-silent-
+ * alias guarantee is preserved) so `--labels "research,tools"` validates
+ * cleanly on DEV while every other team keeps `spike`.
+ */
+const TEAM_TYPE_LABELS = {
+    DEV: ["bug", "feature", "refactor", "chore", "research"],
+};
+/**
+ * Verbs that indicate a `spike`-equivalent type. Shared between `spike` and
+ * its team-local synonym `research` so adding a new investigation verb only
+ * has to land in one place — without this constant the two arrays drift the
+ * next time someone adds e.g. `Probe`.
+ */
+const SPIKE_VERBS = [
+    "Research",
+    "Investigate",
+    "Explore",
+    "Evaluate",
+    "Audit",
+    "Benchmark",
+    "Test",
+];
 /**
  * Recommended leading verbs for each type label.
  * Title verb and type label should express the same intent.
  *
  * Exported so error-enrichment can reuse the same mapping when inferring a
  * type label from a title's first word.
+ *
+ * **Ambiguous-verb resolution.** When a verb belongs to multiple type sets
+ * (e.g. `Research` appears under both `spike` and `research`), the first
+ * declared type wins — `Object.entries` preserves insertion order, and
+ * `inferTypeFromTitle` filters by the team's accepted set before iterating.
+ * In practice no team accepts both `spike` and `research` (the synonyms),
+ * so the first-declared-wins rule never bites; if a future team accepts
+ * both, list the preferred one earlier in this map.
  */
 export const TYPE_VERB_MAP = {
     bug: ["Fix", "Resolve", "Patch", "Handle", "Address", "Correct"],
@@ -56,15 +98,13 @@ export const TYPE_VERB_MAP = {
         "Teardown",
         "Upgrade",
     ],
-    spike: [
-        "Research",
-        "Investigate",
-        "Explore",
-        "Evaluate",
-        "Audit",
-        "Benchmark",
-        "Test",
-    ],
+    spike: SPIKE_VERBS,
+    // Team-local synonym for `spike`. Active when the validator is scoped to
+    // a team whose `typeLabels` includes `research` (see `TEAM_TYPE_LABELS` /
+    // `validation.teamTypeLabels`). Shares `SPIKE_VERBS` so the two stay in
+    // lockstep — drift would silently produce different inferences depending
+    // on which team you're on.
+    research: SPIKE_VERBS,
     refactor: [
         "Refactor",
         "Restructure",
@@ -91,17 +131,50 @@ const LABEL_ALIASES = {
 function getValidationConfig() {
     const config = loadConfig();
     const validation = config.validation;
+    // User-supplied `teamTypeLabels` are layered on top of the built-in
+    // `TEAM_TYPE_LABELS` so an operator can add a new team's override
+    // without having to re-declare DEV's. A user override for an existing
+    // team key replaces the built-in entry for that key.
+    //
+    // Normalize user-config keys to uppercase before merging — Linear team
+    // keys are uppercase canonical, but an operator who writes
+    // `{ "dev": [...] }` (lowercase) should still hit DEV's override. Doing
+    // it here means `resolveTypeLabels` can rely on a uniformly uppercased
+    // map without re-walking on every lookup.
+    const userOverrides = {};
+    for (const [key, value] of Object.entries(validation?.teamTypeLabels ?? {})) {
+        userOverrides[key.toUpperCase()] = value;
+    }
+    const teamTypeLabels = {
+        ...TEAM_TYPE_LABELS,
+        ...userOverrides,
+    };
     return {
         enabled: validation?.enabled ?? true,
         typeLabels: validation?.typeLabels ?? DEFAULT_TYPE_LABELS,
+        teamTypeLabels,
     };
 }
 /**
- * Public accessor for the canonical type labels.
- * Used by error-enrichment when suggesting labels.
+ * Resolve the canonical type-label set for a team. DEV-4084: when the team
+ * has a per-team override (built-in or config-declared) that set is returned;
+ * otherwise the workspace default. The team key is normalized to uppercase
+ * because Linear team keys are case-insensitive but stored uppercase.
+ */
+function resolveTypeLabels(team) {
+    const cfg = getValidationConfig();
+    if (!team)
+        return cfg.typeLabels;
+    const teamKey = team.toUpperCase();
+    return cfg.teamTypeLabels[teamKey] ?? cfg.typeLabels;
+}
+/**
+ * Public accessor for the canonical type labels. Pass the team key to get
+ * the team-scoped set (DEV-4084); omit for the workspace default. Used by
+ * error-enrichment when suggesting labels.
  */
-export function getCanonicalTypeLabels() {
-    return getValidationConfig().typeLabels;
+export function getCanonicalTypeLabels(team) {
+    return resolveTypeLabels(team);
 }
 /**
  * Find the canonical type label for a title's first word, if it matches a
@@ -123,10 +196,18 @@ export function getCanonicalTypeLabels() {
  * conflate "warn about mismatch" with "suggest a default" and produce
  * subtle bugs (e.g. inferring a type the alignment check just rejected).
  */
-export function inferTypeFromTitle(title) {
+export function inferTypeFromTitle(title, team) {
     const lowered = title.toLowerCase();
+    // DEV-4084: when scoping to a team, only suggest a type that the team
+    // actually accepts. This makes "Research GraphQL caching options" on a
+    // DEV team infer `research` instead of `spike` (which DEV doesn't have)
+    // without disrupting other teams whose taxonomy still uses `spike`.
+    const allowedTypes = new Set(resolveTypeLabels(team));
+    const isAllowed = (type) => allowedTypes.has(type);
     // Multi-word verbs first ("Set up")
     for (const [type, verbs] of Object.entries(TYPE_VERB_MAP)) {
+        if (!isAllowed(type))
+            continue;
         for (const verb of verbs) {
             if (!verb.includes(" ")) {
                 continue;
@@ -144,6 +225,8 @@ export function inferTypeFromTitle(title) {
     }
     const firstLower = firstWord.toLowerCase();
     for (const [type, verbs] of Object.entries(TYPE_VERB_MAP)) {
+        if (!isAllowed(type))
+            continue;
         for (const verb of verbs) {
             if (verb.includes(" ")) {
                 continue;
@@ -182,6 +265,10 @@ export function validateIssueCreation(input) {
     if (!vConfig.enabled) {
         return result;
     }
+    // DEV-4084: scope the accepted type-label set to the team when one was
+    // passed. Falls back to the workspace default when no team is supplied
+    // or no override exists.
+    const typeLabels = resolveTypeLabels(input.team);
     // --- Label normalization (always runs when validation is on) ---
     if (input.labels && input.labels.length > 0) {
         result.normalizedLabels = input.labels.map((label) => {
@@ -196,21 +283,21 @@ export function validateIssueCreation(input) {
     // --- Required: labels must be provided ---
     if (effectiveLabels.length === 0) {
         result.errors.push("Missing --labels. At least one label is required, including a type label.\n" +
-            `  Valid type labels: ${vConfig.typeLabels.join(", ")}\n` +
+            `  Valid type labels: ${typeLabels.join(", ")}\n` +
             '  Example: --labels "bug,backend"');
     }
     else {
         // --- Required: exactly one type label ---
-        const typeLabelsFound = effectiveLabels.filter((l) => vConfig.typeLabels.includes(l.toLowerCase()));
+        const typeLabelsFound = effectiveLabels.filter((l) => typeLabels.includes(l.toLowerCase()));
         if (typeLabelsFound.length === 0) {
             result.errors.push("Missing type label. Exactly one required.\n" +
-                `  Valid type labels: ${vConfig.typeLabels.join(", ")}\n` +
+                `  Valid type labels: ${typeLabels.join(", ")}\n` +
                 `  Provided labels: ${effectiveLabels.join(", ")}\n` +
-                `  Example: --labels "${vConfig.typeLabels[0]},${effectiveLabels[0]}"`);
+                `  Example: --labels "${typeLabels[0]},${effectiveLabels[0]}"`);
         }
         else if (typeLabelsFound.length > 1) {
             result.errors.push(`Multiple type labels found: ${typeLabelsFound.join(", ")}. Exactly one required.\n` +
-                `  Valid type labels: ${vConfig.typeLabels.join(", ")}`);
+                `  Valid type labels: ${typeLabels.join(", ")}`);
         }
     }
     // --- Required: description must be provided ---
@@ -242,7 +329,7 @@ export function validateIssueCreation(input) {
         result.warnings.push("Consider starting the title with an action verb instead of an article.");
     }
     // --- Warning: title-verb / type-label alignment ---
-    const typeLabelsFound = effectiveLabels.filter((l) => vConfig.typeLabels.includes(l.toLowerCase()));
+    const typeLabelsFound = effectiveLabels.filter((l) => typeLabels.includes(l.toLowerCase()));
     if (typeLabelsFound.length === 1) {
         checkTitleVerbAlignment(input.title, typeLabelsFound[0].toLowerCase(), result);
     }

package/dist/output.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Public output utilities — secondary entry point for cross-CLI reuse.
+ *
+ * Other Enrich Layer CLIs (el-slack, el-sheets, el-audit, el-git,
+ * el-elasticsearch — currently in the `tools` monorepo) should depend on
+ * `@enrichlayer/el-linear` and import this module to share the same
+ * `--jq` / `--fields` / `--raw` / `--format summary` behavior and the
+ * canonical `{ data, meta }` envelope shape. DEV-3799.
+ *
+ * Why this exists rather than a separate package: linctl is the OSS
+ * canonical source of these patterns (DEV-3619, DEV-3637, DEV-3798); it
+ * already publishes to npm and ships compiled JS in `dist/`. Treating it
+ * as the host of the shared utilities means there is exactly one
+ * implementation, exactly one set of tests, and exactly one place where
+ * the envelope contract is documented. Tools-repo CLIs pick it up via
+ * `pnpm add @enrichlayer/el-linear` and `import { outputSuccess, ... }
+ * from "@enrichlayer/el-linear/output"`.
+ *
+ * Stable API — semver-tracked. Anything re-exported here MUST stay
+ * backwards-compatible across minor releases. Adding exports is fine;
+ * renaming or removing them is a breaking change.
+ *
+ * # Wiring (consumer recipe)
+ *
+ * Each CLI's `main.ts` registers four global options and a `preAction`
+ * hook to read them into the shared state:
+ *
+ * ```ts
+ * import { Command } from "commander";
+ * import {
+ *   setRawMode, setJqFilter, setFieldsFilter, setOutputFormat,
+ * } from "@enrichlayer/el-linear/output";
+ *
+ * const program = new Command()
+ *   .option("--raw", "strip { data, meta } wrapper from list output")
+ *   .option("--jq <filter>", "apply a jq filter to the JSON output")
+ *   .option("--fields <fields>", "comma-separated field allow-list")
+ *   .option("--format <fmt>", "json | summary", "json");
+ *
+ * program.hook("preAction", (_thisCommand, actionCommand) => {
+ *   const o = actionCommand.optsWithGlobals();
+ *   if (o.raw) setRawMode(true);
+ *   if (o.jq) setJqFilter(o.jq);
+ *   if (o.fields) {
+ *     setFieldsFilter(o.fields.split(",").map((s: string) => s.trim()));
+ *   }
+ *   setOutputFormat(o.format === "summary" ? "summary" : "json");
+ * });
+ * ```
+ *
+ * Then in each subcommand handler emit results via `outputList(data)` /
+ * `outputSingle(data)` / `outputSuccess(payload)`, wrap async actions in
+ * `handleAsyncCommand`, and buffer informational messages via
+ * `outputWarning`. The shared state in this module takes care of `--jq`,
+ * `--fields`, `--raw`, and summary rendering uniformly.
+ *
+ * Adapt the option names and flags to your CLI's existing conventions —
+ * the contract is the four setter calls (`setRawMode`, `setJqFilter`,
+ * `setFieldsFilter`, `setOutputFormat`), not the literal `--jq` /
+ * `--fields` / `--raw` / `--format` names. A CLI that already exposes
+ * `--json` / `--summary` shorthands can keep them as long as the
+ * preAction hook ends up calling the same setters with equivalent values.
+ *
+ * # What is NOT exported
+ *
+ * - `--format summary` dispatch tables are linctl-specific (Linear
+ *   resources). Other CLIs that want summary rendering should either
+ *   ship `--format json` only or register their own per-command summary
+ *   path that does not consume this module's `setOutputFormat("summary")`.
+ * - `outputError` is intentionally internal — it calls `process.exit(1)`
+ *   directly. Consumers funnel errors through `handleAsyncCommand`, which
+ *   in turn calls `outputError`. Don't re-export the bare function; the
+ *   wrapper is the contract.
+ * - Token-sanitization (`sanitizeForLog`) is internal to the error path.
+ *   Consumers that route errors through `handleAsyncCommand` automatically
+ *   get token redaction on the error path — no separate redactor needed
+ *   for that case. If a consumer wants sanitization for something OTHER
+ *   than thrown errors (e.g. a custom debug log), it should pull a small
+ *   redactor of its own; coupling token redaction to the output layer
+ *   would make this API surface stickier than it needs to be.
+ */
+export { type CliListEnvelope, getOutputFormat, handleAsyncCommand, type ListExtraMeta, type ListMeta, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, warnIfTruncated, } from "./utils/output.js";

package/dist/output.js

@@ -0,0 +1,82 @@
+/**
+ * Public output utilities — secondary entry point for cross-CLI reuse.
+ *
+ * Other Enrich Layer CLIs (el-slack, el-sheets, el-audit, el-git,
+ * el-elasticsearch — currently in the `tools` monorepo) should depend on
+ * `@enrichlayer/el-linear` and import this module to share the same
+ * `--jq` / `--fields` / `--raw` / `--format summary` behavior and the
+ * canonical `{ data, meta }` envelope shape. DEV-3799.
+ *
+ * Why this exists rather than a separate package: linctl is the OSS
+ * canonical source of these patterns (DEV-3619, DEV-3637, DEV-3798); it
+ * already publishes to npm and ships compiled JS in `dist/`. Treating it
+ * as the host of the shared utilities means there is exactly one
+ * implementation, exactly one set of tests, and exactly one place where
+ * the envelope contract is documented. Tools-repo CLIs pick it up via
+ * `pnpm add @enrichlayer/el-linear` and `import { outputSuccess, ... }
+ * from "@enrichlayer/el-linear/output"`.
+ *
+ * Stable API — semver-tracked. Anything re-exported here MUST stay
+ * backwards-compatible across minor releases. Adding exports is fine;
+ * renaming or removing them is a breaking change.
+ *
+ * # Wiring (consumer recipe)
+ *
+ * Each CLI's `main.ts` registers four global options and a `preAction`
+ * hook to read them into the shared state:
+ *
+ * ```ts
+ * import { Command } from "commander";
+ * import {
+ *   setRawMode, setJqFilter, setFieldsFilter, setOutputFormat,
+ * } from "@enrichlayer/el-linear/output";
+ *
+ * const program = new Command()
+ *   .option("--raw", "strip { data, meta } wrapper from list output")
+ *   .option("--jq <filter>", "apply a jq filter to the JSON output")
+ *   .option("--fields <fields>", "comma-separated field allow-list")
+ *   .option("--format <fmt>", "json | summary", "json");
+ *
+ * program.hook("preAction", (_thisCommand, actionCommand) => {
+ *   const o = actionCommand.optsWithGlobals();
+ *   if (o.raw) setRawMode(true);
+ *   if (o.jq) setJqFilter(o.jq);
+ *   if (o.fields) {
+ *     setFieldsFilter(o.fields.split(",").map((s: string) => s.trim()));
+ *   }
+ *   setOutputFormat(o.format === "summary" ? "summary" : "json");
+ * });
+ * ```
+ *
+ * Then in each subcommand handler emit results via `outputList(data)` /
+ * `outputSingle(data)` / `outputSuccess(payload)`, wrap async actions in
+ * `handleAsyncCommand`, and buffer informational messages via
+ * `outputWarning`. The shared state in this module takes care of `--jq`,
+ * `--fields`, `--raw`, and summary rendering uniformly.
+ *
+ * Adapt the option names and flags to your CLI's existing conventions —
+ * the contract is the four setter calls (`setRawMode`, `setJqFilter`,
+ * `setFieldsFilter`, `setOutputFormat`), not the literal `--jq` /
+ * `--fields` / `--raw` / `--format` names. A CLI that already exposes
+ * `--json` / `--summary` shorthands can keep them as long as the
+ * preAction hook ends up calling the same setters with equivalent values.
+ *
+ * # What is NOT exported
+ *
+ * - `--format summary` dispatch tables are linctl-specific (Linear
+ *   resources). Other CLIs that want summary rendering should either
+ *   ship `--format json` only or register their own per-command summary
+ *   path that does not consume this module's `setOutputFormat("summary")`.
+ * - `outputError` is intentionally internal — it calls `process.exit(1)`
+ *   directly. Consumers funnel errors through `handleAsyncCommand`, which
+ *   in turn calls `outputError`. Don't re-export the bare function; the
+ *   wrapper is the contract.
+ * - Token-sanitization (`sanitizeForLog`) is internal to the error path.
+ *   Consumers that route errors through `handleAsyncCommand` automatically
+ *   get token redaction on the error path — no separate redactor needed
+ *   for that case. If a consumer wants sanitization for something OTHER
+ *   than thrown errors (e.g. a custom debug log), it should pull a small
+ *   redactor of its own; coupling token redaction to the output layer
+ *   would make this API surface stickier than it needs to be.
+ */
+export { getOutputFormat, handleAsyncCommand, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, warnIfTruncated, } from "./utils/output.js";

package/dist/queries/issues.d.ts

@@ -22,7 +22,7 @@ export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdenti
  * by `id` (`projectsById`) so its milestones are still fetched for
  * `--project-milestone` name resolution; a name uses `projectsByName`.
  */
-export declare const BATCH_RESOLVE_FOR_UPDATE_QUERY = "\n  query BatchResolveForUpdate(\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $teamKey: String\n    $issueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $teamKey } } }\n          { number: { eq: $issueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n        team {\n          id\n          key\n        }\n        labels {\n          nodes {\n            id\n            name\n          }\n        }\n        project {\n          id\n          projectMilestones {\n            nodes {\n              id\n              name\n            }\n          }\n        }\n      }\n    }\n  }\n";
+export declare const BATCH_RESOLVE_FOR_UPDATE_QUERY = "\n  query BatchResolveForUpdate(\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $teamKey: String\n    $issueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 5\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $teamKey } } }\n          { number: { eq: $issueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n        team {\n          id\n          key\n        }\n        labels {\n          nodes {\n            id\n            name\n          }\n        }\n        project {\n          id\n          projectMilestones {\n            nodes {\n              id\n              name\n            }\n          }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_ISSUE_MUTATION = "\n  mutation CreateIssue($input: IssueCreateInput!) {\n    issueCreate(input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 export declare const UPDATE_ISSUE_MUTATION = "\n  mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {\n    issueUpdate(id: $id, input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 export declare const ARCHIVE_ISSUE_MUTATION = "\n  mutation ArchiveIssue($id: String!) {\n    issueArchive(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
@@ -46,7 +46,7 @@ export declare const DELETE_ISSUE_MUTATION = "\n  mutation DeleteIssue($id: Stri
  * so they carry distinct aliases and the service folds whichever ran
  * into `resolveResult.projects`.
  */
-export declare const BATCH_RESOLVE_FOR_CREATE_QUERY = "\n  query BatchResolveForCreate(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $parentTeamKey: String\n    $parentIssueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    teams(\n      filter: {\n        or: [\n          { key: { eq: $teamKey } }\n          { name: { eqIgnoreCase: $teamName } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        key\n        name\n      }\n    }\n\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    parentIssues: issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $parentTeamKey } } }\n          { number: { eq: $parentIssueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n      }\n    }\n  }\n";
+export declare const BATCH_RESOLVE_FOR_CREATE_QUERY = "\n  query BatchResolveForCreate(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $parentTeamKey: String\n    $parentIssueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    teams(\n      filter: {\n        or: [\n          { key: { eq: $teamKey } }\n          { name: { eqIgnoreCase: $teamName } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        key\n        name\n      }\n    }\n\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 5\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    parentIssues: issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $parentTeamKey } } }\n          { number: { eq: $parentIssueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n      }\n    }\n  }\n";
 /**
  * Build a label-resolution query filtered by names (case-insensitive).
  * Uses `or` + `eqIgnoreCase` since Linear's `in` filter may be case-sensitive.

package/dist/queries/issues.js

@@ -146,11 +146,14 @@ export const BATCH_RESOLVE_FOR_UPDATE_QUERY = `
   ) {
     projectsByName: projects(
       filter: { name: { eqIgnoreCase: $projectName } }
-      first: 1
+      first: 5
     ) @include(if: $hasProjectName) {
       nodes {
         id
         name
+        teams {
+          nodes { id key }
+        }
         projectMilestones {
           nodes {
             id
@@ -313,7 +316,7 @@ export const BATCH_RESOLVE_FOR_CREATE_QUERY = `
 
     projectsByName: projects(
       filter: { name: { eqIgnoreCase: $projectName } }
-      first: 1
+      first: 5
     ) @include(if: $hasProjectName) {
       nodes {
         id

package/dist/utils/graphql-issues-service.d.ts

@@ -175,6 +175,19 @@ export declare class GraphQLIssuesService {
     private executeCreateMutation;
     searchIssues(args: SearchIssueArgs): Promise<LinearIssue[]>;
     private resolveTeamId;
+    /**
+     * Pick a project ID from the batched name-lookup result.
+     *
+     * The batch query fetches up to 5 candidates by name (DEV-4103) so that
+     * a name shared across teams doesn't silently bind to whichever project
+     * Linear returned first. When a `--team` was supplied, prefer the
+     * candidate whose team set includes it; the downstream
+     * `validateProjectTeam` will then no-op (the team already matches).
+     * When multiple candidates exist and none of them are on the requested
+     * team (or no team was supplied), throw an explicit ambiguous-project
+     * error listing the candidate teams — far better than the prior silent
+     * cross-team match.
+     */
     private resolveProjectId;
     /**
      * Check that the resolved team is associated with the project.

package/dist/utils/graphql-issues-service.js

@@ -3,7 +3,7 @@ import { ARCHIVE_ISSUE_MUTATION, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_F
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
 import { toISOStringOrNow } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
-import { notFoundError } from "./error-messages.js";
+import { multipleMatchesError, notFoundError } from "./error-messages.js";
 import { parseIssueIdentifier, tryParseIssueIdentifier, } from "./identifier-parser.js";
 import { logger } from "./logger.js";
 import { isUuid } from "./uuid.js";
@@ -111,8 +111,15 @@ export class GraphQLIssuesService {
             teamIdForLabels = await this.fetchIssueTeamId(resolvedIssueId);
         }
         const finalLabelIds = await this.resolveLabelsWithMode(normalizedArgs.labelIds, resolveResult, labelMode, currentIssueLabels, teamIdForLabels, normalizedArgs.teamId);
+        // DEV-4103: scope project disambiguation by the issue's existing team
+        // so a `--project` name shared across teams binds to the issue's team
+        // rather than whichever project Linear happened to return first.
+        // `issueTeamId` is the right scope here — it's always a UUID and
+        // represents the team the issue currently lives on. `--team` is rare
+        // on update (and would imply a cross-team move that goes through
+        // separate validation paths anyway).
         const finalProjectId = normalizedArgs.projectId
-            ? this.resolveProjectId(normalizedArgs.projectId, resolveResult)
+            ? this.resolveProjectId(normalizedArgs.projectId, resolveResult, issueTeamId)
             : undefined;
         const { projectMilestoneNodes, issueProjectMilestoneNodes } = this.extractMilestoneNodes(normalizedArgs, resolveResult);
         const finalMilestoneId = this.resolveMilestoneId(normalizedArgs.milestoneId, resolveResult, projectMilestoneNodes, issueProjectMilestoneNodes);
@@ -272,7 +279,7 @@ export class GraphQLIssuesService {
             ? await this.resolveTeamId(args.teamId, resolveResult)
             : undefined;
         const projectId = args.projectId
-            ? this.resolveProjectId(args.projectId, resolveResult)
+            ? this.resolveProjectId(args.projectId, resolveResult, teamId)
             : undefined;
         // Validate team-project compatibility and auto-correct when possible
         if (projectId && teamId && args.projectId) {
@@ -423,7 +430,20 @@ export class GraphQLIssuesService {
         // Exact GraphQL match failed — fall back to prefix matching via LinearService
         return this.linearService.resolveTeamId(teamId);
     }
-    resolveProjectId(projectId, resolveResult) {
+    /**
+     * Pick a project ID from the batched name-lookup result.
+     *
+     * The batch query fetches up to 5 candidates by name (DEV-4103) so that
+     * a name shared across teams doesn't silently bind to whichever project
+     * Linear returned first. When a `--team` was supplied, prefer the
+     * candidate whose team set includes it; the downstream
+     * `validateProjectTeam` will then no-op (the team already matches).
+     * When multiple candidates exist and none of them are on the requested
+     * team (or no team was supplied), throw an explicit ambiguous-project
+     * error listing the candidate teams — far better than the prior silent
+     * cross-team match.
+     */
+    resolveProjectId(projectId, resolveResult, teamId) {
         if (isUuid(projectId)) {
             // The create/update batch queries fetch a `projectsById` block for a
             // UUID `--project` (folded into `resolveResult.projects`). An empty
@@ -443,7 +463,25 @@ export class GraphQLIssuesService {
         if (!projectNodes?.length) {
             throw notFoundError("Project", projectId);
         }
-        return projectNodes[0].id;
+        if (projectNodes.length === 1) {
+            return projectNodes[0].id;
+        }
+        // Multiple matches — disambiguate by team when possible.
+        if (teamId) {
+            const teamMatches = projectNodes.filter((n) => n.teams?.nodes.some((t) => t.id === teamId));
+            if (teamMatches.length === 1) {
+                return teamMatches[0].id;
+            }
+            if (teamMatches.length > 1) {
+                // Same name, same team — extremely rare but Linear permits it.
+                // Fall through to ambiguity error so the user picks by URL/slug.
+            }
+        }
+        const descriptions = projectNodes.map((n) => {
+            const teamKeys = n.teams?.nodes.map((t) => t.key) ?? [];
+            return `${n.id} (teams: ${teamKeys.join(", ") || "none"})`;
+        });
+        throw multipleMatchesError("project", projectId, descriptions, "scope with --team, or pass the project URL/slug-id");
     }
     /**
      * Check that the resolved team is associated with the project.

package/dist/utils/linear-service.d.ts

@@ -35,7 +35,21 @@ export declare class LinearService {
     getCycles(teamFilter?: string, activeOnly?: boolean, limit?: number): Promise<LinearCycleSummary[]>;
     getCycleById(cycleId: string, issuesLimit?: number): Promise<LinearCycleDetail>;
     resolveCycleId(cycleNameOrId: string, teamFilter?: string): Promise<string>;
-    resolveProjectId(projectInput: string): Promise<string>;
+    /**
+     * Resolve a user-supplied project identifier to a UUID.
+     *
+     * Inputs (in order): UUID (pass-through), Linear URL or slug-id pair
+     * (unique by slug, resolved via `slugId` filter), or a plain name (case
+     * insensitive). DEV-4103: when a name resolution returns multiple matches
+     * across teams, the resolver disambiguates by `--team` when provided and
+     * throws an `ambiguous project` error otherwise — replacing the prior
+     * silent `first: 1` pick that could cross team boundaries.
+     *
+     * `teamInput` is the same string a user would pass to `--team`
+     * (key / name / UUID); it is resolved here when present so callers don't
+     * have to double-resolve.
+     */
+    resolveProjectId(projectInput: string, teamInput?: string): Promise<string>;
     /**
      * Normalize a user-supplied project input to a UUID when the input is
      * a URL or slug-id form. Pass-through for UUIDs and plain names — the

package/dist/utils/linear-service.js

@@ -471,7 +471,21 @@ export class LinearService {
         }
         return chosen.id;
     }
-    async resolveProjectId(projectInput) {
+    /**
+     * Resolve a user-supplied project identifier to a UUID.
+     *
+     * Inputs (in order): UUID (pass-through), Linear URL or slug-id pair
+     * (unique by slug, resolved via `slugId` filter), or a plain name (case
+     * insensitive). DEV-4103: when a name resolution returns multiple matches
+     * across teams, the resolver disambiguates by `--team` when provided and
+     * throws an `ambiguous project` error otherwise — replacing the prior
+     * silent `first: 1` pick that could cross team boundaries.
+     *
+     * `teamInput` is the same string a user would pass to `--team`
+     * (key / name / UUID); it is resolved here when present so callers don't
+     * have to double-resolve.
+     */
+    async resolveProjectId(projectInput, teamInput) {
         if (isUuid(projectInput)) {
             return projectInput;
         }
@@ -501,15 +515,46 @@ export class LinearService {
             // not-found error as the name path.
             throw notFoundError("Project", projectInput);
         }
-        const filter = { name: { eqIgnoreCase: projectInput } };
+        // DEV-4103: scope by team when provided so a name shared across teams
+        // doesn't resolve to a different team's project. Same SDK filter shape
+        // `getProjects` already uses for `--team` filtering.
+        const teamId = teamInput ? await this.resolveTeamId(teamInput) : undefined;
+        const filter = {
+            name: { eqIgnoreCase: projectInput },
+        };
+        if (teamId) {
+            // Matches the filter shape `getProjects` uses for `--team`.
+            filter.teams = { some: { id: { eq: teamId } } };
+        }
+        // `first: 5` is wide enough to detect ambiguity (same name across
+        // multiple teams) without paying for a deeper page. Linear's UI caps
+        // effective project-name collisions at a handful in practice; if a
+        // workspace ever exceeds this we'll see it as a still-ambiguous error
+        // listing the first 5 teams — better than a silent wrong pick.
         const projectsConnection = await this.client.projects({
             filter,
-            first: 1,
+            first: 5,
         });
         if (projectsConnection.nodes.length === 0) {
-            throw notFoundError("Project", projectInput);
+            const context = teamInput ? `on team "${teamInput}"` : undefined;
+            throw notFoundError("Project", projectInput, context);
+        }
+        if (projectsConnection.nodes.length === 1) {
+            return projectsConnection.nodes[0].id;
         }
-        return projectsConnection.nodes[0].id;
+        // Multiple candidates — collect team keys per candidate so the error
+        // names them concretely. Bounded N ≤ 5 keeps the per-edge resolver
+        // promise cheap (handful of round-trips on the rare ambiguous path).
+        const candidates = await Promise.all(projectsConnection.nodes.map(async (p) => {
+            const teams = await p.teams();
+            return {
+                id: p.id,
+                name: p.name,
+                teamKeys: teams.nodes.map((t) => t.key),
+            };
+        }));
+        const descriptions = candidates.map((c) => `${c.id} (teams: ${c.teamKeys.join(", ") || "none"})`);
+        throw multipleMatchesError("project", projectInput, descriptions, "scope with --team, or pass the project URL/slug-id");
     }
     /**
      * Normalize a user-supplied project input to a UUID when the input is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -9,6 +9,11 @@
     ".": {
       "types": "./dist/main.d.ts",
       "import": "./dist/main.js"
+    },
+    "./output": {
+      "types": "./dist/output.d.ts",
+      "import": "./dist/output.js",
+      "default": "./dist/output.js"
     }
   },
   "sideEffects": false,