@kici-dev/sdk 0.4.0 → 0.6.0

package/dist/agent-cloud-init.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @deprecated Pass a claim code (ClaimCodeCredentials) so the token never
+ * transits cloud-init. Removed at v1.0.0.
+ */
+export interface CloudInitCredentials {
+    agentToken: string;
+    agentId: string;
+    orchestratorUrl: string;
+    labels: string[];
+}
+/** Preferred: the agent self-claims from a single-use code; the token is minted in-instance. */
+export interface ClaimCodeCredentials {
+    claimCode: string;
+    agentId: string;
+    orchestratorUrl: string;
+    labels: string[];
+}
+/** Either credential shape accepted by `buildAgentCloudInit`. */
+export type AgentCloudInitCredentials = CloudInitCredentials | ClaimCodeCredentials;
+/** How the agent binary is delivered onto the instance. */
+export type AgentDeliveryMode = 'container' | 'payload';
+/** How the rendered `user_data` string is encoded before it is returned. */
+export type UserDataEncoding = 'raw' | 'base64';
+/** A cloud-init `write_files` entry the caller adds. */
+export interface CloudInitWriteFile {
+    path: string;
+    content: string;
+    permissions?: string;
+    owner?: string;
+}
+export interface AgentCloudInitOptions {
+    /** Hard lifetime cap (minutes) after which the instance powers itself off (L2). */
+    maxLifetimeMinutes: number;
+    /** 'container' (docker run the published agent image) | 'payload' (fetch from orchestrator). */
+    deliveryMode?: AgentDeliveryMode;
+    /** Container image ref (container mode). */
+    agentImage?: string;
+    /** Escape hatch: fully override the agent-start command (ignores deliveryMode/agentImage). */
+    startCommand?: string;
+    /** apt/yum packages → cloud-init `packages:` (unioned with the base). */
+    packages?: string[];
+    /** Extra `write_files` entries (the reserved env-file path is rejected). */
+    writeFiles?: CloudInitWriteFile[];
+    /** runcmd lines injected BEFORE the agent starts. */
+    runcmdBefore?: string[];
+    /** runcmd lines injected AFTER the agent starts. */
+    runcmdAfter?: string[];
+    /** Extra env appended to the agent env file (keys validated, newline values rejected). */
+    agentEnv?: Record<string, string>;
+    /** Raw cloud-config YAML to merge everything into (users, ssh, apt, mounts, bootcmd, …). */
+    baseCloudConfig?: string;
+    /**
+     * Encoding of the returned `user_data` string. `'raw'` (the default) returns
+     * the plain `#cloud-config` text — what Hetzner `user_data` expects. `'base64'`
+     * returns the same text base64-encoded, the form AWS EC2 `UserData` and Azure
+     * `customData` expect.
+     */
+    userDataEncoding?: UserDataEncoding;
+}
+/**
+ * Build the cloud-config `user_data` string. In the token form the agent token
+ * appears only in the reserved env-file write entry (`0600`, root-only); the
+ * claim-code form keeps the token off the provisioning channel entirely.
+ */
+export declare function buildAgentCloudInit(creds: AgentCloudInitCredentials, options: AgentCloudInitOptions): string;
+//# sourceMappingURL=agent-cloud-init.d.ts.map

package/dist/agent-cloud-init.js

@@ -0,0 +1,128 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { parse, stringify } from "yaml";
+//#region src/agent-cloud-init.ts
+/**
+* Cloud-init `user_data` builder for a scaler-provisioned KiCI agent.
+*
+* Renders a `#cloud-config` that installs + starts the agent with the claimed
+* ephemeral credentials, plus teardown layer L2 — an in-instance max-lifetime
+* self-poweroff. The agent token is written ONLY into a root-only `0600` env
+* file; it never appears in a comment, a process argument, or any other file.
+*/
+const AGENT_ENV_FILE = "/etc/kici-agent.env";
+const DEFAULT_AGENT_IMAGE = "quay.io/kici-dev/kici-agent:latest";
+/**
+* The credential-specific env lines. The claim-code form emits a single-use
+* code the agent exchanges for its own token in-instance; the token form emits
+* the token directly (the ONLY place the token appears).
+*/
+function credentialEnvLines(creds) {
+	if ("claimCode" in creds) return [
+		`KICI_ORCHESTRATOR_URL=${creds.orchestratorUrl}`,
+		`KICI_SCALER_CLAIM_CODE=${creds.claimCode}`,
+		`KICI_AGENT_ID=${creds.agentId}`,
+		`KICI_LABELS=${creds.labels.join(",")}`
+	];
+	return [
+		`KICI_ORCHESTRATOR_URL=${creds.orchestratorUrl}`,
+		`KICI_AGENT_TOKEN=${creds.agentToken}`,
+		`KICI_AGENT_ID=${creds.agentId}`,
+		`KICI_LABELS=${creds.labels.join(",")}`
+	];
+}
+/** Render the agent env-file content (the ONLY place the token appears, in the token form). */
+function renderEnvFileContent(creds, agentEnv) {
+	return `${[
+		...credentialEnvLines(creds),
+		"KICI_SCALER_MANAGED=1",
+		...Object.entries(agentEnv ?? {}).map(([k, v]) => `${k}=${v}`)
+	].join("\n")}\n`;
+}
+/** Dedupe a list preserving first-seen order. */
+function dedupe(items) {
+	return [...new Set(items)];
+}
+/** POSIX env-name shape: a letter or underscore, then letters/digits/underscores. */
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Reject agentEnv keys that are not POSIX env names and values carrying a newline. */
+function validateAgentEnv(agentEnv) {
+	for (const [key, value] of Object.entries(agentEnv ?? {})) {
+		if (!ENV_NAME_RE.test(key)) throw new Error(`buildAgentCloudInit: invalid agentEnv key "${key}" (must be a POSIX env name)`);
+		if (value.includes("\n")) throw new Error(`buildAgentCloudInit: agentEnv value for "${key}" must not contain a newline`);
+	}
+}
+/** Reject any caller/base write_files entry targeting the reserved env-file path. */
+function assertNoReservedWrite(writeFiles, where) {
+	for (const wf of writeFiles ?? []) if (wf.path === AGENT_ENV_FILE) throw new Error(`buildAgentCloudInit: ${where} may not write the reserved path ${AGENT_ENV_FILE}`);
+}
+/** Parse + shape-check a caller-supplied base cloud-config. */
+function parseBase(baseCloudConfig) {
+	let parsed;
+	try {
+		parsed = parse(baseCloudConfig);
+	} catch (err) {
+		throw new Error(`buildAgentCloudInit: baseCloudConfig is not valid YAML: ${err.message}`);
+	}
+	if (parsed == null) return {};
+	if (typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("buildAgentCloudInit: baseCloudConfig must be a cloud-config mapping");
+	const base = parsed;
+	for (const key of [
+		"packages",
+		"runcmd",
+		"write_files"
+	]) if (base[key] !== void 0 && !Array.isArray(base[key])) throw new Error(`buildAgentCloudInit: baseCloudConfig.${key} must be a list`);
+	return base;
+}
+/** Render the command that starts the agent for the chosen delivery mode. */
+function renderStartCommand(opts) {
+	if (opts.startCommand) return opts.startCommand;
+	if (opts.deliveryMode === "payload") return "/usr/local/bin/kici-agent-bootstrap";
+	const image = opts.agentImage ?? DEFAULT_AGENT_IMAGE;
+	return `docker run -d --restart=no --name kici-agent --network host --env-file ${AGENT_ENV_FILE} ${image}`;
+}
+/**
+* Build the cloud-config `user_data` string. In the token form the agent token
+* appears only in the reserved env-file write entry (`0600`, root-only); the
+* claim-code form keeps the token off the provisioning channel entirely.
+*/
+function buildAgentCloudInit(creds, options) {
+	validateAgentEnv(options.agentEnv);
+	assertNoReservedWrite(options.writeFiles, "writeFiles");
+	const cap = Math.max(1, Math.floor(options.maxLifetimeMinutes));
+	const base = options.baseCloudConfig ? parseBase(options.baseCloudConfig) : {};
+	assertNoReservedWrite(base.write_files, "baseCloudConfig");
+	const baseWriteFiles = base.write_files ?? [];
+	const baseRuncmd = base.runcmd ?? [];
+	const basePackages = base.packages ?? [];
+	const envFile = {
+		path: AGENT_ENV_FILE,
+		permissions: "0600",
+		owner: "root:root",
+		content: renderEnvFileContent(creds, options.agentEnv)
+	};
+	const pkgs = dedupe([...basePackages, ...options.packages ?? []]);
+	const model = {
+		...base,
+		write_files: [
+			...baseWriteFiles,
+			envFile,
+			...options.writeFiles ?? []
+		],
+		runcmd: [
+			...baseRuncmd,
+			...options.runcmdBefore ?? [],
+			`systemd-run --on-active=${cap}m --timer-property=AccuracySec=1s /sbin/poweroff`,
+			renderStartCommand(options),
+			...options.runcmdAfter ?? []
+		]
+	};
+	if (pkgs.length > 0) model.packages = pkgs;
+	else delete model.packages;
+	const cloudConfig = `#cloud-config\n${stringify(model, { lineWidth: 0 })}`;
+	if (options.userDataEncoding === "base64") return Buffer.from(cloudConfig, "utf8").toString("base64");
+	return cloudConfig;
+}
+//#endregion
+export { buildAgentCloudInit };
+
+//# sourceMappingURL=agent-cloud-init.js.map

package/dist/api-types.d.ts

@@ -9,6 +9,7 @@
  * 2. Register the handler in the orchestrator's AgentApiRegistry
  */
 import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { GitApi } from './git-types.js';
 import type { HostInventoryEntry, InventorySelector } from '@kici-dev/engine';
 export type { OidcTokenResult };
 export type { HostInventoryEntry, InventorySelector };
@@ -136,6 +137,27 @@ export interface BootstrapApi {
         restaged: boolean;
     }>;
 }
+/** Credentials a provisioning workflow uses to boot a scaler-provisioned agent. */
+export interface ClaimedAgentCredentials {
+    /** Single-use ephemeral agent token the provisioned instance registers with. */
+    agentToken: string;
+    /** Agent id the instance must register with (chosen by the scaler). */
+    agentId: string;
+    /** Orchestrator WS URL the instance connects back to. */
+    orchestratorUrl: string;
+    /** Labels the token authorizes. */
+    labels: string[];
+}
+export interface ScalerApi {
+    /**
+     * Exchange a single-use claim code — delivered on a `kici.scaler.scale-up`
+     * event to a provisioning workflow — for freshly minted ephemeral agent
+     * credentials. Boot a cloud instance whose agent registers with the returned
+     * `agentId` and `agentToken`, and the pending bound job runs on it. The token
+     * is minted lazily on this call and never appears in the persisted event log.
+     */
+    claimAgentCredentials(claimCode: string): Promise<ClaimedAgentCredentials>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
@@ -143,10 +165,14 @@ export interface KiciApi {
     inventory: InventoryApi;
     /** Request short-lived OIDC ID tokens for the current job (build provenance). */
     oidc: OidcApi;
+    /** Forge-typed git credentials for the current job. */
+    git: GitApi;
     /** Host-lifecycle operations on the agent's own host (e.g. reboot). */
     host: HostApi;
     /** Fresh-box bootstrap bring-up (init-runner over SSH, pre-boot unlock). */
     bootstrap: BootstrapApi;
+    /** Event-scaler provisioning: claim ephemeral agent credentials. */
+    scaler: ScalerApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.

package/dist/api-types.js

@@ -1,5 +1,6 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
+import { GIT_CREDENTIAL_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/git-credential-relay";
 //#region src/api-types.ts
 /**
 * Typed KiCI API available to workflows via ctx.kici.
@@ -37,6 +38,23 @@ function buildKiciApi(transport, jobCtx) {
 				audience: opts.audience
 			});
 		} },
+		git: { github: { getToken: (opts) => {
+			if (!jobCtx) return Promise.reject(/* @__PURE__ */ new Error("ctx.kici.git.github.getToken() is only available inside a running job step"));
+			if (opts.repositories.length === 0) return Promise.reject(/* @__PURE__ */ new Error("git.github.getToken requires at least one repository"));
+			return transport(GIT_CREDENTIAL_REQUEST_METHOD, {
+				jobId: jobCtx.jobId,
+				repositories: opts.repositories,
+				permissions: opts.permissions,
+				...opts.credential ? { credential: opts.credential } : {}
+			}).then((raw) => {
+				const r = raw;
+				return {
+					token: r.secret,
+					expiresAt: r.expiresAt,
+					granted: r.grant
+				};
+			});
+		} } },
 		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) },
 		bootstrap: {
 			ensureInitRunner: (targetAgentId) => transport("kici.ensureInitRunner", { targetAgentId }),
@@ -46,7 +64,8 @@ function buildKiciApi(transport, jobCtx) {
 			}),
 			agentVersionStatus: (targetAgentId) => transport("kici.agentVersionStatus", { targetAgentId }),
 			restageAgent: (targetAgentId) => transport("kici.restageAgent", { targetAgentId })
-		}
+		},
+		scaler: { claimAgentCredentials: (claimCode) => transport("scaler.claim-credentials", { claimCode }) }
 	};
 }
 //#endregion

package/dist/context.d.ts

@@ -189,6 +189,27 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * Defaults to false for backward compatibility.
      */
     isTestRun: boolean;
+    /**
+     * The job's own checked-out repository.
+     *
+     * Present for every job that checks out (unlike `sourceRepo` / `workflowRepo`,
+     * which exist only for a global workflow). `withWrite` opens a write window
+     * for THIS repository, bounded by the repository and by the callback's
+     * duration — not by the step: steps running concurrently in the same job can
+     * push to the same repository while it is open, but cannot reach a different
+     * one. It throws before any git runs when the forge will not grant what was
+     * requested.
+     */
+    repo?: {
+        identifier: string;
+        path: string;
+        ref?: string;
+        sha?: string;
+        withWrite(opts: {
+            permissions?: Record<string, string>;
+            credential?: string;
+        }, fn: () => Promise<void>): Promise<void>;
+    };
     /**
      * Workflow repo metadata -- only set for global workflows.
      * The registering repo where the workflow code is defined.

package/dist/filter-context.d.ts

@@ -0,0 +1,32 @@
+import type { $ as Shell } from 'zx';
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { EventPayload } from './events/event-payloads.js';
+import type { RepoInfo } from './context.js';
+import type { FilterContext } from './filter.js';
+/** Input for {@link createFilterContext}. */
+export interface CreateFilterContextInput {
+    /** The repo whose event triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow. */
+    workflowRepo: RepoInfo;
+    event: EventPayload | Record<string, unknown>;
+    changedFiles?: string[];
+    /** Defaults to `'fetched'` — a caller that passes a real list needs no status. */
+    changedFilesStatus?: ChangedFilesStatus;
+    env?: Record<string, string | undefined>;
+    /** zx shell handed to the filter. Defaults to the ambient `$`. */
+    $?: typeof Shell;
+}
+/**
+ * Build a `FilterContext` — the single construction site for the context a
+ * workflow's `filter` predicate receives, mirroring {@link createRuleContext}.
+ *
+ * `changedFiles` is installed through the shared accessor, so it throws
+ * `ChangedFilesUnavailableError` when the diff is unavailable instead of
+ * reading as an empty list. That matters more here than in a rule: a `false`
+ * verdict dispatches none of the workflow's own jobs, and on the
+ * organization-wide path it produces no run at all — so a silently-empty diff
+ * would suppress the workflow with nothing left to inspect.
+ */
+export declare function createFilterContext(input: CreateFilterContextInput): FilterContext;
+//# sourceMappingURL=filter-context.d.ts.map

package/dist/filter-context.js

@@ -0,0 +1,36 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { defineChangedFilesGetter, eventTypeOf } from "./rules/changed-files.js";
+import { $ } from "zx";
+//#region src/filter-context.ts
+/**
+* Build a `FilterContext` — the single construction site for the context a
+* workflow's `filter` predicate receives, mirroring {@link createRuleContext}.
+*
+* `changedFiles` is installed through the shared accessor, so it throws
+* `ChangedFilesUnavailableError` when the diff is unavailable instead of
+* reading as an empty list. That matters more here than in a rule: a `false`
+* verdict dispatches none of the workflow's own jobs, and on the
+* organization-wide path it produces no run at all — so a silently-empty diff
+* would suppress the workflow with nothing left to inspect.
+*/
+function createFilterContext(input) {
+	const status = input.changedFilesStatus ?? "fetched";
+	const base = {
+		sourceRepo: input.sourceRepo,
+		workflowRepo: input.workflowRepo,
+		event: input.event,
+		changedFilesStatus: status,
+		env: input.env ?? {},
+		$: input.$ ?? $
+	};
+	defineChangedFilesGetter(base, {
+		files: input.changedFiles ?? [],
+		status,
+		eventType: eventTypeOf(input.event)
+	});
+	return base;
+}
+//#endregion
+export { createFilterContext };
+
+//# sourceMappingURL=filter-context.js.map

package/dist/filter.d.ts

@@ -0,0 +1,81 @@
+import type { $ as Shell } from 'zx';
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { EventPayload } from './events/event-payloads.js';
+import type { RepoInfo } from './context.js';
+/**
+ * Context handed to a workflow's `filter`, on an evaluating agent with the
+ * tree(s) on disk. An organization-wide workflow is evaluated once per
+ * (event × workflow repo), before any run row exists; a same-repo workflow is
+ * evaluated once per dispatch-bound job and once per generator, where
+ * `sourceRepo` and `workflowRepo` are the same repo. See `FilterFn` for what
+ * that means for the predicate you write, and which jobs it skips.
+ *
+ * **The context carries no secrets.** Not because nothing has been resolved
+ * yet — on the same-repo path a job's bound contexts, their vars and scoped
+ * secrets, its context rules and its approval hold are all resolved BEFORE the
+ * evaluating job is queued — but because this context deliberately does not
+ * carry them. `filter` sees no `scoped_secrets` and no source-repo credentials
+ * beyond the clone token, whichever path it runs on.
+ *
+ * `sourceRepo.path` is an absolute path on the evaluating agent. Its CONTENTS
+ * are stable across evaluations and the later sandbox run; the path itself is
+ * not (different workDir, possibly a different machine). Read through it; never
+ * embed it in a job name, an output, or anything compared across calls.
+ *
+ * `sourceRepo.ref` and `sourceRepo.sha` are optional on `RepoInfo` and may be
+ * absent for an event that carries no single ref — guard before reading them.
+ */
+export interface FilterContext {
+    /** The repo whose push triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` for a non-global workflow. */
+    workflowRepo: RepoInfo;
+    /** Normalized event envelope that triggered this evaluation. */
+    event: EventPayload;
+    /**
+     * Files changed in this event (push / pull_request diff, computed from the
+     * checkout). Reading this throws `ChangedFilesUnavailableError` when the diff
+     * is not available (`changedFilesStatus !== 'fetched'`) — e.g. a
+     * schedule/tag/manual event. Guard with `changedFilesStatus` first when a
+     * filter runs on such events:
+     * `if (ctx.changedFilesStatus !== 'fetched') return true`.
+     *
+     * The throw is deliberate and mirrors `RuleContext.changedFiles`: a `false`
+     * verdict dispatches none of the workflow's own jobs, so a silently-empty
+     * list would make a path-based gate suppress it invisibly. How invisibly
+     * depends on the path — an organization-wide workflow leaves no run at all,
+     * a same-repo one leaves a `success` run carrying only its `__init__*`
+     * evaluation jobs, whose log records the verdict.
+     */
+    changedFiles: string[];
+    /** Availability of `changedFiles` (see `changedFiles`). */
+    changedFilesStatus: ChangedFilesStatus;
+    /** Environment variables. */
+    env: Record<string, string | undefined>;
+    /** zx shell executor. */
+    $: typeof Shell;
+}
+/**
+ * A workflow-level pre-dispatch predicate.
+ *
+ * **It must be pure and deterministic.** For an organization-wide workflow it is
+ * called once per (event × workflow repo). For a same-repo workflow it is called
+ * once for every job that reaches dispatch and once for every job generator, so
+ * a workflow with ten jobs calls it ten times for one event, each on its own
+ * agent with its own checkout and its own `ctx.$` shell. Two consequences to
+ * design for: anything the predicate does — an API call, a shell command, a
+ * write — happens that many times, so keep it cheap and side-effect free; and if
+ * it can return different answers for the same event, the workflow will
+ * partially dispatch, running some jobs and not others.
+ *
+ * "Reaches dispatch" excludes two same-repo cases: a job **held for approval**
+ * and a job **rejected by a context rule** are never filtered. Each already has
+ * a gate — the hold or the rule — so an approved job dispatches with no filter
+ * verdict having been taken. A path filter therefore cannot stop an approval
+ * request for a job the change does not concern.
+ *
+ * Decide from `ctx` alone — the event, the changed files, and the checked-out
+ * tree — and the same event always yields the same verdict.
+ */
+export type FilterFn = (ctx: FilterContext) => boolean | Promise<boolean>;
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.js

@@ -0,0 +1,2 @@
+import "./rolldown-runtime-ClRpJifh.js";
+export {};

package/dist/filter.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=filter.test-d.d.ts.map

package/dist/filter.test-d.js

@@ -0,0 +1,30 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { workflow } from "./workflow.js";
+import { job } from "./job.js";
+import { step } from "./step.js";
+import { describe, expectTypeOf, it } from "vitest";
+//#region src/filter.test-d.ts
+const noop = job("noop", {
+	runsOn: "linux",
+	steps: [step("x", { run: async () => {} })]
+});
+describe("workflow filter — type level", () => {
+	it("rejects a non-function filter", () => {
+		workflow("org-ci", {
+			jobs: [noop],
+			filter: "yes"
+		});
+	});
+	it("accepts a function filter", () => {
+		const filter = ({ sourceRepo }) => sourceRepo.identifier !== "a/b";
+		const wf = workflow("org-ci", {
+			jobs: [noop],
+			filter
+		});
+		expectTypeOf(wf.filter).toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=filter.test-d.js.map

package/dist/git-types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Forge-typed git surface for workflow authors.
+ *
+ * The forge is a TYPE PARAMETER and nothing more. It is erased at runtime:
+ * `kici.git.clone<'github'>()` against a Forgejo source compiles cleanly, the
+ * requested permissions are ignored, and the result reports
+ * `granted: { scoped: false }`. It buys autocomplete and a compile error on a
+ * wrong-shaped permission object; it buys no safety. The runtime `granted`
+ * value is the only source of truth about what a credential can do.
+ */
+/** Forges that can back a git credential. Mirrors the engine's `ForgeName`. */
+export type ForgeName = 'github' | 'gitlab' | 'bitbucket' | 'generic';
+/**
+ * GitHub repository permissions.
+ *
+ * DELIBERATE CARVE-OUT from the enums-over-hardcoded-strings rule: the known
+ * keys below are typed so editors autocomplete them, but an index signature
+ * lets an unknown key through. GitHub adds permissions over time, and a closed
+ * enum would mean a permission shipped yesterday needs an SDK release — and the
+ * SDK is compat-protected and rides the single-version release train. Unknown
+ * keys are passed to GitHub verbatim for it to accept or reject.
+ */
+export interface GitHubPermissions {
+    contents?: 'read' | 'write';
+    metadata?: 'read';
+    workflows?: 'write';
+    actions?: 'read' | 'write';
+    pull_requests?: 'read' | 'write';
+    issues?: 'read' | 'write';
+    checks?: 'read' | 'write';
+    statuses?: 'read' | 'write';
+    deployments?: 'read' | 'write';
+    packages?: 'read' | 'write';
+    [permission: string]: string | undefined;
+}
+/**
+ * Options for a write elevation, shaped by the forge.
+ *
+ * `WriteOptions<'generic'>` carries no permission fields at all: a static
+ * credential has nothing to request, because an SSH key or PAT is read-write or
+ * it is not.
+ */
+export type WriteOptions<F extends ForgeName = 'github'> = F extends 'github' ? {
+    permissions: GitHubPermissions;
+} : Record<never, never>;
+/** What a credential turned out to be able to do. Never an echo of the request. */
+export type GitGrant = {
+    scoped: false;
+} | {
+    scoped: true;
+    permissions: Record<string, string>;
+};
+/**
+ * One half of a credential field pair. Exactly one form is set: a qualified
+ * `<context>:<secret-name>` reference resolved from the secrets backend, or
+ * material supplied at runtime.
+ *
+ * The field NAME is the discriminator, following the convention `workflow.ts`
+ * already sets with `registries[].tokenSecret` and `isQualifiedSecretRef`.
+ */
+export type Sourced<Name extends string> = {
+    [K in `${Name}Secret`]: string;
+} | {
+    [K in `${Name}Value`]: string;
+};
+/** Where credential material comes from, for each supported credential shape. */
+export type GitCredentialRef = ({
+    kind: 'app';
+} & Sourced<'appId'> & Sourced<'installationId'> & Sourced<'privateKey'>) | ({
+    kind: 'token';
+    user?: string;
+} & Sourced<'token'>) | ({
+    kind: 'ssh';
+} & Sourced<'privateKey'>);
+/** Named credentials for a job. `default` is used when a call names none. */
+export type GitCredentialMap = Record<string, GitCredentialRef>;
+/**
+ * Resolve a call site's credential.
+ *
+ * Order: an explicit per-call value wins; otherwise `default` from the job map;
+ * otherwise undefined, which means the source credential — all a read needs.
+ *
+ * An unknown name THROWS rather than falling back to `default`: silently using
+ * a different credential than the author named is precisely the confusion this
+ * map exists to remove.
+ */
+export declare function resolveCredential(perCall: string | GitCredentialRef | undefined, map: GitCredentialMap | undefined): GitCredentialRef | undefined;
+/**
+ * Every credential field names a secret. Catch the easy, silent mistake of
+ * pasting the credential itself — which would commit it to a git repository.
+ */
+export declare function assertSecretName(value: string, field: string, subject?: string): void;
+/**
+ * Private-registry credentials for pulling a job's container image.
+ *
+ * Built from `Sourced<Name>` so "this field names a secret" has ONE spelling
+ * across the SDK — the same one `gitCredentials` uses. `username` may be a
+ * plain string (a registry username is not a secret); the token may not be.
+ */
+export type ContainerRegistryAuth = Sourced<'token'> & {
+    /** Plain registry username. Mutually exclusive with `usernameSecret`. */
+    username?: string;
+    /**
+     * Registry host these credentials belong to (e.g. `reg.internal:5000`).
+     *
+     * Optional with `container.image`, where it is derived from the image
+     * reference. REQUIRED with `container.dockerfile`: the base image is named
+     * inside the Dockerfile, so there is nothing to derive it from.
+     */
+    registry?: string;
+} & Partial<Sourced<'username'>>;
+/** A checked-out repository. The forge travels with the handle. */
+export interface RepoHandle<F extends ForgeName = 'github'> {
+    /** `owner/repo`. */
+    identifier: string;
+    /** Absolute path to the working tree. */
+    path: string;
+    ref?: string;
+    sha?: string;
+    /**
+     * Run `fn` with write credentials for THIS repository.
+     *
+     * The grant is scoped to this repository and to the duration of `fn` — NOT to
+     * the calling step. The agent runs one process per job and `parallel()` runs
+     * its children inside it, so a concurrent sibling step can push to the same
+     * repository while the grant is live. It cannot reach a different repository.
+     *
+     * Throws at entry — before any git runs — when the forge grants less than was
+     * requested, naming the missing permission.
+     */
+    withWrite(opts: WriteOptions<F>, fn: () => Promise<void>): Promise<void>;
+}
+/** Result of an explicit token request. */
+export interface GitTokenResult {
+    token: string;
+    expiresAt: string | null;
+    granted: GitGrant;
+}
+/** Forge-specific minting. Only minted shapes appear here; static ones have nothing to mint. */
+export interface GitHubApi {
+    /**
+     * Mint a token as a VALUE, for the forge API, the `gh` CLI, or a third-party
+     * tool. Auto-masked in step logs; job-bound; throws outside a running step.
+     *
+     * For git operations prefer `handle.withWrite()`, which never puts a token in
+     * the step environment. `gh` does not read git credential helpers, which is
+     * why this exists.
+     */
+    getToken(opts: {
+        repositories: string[];
+        permissions: GitHubPermissions;
+        /**
+         * Name an entry in the job's `gitCredentials` map. Omit to use `default`;
+         * omit both and the source credential applies.
+         */
+        credential?: string;
+    }): Promise<GitTokenResult>;
+}
+export interface GitApi {
+    github: GitHubApi;
+}
+//# sourceMappingURL=git-types.d.ts.map