@enrichlayer/el-linear 1.2.0 → 1.5.0

package/dist/config/config.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import { outputWarning } from "../utils/output.js";
-import { CONFIG_PATH } from "./paths.js";
+import { CONFIG_PATH, resolveActiveProfile } from "./paths.js";
 const DEFAULT_CONFIG = {
     defaultTeam: "",
     defaultLabels: [],
@@ -23,13 +23,25 @@ const DEFAULT_CONFIG = {
     terms: [],
 };
 let cachedConfig;
+/** Test seam — resets the cache between test cases. */
+export function _resetConfigCacheForTests() {
+    cachedConfig = undefined;
+}
 export function loadConfig() {
     if (cachedConfig) {
         return cachedConfig;
     }
-    if (fs.existsSync(CONFIG_PATH)) {
+    // Profile-aware: read from <CONFIG_DIR>/profiles/<name>/config.json
+    // when a profile is active, falling back to the legacy single-file
+    // path so existing setups keep working without migration.
+    const active = resolveActiveProfile();
+    const candidates = [active.configPath];
+    if (active.configPath !== CONFIG_PATH)
+        candidates.push(CONFIG_PATH);
+    const sourcePath = candidates.find((p) => fs.existsSync(p));
+    if (sourcePath) {
         try {
-            const userConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+            const userConfig = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
             // Migration: the legacy `brand: { name, reject }` config is auto-promoted to
             // a single entry in `terms[]`. We warn (not throw) so existing users get a
             // grace period to update their config.
@@ -52,12 +64,15 @@ export function loadConfig() {
             cachedConfig = deepMerge(DEFAULT_CONFIG, userConfig);
         }
         catch {
-            outputWarning(`Failed to parse ${CONFIG_PATH}, using empty defaults`);
+            outputWarning(`Failed to parse ${sourcePath}, using empty defaults`);
             cachedConfig = DEFAULT_CONFIG;
         }
     }
     else {
-        outputWarning(`No config found at ${CONFIG_PATH}. Run with --init to create one.`);
+        const profileNote = active.name
+            ? ` (active profile: \`${active.name}\` — expected at ${active.configPath})`
+            : "";
+        outputWarning(`No config found at ${active.configPath}${profileNote}. Run \`el-linear init\` (or \`el-linear profile add ${active.name ?? "<name>"}\`) to create one.`);
         cachedConfig = DEFAULT_CONFIG;
     }
     return cachedConfig;

package/dist/config/paths.d.ts

@@ -18,3 +18,30 @@ export declare const LEGACY_LINCTL_CONFIG_PATH: string;
 export declare const LEGACY_LINCTL_TOKEN_PATH: string;
 /** Even older fallback from before the `~/.config/...` move (one release). */
 export declare const LEGACY_TOKEN_PATH: string;
+export declare const PROFILES_DIR: string;
+export declare const ACTIVE_PROFILE_FILE: string;
+export interface ProfilePaths {
+    /** Profile name; null when using the legacy single-file layout. */
+    name: string | null;
+    configPath: string;
+    tokenPath: string;
+}
+export interface ProfileFsOps {
+    readFileSync: (p: string) => string;
+    existsSync: (p: string) => boolean;
+}
+/**
+ * Set the active profile for the duration of this process. Pass `null`
+ * to clear the override and fall back to env / on-disk markers.
+ */
+export declare function setActiveProfileForSession(name: string | null): void;
+/** Read-only accessor for the per-session override (test seam). */
+export declare function getSessionProfileOverride(): string | null;
+/**
+ * Resolve the active profile name + on-disk paths. Returns the legacy
+ * single-file layout when no profile is selected, so existing setups
+ * keep working without migration.
+ */
+export declare function resolveActiveProfile(env?: NodeJS.ProcessEnv, fsImpl?: ProfileFsOps): ProfilePaths;
+/** Build profile-relative paths for a named profile. Pure. */
+export declare function profilePaths(name: string): ProfilePaths;

package/dist/config/paths.js

@@ -3,6 +3,7 @@
  * config loader, the auth module, and the init wizard all agree on where to
  * read and write.
  */
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 export const CONFIG_DIR = path.join(os.homedir(), ".config", "el-linear");
@@ -20,3 +21,79 @@ export const LEGACY_LINCTL_CONFIG_PATH = path.join(LEGACY_LINCTL_CONFIG_DIR, "co
 export const LEGACY_LINCTL_TOKEN_PATH = path.join(LEGACY_LINCTL_CONFIG_DIR, "token");
 /** Even older fallback from before the `~/.config/...` move (one release). */
 export const LEGACY_TOKEN_PATH = path.join(os.homedir(), ".linear_api_token");
+// ---- Profiles --------------------------------------------------------
+//
+// el-linear supports named profiles for switching between Linear
+// workspaces (org A vs org B vs scratch token). Each profile owns its
+// own config + token. The single-profile layout (CONFIG_PATH +
+// TOKEN_PATH above) keeps working unchanged — existing users see no
+// behavior change. A user opts in to multi-profile by either:
+//   - calling `el-linear profile add <name>`, OR
+//   - hand-creating <CONFIG_DIR>/profiles/<name>/{config.json,token}
+//
+// Resolution order (highest priority first):
+//   1. Per-call --profile <name> flag (set via setActiveProfileForSession)
+//   2. EL_LINEAR_PROFILE env var
+//   3. <CONFIG_DIR>/active-profile (single-line text file)
+//   4. Legacy single-file paths (CONFIG_PATH / TOKEN_PATH) — default,
+//      keeps backward compatibility.
+export const PROFILES_DIR = path.join(CONFIG_DIR, "profiles");
+export const ACTIVE_PROFILE_FILE = path.join(CONFIG_DIR, "active-profile");
+const DEFAULT_FS_OPS = {
+    readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    existsSync: (p) => fs.existsSync(p),
+};
+/**
+ * Per-process override for the active profile name. Set by main.ts when
+ * `--profile <name>` is passed (highest priority).
+ */
+let sessionProfileOverride = null;
+/**
+ * Set the active profile for the duration of this process. Pass `null`
+ * to clear the override and fall back to env / on-disk markers.
+ */
+export function setActiveProfileForSession(name) {
+    sessionProfileOverride = name && name.trim().length > 0 ? name.trim() : null;
+}
+/** Read-only accessor for the per-session override (test seam). */
+export function getSessionProfileOverride() {
+    return sessionProfileOverride;
+}
+/**
+ * Resolve the active profile name + on-disk paths. Returns the legacy
+ * single-file layout when no profile is selected, so existing setups
+ * keep working without migration.
+ */
+export function resolveActiveProfile(env = process.env, fsImpl = DEFAULT_FS_OPS) {
+    const explicit = sessionProfileOverride ??
+        (env.EL_LINEAR_PROFILE?.trim() || null) ??
+        readActiveProfileMarker(fsImpl);
+    if (explicit) {
+        return profilePaths(explicit);
+    }
+    return {
+        name: null,
+        configPath: CONFIG_PATH,
+        tokenPath: TOKEN_PATH,
+    };
+}
+/** Build profile-relative paths for a named profile. Pure. */
+export function profilePaths(name) {
+    const dir = path.join(PROFILES_DIR, name);
+    return {
+        name,
+        configPath: path.join(dir, "config.json"),
+        tokenPath: path.join(dir, "token"),
+    };
+}
+function readActiveProfileMarker(fsImpl) {
+    if (!fsImpl.existsSync(ACTIVE_PROFILE_FILE))
+        return null;
+    try {
+        const value = fsImpl.readFileSync(ACTIVE_PROFILE_FILE).toString().trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/main.js

@@ -13,22 +13,26 @@ import { setupInitCommands } from "./commands/init/index.js";
 import { setupIssueIdCommand } from "./commands/issue-id.js";
 import { setupIssuesCommands } from "./commands/issues.js";
 import { setupLabelsCommands } from "./commands/labels.js";
+import { setupProfileCommands } from "./commands/profile.js";
 import { setupProjectMilestonesCommands } from "./commands/project-milestones.js";
 import { setupProjectsCommands } from "./commands/projects.js";
 import { setupReadShortcut } from "./commands/read-shortcut.js";
+import { setupRefsCommands } from "./commands/refs.js";
 import { setupReleasesCommands } from "./commands/releases.js";
 import { setupSearchCommands } from "./commands/search.js";
 import { setupTeamsCommands } from "./commands/teams.js";
 import { setupTemplatesCommands } from "./commands/templates.js";
 import { setupUsersCommands } from "./commands/users.js";
+import { setActiveProfileForSession } from "./config/paths.js";
 import { setFieldsFilter, setJqFilter, setRawMode } from "./utils/output.js";
 import { outputUsageInfo } from "./utils/usage.js";
 import { splitList } from "./utils/validators.js";
 program
     .name("el-linear")
     .description("A pragmatic CLI for Linear.app — deterministic resolution, structured validation, GraphQL escape hatch.")
-    .version("1.2.0")
+    .version("1.5.0")
     .option("--api-token <token>", "Linear API token")
+    .option("--profile <name>", "named profile (under ~/.config/el-linear/profiles/<name>/) for this invocation. Overrides EL_LINEAR_PROFILE env + the on-disk active-profile marker.")
     .option("--json", "output as JSON (default, accepted for compatibility)")
     .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly")
     .option("--jq <filter>", "apply a jq filter to the JSON output")
@@ -44,6 +48,13 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
     if (rootOpts.fields) {
         setFieldsFilter(splitList(rootOpts.fields));
     }
+    // `--profile <name>` is highest-priority. preAction runs BEFORE the
+    // command body, which is BEFORE getApiToken / loadConfig fire — so
+    // setting the override here means the rest of the run picks up the
+    // right profile's token + config.
+    if (rootOpts.profile) {
+        setActiveProfileForSession(rootOpts.profile);
+    }
 });
 program.action(() => {
     program.help();
@@ -68,6 +79,8 @@ setupGdocCommands(program);
 setupGraphQLCommands(program);
 setupConfigCommands(program);
 setupInitCommands(program);
+setupProfileCommands(program);
+setupRefsCommands(program);
 setupReadShortcut(program);
 program
     .command("usage")

package/dist/utils/auth.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
-import { LEGACY_LINCTL_TOKEN_PATH, LEGACY_TOKEN_PATH, TOKEN_PATH, } from "../config/paths.js";
+import { LEGACY_LINCTL_TOKEN_PATH, LEGACY_TOKEN_PATH, resolveActiveProfile, TOKEN_PATH, } from "../config/paths.js";
+import { maybeEmitMigrationHint } from "./migration-hint.js";
 export function getApiToken(options) {
     if (options.apiToken) {
         return options.apiToken;
@@ -7,7 +8,18 @@ export function getApiToken(options) {
     if (process.env.LINEAR_API_TOKEN) {
         return process.env.LINEAR_API_TOKEN;
     }
-    if (fs.existsSync(TOKEN_PATH)) {
+    // Profile-aware: read from <CONFIG_DIR>/profiles/<name>/token when a
+    // profile is active, falling back to the legacy single-file path
+    // (TOKEN_PATH) for the no-profile case.
+    const active = resolveActiveProfile();
+    if (fs.existsSync(active.tokenPath)) {
+        return fs.readFileSync(active.tokenPath, "utf8").trim();
+    }
+    // Even when a profile is selected, fall through to the legacy token
+    // path so an operator who only has the single-file layout doesn't
+    // suddenly fail. The active-profile name is informational only when
+    // no profile-scoped token exists yet.
+    if (active.tokenPath !== TOKEN_PATH && fs.existsSync(TOKEN_PATH)) {
         return fs.readFileSync(TOKEN_PATH, "utf8").trim();
     }
     // Fallback to the linctl-era token (the CLI was briefly published as
@@ -19,5 +31,15 @@ export function getApiToken(options) {
     if (fs.existsSync(LEGACY_TOKEN_PATH)) {
         return fs.readFileSync(LEGACY_TOKEN_PATH, "utf8").trim();
     }
-    throw new Error("No API token found. Use --api-token, LINEAR_API_TOKEN env var, ~/.config/el-linear/token, or ~/.linear_api_token file");
+    // Before falling through to the auth error, check for legacy-config
+    // drift (legacy `config.json` present but no token, or active-profile
+    // pointer broken). If detected, emit a one-shot stderr hint pointing
+    // the user at `el-linear profile migrate-legacy`. The hint is purely
+    // informational — we always still throw below, so scripted callers
+    // continue to see a non-zero exit and a parseable JSON error on stdout.
+    maybeEmitMigrationHint();
+    const profileNote = active.name
+        ? ` (active profile: \`${active.name}\` — expected token at ${active.tokenPath})`
+        : "";
+    throw new Error(`No API token found${profileNote}. Use --api-token, LINEAR_API_TOKEN env var, ~/.config/el-linear/token, or ~/.linear_api_token file. To switch profiles, use \`el-linear profile use <name>\` or \`--profile <name>\`.`);
 }

package/dist/utils/graphql-service.d.ts

@@ -1,8 +1,23 @@
 import type { GraphQLResponseData, GraphQLVariables } from "../types/linear.js";
 import { type AuthOptions } from "./auth.js";
+/**
+ * Constructor arg shapes for `GraphQLService`. Three variants:
+ *   - `string` → personal API token (legacy; sent without `Bearer` prefix).
+ *   - `{apiKey: string}` → personal API token (explicit).
+ *   - `{oauthToken: string}` → OAuth access token (sent as
+ *     `Authorization: Bearer <token>` via the SDK's accessToken option).
+ *
+ * The string variant exists because hundreds of call sites and tests pass
+ * a plain string. We continue to support it indefinitely.
+ */
+export type GraphQLServiceAuth = string | {
+    apiKey: string;
+} | {
+    oauthToken: string;
+};
 export declare class GraphQLService {
     private readonly graphQLClient;
-    constructor(apiToken: string);
+    constructor(auth: GraphQLServiceAuth);
     rawRequest<T = GraphQLResponseData>(query: string, variables?: GraphQLVariables): Promise<T>;
 }
 export declare function createGraphQLService(options: AuthOptions): GraphQLService;

package/dist/utils/graphql-service.js

@@ -1,14 +1,26 @@
 import { LinearClient } from "@linear/sdk";
 import { getApiToken } from "./auth.js";
+function buildLinearClient(auth) {
+    const baseHeaders = { "public-file-urls-expire-in": "3600" };
+    if (typeof auth === "string") {
+        return new LinearClient({ apiKey: auth, headers: baseHeaders });
+    }
+    if ("oauthToken" in auth) {
+        // Linear's SDK natively supports OAuth via the `accessToken` option,
+        // which causes the underlying graphql-request client to send
+        // `Authorization: Bearer <token>` instead of the personal-token
+        // shape (`Authorization: <token>`).
+        return new LinearClient({
+            accessToken: auth.oauthToken,
+            headers: baseHeaders,
+        });
+    }
+    return new LinearClient({ apiKey: auth.apiKey, headers: baseHeaders });
+}
 export class GraphQLService {
     graphQLClient;
-    constructor(apiToken) {
-        const client = new LinearClient({
-            apiKey: apiToken,
-            headers: {
-                "public-file-urls-expire-in": "3600",
-            },
-        });
+    constructor(auth) {
+        const client = buildLinearClient(auth);
         // LinearClient stores a private graphql-request client — access via escape hatch
         this.graphQLClient = client.client;
     }

package/dist/utils/issue-reference-wrapper.d.ts

@@ -1,12 +1,26 @@
+/**
+ * Output emitter target. `markdown` produces `[ID](url)`; `slack` produces
+ * Slack mrkdwn `<url|ID>`. New targets (e.g. `html`) can be added to the
+ * discriminated map without touching callers.
+ */
+export type WrapTarget = "markdown" | "slack";
 /**
  * Rewrite `text`, wrapping each occurrence of a known-valid Linear issue identifier
- * as a markdown link. Skips any occurrence inside protected ranges (code blocks,
- * inline code, existing markdown links, angle-bracket autolinks).
+ * as a link in the chosen `target` syntax. Skips any occurrence inside protected
+ * ranges (code blocks, inline code, existing markdown links, Slack links,
+ * angle-bracket autolinks, bare URLs).
  *
  * Only IDs in `validIdentifiers` are wrapped — IDs that don't resolve in the
  * workspace are left as plain text (handles false positives like ISO codes).
  *
- * If `text` already contains `[ID](url)` for a given ID, that occurrence is left
- * alone (it's inside a protected range), so this function is idempotent.
+ * If `text` already contains a wrapped `[ID](url)` or `<url|ID>` for a given ID,
+ * that occurrence is left alone (it's inside a protected range), so this
+ * function is idempotent for the matching target. Running `markdown` then
+ * `slack` (or vice versa) will not re-wrap previously-wrapped IDs because the
+ * existing link's content stays inside a protected range.
+ *
+ * The 3-arg signature is preserved as a positional `target` defaulting to
+ * `"markdown"` for backward compatibility with existing callers
+ * (`issues create/update`, `comments create/update`).
  */
-export declare function wrapIssueReferencesAsLinks(text: string, validIdentifiers: Set<string>, workspaceUrlKey: string): string;
+export declare function wrapIssueReferencesAsLinks(text: string, validIdentifiers: Set<string>, workspaceUrlKey: string, target?: WrapTarget): string;

package/dist/utils/issue-reference-wrapper.js

@@ -9,6 +9,9 @@ const FENCED_CODE_BLOCK_REGEX = /(?:^|\n)([ \t]*)(?:```|~~~)[^\n]*\n[\s\S]*?\n\1
 const INLINE_CODE_REGEX = /`[^`\n]+?`/g;
 // Existing markdown links: [text](url). We protect both the text and the url.
 const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]*)\)/g;
+// Existing Slack mrkdwn links: <url|text>. We protect both halves so identifiers
+// inside an already-wrapped Slack link aren't double-wrapped.
+const SLACK_LINK_REGEX = /<https?:\/\/[^|>\s]+\|[^>]*>/g;
 // Angle-bracket autolinks: <https://...>
 const ANGLE_AUTOLINK_REGEX = /<[^>\s]+>/g;
 // Bare URLs in prose. We protect these so identifiers inside paths
@@ -30,6 +33,11 @@ function findProtectedRanges(text) {
         FENCED_CODE_BLOCK_REGEX,
         INLINE_CODE_REGEX,
         MARKDOWN_LINK_REGEX,
+        // Slack links must be protected before generic angle-bracket autolinks,
+        // otherwise the autolink regex would still match `<https://…|label>` because
+        // it doesn't include the pipe boundary. matchAll resets per regex so order
+        // in this list is irrelevant for correctness — both ranges still cover the span.
+        SLACK_LINK_REGEX,
         ANGLE_AUTOLINK_REGEX,
         BARE_URL_REGEX,
     ]) {
@@ -51,22 +59,41 @@ function isProtected(pos, ranges) {
 function buildIssueUrl(identifier, workspaceUrlKey) {
     return `https://linear.app/${workspaceUrlKey}/issue/${identifier}/`;
 }
+/**
+ * Per-target emitters. Each takes the resolved url and human identifier and
+ * returns the wrapped link string. Add a new target by adding a key here.
+ */
+const EMITTERS = {
+    markdown: (id, url) => `[${id}](${url})`,
+    // Slack mrkdwn link syntax: <url|label>. Reference:
+    // https://api.slack.com/reference/surfaces/formatting#linking-urls
+    slack: (id, url) => `<${url}|${id}>`,
+};
 /**
  * Rewrite `text`, wrapping each occurrence of a known-valid Linear issue identifier
- * as a markdown link. Skips any occurrence inside protected ranges (code blocks,
- * inline code, existing markdown links, angle-bracket autolinks).
+ * as a link in the chosen `target` syntax. Skips any occurrence inside protected
+ * ranges (code blocks, inline code, existing markdown links, Slack links,
+ * angle-bracket autolinks, bare URLs).
  *
  * Only IDs in `validIdentifiers` are wrapped — IDs that don't resolve in the
  * workspace are left as plain text (handles false positives like ISO codes).
  *
- * If `text` already contains `[ID](url)` for a given ID, that occurrence is left
- * alone (it's inside a protected range), so this function is idempotent.
+ * If `text` already contains a wrapped `[ID](url)` or `<url|ID>` for a given ID,
+ * that occurrence is left alone (it's inside a protected range), so this
+ * function is idempotent for the matching target. Running `markdown` then
+ * `slack` (or vice versa) will not re-wrap previously-wrapped IDs because the
+ * existing link's content stays inside a protected range.
+ *
+ * The 3-arg signature is preserved as a positional `target` defaulting to
+ * `"markdown"` for backward compatibility with existing callers
+ * (`issues create/update`, `comments create/update`).
  */
-export function wrapIssueReferencesAsLinks(text, validIdentifiers, workspaceUrlKey) {
+export function wrapIssueReferencesAsLinks(text, validIdentifiers, workspaceUrlKey, target = "markdown") {
     if (!text || validIdentifiers.size === 0) {
         return text;
     }
     const ranges = findProtectedRanges(text);
+    const emit = EMITTERS[target];
     // Walk through matches and build the result string in pieces.
     // We can't use String.replace with a callback because we need positional protection checks.
     let result = "";
@@ -83,7 +110,7 @@ export function wrapIssueReferencesAsLinks(text, validIdentifiers, workspaceUrlK
         }
         // Append everything up to this match unchanged
         result += text.slice(cursor, start);
-        result += `[${id}](${buildIssueUrl(id, workspaceUrlKey)})`;
+        result += emit(id, buildIssueUrl(id, workspaceUrlKey));
         cursor = end;
     }
     result += text.slice(cursor);

package/dist/utils/legacy-config-detection.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Detects "legacy drift" — the on-disk state where a user upgraded el-linear
+ * to >=1.4.0 (named profiles) while their old `~/.config/el-linear/config.json`
+ * is still present but the legacy single-file `token` (and any per-profile
+ * token) is missing or unreadable. In that state every command fails with
+ * "No API token found" and the user has no clear migration path.
+ *
+ * This module is **pure detection** — it returns a discriminated state and
+ * nothing else. The hint emission lives in `migration-hint.ts` and is wired
+ * into the auth-failure path (`auth.ts`) so the user gets a single clear
+ * stderr line *before* the regular auth error fires.
+ *
+ * The state shape is intentionally a discriminated union so callers can match
+ * exhaustively without re-checking individual booleans:
+ *
+ *   { kind: 'no-drift' }
+ *     — healthy: legacy single-file layout *or* a working active profile.
+ *
+ *   { kind: 'legacy-no-token' }
+ *     — `config.json` exists but no token (legacy or per-profile) does. This
+ *       is the post-upgrade case: 1.4.0 expects per-profile tokens; legacy
+ *       config was never migrated.
+ *
+ *   { kind: 'broken-active-profile' }
+ *     — `active-profile` points at a name whose directory doesn't exist.
+ *       Typically caused by an interrupted `profile remove` or a hand-edit.
+ */
+export type LegacyDriftState = {
+    kind: "no-drift";
+} | {
+    kind: "legacy-no-token";
+    legacyConfigPath: string;
+} | {
+    kind: "broken-active-profile";
+    pointedAt: string;
+};
+export interface DetectionFsOps {
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string) => string;
+    readdirSync: (p: string) => string[];
+}
+/**
+ * Detect drift between the legacy single-file layout and the >=1.4 named-
+ * profiles layout. Pure — `fsImpl` is overridable so tests can drive every
+ * branch without touching the filesystem.
+ */
+export declare function detectLegacyDrift(fsImpl?: DetectionFsOps): LegacyDriftState;

package/dist/utils/legacy-config-detection.js

@@ -0,0 +1,90 @@
+/**
+ * Detects "legacy drift" — the on-disk state where a user upgraded el-linear
+ * to >=1.4.0 (named profiles) while their old `~/.config/el-linear/config.json`
+ * is still present but the legacy single-file `token` (and any per-profile
+ * token) is missing or unreadable. In that state every command fails with
+ * "No API token found" and the user has no clear migration path.
+ *
+ * This module is **pure detection** — it returns a discriminated state and
+ * nothing else. The hint emission lives in `migration-hint.ts` and is wired
+ * into the auth-failure path (`auth.ts`) so the user gets a single clear
+ * stderr line *before* the regular auth error fires.
+ *
+ * The state shape is intentionally a discriminated union so callers can match
+ * exhaustively without re-checking individual booleans:
+ *
+ *   { kind: 'no-drift' }
+ *     — healthy: legacy single-file layout *or* a working active profile.
+ *
+ *   { kind: 'legacy-no-token' }
+ *     — `config.json` exists but no token (legacy or per-profile) does. This
+ *       is the post-upgrade case: 1.4.0 expects per-profile tokens; legacy
+ *       config was never migrated.
+ *
+ *   { kind: 'broken-active-profile' }
+ *     — `active-profile` points at a name whose directory doesn't exist.
+ *       Typically caused by an interrupted `profile remove` or a hand-edit.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ACTIVE_PROFILE_FILE, CONFIG_PATH, PROFILES_DIR, TOKEN_PATH, } from "../config/paths.js";
+const DEFAULT_FS_OPS = {
+    existsSync: (p) => fs.existsSync(p),
+    readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    readdirSync: (p) => fs.readdirSync(p),
+};
+/**
+ * Detect drift between the legacy single-file layout and the >=1.4 named-
+ * profiles layout. Pure — `fsImpl` is overridable so tests can drive every
+ * branch without touching the filesystem.
+ */
+export function detectLegacyDrift(fsImpl = DEFAULT_FS_OPS) {
+    // Branch 1: broken active-profile pointer.
+    // The `active-profile` marker names a profile that doesn't exist on disk —
+    // classic post-`profile remove` orphan, or a hand-edit typo. We classify
+    // this *before* the legacy-no-token branch because the user explicitly
+    // asked for that profile; the right fix is `profile use <good-name>`, not
+    // migration.
+    if (fsImpl.existsSync(ACTIVE_PROFILE_FILE)) {
+        let pointedAt = "";
+        try {
+            pointedAt = fsImpl.readFileSync(ACTIVE_PROFILE_FILE).trim();
+        }
+        catch {
+            pointedAt = "";
+        }
+        if (pointedAt.length > 0) {
+            const profileDir = path.join(PROFILES_DIR, pointedAt);
+            if (!fsImpl.existsSync(profileDir)) {
+                return { kind: "broken-active-profile", pointedAt };
+            }
+        }
+    }
+    // Branch 2: legacy drift.
+    // Legacy `config.json` exists; legacy `token` doesn't; no profiles configured.
+    // "No profiles configured" = profiles dir missing OR exists-but-empty.
+    if (!fsImpl.existsSync(CONFIG_PATH)) {
+        return { kind: "no-drift" };
+    }
+    if (fsImpl.existsSync(TOKEN_PATH)) {
+        return { kind: "no-drift" };
+    }
+    const profilesEmpty = isProfilesDirEmpty(fsImpl);
+    if (!profilesEmpty) {
+        return { kind: "no-drift" };
+    }
+    return { kind: "legacy-no-token", legacyConfigPath: CONFIG_PATH };
+}
+function isProfilesDirEmpty(fsImpl) {
+    if (!fsImpl.existsSync(PROFILES_DIR))
+        return true;
+    try {
+        const entries = fsImpl.readdirSync(PROFILES_DIR);
+        return entries.length === 0;
+    }
+    catch {
+        // Unreadable dir — treat as empty for the purposes of drift detection
+        // so we don't suppress the hint on a permissions edge case.
+        return true;
+    }
+}

package/dist/utils/migration-hint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Once-per-process stderr hint for legacy-config drift.
+ *
+ * Wired into the auth-failure path in `auth.ts`. When the legacy single-file
+ * config exists but no token can be found anywhere (the >=1.4 post-upgrade
+ * scenario), we emit one stderr line pointing the user at
+ * `el-linear profile migrate-legacy` *before* the regular "No API token
+ * found" error fires.
+ *
+ * Constraints:
+ *
+ * - **stderr only** — stdout is reserved for the JSON error payload that
+ *   machine callers parse, and the hint must not corrupt that stream.
+ * - **Once per process** — even if a script invokes el-linear in a tight
+ *   loop within a single Node process (uncommon but possible), only the
+ *   first failure prints. Anything more is noise.
+ * - **Suppressible** — `EL_LINEAR_SKIP_MIGRATION_HINT=1` silences the hint
+ *   for users who've decided to stay on the legacy layout intentionally.
+ *   The env var is read at *emission time*, not module load, so toggling
+ *   it in tests works without re-importing.
+ * - **Non-blocking** — never throws, never delays the underlying auth
+ *   error. The hint is purely informational.
+ */
+import { type DetectionFsOps, type LegacyDriftState } from "./legacy-config-detection.js";
+/**
+ * Test seam — resets the once-per-process latch so each test starts fresh.
+ * Production code never calls this.
+ */
+export declare function _resetMigrationHintForTests(): void;
+/**
+ * Emit the migration hint to stderr if (and only if) legacy drift is
+ * detected, the latch hasn't fired this process, and the suppress env var
+ * isn't set. Returns the detection state so callers can branch (or log).
+ *
+ * Optional `fsImpl` lets tests drive detection without touching disk.
+ * Optional `stderr` lets tests capture the output without spying on the
+ * global stream.
+ */
+export declare function maybeEmitMigrationHint(fsImpl?: DetectionFsOps, stderr?: {
+    write: (chunk: string) => void;
+}): LegacyDriftState;
+/**
+ * Render the hint string for a given state. Returns null when no hint
+ * should be emitted (no-drift). Exported for unit testing.
+ */
+export declare function formatHint(state: LegacyDriftState): string | null;