linear-sdk-cli 0.4.0 → 0.5.0

package/src/commands/project.ts

@@ -4,7 +4,13 @@
 
 import { Command, Option } from "commander";
 import { action } from "../lib/action.js";
-import { parseList, parseIntOption, addAliasOption, readAlias } from "../lib/options.js";
+import {
+  parseList,
+  parseIntOption,
+  addAliasOption,
+  readAlias,
+  addIncludeArchivedOption,
+} from "../lib/options.js";
 import { usageError } from "../lib/errors.js";
 import { resolveBody } from "../lib/body.js";
 import { confirmDestructive, promptInput } from "../lib/prompt.js";
@@ -12,10 +18,16 @@ import type { Context } from "../context.js";
 import * as svc from "../services/project.js";
 import { formatMilestoneProgress } from "./milestone.js";
 import type { Column } from "../output/table.js";
+import { lifecycleSuffix } from "../output/lifecycle.js";
 
 const ROW_COLUMNS: Column<svc.ProjectRow>[] = [
   { key: "name", header: "Name", value: (r) => r.name, max: 36 },
-  { key: "state", header: "State", value: (r) => r.status?.name ?? r.state ?? "—", max: 14 },
+  {
+    key: "state",
+    header: "State",
+    value: (r) => `${r.status?.name ?? r.state ?? "—"}${lifecycleSuffix(r)}`,
+    max: 26,
+  },
   { key: "progress", header: "Progress", value: (r) => formatProgress(r.progress) },
   { key: "lead", header: "Lead", value: (r) => r.lead?.displayName ?? "—", max: 16 },
   { key: "target", header: "Target", value: (r) => r.targetDate ?? "—" },
@@ -72,6 +84,7 @@ export function registerProject(program: Command): void {
             team: opts.allTeams ? undefined : (opts.team ?? ctx.defaultTeam),
             allTeams: !!opts.allTeams,
             state: readAlias(opts, "--state", "--status"),
+            includeArchived: !!opts.includeArchived,
           },
           ctx.limit,
           ctx.defaultTeam,
@@ -79,6 +92,7 @@ export function registerProject(program: Command): void {
         ctx.output.list(rows, ROW_COLUMNS, rows);
       }),
     );
+  addIncludeArchivedOption(list);
   // `--status` is the reference CLI's spelling for the same thing; it shipped
   // earlier as a visible duplicate and now goes through the shared alias
   // mechanism, so `--help` shows one canonical spelling here like everywhere else.
@@ -94,7 +108,11 @@ export function registerProject(program: Command): void {
         const detail = await svc.getProjectDetail(ctx.client, idArg);
         ctx.output.detail(detail, [
           ["Project", detail.name],
-          ["Archived", detail.archivedAt ? `YES (${detail.archivedAt})` : null],
+          [
+            "Trashed",
+            detail.trashed ? `YES (deleted ${detail.archivedAt ?? "at an unknown time"})` : null,
+          ],
+          ["Archived", !detail.trashed && detail.archivedAt ? `YES (${detail.archivedAt})` : null],
           ["State", detail.status?.name ?? detail.state],
           ["Health", detail.health],
           ["Progress", detail.progress !== null ? formatProgress(detail.progress) : null],

package/src/config.ts

@@ -3,8 +3,9 @@
  *
  * Two tiers with different trust boundaries:
  *  - Non-secret settings (team, workspace, sort): flag > env > project
- *    config > user config (`~/.config/linear/config.toml`) > the reference
- *    CLI's global config (`~/.config/linear/linear.toml`, read-only).
+ *    config > selected workspace profile (team only) > user config
+ *    (`~/.config/linear/config.toml`) > the reference CLI's global config
+ *    (`~/.config/linear/linear.toml`, read-only).
  *    The project config is the first file found walking cwd → filesystem
  *    root, checking `linear.toml`, `.linear.toml`, `.config/linear.toml` in
  *    each directory — every location schpet/linear-cli 2.5 reads (it checks
@@ -70,7 +71,15 @@ export interface RawSettings {
  * `global` is the reference CLI's `~/.config/linear/linear.toml`, read for
  * non-secret settings only; `keychain` is the OS keyring (API key or human OAuth session).
  */
-export type ConfigSource = "flag" | "env" | "project" | "user" | "global" | "keychain" | "none";
+export type ConfigSource =
+  | "flag"
+  | "env"
+  | "project"
+  | "workspace-profile"
+  | "user"
+  | "global"
+  | "keychain"
+  | "none";
 
 /** Where a stored workspace credential's secret lives. */
 export type CredentialStorage = "file" | "keychain";
@@ -81,6 +90,8 @@ export interface SettingOrigin {
   path?: string;
   /** Exact spelling found in the file (`issue_sort`, not just canonical `sort`). */
   key?: string;
+  /** Workspace slug for a value read from `[workspaces."<slug>"]`. */
+  workspace?: string;
 }
 
 /** The non-secret settings, each with its provenance. */
@@ -104,6 +115,8 @@ export interface ResolvedConfig {
   apiKeyError?: CliError;
   /** Workspace slug whose stored credential was used, if any. */
   credentialWorkspace?: string;
+  /** Selected stored profile whose non-secret metadata may participate. */
+  workspaceProfile?: string;
   team?: string;
   /** Non-secret display workspace setting (separate from credentialWorkspace). */
   workspace?: string;
@@ -174,6 +187,8 @@ interface WorkspaceEntry {
   apiKey?: string;
   /** This workspace uses the isolated `oauth:<slug>` keyring account. */
   oauth?: boolean;
+  /** Non-secret default team for this workspace. */
+  team?: string;
 }
 
 /** Parsed view of the user config: top-level settings + nested workspace creds. */
@@ -328,6 +343,7 @@ function readUserConfig(path: string): UserConfig {
         workspaces[slug] = {
           apiKey: asString(table.api_key),
           oauth: table.oauth === true,
+          team: asString(table.team),
         };
       }
     }
@@ -450,6 +466,7 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   let accessTokenSource: ConfigSource = "none";
   let oauthCredential: OAuthUserCredential | undefined;
   let credentialWorkspace: string | undefined;
+  let workspaceProfile: string | undefined;
   let apiKeyError: CliError | undefined;
 
   if (flags.apiKey && flags.accessToken) {
@@ -531,8 +548,27 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
     }
   }
 
+  // A stored credential binds its own profile. An invocation-scoped credential
+  // never inherits the default/project workspace implicitly; it may bind only
+  // when this invocation explicitly selected a profile by flag or environment
+  // and that profile is actually configured.
+  if (credentialWorkspace && user.workspaces[credentialWorkspace]) {
+    workspaceProfile = credentialWorkspace;
+  } else {
+    const invocationCredential =
+      apiKeySource === "flag" ||
+      apiKeySource === "env" ||
+      accessTokenSource === "flag" ||
+      accessTokenSource === "env";
+    const explicitWorkspace = flags.workspace ?? envSettings.workspace;
+    if (invocationCredential && explicitWorkspace && user.workspaces[explicitWorkspace]) {
+      workspaceProfile = explicitWorkspace;
+    }
+  }
+
   // ----- Non-secret settings (project + global config MAY participate) -----
-  // flag > env > project file > our user file > the reference CLI's global file.
+  // Workspace and sort keep their existing order. Team inserts the selected
+  // workspace profile between project and the legacy top-level user fallback.
   const tiers: Array<[ConfigSource, RawSettings, string | undefined, SettingKeys | undefined]> = [
     ["flag", flags, undefined, undefined],
     ["env", envSettings, undefined, undefined],
@@ -543,13 +579,30 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   const pick = <K extends "team" | "workspace" | "sort">(key: K): string | undefined =>
     tiers.find(([, settings]) => settings[key] !== undefined)?.[1][key];
 
+  const profileTeam = workspaceProfile ? user.workspaces[workspaceProfile]?.team : undefined;
+  const teamTiers: typeof tiers = [
+    ["flag", flags, undefined, undefined],
+    ["env", envSettings, undefined, undefined],
+    ["project", project.settings, projectPath, project.keys],
+    [
+      "workspace-profile",
+      profileTeam ? { team: profileTeam } : {},
+      userPath,
+      profileTeam ? { team: "team" } : undefined,
+    ],
+    ["user", user.settings, userPath, user.settingKeys],
+    ["global", global.settings, globalPath, global.keys],
+  ];
+
   /** Which tier `pick` took the value from, and which file if it was one. */
   const originOf = (key: "team" | "workspace" | "sort"): SettingOrigin => {
-    const hit = tiers.find(([, settings]) => settings[key] !== undefined);
+    const candidates = key === "team" ? teamTiers : tiers;
+    const hit = candidates.find(([, settings]) => settings[key] !== undefined);
     if (!hit) return { source: "none" };
     const origin: SettingOrigin = { source: hit[0], path: hit[2] };
     const spelling = hit[3]?.[key];
     if (spelling !== undefined) origin.key = spelling;
+    if (hit[0] === "workspace-profile") origin.workspace = workspaceProfile;
     return origin;
   };
 
@@ -567,7 +620,8 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
     oauthCredential,
     apiKeyError,
     credentialWorkspace,
-    team: pick("team"),
+    workspaceProfile,
+    team: teamTiers.find(([, settings]) => settings.team !== undefined)?.[1].team,
     // The display setting walks every tier. Credential selection above uses
     // the flag, env, and project tiers, then the auth-specific user default.
     workspace: pick("workspace"),
@@ -823,6 +877,7 @@ interface WorkspaceTable {
   api_key?: string;
   keyring?: boolean;
   oauth?: boolean;
+  team?: string;
 }
 
 function workspacesTable(obj: Record<string, unknown>): Record<string, WorkspaceTable> {
@@ -1151,6 +1206,31 @@ export function setDefaultWorkspace(slug: string): string {
   });
 }
 
+/** Set non-secret team metadata on one existing workspace profile. */
+export function setWorkspaceTeam(
+  slug: string,
+  team: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const path = userConfigPath(env);
+  return withUserConfigLock(path, () => {
+    const known = readUserConfig(path).workspaces;
+    if (!known[slug]) {
+      throw new CliError(
+        `Workspace '${sanitize(slug)}' is not configured. Run \`linear auth login --workspace ${sanitize(slug)}\` first.`,
+        "not_found",
+      );
+    }
+    const obj = readUserObject(path);
+    const ws = workspacesTable(obj);
+    const table: WorkspaceTable = { ...(ws[slug] ?? {}) };
+    table.team = team;
+    ws[slug] = table;
+    writeUserObject(path, obj);
+    return path;
+  });
+}
+
 /**
  * Drop `slug` from the reference CLI's keyring-format credentials list, if it
  * is there, in that file's own layout (`default` first, sorted `workspaces`).
@@ -1176,10 +1256,17 @@ function removeFromReferenceCredentials(slug: string): boolean {
  * removed slug was the default, the default is repointed to a remaining
  * workspace (or cleared). Returns true if anything was removed.
  */
-export function removeCredential(slug: string): boolean {
+export interface RemoveCredentialResult {
+  removed: boolean;
+  teamMetadataRemoved: boolean;
+}
+
+/** Detailed removal receipt used by `auth logout`. */
+export function removeCredentialWithMetadata(slug: string): RemoveCredentialResult {
   const path = userConfigPath();
   return withUserConfigLock(path, () => {
     let removed = false;
+    let teamMetadataRemoved = false;
 
     const backend = keyring();
     if (backend) {
@@ -1188,11 +1275,12 @@ export function removeCredential(slug: string): boolean {
     }
     if (removeFromReferenceCredentials(slug)) removed = true;
 
-    if (!existsSync(path)) return removed;
+    if (!existsSync(path)) return { removed, teamMetadataRemoved };
     const obj = readUserObject(path);
     const ws = workspacesTable(obj);
     const listed = Boolean(ws[slug]);
     if (listed) {
+      teamMetadataRemoved = asString(ws[slug]?.team) !== undefined;
       delete ws[slug];
       removed = true;
     }
@@ -1206,13 +1294,19 @@ export function removeCredential(slug: string): boolean {
     } else if (listed) {
       writeUserObject(path, obj);
     }
-    return removed;
+    return { removed, teamMetadataRemoved };
   });
 }
 
+/** Backward-compatible boolean removal API. */
+export function removeCredential(slug: string): boolean {
+  return removeCredentialWithMetadata(slug).removed;
+}
+
 export interface RemoveOAuthCredentialResult {
   removed: boolean;
   fallbackCredentialType: "api-key" | null;
+  teamMetadataRemoved: boolean;
 }
 
 /** Remove only the human OAuth lifecycle, restoring a pre-existing API-key profile if present. */
@@ -1223,6 +1317,7 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
     let oauthRaw: string | null = null;
     let keyringApiKey = false;
     let removed = false;
+    let teamMetadataRemoved = false;
     if (backend) {
       try {
         oauthRaw = backend.get(oauthAccount(slug));
@@ -1237,7 +1332,11 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
     }
 
     if (!existsSync(path)) {
-      return { removed, fallbackCredentialType: keyringApiKey ? "api-key" : null };
+      return {
+        removed,
+        fallbackCredentialType: keyringApiKey ? "api-key" : null,
+        teamMetadataRemoved,
+      };
     }
     try {
       const obj = readUserObject(path);
@@ -1255,6 +1354,7 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
         else fallback.keyring = true;
         ws[slug] = fallback;
       } else if (table) {
+        teamMetadataRemoved = asString(table.team) !== undefined;
         delete ws[slug];
       }
       if (Object.keys(ws).length === 0) delete obj.workspaces;
@@ -1270,6 +1370,7 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
       return {
         removed,
         fallbackCredentialType: apiKeyFallback ? "api-key" : null,
+        teamMetadataRemoved,
       };
     } catch (err) {
       try {

package/src/lib/delegation.ts

@@ -0,0 +1,240 @@
+/**
+ * Linear for Agents (Developer Preview) helpers.
+ *
+ * Delegates are deliberately resolved separately from assignees. A human can
+ * own an issue; only an active, assignable app user with access to the issue's
+ * team can be delegated the work.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { CliError, ambiguous, normalizeError, notFound } from "./errors.js";
+import { isUuid } from "./resolve.js";
+
+const PAGE_SIZE = 250;
+const SCAN_CAP = 2000;
+const MAX_LISTED = 25;
+
+export interface DelegateRef {
+  id: string;
+  displayName: string;
+  name: string;
+}
+
+function delegationMessages(err: unknown): { normalized: CliError; messages: string } {
+  const normalized = normalizeError(err);
+  return {
+    normalized,
+    messages: [normalized.message, JSON.stringify(normalized.detail ?? "")].join(" "),
+  };
+}
+
+function missingDelegationSchema(messages: string): boolean {
+  return (
+    /(cannot query field|unknown (argument|field)|is not defined by type).*(delegate|isAssignable|canAccessAnyPublicTeam)/i.test(
+      messages,
+    ) ||
+    /(delegateId|delegate|isAssignable|canAccessAnyPublicTeam).*(cannot query field|unknown (argument|field)|is not defined by type)/i.test(
+      messages,
+    )
+  );
+}
+
+/** Whether an issue read can safely retry without its one preview-only field. */
+export function isDelegationReadUnavailable(err: unknown): boolean {
+  const { normalized, messages } = delegationMessages(err);
+  return (
+    missingDelegationSchema(messages) ||
+    (normalized.code === "feature_not_accessible" && /delegate/i.test(messages))
+  );
+}
+
+interface DelegateCandidate extends DelegateRef {
+  active: boolean;
+  app: boolean;
+  isAssignable: boolean;
+  canAccessAnyPublicTeam: boolean;
+  teams: { nodes: Array<{ id: string }> };
+}
+
+const CANDIDATE_FIELDS = `
+  id displayName name active app isAssignable canAccessAnyPublicTeam
+  teams(filter: { id: { eq: $teamId } }, first: 1) { nodes { id } }
+`;
+
+const CANDIDATES_QUERY = `
+query CliDelegateCandidates($teamId: String!, $after: String) {
+  users(first: ${PAGE_SIZE}, after: $after, includeDisabled: true, includeArchived: true) {
+    nodes { ${CANDIDATE_FIELDS} }
+    pageInfo { hasNextPage endCursor }
+  }
+}
+`;
+
+const CANDIDATE_QUERY = `
+query CliDelegateCandidate($id: String!, $teamId: String!) {
+  user(id: $id) { ${CANDIDATE_FIELDS} }
+}
+`;
+
+/**
+ * Turn an unavailable Developer Preview schema/feature into a stable boundary.
+ * Other validation failures retain their original code and wording.
+ */
+export function delegationFeatureError(err: unknown): CliError {
+  const { normalized, messages } = delegationMessages(err);
+  const schemaMissing = missingDelegationSchema(messages);
+  if (normalized.code !== "feature_not_accessible" && !schemaMissing) return normalized;
+  return new CliError(
+    "Issue delegation is unavailable in this Linear workspace or API schema (Linear for Agents is in Developer Preview).",
+    "feature_not_accessible",
+    normalized.detail,
+    "Enable an assignable agent integration with access to this team, or retry when the workspace supports issue delegation.",
+  );
+}
+
+async function request<T>(client: LinearClient, query: string, variables: object): Promise<T> {
+  try {
+    const response: any = await withRetry(() =>
+      (client as any).client.rawRequest(query, variables),
+    );
+    return response.data as T;
+  } catch (err) {
+    throw delegationFeatureError(err);
+  }
+}
+
+async function allCandidates(client: LinearClient, teamId: string): Promise<DelegateCandidate[]> {
+  const candidates: DelegateCandidate[] = [];
+  let after: string | undefined;
+  for (;;) {
+    const data = await request<{
+      users: {
+        nodes: DelegateCandidate[];
+        pageInfo: { hasNextPage: boolean; endCursor: string | null };
+      };
+    }>(client, CANDIDATES_QUERY, { teamId, after });
+    candidates.push(...data.users.nodes);
+    if (!data.users.pageInfo.hasNextPage) return candidates;
+    if (candidates.length >= SCAN_CAP || !data.users.pageInfo.endCursor) {
+      throw new CliError(
+        `More than ${SCAN_CAP} workspace users to search; pass the agent user UUID instead.`,
+        "usage",
+      );
+    }
+    after = data.users.pageInfo.endCursor;
+  }
+}
+
+function isBaseEligible(candidate: DelegateCandidate): boolean {
+  return candidate.active && candidate.app && candidate.isAssignable;
+}
+
+function hasTeamAccess(candidate: DelegateCandidate, privateTeam: boolean): boolean {
+  return candidate.teams.nodes.length > 0 || (!privateTeam && candidate.canAccessAnyPublicTeam);
+}
+
+function label(candidate: DelegateCandidate): string {
+  const names =
+    candidate.displayName === candidate.name
+      ? candidate.displayName
+      : `${candidate.displayName} (${candidate.name})`;
+  return `${names} [${candidate.id}]`;
+}
+
+function validateCandidate(
+  candidate: DelegateCandidate,
+  team: { key: string; private: boolean },
+): DelegateRef {
+  if (!candidate.active) {
+    throw new CliError(
+      `'${candidate.displayName}' is inactive and cannot be delegated issues.`,
+      "validation",
+    );
+  }
+  if (!candidate.app) {
+    throw new CliError(
+      `'${candidate.displayName}' is a human user. Use --assignee for people; --delegate accepts agent app users only.`,
+      "validation",
+    );
+  }
+  if (!candidate.isAssignable) {
+    throw new CliError(
+      `'${candidate.displayName}' is an app user but is not eligible for issue delegation.`,
+      "validation",
+      undefined,
+      "Reinstall or reconfigure the agent with Linear's app:assignable scope.",
+    );
+  }
+  if (!hasTeamAccess(candidate, team.private)) {
+    throw new CliError(
+      `'${candidate.displayName}' cannot access team ${team.key} and cannot be delegated this issue.`,
+      "validation",
+      undefined,
+      "Ask a Linear workspace admin to grant the agent access to this team.",
+    );
+  }
+  return { id: candidate.id, displayName: candidate.displayName, name: candidate.name };
+}
+
+/**
+ * Resolve an agent by UUID, exact display name, or exact full name. Exact case
+ * wins over case-insensitive matching; ambiguity considers eligible app users
+ * only and lists safe names plus IDs.
+ */
+export async function resolveDelegate(
+  client: LinearClient,
+  input: string,
+  teamId: string,
+): Promise<DelegateRef> {
+  let team: { key: string; private: boolean };
+  try {
+    const model: any = await withRetry(() => client.team(teamId));
+    team = { key: model.key, private: !!model.private };
+  } catch (err) {
+    throw delegationFeatureError(err);
+  }
+
+  if (isUuid(input)) {
+    const data = await request<{ user: DelegateCandidate | null }>(client, CANDIDATE_QUERY, {
+      id: input,
+      teamId,
+    });
+    if (!data.user) throw notFound(`No agent user with id '${input}'.`);
+    return validateCandidate(data.user, team);
+  }
+
+  const candidates = await allCandidates(client, teamId);
+  const exact = candidates.filter(
+    (candidate) => candidate.displayName === input || candidate.name === input,
+  );
+  const lower = input.toLocaleLowerCase();
+  const matching = exact.length
+    ? exact
+    : candidates.filter(
+        (candidate) =>
+          candidate.displayName.toLocaleLowerCase() === lower ||
+          candidate.name.toLocaleLowerCase() === lower,
+      );
+  const eligible = matching.filter(
+    (candidate) => isBaseEligible(candidate) && hasTeamAccess(candidate, team.private),
+  );
+  if (eligible.length > 1) {
+    throw ambiguous(
+      `Multiple eligible agents match '${input}': ${eligible.map(label).join(", ")}. Pass the agent user UUID.`,
+    );
+  }
+  if (eligible.length === 1) return validateCandidate(eligible[0]!, team);
+  if (matching.length > 0) return validateCandidate(matching[0]!, team);
+
+  const available = candidates.filter(
+    (candidate) => isBaseEligible(candidate) && hasTeamAccess(candidate, team.private),
+  );
+  const suffix =
+    available.length === 0
+      ? " No eligible agents can access this team."
+      : available.length > MAX_LISTED
+        ? ` Run 'linear user list --all' to inspect workspace users.`
+        : ` Available agents: ${available.map(label).join(", ")}.`;
+  throw notFound(`No eligible agent matching '${input}'.${suffix}`);
+}

package/src/lib/options.ts

@@ -210,6 +210,20 @@ export function readAlias<T = string>(
   return (canonicalValue ?? aliasValue) as T | undefined;
 }
 
+/**
+ * Add the canonical lifecycle-listing option. Linear may return both archived
+ * and trashed records when this is true, so the help does not imply an
+ * archived-only filter.
+ */
+export function addIncludeArchivedOption(cmd: Command): Command {
+  return cmd.addOption(
+    new Option(
+      "--include-archived",
+      "include archived resources (the API may also return trashed records)",
+    ),
+  );
+}
+
 /**
  * A `--no-…` global registered as an ordinary boolean flag rather than as
  * commander's *negation* of a positive option. Two bugs came out of leaving
@@ -603,7 +617,7 @@ export function addCoreFilterOptions(cmd: Command, set: FilterOptionSet = {}): C
     cmd.addOption(new Option("-a, --assignee <who>", "filter by assignee (me|email|name)"));
     cmd.addOption(new Option("-U, --unassigned", "only issues with no assignee"));
   }
-  return cmd
+  cmd
     .addOption(new Option("-p, --project <name>", "filter by project"))
     .addOption(
       new Option("--project-label <name>", "filter by the project's label (excludes --project)"),
@@ -622,8 +636,8 @@ export function addCoreFilterOptions(cmd: Command, set: FilterOptionSet = {}): C
     .addOption(
       new Option("--updated-after <date>", "only issues updated at/after a date (YYYY-MM-DD)"),
     )
-    .addOption(new Option("--all-teams", "search every team, ignoring the default team"))
-    .addOption(new Option("--include-archived", "include archived issues"));
+    .addOption(new Option("--all-teams", "search every team, ignoring the default team"));
+  return addIncludeArchivedOption(cmd);
 }
 
 /**