@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/utils/project-slug.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parse a Linear project URL or bare slug-id into the `slugId` form that
+ * Linear's GraphQL `ProjectFilter.slugId` accepts.
+ *
+ * Linear project URLs look like:
+ *   https://linear.app/<workspace>/project/<slug>-<12-hex>/<view>
+ *
+ * The slug-id is the `<slug>-<12-hex>` segment (kebab-case name followed
+ * by a 12-character hex suffix). Linear uses this exact string as the
+ * unique `slugId` field on the Project type.
+ *
+ * Accepts:
+ *   - Full URL form: extracts the slug-id from the path
+ *   - Bare slug-id: `tools-and-standardization-40815d9beb16`
+ *   - Trailing path / query string is tolerated (`/overview`, `?foo=bar`)
+ *
+ * Returns `null` when the input is neither — caller can then fall through
+ * to name-based or UUID-based resolution. Canonical UUIDs are rejected
+ * here so that `isUuid()` callers stay the authoritative UUID path.
+ */
+export declare function parseProjectSlugId(input: string): string | null;

package/dist/utils/project-slug.js

@@ -0,0 +1,45 @@
+import { isUuid } from "./uuid.js";
+/**
+ * Parse a Linear project URL or bare slug-id into the `slugId` form that
+ * Linear's GraphQL `ProjectFilter.slugId` accepts.
+ *
+ * Linear project URLs look like:
+ *   https://linear.app/<workspace>/project/<slug>-<12-hex>/<view>
+ *
+ * The slug-id is the `<slug>-<12-hex>` segment (kebab-case name followed
+ * by a 12-character hex suffix). Linear uses this exact string as the
+ * unique `slugId` field on the Project type.
+ *
+ * Accepts:
+ *   - Full URL form: extracts the slug-id from the path
+ *   - Bare slug-id: `tools-and-standardization-40815d9beb16`
+ *   - Trailing path / query string is tolerated (`/overview`, `?foo=bar`)
+ *
+ * Returns `null` when the input is neither — caller can then fall through
+ * to name-based or UUID-based resolution. Canonical UUIDs are rejected
+ * here so that `isUuid()` callers stay the authoritative UUID path.
+ */
+export function parseProjectSlugId(input) {
+    const trimmed = input.trim();
+    if (!trimmed || isUuid(trimmed)) {
+        return null;
+    }
+    const urlMatch = trimmed.match(/\blinear\.app\/[^/\s]+\/project\/([^/?#\s]+)/i);
+    if (urlMatch) {
+        const candidate = urlMatch[1];
+        return looksLikeSlugId(candidate) ? candidate : null;
+    }
+    if (looksLikeSlugId(trimmed)) {
+        return trimmed;
+    }
+    return null;
+}
+/**
+ * A Linear project slug-id is a kebab-case name segment followed by a
+ * 12-character hex suffix. The minimum form is just the 12 hex chars
+ * (when the project name slugifies to empty), but in practice there's
+ * always at least one name segment.
+ */
+function looksLikeSlugId(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{12}$/i.test(value);
+}

package/dist/utils/protected-ranges.d.ts

@@ -17,6 +17,20 @@
  */
 /** Linear identifier shape: ABC-123, EMW-1, DEV-3592. */
 export declare const IDENTIFIER_REGEX: RegExp;
+/**
+ * Find the first position in `s` where a close-bracket character
+ * appears without a matching opener earlier in the string. Returns
+ * `s.length` if all close-brackets are balanced. Used to truncate
+ * a bare-URL match at the first unbalanced `)`, `]`, or `}` —
+ * exactly the position CommonMark treats as the URL terminator.
+ *
+ * Exported for direct unit testing. Depth counters per bracket type
+ * are independent — pathological interleavings like `[(a]b)` don't
+ * trigger an unbalance, which errs toward keeping a URL whole rather
+ * than over-truncating (no real-world URL nests bracket types this
+ * way).
+ */
+export declare function firstUnbalancedClose(s: string): number;
 export interface ProtectedRange {
     end: number;
     start: number;

package/dist/utils/protected-ranges.js

@@ -33,7 +33,87 @@ const ANGLE_AUTOLINK_REGEX = /<[^>\s]+>/g;
 // Bare URLs in prose. We protect these so identifiers inside path
 // components (e.g. "https://github.com/foo/DEV-100") don't get
 // processed.
-const BARE_URL_REGEX = /https?:\/\/\S+/g;
+//
+// Match strategy follows CommonMark's "extended autolink" rule:
+//
+// 1. Greedy match up to whitespace or angle/quote terminators
+//    (`<`, `>`, `"`). Parens and brackets stay IN the match — they
+//    appear inside legitimate URLs (Wikipedia article paths, Next.js
+//    route groups like `/docs/app/(group)/page`, CDN signing-key
+//    query strings, etc.).
+// 2. Post-process via `trimBareUrlTrailingPunct` to strip UNBALANCED
+//    trailing brackets and stand-alone punctuation. So
+//    `https://example.com/foo)DEV-100` correctly terminates at
+//    `…foo` (the closing paren is unbalanced — no opener inside the
+//    match), while `https://en.wikipedia.org/wiki/Foo_(bar)` keeps
+//    its balanced parens intact.
+//
+// Pre-fix `https?:\/\/\S+` greedily consumed everything to the next
+// whitespace and silently hid identifiers in position-dependent
+// prose. A char-class exclusion of `)`, `]`, `}` over-corrected and
+// broke Wikipedia / route-group URLs (cycle 2 finding on PR #75).
+// The balanced-paren trim is the CommonMark-faithful middle ground.
+const BARE_URL_REGEX = /https?:\/\/[^\s<>"]+/g;
+/**
+ * Find the first position in `s` where a close-bracket character
+ * appears without a matching opener earlier in the string. Returns
+ * `s.length` if all close-brackets are balanced. Used to truncate
+ * a bare-URL match at the first unbalanced `)`, `]`, or `}` —
+ * exactly the position CommonMark treats as the URL terminator.
+ *
+ * Exported for direct unit testing. Depth counters per bracket type
+ * are independent — pathological interleavings like `[(a]b)` don't
+ * trigger an unbalance, which errs toward keeping a URL whole rather
+ * than over-truncating (no real-world URL nests bracket types this
+ * way).
+ */
+export function firstUnbalancedClose(s) {
+    let parenDepth = 0;
+    let brackDepth = 0;
+    let braceDepth = 0;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === "(")
+            parenDepth++;
+        else if (ch === ")") {
+            if (parenDepth === 0)
+                return i;
+            parenDepth--;
+        }
+        else if (ch === "[")
+            brackDepth++;
+        else if (ch === "]") {
+            if (brackDepth === 0)
+                return i;
+            brackDepth--;
+        }
+        else if (ch === "{")
+            braceDepth++;
+        else if (ch === "}") {
+            if (braceDepth === 0)
+                return i;
+            braceDepth--;
+        }
+    }
+    return s.length;
+}
+function trimBareUrlTrailingPunct(url) {
+    // First: truncate at the first unbalanced bracket. So
+    // `https://example.com/foo)DEV-100` (no `(` opener inside) terminates
+    // at the `)` regardless of what follows it; `Foo_(bar)/DEV` keeps
+    // the balanced `(bar)` intact.
+    let trimmed = url.slice(0, firstUnbalancedClose(url));
+    // Then: strip standard trailing sentence-terminators (`.`, `,`, `;`,
+    // `:`, `!`, `?`). These never appear in legitimate URL paths at the
+    // very end, but they're commonly adjacent to URLs in prose. The
+    // char class deliberately excludes `)`, `]`, `}` — those are
+    // already handled by firstUnbalancedClose above, where the
+    // balanced/unbalanced check lives.
+    while (trimmed.length > 0 && /[.,;:!?]$/.test(trimmed)) {
+        trimmed = trimmed.slice(0, -1);
+    }
+    return trimmed;
+}
 /**
  * Find ranges of `text` that should NOT have identifiers processed.
  * Covered: fenced code, inline backticks, existing markdown links,
@@ -54,13 +134,19 @@ export function findProtectedRanges(text) {
         // clarity here.
         SLACK_LINK_REGEX,
         ANGLE_AUTOLINK_REGEX,
-        BARE_URL_REGEX,
     ]) {
         for (const m of text.matchAll(re)) {
             const start = m.index ?? 0;
             ranges.push({ start, end: start + m[0].length });
         }
     }
+    // Bare URLs need the trailing-punctuation trim that's hard to express
+    // in pure regex (depends on bracket-balance inside the match).
+    for (const m of text.matchAll(BARE_URL_REGEX)) {
+        const start = m.index ?? 0;
+        const trimmed = trimBareUrlTrailingPunct(m[0]);
+        ranges.push({ start, end: start + trimmed.length });
+    }
     return ranges;
 }
 export function isProtected(pos, ranges) {

package/dist/utils/sanitize-for-log.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Strip anything that looks like a Linear API/OAuth token from a string.
+ *
+ * Defense in depth: today the @linear/sdk error message embeds `{ query,
+ * variables }` but not the Authorization header. A future SDK upgrade that
+ * includes headers (which upstream graphql-request has done historically)
+ * would otherwise silently write `Bearer lin_api_…` into stdout, shell
+ * history, or CI logs. The regex also catches token shapes that may show
+ * up in custom error wrappers — e.g. a network proxy that echoes the
+ * Bearer header in its 502 body.
+ *
+ * Originally lived in `commands/init/token.ts` for the wizard's error
+ * formatting. Hoisted to `utils/` so the central error path
+ * (`output.ts`'s `outputError`) can use it too — that path runs on
+ * every non-wizard CLI invocation. `init/token.ts` re-exports the
+ * symbol so existing imports under `init/` keep working.
+ *
+ * The OAuth token-exchange / refresh / revoke paths also call this
+ * function at source (`auth/oauth-token.ts`'s `postForm` + `revokeToken`,
+ * `auth/token-resolver.ts`'s refresh-failure rewrap) so a future caller
+ * that catches+rethrows or logs mid-chain can't leak a token before the
+ * error reaches `outputError`. Defense in depth (DEV-4065).
+ */
+export declare function sanitizeForLog(text: string): string;

package/dist/utils/sanitize-for-log.js

@@ -0,0 +1,38 @@
+/**
+ * Strip anything that looks like a Linear API/OAuth token from a string.
+ *
+ * Defense in depth: today the @linear/sdk error message embeds `{ query,
+ * variables }` but not the Authorization header. A future SDK upgrade that
+ * includes headers (which upstream graphql-request has done historically)
+ * would otherwise silently write `Bearer lin_api_…` into stdout, shell
+ * history, or CI logs. The regex also catches token shapes that may show
+ * up in custom error wrappers — e.g. a network proxy that echoes the
+ * Bearer header in its 502 body.
+ *
+ * Originally lived in `commands/init/token.ts` for the wizard's error
+ * formatting. Hoisted to `utils/` so the central error path
+ * (`output.ts`'s `outputError`) can use it too — that path runs on
+ * every non-wizard CLI invocation. `init/token.ts` re-exports the
+ * symbol so existing imports under `init/` keep working.
+ *
+ * The OAuth token-exchange / refresh / revoke paths also call this
+ * function at source (`auth/oauth-token.ts`'s `postForm` + `revokeToken`,
+ * `auth/token-resolver.ts`'s refresh-failure rewrap) so a future caller
+ * that catches+rethrows or logs mid-chain can't leak a token before the
+ * error reaches `outputError`. Defense in depth (DEV-4065).
+ */
+// Personal-API tokens (`lin_api_…`) and OAuth access/refresh tokens
+// (`lin_oauth_…`).
+const TOKEN_PREFIX_RE = /lin_(api|oauth)_[A-Za-z0-9_-]{16,}/g;
+// High-entropy bearer payload fallback: catches generic Bearer-style
+// strings adjacent to Authorization / Bearer keywords. Useful for
+// future SDK error wrappers that might leak headers without the
+// `lin_` prefix.
+const BEARER_PAYLOAD_RE = /(\b(?:Authorization|Bearer)\b[:\s]*)([A-Za-z0-9_\-/+=]{40,})/gi;
+export function sanitizeForLog(text) {
+    return text
+        .replace(TOKEN_PREFIX_RE, (m) => m.startsWith("lin_oauth_")
+        ? "lin_oauth_***REDACTED***"
+        : "lin_api_***REDACTED***")
+        .replace(BEARER_PAYLOAD_RE, "$1***REDACTED***");
+}

package/dist/utils/table-formatter.js

@@ -86,6 +86,19 @@ const ALL_COLUMNS = {
             return atIdx > 0 ? name.slice(0, atIdx) : name;
         },
     },
+    delegate: {
+        key: "delegate",
+        header: "Delegate",
+        width: 20,
+        extract: (i) => {
+            if (!i.delegate) {
+                return "—";
+            }
+            const name = i.delegate.name;
+            const atIdx = name.indexOf("@");
+            return atIdx > 0 ? name.slice(0, atIdx) : name;
+        },
+    },
     project: {
         key: "project",
         header: "Project",
@@ -229,6 +242,17 @@ const MD_COLUMNS = {
             return atIdx > 0 ? name.slice(0, atIdx) : name;
         },
     },
+    delegate: {
+        header: "Delegate",
+        extract: (i) => {
+            if (!i.delegate) {
+                return "—";
+            }
+            const name = i.delegate.name;
+            const atIdx = name.indexOf("@");
+            return atIdx > 0 ? name.slice(0, atIdx) : name;
+        },
+    },
     project: {
         header: "Project",
         extract: (i) => i.project?.name ?? "—",

package/dist/utils/validators.d.ts

@@ -1,3 +1,4 @@
+import type { LinearPriority } from "../types/linear.js";
 export declare function parsePositiveInt(value: string, flagName: string): number;
 /**
  * Parse a single priority value (for `issues create --priority`, `issues update --priority`).
@@ -5,8 +6,12 @@ export declare function parsePositiveInt(value: string, flagName: string): numbe
  * Accepts:
  *   - keywords:  none | urgent | high | medium | normal | low
  *   - numbers:   0 (no priority), 1 (urgent), 2 (high), 3 (medium), 4 (low)
+ *
+ * Narrows arbitrary string input to the `LinearPriority` literal union so
+ * downstream call sites get type-level guarantees that the value is in
+ * range — no `as 0 | 1 | 2 | 3 | 4` cast at the boundary.
  */
-export declare function validatePriority(value: string): number;
+export declare function validatePriority(value: string): LinearPriority;
 export declare function validateHexColor(value: string): string;
 export declare function validateIsoDate(value: string): string;
 /**
@@ -18,5 +23,5 @@ export declare function validateIsoDate(value: string): string;
  * resolve to `[]`.
  */
 export declare function splitList(value: string | undefined | null | false): string[];
-export declare function parsePriorityFilter(value: string): number[];
+export declare function parsePriorityFilter(value: string): LinearPriority[];
 export declare const PRIORITY_LABELS: Record<number, string>;

package/dist/utils/validators.js

@@ -14,6 +14,10 @@ export function parsePositiveInt(value, flagName) {
  * Accepts:
  *   - keywords:  none | urgent | high | medium | normal | low
  *   - numbers:   0 (no priority), 1 (urgent), 2 (high), 3 (medium), 4 (low)
+ *
+ * Narrows arbitrary string input to the `LinearPriority` literal union so
+ * downstream call sites get type-level guarantees that the value is in
+ * range — no `as 0 | 1 | 2 | 3 | 4` cast at the boundary.
  */
 export function validatePriority(value) {
     const asName = PRIORITY_NAMES[value.toLowerCase()];
@@ -24,6 +28,8 @@ export function validatePriority(value) {
     if (Number.isNaN(n) || n < 0 || n > 4) {
         throw invalidParameterError("--priority", `"${value}" is not valid. Use names (none, urgent, high, medium/normal, low) or numbers (0-4).`);
     }
+    // The 0-4 range check above is what narrows `n` to LinearPriority;
+    // TypeScript can't infer that automatically.
     return n;
 }
 export function validateHexColor(value) {

package/dist/utils/workspace-url.d.ts

@@ -1,4 +1,8 @@
 import type { GraphQLService } from "./graphql-service.js";
-export declare function getWorkspaceUrlKey(graphQLService: GraphQLService): Promise<string>;
+export interface GetWorkspaceUrlKeyOptions {
+    /** Highest-priority source. Typically the `--workspace-url-key` flag. */
+    override?: string;
+}
+export declare function getWorkspaceUrlKey(graphQLService?: GraphQLService, options?: GetWorkspaceUrlKeyOptions): Promise<string>;
 /** Test helper: clear the cached URL key. Not called from production code. */
 export declare function _resetWorkspaceUrlKeyCache(): void;

package/dist/utils/workspace-url.js

@@ -4,11 +4,20 @@ import { loadConfig } from "../config/config.js";
  * issue URLs). Used to build canonical markdown link URLs like
  * `https://linear.app/<urlKey>/issue/<identifier>/`.
  *
- * Resolution order:
- *   1. `config.workspaceUrlKey` if explicitly set in el-linear config
- *   2. `viewer.organization.urlKey` from the Linear API (fetched once, cached)
+ * Resolution order (highest priority first):
  *
- * Cached in-process for the lifetime of the CLI invocation.
+ *   1. `options.override` — typically wired from a `--workspace-url-key` CLI flag
+ *      (per-invocation, wins over everything).
+ *   2. `EL_LINEAR_WORKSPACE_URL_KEY` env var.
+ *   3. `config.workspaceUrlKey` from `~/.config/el-linear/config.json`.
+ *   4. Live `viewer.organization.urlKey` GraphQL query (cached in-process).
+ *
+ * Layers 1–3 short-circuit without touching the network — this makes
+ * `el-linear refs wrap --no-validate` work offline once any one of them
+ * is set. Layer 4 is the original behavior preserved as a fallback.
+ *
+ * The graphQLService is only needed for layer 4 — pass `undefined` (or omit it)
+ * when the caller knows the network will not be used.
  */
 const VIEWER_ORG_URL_KEY_QUERY = /* GraphQL */ `
   query ViewerOrgUrlKey {
@@ -19,15 +28,52 @@ const VIEWER_ORG_URL_KEY_QUERY = /* GraphQL */ `
     }
   }
 `;
+const WORKSPACE_URL_KEY_ENV = "EL_LINEAR_WORKSPACE_URL_KEY";
+// Linear workspace URL keys are URL-safe slugs. The Linear API itself
+// validates this shape (`viewerIsValid` in init/token.ts uses the same
+// regex). Applying the check on env + config reads closes the gap where
+// a malformed key (`EL_LINEAR_WORKSPACE_URL_KEY=" javascript:alert(1)#"`)
+// would otherwise flow into markdown link URLs verbatim. Live-API path
+// is already trusted because the value comes from `viewer.organization`.
+// DEV-4067.
+const VALID_URL_KEY_RE = /^[a-z0-9-]+$/i;
+function validateUrlKey(value, source) {
+    if (!VALID_URL_KEY_RE.test(value)) {
+        throw new Error(`Invalid Linear workspace URL key from ${source}: ${JSON.stringify(value)}. ` +
+            "Must match /^[a-z0-9-]+$/i (e.g. 'verticalint').");
+    }
+    return value;
+}
 let cachedUrlKey;
-export async function getWorkspaceUrlKey(graphQLService) {
+export async function getWorkspaceUrlKey(graphQLService, options = {}) {
+    // 1. Per-invocation override — highest priority.
+    if (options.override) {
+        return validateUrlKey(options.override, "--workspace-url-key flag");
+    }
+    // 2. Env var. Read on every call (cheap; lets tests/CI flip the value
+    //    mid-process without restarting). Not cached, so a test that sets
+    //    EL_LINEAR_WORKSPACE_URL_KEY then unsets it sees the unset state.
+    const envKey = process.env[WORKSPACE_URL_KEY_ENV];
+    if (envKey) {
+        return validateUrlKey(envKey, `${WORKSPACE_URL_KEY_ENV} env var`);
+    }
+    // Layers 3-4 are cached in-process — config and the live lookup are
+    // both stable for the CLI invocation's lifetime.
     if (cachedUrlKey) {
         return cachedUrlKey;
     }
+    // 3. Config override.
     const { workspaceUrlKey } = loadConfig();
     if (workspaceUrlKey) {
-        cachedUrlKey = workspaceUrlKey;
-        return workspaceUrlKey;
+        const validated = validateUrlKey(workspaceUrlKey, "config.workspaceUrlKey");
+        cachedUrlKey = validated;
+        return validated;
+    }
+    // 4. Live API lookup — requires a GraphQL service.
+    if (!graphQLService) {
+        throw new Error("Could not resolve Linear workspace URL key — no override, env, or config set, " +
+            "and no GraphQL service was provided for the live lookup. " +
+            `Set \`workspaceUrlKey\` in your el-linear config, or \`${WORKSPACE_URL_KEY_ENV}\` in the environment.`);
     }
     const data = await graphQLService.rawRequest(VIEWER_ORG_URL_KEY_QUERY);
     const fetched = data?.viewer?.organization?.urlKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.9.0",
+  "version": "1.15.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",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "@linear/sdk": "^83.0.0",
+    "@linear/sdk": "^84.0.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1"
   },