@enrichlayer/el-linear 1.10.0 → 1.16.0

package/dist/commands/init/shared.d.ts

@@ -29,8 +29,30 @@ type DeepPartial<T> = T extends Array<infer _U> ? T : T extends object ? {
  */
 export type WizardConfig = DeepPartial<ElLinearConfig>;
 export declare function ensureConfigDir(): Promise<void>;
-export declare function readConfig(): Promise<WizardConfig>;
-export declare function writeConfig(config: WizardConfig): Promise<void>;
+export declare function readConfig(configPath?: string): Promise<WizardConfig>;
+export declare function writeConfig(config: WizardConfig, configPath?: string): Promise<void>;
+/**
+ * Run a read-modify-write update on the active profile's config.json under
+ * an exclusive file lock. The mutator receives the latest on-disk config
+ * (re-read inside the lock), and its return value is written back atomically.
+ *
+ * Use this anywhere two parallel wizard invocations could race a
+ * read → mutate → write sequence. Each `el-linear init <step>` re-reads the
+ * config and merges its slice; without serialization, the slower writer's
+ * mutation would clobber the faster writer's already-persisted changes.
+ *
+ * The interactive prompt phase MUST run outside the lock — prompts can sit
+ * waiting for user input longer than the lock's stale window. Seed prompts
+ * with a cheap pre-read, do the prompts, then call `updateConfig` with a
+ * mutator that re-reads and merges your slice on top of the latest state.
+ *
+ * The active-profile path is snapshotted ONCE at entry and threaded through
+ * `readConfig` + `writeConfig`. A theoretical mid-update profile switch
+ * (`--profile` is bound by the commander preAction before any subcommand
+ * runs, so this can't happen via the CLI today) can't cause a lock-A /
+ * read-or-write-B mismatch.
+ */
+export declare function updateConfig(mutator: (current: WizardConfig) => WizardConfig | Promise<WizardConfig>): Promise<void>;
 export declare function readToken(): Promise<string | null>;
 /**
  * Write the token to disk with mode 0600.

package/dist/commands/init/shared.js

@@ -8,6 +8,7 @@
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { withFileLock } from "../../auth/oauth-fs.js";
 import { ALIASES_PROGRESS_PATH, CONFIG_DIR, CONFIG_PATH, resolveActiveProfile, TOKEN_PATH, } from "../../config/paths.js";
 // Re-export for tests and call sites that already pulled the paths from here.
 export { ALIASES_PROGRESS_PATH, CONFIG_PATH, TOKEN_PATH };
@@ -65,9 +66,9 @@ export async function ensureConfigDir() {
         await fs.mkdir(dir, { recursive: true, mode: 0o700 });
     }
 }
-export async function readConfig() {
+export async function readConfig(configPath = activePaths().configPath) {
     try {
-        const raw = await fs.readFile(activePaths().configPath, "utf8");
+        const raw = await fs.readFile(configPath, "utf8");
         return JSON.parse(raw);
     }
     catch (err) {
@@ -77,11 +78,41 @@ export async function readConfig() {
         throw err;
     }
 }
-export async function writeConfig(config) {
+export async function writeConfig(config, configPath = activePaths().configPath) {
     await ensureConfigDir();
     // Stable key order so byte-identical config produces byte-identical output.
     const sorted = sortKeys(config);
-    await atomicWrite(activePaths().configPath, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
+    await atomicWrite(configPath, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
+}
+/**
+ * Run a read-modify-write update on the active profile's config.json under
+ * an exclusive file lock. The mutator receives the latest on-disk config
+ * (re-read inside the lock), and its return value is written back atomically.
+ *
+ * Use this anywhere two parallel wizard invocations could race a
+ * read → mutate → write sequence. Each `el-linear init <step>` re-reads the
+ * config and merges its slice; without serialization, the slower writer's
+ * mutation would clobber the faster writer's already-persisted changes.
+ *
+ * The interactive prompt phase MUST run outside the lock — prompts can sit
+ * waiting for user input longer than the lock's stale window. Seed prompts
+ * with a cheap pre-read, do the prompts, then call `updateConfig` with a
+ * mutator that re-reads and merges your slice on top of the latest state.
+ *
+ * The active-profile path is snapshotted ONCE at entry and threaded through
+ * `readConfig` + `writeConfig`. A theoretical mid-update profile switch
+ * (`--profile` is bound by the commander preAction before any subcommand
+ * runs, so this can't happen via the CLI today) can't cause a lock-A /
+ * read-or-write-B mismatch.
+ */
+export async function updateConfig(mutator) {
+    await ensureConfigDir();
+    const configPath = activePaths().configPath;
+    await withFileLock(configPath, async () => {
+        const current = await readConfig(configPath);
+        const next = await mutator(current);
+        await writeConfig(next, configPath);
+    });
 }
 export async function readToken() {
     try {

package/dist/commands/init/token.d.ts

@@ -5,6 +5,8 @@
  * before saving. Token is stored at ~/.config/el-linear/token (mode 0600),
  * never embedded in config.json.
  */
+import { sanitizeForLog } from "../../utils/sanitize-for-log.js";
+export { sanitizeForLog };
 interface ViewerResponse {
     viewer: {
         id: string;
@@ -17,11 +19,10 @@ interface ViewerResponse {
         };
     };
 }
-export interface TokenStepResult {
+interface TokenStepResult {
     token: string;
     viewer: ViewerResponse["viewer"];
 }
-export declare function sanitizeForLog(text: string): string;
 /**
  * Validate a Linear API token by fetching the viewer. Throws with a
  * sanitized user-readable message on auth failure — the error string is
@@ -39,4 +40,3 @@ export declare function runTokenStep(options?: {
     /** Skip the "replace existing?" prompt; always replace if existing is present. */
     force?: boolean;
 }): Promise<TokenStepResult>;
-export {};

package/dist/commands/init/token.js

@@ -7,7 +7,11 @@
  */
 import { confirm, password } from "@inquirer/prompts";
 import { GraphQLService } from "../../utils/graphql-service.js";
+import { sanitizeForLog } from "../../utils/sanitize-for-log.js";
 import { readToken, writeToken } from "./shared.js";
+// Re-export for legacy import paths under `init/`. New code should import
+// from `utils/sanitize-for-log.js` directly.
+export { sanitizeForLog };
 const TOKEN_GENERATION_URL = "https://linear.app/settings/account/security";
 const VIEWER_QUERY = /* GraphQL */ `
   query {
@@ -23,29 +27,6 @@ const VIEWER_QUERY = /* GraphQL */ `
     }
   }
 `;
-/**
- * Strip anything that looks like a Linear API 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 / CI logs. The regex
- * also catches token shapes that may show up in custom error wrappers.
- */
-// Personal-API tokens (`lin_api_…`) and OAuth access/refresh tokens
-// (`lin_oauth_…`). Pre-fix the regex only matched personal tokens.
-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***");
-}
 /**
  * Strict shape check on the viewer response. Treats whitespace-only fields as
  * "validated to nothing" — easy to forge with a malformed but truthy stub
@@ -73,7 +54,7 @@ function viewerIsValid(viewer) {
  * is redacted before it hits stdout.
  */
 export async function validateToken(token) {
-    const service = new GraphQLService(token);
+    const service = new GraphQLService({ apiKey: token });
     let data;
     try {
         data = await service.rawRequest(VIEWER_QUERY);

package/dist/commands/init/workspace.d.ts

@@ -5,7 +5,7 @@
  * Lets the user pick a default team, optional. Skip-by-default.
  */
 import type { WizardConfig } from "./shared.js";
-export interface WorkspaceStepResult {
+interface WorkspaceStepResult {
     workspaceUrlKey: string;
     defaultTeam: string | undefined;
     teams: Record<string, string>;
@@ -18,3 +18,4 @@ export interface WorkspaceStepResult {
  * the existing config exactly.
  */
 export declare function runWorkspaceStep(token: string, workspaceUrlKey: string, existing: WizardConfig): Promise<WorkspaceStepResult>;
+export {};

package/dist/commands/init/workspace.js

@@ -25,7 +25,7 @@ const TEAMS_QUERY = /* GraphQL */ `
  * the existing config exactly.
  */
 export async function runWorkspaceStep(token, workspaceUrlKey, existing) {
-    const service = new GraphQLService(token);
+    const service = new GraphQLService({ apiKey: token });
     // Fetch teams once so we can populate both the picker and the cached id map.
     const data = await service.rawRequest(TEAMS_QUERY);
     const teams = data?.teams?.nodes ?? [];

package/dist/commands/introspect.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `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 type { Command } from "commander";
+export declare function setupIntrospectCommand(program: Command): void;

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/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/relations.d.ts

@@ -6,12 +6,10 @@
  * Extracted from `commands/issues.ts` (ALL-938) so that file can
  * focus on commander wiring + handlers.
  */
-import type { IssueRelationCreateResponse, RelationIncomingNode, RelationOutgoingNode, RelationPeerNode } from "../../queries/issues-types.js";
-import type { LinearIssueRelation } from "../../types/linear.js";
+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";
-type CreatedIssueRelation = NonNullable<IssueRelationCreateResponse["issueRelationCreate"]["issueRelation"]>;
-export declare function transformIssueRelation(rel: CreatedIssueRelation): LinearIssueRelation;
 /**
  * Walk the `--related-to` / `--blocks` / `--blocked-by` /
  * `--duplicate-of` flags and create the corresponding
@@ -29,7 +27,7 @@ export interface RelatedIssueEntry {
             id: string;
             name: string;
         };
-        priority?: number;
+        priority?: LinearPriority;
         assignee?: {
             id: string;
             name: string;
@@ -42,14 +40,5 @@ export interface RelatedIssueEntry {
     };
     type: string;
 }
-/**
- * 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".
- */
-export declare function normalizeInverseType(type: string): string;
-export declare function buildRelatedIssueSummary(peer: RelationPeerNode): RelatedIssueEntry["issue"];
 export declare function buildOutgoingRelationEntries(nodes: RelationOutgoingNode[] | undefined): RelatedIssueEntry[];
 export declare function buildIncomingRelationEntries(nodes: RelationIncomingNode[] | undefined): RelatedIssueEntry[];
-export {};

package/dist/commands/issues/relations.js

@@ -8,7 +8,7 @@
  */
 import { ISSUE_RELATION_CREATE_MUTATION } from "../../queries/issues.js";
 import { splitList } from "../../utils/validators.js";
-export function transformIssueRelation(rel) {
+function transformIssueRelation(rel) {
     return {
         id: rel.id,
         type: rel.type,
@@ -66,13 +66,13 @@ export async function createRelations(sourceId, options, graphQLService, linearS
  * DEV-100 "blocks" DEV-200, and we query DEV-200, the inverse relation
  * type is "blocks" but direction is incoming → "blockedBy".
  */
-export function normalizeInverseType(type) {
+function normalizeInverseType(type) {
     if (type === "blocks") {
         return "blockedBy";
     }
     return type;
 }
-export function buildRelatedIssueSummary(peer) {
+function buildRelatedIssueSummary(peer) {
     return {
         id: peer.id,
         identifier: peer.identifier,