@enrichlayer/el-linear 1.6.0 → 1.9.0

package/dist/config/config.js

@@ -22,23 +22,38 @@ const DEFAULT_CONFIG = {
     },
     terms: [],
 };
-let cachedConfig;
+// 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.
+//
+// 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. */
 export function _resetConfigCacheForTests() {
-    cachedConfig = undefined;
+    cachedConfigByProfile.clear();
 }
 export function loadConfig() {
-    if (cachedConfig) {
-        return cachedConfig;
-    }
     // 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);
+    if (cached) {
+        return cached;
+    }
     const candidates = [active.configPath];
     if (active.configPath !== CONFIG_PATH)
         candidates.push(CONFIG_PATH);
     const sourcePath = candidates.find((p) => fs.existsSync(p));
+    let resolved;
     if (sourcePath) {
         try {
             const userConfig = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
@@ -61,11 +76,11 @@ export function loadConfig() {
                 }
                 delete userConfig.brand;
             }
-            cachedConfig = deepMerge(DEFAULT_CONFIG, userConfig);
+            resolved = deepMerge(DEFAULT_CONFIG, userConfig);
         }
         catch {
             outputWarning(`Failed to parse ${sourcePath}, using empty defaults`);
-            cachedConfig = DEFAULT_CONFIG;
+            resolved = DEFAULT_CONFIG;
         }
     }
     else {
@@ -73,13 +88,20 @@ export function loadConfig() {
             ? ` (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;
+        resolved = DEFAULT_CONFIG;
     }
-    return cachedConfig;
+    cachedConfigByProfile.set(cacheKey, resolved);
+    return resolved;
 }
 function deepMerge(target, source) {
     const result = { ...target };
     for (const key of Object.keys(source)) {
+        // Reject prototype-pollution keys regardless of value shape: a
+        // hand-edited config.json with `__proto__` would otherwise mutate
+        // Object.prototype for the whole process.
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            continue;
+        }
         if (source[key] &&
             typeof source[key] === "object" &&
             !Array.isArray(source[key]) &&

package/dist/config/issue-validation.js

@@ -252,7 +252,7 @@ function checkTitleVerbAlignment(title, typeLabel, result) {
  */
 export function enforceValidation(result) {
     for (const warning of result.warnings) {
-        outputWarning(warning, "validation");
+        outputWarning(warning);
     }
     if (result.errors.length > 0) {
         const errorMsg = "Issue creation blocked by validation:\n\n" +

package/dist/config/paths.d.ts

@@ -6,6 +6,7 @@
 export declare const CONFIG_DIR: string;
 export declare const CONFIG_PATH: string;
 export declare const TOKEN_PATH: string;
+export declare const TEAM_OAUTH_CONFIG_PATH: string;
 export declare const ALIASES_PROGRESS_PATH: string;
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly
@@ -30,9 +31,20 @@ export interface ProfileFsOps {
     readFileSync: (p: string) => string;
     existsSync: (p: string) => boolean;
 }
+/**
+ * Conservative profile-name charset. Rejects path traversal (`..`, `/`),
+ * shell metacharacters, and Unicode lookalikes that would confuse `profile
+ * use` or let `--profile`/EL_LINEAR_PROFILE/active-profile escape out of
+ * <CONFIG_DIR>/profiles/.
+ */
+export declare function isSafeProfileName(name: 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.
+ *
+ * @throws when `name` is not a safe profile name. Validation lives here
+ * so every entry point (CLI flag, env var, marker file) goes through one
+ * gate — see `resolveActiveProfile`.
  */
 export declare function setActiveProfileForSession(name: string | null): void;
 /** Read-only accessor for the per-session override (test seam). */

package/dist/config/paths.js

@@ -9,6 +9,7 @@ import path from "node:path";
 export const CONFIG_DIR = path.join(os.homedir(), ".config", "el-linear");
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 export const TOKEN_PATH = path.join(CONFIG_DIR, "token");
+export const TEAM_OAUTH_CONFIG_PATH = path.join(CONFIG_DIR, "team-oauth.json");
 export const ALIASES_PROGRESS_PATH = path.join(CONFIG_DIR, ".init-aliases-progress");
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly
@@ -43,6 +44,15 @@ const DEFAULT_FS_OPS = {
     readFileSync: (p) => fs.readFileSync(p, "utf8"),
     existsSync: (p) => fs.existsSync(p),
 };
+/**
+ * Conservative profile-name charset. Rejects path traversal (`..`, `/`),
+ * shell metacharacters, and Unicode lookalikes that would confuse `profile
+ * use` or let `--profile`/EL_LINEAR_PROFILE/active-profile escape out of
+ * <CONFIG_DIR>/profiles/.
+ */
+export function isSafeProfileName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(name);
+}
 /**
  * Per-process override for the active profile name. Set by main.ts when
  * `--profile <name>` is passed (highest priority).
@@ -51,9 +61,25 @@ 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.
+ *
+ * @throws when `name` is not a safe profile name. Validation lives here
+ * so every entry point (CLI flag, env var, marker file) goes through one
+ * gate — see `resolveActiveProfile`.
  */
 export function setActiveProfileForSession(name) {
-    sessionProfileOverride = name && name.trim().length > 0 ? name.trim() : null;
+    if (name === null) {
+        sessionProfileOverride = null;
+        return;
+    }
+    const trimmed = name.trim();
+    if (trimmed.length === 0) {
+        sessionProfileOverride = null;
+        return;
+    }
+    if (!isSafeProfileName(trimmed)) {
+        throw new Error(`Invalid profile name "${trimmed}". Allowed: [A-Za-z0-9][A-Za-z0-9_.-]{0,63}.`);
+    }
+    sessionProfileOverride = trimmed;
 }
 /** Read-only accessor for the per-session override (test seam). */
 export function getSessionProfileOverride() {
@@ -65,11 +91,24 @@ export function getSessionProfileOverride() {
  * 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);
+    // session override is already validated at write time (see
+    // setActiveProfileForSession). Env var is explicit user input and
+    // must fail loudly. Marker file is our own on-disk state; treat
+    // invalid contents as "no marker" so a stale/corrupt file doesn't
+    // brick every command.
+    if (sessionProfileOverride) {
+        return profilePaths(sessionProfileOverride);
+    }
+    const envName = env.EL_LINEAR_PROFILE?.trim();
+    if (envName) {
+        if (!isSafeProfileName(envName)) {
+            throw new Error(`Invalid EL_LINEAR_PROFILE value "${envName}". Allowed: [A-Za-z0-9][A-Za-z0-9_.-]{0,63}.`);
+        }
+        return profilePaths(envName);
+    }
+    const marker = readActiveProfileMarker(fsImpl);
+    if (marker && isSafeProfileName(marker)) {
+        return profilePaths(marker);
     }
     return {
         name: null,

package/dist/config/term-enforcer.js

@@ -62,7 +62,7 @@ export function enforceTerms(texts, options = {}) {
     if (options.strict) {
         throw new Error(`Term enforcement failed:\n${warnings.map((w) => `  - ${w}`).join("\n")}`);
     }
-    outputWarning(warnings, "term_enforcement");
+    outputWarning(warnings);
 }
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/dist/main.js

@@ -24,19 +24,21 @@ 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 { setFieldsFilter, setJqFilter, setOutputFormat, 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.6.0")
+    .version("1.8.1")
     .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("--format <kind>", "output format: json (default, structured envelope) or summary (human-readable)", "json")
     .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly")
     .option("--jq <filter>", "apply a jq filter to the JSON output")
-    .option("--fields <fields>", "filter output to specific fields (comma-separated)");
+    .option("--fields <fields>", "filter output to specific fields (comma-separated)")
+    .option("--no-cache", "bypass the on-disk cache for `teams list` / `labels list` / `projects list`");
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const rootOpts = actionCommand.optsWithGlobals();
     if (rootOpts.raw) {
@@ -48,6 +50,40 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
     if (rootOpts.fields) {
         setFieldsFilter(splitList(rootOpts.fields));
     }
+    // Subcommand --format wins over the global flag (commander resolves
+    // options closest to the action), so `optsWithGlobals` returns the
+    // subcommand value when one is set. We accept any of the per-command
+    // formats (table/md/csv) silently — those take a different code path
+    // inside the handler and never reach outputSuccess. The global
+    // behavior only triggers for `summary`.
+    const fmt = typeof rootOpts.format === "string"
+        ? rootOpts.format.toLowerCase()
+        : "json";
+    if (fmt === "summary") {
+        setOutputFormat("summary");
+    }
+    else if (fmt === "json") {
+        setOutputFormat("json");
+    }
+    else if (fmt === "table" ||
+        fmt === "md" ||
+        fmt === "markdown" ||
+        fmt === "csv") {
+        // Per-subcommand format: no global state change. The subcommand
+        // owns its own output path.
+        setOutputFormat("json");
+    }
+    else {
+        // Match outputSuccess's stable JSON-on-stdout shape so machine
+        // callers always get a parseable error envelope on stdout. We
+        // can't route through handleAsyncCommand here — preAction runs
+        // before the action handler.
+        const msg = `Unknown --format: "${rootOpts.format}". Use one of: json, summary` +
+            " (per-command formats table/md/csv are also accepted on issues" +
+            " list/search and projects list).";
+        process.stdout.write(`${JSON.stringify({ error: msg }, null, 2)}\n`);
+        process.exit(1);
+    }
     // `--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

package/dist/queries/templates.d.ts

@@ -1,2 +1,5 @@
 export declare const TEMPLATES_LIST_QUERY = "\n  query {\n    templates {\n      id\n      name\n      type\n      description\n      templateData\n      createdAt\n      updatedAt\n      team { id key name }\n      creator { id name }\n    }\n  }\n";
 export declare const TEMPLATE_BY_ID_QUERY = "\n  query ($id: String!) {\n    template(id: $id) {\n      id\n      name\n      type\n      description\n      templateData\n      createdAt\n      updatedAt\n      team { id key name }\n      creator { id name }\n    }\n  }\n";
+export declare const TEMPLATE_CREATE_MUTATION = "\n  mutation ($input: TemplateCreateInput!) {\n    templateCreate(input: $input) {\n      success\n      lastSyncId\n      template {\n        id\n        name\n        type\n        description\n        templateData\n        team { id key name }\n        createdAt\n        updatedAt\n      }\n    }\n  }\n";
+export declare const TEMPLATE_UPDATE_MUTATION = "\n  mutation ($id: String!, $input: TemplateUpdateInput!) {\n    templateUpdate(id: $id, input: $input) {\n      success\n      lastSyncId\n      template {\n        id\n        name\n        type\n        description\n        templateData\n        team { id key name }\n        updatedAt\n      }\n    }\n  }\n";
+export declare const TEMPLATE_DELETE_MUTATION = "\n  mutation ($id: String!) {\n    templateDelete(id: $id) {\n      success\n      lastSyncId\n    }\n  }\n";

package/dist/queries/templates.js

@@ -28,3 +28,46 @@ export const TEMPLATE_BY_ID_QUERY = `
     }
   }
 `;
+export const TEMPLATE_CREATE_MUTATION = `
+  mutation ($input: TemplateCreateInput!) {
+    templateCreate(input: $input) {
+      success
+      lastSyncId
+      template {
+        id
+        name
+        type
+        description
+        templateData
+        team { id key name }
+        createdAt
+        updatedAt
+      }
+    }
+  }
+`;
+export const TEMPLATE_UPDATE_MUTATION = `
+  mutation ($id: String!, $input: TemplateUpdateInput!) {
+    templateUpdate(id: $id, input: $input) {
+      success
+      lastSyncId
+      template {
+        id
+        name
+        type
+        description
+        templateData
+        team { id key name }
+        updatedAt
+      }
+    }
+  }
+`;
+export const TEMPLATE_DELETE_MUTATION = `
+  mutation ($id: String!) {
+    templateDelete(id: $id) {
+      success
+      lastSyncId
+    }
+  }
+`;

package/dist/utils/auth.js

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import { LEGACY_LINCTL_TOKEN_PATH, LEGACY_TOKEN_PATH, resolveActiveProfile, TOKEN_PATH, } from "../config/paths.js";
+import { LEGACY_LINCTL_TOKEN_PATH, LEGACY_TOKEN_PATH, resolveActiveProfile, } from "../config/paths.js";
 import { maybeEmitMigrationHint } from "./migration-hint.js";
 export function getApiToken(options) {
     if (options.apiToken) {
@@ -9,18 +9,16 @@ export function getApiToken(options) {
         return process.env.LINEAR_API_TOKEN;
     }
     // 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.
+    // profile is active. When the user has explicitly selected a profile
+    // (--profile / EL_LINEAR_PROFILE / active-profile marker), do NOT
+    // fall back to the legacy single-file token — that path silently
+    // posts writes to the wrong workspace when a profile token is missing.
     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();
+    if (active.name !== null) {
+        throw new Error(`No token for active profile \`${active.name}\` (expected at ${active.tokenPath}). Run \`el-linear init token --profile ${active.name}\` (or unset --profile / EL_LINEAR_PROFILE / \`el-linear profile use <name>\`) before retrying. Refusing to fall back to the legacy single-file token to avoid posting writes to the wrong workspace.`);
     }
     // Fallback to the linctl-era token (the CLI was briefly published as
     // `@enrichlayer/linctl` then reverted). Kept for one release.

package/dist/utils/auto-link-references.js

@@ -155,7 +155,21 @@ export async function autoLinkReferences(input) {
     const failed = [];
     const descriptionRefs = extractIssueReferences(description ?? "", identifier);
     const commentRefs = (comments ?? []).flatMap((body) => extractIssueReferences(body, identifier));
-    const candidates = mergeCandidates(descriptionRefs, commentRefs);
+    const merged = mergeCandidates(descriptionRefs, commentRefs);
+    // Cap the number of candidates we'll resolve per call. A malicious
+    // (or merely careless) issue body containing hundreds of fake
+    // identifiers — `AAA-1, AAA-2, …, AAA-999` — would otherwise trigger
+    // 999 GraphQL roundtrips before deciding none resolve. Realistic
+    // human-authored bodies stay well under this cap.
+    const MAX_CANDIDATES_PER_CALL = 50;
+    const candidates = merged.slice(0, MAX_CANDIDATES_PER_CALL);
+    if (merged.length > MAX_CANDIDATES_PER_CALL) {
+        const overflow = merged.length - MAX_CANDIDATES_PER_CALL;
+        failed.push({
+            identifier: `+${overflow} more`,
+            reason: `Too many candidate references (${merged.length}); only the first ${MAX_CANDIDATES_PER_CALL} are processed.`,
+        });
+    }
     if (candidates.length === 0) {
         return { linked, skipped, failed };
     }

package/dist/utils/disk-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+export interface CacheOptions {
+    /** When true, skip the read step and always refetch + rewrite. */
+    bypass?: boolean;
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export declare function cached<T>(key: string, ttlSeconds: number, fetcher: () => Promise<T>, options?: CacheOptions): Promise<T>;
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export declare function clearCache(prefix?: string): Promise<void>;
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export declare function resolveCacheTTL(args: {
+    configTTL: number | undefined;
+    noCacheFlag: boolean | undefined;
+}): number;

package/dist/utils/disk-cache.js

@@ -0,0 +1,179 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveActiveProfile } from "../config/paths.js";
+import { logger } from "./logger.js";
+const CACHE_VERSION = 1;
+const CACHE_FILE_MODE = 0o644;
+const CACHE_DIR_MODE = 0o700;
+/**
+ * Resolve `<profile-dir>/cache/`. Profile-aware so caches don't bleed
+ * across profiles. The directory of the active profile's `configPath` is
+ * the canonical "profile dir" — this matches what `commands/init/shared.ts`
+ * uses.
+ */
+function cacheDir() {
+    const active = resolveActiveProfile();
+    return path.join(path.dirname(active.configPath), "cache");
+}
+function cachePath(key) {
+    return path.join(cacheDir(), `${sanitizeKey(key)}.json`);
+}
+/**
+ * Cache keys may include filter values like `team:ENG` or `status:active`,
+ * which are POSIX-safe but we still strip path separators defensively so a
+ * malicious or buggy caller can't write outside the cache directory.
+ */
+function sanitizeKey(key) {
+    return key.replace(/[/\\\0]/g, "_");
+}
+/**
+ * Atomic write: write to a sibling tmp file then rename. Mirrors the helper
+ * in `commands/init/shared.ts` and `auth/oauth-fs.ts`. Duplicated (12 lines)
+ * to keep the dependency graph clean — the wizard depends on cache callers
+ * indirectly, so importing wizard internals here would be a cycle hazard.
+ */
+async function atomicWrite(targetPath, data) {
+    const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+    try {
+        await fs.writeFile(tmpPath, data, {
+            encoding: "utf8",
+            mode: CACHE_FILE_MODE,
+        });
+        await fs.chmod(tmpPath, CACHE_FILE_MODE);
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+async function readEnvelope(key) {
+    let raw;
+    try {
+        raw = await fs.readFile(cachePath(key), "utf8");
+    }
+    catch {
+        // Missing dir, missing file, permission errors → treat as cache miss.
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Reject envelopes from a future cache version we don't understand.
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.v !== CACHE_VERSION ||
+            typeof parsed.expiresAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        // Corrupt JSON → treat as cache miss.
+        return null;
+    }
+}
+async function writeEnvelope(key, envelope) {
+    const dir = cacheDir();
+    await fs.mkdir(dir, { recursive: true, mode: CACHE_DIR_MODE });
+    await atomicWrite(cachePath(key), JSON.stringify(envelope));
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export async function cached(key, ttlSeconds, fetcher, options) {
+    // TTL = 0 disables caching: never read, never write.
+    if (ttlSeconds <= 0) {
+        return fetcher();
+    }
+    const now = Date.now();
+    if (!options?.bypass) {
+        const envelope = await readEnvelope(key);
+        if (envelope && envelope.expiresAt > now) {
+            return envelope.data;
+        }
+    }
+    const data = await fetcher();
+    const envelope = {
+        v: CACHE_VERSION,
+        key,
+        fetchedAt: now,
+        expiresAt: now + ttlSeconds * 1000,
+        data,
+    };
+    try {
+        await writeEnvelope(key, envelope);
+    }
+    catch (err) {
+        // Cache writes are best-effort — log to stderr and return the data
+        // anyway so a flaky disk doesn't break the user's command.
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[disk-cache] write failed for "${key}": ${msg}`);
+    }
+    return data;
+}
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export async function clearCache(prefix) {
+    const dir = cacheDir();
+    if (!prefix) {
+        await fs.rm(dir, { recursive: true, force: true });
+        return;
+    }
+    const sanitized = sanitizeKey(prefix);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries
+        .filter((name) => name.endsWith(".json") && name.startsWith(sanitized))
+        .map((name) => fs.unlink(path.join(dir, name)).catch(() => { })));
+}
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export function resolveCacheTTL(args) {
+    if (args.noCacheFlag) {
+        return 0;
+    }
+    if (args.configTTL === undefined) {
+        return 3600;
+    }
+    return args.configTTL;
+}