@enrichlayer/el-linear 1.4.0 → 1.5.0

package/dist/commands/profile.js

@@ -26,6 +26,7 @@ import { confirm } from "@inquirer/prompts";
 import { ACTIVE_PROFILE_FILE, CONFIG_DIR, CONFIG_PATH, PROFILES_DIR, profilePaths, resolveActiveProfile, setActiveProfileForSession, TOKEN_PATH, } from "../config/paths.js";
 import { outputSuccess, outputWarning } from "../utils/output.js";
 import { runFullWizard } from "./init/index.js";
+import { registerMigrateLegacy } from "./profile/migrate-legacy.js";
 export function setupProfileCommands(program) {
     const profile = program
         .command("profile")
@@ -72,6 +73,11 @@ export function setupProfileCommands(program) {
         .action(async (name, opts) => {
         await runProfileRemove(name, opts.force === true);
     });
+    // `el-linear profile migrate-legacy` — registered alongside add/list/etc.
+    // Lives in its own module so the multi-step migration logic stays
+    // self-contained and unit-testable without dragging in the full
+    // profile-management surface.
+    registerMigrateLegacy(profile);
 }
 export async function runProfileList() {
     const active = resolveActiveProfile();

package/dist/main.js

@@ -30,7 +30,7 @@ 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.3.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)")

package/dist/utils/auth.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 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;
@@ -30,6 +31,13 @@ export function getApiToken(options) {
     if (fs.existsSync(LEGACY_TOKEN_PATH)) {
         return fs.readFileSync(LEGACY_TOKEN_PATH, "utf8").trim();
     }
+    // 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})`
         : "";

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/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;

package/dist/utils/migration-hint.js

@@ -0,0 +1,90 @@
+/**
+ * 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 { detectLegacyDrift, } from "./legacy-config-detection.js";
+let hintAlreadyEmitted = false;
+/**
+ * Test seam — resets the once-per-process latch so each test starts fresh.
+ * Production code never calls this.
+ */
+export function _resetMigrationHintForTests() {
+    hintAlreadyEmitted = false;
+}
+/**
+ * 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 function maybeEmitMigrationHint(fsImpl, stderr = process.stderr) {
+    const state = detectLegacyDrift(fsImpl);
+    // Read the env var at call time — the suppress flag may be flipped between
+    // commands in long-lived test processes.
+    if (process.env.EL_LINEAR_SKIP_MIGRATION_HINT === "1") {
+        return state;
+    }
+    if (hintAlreadyEmitted) {
+        return state;
+    }
+    const message = formatHint(state);
+    if (message === null) {
+        return state;
+    }
+    hintAlreadyEmitted = true;
+    stderr.write(`${message}\n`);
+    return state;
+}
+/**
+ * Render the hint string for a given state. Returns null when no hint
+ * should be emitted (no-drift). Exported for unit testing.
+ */
+export function formatHint(state) {
+    if (state.kind === "no-drift")
+        return null;
+    if (state.kind === "broken-active-profile") {
+        return [
+            `el-linear: active profile "${state.pointedAt}" doesn't exist.`,
+            "Switch with:",
+            "",
+            "  el-linear profile use <name>",
+            "",
+            "Or list available profiles:",
+            "",
+            "  el-linear profile list",
+            "",
+            "Or suppress this hint with EL_LINEAR_SKIP_MIGRATION_HINT=1.",
+        ].join("\n");
+    }
+    // legacy-no-token
+    return [
+        `el-linear: legacy config detected at ${state.legacyConfigPath}`,
+        "but no token. Migrate with:",
+        "",
+        "  el-linear profile migrate-legacy [--name <profile>]",
+        "",
+        "Or suppress this hint with EL_LINEAR_SKIP_MIGRATION_HINT=1.",
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",