@enrichlayer/el-linear 1.2.0

package/dist/commands/init/defaults.js

@@ -0,0 +1,112 @@
+/**
+ * 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 { confirm, input } from "@inquirer/prompts";
+import { parseCsvList } from "./shared.js";
+const STATUS_FALLBACK = { noProject: "Triage", withAssigneeAndProject: "Todo" };
+export async function runDefaultsStep(existing) {
+    // Idempotency rule: when the user skips a sub-section, return the existing
+    // value byte-for-byte. We deliberately do NOT spread or backfill optional
+    // fields (a partial { noProject: "Backlog" } stays partial) so re-running
+    // with no input produces a byte-identical config.
+    const result = {
+        defaultLabels: existing.defaultLabels,
+        statusDefaults: existing.statusDefaults,
+        terms: existing.terms,
+    };
+    // ── Default labels ────────────────────────────────────────────────
+    const currentLabels = existing.defaultLabels ?? [];
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Current default labels: ${currentLabels.length > 0 ? currentLabels.join(", ") : "(none)"}`);
+    const editLabels = await confirm({
+        message: "Change default labels for new issues?",
+        default: false,
+    });
+    if (editLabels) {
+        const raw = await input({
+            message: "Default labels (comma-separated, blank for none):",
+            default: currentLabels.join(", "),
+        });
+        const parsed = parseCsvList(raw);
+        result.defaultLabels = parsed.length > 0 ? parsed : undefined;
+    }
+    // ── Status defaults ────────────────────────────────────────────────
+    const cur = existing.statusDefaults;
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Current status defaults: noProject=${cur?.noProject ?? STATUS_FALLBACK.noProject}, ` +
+        `withAssigneeAndProject=${cur?.withAssigneeAndProject ?? STATUS_FALLBACK.withAssigneeAndProject}`);
+    const editStatus = await confirm({
+        message: "Change status defaults?",
+        default: false,
+    });
+    if (editStatus) {
+        const noProject = await input({
+            message: "Status when no project assigned:",
+            default: cur?.noProject ?? STATUS_FALLBACK.noProject,
+        });
+        const withAP = await input({
+            message: "Status when assignee + project both set:",
+            default: cur?.withAssigneeAndProject ?? STATUS_FALLBACK.withAssigneeAndProject,
+        });
+        result.statusDefaults = {
+            noProject: noProject.trim(),
+            withAssigneeAndProject: withAP.trim(),
+        };
+    }
+    // ── Term enforcement ───────────────────────────────────────────────
+    const currentTerms = existing.terms ?? [];
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log(`  Current term-enforcement rules: ${currentTerms.length}`);
+    for (const t of currentTerms) {
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`    "${t.canonical}" rejects: ${t.reject.join(", ")}`);
+    }
+    const editTerms = await confirm({
+        message: currentTerms.length === 0
+            ? "Set up term-enforcement rules?"
+            : "Change term-enforcement rules?",
+        default: false,
+    });
+    if (editTerms) {
+        result.terms = await collectTermsInteractively(currentTerms);
+    }
+    return result;
+}
+async function collectTermsInteractively(initial) {
+    const terms = [...initial];
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("  Term enforcement catches misspellings of brand or product names in issue titles " +
+        "and descriptions. Define the canonical form and a list of rejected variants.");
+    if (terms.length > 0) {
+        const replace = await confirm({
+            message: `Replace the existing ${terms.length} rule(s) instead of appending?`,
+            default: false,
+        });
+        if (replace)
+            terms.length = 0;
+    }
+    for (;;) {
+        const canonical = (await input({
+            message: terms.length === 0
+                ? "Canonical form (e.g. 'Enrich Layer'):"
+                : "Add another? Canonical form (blank to finish):",
+            default: "",
+        })).trim();
+        if (!canonical)
+            break;
+        const rejectRaw = await input({
+            message: `Rejected variants of "${canonical}" (comma-separated, e.g. EnrichLayer, enrichlayer):`,
+        });
+        const reject = parseCsvList(rejectRaw);
+        if (reject.length === 0) {
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log("  No variants given — skipping this rule.");
+            continue;
+        }
+        terms.push({ canonical, reject });
+    }
+    return terms;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Setup wizard for first-time el-linear users.
+ *
+ * Top-level command:
+ *   el-linear init                  — full wizard (token → workspace → aliases → defaults)
+ *
+ * Sub-commands (each idempotent, runnable in isolation):
+ *   el-linear init token            — set/replace the API token
+ *   el-linear init workspace        — pick a default team
+ *   el-linear init aliases          — walk users for aliases / handles (resumable)
+ *   el-linear init aliases --import users.csv
+ *   el-linear init defaults         — default labels, status, term enforcement
+ *
+ * Skip is the default at every prompt. Only `init token` is required for a
+ * first-time setup; everything else can be skipped and revisited later.
+ */
+import type { Command } from "commander";
+export declare function setupInitCommands(program: Command): void;

package/dist/commands/init/index.js

@@ -0,0 +1,182 @@
+/**
+ * Setup wizard for first-time el-linear users.
+ *
+ * Top-level command:
+ *   el-linear init                  — full wizard (token → workspace → aliases → defaults)
+ *
+ * Sub-commands (each idempotent, runnable in isolation):
+ *   el-linear init token            — set/replace the API token
+ *   el-linear init workspace        — pick a default team
+ *   el-linear init aliases          — walk users for aliases / handles (resumable)
+ *   el-linear init aliases --import users.csv
+ *   el-linear init defaults         — default labels, status, term enforcement
+ *
+ * Skip is the default at every prompt. Only `init token` is required for a
+ * first-time setup; everything else can be skipped and revisited later.
+ */
+import { mergeAliasesIntoConfig, runAliasesImport, runAliasesStep, } from "./aliases.js";
+import { runDefaultsStep } from "./defaults.js";
+import { assignDefined, printStep, readConfig, writeConfig, } from "./shared.js";
+import { runTokenStep } from "./token.js";
+import { runWorkspaceStep } from "./workspace.js";
+/**
+ * Wrap a wizard handler so that pressing Ctrl+C at any inquirer prompt exits
+ * cleanly with code 130 (the standard SIGINT exit code) instead of dumping a
+ * stack trace. inquirer throws an `ExitPromptError` whose `name === "ExitPromptError"`;
+ * we catch by name to avoid a hard import dependency on the internal class.
+ */
+function withCleanExit(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "ExitPromptError") {
+                // biome-ignore lint/suspicious/noConsole: wizard
+                console.log("\n  Cancelled.");
+                process.exit(130);
+            }
+            throw err;
+        }
+    };
+}
+export function setupInitCommands(program) {
+    const init = program
+        .command("init")
+        .description("Interactive setup wizard for first-time el-linear users")
+        .option("--force", "ignore existing config when prompting")
+        .action(withCleanExit(async (options) => {
+        await runFullWizard({ force: options.force ?? false });
+    }));
+    init
+        .command("token")
+        .description("Set or replace the Linear API token")
+        .option("--force", "always replace existing token")
+        .action(withCleanExit(async (options) => {
+        printStep("token", "Linear API token");
+        await runTokenStep({ force: options.force ?? false });
+    }));
+    init
+        .command("workspace")
+        .description("Set the default team and refresh team UUID cache")
+        .action(withCleanExit(async () => {
+        const tokenResult = await runTokenStep();
+        const existing = await readConfig();
+        printStep("workspace", "Workspace defaults");
+        const ws = await runWorkspaceStep(tokenResult.token, tokenResult.viewer.organization.urlKey, existing);
+        const merged = assignDefined(existing, {
+            defaultTeam: ws.defaultTeam,
+            teams: { ...(existing.teams ?? {}), ...ws.teams },
+            // Don't clobber a manual urlKey override — same idempotency
+            // rule as the full wizard.
+            workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
+        });
+        await writeConfig(merged);
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  ✓ Workspace defaults saved.");
+    }));
+    init
+        .command("aliases")
+        .description("Walk Linear users to add aliases / GitHub / GitLab handles (resumable)")
+        .option("--import <csv>", "Batch import from a CSV with columns: email,aliases,github,gitlab")
+        .option("--force", "skip the 'walk now?' prompt")
+        .action(withCleanExit(async (options) => {
+        const tokenResult = await runTokenStep();
+        const existing = await readConfig();
+        printStep("aliases", "Member aliases");
+        let updates;
+        if (options.import) {
+            const result = await runAliasesImport(tokenResult.token, options.import);
+            updates = result.updates;
+            if (result.skipped.length > 0) {
+                // biome-ignore lint/suspicious/noConsole: wizard
+                console.log(`  Skipped ${result.skipped.length} unmatched email(s): ${result.skipped.join(", ")}`);
+            }
+        }
+        else {
+            updates = await runAliasesStep(tokenResult.token, existing, {
+                force: options.force ?? false,
+            });
+        }
+        if (updates.size === 0) {
+            // biome-ignore lint/suspicious/noConsole: wizard
+            console.log("  No alias changes — config unchanged.");
+            return;
+        }
+        const merged = mergeAliasesIntoConfig(existing, updates);
+        await writeConfig(merged);
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log(`  ✓ Updated aliases for ${updates.size} user(s).`);
+    }));
+    init
+        .command("defaults")
+        .description("Default labels, status defaults, term enforcement rules")
+        .action(withCleanExit(async () => {
+        const existing = await readConfig();
+        printStep("defaults", "Defaults");
+        const result = await runDefaultsStep(existing);
+        const merged = assignDefined(existing, {
+            defaultLabels: result.defaultLabels,
+            statusDefaults: result.statusDefaults,
+            terms: result.terms,
+        });
+        await writeConfig(merged);
+        // biome-ignore lint/suspicious/noConsole: wizard
+        console.log("  ✓ Defaults saved.");
+    }));
+}
+/**
+ * Full wizard: walk through all four steps in sequence. Each step writes its
+ * own slice of the config and is restartable on its own.
+ */
+async function runFullWizard(options) {
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("Welcome to el-linear. This wizard will set up your config.");
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("Skip is the default at every prompt; only the API token is required.\n");
+    const existing = await readConfig();
+    // Step 1: token (required)
+    printStep("1/4", "Linear API token");
+    const tokenResult = await runTokenStep({ force: options.force });
+    // Step 2: workspace
+    printStep("2/4", "Workspace defaults");
+    const ws = await runWorkspaceStep(tokenResult.token, tokenResult.viewer.organization.urlKey, existing);
+    // Step 3: aliases
+    printStep("3/4", "Member aliases");
+    const aliasUpdates = await runAliasesStep(tokenResult.token, existing);
+    // Step 4: defaults
+    printStep("4/4", "Defaults");
+    const defaults = await runDefaultsStep(existing);
+    // Merge everything and write atomically at the end.
+    // Idempotency rule: only write a key when the user explicitly changed it.
+    // `existing.X ?? new.X` preserves any manual override the user may have
+    // in config.json (self-hosted Linear urlKey, custom default team, etc.).
+    // `assignDefined` skips undefined values so the resulting object's own-
+    // property set matches what JSON.stringify would actually serialize.
+    let merged = assignDefined(existing, {
+        // defaults step: result is `existing.X` itself when the user skipped
+        // the edit branch, so direct assignment is safe.
+        defaultLabels: defaults.defaultLabels,
+        statusDefaults: defaults.statusDefaults,
+        terms: defaults.terms,
+        // workspace step: `ws.defaultTeam` may be the existing value (user
+        // skipped) or a new pick.
+        defaultTeam: ws.defaultTeam,
+        // Always merge the team UUID cache (additive, not destructive).
+        teams: { ...(existing.teams ?? {}), ...ws.teams },
+        // workspaceUrlKey: never clobber an existing manual override.
+        workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
+    });
+    if (aliasUpdates.size > 0) {
+        merged = mergeAliasesIntoConfig(merged, aliasUpdates);
+    }
+    await writeConfig(merged);
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("\n✓ Setup complete.");
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("  Token:  ~/.config/el-linear/token (mode 0600)");
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("  Config: ~/.config/el-linear/config.json");
+    // biome-ignore lint/suspicious/noConsole: wizard
+    console.log("\nTry: el-linear teams list");
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Shared helpers for the `el-linear init` wizard.
+ *
+ * Every step reads the on-disk config first, shows current state, and defaults
+ * to "keep as-is" so re-running the wizard with no input produces a
+ * byte-identical config.
+ */
+import type { ElLinearConfig } from "../../config/config.js";
+import { ALIASES_PROGRESS_PATH, CONFIG_PATH, TOKEN_PATH } from "../../config/paths.js";
+export { ALIASES_PROGRESS_PATH, CONFIG_PATH, TOKEN_PATH };
+/** Recursive Partial — sub-objects are also Partial. Arrays/primitives unchanged. */
+type DeepPartial<T> = T extends Array<infer _U> ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Shape the wizard reads and writes. `DeepPartial<ElLinearConfig>` because a
+ * wizard run may only set a subset of keys at any nesting level (a partial
+ * `statusDefaults: { noProject: "Backlog" }` with no `withAssigneeAndProject`
+ * is valid on disk; the runtime loader applies fallbacks at read time).
+ *
+ * The runtime config loader (`src/config/config.ts`) is the canonical source
+ * of truth for the on-disk shape; we narrow to a partial view here so the
+ * wizard can compose updates without owning the whole tree.
+ *
+ * The on-disk `config.json` may also contain unknown keys (custom extensions
+ * the wizard doesn't recognise); these are preserved verbatim through the
+ * `JSON.parse → sortKeys → JSON.stringify` round-trip in `readConfig` /
+ * `writeConfig` even though the type doesn't surface them.
+ */
+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 readToken(): Promise<string | null>;
+/**
+ * Write the token to disk with mode 0600.
+ *
+ * IMPORTANT: We use atomicWrite (write-tmp + rename), which guarantees the
+ * destination file's mode comes from the freshly-created tmp file — not from
+ * any pre-existing token file. This closes a real security hole: `fs.writeFile`
+ * with `{mode}` only honors the mode when *creating* a new file, so a legacy
+ * token left at 0644 (umask, scp from another machine, migrated from
+ * `~/.linear_api_token`) would have stayed world-readable forever otherwise.
+ */
+export declare function writeToken(token: string): Promise<void>;
+/**
+ * Build a new object containing only the keys whose values are not `undefined`.
+ *
+ * Use this anywhere you'd otherwise spread `{ ...existing, key: maybeUndefined }`
+ * — `JSON.stringify` skips `undefined` values, so the resulting JSON is fine,
+ * but the in-memory merged object has an own `key` property that subsequent
+ * reads diverge on. That asymmetry is what made `defaultTeam: undefined` round-
+ * trip inconsistently across runs.
+ */
+export declare function assignDefined<T extends Record<string, unknown>>(target: T, updates: {
+    [K in keyof T]?: T[K] | undefined;
+}): T;
+/**
+ * Progress checkpoint for the resumable user-walk.
+ *
+ * Stores the UUID of the last user the operator completed (rather than the
+ * positional index). On resume we look up that UUID's index in the freshly-
+ * fetched user list — so adding or removing users in the workspace between
+ * runs no longer silently misaligns the resume point onto the wrong person.
+ *
+ * `totalUsers` is kept around as a soft sanity check; if both UUID matching
+ * and total-count match fail, we fall back to starting over.
+ */
+export interface AliasesProgress {
+    /** UUID of the last user the operator finished. */
+    lastCompletedUserId: string;
+    /** Total user count when the run started — used as a soft drift signal. */
+    totalUsers: number;
+    /** When the progress was saved. */
+    savedAt: string;
+}
+export declare function readAliasesProgress(): Promise<AliasesProgress | null>;
+export declare function writeAliasesProgress(p: AliasesProgress): Promise<void>;
+export declare function clearAliasesProgress(): Promise<void>;
+/**
+ * Print a step header in the wizard. Step strings like "1/4" or "2/4 (skipped)".
+ */
+export declare function printStep(label: string, title: string): void;
+/**
+ * Parse a comma-separated user input ("alice, ali, alex") into trimmed,
+ * non-empty values. Used by the alias and label prompts.
+ */
+export declare function parseCsvList(value: string): string[];

package/dist/commands/init/shared.js

@@ -0,0 +1,164 @@
+/**
+ * Shared helpers for the `el-linear init` wizard.
+ *
+ * Every step reads the on-disk config first, shows current state, and defaults
+ * to "keep as-is" so re-running the wizard with no input produces a
+ * byte-identical config.
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import { ALIASES_PROGRESS_PATH, CONFIG_DIR, CONFIG_PATH, 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 };
+/**
+ * Atomic file write: write to a sibling tmp file then rename. Survives SIGINT,
+ * OOM, and laptop suspend mid-write — the original file is either untouched
+ * (rename never happened) or fully replaced (rename succeeded). On POSIX
+ * same-filesystem, rename is atomic.
+ *
+ * Tmp suffix uses crypto random bytes so concurrent writers don't collide.
+ *
+ * @param targetPath  destination path
+ * @param data        bytes/string to write
+ * @param mode        unix mode for the new file (default 0o644)
+ */
+async function atomicWrite(targetPath, data, mode = 0o644) {
+    const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+    try {
+        await fs.writeFile(tmpPath, data, { encoding: "utf8", mode });
+        // Defensively chmod — fs.writeFile only honors `mode` when the file is
+        // newly created. Tmp is always new, but be explicit.
+        await fs.chmod(tmpPath, mode);
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        // Best-effort cleanup of orphaned tmp.
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+export async function ensureConfigDir() {
+    await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+export async function readConfig() {
+    try {
+        const raw = await fs.readFile(CONFIG_PATH, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return {};
+        }
+        throw err;
+    }
+}
+export async function writeConfig(config) {
+    await ensureConfigDir();
+    // Stable key order so byte-identical config produces byte-identical output.
+    const sorted = sortKeys(config);
+    await atomicWrite(CONFIG_PATH, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
+}
+export async function readToken() {
+    try {
+        const raw = await fs.readFile(TOKEN_PATH, "utf8");
+        return raw.trim() || null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Write the token to disk with mode 0600.
+ *
+ * IMPORTANT: We use atomicWrite (write-tmp + rename), which guarantees the
+ * destination file's mode comes from the freshly-created tmp file — not from
+ * any pre-existing token file. This closes a real security hole: `fs.writeFile`
+ * with `{mode}` only honors the mode when *creating* a new file, so a legacy
+ * token left at 0644 (umask, scp from another machine, migrated from
+ * `~/.linear_api_token`) would have stayed world-readable forever otherwise.
+ */
+export async function writeToken(token) {
+    await ensureConfigDir();
+    await atomicWrite(TOKEN_PATH, `${token.trim()}\n`, 0o600);
+}
+/**
+ * Build a new object containing only the keys whose values are not `undefined`.
+ *
+ * Use this anywhere you'd otherwise spread `{ ...existing, key: maybeUndefined }`
+ * — `JSON.stringify` skips `undefined` values, so the resulting JSON is fine,
+ * but the in-memory merged object has an own `key` property that subsequent
+ * reads diverge on. That asymmetry is what made `defaultTeam: undefined` round-
+ * trip inconsistently across runs.
+ */
+export function assignDefined(target, updates) {
+    const next = { ...target };
+    for (const key of Object.keys(updates)) {
+        const v = updates[key];
+        if (v !== undefined)
+            next[key] = v;
+    }
+    return next;
+}
+/**
+ * Recursively sort object keys for stable JSON output. Arrays are left in
+ * insertion order; primitive values are returned as-is.
+ */
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (value && typeof value === "object" && value.constructor === Object) {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+export async function readAliasesProgress() {
+    try {
+        const raw = await fs.readFile(ALIASES_PROGRESS_PATH, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeAliasesProgress(p) {
+    await ensureConfigDir();
+    await atomicWrite(ALIASES_PROGRESS_PATH, JSON.stringify(p, null, 2), 0o644);
+}
+export async function clearAliasesProgress() {
+    try {
+        await fs.unlink(ALIASES_PROGRESS_PATH);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+/**
+ * Print a step header in the wizard. Step strings like "1/4" or "2/4 (skipped)".
+ */
+export function printStep(label, title) {
+    // biome-ignore lint/suspicious/noConsole: wizard output is meant for stdout
+    console.log(`\n[${label}] ${title}`);
+}
+/**
+ * Parse a comma-separated user input ("alice, ali, alex") into trimmed,
+ * non-empty values. Used by the alias and label prompts.
+ */
+export function parseCsvList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+interface ViewerResponse {
+    viewer: {
+        id: string;
+        name: string;
+        email: string;
+        displayName: string;
+        organization: {
+            urlKey: string;
+            name: string;
+        };
+    };
+}
+export interface TokenStepResult {
+    token: string;
+    viewer: ViewerResponse["viewer"];
+}
+/**
+ * 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 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
+ * always run through sanitizeForLog so a leaked token in an upstream error
+ * is redacted before it hits stdout.
+ */
+export declare function validateToken(token: string): Promise<ViewerResponse["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 declare function runTokenStep(options?: {
+    /** Skip the "replace existing?" prompt; always replace if existing is present. */
+    force?: boolean;
+}): Promise<TokenStepResult>;
+export {};