@enrichlayer/el-linear 1.2.0 → 1.5.0

package/dist/commands/init/oauth.js

@@ -0,0 +1,308 @@
+/**
+ * Wizard step for OAuth 2.0 (PKCE flow) authorization.
+ *
+ * Flow:
+ *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
+ *      app registration page. (Until we ship a shared OAuth client_id,
+ *      every user registers their own app.)
+ *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   3. Generate PKCE verifier + state, build the authorize URL.
+ *   4. Try to open the system browser; fall back to printing the URL.
+ *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
+ *      receive the redirect.
+ *   6. Exchange code for tokens.
+ *   7. Validate by calling `viewer { ... }` with the new bearer token.
+ *   8. Persist `oauth.json` to the active profile.
+ *
+ * Idempotent: if a fresh `oauth.json` already exists, offer keep / re-auth /
+ * revoke before doing anything else.
+ */
+import { spawn } from "node:child_process";
+import { checkbox, input, password, select } from "@inquirer/prompts";
+import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-callback.js";
+import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateScopes, } from "../../auth/oauth-client.js";
+import { promptForPastedCode } from "../../auth/oauth-headless.js";
+import { clearOAuthState, OAUTH_STATE_VERSION, readOAuthState, writeOAuthState, } from "../../auth/oauth-storage.js";
+import { exchangeCodeForTokens, revokeToken, } from "../../auth/oauth-token.js";
+import { GraphQLService } from "../../utils/graphql-service.js";
+import { sanitizeForLog } from "./token.js";
+const DEFAULT_PORT = 8765;
+const REGISTRATION_URL = "https://linear.app/settings/api/applications/new";
+const VIEWER_QUERY = /* GraphQL */ `
+  query {
+    viewer {
+      id
+      name
+      email
+      displayName
+      organization {
+        urlKey
+        name
+      }
+    }
+  }
+`;
+const TS = (msg) => `  ${msg}`;
+function logLine(msg) {
+    console.log(msg);
+}
+/**
+ * Open `url` in the system browser. Forks per-platform:
+ *   - darwin → `open <url>`
+ *   - win32  → `start "" "<url>"` (cmd builtin)
+ *   - other  → `xdg-open <url>` (Linux / BSD with desktop env)
+ *
+ * Returns once the spawn call succeeds — does NOT wait for the browser to
+ * actually load. Throws on spawn failure (e.g. xdg-open not installed in
+ * a barebones container).
+ */
+export async function openSystemBrowser(url) {
+    return new Promise((resolve, reject) => {
+        let cmd;
+        let args;
+        if (process.platform === "darwin") {
+            cmd = "open";
+            args = [url];
+        }
+        else if (process.platform === "win32") {
+            cmd = "cmd";
+            // `start "" "<url>"` — empty title means "use the URL".
+            args = ["/c", "start", "", url];
+        }
+        else {
+            cmd = "xdg-open";
+            args = [url];
+        }
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.once("error", reject);
+        // Don't keep the parent alive on the child — we don't track its exit.
+        child.unref();
+        // Linux's xdg-open immediately exits with the result code. Wait
+        // until the next tick so a synchronous `error` event has a chance
+        // to fire before we resolve.
+        setImmediate(() => resolve());
+    });
+}
+/**
+ * Prompt for what to do with existing OAuth state. Returns a discriminated
+ * tagged union so the caller can branch cleanly.
+ */
+async function handleExistingState(existing, options) {
+    if (options.force)
+        return { kind: "reauth" };
+    logLine(TS(`Existing OAuth tokens found for client ${existing.clientId} (${existing.scopes.join(",")}).`));
+    const choice = await select({
+        message: "What would you like to do?",
+        choices: [
+            { name: "Keep existing tokens (no changes)", value: "keep" },
+            { name: "Re-authorize (replace tokens)", value: "reauth" },
+            { name: "Revoke and remove", value: "revoke" },
+        ],
+        default: "keep",
+    });
+    if (choice === "keep")
+        return { kind: "keep", state: existing };
+    if (choice === "revoke") {
+        const result = await revokeToken({ accessToken: existing.accessToken }, options.fetchImpl);
+        await clearOAuthState();
+        logLine(TS(result.ok
+            ? "✓ Token revoked and oauth.json removed."
+            : `Revoke endpoint returned ${result.status} (${sanitizeForLog(result.message ?? "")}). Local oauth.json removed anyway.`));
+        return { kind: "revoked" };
+    }
+    return { kind: "reauth" };
+}
+/** Extract the port from a stored `http://localhost:NNN/...` redirect URI, if any. */
+function extractPortFromRedirect(state) {
+    if (!state)
+        return null;
+    const match = state.registeredRedirectUri.match(/:(\d+)\//);
+    if (!match)
+        return null;
+    const n = Number.parseInt(match[1], 10);
+    return Number.isInteger(n) ? n : null;
+}
+/** Walk the user through their OAuth-app registration values. */
+async function promptRegistration(defaults) {
+    logLine("");
+    logLine(TS(`Register a Linear OAuth app: ${REGISTRATION_URL}`));
+    logLine(TS(`Set the redirect URL to: http://localhost:${defaults.port ?? DEFAULT_PORT}${DEFAULT_CALLBACK_PATH}`));
+    logLine(TS("Then paste the client_id (and client_secret, if your app is configured as confidential)."));
+    logLine("");
+    const port = Number.parseInt(await input({
+        message: "Localhost callback port:",
+        default: String(defaults.port ?? DEFAULT_PORT),
+        validate: (value) => {
+            const n = Number.parseInt(value, 10);
+            if (!Number.isInteger(n) || n < 1024 || n > 65535) {
+                return "Port must be an integer between 1024 and 65535";
+            }
+            return true;
+        },
+    }), 10);
+    const clientId = (await input({
+        message: "Linear OAuth client_id:",
+        validate: (v) => v.trim().length > 0 || "client_id cannot be empty",
+    })).trim();
+    const clientSecret = (await password({
+        message: "Linear OAuth client_secret (optional, hidden — press enter to skip):",
+        mask: "*",
+        validate: () => true,
+    })).trim();
+    const scopes = (await checkbox({
+        message: "Scopes (space to toggle, enter to confirm):",
+        choices: ALL_SCOPES.map((s) => ({
+            name: `${s} — ${SCOPE_DESCRIPTIONS[s]}`,
+            value: s,
+            checked: DEFAULT_SCOPES.includes(s),
+        })),
+        validate: (selections) => selections.length > 0 || "Pick at least one scope",
+    }));
+    return {
+        clientId,
+        clientSecret: clientSecret || undefined,
+        port,
+        scopes: validateScopes(scopes),
+    };
+}
+/**
+ * Default viewer-validation routine. Calls `viewer { ... }` with the new
+ * bearer token to confirm Linear accepted it. Reused for both the wizard
+ * step's success path and the test seam.
+ */
+async function defaultValidateViewer(oauthToken) {
+    const service = new GraphQLService({ oauthToken });
+    let data;
+    try {
+        data = await service.rawRequest(VIEWER_QUERY);
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not validate the OAuth access token via viewer: ${sanitizeForLog(raw)}`);
+    }
+    const viewer = data?.viewer;
+    if (!viewer || typeof viewer !== "object" || typeof viewer.id !== "string") {
+        throw new Error("OAuth token validated but the response was missing a viewer with id. Try a different scope set.");
+    }
+    return viewer;
+}
+/**
+ * Run the OAuth step. Returns the final stored state + viewer info.
+ *
+ * If the user opts to keep their existing tokens, returns the existing
+ * state unchanged (no network calls).
+ */
+export async function runOAuthStep(options = {}) {
+    const validateViewer = options.validateViewer ?? defaultValidateViewer;
+    const existing = await readOAuthState();
+    if (existing && !options.force) {
+        const handled = await handleExistingState(existing, options);
+        if (handled.kind === "keep") {
+            // Validate the existing token actually works; if it's already
+            // expired and unrefreshable, the next `el-linear` invocation
+            // would fall over — fail loudly here.
+            try {
+                const viewer = await validateViewer(handled.state.accessToken);
+                logLine(TS(`✓ Existing OAuth tokens verified — authenticated as ${viewer.displayName} <${viewer.email}>.`));
+                return { state: handled.state, viewer };
+            }
+            catch (err) {
+                const raw = err instanceof Error ? err.message : String(err);
+                logLine(TS(`Existing token failed validation (${sanitizeForLog(raw)}). Continuing with re-authorization…`));
+            }
+        }
+        // Both `reauth` and `revoked` fall through to the re-auth flow.
+    }
+    const reg = await promptRegistration({
+        port: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+    });
+    const redirectUri = `http://localhost:${reg.port}${DEFAULT_CALLBACK_PATH}`;
+    const pkce = generatePkce();
+    const state = generateState();
+    const authorizeUrl = buildAuthorizeUrl({
+        clientId: reg.clientId,
+        redirectUri,
+        scopes: reg.scopes,
+        state,
+        codeChallenge: pkce.challenge,
+    });
+    logLine("");
+    logLine(TS("Opening your browser to authorize…"));
+    logLine(TS(`If it doesn't open, visit: ${authorizeUrl}`));
+    const useBrowser = !options.noBrowser;
+    let browserOpened = false;
+    if (useBrowser) {
+        try {
+            await (options.openBrowser ?? openSystemBrowser)(authorizeUrl);
+            browserOpened = true;
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            logLine(TS(`Could not open a browser automatically (${raw}). Falling back to manual.`));
+        }
+    }
+    let callback;
+    if (browserOpened) {
+        try {
+            callback = await (options.runLocalhostCallbackImpl ?? runLocalhostCallback)({
+                port: reg.port,
+                expectedState: state,
+            });
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            logLine(TS(`Localhost listener failed (${sanitizeForLog(raw)}). Falling back to manual paste.`));
+            callback = await promptForPastedCode({ expectedState: state });
+        }
+    }
+    else {
+        callback = await promptForPastedCode({ expectedState: state });
+    }
+    logLine(TS("Exchanging authorization code for tokens…"));
+    const exchanged = await exchangeCodeForTokens({
+        clientId: reg.clientId,
+        clientSecret: reg.clientSecret,
+        code: callback.code,
+        redirectUri,
+        codeVerifier: pkce.verifier,
+    }, options.fetchImpl);
+    const newState = {
+        v: OAUTH_STATE_VERSION,
+        clientId: reg.clientId,
+        clientSecret: reg.clientSecret,
+        registeredRedirectUri: redirectUri,
+        accessToken: exchanged.accessToken,
+        refreshToken: exchanged.refreshToken,
+        tokenType: exchanged.tokenType,
+        scopes: exchanged.scopes.length > 0 ? exchanged.scopes : reg.scopes,
+        expiresAt: exchanged.expiresAt,
+        obtainedAt: Date.now(),
+    };
+    logLine(TS("Validating against viewer…"));
+    const viewer = await validateViewer(newState.accessToken);
+    await writeOAuthState(newState);
+    logLine(TS(`✓ Authorized as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`));
+    return { state: newState, viewer };
+}
+/**
+ * `init oauth --revoke`: revoke the active profile's tokens and remove
+ * `oauth.json`. Best-effort on the network call.
+ */
+export async function runOAuthRevoke(options = {}) {
+    const existing = await readOAuthState();
+    if (!existing) {
+        return { revoked: false, message: "No OAuth state to revoke." };
+    }
+    const result = await revokeToken({ accessToken: existing.accessToken }, options.fetchImpl);
+    await clearOAuthState();
+    if (result.ok) {
+        return {
+            revoked: true,
+            message: "✓ Token revoked and oauth.json removed.",
+        };
+    }
+    return {
+        revoked: false,
+        message: `Revoke endpoint returned ${result.status} (${sanitizeForLog(result.message ?? "")}). Local oauth.json removed anyway.`,
+    };
+}

package/dist/commands/init/shared.js

@@ -7,9 +7,27 @@
  */
 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";
+import path from "node:path";
+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 };
+/**
+ * Profile-aware paths for the active wizard run. The wizard always
+ * writes to (and reads from) the active profile — switched via
+ * `EL_LINEAR_PROFILE`, `--profile`, or the on-disk `active-profile`
+ * marker. When no profile is selected, paths fall through to the
+ * legacy single-file layout (CONFIG_PATH / TOKEN_PATH).
+ */
+function activePaths() {
+    const active = resolveActiveProfile();
+    return {
+        // Profile dir is always the directory of configPath (whether
+        // that's the legacy CONFIG_DIR or a per-profile subdirectory).
+        configDir: path.dirname(active.configPath),
+        configPath: active.configPath,
+        tokenPath: active.tokenPath,
+    };
+}
 /**
  * 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
@@ -38,11 +56,18 @@ async function atomicWrite(targetPath, data, mode = 0o644) {
     }
 }
 export async function ensureConfigDir() {
+    // Always make sure the legacy CONFIG_DIR exists (it's where the
+    // `active-profile` marker + `profiles/` tree live), then make the
+    // active profile's directory if it differs.
     await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const dir = activePaths().configDir;
+    if (dir !== CONFIG_DIR) {
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    }
 }
 export async function readConfig() {
     try {
-        const raw = await fs.readFile(CONFIG_PATH, "utf8");
+        const raw = await fs.readFile(activePaths().configPath, "utf8");
         return JSON.parse(raw);
     }
     catch (err) {
@@ -56,11 +81,11 @@ 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);
+    await atomicWrite(activePaths().configPath, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
 }
 export async function readToken() {
     try {
-        const raw = await fs.readFile(TOKEN_PATH, "utf8");
+        const raw = await fs.readFile(activePaths().tokenPath, "utf8");
         return raw.trim() || null;
     }
     catch (err) {
@@ -82,7 +107,7 @@ export async function readToken() {
  */
 export async function writeToken(token) {
     await ensureConfigDir();
-    await atomicWrite(TOKEN_PATH, `${token.trim()}\n`, 0o600);
+    await atomicWrite(activePaths().tokenPath, `${token.trim()}\n`, 0o600);
 }
 /**
  * Build a new object containing only the keys whose values are not `undefined`.

package/dist/commands/profile/migrate-legacy.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `el-linear profile migrate-legacy` — one-shot migration from the legacy
+ * single-file config layout (`~/.config/el-linear/{token,config.json}`) to
+ * the named-profiles layout introduced in 1.4 (`~/.config/el-linear/
+ * profiles/<name>/{token,config.json}`).
+ *
+ * Why this command exists:
+ *
+ *   When a user upgraded el-linear to >=1.4, their existing single-file
+ *   `config.json` was preserved verbatim, but the legacy `token` slot was
+ *   sometimes cleared (depending on how the upgrade was performed) and
+ *   1.4 expects per-profile tokens. Result: every command failed with
+ *   "Authentication required" while the rich legacy config (member
+ *   aliases, brand rules, default labels) sat right there on disk with
+ *   no documented migration path.
+ *
+ * Design constraints:
+ *
+ * - **Each step is independently idempotent.** Re-running the command
+ *   after a successful migration is a no-op — config + token files match,
+ *   active-profile already points at the right name. Re-running after a
+ *   partial failure picks up where it left off without `--force`.
+ *
+ * - **Validate before writing.** A token that doesn't pass `viewer { ... }`
+ *   never lands on disk. The validate-then-write order means an interrupted
+ *   migration can't leave a dud token in a freshly-created profile dir.
+ *
+ * - **Legacy preservation.** We never delete the legacy `config.json` or
+ *   `token` — the user gets a rollback path. A one-line stdout hint says
+ *   so explicitly.
+ *
+ * - **`--force` is opt-in destruction.** When the destination profile
+ *   already has a config.json or token that *differs* from the source,
+ *   the command refuses by default with a clear diff hint. `--force`
+ *   overwrites; `--yes` skips the interactive confirm. Both are
+ *   required-together for unattended (CI / scripted) overwrites.
+ */
+import { confirm, input, password } from "@inquirer/prompts";
+import type { Command } from "commander";
+import { CONFIG_PATH, PROFILES_DIR, TOKEN_PATH } from "../../config/paths.js";
+export interface MigrateLegacyOptions {
+    /** Target profile name. Defaults to "default" when omitted. */
+    name?: string;
+    /** Path to a file containing the API token (whitespace trimmed). */
+    tokenFrom?: string;
+    /** Overwrite existing profile config.json/token even if they differ. */
+    force?: boolean;
+    /** Skip interactive confirmation when --force is needed. */
+    yes?: boolean;
+    /** Skip the interactive name prompt — use whatever `name` resolved to. */
+    skipPrompt?: boolean;
+}
+export interface MigrateLegacyDeps {
+    /**
+     * Hook around the `viewer` validation call so tests can short-circuit
+     * the GraphQL roundtrip. Production wiring uses the real
+     * `validateToken` from `init/token.ts`.
+     */
+    validateToken?: (token: string) => Promise<{
+        id: string;
+        organization: {
+            urlKey: string;
+            name: string;
+        };
+        displayName: string;
+        email: string;
+    }>;
+    /** stdout writer (for the success line + "kept for rollback" hint). */
+    stdout?: {
+        write: (chunk: string) => void;
+    };
+    /**
+     * Inquirer-based prompts. Tests inject deterministic responses so we
+     * don't need a TTY.
+     */
+    prompts?: {
+        input: typeof input;
+        password: typeof password;
+        confirm: typeof confirm;
+    };
+}
+/** Register `el-linear profile migrate-legacy` under the parent `profile` command. */
+export declare function registerMigrateLegacy(profile: Command): void;
+/**
+ * Top-level orchestrator. Each helper below is independently idempotent;
+ * this function just sequences them and prints the final ✓ banner.
+ *
+ * Exit semantics:
+ *
+ *   - Missing legacy config → `process.exit(1)` (user error, nothing to do).
+ *   - Refused overwrite (no --force) → throws — handled by handleAsyncCommand
+ *     elsewhere in the CLI and surfaces as a structured JSON error on stdout.
+ *   - Token validation failure → throws (no on-disk change has happened yet).
+ */
+export declare function runMigrateLegacy(options: MigrateLegacyOptions, deps?: MigrateLegacyDeps): Promise<void>;
+export { CONFIG_PATH, PROFILES_DIR, TOKEN_PATH };