@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/commands/init/index.js

@@ -14,10 +14,11 @@
  * Skip is the default at every prompt. Only `init token` is required for a
  * first-time setup; everything else can be skipped and revisited later.
  */
+import { validateOAuthActor, } from "../../auth/oauth-client.js";
 import { mergeAliasesIntoConfig, runAliasesImport, runAliasesStep, } from "./aliases.js";
 import { runDefaultsStep } from "./defaults.js";
 import { runOAuthRevoke, runOAuthStep } from "./oauth.js";
-import { assignDefined, printStep, readConfig, writeConfig, } from "./shared.js";
+import { assignDefined, printStep, readConfig, updateConfig, } from "./shared.js";
 import { runTokenStep } from "./token.js";
 import { runWorkspaceStep } from "./workspace.js";
 /**
@@ -60,6 +61,7 @@ export function setupInitCommands(program) {
         .command("oauth")
         .description("Authorize via OAuth 2.0 (PKCE) — alternative to a personal API token")
         .option("--force", "ignore existing tokens; re-authorize unconditionally")
+        .option("--actor <actor>", "OAuth actor: user (default) or app for agents/service accounts", validateOAuthActor)
         .option("--revoke", "revoke and remove the stored OAuth tokens")
         .option("--no-browser", "skip the browser-open + localhost listener; paste the code manually")
         .option("--port <port>", "localhost callback port (default 8765)", (value) => Number.parseInt(value, 10))
@@ -72,6 +74,7 @@ export function setupInitCommands(program) {
             return;
         }
         await runOAuthStep({
+            actor: options.actor,
             force: options.force ?? false,
             // commander's `--no-browser` produces `browser: false`.
             noBrowser: options.browser === false,
@@ -87,14 +90,15 @@ export function setupInitCommands(program) {
         const existing = await readConfig();
         printStep("workspace", "Workspace defaults");
         const ws = await runWorkspaceStep(tokenResult.token, tokenResult.viewer.organization.urlKey, existing);
-        const merged = assignDefined(existing, {
+        // Re-read inside the lock so a concurrent `init <step>` that
+        // finished while we were prompting isn't clobbered (DEV-4066).
+        await updateConfig((current) => assignDefined(current, {
             defaultTeam: ws.defaultTeam,
-            teams: { ...(existing.teams ?? {}), ...ws.teams },
-            // Don't clobber a manual urlKey override — same idempotency
-            // rule as the full wizard.
-            workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
-        });
-        await writeConfig(merged);
+            teams: { ...(current.teams ?? {}), ...ws.teams },
+            // Don't clobber a manual urlKey override — same
+            // idempotency rule as the full wizard.
+            workspaceUrlKey: current.workspaceUrlKey ?? ws.workspaceUrlKey,
+        }));
         console.log("  ✓ Workspace defaults saved.");
     }));
     init
@@ -123,8 +127,9 @@ export function setupInitCommands(program) {
             console.log("  No alias changes — config unchanged.");
             return;
         }
-        const merged = mergeAliasesIntoConfig(existing, updates);
-        await writeConfig(merged);
+        // Re-merge under the lock against the latest on-disk state so
+        // a concurrent step's write isn't lost (DEV-4066).
+        await updateConfig((current) => mergeAliasesIntoConfig(current, updates));
         console.log(`  ✓ Updated aliases for ${updates.size} user(s).`);
     }));
     init
@@ -134,15 +139,16 @@ export function setupInitCommands(program) {
         const existing = await readConfig();
         printStep("defaults", "Defaults");
         const result = await runDefaultsStep(existing);
-        const merged = assignDefined(existing, {
+        // Re-read inside the lock so a concurrent `init <step>` that
+        // finished while we were prompting isn't clobbered (DEV-4066).
+        await updateConfig((current) => assignDefined(current, {
             defaultLabels: result.defaultLabels,
             defaultAssignee: result.defaultAssignee,
             defaultPriority: result.defaultPriority,
             statusDefaults: result.statusDefaults,
             terms: result.terms,
             cacheTTLSeconds: result.cacheTTLSeconds,
-        });
-        await writeConfig(merged);
+        }));
         console.log("  ✓ Defaults saved.");
     }));
 }
@@ -170,33 +176,37 @@ async function runFullWizardImpl(options) {
     // Step 4: defaults
     printStep("4/4", "Defaults");
     const defaults = await runDefaultsStep(existing);
-    // Merge everything and write atomically at the end.
+    // Merge everything and write atomically at the end, under the config
+    // lock so a parallel `init <step>` invocation can't clobber us
+    // (DEV-4066). Re-read inside the lock to merge on the latest state.
     // Idempotency rule: only write a key when the user explicitly changed it.
-    // `existing.X ?? new.X` preserves any manual override the user may have
+    // `current.X ?? new.X` preserves any manual override the user may have
     // in config.json (self-hosted Linear urlKey, custom default team, etc.).
     // `assignDefined` skips undefined values so the resulting object's own-
     // property set matches what JSON.stringify would actually serialize.
-    let merged = assignDefined(existing, {
-        // defaults step: result is `existing.X` itself when the user skipped
-        // the edit branch, so direct assignment is safe.
-        defaultLabels: defaults.defaultLabels,
-        defaultAssignee: defaults.defaultAssignee,
-        defaultPriority: defaults.defaultPriority,
-        statusDefaults: defaults.statusDefaults,
-        terms: defaults.terms,
-        cacheTTLSeconds: defaults.cacheTTLSeconds,
-        // workspace step: `ws.defaultTeam` may be the existing value (user
-        // skipped) or a new pick.
-        defaultTeam: ws.defaultTeam,
-        // Always merge the team UUID cache (additive, not destructive).
-        teams: { ...(existing.teams ?? {}), ...ws.teams },
-        // workspaceUrlKey: never clobber an existing manual override.
-        workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
+    await updateConfig((current) => {
+        let merged = assignDefined(current, {
+            // defaults step: result is `existing.X` itself when the user
+            // skipped the edit branch, so direct assignment is safe.
+            defaultLabels: defaults.defaultLabels,
+            defaultAssignee: defaults.defaultAssignee,
+            defaultPriority: defaults.defaultPriority,
+            statusDefaults: defaults.statusDefaults,
+            terms: defaults.terms,
+            cacheTTLSeconds: defaults.cacheTTLSeconds,
+            // workspace step: `ws.defaultTeam` may be the existing value (user
+            // skipped) or a new pick.
+            defaultTeam: ws.defaultTeam,
+            // Always merge the team UUID cache (additive, not destructive).
+            teams: { ...(current.teams ?? {}), ...ws.teams },
+            // workspaceUrlKey: never clobber an existing manual override.
+            workspaceUrlKey: current.workspaceUrlKey ?? ws.workspaceUrlKey,
+        });
+        if (aliasUpdates.size > 0) {
+            merged = mergeAliasesIntoConfig(merged, aliasUpdates);
+        }
+        return merged;
     });
-    if (aliasUpdates.size > 0) {
-        merged = mergeAliasesIntoConfig(merged, aliasUpdates);
-    }
-    await writeConfig(merged);
     console.log("\n✓ Setup complete.");
     console.log("  Token:  ~/.config/el-linear/token (mode 0600)");
     console.log("  Config: ~/.config/el-linear/config.json");

package/dist/commands/init/oauth.d.ts

@@ -18,6 +18,7 @@
  * revoke before doing anything else.
  */
 import { runLocalhostCallback } from "../../auth/oauth-callback.js";
+import { type OAuthActor } from "../../auth/oauth-client.js";
 import { type OAuthState } from "../../auth/oauth-storage.js";
 import { type FetchLike } from "../../auth/oauth-token.js";
 interface ViewerResponse {
@@ -33,6 +34,8 @@ interface ViewerResponse {
     };
 }
 export interface OAuthStepOptions {
+    /** OAuth actor mode: `user` (default) or `app` for agents/service accounts. */
+    actor?: OAuthActor;
     /** Force re-authorization even if existing state is valid. */
     force?: boolean;
     /** Skip the localhost listener; use the headless code-paste prompt. */
@@ -56,7 +59,7 @@ export interface OAuthStepOptions {
     /** Test seam for `viewer` validation against the new bearer token. */
     validateViewer?: (oauthToken: string) => Promise<ViewerResponse["viewer"]>;
 }
-export interface OAuthStepResult {
+interface OAuthStepResult {
     state: OAuthState;
     viewer: ViewerResponse["viewer"];
 }

package/dist/commands/init/oauth.js

@@ -21,7 +21,7 @@ import { spawn } from "node:child_process";
 import { checkbox, input, password, select } from "@inquirer/prompts";
 import { readTeamOAuthConfig } from "../../auth/oauth-app-config.js";
 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 { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateActorScopes, 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";
@@ -128,7 +128,11 @@ 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(TS(`Then paste the client_id (and client_secret, if your app is configured as confidential).`));
+    logLine(TS(`Actor: ${defaults.actor}.`));
+    if (defaults.actor === "user") {
+        logLine(TS("Use --actor app for agent/service-account app user tokens."));
+    }
     logLine("");
     const port = Number.parseInt(await input({
         message: "Localhost callback port:",
@@ -159,24 +163,34 @@ async function promptRegistration(defaults) {
         })),
         validate: (selections) => selections.length > 0 || "Pick at least one scope",
     }));
+    const validatedScopes = validateScopes(scopes);
+    validateActorScopes(defaults.actor, validatedScopes);
     return {
+        actor: defaults.actor,
         clientId,
         clientSecret: clientSecret || undefined,
         port,
-        scopes: validateScopes(scopes),
+        scopes: validatedScopes,
     };
 }
 async function resolveRegistration(defaults) {
     const teamConfig = await readTeamOAuthConfig();
     if (!teamConfig) {
-        return promptRegistration({ port: defaults.manualPort });
+        return promptRegistration({
+            actor: defaults.actor ?? "user",
+            port: defaults.manualPort,
+        });
     }
+    const actor = defaults.actor ?? teamConfig.actor;
     const port = defaults.requestedPort ?? teamConfig.redirectPort;
     logLine("");
     logLine(TS(`Using Linear OAuth app defaults from ${teamConfig.sourcePath}.`));
+    logLine(TS(`Actor: ${actor}.`));
     logLine(TS(`Callback URL: http://localhost:${port}${DEFAULT_CALLBACK_PATH}`));
     logLine("");
+    validateActorScopes(actor, teamConfig.scopes);
     return {
+        actor,
         clientId: teamConfig.clientId,
         port,
         scopes: teamConfig.scopes,
@@ -231,6 +245,7 @@ export async function runOAuthStep(options = {}) {
         // Both `reauth` and `revoked` fall through to the re-auth flow.
     }
     const reg = await resolveRegistration({
+        actor: options.actor,
         manualPort: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
         requestedPort: options.port,
     });
@@ -243,6 +258,7 @@ export async function runOAuthStep(options = {}) {
         scopes: reg.scopes,
         state,
         codeChallenge: pkce.challenge,
+        actor: reg.actor,
     });
     logLine("");
     logLine(TS("Opening your browser to authorize…"));
@@ -292,6 +308,7 @@ export async function runOAuthStep(options = {}) {
     }, options.fetchImpl);
     const newState = {
         v: OAUTH_STATE_VERSION,
+        actor: reg.actor,
         clientId: reg.clientId,
         clientSecret: reg.clientSecret,
         registeredRedirectUri: redirectUri,
@@ -304,6 +321,7 @@ export async function runOAuthStep(options = {}) {
     };
     logLine(TS("Validating against viewer…"));
     const viewer = await validateViewer(newState.accessToken);
+    newState.viewerId = viewer.id;
     await writeOAuthState(newState);
     logLine(TS(`✓ Authorized as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`));
     return { state: newState, viewer };

package/dist/commands/init/shared.d.ts

@@ -29,8 +29,30 @@ type DeepPartial<T> = T extends Array<infer _U> ? T : T extends object ? {
  */
 export type WizardConfig = DeepPartial<ElLinearConfig>;
 export declare function ensureConfigDir(): Promise<void>;
-export declare function readConfig(): Promise<WizardConfig>;
-export declare function writeConfig(config: WizardConfig): Promise<void>;
+export declare function readConfig(configPath?: string): Promise<WizardConfig>;
+export declare function writeConfig(config: WizardConfig, configPath?: string): Promise<void>;
+/**
+ * Run a read-modify-write update on the active profile's config.json under
+ * an exclusive file lock. The mutator receives the latest on-disk config
+ * (re-read inside the lock), and its return value is written back atomically.
+ *
+ * Use this anywhere two parallel wizard invocations could race a
+ * read → mutate → write sequence. Each `el-linear init <step>` re-reads the
+ * config and merges its slice; without serialization, the slower writer's
+ * mutation would clobber the faster writer's already-persisted changes.
+ *
+ * The interactive prompt phase MUST run outside the lock — prompts can sit
+ * waiting for user input longer than the lock's stale window. Seed prompts
+ * with a cheap pre-read, do the prompts, then call `updateConfig` with a
+ * mutator that re-reads and merges your slice on top of the latest state.
+ *
+ * The active-profile path is snapshotted ONCE at entry and threaded through
+ * `readConfig` + `writeConfig`. A theoretical mid-update profile switch
+ * (`--profile` is bound by the commander preAction before any subcommand
+ * runs, so this can't happen via the CLI today) can't cause a lock-A /
+ * read-or-write-B mismatch.
+ */
+export declare function updateConfig(mutator: (current: WizardConfig) => WizardConfig | Promise<WizardConfig>): Promise<void>;
 export declare function readToken(): Promise<string | null>;
 /**
  * Write the token to disk with mode 0600.

package/dist/commands/init/shared.js

@@ -8,6 +8,7 @@
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { withFileLock } from "../../auth/oauth-fs.js";
 import { ALIASES_PROGRESS_PATH, CONFIG_DIR, CONFIG_PATH, resolveActiveProfile, TOKEN_PATH, } from "../../config/paths.js";
 // Re-export for tests and call sites that already pulled the paths from here.
 export { ALIASES_PROGRESS_PATH, CONFIG_PATH, TOKEN_PATH };
@@ -65,9 +66,9 @@ export async function ensureConfigDir() {
         await fs.mkdir(dir, { recursive: true, mode: 0o700 });
     }
 }
-export async function readConfig() {
+export async function readConfig(configPath = activePaths().configPath) {
     try {
-        const raw = await fs.readFile(activePaths().configPath, "utf8");
+        const raw = await fs.readFile(configPath, "utf8");
         return JSON.parse(raw);
     }
     catch (err) {
@@ -77,11 +78,41 @@ export async function readConfig() {
         throw err;
     }
 }
-export async function writeConfig(config) {
+export async function writeConfig(config, configPath = activePaths().configPath) {
     await ensureConfigDir();
     // Stable key order so byte-identical config produces byte-identical output.
     const sorted = sortKeys(config);
-    await atomicWrite(activePaths().configPath, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
+    await atomicWrite(configPath, `${JSON.stringify(sorted, null, 2)}\n`, 0o644);
+}
+/**
+ * Run a read-modify-write update on the active profile's config.json under
+ * an exclusive file lock. The mutator receives the latest on-disk config
+ * (re-read inside the lock), and its return value is written back atomically.
+ *
+ * Use this anywhere two parallel wizard invocations could race a
+ * read → mutate → write sequence. Each `el-linear init <step>` re-reads the
+ * config and merges its slice; without serialization, the slower writer's
+ * mutation would clobber the faster writer's already-persisted changes.
+ *
+ * The interactive prompt phase MUST run outside the lock — prompts can sit
+ * waiting for user input longer than the lock's stale window. Seed prompts
+ * with a cheap pre-read, do the prompts, then call `updateConfig` with a
+ * mutator that re-reads and merges your slice on top of the latest state.
+ *
+ * The active-profile path is snapshotted ONCE at entry and threaded through
+ * `readConfig` + `writeConfig`. A theoretical mid-update profile switch
+ * (`--profile` is bound by the commander preAction before any subcommand
+ * runs, so this can't happen via the CLI today) can't cause a lock-A /
+ * read-or-write-B mismatch.
+ */
+export async function updateConfig(mutator) {
+    await ensureConfigDir();
+    const configPath = activePaths().configPath;
+    await withFileLock(configPath, async () => {
+        const current = await readConfig(configPath);
+        const next = await mutator(current);
+        await writeConfig(next, configPath);
+    });
 }
 export async function readToken() {
     try {

package/dist/commands/init/token.d.ts

@@ -5,6 +5,8 @@
  * before saving. Token is stored at ~/.config/el-linear/token (mode 0600),
  * never embedded in config.json.
  */
+import { sanitizeForLog } from "../../utils/sanitize-for-log.js";
+export { sanitizeForLog };
 interface ViewerResponse {
     viewer: {
         id: string;
@@ -17,11 +19,10 @@ interface ViewerResponse {
         };
     };
 }
-export interface TokenStepResult {
+interface TokenStepResult {
     token: string;
     viewer: ViewerResponse["viewer"];
 }
-export declare function sanitizeForLog(text: string): string;
 /**
  * Validate a Linear API token by fetching the viewer. Throws with a
  * sanitized user-readable message on auth failure — the error string is
@@ -39,4 +40,3 @@ export declare function runTokenStep(options?: {
     /** Skip the "replace existing?" prompt; always replace if existing is present. */
     force?: boolean;
 }): Promise<TokenStepResult>;
-export {};

package/dist/commands/init/token.js

@@ -7,7 +7,11 @@
  */
 import { confirm, password } from "@inquirer/prompts";
 import { GraphQLService } from "../../utils/graphql-service.js";
+import { sanitizeForLog } from "../../utils/sanitize-for-log.js";
 import { readToken, writeToken } from "./shared.js";
+// Re-export for legacy import paths under `init/`. New code should import
+// from `utils/sanitize-for-log.js` directly.
+export { sanitizeForLog };
 const TOKEN_GENERATION_URL = "https://linear.app/settings/account/security";
 const VIEWER_QUERY = /* GraphQL */ `
   query {
@@ -23,29 +27,6 @@ const VIEWER_QUERY = /* GraphQL */ `
     }
   }
 `;
-/**
- * Strip anything that looks like a Linear API token from a string. Defense in
- * depth: today the @linear/sdk error message embeds {query, variables} but not
- * the Authorization header. A future SDK upgrade that includes headers (which
- * upstream graphql-request has done historically) would otherwise silently
- * write `Bearer lin_api_…` into stdout / shell history / CI logs. The regex
- * also catches token shapes that may show up in custom error wrappers.
- */
-// Personal-API tokens (`lin_api_…`) and OAuth access/refresh tokens
-// (`lin_oauth_…`). Pre-fix the regex only matched personal tokens.
-const TOKEN_PREFIX_RE = /lin_(api|oauth)_[A-Za-z0-9_-]{16,}/g;
-// High-entropy bearer payload fallback: catches generic Bearer-style
-// strings adjacent to Authorization / Bearer keywords. Useful for
-// future SDK error wrappers that might leak headers without the
-// `lin_` prefix.
-const BEARER_PAYLOAD_RE = /(\b(?:Authorization|Bearer)\b[:\s]*)([A-Za-z0-9_\-/+=]{40,})/gi;
-export function sanitizeForLog(text) {
-    return text
-        .replace(TOKEN_PREFIX_RE, (m) => m.startsWith("lin_oauth_")
-        ? "lin_oauth_***REDACTED***"
-        : "lin_api_***REDACTED***")
-        .replace(BEARER_PAYLOAD_RE, "$1***REDACTED***");
-}
 /**
  * Strict shape check on the viewer response. Treats whitespace-only fields as
  * "validated to nothing" — easy to forge with a malformed but truthy stub
@@ -73,7 +54,7 @@ function viewerIsValid(viewer) {
  * is redacted before it hits stdout.
  */
 export async function validateToken(token) {
-    const service = new GraphQLService(token);
+    const service = new GraphQLService({ apiKey: token });
     let data;
     try {
         data = await service.rawRequest(VIEWER_QUERY);

package/dist/commands/init/workspace.d.ts

@@ -5,7 +5,7 @@
  * Lets the user pick a default team, optional. Skip-by-default.
  */
 import type { WizardConfig } from "./shared.js";
-export interface WorkspaceStepResult {
+interface WorkspaceStepResult {
     workspaceUrlKey: string;
     defaultTeam: string | undefined;
     teams: Record<string, string>;
@@ -18,3 +18,4 @@ export interface WorkspaceStepResult {
  * the existing config exactly.
  */
 export declare function runWorkspaceStep(token: string, workspaceUrlKey: string, existing: WizardConfig): Promise<WorkspaceStepResult>;
+export {};

package/dist/commands/init/workspace.js

@@ -25,7 +25,7 @@ const TEAMS_QUERY = /* GraphQL */ `
  * the existing config exactly.
  */
 export async function runWorkspaceStep(token, workspaceUrlKey, existing) {
-    const service = new GraphQLService(token);
+    const service = new GraphQLService({ apiKey: token });
     // Fetch teams once so we can populate both the picker and the cached id map.
     const data = await service.rawRequest(TEAMS_QUERY);
     const teams = data?.teams?.nodes ?? [];

package/dist/commands/introspect.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `el-linear introspect` and `el-linear validate-flag` — expose the
+ * commander command tree so external linters (e.g. CI steps that scan
+ * SKILL.md files for `el-linear <cmd> --<flag>` references) can verify
+ * that hardcoded flag names actually exist on the current binary.
+ *
+ * Without this, a flag rename inside `el-linear` (say `--parent-ticket`
+ * → `--parent`) silently breaks every skill that prose-references the
+ * old name. Skills then fail at runtime, far from the rename commit.
+ *
+ * `introspect` dumps the full tree — name, description, version,
+ * options, aliases, and recursively nested subcommands.
+ *
+ * `validate-flag` is a thin ergonomic wrapper for the CI-lint use case:
+ *
+ *   $ el-linear validate-flag issues create --parent-ticket
+ *   { "ok": true, "command": ["issues", "create"], "flag": "--parent-ticket" }
+ *   $ el-linear validate-flag issues create --does-not-exist
+ *   { "ok": false, ... "error": "..." }   # exit code 1
+ *
+ * Both commands ignore root-level flags (`--api-token`, `--json`, etc.)
+ * when walking subcommand options; those are dumped at the root, not
+ * under every command. `validate-flag` walks ancestors so a global flag
+ * (e.g. `--format`) validates on any subcommand.
+ */
+import type { Command } from "commander";
+export declare function setupIntrospectCommand(program: Command): void;