@piecemaker-legal/piecemaker 1.0.0

package/server/modules/providers/shared/base/abstract.provider.ts

@@ -0,0 +1,32 @@
+import type {
+  IProvider,
+  IProviderAuth,
+  IProviderMcp,
+  IProviderModels,
+  IProviderRuntime,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
+import type { LLMProvider } from '@/shared/types.js';
+
+/**
+ * Shared provider base.
+ *
+ * Concrete providers expose their live runtime plus model, auth, MCP, skill,
+ * session, and synchronization facets behind one registry-owned object.
+ */
+export abstract class AbstractProvider implements IProvider {
+  readonly id: LLMProvider;
+  abstract readonly runtime: IProviderRuntime;
+  abstract readonly models: IProviderModels;
+  abstract readonly mcp: IProviderMcp;
+  abstract readonly auth: IProviderAuth;
+  abstract readonly skills: IProviderSkills;
+  abstract readonly sessions: IProviderSessions;
+  abstract readonly sessionSynchronizer: IProviderSessionSynchronizer;
+
+  protected constructor(id: LLMProvider) {
+    this.id = id;
+  }
+}

package/server/modules/providers/shared/mcp/mcp.provider.ts

@@ -0,0 +1,151 @@
+import path from 'node:path';
+
+import type { IProviderMcp } from '@/shared/interfaces.js';
+import type { LLMProvider, McpScope, McpTransport, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+const resolveWorkspacePath = (workspacePath?: string): string =>
+  path.resolve(workspacePath ?? process.cwd());
+
+const normalizeServerName = (name: string): string => {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new AppError('MCP server name is required.', {
+      code: 'MCP_SERVER_NAME_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return normalized;
+};
+
+/**
+ * Shared MCP provider for provider-specific config readers/writers.
+ */
+export abstract class McpProvider implements IProviderMcp {
+  protected readonly provider: LLMProvider;
+  protected readonly supportedScopes: McpScope[];
+  protected readonly supportedTransports: McpTransport[];
+
+  protected constructor(
+    provider: LLMProvider,
+    supportedScopes: McpScope[],
+    supportedTransports: McpTransport[],
+  ) {
+    this.provider = provider;
+    this.supportedScopes = supportedScopes;
+    this.supportedTransports = supportedTransports;
+  }
+
+  async listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const grouped: Record<McpScope, ProviderMcpServer[]> = {
+      user: [],
+      local: [],
+      project: [],
+    };
+
+    for (const scope of this.supportedScopes) {
+      grouped[scope] = await this.listServersForScope(scope, options);
+    }
+
+    return grouped;
+  }
+
+  async listServersForScope(
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    if (!this.supportedScopes.includes(scope)) {
+      return [];
+    }
+
+    const workspacePath = resolveWorkspacePath(options?.workspacePath);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    return Object.entries(scopedServers)
+      .map(([name, rawConfig]) => this.normalizeServerConfig(scope, name, rawConfig))
+      .filter((entry): entry is ProviderMcpServer => entry !== null);
+  }
+
+  async upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer> {
+    const scope = input.scope ?? 'project';
+    this.assertScopeAndTransport(scope, input.transport);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    scopedServers[normalizedName] = this.buildServerConfig(input);
+    await this.writeScopedServers(scope, workspacePath, scopedServers);
+
+    return {
+      provider: this.provider,
+      name: normalizedName,
+      scope,
+      transport: input.transport,
+      command: input.command,
+      args: input.args,
+      env: input.env,
+      cwd: input.cwd,
+      url: input.url,
+      headers: input.headers,
+      envVars: input.envVars,
+      bearerTokenEnvVar: input.bearerTokenEnvVar,
+      envHttpHeaders: input.envHttpHeaders,
+    };
+  }
+
+  async removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const scope = input.scope ?? 'project';
+    this.assertScope(scope);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    const removed = Object.prototype.hasOwnProperty.call(scopedServers, normalizedName);
+    if (removed) {
+      delete scopedServers[normalizedName];
+      await this.writeScopedServers(scope, workspacePath, scopedServers);
+    }
+
+    return { removed, provider: this.provider, name: normalizedName, scope };
+  }
+
+  protected abstract readScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+  ): Promise<Record<string, unknown>>;
+
+  protected abstract writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void>;
+
+  protected abstract buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown>;
+
+  protected abstract normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null;
+
+  protected assertScope(scope: McpScope): void {
+    if (!this.supportedScopes.includes(scope)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${scope}" MCP scope.`, {
+        code: 'MCP_SCOPE_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+
+  protected assertScopeAndTransport(scope: McpScope, transport: McpTransport): void {
+    this.assertScope(scope);
+    if (!this.supportedTransports.includes(transport)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${transport}" MCP transport.`, {
+        code: 'MCP_TRANSPORT_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+}

package/server/modules/providers/shared/skills/skills.provider.ts

@@ -0,0 +1,287 @@
+import path from 'node:path';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+
+import type { IProviderSkills } from '@/shared/interfaces.js';
+import type {
+  LLMProvider,
+  ProviderSkillCreateInput,
+  ProviderSkillRemoveInput,
+  ProviderSkill,
+  ProviderSkillListOptions,
+  ProviderSkillSource,
+} from '@/shared/types.js';
+import {
+  findProviderSkillMarkdownFiles,
+  readOptionalString,
+  readProviderSkillMarkdownDefinitionFromContent,
+  readProviderSkillMarkdownDefinition,
+  AppError,
+} from '@/shared/utils.js';
+
+const resolveWorkspacePath = (workspacePath?: string): string =>
+  path.resolve(workspacePath ?? process.cwd());
+
+const stripMarkdownExtension = (value: string): string => value.replace(/\.md$/i, '');
+
+const normalizeSkillDirectoryName = (value: string): string => (
+  value
+    .trim()
+    .replace(/[\\/]+/g, '-')
+    .replace(/[<>:"|?*\x00-\x1F]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^\.+|\.+$/g, '')
+    .replace(/^-+|-+$/g, '')
+);
+
+type PendingSkillInstall = {
+  skillDirectoryPath: string;
+  skillPath: string;
+  content: string;
+  supportingFiles: Array<{
+    targetPath: string;
+    content: string | Buffer;
+  }>;
+  skill: ProviderSkill;
+};
+
+const resolveSkillSupportingFilePath = (
+  skillDirectoryPath: string,
+  relativePath: string,
+  entryIndex: number,
+): string => {
+  const normalizedRelativePath = relativePath.trim().replace(/\\/g, '/');
+  const pathSegments = normalizedRelativePath.split('/');
+  if (
+    !normalizedRelativePath
+    || path.isAbsolute(normalizedRelativePath)
+    || pathSegments.some((segment) => !segment || segment === '.' || segment === '..')
+    || normalizedRelativePath.toLowerCase() === 'skill.md'
+  ) {
+    throw new AppError(
+      `Skill entry ${entryIndex + 1} includes an invalid supporting file path "${relativePath}".`,
+      {
+        code: 'PROVIDER_SKILL_FILE_PATH_INVALID',
+        statusCode: 400,
+      },
+    );
+  }
+
+  const resolvedSkillDirectoryPath = path.resolve(skillDirectoryPath);
+  const resolvedFilePath = path.resolve(resolvedSkillDirectoryPath, ...pathSegments);
+  if (!resolvedFilePath.startsWith(`${resolvedSkillDirectoryPath}${path.sep}`)) {
+    throw new AppError(
+      `Skill entry ${entryIndex + 1} supporting files must stay inside the skill directory.`,
+      {
+        code: 'PROVIDER_SKILL_FILE_PATH_INVALID',
+        statusCode: 400,
+      },
+    );
+  }
+
+  return resolvedFilePath;
+};
+
+/**
+ * Shared skills provider for provider-specific skill source discovery.
+ */
+export abstract class SkillsProvider implements IProviderSkills {
+  protected readonly provider: LLMProvider;
+
+  protected constructor(provider: LLMProvider) {
+    this.provider = provider;
+  }
+
+  async listSkills(options?: ProviderSkillListOptions): Promise<ProviderSkill[]> {
+    const workspacePath = resolveWorkspacePath(options?.workspacePath);
+    const sources = await this.getSkillSources(workspacePath);
+    const skills: ProviderSkill[] = [];
+
+    for (const source of sources) {
+      const skillFiles = await findProviderSkillMarkdownFiles(source.rootDir, {
+        recursive: source.recursive,
+      });
+      for (const skillPath of skillFiles) {
+        try {
+          const definition = await readProviderSkillMarkdownDefinition(skillPath);
+          const command = source.commandForSkill
+            ? source.commandForSkill(definition.name)
+            : `${source.commandPrefix ?? '/'}${definition.name}`;
+
+          skills.push({
+            provider: this.provider,
+            name: definition.name,
+            description: definition.description,
+            command,
+            scope: source.scope,
+            sourcePath: skillPath,
+            pluginName: source.pluginName,
+            pluginId: source.pluginId,
+          });
+        } catch {
+          // A malformed or unreadable skill markdown file should not hide other valid skills.
+        }
+      }
+    }
+
+    return skills;
+  }
+
+  async addSkills(input: ProviderSkillCreateInput): Promise<ProviderSkill[]> {
+    const globalSkillSource = await this.getGlobalSkillSource();
+    if (!globalSkillSource) {
+      throw new AppError(`${this.provider} does not support managed global skills.`, {
+        code: 'PROVIDER_SKILLS_WRITE_UNSUPPORTED',
+        statusCode: 400,
+      });
+    }
+
+    if (!Array.isArray(input.entries) || input.entries.length === 0) {
+      throw new AppError('At least one skill entry is required.', {
+        code: 'PROVIDER_SKILLS_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const seenSkillPaths = new Set<string>();
+    const pendingInstalls: PendingSkillInstall[] = [];
+
+    for (const [index, entry] of input.entries.entries()) {
+      const content = typeof entry.content === 'string' ? entry.content.trim() : '';
+      if (!content) {
+        throw new AppError(`Skill entry ${index + 1} must include markdown content.`, {
+          code: 'PROVIDER_SKILL_CONTENT_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      const fileNameFallback = readOptionalString(entry.fileName);
+      const requestedDirectoryName = readOptionalString(entry.directoryName);
+      const fallbackSkillName = normalizeSkillDirectoryName(
+        requestedDirectoryName
+          ?? (fileNameFallback ? stripMarkdownExtension(fileNameFallback) : `skill-${index + 1}`),
+      );
+      const definition = readProviderSkillMarkdownDefinitionFromContent(content, fallbackSkillName);
+      const resolvedDirectoryName = normalizeSkillDirectoryName(
+        requestedDirectoryName ?? definition.name,
+      );
+
+      if (!resolvedDirectoryName) {
+        throw new AppError(`Skill entry ${index + 1} must include a valid skill name.`, {
+          code: 'PROVIDER_SKILL_NAME_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      const skillDirectoryPath = path.join(globalSkillSource.rootDir, resolvedDirectoryName);
+      const skillPath = path.join(skillDirectoryPath, 'SKILL.md');
+      const normalizedSkillPath = path.resolve(skillPath);
+      if (seenSkillPaths.has(normalizedSkillPath)) {
+        throw new AppError(`Duplicate skill target "${resolvedDirectoryName}" in one request.`, {
+          code: 'PROVIDER_SKILL_DUPLICATE_TARGET',
+          statusCode: 400,
+        });
+      }
+
+      seenSkillPaths.add(normalizedSkillPath);
+      const supportingFiles = (entry.files ?? []).map((file) => ({
+        targetPath: resolveSkillSupportingFilePath(skillDirectoryPath, file.relativePath, index),
+        content: file.encoding === 'base64'
+          ? Buffer.from(file.content, 'base64')
+          : file.content,
+      }));
+      const seenSupportingPaths = new Set<string>();
+      for (const file of supportingFiles) {
+        if (seenSupportingPaths.has(file.targetPath)) {
+          throw new AppError(`Skill entry ${index + 1} includes a duplicate supporting file path.`, {
+            code: 'PROVIDER_SKILL_DUPLICATE_FILE',
+            statusCode: 400,
+          });
+        }
+        seenSupportingPaths.add(file.targetPath);
+      }
+
+      const command = globalSkillSource.commandForSkill
+        ? globalSkillSource.commandForSkill(definition.name)
+        : `${globalSkillSource.commandPrefix ?? '/'}${definition.name}`;
+
+      pendingInstalls.push({
+        skillDirectoryPath,
+        skillPath,
+        content,
+        supportingFiles,
+        skill: {
+          provider: this.provider,
+          name: definition.name,
+          description: definition.description,
+          command,
+          scope: globalSkillSource.scope,
+          sourcePath: skillPath,
+          pluginName: globalSkillSource.pluginName,
+          pluginId: globalSkillSource.pluginId,
+        },
+      });
+    }
+
+    for (const install of pendingInstalls) {
+      // Replace the complete skill directory so removed scripts or assets do not remain stale.
+      await rm(install.skillDirectoryPath, { recursive: true, force: true });
+      await mkdir(install.skillDirectoryPath, { recursive: true });
+      await writeFile(install.skillPath, `${install.content}\n`, 'utf8');
+      for (const file of install.supportingFiles) {
+        await mkdir(path.dirname(file.targetPath), { recursive: true });
+        await writeFile(file.targetPath, file.content);
+      }
+    }
+
+    return pendingInstalls.map((install) => install.skill);
+  }
+
+  async removeSkill(
+    input: ProviderSkillRemoveInput,
+  ): Promise<{ removed: boolean; provider: LLMProvider; directoryName: string }> {
+    const globalSkillSource = await this.getGlobalSkillSource();
+    if (!globalSkillSource) {
+      throw new AppError(`${this.provider} does not support managed global skills.`, {
+        code: 'PROVIDER_SKILLS_WRITE_UNSUPPORTED',
+        statusCode: 400,
+      });
+    }
+
+    const directoryName = normalizeSkillDirectoryName(input.directoryName);
+    if (!directoryName) {
+      throw new AppError('Skill directoryName is required.', {
+        code: 'PROVIDER_SKILL_DIRECTORY_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const skillDirectoryPath = path.join(globalSkillSource.rootDir, directoryName);
+    const resolvedRoot = path.resolve(globalSkillSource.rootDir);
+    const resolvedSkillDirectoryPath = path.resolve(skillDirectoryPath);
+    if (
+      resolvedSkillDirectoryPath !== resolvedRoot
+      && !resolvedSkillDirectoryPath.startsWith(`${resolvedRoot}${path.sep}`)
+    ) {
+      throw new AppError('Skill directory must stay inside the managed skill root.', {
+        code: 'PROVIDER_SKILL_DIRECTORY_INVALID',
+        statusCode: 400,
+      });
+    }
+
+    const removed = await stat(resolvedSkillDirectoryPath)
+      .then((stats) => stats.isDirectory())
+      .catch(() => false);
+    if (removed) {
+      await rm(resolvedSkillDirectoryPath, { recursive: true, force: true });
+    }
+
+    return { removed, provider: this.provider, directoryName };
+  }
+
+  protected abstract getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]>;
+
+  protected async getGlobalSkillSource(): Promise<ProviderSkillSource | null> {
+    return null;
+  }
+}

package/server/modules/providers/tests/claude-auth.test.ts

@@ -0,0 +1,208 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { ClaudeProviderAuth } from '@/modules/providers/list/claude/claude-auth.provider.js';
+
+// checkCredentials() is private, but unlike getStatus() it never shells out to the
+// `claude` CLI — it only reads env vars and ~/.claude files. Calling it directly
+// (TypeScript's `private` has no runtime effect) tests the priority order without
+// depending on `claude` being installed in the test environment.
+type CheckCredentialsResult = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+const checkCredentials = (auth: ClaudeProviderAuth): Promise<CheckCredentialsResult> =>
+  (auth as unknown as { checkCredentials: () => Promise<CheckCredentialsResult> }).checkCredentials();
+
+const ENV_KEYS = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN'] as const;
+
+const withEnv = async (
+  overrides: Partial<Record<(typeof ENV_KEYS)[number], string>>,
+  fn: () => Promise<void>,
+) => {
+  const original: Partial<Record<(typeof ENV_KEYS)[number], string>> = {};
+  for (const key of ENV_KEYS) {
+    original[key] = process.env[key];
+    const value = overrides[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+  try {
+    await fn();
+  } finally {
+    for (const key of ENV_KEYS) {
+      if (original[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = original[key];
+      }
+    }
+  }
+};
+
+const withTempHome = async (fn: (homeDir: string) => Promise<void>) => {
+  const homeDir = await mkdtemp(path.join(os.tmpdir(), 'claude-auth-test-'));
+  const originalHome = process.env.HOME;
+  process.env.HOME = homeDir;
+  try {
+    await fn(homeDir);
+  } finally {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+    await rm(homeDir, { recursive: true, force: true });
+  }
+};
+
+const writeCredentialsFile = async (homeDir: string, body: unknown) => {
+  const claudeDir = path.join(homeDir, '.claude');
+  await mkdir(claudeDir, { recursive: true });
+  await writeFile(path.join(claudeDir, '.credentials.json'), JSON.stringify(body));
+};
+
+const writeSettingsFile = async (homeDir: string, env: Record<string, string>) => {
+  const claudeDir = path.join(homeDir, '.claude');
+  await mkdir(claudeDir, { recursive: true });
+  await writeFile(path.join(claudeDir, 'settings.json'), JSON.stringify({ env }));
+};
+
+test('checkCredentials: CLAUDE_CODE_OAUTH_TOKEN set is authenticated via environment, even with a stale credentials file', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 }, // long expired
+    });
+
+    await withEnv({ CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token' }, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'environment');
+    });
+  });
+});
+
+test('checkCredentials: CLAUDE_CODE_OAUTH_TOKEN configured via settings.json env block is authenticated via environment', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeSettingsFile(homeDir, { CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token-from-settings' });
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 }, // long expired
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'environment');
+    });
+  });
+});
+
+test('checkCredentials: no CLAUDE_CODE_OAUTH_TOKEN, valid credentials file falls back to credentials_file', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'valid-token', expiresAt: Date.now() + 60 * 60 * 1000 },
+      email: 'someone@example.com',
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'credentials_file');
+      assert.equal(status.email, 'someone@example.com');
+    });
+  });
+});
+
+test('checkCredentials: no CLAUDE_CODE_OAUTH_TOKEN, expired credentials file reports not authenticated', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 },
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, false);
+      assert.match(status.error ?? '', /expired/i);
+    });
+  });
+});
+
+test('checkCredentials: expired access token with a live refresh token is still authenticated', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: {
+        accessToken: 'stale-token',
+        refreshToken: 'live-refresh-token',
+        expiresAt: 1_000_000_000_000,
+        refreshTokenExpiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000,
+      },
+      email: 'someone@example.com',
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'credentials_file');
+      assert.equal(status.email, 'someone@example.com');
+    });
+  });
+});
+
+test('checkCredentials: expired access token with a refresh token that has no recorded expiry is authenticated', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: {
+        accessToken: 'stale-token',
+        refreshToken: 'live-refresh-token',
+        expiresAt: 1_000_000_000_000,
+      },
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'credentials_file');
+    });
+  });
+});
+
+test('checkCredentials: expired access token with an expired refresh token reports not authenticated', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: {
+        accessToken: 'stale-token',
+        refreshToken: 'stale-refresh-token',
+        expiresAt: 1_000_000_000_000,
+        refreshTokenExpiresAt: 1_000_000_000_000,
+      },
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, false);
+      assert.match(status.error ?? '', /expired/i);
+    });
+  });
+});
+
+test('checkCredentials: ANTHROPIC_API_KEY takes precedence over CLAUDE_CODE_OAUTH_TOKEN', async () => {
+  await withTempHome(async () => {
+    await withEnv(
+      { ANTHROPIC_API_KEY: 'test-api-key', CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token' },
+      async () => {
+        const status = await checkCredentials(new ClaudeProviderAuth());
+        assert.equal(status.authenticated, true);
+        assert.equal(status.method, 'api_key');
+      },
+    );
+  });
+});