@cleocode/contracts 2026.5.62 → 2026.5.64

package/src/operations/llm.ts

@@ -56,6 +56,15 @@ export interface ModelConfig {
   cachePolicy?: PromptCachePolicy | null;
   /** Fallback model config used on final retry attempt. */
   fallback?: Omit<ModelConfig, 'fallback'> | null;
+  /**
+   * Extra HTTP headers to attach to the provider client (merged into the SDK's
+   * `defaultHeaders`). Populated from `authHeaders(cred)` when a credential is
+   * resolved with `authType: 'oauth'` so the provider client uses the
+   * `Authorization: Bearer …` scheme instead of `x-api-key`.
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 1
+   */
+  extraHeaders?: Record<string, string> | null;
 }
 
 /** Parameters for a single LLM call. */
@@ -113,3 +122,431 @@ export interface LLMCallResult<T = string> {
   thinkingBlocks: Array<Record<string, unknown>>;
   reasoningDetails: Array<Record<string, unknown>>;
 }
+
+// ============================================================================
+// Credential resolution wire types (T-LLM-CRED-CENTRALIZATION Phase 1/2)
+//
+// These mirror the runtime types declared in `@cleocode/core/llm/credentials.ts`
+// but live here so packages outside `core` (CLI, harness, studio) can speak
+// the same wire vocabulary without taking a dependency on core internals.
+// The runtime module re-exports compatible aliases so existing imports keep
+// working.
+// ============================================================================
+
+/**
+ * Which credential-resolution tier produced a {@link CredentialResultWire}.
+ *
+ * Mirrors `CredentialSource` in `@cleocode/core/llm/credentials.ts`. The set is
+ * append-only; new tiers (e.g. `aws-sdk`, `gcp-sdk` in Phase 3) extend this
+ * union.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export type CredentialSourceWire =
+  | 'explicit'
+  | 'env'
+  | 'cred-file'
+  | 'claude-creds'
+  | 'global-config'
+  | 'project-config';
+
+/**
+ * Authentication scheme used when sending the credential to the provider.
+ *
+ * - `api_key` — provider-issued long-lived key sent as `x-api-key` (Anthropic)
+ *   or `Authorization: Bearer …` (OpenAI, Gemini, Moonshot).
+ * - `oauth` — short-lived OAuth bearer token sent as `Authorization: Bearer …`
+ *   with the matching beta header.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export type AuthTypeWire = 'api_key' | 'oauth';
+
+/**
+ * Resolved credential as returned by `resolveCredentials()` /
+ * `resolveLLMForRole()`. Mirrors `CredentialResult` in core. Compatible by
+ * structural typing.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export interface CredentialResultWire {
+  /** Provider transport this credential is for. */
+  provider: ModelTransport;
+  /** API key or OAuth bearer token. `null` only when no credential was found. */
+  apiKey: string | null;
+  /** Which tier produced this credential. `undefined` when `apiKey` is `null`. */
+  source: CredentialSourceWire | undefined;
+  /** Scheme used to present the credential to the provider. */
+  authType: AuthTypeWire;
+}
+
+// ============================================================================
+// Role-based LLM resolution wire types (T9255 — Phase 2 T-llm-1)
+// ============================================================================
+
+/**
+ * Which configuration tier produced a {@link ResolvedLLM}.
+ *
+ * Resolution chain order:
+ *   1. `role`               — `config.llm.roles[role]` (explicit override)
+ *   2. `default`            — `config.llm.default` (canonical default)
+ *   3. `daemon-legacy`      — `config.llm.daemon` (deprecated alias)
+ *   4. `implicit-fallback`  — hard-coded fallback inside the resolver
+ *
+ * Useful for `cleo llm whoami` diagnostics and for migration tooling that
+ * needs to identify call-sites still on the legacy `daemon` block.
+ *
+ * @task T9255
+ */
+export type ResolutionSource = 'role' | 'default' | 'daemon-legacy' | 'implicit-fallback';
+
+/**
+ * Result envelope returned by `resolveLLMForRole(role)`.
+ *
+ * Carries the fully-wired SDK client plus the {@link CredentialResultWire}
+ * so raw-fetch callers (sleep-consolidation, observer-reflector, hygiene-scan)
+ * can call `authHeaders(credential)` themselves when bypassing the SDK
+ * client (e.g. to call the Anthropic Messages REST API directly).
+ *
+ * `client` is `null` only when `credential.apiKey` is also `null` — in which
+ * case the caller MUST fall back to its graceful-degradation path
+ * (`return null` / skip / log warn).
+ *
+ * `client` is typed as `unknown` here because the concrete SDK classes
+ * (Anthropic, OpenAI, GoogleGenerativeAI) are not referenced from contracts
+ * to preserve its zero-dependency footprint. Consumers MUST narrow via the
+ * typed helpers in `@cleocode/core/llm/role-resolver` (e.g.
+ * `resolveAnthropicForRole`) rather than casting with `as unknown as X`.
+ *
+ * @task T9255
+ */
+export interface ResolvedLLM {
+  /** LLM provider transport that was resolved. */
+  provider: ModelTransport;
+  /** Full model identifier. */
+  model: string;
+  /**
+   * Fully-wired SDK client constructed via `clientForModelConfig`. `null`
+   * when no credential is available. Typed as `unknown` — consumers MUST
+   * narrow via a provider-specific helper (e.g. `resolveAnthropicForRole`
+   * in `@cleocode/core/llm/role-resolver`), NEVER via an `as unknown as X`
+   * cast.
+   */
+  client: unknown;
+  /**
+   * Resolved credential. `null` when no tier produced a token. Callers
+   * MUST handle this case.
+   */
+  credential: CredentialResultWire | null;
+  /** Which config path produced this resolution. */
+  source: ResolutionSource;
+  /** When `roles[role].credentialLabel` was set, the label that was used. */
+  credentialLabel?: string;
+}
+
+/**
+ * Options accepted by `resolveLLMForRole()`.
+ *
+ * @task T9255
+ */
+export interface ResolveLLMForRoleOptions {
+  /**
+   * Absolute path to the project root. Forwarded to `loadConfig()` and to
+   * `resolveCredentials({ projectRoot })` for tier-5 project-config lookup.
+   * Defaults to `process.cwd()`.
+   */
+  projectRoot?: string;
+}
+
+// ============================================================================
+// `cleo llm` CLI / dispatch operation contracts (T9258 — Phase 2 T-llm-4)
+//
+// Wire types backing the `cleo llm` CLI subcommands and the `llm` dispatch
+// domain. Provider-redacted views of `StoredCredential` (defined in
+// `@cleocode/core/llm/credentials-store`) plus the dispatch param/result
+// shapes for add / list / remove / use / profile / test / whoami.
+//
+// Tokens are NEVER returned in raw form by these envelopes — `tokenPreview`
+// surfaces only the last 4 characters so the wire vocabulary is safe for
+// JSON output, logs, and remote dispatch consumers.
+// ============================================================================
+
+/**
+ * Storage-level authentication scheme as persisted in the credentials store.
+ *
+ * Wider than the wire-level {@link AuthTypeWire}: includes `'aws_sdk'` for
+ * Bedrock / Vertex entries where the AWS SDK supplies the credential
+ * out-of-band. The runtime resolver narrows `'aws_sdk' → 'api_key'` for
+ * wire-level use until Phase 3 widens {@link AuthTypeWire}.
+ *
+ * Mirrors `StoredAuthType` in `@cleocode/core/llm/credentials-store`.
+ *
+ * @task T9258
+ */
+export type StoredAuthTypeWire = 'api_key' | 'oauth' | 'aws_sdk';
+
+/**
+ * Strategy used by the credentials-store picker.
+ *
+ * Mirrors `CredentialsStoreStrategy` in
+ * `@cleocode/core/llm/credentials-store`. Held here so callers outside
+ * `core` can render UI without taking a dependency on the storage module.
+ *
+ * @task T9258
+ */
+export type CredentialsStoreStrategyWire = 'priorityWithFallback' | 'roundRobin' | 'priorityOnly';
+
+/**
+ * Token-redacted view of a single stored credential.
+ *
+ * `tokenPreview` is the last 4 characters of `accessToken` prefixed by
+ * `'…'` (e.g. `'…aB7q'`). The full token is NEVER returned by any
+ * `cleo llm` operation — callers that need the live token must resolve it
+ * through `resolveLLMForRole()`.
+ *
+ * @task T9258
+ */
+export interface LlmStoredCredentialView {
+  /** LLM transport this credential is for. */
+  provider: ModelTransport;
+  /** Human-readable identifier, unique within `provider`. */
+  label: string;
+  /** Storage-level auth scheme. */
+  authType: StoredAuthTypeWire;
+  /** Redacted token preview — last 4 chars, prefixed by `'…'`. */
+  tokenPreview: string;
+  /** Whether the entry carried a non-empty refresh token. */
+  hasRefreshToken: boolean;
+  /** Unix epoch ms; `null` means "never expires". */
+  expiresAt: number | null;
+  /** Lower wins. */
+  priority: number;
+  /** Free-form provenance label (`claude-code`, `cli-input`, etc.). */
+  source: string | undefined;
+  /** Optional override for provider base URL. */
+  baseUrl: string | null;
+  /** When `true`, the picker skips this entry. */
+  disabled: boolean;
+}
+
+/**
+ * Parameters for `llm.add` (mutate).
+ *
+ * Mirrors the `cleo llm add <provider> --api-key <k>` CLI surface. When
+ * `authType` is omitted, the dispatcher auto-detects from the token
+ * prefix: tokens beginning with `sk-ant-oat-` are stored as `'oauth'`,
+ * everything else as `'api_key'`.
+ *
+ * @task T9258
+ */
+export interface LlmAddParams {
+  /** Target provider transport. */
+  provider: ModelTransport;
+  /** API key or OAuth bearer token to persist. */
+  apiKey: string;
+  /** Human-readable label, unique within `provider`. Defaults to `'default'`. */
+  label?: string;
+  /** Optional override for the provider base URL. */
+  baseUrl?: string;
+  /** Optional explicit auth type override (skips prefix auto-detect). */
+  authType?: StoredAuthTypeWire;
+  /** Optional priority override (lower wins). */
+  priority?: number;
+}
+
+/**
+ * Result envelope for `llm.add`.
+ *
+ * @task T9258
+ */
+export interface LlmAddResult {
+  /** Token-redacted view of the newly stored entry. */
+  credential: LlmStoredCredentialView;
+  /** Detected auth type (`'oauth'` for `sk-ant-oat-*`, else `'api_key'`). */
+  detectedAuthType: StoredAuthTypeWire;
+}
+
+/**
+ * Parameters for `llm.list` (query).
+ *
+ * @task T9258
+ */
+export interface LlmListParams {
+  /** Optional provider filter — when set, only entries for that provider. */
+  provider?: ModelTransport;
+}
+
+/**
+ * Result envelope for `llm.list`.
+ *
+ * @task T9258
+ */
+export interface LlmListResult {
+  /** Token-redacted credentials, in store order (priority asc). */
+  credentials: LlmStoredCredentialView[];
+}
+
+/**
+ * Parameters for `llm.remove` (mutate).
+ *
+ * @task T9258
+ */
+export interface LlmRemoveParams {
+  /** Target provider transport. */
+  provider: ModelTransport;
+  /** Label of the credential to remove. */
+  label: string;
+}
+
+/**
+ * Result envelope for `llm.remove`.
+ *
+ * @task T9258
+ */
+export interface LlmRemoveResult {
+  /** `true` when a matching entry was deleted. */
+  removed: boolean;
+  /** Echo of the targeted `(provider, label)` pair. */
+  provider: ModelTransport;
+  /** Echo of the targeted label. */
+  label: string;
+}
+
+/**
+ * Parameters for `llm.use` (mutate) — set `llm.default.{provider,model}`.
+ *
+ * @task T9258
+ */
+export interface LlmUseParams {
+  /** Provider transport to mark as the default. */
+  provider: ModelTransport;
+  /** Optional default model identifier. When omitted, `default.model` is left untouched. */
+  model?: string;
+}
+
+/**
+ * Result envelope for `llm.use`.
+ *
+ * @task T9258
+ */
+export interface LlmUseResult {
+  /** Provider written to `llm.default.provider`. */
+  provider: ModelTransport;
+  /** Model written to `llm.default.model` — `null` when not provided. */
+  model: string | null;
+  /** Config scope the write landed in (`'global'` for `cleo llm use`). */
+  scope: 'project' | 'global';
+}
+
+/**
+ * Parameters for `llm.profile` (mutate) — set `llm.roles[role]`.
+ *
+ * @task T9258
+ */
+export interface LlmProfileParams {
+  /** Logical role name. */
+  role: string;
+  /** Provider transport for this role. */
+  provider: ModelTransport;
+  /** Optional model identifier for this role. */
+  model?: string;
+  /** Optional credential label to pin this role to a specific store entry. */
+  credentialLabel?: string;
+}
+
+/**
+ * Result envelope for `llm.profile`.
+ *
+ * @task T9258
+ */
+export interface LlmProfileResult {
+  /** Role name written to `llm.roles[role]`. */
+  role: string;
+  /** Provider written for the role. */
+  provider: ModelTransport;
+  /** Model written for the role (or `null` when not supplied). */
+  model: string | null;
+  /** Credential label written for the role (or `null` when not supplied). */
+  credentialLabel: string | null;
+  /** Config scope the write landed in. */
+  scope: 'project' | 'global';
+}
+
+/**
+ * Parameters for `llm.test` (query).
+ *
+ * @task T9258
+ */
+export interface LlmTestParams {
+  /** Provider transport to test. */
+  provider: ModelTransport;
+  /** Optional credential label to pin the test to a specific store entry. */
+  label?: string;
+  /** Optional model override. Defaults to the provider's implicit fallback. */
+  model?: string;
+}
+
+/**
+ * Result envelope for `llm.test`. Tokens are NEVER included.
+ *
+ * @task T9258
+ */
+export interface LlmTestResult {
+  /** Provider transport that was probed. */
+  provider: ModelTransport;
+  /** Model identifier used for the probe. */
+  model: string;
+  /** End-to-end round-trip latency in ms. */
+  latencyMs: number;
+  /** Provider response identifier (e.g. Anthropic `msg_…`). `null` when unavailable. */
+  providerResponseId: string | null;
+  /** Redacted credential preview (last 4 chars) — confirms which entry was used. */
+  credentialPreview: string;
+  /** Resolution tier that produced the credential (`env`, `cred-file`, etc.). */
+  credentialSource: CredentialSourceWire;
+}
+
+/**
+ * Single `whoami` row — one entry per `RoleName`.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiEntry {
+  /** Role name (`'extraction' | 'consolidation' | ...`). */
+  role: string;
+  /** Provider that would be picked for this role. */
+  provider: ModelTransport;
+  /** Model that would be used. */
+  model: string;
+  /** Which config tier produced the resolution. */
+  source: ResolutionSource;
+  /** Credential label, when the role pinned a specific store entry. */
+  credentialLabel: string | undefined;
+  /** Resolution tier of the eventual credential, when one was reachable. */
+  credentialSource: CredentialSourceWire | undefined;
+  /** Whether a usable credential exists for this role. */
+  hasCredential: boolean;
+}
+
+/**
+ * Parameters for `llm.whoami` (query). Reserved for future filters.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiParams {
+  /** Optional role filter — when set, only that role is resolved. */
+  role?: string;
+}
+
+/**
+ * Result envelope for `llm.whoami`.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiResult {
+  /** One entry per role resolved (filtered by `params.role` when set). */
+  entries: LlmWhoamiEntry[];
+}

package/src/project-context.ts

@@ -0,0 +1,106 @@
+/**
+ * Project context — canonical ecosystem detection types.
+ *
+ * Defines the shape of `.cleo/project-context.json` and the smaller hint
+ * envelope consumed by release-flow / spawn-engine / codebase-map analyzers.
+ *
+ * Type-only: the detector implementation lives in `@cleocode/core/store/
+ * project-detect.ts`. Centralising the types here lets any package (release,
+ * studio, agents, …) reason about ecosystem signals without importing core.
+ *
+ * @adr ADR-013
+ */
+
+/** Detected project ecosystem. Matches the writer in `detectProjectType`. */
+export type ProjectType =
+  | 'node'
+  | 'python'
+  | 'rust'
+  | 'go'
+  | 'ruby'
+  | 'java'
+  | 'dotnet'
+  | 'bash'
+  | 'elixir'
+  | 'php'
+  | 'deno'
+  | 'bun'
+  | 'unknown';
+
+/** Detected test framework. */
+export type TestFramework =
+  | 'jest'
+  | 'vitest'
+  | 'mocha'
+  | 'pytest'
+  | 'bats'
+  | 'cargo'
+  | 'go'
+  | 'rspec'
+  | 'junit'
+  | 'playwright'
+  | 'cypress'
+  | 'ava'
+  | 'uvu'
+  | 'tap'
+  | 'node:test'
+  | 'deno'
+  | 'bun'
+  | 'custom'
+  | 'unknown';
+
+/** File-naming convention detected from source files. */
+export type FileNamingConvention = 'kebab-case' | 'snake_case' | 'camelCase' | 'PascalCase';
+
+/** Module import style. */
+export type ImportStyle = 'esm' | 'commonjs' | 'mixed';
+
+/** Schema-compliant project context for LLM agent consumption. */
+export interface ProjectContext {
+  schemaVersion: string;
+  detectedAt: string;
+  projectTypes: ProjectType[];
+  primaryType?: ProjectType;
+  monorepo: boolean;
+  testing?: {
+    framework?: TestFramework;
+    command?: string;
+    testFilePatterns?: string[];
+    directories?: {
+      unit?: string;
+      integration?: string;
+    };
+  };
+  build?: {
+    command?: string;
+    outputDir?: string;
+  };
+  directories?: {
+    source?: string;
+    tests?: string;
+    docs?: string;
+  };
+  conventions?: {
+    fileNaming?: FileNamingConvention;
+    importStyle?: ImportStyle;
+    typeSystem?: string;
+  };
+  llmHints?: {
+    preferredTestStyle?: string;
+    typeSystem?: string;
+    commonPatterns?: string[];
+    avoidPatterns?: string[];
+  };
+}
+
+/**
+ * Narrow subset of {@link ProjectContext} consumed by the release engine's
+ * workspace discovery and other ecosystem-aware flows. Avoid passing the
+ * full {@link ProjectContext} when only the three discriminating fields are
+ * needed.
+ */
+export interface EcosystemHint {
+  primaryType?: ProjectType;
+  projectTypes?: ProjectType[];
+  monorepo?: boolean;
+}

package/src/release/channel.ts

@@ -0,0 +1,21 @@
+/**
+ * Release channel contracts — types describing the npm dist-tag channel
+ * model used by the release pipeline.
+ *
+ * The implementation (branch→channel resolution, version validation) lives
+ * in `@cleocode/core/release/channel.ts`. The types live here so consumers
+ * can describe / validate the same shapes without depending on core.
+ *
+ * @adr ADR-063
+ */
+
+/** npm dist-tag channel for a release. */
+export type ReleaseChannel = 'latest' | 'beta' | 'alpha';
+
+/** Result of validating a version string against a channel's expectations. */
+export interface ChannelValidationResult {
+  valid: boolean;
+  expected?: string;
+  actual?: string;
+  message: string;
+}

package/src/release/github-pr.ts

@@ -0,0 +1,89 @@
+/**
+ * GitHub PR contracts — types describing the PR-creation surface used by
+ * the release pipeline.
+ *
+ * The implementation lives in `@cleocode/core/release/github-pr.ts`. The
+ * types live here so consumers (CLI, studio, downstream tools) can describe
+ * / validate the same shapes without depending on core.
+ *
+ * @adr ADR-063
+ */
+
+import type { ReleaseChannel } from './channel.js';
+
+/** Outcome of `detectBranchProtection`. */
+export interface BranchProtectionResult {
+  protected: boolean;
+  detectionMethod: 'gh-api' | 'push-dry-run' | 'unknown';
+  error?: string;
+}
+
+/** Input to `createPullRequest`. */
+export interface PRCreateOptions {
+  base: string;
+  head: string;
+  title: string;
+  body: string;
+  /**
+   * Requested PR labels. Non-existent ones are filtered or auto-created by
+   * the resolver; the engine never passes a bare list to `gh pr create`.
+   */
+  labels?: string[];
+  version: string;
+  epicId?: string;
+  projectRoot?: string;
+}
+
+/** How a PR-create attempt resolved. */
+export type PRMode = 'created' | 'manual' | 'skipped';
+
+/** Outcome of `createPullRequest`. */
+export interface PRResult {
+  mode: PRMode;
+  prUrl?: string;
+  prNumber?: number;
+  instructions?: string;
+  error?: string;
+}
+
+/** Parsed `owner/repo` pair extracted from a git remote URL. */
+export interface RepoIdentity {
+  owner: string;
+  repo: string;
+}
+
+/**
+ * Names of the labels CLEO knows how to auto-create when they are missing
+ * on a repo. Includes the universal `release` flag plus one label per npm
+ * dist-tag channel.
+ */
+export type CleoKnownLabel = 'release' | ReleaseChannel;
+
+/** Color + description used when CLEO auto-creates one of its known labels. */
+export interface LabelDefinition {
+  color: string;
+  description: string;
+}
+
+/** Static palette of CLEO-known labels keyed by label name. */
+export type CleoLabelPalette = Readonly<Record<CleoKnownLabel, LabelDefinition>>;
+
+/** Outcome of {@link ensureCleoLabelsExist}. */
+export interface LabelEnsureResult {
+  /** Labels that exist on the repo after this call (pre-existed or auto-created). */
+  ensured: string[];
+  /** Labels that this call created. */
+  created: string[];
+  /** Labels that could not be ensured (unknown to CLEO, or `gh label create` failed). */
+  missing: string[];
+}
+
+/** Outcome of {@link resolvePRLabels} — what to actually pass to `gh pr create`. */
+export interface PRLabelResolution {
+  /** Labels safe to pass to `gh pr create`. */
+  labels: string[];
+  /** Labels auto-created during resolution. */
+  created: string[];
+  /** Labels dropped because they could not be ensured. */
+  missing: string[];
+}