@h-rig/contracts 0.0.6-alpha.18 → 0.0.6-alpha.180

package/dist/src/drift.js

@@ -0,0 +1,69 @@
+// @bun
+// packages/contracts/src/drift.ts
+import { Schema as Schema2 } from "effect";
+
+// packages/contracts/src/baseSchemas.ts
+import { Schema } from "effect";
+var TrimmedString = Schema.Trim;
+var TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
+var NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+var PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+var IsoDateTime = Schema.String;
+var makeEntityId = (brand) => TrimmedNonEmptyString.pipe(Schema.brand(brand));
+var ThreadId = makeEntityId("ThreadId");
+var ProjectId = makeEntityId("ProjectId");
+var WorkspaceId = makeEntityId("WorkspaceId");
+var GraphId = makeEntityId("GraphId");
+var TaskId = makeEntityId("TaskId");
+var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
+var EngineRuntimeId = makeEntityId("EngineRuntimeId");
+var ConversationId = makeEntityId("ConversationId");
+var ActionId = makeEntityId("ActionId");
+var ArtifactId = makeEntityId("ArtifactId");
+var WorktreeId = makeEntityId("WorktreeId");
+var ValidationResultId = makeEntityId("ValidationResultId");
+var ReviewResultId = makeEntityId("ReviewResultId");
+var CommandId = makeEntityId("CommandId");
+var EventId = makeEntityId("EventId");
+var MessageId = makeEntityId("MessageId");
+var TurnId = makeEntityId("TurnId");
+var ProviderItemId = makeEntityId("ProviderItemId");
+var RuntimeSessionId = makeEntityId("RuntimeSessionId");
+var RuntimeItemId = makeEntityId("RuntimeItemId");
+var RuntimeRequestId = makeEntityId("RuntimeRequestId");
+var RuntimeTaskId = makeEntityId("RuntimeTaskId");
+var ApprovalRequestId = makeEntityId("ApprovalRequestId");
+var CheckpointRef = makeEntityId("CheckpointRef");
+var RemoteEndpointId = makeEntityId("RemoteEndpointId");
+
+// packages/contracts/src/drift.ts
+var DriftKind = Schema2.Literals([
+  "deleted-reference",
+  "stale-anchor",
+  "semantic-mismatch",
+  "issue-mismatch"
+]);
+var DriftConfidence = Schema2.Literals(["high", "medium", "low"]);
+var DriftFinding = Schema2.Struct({
+  kind: DriftKind,
+  docPath: TrimmedNonEmptyString,
+  line: Schema2.NullOr(PositiveInt),
+  reference: Schema2.NullOr(TrimmedNonEmptyString),
+  detail: Schema2.String,
+  confidence: DriftConfidence
+});
+var DriftReport = Schema2.Struct({
+  generatedAt: IsoDateTime,
+  scanned: NonNegativeInt,
+  degraded: Schema2.Boolean,
+  findings: Schema2.Array(DriftFinding)
+});
+export {
+  DriftReport,
+  DriftKind,
+  DriftFinding,
+  DriftConfidence
+};

package/dist/src/editor.d.ts

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+export declare const EDITORS: readonly [{
+    readonly id: "cursor";
+    readonly label: "Cursor";
+    readonly command: "cursor";
+}, {
+    readonly id: "vscode";
+    readonly label: "VS Code";
+    readonly command: "code";
+}, {
+    readonly id: "zed";
+    readonly label: "Zed";
+    readonly command: "zed";
+}, {
+    readonly id: "file-manager";
+    readonly label: "File Manager";
+    readonly command: null;
+}];
+export declare const EditorId: Schema.Literals<("cursor" | "vscode" | "zed" | "file-manager")[]>;
+export type EditorId = typeof EditorId.Type;
+export declare const OpenInEditorInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly editor: Schema.Literals<("cursor" | "vscode" | "zed" | "file-manager")[]>;
+}>;
+export type OpenInEditorInput = typeof OpenInEditorInput.Type;

package/dist/src/editor.js

@@ -16,6 +16,9 @@ var WorkspaceId = makeEntityId("WorkspaceId");
 var GraphId = makeEntityId("GraphId");
 var TaskId = makeEntityId("TaskId");
 var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
 var EngineRuntimeId = makeEntityId("EngineRuntimeId");
 var ConversationId = makeEntityId("ConversationId");
 var ActionId = makeEntityId("ActionId");

package/dist/src/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    /**
+     * Optional remediation hint. Rendered on its own `Next: <hint>` line (and
+     * carried in the `--json` error payload) so a failure can name the next
+     * command to run. Pure vocab — the exec machinery (now in @rig/guard-plugin)
+     * throws this with a hint without importing a CLI-seed error class.
+     */
+    readonly hint?: string;
+    constructor(message: string, exitCode?: number, options?: {
+        readonly hint?: string;
+    });
+}

package/dist/src/errors.js

@@ -0,0 +1,17 @@
+// @bun
+// packages/contracts/src/errors.ts
+class CliError extends Error {
+  exitCode;
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
+export {
+  CliError
+};

package/dist/src/git.d.ts

@@ -0,0 +1,152 @@
+import { Schema } from "effect";
+export declare const GitStackedAction: Schema.Literals<readonly ["commit", "commit_push", "commit_push_pr"]>;
+export type GitStackedAction = typeof GitStackedAction.Type;
+export type GitWorkingTreeFileStatus = "added" | "copied" | "deleted" | "modified" | "renamed" | "type_changed" | "untracked" | "conflicted" | "unknown";
+export interface GitWorkingTreeFileChange {
+    readonly path: string;
+    readonly status: GitWorkingTreeFileStatus;
+    readonly staged: boolean;
+    readonly unstaged: boolean;
+    readonly previousPath?: string;
+}
+export declare const GitBranch: Schema.Struct<{
+    readonly name: Schema.Trim;
+    readonly isRemote: Schema.optional<Schema.Boolean>;
+    readonly remoteName: Schema.optional<Schema.Trim>;
+    readonly current: Schema.Boolean;
+    readonly isDefault: Schema.Boolean;
+    readonly worktreePath: Schema.NullOr<Schema.Trim>;
+}>;
+export type GitBranch = typeof GitBranch.Type;
+export declare const GitStatusInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+}>;
+export type GitStatusInput = typeof GitStatusInput.Type;
+export declare const GitPullInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+}>;
+export type GitPullInput = typeof GitPullInput.Type;
+export declare const GitReadWorkingTreePatchInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly relativePath: Schema.optional<Schema.Trim>;
+}>;
+export type GitReadWorkingTreePatchInput = typeof GitReadWorkingTreePatchInput.Type;
+export declare const GitRunStackedActionInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly action: Schema.Literals<readonly ["commit", "commit_push", "commit_push_pr"]>;
+    readonly commitMessage: Schema.optional<Schema.Trim>;
+    readonly featureBranch: Schema.optional<Schema.Boolean>;
+}>;
+export type GitRunStackedActionInput = typeof GitRunStackedActionInput.Type;
+export declare const GitListBranchesInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+}>;
+export type GitListBranchesInput = typeof GitListBranchesInput.Type;
+export declare const GitCreateWorktreeInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly branch: Schema.Trim;
+    readonly newBranch: Schema.Trim;
+    readonly path: Schema.NullOr<Schema.Trim>;
+}>;
+export type GitCreateWorktreeInput = typeof GitCreateWorktreeInput.Type;
+export declare const GitRemoveWorktreeInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly path: Schema.Trim;
+    readonly force: Schema.optional<Schema.Boolean>;
+}>;
+export type GitRemoveWorktreeInput = typeof GitRemoveWorktreeInput.Type;
+export declare const GitCreateBranchInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly branch: Schema.Trim;
+}>;
+export type GitCreateBranchInput = typeof GitCreateBranchInput.Type;
+export declare const GitCheckoutInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly branch: Schema.Trim;
+}>;
+export type GitCheckoutInput = typeof GitCheckoutInput.Type;
+export declare const GitInitInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+}>;
+export type GitInitInput = typeof GitInitInput.Type;
+export declare const GitStatusResult: Schema.Struct<{
+    readonly branch: Schema.NullOr<Schema.Trim>;
+    readonly hasWorkingTreeChanges: Schema.Boolean;
+    readonly workingTree: Schema.Struct<{
+        readonly files: Schema.$Array<Schema.Struct<{
+            readonly path: Schema.Trim;
+            readonly insertions: Schema.Int;
+            readonly deletions: Schema.Int;
+        }>>;
+        readonly insertions: Schema.Int;
+        readonly deletions: Schema.Int;
+    }>;
+    readonly hasUpstream: Schema.Boolean;
+    readonly aheadCount: Schema.Int;
+    readonly behindCount: Schema.Int;
+    readonly pr: Schema.NullOr<Schema.Struct<{
+        readonly number: Schema.Int;
+        readonly title: Schema.Trim;
+        readonly url: Schema.String;
+        readonly baseBranch: Schema.Trim;
+        readonly headBranch: Schema.Trim;
+        readonly state: Schema.Literals<readonly ["open", "closed", "merged"]>;
+    }>>;
+}>;
+export type GitStatusResult = typeof GitStatusResult.Type;
+export declare const GitListBranchesResult: Schema.Struct<{
+    readonly branches: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.Trim;
+        readonly isRemote: Schema.optional<Schema.Boolean>;
+        readonly remoteName: Schema.optional<Schema.Trim>;
+        readonly current: Schema.Boolean;
+        readonly isDefault: Schema.Boolean;
+        readonly worktreePath: Schema.NullOr<Schema.Trim>;
+    }>>;
+    readonly isRepo: Schema.Boolean;
+}>;
+export type GitListBranchesResult = typeof GitListBranchesResult.Type;
+export declare const GitCreateWorktreeResult: Schema.Struct<{
+    readonly worktree: Schema.Struct<{
+        readonly path: Schema.Trim;
+        readonly branch: Schema.Trim;
+    }>;
+}>;
+export type GitCreateWorktreeResult = typeof GitCreateWorktreeResult.Type;
+export declare const GitRunStackedActionResult: Schema.Struct<{
+    readonly action: Schema.Literals<readonly ["commit", "commit_push", "commit_push_pr"]>;
+    readonly branch: Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["created", "skipped_not_requested"]>;
+        readonly name: Schema.optional<Schema.Trim>;
+    }>;
+    readonly commit: Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["created", "skipped_no_changes"]>;
+        readonly commitSha: Schema.optional<Schema.Trim>;
+        readonly subject: Schema.optional<Schema.Trim>;
+    }>;
+    readonly push: Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["pushed", "skipped_not_requested", "skipped_up_to_date"]>;
+        readonly branch: Schema.optional<Schema.Trim>;
+        readonly upstreamBranch: Schema.optional<Schema.Trim>;
+        readonly setUpstream: Schema.optional<Schema.Boolean>;
+    }>;
+    readonly pr: Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["created", "opened_existing", "skipped_not_requested"]>;
+        readonly url: Schema.optional<Schema.String>;
+        readonly number: Schema.optional<Schema.Int>;
+        readonly baseBranch: Schema.optional<Schema.Trim>;
+        readonly headBranch: Schema.optional<Schema.Trim>;
+        readonly title: Schema.optional<Schema.Trim>;
+    }>;
+}>;
+export type GitRunStackedActionResult = typeof GitRunStackedActionResult.Type;
+export declare const GitPullResult: Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["pulled", "skipped_up_to_date"]>;
+    readonly branch: Schema.Trim;
+    readonly upstreamBranch: Schema.NullOr<Schema.Trim>;
+}>;
+export type GitPullResult = typeof GitPullResult.Type;
+export declare const GitReadWorkingTreePatchResult: Schema.Struct<{
+    readonly diff: Schema.String;
+}>;
+export type GitReadWorkingTreePatchResult = typeof GitReadWorkingTreePatchResult.Type;

package/dist/src/git.js

@@ -16,6 +16,9 @@ var WorkspaceId = makeEntityId("WorkspaceId");
 var GraphId = makeEntityId("GraphId");
 var TaskId = makeEntityId("TaskId");
 var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
 var EngineRuntimeId = makeEntityId("EngineRuntimeId");
 var ConversationId = makeEntityId("ConversationId");
 var ActionId = makeEntityId("ActionId");

package/dist/src/github.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Pure GitHub-provider contract types.
+ *
+ * This is the neutral home for the GitHub SCM-provider data model so that the
+ * @rig/github-provider-plugin (which owns the implementation), the
+ * @rig/task-sources-plugin (which consumes the credential-provider abstraction),
+ * and any future dumb runtime substrate can all reference the same vocabulary
+ * without a substrate->plugin import cycle. These types carry no behaviour and
+ * import nothing — exactly like `memory.ts` / `lifecycle-capabilities.ts`.
+ *
+ * The plugin registers its executable GitHub-provider service under
+ * {@link GITHUB_PROVIDER_CAPABILITY_ID} on `contributes.capabilities[].run`; a
+ * dumb substrate consumer would resolve it by id from a plugin host built from
+ * the project's rig.config via a typed port — the same seam shape proven by
+ * the memory/lifecycle capability ports. (Today the only substrate-facing
+ * GitHub primitive — reading a token from an env-pointed state file — stays in
+ * @rig/runtime/control-plane/github/token-env as a dumb reader; the policy that
+ * produces that token lives in this plugin.)
+ */
+import type { CapabilityId } from "./capability-id";
+/** Capability id the GitHub-provider plugin registers its service factory under. */
+export declare const GITHUB_PROVIDER_CAPABILITY_ID = "github.provider";
+export type GitHubCredentialPurpose = "selected-repo" | "admin-fallback";
+export type GitHubCredentialSource = "signed-in-user" | "host-admin-fallback";
+export type GitHubCredentialProviderOptions = {
+    /**
+     * Session-scoped tokens keyed as:
+     * `user:<userId>|repo:<owner>/<repo>|workspace:<workspaceId>`.
+     * This intentionally models the app/session auth boundary; host tokens are
+     * not used for normal selected-repo operations.
+     */
+    sessionTokens?: Readonly<Record<string, string>>;
+    hostToken?: string | null;
+};
+export type ResolveGitHubTokenInput = {
+    owner: string;
+    repo: string;
+    workspaceId: string;
+    userId?: string;
+    purpose: GitHubCredentialPurpose;
+};
+export type ResolvedGitHubToken = {
+    token: string;
+    source: GitHubCredentialSource;
+};
+export interface GitHubCredentialProvider {
+    resolveGitHubToken(input: ResolveGitHubTokenInput): Promise<ResolvedGitHubToken>;
+}
+/** Options the state-file-backed credential provider accepts. */
+export type GitHubStateCredentialProviderOptions = {
+    stateFile?: string;
+    stateDir?: string;
+};
+export type GitHubAuthStatus = {
+    readonly signedIn: boolean;
+    readonly login: string | null;
+    readonly userId: string | null;
+    readonly scopes: readonly string[];
+    readonly selectedRepo: string | null;
+    readonly oauthConfigured: boolean;
+    readonly tokenSource: "oauth-device" | "manual-token" | "env" | null;
+};
+export type GitHubUserInfo = {
+    readonly login: string;
+    readonly id: string;
+    readonly scopes?: readonly string[];
+};
+export type GitHubRepositoryProbe = {
+    readonly ok: boolean;
+    readonly owner: string;
+    readonly repo: string;
+    readonly status: number;
+    readonly authenticated: boolean;
+    readonly authenticationRequired: boolean;
+    readonly fullName: string | null;
+    readonly private: boolean | null;
+    readonly message: string;
+    readonly scopes: readonly string[];
+};
+export interface GitHubProjectSummary {
+    id: string;
+    number: number;
+    title: string;
+    url?: string;
+}
+export interface GitHubProjectStatusField {
+    id: string;
+    name: string;
+    options: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export type GitHubDeviceFlowPending = {
+    readonly pollId: string;
+    readonly deviceCode: string;
+    readonly expiresAt: string;
+    readonly intervalSeconds: number;
+};
+export type GitHubAuthStore = {
+    readonly stateFile: string;
+    readonly status: (options?: {
+        oauthConfigured?: boolean;
+    }) => GitHubAuthStatus;
+    readonly readToken: () => string | null;
+    readonly saveToken: (input: {
+        readonly token: string;
+        readonly tokenSource: "oauth-device" | "manual-token";
+        readonly login?: string | null;
+        readonly userId?: string | null;
+        readonly scopes?: readonly string[];
+        readonly selectedRepo?: string | null;
+    }) => void;
+    readonly createApiSession: () => {
+        token: string;
+        login: string | null;
+        userId: string | null;
+    };
+    readonly readApiSession: (token: string) => {
+        login: string | null;
+        userId: string | null;
+    } | null;
+    readonly copyToProjectRoot: (projectRoot: string) => void;
+    readonly copyToLocalProjectRoot: (projectRoot: string) => void;
+    readonly savePendingDevice: (input: GitHubDeviceFlowPending) => void;
+    readonly saveSelectedRepo: (selectedRepo: string | null) => void;
+    readonly readPendingDevice: (pollId: string) => GitHubDeviceFlowPending | null;
+    readonly clearPendingDevice: (pollId?: string) => void;
+};
+export type GitHubFormPostResult = {
+    readonly status: number;
+    readonly payload: Record<string, unknown>;
+};
+export type GitHubFormPoster = (endpoint: string, body: Record<string, string>) => Promise<GitHubFormPostResult>;
+export type GitHubUserFetcher = (token: string) => Promise<GitHubUserInfo>;
+export type GitHubGraphQLFetch = (query: string, variables: Record<string, unknown>, token: string) => Promise<unknown>;
+export type GitHubTokenSaveResult = {
+    readonly ok: true;
+} & GitHubAuthStatus;
+export type GitHubDeviceFlowStartResult = {
+    readonly ok: true;
+    readonly pollId: string;
+    readonly userCode: string | null;
+    readonly verificationUri: string | null;
+    readonly expiresIn: number;
+    readonly intervalSeconds: number;
+};
+export type GitHubDeviceFlowPollResult = ({
+    readonly ok: true;
+    readonly status: "signed-in";
+} & GitHubAuthStatus) | {
+    readonly ok: false;
+    readonly status: "expired";
+    readonly error: string;
+} | {
+    readonly ok: false;
+    readonly status: "pending";
+    readonly intervalSeconds: number;
+} | {
+    readonly ok: false;
+    readonly status: "slow-down";
+    readonly intervalSeconds: number;
+} | {
+    readonly ok: false;
+    readonly status: "error";
+    readonly error: string;
+};
+export type GitHubRepoPermissionsResult = {
+    readonly ok: false;
+    readonly signedIn: false;
+    readonly canOpenPullRequest: false;
+    readonly reason: "not-authenticated";
+} | {
+    readonly ok: true;
+    readonly signedIn: true;
+    readonly login: string | null;
+    readonly scopes: readonly string[];
+    readonly canOpenPullRequest: boolean;
+    readonly pullRequests: boolean;
+    readonly push: boolean;
+    readonly reason: "stored-token" | "token-scope-unverified";
+};
+/**
+ * The executable surface the GitHub-provider capability `run()` returns. The
+ * provider owns the GitHub implementation; sibling plugins resolve this service
+ * from the configured project host instead of importing the provider package.
+ */
+export interface GitHubProviderService {
+    detectGhLogin(input?: {
+        readonly projectRoot?: string | undefined;
+    }): string | null;
+    readGhAuthToken(input?: {
+        readonly projectRoot?: string | undefined;
+    }): string;
+    refreshGhProjectScopesAndReadToken(input?: {
+        readonly projectRoot?: string | undefined;
+        readonly scopes?: readonly string[] | undefined;
+    }): string | null;
+    createCredentialProvider(options?: GitHubCredentialProviderOptions): GitHubCredentialProvider;
+    createEnvGitHubCredentialProvider(): GitHubCredentialProvider;
+    createStateGitHubCredentialProvider(options?: GitHubStateCredentialProviderOptions): GitHubCredentialProvider;
+    createGitHubAuthStore(projectRoot: string): GitHubAuthStore;
+    resolveGitHubAuthStatus(input: {
+        readonly projectRoot: string;
+        readonly oauthConfigured?: boolean;
+    }): GitHubAuthStatus;
+    saveGitHubTokenForProject(input: {
+        readonly projectRoot: string;
+        readonly token: string;
+        readonly tokenSource?: "oauth-device" | "manual-token";
+        readonly selectedRepo?: string | null;
+        readonly fetchUser?: GitHubUserFetcher;
+    }): Promise<GitHubTokenSaveResult>;
+    beginGitHubDeviceFlow(input: {
+        readonly projectRoot: string;
+        readonly clientId: string;
+        readonly scope?: string;
+        readonly selectedRepo?: string | null;
+        readonly postForm?: GitHubFormPoster;
+    }): Promise<GitHubDeviceFlowStartResult>;
+    pollGitHubDeviceFlow(input: {
+        readonly projectRoot: string;
+        readonly clientId: string;
+        readonly pollId: string;
+        readonly selectedRepo?: string | null;
+        readonly postForm?: GitHubFormPoster;
+        readonly fetchUser?: GitHubUserFetcher;
+    }): Promise<GitHubDeviceFlowPollResult>;
+    checkGitHubRepoPermissions(input: {
+        readonly projectRoot: string;
+        readonly oauthConfigured?: boolean;
+    }): GitHubRepoPermissionsResult;
+    probeGitHubRepository(input: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly token: string | null;
+        readonly scopes: readonly string[];
+        readonly fetchRepository?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    }): Promise<GitHubRepositoryProbe>;
+    listGitHubProjects(input: {
+        readonly owner: string;
+        readonly token: string;
+        readonly first?: number;
+        readonly fetchGraphQL?: GitHubGraphQLFetch;
+    }): Promise<GitHubProjectSummary[]>;
+    resolveProjectStatusField(input: {
+        readonly projectId: string;
+        readonly token: string;
+        readonly fetchGraphQL?: GitHubGraphQLFetch;
+    }): Promise<GitHubProjectStatusField>;
+}
+/** The capability `run` shape the plugin registers: a zero-arg service factory. */
+export type GitHubProviderServiceRun = () => GitHubProviderService;
+/**
+ * Typed capability id, phantom-typed with {@link GitHubProviderService} so
+ * consumers (task-sources/doctor/init) resolve it off the host with no cast.
+ * String value is {@link GITHUB_PROVIDER_CAPABILITY_ID}.
+ */
+export declare const GITHUB_PROVIDER: CapabilityId<GitHubProviderService>;
+/** Capability id the issue-triage provider registers its runner under. */
+export declare const ISSUE_TRIAGE_CAPABILITY_ID = "cap:issue-triage";
+/** Pure input to a triage pass: which project + an optional reason label. */
+export type IssueTriageInput = {
+    readonly projectRoot: string;
+    readonly reason?: string;
+};
+/**
+ * Pure summary of a triage pass. Contracts-owned mirror of the plugin's
+ * `IssueAnalysisTriageRunResult` so substrate consumers read the outcome
+ * without importing the plugin. Structurally compatible with the impl result.
+ */
+export type IssueTriageResult = {
+    readonly ok: true;
+    readonly enabled: boolean;
+    readonly reason: string;
+    readonly sourceId: string | null;
+    readonly sourceKind: string | null;
+    readonly analyzedIssues: number;
+    readonly metadataPatches: number;
+    readonly labelsAdded: number;
+    readonly labelsRemoved: number;
+    readonly generatedIssues: number;
+    readonly writeBackRefreshes: number;
+    readonly refreshedIssueCount: number | null;
+    readonly skippedReason?: "no-config" | "disabled";
+};
+/** The cohesive triage operation the CLI surface depends on. Async (does IO). */
+export interface IssueTriageService {
+    runTriage(input: IssueTriageInput): Promise<IssueTriageResult>;
+}
+/**
+ * Typed capability id, phantom-typed with {@link IssueTriageService}. String
+ * value is {@link ISSUE_TRIAGE_CAPABILITY_ID}.
+ */
+export declare const ISSUE_TRIAGE: CapabilityId<IssueTriageService>;

package/dist/src/github.js

@@ -0,0 +1,17 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/github.ts
+var GITHUB_PROVIDER_CAPABILITY_ID = "github.provider";
+var GITHUB_PROVIDER = makeCapabilityId(GITHUB_PROVIDER_CAPABILITY_ID);
+var ISSUE_TRIAGE_CAPABILITY_ID = "cap:issue-triage";
+var ISSUE_TRIAGE = makeCapabilityId(ISSUE_TRIAGE_CAPABILITY_ID);
+export {
+  ISSUE_TRIAGE_CAPABILITY_ID,
+  ISSUE_TRIAGE,
+  GITHUB_PROVIDER_CAPABILITY_ID,
+  GITHUB_PROVIDER
+};