@enrichlayer/el-linear 1.4.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/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 };

package/dist/commands/profile/migrate-legacy.js

@@ -0,0 +1,272 @@
+/**
+ * `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 { promises as fsp } from "node:fs";
+import path from "node:path";
+import { confirm, input, password } from "@inquirer/prompts";
+import { ACTIVE_PROFILE_FILE, CONFIG_DIR, CONFIG_PATH, PROFILES_DIR, profilePaths, TOKEN_PATH, } from "../../config/paths.js";
+import { sanitizeForLog, validateToken } from "../init/token.js";
+const DEFAULT_PROMPTS = { input, password, confirm };
+/** Register `el-linear profile migrate-legacy` under the parent `profile` command. */
+export function registerMigrateLegacy(profile) {
+    profile
+        .command("migrate-legacy")
+        .description("Copy the legacy ~/.config/el-linear/{config.json,token} into a named profile so >=1.4 commands work again.")
+        .option("--name <name>", "Target profile name. Defaults to `default`.", "default")
+        .option("--token-from <path>", "Read the API token from this file instead of prompting.")
+        .option("--force", "Overwrite an existing per-profile config.json or token even when contents differ.")
+        .option("--yes", "Skip interactive confirmations (still respects --force semantics).")
+        .action(async (opts) => {
+        await runMigrateLegacy({
+            name: opts.name,
+            tokenFrom: opts.tokenFrom,
+            force: opts.force === true,
+            yes: opts.yes === true,
+        });
+    });
+}
+/**
+ * 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 async function runMigrateLegacy(options, deps = {}) {
+    const stdout = deps.stdout ?? process.stdout;
+    const prompts = deps.prompts ?? DEFAULT_PROMPTS;
+    const validate = deps.validateToken ?? validateToken;
+    // 1. Pre-flight: legacy config must exist. There's nothing to migrate
+    //    on a freshly-onboarded machine and we don't want to silently
+    //    create an empty profile.
+    if (!(await pathExists(CONFIG_PATH))) {
+        stdout.write(`Nothing to migrate — no legacy config found at ${CONFIG_PATH}.\n`);
+        stdout.write("If this is a fresh install, run `el-linear init` instead.\n");
+        process.exit(1);
+    }
+    const initialName = (options.name ?? "default").trim() || "default";
+    let name = initialName;
+    // Allow an interactive override of the target name unless --yes was passed
+    // (scripted) or --name was explicitly set to something other than the
+    // default. Keeps backward compat with the CLI flag while not surprising
+    // CI runs.
+    if (!options.skipPrompt && !options.yes && options.name === undefined) {
+        const answer = await prompts.input({
+            message: "Target profile name:",
+            default: name,
+        });
+        const trimmed = answer.trim();
+        if (trimmed.length > 0)
+            name = trimmed;
+    }
+    if (!isSafeName(name)) {
+        throw new Error(`Invalid profile name "${name}". Allowed: [a-z0-9_.-], up to 64 chars.`);
+    }
+    // 2. Token source priority: --token-from > EL_LINEAR_TOKEN > prompt.
+    //    Validate before writing anything to disk.
+    const token = await resolveAndValidateToken(options, prompts, validate);
+    // 3. Profile dir.
+    const paths = profilePaths(name);
+    const profileDir = path.dirname(paths.configPath);
+    await fsp.mkdir(profileDir, { recursive: true, mode: 0o700 });
+    // 4. Config copy with idempotent + force semantics.
+    await copyConfigIntoProfile(paths.configPath, options, prompts);
+    // 5. Token write with idempotent + force semantics.
+    await writeProfileToken(paths.tokenPath, token, options, prompts);
+    // 6. active-profile marker.
+    await ensureActiveProfile(name);
+    // 7. Legacy preservation hint. We do NOT delete the legacy paths —
+    //    the user gets a rollback if anything went sideways.
+    stdout.write(`legacy ${CONFIG_PATH} kept for rollback; safe to remove later if no longer needed\n`);
+    // 8. Final verify against the freshly-written profile token. This is
+    //    a defensive double-check: the token was already validated above,
+    //    but verifying *after* the write catches any FS-level surprise
+    //    (e.g. wrong token landed in the wrong dir on a multi-profile box).
+    const onDiskToken = (await fsp.readFile(paths.tokenPath, "utf8")).trim();
+    const viewer = await validate(onDiskToken);
+    stdout.write(`✓ Migrated. Active profile: ${name}. Workspace: ${viewer.organization.urlKey}\n`);
+}
+// ---- Helpers --------------------------------------------------------
+async function resolveAndValidateToken(options, prompts, validate) {
+    if (options.tokenFrom) {
+        const raw = await fsp.readFile(options.tokenFrom, "utf8");
+        const token = raw.trim();
+        if (!token) {
+            throw new Error(`Token file ${options.tokenFrom} is empty.`);
+        }
+        await validate(token);
+        return token;
+    }
+    const envToken = process.env.EL_LINEAR_TOKEN?.trim();
+    if (envToken) {
+        await validate(envToken);
+        return envToken;
+    }
+    // Interactive: up to three attempts, hidden input. We re-prompt on
+    // validation failure rather than aborting so the user can paste a
+    // fresh token without re-running the whole command.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const candidate = (await prompts.password({
+            message: attempt === 0
+                ? "Linear API token (input hidden):"
+                : "Try again (input hidden):",
+            mask: "*",
+            validate: (s) => s.trim().length > 0 || "Token cannot be empty",
+        })).trim();
+        try {
+            await validate(candidate);
+            return candidate;
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            // biome-ignore lint/suspicious/noConsole: interactive prompt feedback
+            console.log(`  ✗ ${sanitizeForLog(raw)}`);
+        }
+    }
+    throw new Error("Could not validate a Linear API token after 3 attempts. Aborting migration.");
+}
+async function copyConfigIntoProfile(destConfigPath, options, prompts) {
+    const sourceContent = await fsp.readFile(CONFIG_PATH, "utf8");
+    if (!(await pathExists(destConfigPath))) {
+        await fsp.writeFile(destConfigPath, sourceContent, {
+            mode: 0o644,
+            encoding: "utf8",
+        });
+        return;
+    }
+    const destContent = await fsp.readFile(destConfigPath, "utf8");
+    if (destContent === sourceContent) {
+        // Idempotent re-run — nothing to do.
+        return;
+    }
+    if (!options.force) {
+        throw new Error([
+            `Refusing to overwrite ${destConfigPath} — its contents differ from ${CONFIG_PATH}.`,
+            "Re-run with --force to overwrite. The legacy file is kept either way; only the per-profile copy changes.",
+            `Diff hint: \`diff ${CONFIG_PATH} ${destConfigPath}\``,
+        ].join("\n"));
+    }
+    if (!options.yes) {
+        const ok = await prompts.confirm({
+            message: `Overwrite ${destConfigPath} with the legacy config?`,
+            default: false,
+        });
+        if (!ok) {
+            throw new Error("Aborted by user.");
+        }
+    }
+    await fsp.writeFile(destConfigPath, sourceContent, {
+        mode: 0o644,
+        encoding: "utf8",
+    });
+}
+async function writeProfileToken(destTokenPath, token, options, prompts) {
+    const newline = `${token}\n`;
+    if (!(await pathExists(destTokenPath))) {
+        await fsp.writeFile(destTokenPath, newline, {
+            mode: 0o600,
+            encoding: "utf8",
+        });
+        // fs.writeFile mode is only honored on file creation; chmod defensively
+        // in case a parent process pre-created the file with permissive perms.
+        await fsp.chmod(destTokenPath, 0o600);
+        return;
+    }
+    const existing = (await fsp.readFile(destTokenPath, "utf8")).trim();
+    if (existing === token) {
+        // Idempotent re-run — already correct; force perms regardless.
+        await fsp.chmod(destTokenPath, 0o600);
+        return;
+    }
+    if (!options.force) {
+        throw new Error([
+            `Refusing to overwrite ${destTokenPath} — it contains a different token.`,
+            "Re-run with --force to overwrite the per-profile token.",
+        ].join("\n"));
+    }
+    if (!options.yes) {
+        const ok = await prompts.confirm({
+            message: `Overwrite the existing token at ${destTokenPath}?`,
+            default: false,
+        });
+        if (!ok) {
+            throw new Error("Aborted by user.");
+        }
+    }
+    await fsp.writeFile(destTokenPath, newline, {
+        mode: 0o600,
+        encoding: "utf8",
+    });
+    await fsp.chmod(destTokenPath, 0o600);
+}
+async function ensureActiveProfile(name) {
+    await fsp.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    let current = null;
+    if (await pathExists(ACTIVE_PROFILE_FILE)) {
+        current = (await fsp.readFile(ACTIVE_PROFILE_FILE, "utf8")).trim();
+    }
+    if (current === name)
+        return;
+    await fsp.writeFile(ACTIVE_PROFILE_FILE, `${name}\n`, {
+        mode: 0o644,
+        encoding: "utf8",
+    });
+}
+async function pathExists(p) {
+    try {
+        await fsp.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Profile names land in filesystem paths and the active-profile marker.
+ * Same conservative charset as `profile add` to avoid `..` traversal,
+ * shell metacharacters, and Unicode lookalikes.
+ */
+function isSafeName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(name);
+}
+// Re-export internals so the integration test (and follow-up commands)
+// can compose them without re-implementing the idempotency rules.
+export { CONFIG_PATH, PROFILES_DIR, TOKEN_PATH };