@enrichlayer/el-linear 1.2.0

package/dist/commands/init/token.js

@@ -0,0 +1,141 @@
+/**
+ * Step 1 of the wizard: Linear API token.
+ *
+ * The only required step. Validates the token by calling `viewer { ... }`
+ * before saving. Token is stored at ~/.config/el-linear/token (mode 0600),
+ * never embedded in config.json.
+ */
+import { confirm, password } from "@inquirer/prompts";
+import { GraphQLService } from "../../utils/graphql-service.js";
+import { readToken, writeToken } from "./shared.js";
+const TOKEN_GENERATION_URL = "https://linear.app/settings/account/security";
+const VIEWER_QUERY = /* GraphQL */ `
+  query {
+    viewer {
+      id
+      name
+      email
+      displayName
+      organization {
+        urlKey
+        name
+      }
+    }
+  }
+`;
+/**
+ * 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.
+ */
+export function sanitizeForLog(text) {
+    return text.replace(/lin_api_[A-Za-z0-9_-]{16,}/g, "lin_api_***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
+ * response, so we require a UUID-shaped id and a basic urlKey.
+ */
+function viewerIsValid(viewer) {
+    if (!viewer || typeof viewer !== "object")
+        return false;
+    const v = viewer;
+    const id = typeof v.id === "string" ? v.id.trim() : "";
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))
+        return false;
+    const org = v.organization;
+    if (!org || typeof org !== "object")
+        return false;
+    const urlKey = typeof org.urlKey === "string" ? org.urlKey.trim() : "";
+    if (!/^[a-z0-9-]+$/i.test(urlKey))
+        return false;
+    return true;
+}
+/**
+ * Validate a Linear API token by fetching the viewer. Throws with a
+ * sanitized user-readable message on auth failure — the error string is
+ * always run through sanitizeForLog so a leaked token in an upstream error
+ * is redacted before it hits stdout.
+ */
+export async function validateToken(token) {
+    const service = new GraphQLService(token);
+    let data;
+    try {
+        data = await service.rawRequest(VIEWER_QUERY);
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        const message = sanitizeForLog(raw);
+        if (/AuthenticationFailed|Unauthorized|invalid|expired/i.test(message)) {
+            throw new Error(`Token rejected by Linear: ${message}`);
+        }
+        throw new Error(`Could not validate token: ${message}`);
+    }
+    if (!viewerIsValid(data?.viewer)) {
+        throw new Error("Token validated but the response is missing a viewer with a valid id and organization. " +
+            "Try a different token.");
+    }
+    return data.viewer;
+}
+/**
+ * Run the interactive token step. Returns the validated token + viewer info.
+ *
+ * On re-run with an existing valid token, the prompt defaults to "keep" — so
+ * pressing enter is a no-op.
+ */
+export async function runTokenStep(options = {}) {
+    const existing = await readToken();
+    if (existing && !options.force) {
+        try {
+            const viewer = await validateToken(existing);
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log(`  Existing token works — authenticated as ${viewer.displayName} <${viewer.email}>.`);
+            const replace = await confirm({
+                message: "Replace this token?",
+                default: false,
+            });
+            if (!replace) {
+                return { token: existing, viewer };
+            }
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            const message = sanitizeForLog(raw);
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log(`  Existing token failed validation (${message}). You'll need to provide a new one.`);
+        }
+    }
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Generate a personal API token: ${TOKEN_GENERATION_URL}`);
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("  The token stays on your machine. el-linear only sends it to Linear's API. " +
+        "It's stored at ~/.config/el-linear/token (mode 0600).");
+    // Up to three attempts before giving up.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const token = (await password({
+            message: attempt === 0
+                ? "Linear API token (input hidden):"
+                : "Try again (input hidden):",
+            mask: "*",
+            validate: (input) => input.trim().length > 0 || "Token cannot be empty",
+        })).trim();
+        try {
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log("  Validating…");
+            const viewer = await validateToken(token);
+            await writeToken(token);
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log(`  ✓ Authenticated as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`);
+            return { token, viewer };
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log(`  ✗ ${sanitizeForLog(raw)}`);
+        }
+    }
+    throw new Error("Could not validate a Linear API token after 3 attempts. Aborting.");
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Step 2 of the wizard: workspace defaults.
+ *
+ * Auto-fetches the Linear workspace urlKey (no prompt) since it's deterministic.
+ * Lets the user pick a default team, optional. Skip-by-default.
+ */
+import type { WizardConfig } from "./shared.js";
+export interface WorkspaceStepResult {
+    workspaceUrlKey: string;
+    defaultTeam: string | undefined;
+    teams: Record<string, string>;
+}
+/**
+ * Run the workspace step. Reads existing config to default the team picker
+ * to the current default. Returns values to merge into the on-disk config.
+ *
+ * No-op safe: if the user keeps everything as-is, returns values that match
+ * the existing config exactly.
+ */
+export declare function runWorkspaceStep(token: string, workspaceUrlKey: string, existing: WizardConfig): Promise<WorkspaceStepResult>;

package/dist/commands/init/workspace.js

@@ -0,0 +1,80 @@
+/**
+ * Step 2 of the wizard: workspace defaults.
+ *
+ * Auto-fetches the Linear workspace urlKey (no prompt) since it's deterministic.
+ * Lets the user pick a default team, optional. Skip-by-default.
+ */
+import { confirm, select } from "@inquirer/prompts";
+import { GraphQLService } from "../../utils/graphql-service.js";
+const TEAMS_QUERY = /* GraphQL */ `
+  query InitTeams {
+    teams(first: 100) {
+      nodes {
+        id
+        key
+        name
+      }
+    }
+  }
+`;
+/**
+ * Run the workspace step. Reads existing config to default the team picker
+ * to the current default. Returns values to merge into the on-disk config.
+ *
+ * No-op safe: if the user keeps everything as-is, returns values that match
+ * the existing config exactly.
+ */
+export async function runWorkspaceStep(token, workspaceUrlKey, existing) {
+    const service = new GraphQLService(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 ?? [];
+    const teamMap = {};
+    for (const t of teams) {
+        teamMap[t.key] = t.id;
+    }
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Workspace: ${workspaceUrlKey} (${teams.length} teams)`);
+    const currentDefault = existing.defaultTeam || "";
+    // `change` reflects what the user agreed to: `true` means "open the picker
+    // and change the default team", `false` means "leave the existing config
+    // alone". Default false makes pressing enter a no-op (keep-as-is).
+    const change = await confirm({
+        message: currentDefault
+            ? `Current default team: ${currentDefault}. Change it?`
+            : "Set a default team for new issues?",
+        default: false,
+    });
+    if (!change) {
+        return {
+            workspaceUrlKey,
+            defaultTeam: currentDefault || undefined,
+            teams: teamMap,
+        };
+    }
+    if (teams.length === 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  No teams visible to this token. Skipping default-team picker.");
+        return {
+            workspaceUrlKey,
+            defaultTeam: currentDefault || undefined,
+            teams: teamMap,
+        };
+    }
+    const choice = await select({
+        message: "Default team:",
+        choices: [
+            ...teams.map((t) => ({
+                name: `${t.key}${t.name && t.name !== t.key ? ` — ${t.name}` : ""}`,
+                value: t.key,
+            })),
+            { name: "(no default — pick per-issue)", value: "__skip" },
+        ],
+        default: currentDefault || teams[0]?.key,
+    });
+    return {
+        workspaceUrlKey,
+        defaultTeam: choice === "__skip" ? undefined : choice,
+        teams: teamMap,
+    };
+}

package/dist/commands/issue-id.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `el-linear issue-id` — extract the Linear issue ID from the current
+ * git branch (or any branch passed as an argument).
+ *
+ * Replaces the regex that was duplicated across 4 skills: commit-guard,
+ * glab-commit-push-mr, stray-file-triage, git-branch-from-linear. Each
+ * had its own copy of `feature/(DEV|ALL|...)-\d+-...` parsing.
+ *
+ * Output (when issueId found):
+ *   { branch, issueId: "DEV-3900", team: "DEV", number: 3900, slug: "..." }
+ * Output (when no match):
+ *   { branch, issueId: null, team: null, number: null, slug: null }
+ *
+ * `--fetch` (optional): also fetches the issue from Linear and includes
+ * { title, description, state, assignee }. Skip when you only need the
+ * parsed ID — saves an API round-trip.
+ */
+import type { Command } from "commander";
+interface ParsedBranch {
+    branch: string;
+    issueId: string | null;
+    number: number | null;
+    slug: string | null;
+    team: string | null;
+}
+export declare function parseBranchName(branch: string): ParsedBranch;
+export declare function setupIssueIdCommand(program: Command): void;
+export {};

package/dist/commands/issue-id.js

@@ -0,0 +1,81 @@
+/**
+ * `el-linear issue-id` — extract the Linear issue ID from the current
+ * git branch (or any branch passed as an argument).
+ *
+ * Replaces the regex that was duplicated across 4 skills: commit-guard,
+ * glab-commit-push-mr, stray-file-triage, git-branch-from-linear. Each
+ * had its own copy of `feature/(DEV|ALL|...)-\d+-...` parsing.
+ *
+ * Output (when issueId found):
+ *   { branch, issueId: "DEV-3900", team: "DEV", number: 3900, slug: "..." }
+ * Output (when no match):
+ *   { branch, issueId: null, team: null, number: null, slug: null }
+ *
+ * `--fetch` (optional): also fetches the issue from Linear and includes
+ * { title, description, state, assignee }. Skip when you only need the
+ * parsed ID — saves an API round-trip.
+ */
+import { spawnSync } from "node:child_process";
+import { createGraphQLService } from "../utils/graphql-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+// Branch naming conventions — kept in sync with branch-name validators
+// elsewhere in the workspace. Any addition here is the single point of
+// truth that all skills rely on.
+const BRANCH_RE = /^(?:feature|fix|chore|refactor|dev)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
+export function parseBranchName(branch) {
+    const m = branch.match(BRANCH_RE);
+    if (!m) {
+        return { branch, issueId: null, team: null, number: null, slug: null };
+    }
+    const team = m[1].toUpperCase();
+    const number = Number.parseInt(m[2], 10);
+    return {
+        branch,
+        issueId: `${team}-${number}`,
+        team,
+        number,
+        slug: m[3] ?? null,
+    };
+}
+function getCurrentBranch() {
+    const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        encoding: "utf8",
+    });
+    if (result.status !== 0) {
+        throw new Error(`git rev-parse failed: ${result.stderr.trim() || "non-zero exit"}`);
+    }
+    return result.stdout.trim();
+}
+const ISSUE_QUERY = /* GraphQL */ `
+  query IssueByIdentifier($id: String!) {
+    issue(id: $id) {
+      id
+      identifier
+      title
+      description
+      branchName
+      state { name type }
+      assignee { id name email }
+    }
+  }
+`;
+export function setupIssueIdCommand(program) {
+    program
+        .command("issue-id [branch]")
+        .description("Extract the Linear issue ID from a git branch name (defaults to current branch). Use --fetch to also pull the issue from Linear.")
+        .option("--fetch", "also fetch issue title/description/state from Linear")
+        .action(handleAsyncCommand(async (branchArg, options, command) => {
+        const branch = branchArg ?? getCurrentBranch();
+        const parsed = parseBranchName(branch);
+        if (!(options.fetch && parsed.issueId)) {
+            outputSuccess(parsed);
+            return;
+        }
+        const rootOpts = command.parent?.opts() ?? {};
+        const service = createGraphQLService({ apiToken: rootOpts.apiToken });
+        const result = (await service.rawRequest(ISSUE_QUERY, {
+            id: parsed.issueId,
+        }));
+        outputSuccess({ ...parsed, issue: result.issue ?? null });
+    }));
+}

package/dist/commands/issues.d.ts

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