linear-sdk-cli 0.5.3 → 0.7.0

package/src/commands/changelog.ts

@@ -0,0 +1,108 @@
+/** Show release notes from the CHANGELOG.md bundled with the CLI package. */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { CliError } from "../lib/errors.js";
+import type { Context } from "../context.js";
+
+export interface ChangelogSection {
+  title: string;
+  items: string[];
+}
+
+export interface ChangelogRelease {
+  version: string;
+  date: string;
+  url: string;
+  sections: ChangelogSection[];
+}
+
+const CHANGELOG_PATH = fileURLToPath(new URL("../../CHANGELOG.md", import.meta.url));
+const DEFAULT_RELEASE_COUNT = 3;
+
+/** Parse the Release Please Markdown format into a stable machine-readable shape. */
+export function parseChangelog(markdown: string): ChangelogRelease[] {
+  const releases: ChangelogRelease[] = [];
+  const releasePattern = /^## \[([^\]]+)]\(([^)]+)\) \((\d{4}-\d{2}-\d{2})\)\s*$/gm;
+  const matches = [...markdown.matchAll(releasePattern)];
+
+  for (const [index, match] of matches.entries()) {
+    const bodyStart = (match.index ?? 0) + match[0].length;
+    const bodyEnd = matches[index + 1]?.index ?? markdown.length;
+    const body = markdown.slice(bodyStart, bodyEnd);
+    const sections: ChangelogSection[] = [];
+    const sectionPattern = /^### (.+)\s*$/gm;
+    const sectionMatches = [...body.matchAll(sectionPattern)];
+
+    for (const [sectionIndex, sectionMatch] of sectionMatches.entries()) {
+      const itemsStart = (sectionMatch.index ?? 0) + sectionMatch[0].length;
+      const itemsEnd = sectionMatches[sectionIndex + 1]?.index ?? body.length;
+      const itemsBody = body.slice(itemsStart, itemsEnd).trim();
+      const items = itemsBody
+        .split(/\n(?=- )/)
+        .map((item) => item.replace(/^- /, "").replace(/\n\s+/g, " ").trim())
+        .filter(Boolean);
+      sections.push({ title: sectionMatch[1]!.trim(), items });
+    }
+
+    releases.push({
+      version: match[1]!,
+      url: match[2]!,
+      date: match[3]!,
+      sections,
+    });
+  }
+
+  return releases;
+}
+
+export function registerChangelog(program: Command): void {
+  program
+    .command("changelog")
+    .description("Show recent CLI release notes")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear changelog                 # latest three releases",
+        "  linear changelog --limit 1       # latest release only",
+        "  linear changelog --all           # complete bundled history",
+        "  linear changelog --json          # structured release notes",
+      ].join("\n"),
+    )
+    .action(action(runChangelog));
+}
+
+export function runChangelog(ctx: Context): void {
+  let markdown: string;
+  try {
+    markdown = readFileSync(CHANGELOG_PATH, "utf8");
+  } catch (error) {
+    throw new CliError(`Cannot read the bundled changelog: ${(error as Error).message}`, "runtime");
+  }
+
+  const releases = parseChangelog(markdown);
+  const count =
+    ctx.options.all || ctx.options.limit === 0
+      ? releases.length
+      : (ctx.options.limit ?? DEFAULT_RELEASE_COUNT);
+  const recent = releases.slice(0, count);
+
+  ctx.output.emit(recent, () => {
+    const rendered = recent
+      .map((release) => {
+        const sections = release.sections
+          .map(
+            (section) =>
+              `### ${section.title}\n\n${section.items.map((item) => `- ${item}`).join("\n")}`,
+          )
+          .join("\n\n");
+        return `## [${release.version}](${release.url}) (${release.date})\n\n${sections}`;
+      })
+      .join("\n\n");
+    ctx.output.markdown(rendered);
+  });
+}

package/src/commands/meta.ts

@@ -38,6 +38,10 @@ import { resolveTeam } from "../lib/resolve.js";
 import { ISSUE_SORTS } from "../services/issue.js";
 import { firstTeam, type Context } from "../context.js";
 import { openUrl } from "../lib/open.js";
+import {
+  authorizationCapabilities,
+  credentialType as resolvedCredentialType,
+} from "../lib/authorization.js";
 import {
   DEFAULT_OAUTH_SCOPES,
   buildAuthorizationUrl,
@@ -59,6 +63,7 @@ export const DEFAULT_OAUTH_CLIENT_ID = "eda60862e4bb8b8af82cfb3193b65c2f";
 const whoamiAction = action(async (ctx: Context) => {
   const me = await withRetry(() => ctx.client.viewer);
   const org = await withRetry(() => ctx.client.organization);
+  const authorization = authorizationCapabilities(ctx.config);
   ctx.output.detail(
     {
       id: me.id,
@@ -66,13 +71,17 @@ const whoamiAction = action(async (ctx: Context) => {
       displayName: me.displayName,
       email: me.email,
       admin: me.admin,
+      authorization,
       organization: { id: org.id, name: org.name, urlKey: org.urlKey },
     },
     [
       ["Name", me.name],
       ["Display name", me.displayName],
       ["Email", me.email],
-      ["Admin", me.admin],
+      ["Workspace admin", me.admin],
+      ["Credential type", authorization.credentialType ?? "(none)"],
+      ["Credential scopes", authorization.scopes?.join(", ") ?? "unknown"],
+      ["Credential admin scope", authorization.adminScope ?? "unknown"],
       ["User ID", me.id],
       ["Organization", `${org.name} (${org.urlKey})`],
     ],
@@ -481,13 +490,8 @@ export function registerMeta(program: Command): void {
         const c = ctx.config;
         if (c.workspaceChoices) throw c.apiKeyError;
         const credential = c.accessToken ?? c.apiKey;
-        const credentialType = c.oauthCredential
-          ? "oauth-user"
-          : c.accessToken
-            ? "oauth-access-token"
-            : c.apiKey
-              ? "api-key"
-              : null;
+        const credentialType = resolvedCredentialType(c);
+        const authorization = authorizationCapabilities(c);
         const source = c.accessToken ? c.accessTokenSource : c.apiKeySource;
         const backend = keyring();
         ctx.output.detail(
@@ -502,6 +506,9 @@ export function registerMeta(program: Command): void {
             expiresAt: c.oauthCredential
               ? new Date(c.oauthCredential.expiresAt).toISOString()
               : null,
+            scopeVisibility: authorization.scopeVisibility,
+            adminScope: authorization.adminScope,
+            scopeNote: authorization.note,
           },
           [
             ["Authenticated", !!credential],
@@ -511,6 +518,9 @@ export function registerMeta(program: Command): void {
             ["Credential", redactKey(credential)],
             ["Keyring", backend ? backend.label : "(none on this platform)"],
             ["Scopes", c.oauthCredential?.scopes.join(", ")],
+            ["Scope visibility", authorization.scopeVisibility],
+            ["Admin scope", authorization.adminScope ?? "unknown"],
+            ["Scope note", authorization.note],
             [
               "Expires",
               c.oauthCredential ? new Date(c.oauthCredential.expiresAt).toISOString() : undefined,

package/src/commands/project-label.ts

@@ -0,0 +1,144 @@
+/** `linear project-label` — manage labels that apply to projects, not issues. */
+
+import { Command } from "commander";
+import type { Context } from "../context.js";
+import { action } from "../lib/action.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import type { Column } from "../output/table.js";
+import * as svc from "../services/project-label.js";
+
+const COLUMNS: Column<svc.ProjectLabelRow>[] = [
+  { key: "name", header: "Name", value: (label) => label.name, max: 30 },
+  { key: "color", header: "Color", value: (label) => label.color },
+  { key: "group", header: "Group", value: (label) => (label.isGroup ? "yes" : "—") },
+  { key: "parent", header: "Parent", value: (label) => label.parent?.name ?? "—" },
+  { key: "retired", header: "Retired", value: (label) => (label.retiredAt ? "yes" : "—") },
+];
+
+const receipt = (label: { id: string; name: string; color: string }) => ({
+  id: label.id,
+  name: label.name,
+  color: label.color,
+});
+
+export function registerProjectLabel(program: Command): void {
+  const labels = program
+    .command("project-label")
+    .alias("pl")
+    .description("Manage project labels (distinct from issue labels)");
+
+  labels
+    .command("list")
+    .alias("ls")
+    .description("List project labels")
+    .option("--include-retired", "include labels retired from new project assignment")
+    .action(
+      action(async (ctx: Context, opts) => {
+        const rows = await svc.listProjectLabels(ctx.client, ctx.limit, !!opts.includeRetired);
+        ctx.output.list(rows, COLUMNS, rows);
+      }),
+    );
+
+  labels
+    .command("view <name-or-id>")
+    .description("View a project label or label group by exact name or id")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const label = await svc.getProjectLabel(ctx.client, input);
+        ctx.output.emit(label, () =>
+          ctx.output.detail(label.name, [
+            ["ID", label.id],
+            ["Color", label.color],
+            ["Description", label.description],
+            ["Group", label.isGroup ? "yes" : "no"],
+            ["Parent", label.parent?.name ?? null],
+            ["Retired", label.retiredAt],
+            [
+              "Children",
+              label.children.length ? label.children.map((child) => child.name).join(", ") : null,
+            ],
+          ]),
+        );
+      }),
+    );
+
+  labels
+    .command("create")
+    .alias("new")
+    .description("Create a project label or label group")
+    .option("--name <name>", "project label name")
+    .option("--color <hex>", "label color (six-digit hex, e.g. #5E6AD2)")
+    .option("-d, --description <text>", "label description")
+    .option("--group", "create a non-assignable label group")
+    .option("--parent <name-or-id>", "put the label in this group")
+    .action(
+      action(async (ctx: Context, opts) => {
+        let name: string | undefined = opts.name;
+        if (!name) name = await promptInput(ctx, "Name:", { required: true });
+        const label = await svc.createProjectLabel(ctx.client, { ...opts, name });
+        ctx.output.emit(receipt(label), () =>
+          ctx.output.success(`Created project label ${label.name}`),
+        );
+      }),
+    );
+
+  labels
+    .command("update <name-or-id>")
+    .alias("edit")
+    .description("Update a project label by exact name or id")
+    .option("--name <name>", "new name")
+    .option("--color <hex>", "new color (six-digit hex, e.g. #5E6AD2)")
+    .option("-d, --description <text>", "new description")
+    .option("--parent <name-or-id>", "move the label into this group")
+    .option("--clear-parent", "remove the label from its group")
+    .action(
+      action(async (ctx: Context, opts, input: string) => {
+        const label = await svc.updateProjectLabel(ctx.client, input, opts);
+        ctx.output.emit(receipt(label), () =>
+          ctx.output.success(`Updated project label ${label.name}`),
+        );
+      }),
+    );
+
+  labels
+    .command("retire <name-or-id>")
+    .description("Retire a label so it cannot be assigned to new projects")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const current = await svc.getProjectLabel(ctx.client, input);
+        if (!(await confirmDestructive(ctx, `Retire project label ${current.name}?`))) return;
+        const label = await svc.retireProjectLabel(ctx.client, current.id);
+        ctx.output.emit({ id: label.id, name: label.name, retired: true }, () =>
+          ctx.output.success(`Retired project label ${label.name}`),
+        );
+      }),
+    );
+
+  labels
+    .command("restore <name-or-id>")
+    .alias("unretire")
+    .description("Restore a retired project label")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const label = await svc.restoreProjectLabel(ctx.client, input);
+        ctx.output.emit({ id: label.id, name: label.name, restored: true }, () =>
+          ctx.output.success(`Restored project label ${label.name}`),
+        );
+      }),
+    );
+
+  labels
+    .command("delete <name-or-id>")
+    .alias("rm")
+    .description("Permanently delete a project label")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const current = await svc.getProjectLabel(ctx.client, input);
+        if (!(await confirmDestructive(ctx, `Delete project label ${current.name}?`))) return;
+        const label = await svc.deleteProjectLabel(ctx.client, current.id);
+        ctx.output.emit({ id: label.id, name: label.name, deleted: true }, () =>
+          ctx.output.success(`Deleted project label ${label.name}`),
+        );
+      }),
+    );
+}

package/src/commands/project-status.ts

@@ -0,0 +1,166 @@
+/** `linear project-status` — manage workspace project-status definitions. */
+
+import { Command } from "commander";
+import type { Context } from "../context.js";
+import { action } from "../lib/action.js";
+import { resolveBody } from "../lib/body.js";
+import { usageError } from "../lib/errors.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import type { Column } from "../output/table.js";
+import * as svc from "../services/project-status.js";
+
+const ROW_COLUMNS: Column<svc.ProjectStatusRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.name, max: 28 },
+  { key: "type", header: "Type", value: (r) => r.type },
+  { key: "position", header: "Pos", value: (r) => r.position },
+  { key: "color", header: "Color", value: (r) => r.color },
+  { key: "indefinite", header: "Indefinite", value: (r) => (r.indefinite ? "yes" : "no") },
+  { key: "archived", header: "Archived", value: (r) => (r.archivedAt ? "yes" : "no") },
+];
+
+export function registerProjectStatus(program: Command): void {
+  const status = program
+    .command("project-status")
+    .alias("project-statuses")
+    .description("Manage workspace project-status definitions");
+
+  status
+    .command("list")
+    .alias("ls")
+    .description("List workspace project statuses")
+    .option("--include-archived", "include archived project statuses")
+    .action(
+      action(async (ctx: Context, opts) => {
+        const rows = await svc.listProjectStatuses(ctx.client, ctx.limit, !!opts.includeArchived);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  status
+    .command("view <name-or-id>")
+    .description("Show a project status by exact name or id")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const detail = await svc.getProjectStatusDetail(ctx.client, input);
+        ctx.output.detail(detail, [
+          ["Project status", detail.name],
+          ["ID", detail.id],
+          ["Type", detail.type],
+          ["Position", detail.position],
+          ["Color", detail.color],
+          ["Indefinite", detail.indefinite],
+          ["Archived", detail.archivedAt],
+          ["Description", detail.description ? `\n${detail.description}` : null],
+          ["Created", detail.createdAt],
+          ["Updated", detail.updatedAt],
+        ]);
+      }),
+    );
+
+  status
+    .command("create")
+    .alias("new")
+    .description("Create a workspace project status (explicit because duplicate names are valid)")
+    .option("--name <name>", "status name")
+    .option("-d, --description <text>", "status description")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--color <hex>", "six-digit hex color (e.g. #5E6AD2)")
+    .option("--position <number>", "position within the status type", parseNumber)
+    .option("--type <type>", `status type (${svc.PROJECT_STATUS_TYPES.join("|")})`)
+    .option("--indefinite", "allow projects to remain in this status indefinitely")
+    .action(
+      action(async (ctx: Context, opts) => {
+        let name: string | undefined = opts.name;
+        if (!name) name = await promptInput(ctx, "Name:", { required: true });
+        const created = await svc.createProjectStatus(ctx.client, {
+          name,
+          description: resolveBody({
+            arg: opts.description,
+            file: opts.descriptionFile,
+            interactive: false,
+          }),
+          color: opts.color,
+          position: opts.position,
+          type: opts.type,
+          indefinite: opts.indefinite,
+        });
+        ctx.output.emit(statusReceipt(created), () =>
+          ctx.output.success(`Created project status ${created.name}`),
+        );
+      }),
+    );
+
+  status
+    .command("update <name-or-id>")
+    .alias("edit")
+    .description("Update a project status by exact name or id")
+    .option("--name <name>", "new status name")
+    .option("-d, --description <text>", "new status description")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--color <hex>", "six-digit hex color (e.g. #5E6AD2)")
+    .option("--position <number>", "position within the status type", parseNumber)
+    .option("--type <type>", `status type (${svc.PROJECT_STATUS_TYPES.join("|")})`)
+    .option("--indefinite", "allow projects to remain in this status indefinitely")
+    .option("--no-indefinite", "do not allow projects to remain indefinitely")
+    .action(
+      action(async (ctx: Context, opts, input: string) => {
+        const updated = await svc.updateProjectStatus(ctx.client, input, {
+          name: opts.name,
+          description: resolveBody({
+            arg: opts.description,
+            file: opts.descriptionFile,
+            interactive: false,
+          }),
+          color: opts.color,
+          position: opts.position,
+          type: opts.type,
+          indefinite: opts.indefinite,
+        });
+        ctx.output.emit(statusReceipt(updated), () =>
+          ctx.output.success(`Updated project status ${updated.name}`),
+        );
+      }),
+    );
+
+  status
+    .command("archive <name-or-id>")
+    .description(
+      "Archive a project status (requires no active projects and another status of its type)",
+    )
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const detail = await svc.getProjectStatusDetail(ctx.client, input);
+        if (!(await confirmDestructive(ctx, `Archive project status ${detail.name}?`))) return;
+        const archived = await svc.archiveProjectStatus(ctx.client, detail.id);
+        ctx.output.emit({ id: archived.id, name: archived.name, archived: true }, () =>
+          ctx.output.success(`Archived project status ${archived.name}`),
+        );
+      }),
+    );
+
+  status
+    .command("unarchive <name-or-id>")
+    .description("Unarchive a project status by exact name or id")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const restored = await svc.unarchiveProjectStatus(ctx.client, input);
+        ctx.output.emit({ id: restored.id, name: restored.name, archived: false }, () =>
+          ctx.output.success(`Unarchived project status ${restored.name}`),
+        );
+      }),
+    );
+}
+
+function statusReceipt(status: any) {
+  return {
+    id: status.id,
+    name: status.name,
+    type: status.type,
+  };
+}
+
+function parseNumber(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw usageError(`Invalid number '${value}'.`);
+  return parsed;
+}

package/src/commands/project.ts

@@ -165,7 +165,11 @@ export function registerProject(program: Command): void {
     .option("--start <date>", "planned start date (YYYY-MM-DD)")
     .option("--target <date>", "planned target date (YYYY-MM-DD)")
     .option("-P, --priority <0-4>", "priority (0 none, 1 urgent … 4 low)", parseIntOption)
-    .option("-l, --label <name>", "project label (repeatable / comma-separated)", parseList)
+    .option(
+      "-l, --label <name>",
+      "project label from `project-label list` (repeatable / comma-separated)",
+      parseList,
+    )
     .option("--icon <name>", "Linear icon name, capitalized (e.g. Rocket)")
     .option("--color <hex>", "project color (e.g. #EB5757)")
     .addHelpText(
@@ -243,7 +247,11 @@ export function registerProject(program: Command): void {
     .option("--start <date>", "planned start date (YYYY-MM-DD)")
     .option("--target <date>", "planned target date (YYYY-MM-DD)")
     .option("-P, --priority <0-4>", "priority (0 none, 1 urgent … 4 low)", parseIntOption)
-    .option("-l, --label <name>", "replace the labels (repeatable / comma-separated)", parseList)
+    .option(
+      "-l, --label <name>",
+      "replace project labels from `project-label list` (repeatable / comma-separated)",
+      parseList,
+    )
     .option("--icon <name>", "Linear icon name, capitalized (e.g. Rocket)")
     .option("--color <hex>", "project color (e.g. #EB5757)")
     // `-t/--team` is a global on every other command, so it is the flag a user

package/src/lib/action.ts

@@ -8,6 +8,7 @@
 
 import type { Command } from "commander";
 import { Context, type GlobalOptions } from "../context.js";
+import { enrichAuthorizationError } from "./authorization.js";
 
 export type ActionHandler = (
   ctx: Context,
@@ -26,9 +27,13 @@ export function action(handler: ActionHandler) {
     let group = command;
     while (group.parent?.parent) group = group.parent;
     const offline =
-      ["config", "open", "commands", "completion"].includes(group.name()) ||
+      ["config", "open", "commands", "completion", "changelog"].includes(group.name()) ||
       (group.name() === "auth" && !["whoami", "status", "token"].includes(command.name()));
     if (!offline) await ctx.selectWorkspace();
-    await handler(ctx, localOpts, ...positionals);
+    try {
+      await handler(ctx, localOpts, ...positionals);
+    } catch (error) {
+      throw enrichAuthorizationError(error, ctx.config);
+    }
   };
 }

package/src/lib/authorization.ts

@@ -0,0 +1,91 @@
+import type { ResolvedConfig } from "../config.js";
+import { CliError, normalizeError } from "./errors.js";
+
+export type CredentialType = "api-key" | "oauth-access-token" | "oauth-user" | null;
+export type ScopeVisibility = "known" | "unknown" | "unavailable";
+
+export interface AuthorizationCapabilities {
+  credentialType: CredentialType;
+  scopeVisibility: ScopeVisibility;
+  scopes: string[] | null;
+  adminScope: boolean | null;
+  note: string;
+}
+
+export function credentialType(config: ResolvedConfig): CredentialType {
+  if (config.oauthCredential) return "oauth-user";
+  if (config.accessToken) return "oauth-access-token";
+  if (config.apiKey) return "api-key";
+  return null;
+}
+
+/**
+ * Report only capabilities the CLI can establish without probing a mutation.
+ * Stored OAuth grants carry their requested scopes. Linear exposes no safe
+ * read-only scope introspection for personal API keys or injected access tokens.
+ */
+export function authorizationCapabilities(config: ResolvedConfig): AuthorizationCapabilities {
+  const type = credentialType(config);
+  if (config.oauthCredential) {
+    const scopes = [...config.oauthCredential.scopes];
+    return {
+      credentialType: type,
+      scopeVisibility: "known",
+      scopes,
+      adminScope: scopes.includes("admin"),
+      note: "Stored OAuth grant scopes are known; workspace role is a separate authorization check.",
+    };
+  }
+  if (type) {
+    return {
+      credentialType: type,
+      scopeVisibility: "unknown",
+      scopes: null,
+      adminScope: null,
+      note:
+        type === "api-key"
+          ? "Linear does not expose personal API-key scopes for read-only introspection; workspace role alone does not prove admin-scope access."
+          : "Injected OAuth token scopes are not available to the CLI; workspace role alone does not prove admin-scope access.",
+    };
+  }
+  return {
+    credentialType: null,
+    scopeVisibility: "unavailable",
+    scopes: null,
+    adminScope: null,
+    note: "No active credential is available to inspect.",
+  };
+}
+
+function requiredScope(error: CliError): string | undefined {
+  const text = [error.message, JSON.stringify(error.detail ?? "")].join(" ");
+  if (/admin[^.]{0,40}scope|scope[^.]{0,40}admin/i.test(text)) return "admin";
+  return undefined;
+}
+
+/** Add safe, stable authorization context to scope-related forbidden failures. */
+export function enrichAuthorizationError(error: unknown, config: ResolvedConfig): CliError {
+  const normalized = normalizeError(error);
+  if (normalized.code !== "forbidden") return normalized;
+  const required = requiredScope(normalized);
+  if (!required) return normalized;
+
+  const capabilities = authorizationCapabilities(config);
+  const remediation =
+    capabilities.credentialType === "oauth-user"
+      ? "Re-authenticate with `linear auth login --admin`; member admin status alone is insufficient."
+      : "Use a credential authorized for the admin scope; member admin status alone is insufficient.";
+  return new CliError(
+    normalized.message,
+    normalized.code,
+    normalized.detail,
+    normalized.suggestion ?? remediation,
+    {
+      requiredScope: required,
+      credentialType: capabilities.credentialType,
+      scopeVisibility: capabilities.scopeVisibility,
+      grantedScopes: capabilities.scopes,
+      remediation,
+    },
+  );
+}

package/src/lib/errors.ts

@@ -52,14 +52,23 @@ export class CliError extends Error {
   readonly detail?: unknown;
   /** A separately actionable hint; machine callers never have to parse prose. */
   readonly suggestion?: string;
-
-  constructor(message: string, code: ErrorCode = "runtime", detail?: unknown, suggestion?: string) {
+  /** Stable, safe machine-readable context; unlike `detail`, this needs no --debug. */
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    code: ErrorCode = "runtime",
+    detail?: unknown,
+    suggestion?: string,
+    details?: Record<string, unknown>,
+  ) {
     super(message);
     this.name = "CliError";
     this.code = code;
     this.exitCode = EXIT_BY_CODE[code];
     this.detail = detail;
     this.suggestion = suggestion;
+    this.details = details;
   }
 }