@enrichlayer/el-linear 1.10.0 → 1.16.0

package/dist/config/config.js

@@ -1,6 +1,44 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { outputWarning } from "../utils/output.js";
-import { CONFIG_PATH, resolveActiveProfile } from "./paths.js";
+import { CONFIG_PATH, LOCAL_CONFIG_PATH, resolveActiveProfile, } from "./paths.js";
+/**
+ * Marker file written by the EL onboarding flow (`link-project.sh`) when a
+ * developer wires the tools repo to their machine. We treat its presence as
+ * the consent signal for auto-discovering the team config — see
+ * `discoverTeamConfigViaMarker` and DEV-4258.
+ *
+ * `os.homedir()` is evaluated lazily inside the helper so a mocked HOME in
+ * tests doesn't get baked into a module-level constant.
+ */
+function elToolsRootMarkerPath() {
+    return path.join(os.homedir(), ".config", "el-tools-root");
+}
+/**
+ * Resolve the shared team config path by reading the `~/.config/el-tools-root`
+ * marker file written by the EL onboarding flow (`link-project.sh`). Looks for
+ * `<root>/config/el-linear.shared.json` and returns the absolute path when it
+ * exists. Returns `undefined` for any of: marker missing, marker unreadable,
+ * marker empty, shared file missing — every failure mode is silent because
+ * the marker is opt-in and a non-EL user (OSS audience) is expected to miss
+ * it.
+ *
+ * The marker is the consent signal: only developers who explicitly linked
+ * their tools repo see this auto-discovery. DEV-4258 / ALL-964.
+ */
+function discoverTeamConfigViaMarker() {
+    try {
+        const root = fs.readFileSync(elToolsRootMarkerPath(), "utf8").trim();
+        if (!root)
+            return undefined;
+        const shared = path.join(root, "config", "el-linear.shared.json");
+        return fs.existsSync(shared) ? shared : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const DEFAULT_CONFIG = {
     defaultTeam: "",
     defaultLabels: [],
@@ -22,77 +60,245 @@ const DEFAULT_CONFIG = {
     },
     terms: [],
 };
-// Profile-keyed cache. Pre-fix this was a single `cachedConfig` —
-// switching the active profile mid-process and calling `loadConfig`
-// again would return the OLD profile's config until
-// `_resetConfigCacheForTests` ran. Today the CLI sets the profile
-// in `preAction` before any command body, so this is latent — but
-// keying by profile makes it future-proof and makes test isolation
-// less footgun-prone (profile A's setup pollutes profile B's read).
-// ALL-935 deferred fix.
+// Two-level cache to avoid re-reading personal config on every loadConfig() call.
+//
+// Level 1 — team config path resolution:
+//   Key: `"${profileKey}::${envPath}"` (both "" when absent)
+//   Value: the resolved team config path, or undefined if none is configured.
+//   Populated on the first loadConfig() call for a (profile, env) combination.
+//   On subsequent calls the cache hit lets us skip reading personal config and
+//   go straight to the merged-config cache.
+//
+// Level 2 — merged result (team + personal):
+//   Key: `"${profileKey}::${teamConfigPath}"`
+//   Value: the fully merged ElLinearConfig (before local.json overlay).
 //
-// Key: `null` for the legacy single-file layout (no active profile),
-// otherwise the profile name. We never mix the two paths in the
-// cache — the marker name selects exactly one path.
-const cachedConfigByProfile = new Map();
-/** Test seam — resets the cache between test cases. */
+// Level 3 — local config:
+//   Key: profile name (null for legacy single-file layout).
+//   Value: the parsed ElLinearLocalConfig from local.json.
+//
+// ALL-935 deferred fix note: profile switching mid-process is covered because
+// the profile name is part of all cache keys.
+const cachedTeamConfigPath = new Map();
+const cachedConfig = new Map();
+const cachedLocalConfigByProfile = new Map();
+/** Test seam — resets all caches between test cases. */
 export function _resetConfigCacheForTests() {
-    cachedConfigByProfile.clear();
+    cachedTeamConfigPath.clear();
+    cachedConfig.clear();
+    cachedLocalConfigByProfile.clear();
 }
 export function loadConfig() {
-    // 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 cacheKey = active.name;
-    const cached = cachedConfigByProfile.get(cacheKey);
+    const teamConfigEnvPath = process.env.EL_LINEAR_TEAM_CONFIG?.trim() || undefined;
+    const profileKey = active.name ?? "";
+    const pathCacheKey = `${profileKey}::${teamConfigEnvPath ?? ""}`;
+    // Fast path: if we already know the team config path for this
+    // (profile, env) combination, skip reading personal config.
+    let teamConfigPath;
+    let personalRaw;
+    if (cachedTeamConfigPath.has(pathCacheKey)) {
+        teamConfigPath = cachedTeamConfigPath.get(pathCacheKey);
+    }
+    else if (teamConfigEnvPath !== undefined) {
+        // Env var fully determines the path — no need to read personal config.
+        teamConfigPath = teamConfigEnvPath;
+        cachedTeamConfigPath.set(pathCacheKey, teamConfigPath);
+    }
+    else {
+        // First time for this profile without an env var: read personal config
+        // to find teamConfigPath, then fall back to the EL onboarding marker
+        // (`~/.config/el-tools-root` → `<root>/config/el-linear.shared.json`).
+        // The marker is the opt-in consent signal — only developers who ran
+        // `link-project.sh` get the auto-discovery; OSS users hit the silent
+        // no-op path. DEV-4258 / ALL-964.
+        personalRaw = readRawPersonalConfig(active);
+        teamConfigPath = personalRaw.teamConfigPath;
+        if (teamConfigPath === undefined) {
+            teamConfigPath = discoverTeamConfigViaMarker();
+        }
+        cachedTeamConfigPath.set(pathCacheKey, teamConfigPath);
+    }
+    const cacheKey = `${profileKey}::${teamConfigPath ?? ""}`;
+    const cached = cachedConfig.get(cacheKey);
     if (cached) {
+        // Apply local config on top of cached merged result.
+        return applyLocalConfig(cached, loadLocalConfig());
+    }
+    // Cache miss — do the full merge. Reuse personalRaw if we already read it.
+    if (!personalRaw) {
+        personalRaw = readRawPersonalConfig(active);
+    }
+    // Load the team config layer (errors are warned, never thrown).
+    const teamRaw = teamConfigPath
+        ? loadTeamConfigRaw(teamConfigPath)
+        : {};
+    // teamConfigPath inside a team config file would be circular; strip it.
+    delete teamRaw.teamConfigPath;
+    // Merge order: defaults → team config → personal config.
+    // Arrays (terms, defaultLabels, etc.) are concatenated so personal entries
+    // extend team entries rather than replace them.
+    const afterTeam = deepMerge(DEFAULT_CONFIG, teamRaw);
+    const merged = deepMerge(afterTeam, personalRaw);
+    cachedConfig.set(cacheKey, merged);
+    // Overlay local.json on top — highest priority layer.
+    return applyLocalConfig(merged, loadLocalConfig());
+}
+/**
+ * Returns the team config file path that is active for the current process
+ * (resolved via `EL_LINEAR_TEAM_CONFIG` env var, `teamConfigPath` in personal
+ * config, or `~/.config/el-tools-root` marker — in that order). Returns
+ * `undefined` when no team config is configured.
+ *
+ * Calling this before `loadConfig()` will trigger a `loadConfig()` internally
+ * so the path cache is populated.
+ */
+export function getActiveTeamConfigPath() {
+    const active = resolveActiveProfile();
+    const teamConfigEnvPath = process.env.EL_LINEAR_TEAM_CONFIG?.trim() || undefined;
+    const profileKey = active.name ?? "";
+    const pathCacheKey = `${profileKey}::${teamConfigEnvPath ?? ""}`;
+    if (!cachedTeamConfigPath.has(pathCacheKey)) {
+        loadConfig();
+    }
+    return cachedTeamConfigPath.get(pathCacheKey);
+}
+/**
+ * Returns the active team-config path AND the source it was resolved from
+ * (env var / personal config field / onboarding-marker auto-discovery).
+ * `el-linear config team show` uses this to render which resolver fired —
+ * so an operator debugging "why isn't my team config loading?" sees the
+ * answer in one command.
+ *
+ * Re-derives source on each call rather than caching it: the lookup is cheap
+ * (one file read at most for personal config, one for the marker) and only
+ * `config team show` calls it.
+ */
+export function getActiveTeamConfigInfo() {
+    const envPath = process.env.EL_LINEAR_TEAM_CONFIG?.trim() || undefined;
+    if (envPath !== undefined) {
+        return { path: envPath, source: "env" };
+    }
+    const personalRaw = readRawPersonalConfig(resolveActiveProfile());
+    const personalPath = personalRaw.teamConfigPath;
+    if (personalPath !== undefined && personalPath !== "") {
+        return { path: personalPath, source: "personal" };
+    }
+    const markerPath = discoverTeamConfigViaMarker();
+    if (markerPath !== undefined) {
+        return { path: markerPath, source: "marker" };
+    }
+    return { path: undefined, source: null };
+}
+/**
+ * Load user-local overrides from `local.json`. Returns an empty object when
+ * no file exists — callers treat it as "no overrides". Errors are silent so
+ * a missing or malformed `local.json` never breaks a command.
+ */
+export function loadLocalConfig() {
+    const active = resolveActiveProfile();
+    const cacheKey = active.name;
+    const cached = cachedLocalConfigByProfile.get(cacheKey);
+    if (cached !== undefined) {
         return cached;
     }
-    const candidates = [active.configPath];
-    if (active.configPath !== CONFIG_PATH)
-        candidates.push(CONFIG_PATH);
+    const candidates = [active.localConfigPath];
+    if (active.localConfigPath !== LOCAL_CONFIG_PATH)
+        candidates.push(LOCAL_CONFIG_PATH);
     const sourcePath = candidates.find((p) => fs.existsSync(p));
-    let resolved;
+    let local = {};
     if (sourcePath) {
         try {
-            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.
-            if (userConfig.brand &&
-                typeof userConfig.brand === "object" &&
-                !Array.isArray(userConfig.brand)) {
-                const legacy = userConfig.brand;
-                if (typeof legacy.name === "string" && Array.isArray(legacy.reject)) {
-                    outputWarning("config.brand is deprecated — replace it with config.terms = [{ canonical, reject }]. See README#term-enforcer.");
-                    const existing = Array.isArray(userConfig.terms)
-                        ? userConfig.terms
-                        : [];
-                    userConfig.terms = [
-                        ...existing,
-                        { canonical: legacy.name, reject: legacy.reject },
-                    ];
-                }
-                delete userConfig.brand;
-            }
-            resolved = deepMerge(DEFAULT_CONFIG, userConfig);
+            local = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
         }
         catch {
-            outputWarning(`Failed to parse ${sourcePath}, using empty defaults`);
-            resolved = DEFAULT_CONFIG;
+            outputWarning(`Failed to parse ${sourcePath}, ignoring local config`);
         }
     }
-    else {
+    cachedLocalConfigByProfile.set(cacheKey, local);
+    return local;
+}
+/**
+ * Merge local config overrides onto the merged team+personal config.
+ * `assigneeEmail` maps to `defaultAssignee` as a convenience alias.
+ */
+function applyLocalConfig(base, local) {
+    const hasApplicable = local.cacheTTLSeconds !== undefined ||
+        local.defaultPriority !== undefined ||
+        local.defaultAssignee !== undefined ||
+        local.assigneeEmail !== undefined;
+    if (!hasApplicable)
+        return base;
+    const result = { ...base };
+    if (local.cacheTTLSeconds !== undefined)
+        result.cacheTTLSeconds = local.cacheTTLSeconds;
+    if (local.defaultPriority !== undefined)
+        result.defaultPriority = local.defaultPriority;
+    if (local.defaultAssignee !== undefined) {
+        result.defaultAssignee = local.defaultAssignee;
+    }
+    else if (local.assigneeEmail !== undefined) {
+        result.defaultAssignee = local.assigneeEmail;
+    }
+    return result;
+}
+function readRawPersonalConfig(active) {
+    const candidates = [active.configPath];
+    if (active.configPath !== CONFIG_PATH)
+        candidates.push(CONFIG_PATH);
+    const sourcePath = candidates.find((p) => fs.existsSync(p));
+    if (!sourcePath) {
         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.`);
-        resolved = DEFAULT_CONFIG;
+        return {};
+    }
+    try {
+        const raw = 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.
+        if (raw.brand &&
+            typeof raw.brand === "object" &&
+            !Array.isArray(raw.brand)) {
+            const legacy = raw.brand;
+            if (typeof legacy.name === "string" && Array.isArray(legacy.reject)) {
+                outputWarning("config.brand is deprecated — replace it with config.terms = [{ canonical, reject }]. See README#term-enforcer.");
+                const existing = Array.isArray(raw.terms) ? raw.terms : [];
+                raw.terms = [
+                    ...existing,
+                    { canonical: legacy.name, reject: legacy.reject },
+                ];
+            }
+            delete raw.brand;
+        }
+        return raw;
+    }
+    catch {
+        outputWarning(`Failed to parse ${sourcePath}, using empty defaults`);
+        return {};
+    }
+}
+function loadTeamConfigRaw(teamConfigPath) {
+    if (!fs.existsSync(teamConfigPath)) {
+        outputWarning(`Team config not found at ${teamConfigPath} — skipping team config layer.`);
+        return {};
+    }
+    try {
+        return JSON.parse(fs.readFileSync(teamConfigPath, "utf8"));
+    }
+    catch {
+        outputWarning(`Failed to parse team config at ${teamConfigPath} — skipping team config layer.`);
+        return {};
     }
-    cachedConfigByProfile.set(cacheKey, resolved);
-    return resolved;
 }
+/**
+ * Deep-merge `source` into `target`. Objects are merged recursively; arrays
+ * are concatenated (target first, source appended) so that a team config's
+ * `terms` and `defaultLabels` are extended by personal config rather than
+ * replaced. Scalar values from `source` win over `target`.
+ */
 function deepMerge(target, source) {
     const result = { ...target };
     for (const key of Object.keys(source)) {
@@ -102,7 +308,13 @@ function deepMerge(target, source) {
         if (key === "__proto__" || key === "constructor" || key === "prototype") {
             continue;
         }
-        if (source[key] &&
+        if (Array.isArray(source[key]) && Array.isArray(target[key])) {
+            result[key] = [
+                ...target[key],
+                ...source[key],
+            ];
+        }
+        else if (source[key] &&
             typeof source[key] === "object" &&
             !Array.isArray(source[key]) &&
             target[key] &&

package/dist/config/error-enrichment.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Validation error enrichment.
+ *
+ * When `validateIssueCreation` flags a missing required field AND `--team`
+ * is set, this module fetches concrete team-scoped suggestions (active
+ * projects, active members, valid labels) and appends a "Suggestions:" block
+ * to each relevant error message.
+ *
+ * Goal: reduce the agent's loop time. A single error should carry enough
+ * concrete options that the agent can rebuild a complete retry command
+ * without follow-up `projects list` / `users list` / `labels list` calls.
+ *
+ * Latency budget: enrichment only runs on the validation-fail path. The
+ * success path is unchanged. Fetches run in parallel and only for the fields
+ * that are actually missing.
+ */
+import type { GraphQLService } from "../utils/graphql-service.js";
+import type { LinearService } from "../utils/linear-service.js";
+import { type ValidationResult } from "./issue-validation.js";
+interface EnrichOptions {
+    team?: string;
+    title?: string;
+}
+/**
+ * Enrich validation errors with team-scoped suggestions.
+ *
+ * Mutates `result.errors` in place — each enrichable error gets a
+ * "Suggestions:" block appended. Verb→type inference is added as a prefixed
+ * "Inferred from title:" line on the `--labels` missing error.
+ *
+ * No-op when `--team` is not set or when there are no errors to enrich.
+ * Safe to call on the failure path only — never invoked when validation
+ * passes, so the success path's latency is unchanged.
+ *
+ * Failures (network, unknown team) are swallowed: enrichment is a best-effort
+ * UX hint, not part of the validation contract.
+ */
+export declare function enrichValidationErrors(result: ValidationResult, options: EnrichOptions, services: {
+    graphQLService: GraphQLService;
+    linearService: LinearService;
+}): Promise<void>;
+/**
+ * Enrich a project resolver failure ({@link PROJECT_NOT_FOUND_PATTERN})
+ * with the same team-scoped suggestions that {@link enrichValidationErrors}
+ * appends to `Missing --project` validation errors. Returns the original
+ * message unchanged if the error doesn't match or `--team` is unknown.
+ *
+ * The validation path covers "user forgot `--project`"; this path covers
+ * "user pasted a URL/slug/name that didn't resolve" — same recovery hints
+ * apply in both cases. Synthesizes a `Missing --project: …` error string
+ * so the existing classifier and suggestion code can be reused without
+ * special-casing the resolver shape.
+ *
+ * Best-effort like `enrichValidationErrors`: any failure (network, unknown
+ * team, GraphQL error) returns the original message unchanged. The caller
+ * is expected to rethrow with the returned message.
+ */
+export declare function enrichProjectResolverError(originalMessage: string, options: EnrichOptions, services: {
+    graphQLService: GraphQLService;
+    linearService: LinearService;
+}): Promise<string>;
+export {};