@enrichlayer/el-linear 1.4.0 → 1.6.0

package/dist/commands/releases.js

@@ -1,6 +1,7 @@
 import { CREATE_RELEASE_MUTATION, GET_RELEASE_BY_ID_QUERY, GET_RELEASE_PIPELINES_QUERY, GET_RELEASES_QUERY, } from "../queries/releases.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 function transformRelease(release) {
     return {
         id: release.id,
@@ -36,8 +37,8 @@ function transformRelease(release) {
     };
 }
 async function handleCreateRelease(name, options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
     const pipelines = await graphQLService.rawRequest(GET_RELEASE_PIPELINES_QUERY, { first: 50 });
     const pipelineNodes = pipelines.releasePipelines
         ?.nodes;
@@ -84,8 +85,8 @@ export function setupReleasesCommands(program) {
         .option("--pipeline <pipeline>", "filter by pipeline name or ID")
         .option("-l, --limit <number>", "limit results", "25")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const filter = {};
         if (options.pipeline) {
             filter.pipeline = { name: { eqIgnoreCase: options.pipeline } };
@@ -102,8 +103,8 @@ export function setupReleasesCommands(program) {
         .command("read <releaseId>")
         .description("Get release details including linked documents")
         .action(handleAsyncCommand(async (releaseId, _options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(GET_RELEASE_BY_ID_QUERY, { id: releaseId });
         if (!result.release) {
             throw new Error(`Release "${releaseId}" not found`);
@@ -122,8 +123,8 @@ export function setupReleasesCommands(program) {
         .command("pipelines")
         .description("List release pipelines and their stages")
         .action(handleAsyncCommand(async (_options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(GET_RELEASE_PIPELINES_QUERY, { first: 50 });
         const data = (result.releasePipelines
             ?.nodes ?? []).map((p) => ({

package/dist/commands/search.js

@@ -2,6 +2,7 @@ import { resolveTeam, resolveUserDisplayName } from "../config/resolver.js";
 import { SEMANTIC_SEARCH_QUERY } from "../queries/search.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 const TEMPLATES_QUERY = `
   query {
     templates {
@@ -137,8 +138,8 @@ export function setupSearchCommands(program) {
         .option("--team <team>", "filter issue results by team key")
         .option("-l, --limit <number>", "max results", "10")
         .action(handleAsyncCommand(async (query, options, command) => {
-        const rootOpts = command.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const limit = Number.parseInt(options.limit, 10);
         const requestedTypes = options.type
             ? options.type.split(",").map((t) => t.trim().toLowerCase())

package/dist/commands/teams.js

@@ -1,5 +1,6 @@
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 export function setupTeamsCommands(program) {
     const teams = program
         .command("teams")
@@ -11,8 +12,8 @@ export function setupTeamsCommands(program) {
         .description("List all teams")
         .option("-l, --limit <number>", "limit results", "100")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const service = createLinearService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const service = await createLinearService(rootOpts);
         const result = await service.getTeams(Number.parseInt(options.limit, 10));
         outputSuccess({ data: result, meta: { count: result.length } });
     }));

package/dist/commands/templates.js

@@ -1,6 +1,7 @@
 import { TEMPLATE_BY_ID_QUERY, TEMPLATES_LIST_QUERY, } from "../queries/templates.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
 function formatTemplateSummary(t) {
     return {
@@ -25,8 +26,8 @@ export function setupTemplatesCommands(program) {
         .option("--type <type>", "filter by type (issue, document, project, recurringIssue)")
         .option("-l, --limit <number>", "limit results", "50")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const limit = parsePositiveInt(options.limit, "--limit");
         const result = await graphQLService.rawRequest(TEMPLATES_LIST_QUERY);
         let items = result.templates ?? [];
@@ -44,8 +45,8 @@ export function setupTemplatesCommands(program) {
         .command("read <templateId>")
         .description("Read a template including its full content (templateData)")
         .action(handleAsyncCommand(async (templateId, _options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(TEMPLATE_BY_ID_QUERY, {
             id: templateId,
         });

package/dist/commands/users.js

@@ -1,5 +1,6 @@
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 export function setupUsersCommands(program) {
     const users = program.command("users").description("User operations");
     users.action(() => users.help());
@@ -9,8 +10,8 @@ export function setupUsersCommands(program) {
         .option("--active", "Only show active users")
         .option("-l, --limit <number>", "limit results", "100")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const service = createLinearService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const service = await createLinearService(rootOpts);
         const result = await service.getUsers(options.active, Number.parseInt(options.limit, 10));
         outputSuccess({ data: result, meta: { count: result.length } });
     }));

package/dist/config/config.d.ts

@@ -39,6 +39,24 @@ export interface ElLinearConfig {
      * once per session and caches the result.
      */
     workspaceUrlKey?: string;
+    /**
+     * Text appended to issue descriptions and comment bodies on the `create`
+     * paths. Treated as a literal string — include any `\n\n---\n` separator
+     * yourself if you want a horizontal rule. CLI flags `--footer <text>` and
+     * `--no-footer` override this per-invocation.
+     */
+    messageFooter?: string;
+    /**
+     * Named description boilerplates for `el-linear issues create --template <name>`.
+     * The template's value is used as the description body when `--template` is
+     * provided and neither `--description` nor `--description-file` is set.
+     *
+     * Example:
+     *   "descriptionTemplates": {
+     *     "bug": "## Steps to reproduce\n\n1. ...\n\n## Expected\n\n...\n\n## Actual\n\n..."
+     *   }
+     */
+    descriptionTemplates?: Record<string, string>;
 }
 /** Test seam — resets the cache between test cases. */
 export declare function _resetConfigCacheForTests(): void;

package/dist/config/issue-validation.js

@@ -210,7 +210,7 @@ function checkTitleVerbAlignment(title, typeLabel, result) {
         for (const verb of typeVerbs) {
             if (!verb.includes(" "))
                 continue;
-            if (title.toLowerCase().startsWith(verb.toLowerCase() + " ") ||
+            if (title.toLowerCase().startsWith(`${verb.toLowerCase()} `) ||
                 title.toLowerCase() === verb.toLowerCase()) {
                 if (type === typeLabel)
                     return; // match — all good

package/dist/config/resolver.js

@@ -91,7 +91,7 @@ export function resolveMember(input) {
  */
 export async function resolveAssignee(input, rootOpts) {
     if (input.toLowerCase() === "me") {
-        const graphQLService = createGraphQLService(rootOpts);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest("{ viewer { id } }");
         const viewer = result.viewer;
         if (!viewer?.id) {

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.6.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/download-uploads.d.ts

@@ -1,7 +1,8 @@
 import type { LinearIssue } from "../types/linear.js";
+import type { FileService } from "./file-service.js";
 /**
  * Downloads all uploads.linear.app URLs found in an issue's description
  * and comments, replacing them with local file paths so Claude Code
  * can read the images directly.
  */
-export declare function downloadLinearUploads(issue: LinearIssue, apiToken: string): Promise<LinearIssue>;
+export declare function downloadLinearUploads(issue: LinearIssue, fileService: FileService): Promise<LinearIssue>;

package/dist/utils/download-uploads.js

@@ -1,7 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { FileService } from "./file-service.js";
 const DOWNLOAD_DIR = join(tmpdir(), "el-linear-downloads");
 const UPLOAD_URL_REGEX = /https:\/\/uploads\.linear\.app\/[^\s)>\]"]+/g;
 function collectUploadUrls(text) {
@@ -20,7 +19,7 @@ function replaceUrls(text, urlMap) {
  * and comments, replacing them with local file paths so Claude Code
  * can read the images directly.
  */
-export async function downloadLinearUploads(issue, apiToken) {
+export async function downloadLinearUploads(issue, fileService) {
     const allUrls = new Set();
     if (issue.description) {
         for (const url of collectUploadUrls(issue.description)) {
@@ -38,7 +37,6 @@ export async function downloadLinearUploads(issue, apiToken) {
         return issue;
     }
     await mkdir(DOWNLOAD_DIR, { recursive: true });
-    const fileService = new FileService(apiToken);
     const urlMap = new Map();
     await Promise.all([...allUrls].map(async (url) => {
         const filename = extractUniqueFilename(url);
@@ -78,7 +76,7 @@ function extractUniqueFilename(url) {
         // Path like /workspace-id/uuid1/uuid2/filename.png — take last two parts for uniqueness
         const parts = urlObj.pathname.split("/").filter(Boolean);
         if (parts.length >= 2) {
-            return `${parts.at(-2).slice(0, 8)}-${parts.at(-1)}`;
+            return `${parts.at(-2)?.slice(0, 8)}-${parts.at(-1) ?? ""}`;
         }
         return parts.at(-1) || "download";
     }

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

@@ -1,7 +1,22 @@
 import type { FileDownloadResult, FileUploadResult } from "../types/linear.js";
+/**
+ * Constructor arg shapes for `FileService`:
+ *   - `string` → personal API token (legacy; sent as `Authorization: <token>`).
+ *   - `{apiKey: string}` → personal API token (explicit).
+ *   - `{oauthToken: string}` → OAuth access token (sent as
+ *     `Authorization: Bearer <token>`).
+ *
+ * The string variant exists because dozens of tests construct `FileService`
+ * with a plain string. We continue to support it indefinitely.
+ */
+export type FileServiceAuth = string | {
+    apiKey: string;
+} | {
+    oauthToken: string;
+};
 export declare class FileService {
-    private readonly apiToken;
-    constructor(apiToken: string);
+    private readonly authHeader;
+    constructor(auth: FileServiceAuth);
     downloadFile(url: string, options?: {
         output?: string;
         overwrite?: boolean;
@@ -11,3 +26,12 @@ export declare class FileService {
     private requestUploadUrl;
     private putFileToUrl;
 }
+import type { AuthOptions } from "./auth.js";
+/**
+ * OAuth-aware factory: resolves the active credential (with auto-refresh
+ * for OAuth tokens) and returns a `FileService` configured with the right
+ * `Authorization` header shape. Personal tokens use `Authorization:
+ * <token>` (no Bearer prefix); OAuth tokens use `Authorization: Bearer
+ * <token>`.
+ */
+export declare function createFileService(options: AuthOptions): Promise<FileService>;

package/dist/utils/file-service.js

@@ -37,10 +37,17 @@ function getMimeType(filePath) {
     const ext = extname(filePath).toLowerCase();
     return MIME_TYPES[ext] || "application/octet-stream";
 }
+function buildAuthHeader(auth) {
+    if (typeof auth === "string")
+        return auth;
+    if ("oauthToken" in auth)
+        return `Bearer ${auth.oauthToken}`;
+    return auth.apiKey;
+}
 export class FileService {
-    apiToken;
-    constructor(apiToken) {
-        this.apiToken = apiToken;
+    authHeader;
+    constructor(auth) {
+        this.authHeader = buildAuthHeader(auth);
     }
     async downloadFile(url, options = {}) {
         if (!isLinearUploadUrl(url)) {
@@ -67,7 +74,7 @@ export class FileService {
             const isSignedUrl = urlObj.searchParams.has("signature");
             const headers = {};
             if (!isSignedUrl) {
-                headers.Authorization = this.apiToken;
+                headers.Authorization = this.authHeader;
             }
             const response = await fetch(url, { method: "GET", headers });
             if (!response.ok) {
@@ -162,7 +169,7 @@ export class FileService {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                Authorization: this.apiToken,
+                Authorization: this.authHeader,
             },
             body: JSON.stringify({
                 query,
@@ -237,3 +244,18 @@ export class FileService {
         return { success: true, assetUrl: meta.assetUrl, filename };
     }
 }
+import { getActiveAuth } from "../auth/token-resolver.js";
+/**
+ * OAuth-aware factory: resolves the active credential (with auto-refresh
+ * for OAuth tokens) and returns a `FileService` configured with the right
+ * `Authorization` header shape. Personal tokens use `Authorization:
+ * <token>` (no Bearer prefix); OAuth tokens use `Authorization: Bearer
+ * <token>`.
+ */
+export async function createFileService(options) {
+    const auth = await getActiveAuth(options);
+    if (auth.kind === "oauth") {
+        return new FileService({ oauthToken: auth.token });
+    }
+    return new FileService({ apiKey: auth.token });
+}

package/dist/utils/footer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Append a footer to a body string.
+ *
+ * Resolution order:
+ *   1. `--no-footer` flag → return body unchanged
+ *   2. `--footer <text>` flag → use the explicit value
+ *   3. `config.messageFooter` → use the configured value
+ *   4. nothing set → return body unchanged
+ *
+ * The footer is treated as a literal string — callers who want a horizontal
+ * rule or blank line before it must include the separator in the value.
+ *
+ * Used on `create` paths only (issues create, comments create). Update paths
+ * take an explicit body the user has already authored, so we don't auto-inject.
+ */
+export declare function applyFooter(body: string | undefined, options: {
+    footer?: string;
+    noFooter?: boolean;
+}): string | undefined;

package/dist/utils/footer.js

@@ -0,0 +1,27 @@
+import { loadConfig } from "../config/config.js";
+/**
+ * Append a footer to a body string.
+ *
+ * Resolution order:
+ *   1. `--no-footer` flag → return body unchanged
+ *   2. `--footer <text>` flag → use the explicit value
+ *   3. `config.messageFooter` → use the configured value
+ *   4. nothing set → return body unchanged
+ *
+ * The footer is treated as a literal string — callers who want a horizontal
+ * rule or blank line before it must include the separator in the value.
+ *
+ * Used on `create` paths only (issues create, comments create). Update paths
+ * take an explicit body the user has already authored, so we don't auto-inject.
+ */
+export function applyFooter(body, options) {
+    if (options.noFooter) {
+        return body;
+    }
+    const explicit = options.footer;
+    const footer = explicit ?? loadConfig().messageFooter;
+    if (!footer) {
+        return body;
+    }
+    return body ? `${body}${footer}` : footer;
+}

package/dist/utils/gdoc-parser.js

@@ -82,7 +82,7 @@ export function parseGoogleDoc(doc) {
                         .filter((c) => c.paragraph)
                         .map((c) => {
                         let text = "";
-                        for (const el of c.paragraph.elements) {
+                        for (const el of c.paragraph?.elements ?? []) {
                             text += formatTextRun(el);
                         }
                         return text.replace(TRAILING_NEWLINE_RE, "");

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

@@ -8,5 +8,5 @@ declare class GraphQLAttachmentsService {
     deleteAttachment(id: string): Promise<boolean>;
     listAttachments(issueId: string): Promise<LinearAttachment[]>;
 }
-export declare function createGraphQLAttachmentsService(options: AuthOptions): GraphQLAttachmentsService;
+export declare function createGraphQLAttachmentsService(options: AuthOptions): Promise<GraphQLAttachmentsService>;
 export {};

package/dist/utils/graphql-attachments-service.js

@@ -40,7 +40,7 @@ class GraphQLAttachmentsService {
         return attachments.nodes.map(transformAttachment);
     }
 }
-export function createGraphQLAttachmentsService(options) {
-    const graphqlService = createGraphQLService(options);
+export async function createGraphQLAttachmentsService(options) {
+    const graphqlService = await createGraphQLService(options);
     return new GraphQLAttachmentsService(graphqlService);
 }

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

@@ -14,5 +14,5 @@ declare class GraphQLDocumentsService {
     deleteDocument(id: string): Promise<boolean>;
     listDocumentsBySlugIds(slugIds: string[], limit?: number): Promise<LinearDocument[]>;
 }
-export declare function createGraphQLDocumentsService(options: AuthOptions): GraphQLDocumentsService;
+export declare function createGraphQLDocumentsService(options: AuthOptions): Promise<GraphQLDocumentsService>;
 export {};

package/dist/utils/graphql-documents-service.js

@@ -91,7 +91,7 @@ class GraphQLDocumentsService {
         return result.documents.nodes.map(transformDocument);
     }
 }
-export function createGraphQLDocumentsService(options) {
-    const graphqlService = createGraphQLService(options);
+export async function createGraphQLDocumentsService(options) {
+    const graphqlService = await createGraphQLService(options);
     return new GraphQLDocumentsService(graphqlService);
 }

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";
+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;
+export declare function createGraphQLService(options: AuthOptions): Promise<GraphQLService>;

package/dist/utils/graphql-service.js

@@ -1,14 +1,26 @@
 import { LinearClient } from "@linear/sdk";
-import { getApiToken } from "./auth.js";
+import { getActiveAuth } from "../auth/token-resolver.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;
     }
@@ -29,7 +41,10 @@ export class GraphQLService {
         }
     }
 }
-export function createGraphQLService(options) {
-    const apiToken = getApiToken(options);
-    return new GraphQLService(apiToken);
+export async function createGraphQLService(options) {
+    const auth = await getActiveAuth(options);
+    if (auth.kind === "oauth") {
+        return new GraphQLService({ oauthToken: auth.token });
+    }
+    return new GraphQLService({ apiKey: auth.token });
 }

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;