@kici-dev/sdk 0.6.1 → 0.7.0

package/dist/git-types.d.ts

@@ -90,6 +90,15 @@ export declare function resolveCredential(perCall: string | GitCredentialRef | u
  * pasting the credential itself — which would commit it to a git repository.
  */
 export declare function assertSecretName(value: string, field: string, subject?: string): void;
+/**
+ * Every `<name>Secret` field in a credential map names a secret in qualified
+ * `<context>:<secret-name>` form, and never carries the material itself.
+ *
+ * `subject` is the declaring surface as the author wrote it — `job('build')` or
+ * `dynamicJob('reports')` — so a message names the call the author can find.
+ * A `<name>Value` sibling is material by design and is not checked here.
+ */
+export declare function validateGitCredentials(subject: string, credentials: GitCredentialMap): void;
 /**
  * Private-registry credentials for pulling a job's container image.
  *

package/dist/git-types.js

@@ -26,7 +26,26 @@ function resolveCredential(perCall, map) {
 function assertSecretName(value, field, subject = "git credential") {
 	if (value.startsWith("-----BEGIN") || /^gh[pousr]_/.test(value) || value.startsWith("github_pat_")) throw new Error(`${subject} '${field}' looks like the credential itself, not the name of a secret holding it. Store it with \`kici-admin secret set\` and name it here.`);
 }
+/**
+* Every `<name>Secret` field in a credential map names a secret in qualified
+* `<context>:<secret-name>` form, and never carries the material itself.
+*
+* `subject` is the declaring surface as the author wrote it — `job('build')` or
+* `dynamicJob('reports')` — so a message names the call the author can find.
+* A `<name>Value` sibling is material by design and is not checked here.
+*/
+function validateGitCredentials(subject, credentials) {
+	for (const [alias, ref] of Object.entries(credentials)) {
+		const bag = ref;
+		for (const [field, value] of Object.entries(bag)) {
+			if (!field.endsWith("Secret") || typeof value !== "string") continue;
+			assertSecretName(value, `${alias}.${field}`);
+			const idx = value.indexOf(":");
+			if (idx <= 0 || idx >= value.length - 1 || value.slice(idx + 1).includes(":")) throw new Error(`${subject}: gitCredentials.${alias}.${field} must use qualified <context>:<secret-name> syntax (got: ${value})`);
+		}
+	}
+}
 //#endregion
-export { assertSecretName, resolveCredential };
+export { assertSecretName, resolveCredential, validateGitCredentials };
 
 //# sourceMappingURL=git-types.js.map

package/dist/index.d.ts

@@ -1,10 +1,13 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
-export { parallel, isParallelGroup, flattenStepInputs } from './parallel.js';
+export { parallel, isParallelGroup } from './parallel.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
+export { flattenStepInputs } from './parallel.js';
 export type { ParallelGroup, ParallelOptions } from './parallel.js';
 export { invokeSource } from './invoke.js';
 export type { InvokeConfig } from './invoke.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { normalizeApproval } from './approval.js';
 export type { ApprovalConfig, ApprovalWhen, ApproverClause, NormalizedApproval, } from './approval.js';
 export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, workflowsFailedBatch, jobComplete, genericWebhook, schedule, lifecycle, defineDispatchInputs, } from './triggers/index.js';
@@ -12,19 +15,25 @@ export type { DefinedDispatchInputs, InferDispatchInputs, DispatchInputsMap, Tri
 export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
 export type { HookConfig, HookFn, HookInput, HookContext, OutcomeMetadata } from './hooks/index.js';
 export { rule, skip, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rules/index.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { evaluateRules } from './rules/index.js';
-export { createRuleContext, ChangedFilesUnavailableError } from './rules/index.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
+export { createRuleContext } from './rules/index.js';
+export { ChangedFilesUnavailableError } from './rules/index.js';
 export type { CreateRuleContextInput } from './rules/index.js';
 export { isEventType } from './rules/index.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEvaluationResult, EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from './rules/index.js';
 export { validateDag } from './validation/index.js';
 export type { DagNode, DagValidationResult } from './validation/index.js';
 export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, RetryConfig, NormalizedRetry, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, RunsOnPick, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
-export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
+export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, getDynamicJobGitCredentials, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, DYNAMIC_JOB_GIT_CREDENTIALS_TAG, } from './types.js';
 export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { buildNeedsContext } from './needs-context.js';
 export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry, InvokeNeedEntry, InvokeResult, } from './needs-context.js';
-export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
+export { CacheSpecSchema } from './cache-types.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
+export { normalizeCacheSpecs } from './cache-types.js';
 export type { CacheSpec, CacheInput } from './cache-types.js';
 export type { CacheRestoreResult, CacheApi } from './cache-types.js';
 export { ArtifactNameSchema, ARTIFACT_NAME_MAX_LENGTH } from './artifacts-types.js';
@@ -36,18 +45,24 @@ export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
 export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
 export type { FilterContext, FilterFn } from './filter.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { createFilterContext } from './filter-context.js';
 export type { CreateFilterContextInput } from './filter-context.js';
 export type { FanoutPosition } from './fanout-context.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { buildKiciApi } from './api-types.js';
 export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
 export { SecretNotFoundError } from './errors.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { createStepSecrets } from './secrets.js';
 export type { StepSecrets, TrackedStepSecrets, SecretMeta, SecretFileOptions, MountedFile, StepSecretsFileHost, StepSecretsFileWiring, StepSecretsHandle, StepSecretMountKind, StepSecretMountRecord, } from './secrets.js';
-export { createStepOutputProxy, createJobOutputProxy, createSnapshotOutputProxy, resolveStepOutputs, resolveJobOutputs, setStepOutputsMap, setJobOutputsMap, setStepRefMap, getStepOutputsMap, getJobOutputsMap, getStepRefMap, } from './outputs.js';
+export { createStepOutputProxy, createJobOutputProxy, createSnapshotOutputProxy, resolveStepOutputs, resolveJobOutputs, getStepOutputsMap, getJobOutputsMap, getStepRefMap, } from './outputs.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
+export { setStepOutputsMap, setJobOutputsMap, setStepRefMap } from './outputs.js';
 export type { OutputsMap, StepRefMap } from './outputs.js';
 export type { StaticMatrixArray, StaticMatrixObject, DynamicMatrixFn, DynamicMatrixContext, Matrix, MatrixInclude, MatrixExclude, MatrixValues, } from './matrix/index.js';
 export { isStaticArray, isStaticObject, isDynamicFunction } from './matrix/index.js';
+/** @deprecated Moved to `@kici-dev/sdk/internal` — internal runtime API, not covered by semver. */
 export { expandMatrix, applyIncludeExclude } from './matrix/index.js';
 export { defineEvent, isEventDefinition } from './events/index.js';
 export type { EventDefinition } from './events/index.js';

package/dist/index.js

@@ -53,7 +53,7 @@ import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
 import { validateDag } from "./validation/dag.js";
 import "./validation/index.js";
-import { DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn } from "./types.js";
+import { DYNAMIC_JOB_GIT_CREDENTIALS_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGitCredentials, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn } from "./types.js";
 import { buildNeedsContext } from "./needs-context.js";
 import { provenanceSubjectIsPath } from "./provenance-types.js";
 import { createStepSecrets } from "./secrets.js";
@@ -65,4 +65,4 @@ import "./events/index.js";
 import { agentVersionConverge } from "./fleet/agent-version-converge.js";
 import { SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload } from "@kici-dev/engine";
 import { z } from "zod";
-export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, assertSecretName, beforeStep, buildAgentCloudInit, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createFilterContext, createJobOutputProxy, createRuleContext, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, invokeSource, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventDefinition, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, workflowsFailedBatch, z };
+export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GIT_CREDENTIALS_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, assertSecretName, beforeStep, buildAgentCloudInit, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createFilterContext, createJobOutputProxy, createRuleContext, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGitCredentials, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, invokeSource, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventDefinition, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, workflowsFailedBatch, z };

package/dist/internal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @internal — NOT covered by semver.
+ *
+ * The runtime ABI between `@kici-dev/sdk` and the KiCI agent, compiler, and
+ * orchestrator. Everything here is machinery the execution tiers drive on a
+ * workflow's behalf: it installs the maps a `.result` proxy reads, builds the
+ * step context a workflow body receives, evaluates its rules, and expands its
+ * matrix. A workflow author never calls any of it.
+ *
+ * It lives on its own subpath because the root barrel is a **compat-protected**
+ * surface (`.claude/rules/compatibility.md`): every symbol on it is frozen at
+ * v1.0.0 and can only be removed at a major bump. Leaving the runtime ABI there
+ * would mean a version handshake, or making the outputs map per-job instead of
+ * module-global, is a customer-facing SDK deprecation — with a ledger row and a
+ * dual-shape window — for a function no customer ever called. Every internal
+ * refactor of the runtime would pay the public-API tax forever.
+ *
+ * Each symbol also stays on the root barrel, marked `@deprecated`, for the whole
+ * 0.x line. The agent resolves the customer's own SDK copy at run time
+ * (`workflow-loader.ts`), so a tree carrying an SDK older than this subpath must
+ * keep working.
+ *
+ * Do not import this from a workflow. It carries no compatibility promise and
+ * may change shape in any release.
+ */
+export { flattenStepInputs } from './parallel.js';
+export { normalizeApproval } from './approval.js';
+export { evaluateRules, createRuleContext } from './rules/index.js';
+export { buildNeedsContext } from './needs-context.js';
+export { normalizeCacheSpecs } from './cache-types.js';
+export { createFilterContext } from './filter-context.js';
+export { buildKiciApi } from './api-types.js';
+export { createStepSecrets } from './secrets.js';
+export { setStepOutputsMap, setJobOutputsMap, setStepRefMap } from './outputs.js';
+export { expandMatrix, applyIncludeExclude } from './matrix/index.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -0,0 +1,15 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { buildKiciApi } from "./api-types.js";
+import { normalizeApproval } from "./approval.js";
+import { normalizeCacheSpecs } from "./cache-types.js";
+import { createFilterContext } from "./filter-context.js";
+import { setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
+import { flattenStepInputs } from "./parallel.js";
+import { createRuleContext } from "./rules/context.js";
+import { evaluateRules } from "./rules/evaluator.js";
+import "./rules/index.js";
+import { buildNeedsContext } from "./needs-context.js";
+import { createStepSecrets } from "./secrets.js";
+import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
+import "./matrix/index.js";
+export { applyIncludeExclude, buildKiciApi, buildNeedsContext, createFilterContext, createRuleContext, createStepSecrets, evaluateRules, expandMatrix, flattenStepInputs, normalizeApproval, normalizeCacheSpecs, setJobOutputsMap, setStepOutputsMap, setStepRefMap };

package/dist/job.js

@@ -1,6 +1,6 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { createJobOutputProxy } from "./outputs.js";
-import { assertSecretName } from "./git-types.js";
+import { assertSecretName, validateGitCredentials } from "./git-types.js";
 import { isKnownCapability } from "@kici-dev/engine";
 import { randomUUID } from "node:crypto";
 //#region src/job.ts
@@ -53,7 +53,7 @@ function job(nameOrOptions, maybeOptions) {
 	if (options.runsOn !== void 0 && options.runsOnAll !== void 0) throw new Error(`job('${name}'): runsOn and runsOnAll are mutually exclusive`);
 	if (options.container !== void 0) validateContainerImageSource(name, options.container);
 	if (options.container && typeof options.container === "object" && options.container.auth) validateContainerAuth(name, options.container.auth);
-	if (options.gitCredentials) validateGitCredentials(name, options.gitCredentials);
+	if (options.gitCredentials) validateGitCredentials(`job('${name}')`, options.gitCredentials);
 	if (options.invoke === void 0 && options.runsOn === void 0 && options.runsOnAll === void 0) throw new Error(`job('${name}'): one of runsOn or runsOnAll is required`);
 	if (options.onUnreachable !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): onUnreachable is ignored without runsOnAll`);
 	if (options.includeUninitialized !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): includeUninitialized is ignored without runsOnAll`);
@@ -171,17 +171,6 @@ function validateContainerAuth(name, auth) {
 		if (idx <= 0 || idx >= value.length - 1 || value.slice(idx + 1).includes(":")) throw new Error(`job('${name}'): container.auth.${field} must use qualified <context>:<secret-name> syntax (got: ${value})`);
 	}
 }
-function validateGitCredentials(name, credentials) {
-	for (const [alias, ref] of Object.entries(credentials)) {
-		const bag = ref;
-		for (const [field, value] of Object.entries(bag)) {
-			if (!field.endsWith("Secret") || typeof value !== "string") continue;
-			assertSecretName(value, `${alias}.${field}`);
-			const idx = value.indexOf(":");
-			if (idx <= 0 || idx >= value.length - 1 || value.slice(idx + 1).includes(":")) throw new Error(`job('${name}'): gitCredentials.${alias}.${field} must use qualified <context>:<secret-name> syntax (got: ${value})`);
-		}
-	}
-}
 //#endregion
 export { job };
 

package/dist/triggers/comment.js

@@ -1,15 +1,20 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { asArray, toBranchPattern } from "./types.js";
+import { normalizeRegexFlags } from "@kici-dev/engine";
 //#region src/triggers/comment.ts
 /**
 * Convert a string or RegExp to a BodyMatchPattern.
 * Strings become glob patterns, RegExp becomes regex patterns.
+*
+* `g` and `y` are dropped for the same reason as `toBranchPattern`: the reader
+* memoizes the compiled instance, so a sticky one alternates verdicts between
+* comments.
 */
 function toBodyMatchPattern(input) {
 	if (input instanceof RegExp) return {
 		type: "regex",
 		pattern: input.source,
-		flags: input.flags || void 0
+		flags: normalizeRegexFlags(input.flags)
 	};
 	return {
 		type: "glob",

package/dist/triggers/types.d.ts

@@ -600,6 +600,11 @@ export interface PushConfigInput {
 /**
  * Convert a string or RegExp to a BranchPattern.
  * Strings become glob patterns, RegExp becomes regex patterns.
+ *
+ * `g` and `y` are dropped from the author's flags: the matcher memoizes one
+ * `RegExp` per (flags, pattern), and a sticky instance carries `lastIndex`
+ * between calls — so `/^release-\d+/g` would match `release-1`, miss
+ * `release-2`, and match `release-3`, silently skipping every second push.
  */
 export declare function toBranchPattern(input: string | RegExp): BranchPattern;
 /**

package/dist/triggers/types.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { normalizeRegexFlags } from "@kici-dev/engine";
 //#region src/triggers/types.ts
 /**
 * Default PR events when pr() is called without explicit events.
@@ -12,12 +13,17 @@ const DEFAULT_PR_EVENTS = [
 /**
 * Convert a string or RegExp to a BranchPattern.
 * Strings become glob patterns, RegExp becomes regex patterns.
+*
+* `g` and `y` are dropped from the author's flags: the matcher memoizes one
+* `RegExp` per (flags, pattern), and a sticky instance carries `lastIndex`
+* between calls — so `/^release-\d+/g` would match `release-1`, miss
+* `release-2`, and match `release-3`, silently skipping every second push.
 */
 function toBranchPattern(input) {
 	if (input instanceof RegExp) return {
 		type: "regex",
 		pattern: input.source,
-		flags: input.flags || void 0
+		flags: normalizeRegexFlags(input.flags)
 	};
 	return {
 		type: "glob",

package/dist/types.d.ts

@@ -355,12 +355,16 @@ export interface TaggedDynamicJobFn extends DynamicJobFn {
  * Two forms:
  * - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
  *   Dispatched at webhook time; deterministic from `ctx.event` alone.
- * - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
- *   Deferred until every job/group in `needs` completes, then `generate` is
- *   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+ * - **Options form**: `dynamicJob('reports', { needs, generate, gitCredentials })`.
+ *   With `needs` it is result-aware — deferred until every job/group in `needs`
+ *   completes, then `generate` is evaluated with the upstreams' frozen outputs
+ *   available as `ctx.needs`. `needs` is optional: without it the generator is
+ *   dispatched at webhook time, as the function form is. `gitCredentials`
+ *   declares the named credentials every generated job inherits, and only the
+ *   options form can carry it.
  *
  * @param groupName - The group name (must match what static jobs reference)
- * @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
+ * @param fnOrConfig - The generator function, or a `{ needs, generate, gitCredentials }` config
  */
 export declare function dynamicJob(groupName: string, fnOrConfig: DynamicJobFn | ResultAwareDynamicJobConfig): TaggedDynamicJobFn;
 /**
@@ -387,10 +391,25 @@ export type DynamicJobNeed = Job | string | DynamicGroupRef | {
  * outputs available as `ctx.needs`.
  */
 export interface ResultAwareDynamicJobConfig {
-    /** Upstream jobs/groups whose outputs the generator reads via `ctx.needs`. */
-    needs: ReadonlyArray<DynamicJobNeed>;
+    /**
+     * Upstream jobs/groups whose outputs the generator reads via `ctx.needs`.
+     * Omit it for an event-only generator that declares `gitCredentials` and
+     * nothing else — the generator then runs at webhook time, as the bare
+     * function form does.
+     */
+    needs?: ReadonlyArray<DynamicJobNeed>;
     /** The generator. Receives `ctx.needs` resolved from the frozen upstream snapshot. */
     generate: DynamicJobFn;
+    /**
+     * Named git credentials every job this generator produces inherits.
+     *
+     * A generated job has no lock entry of its own, so it cannot declare its own
+     * map: the definitions come back from the agent that evaluated the generator,
+     * and a declaration read from there would let job code authorize itself. The
+     * generator does live in the lock file, so its map is the ceiling the
+     * credential relay holds every generated child to.
+     */
+    gitCredentials?: GitCredentialMap;
 }
 /** A {@link DynamicJobFn} tagged with declared needs (result-aware). */
 export interface ResultAwareDynamicJobFn extends TaggedDynamicJobFn {
@@ -402,6 +421,13 @@ export interface ResultAwareDynamicJobFn extends TaggedDynamicJobFn {
  */
 export declare function getDynamicJobNeeds(fn: DynamicJobFn): ReadonlyArray<DynamicJobNeed> | undefined;
 export { DYNAMIC_JOB_NEEDS_TAG };
+declare const DYNAMIC_JOB_GIT_CREDENTIALS_TAG: unique symbol;
+/**
+ * Read the named git credentials a generator declared.
+ * Returns undefined for the bare function form, which cannot declare any.
+ */
+export declare function getDynamicJobGitCredentials(fn: DynamicJobFn): GitCredentialMap | undefined;
+export { DYNAMIC_JOB_GIT_CREDENTIALS_TAG };
 /**
  * Container configuration for job execution.
  * When set, all steps run inside the specified container.

package/dist/types.js

@@ -1,4 +1,5 @@
 import "./rolldown-runtime-ClRpJifh.js";
+import { validateGitCredentials } from "./git-types.js";
 //#region src/types.ts
 /**
 * Type guard to check if a JobOrFactory is a dynamic job generator.
@@ -14,12 +15,16 @@ const DYNAMIC_JOB_GROUP_TAG = Symbol.for("kici:dynamicJobGroup");
 * Two forms:
 * - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
 *   Dispatched at webhook time; deterministic from `ctx.event` alone.
-* - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
-*   Deferred until every job/group in `needs` completes, then `generate` is
-*   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+* - **Options form**: `dynamicJob('reports', { needs, generate, gitCredentials })`.
+*   With `needs` it is result-aware — deferred until every job/group in `needs`
+*   completes, then `generate` is evaluated with the upstreams' frozen outputs
+*   available as `ctx.needs`. `needs` is optional: without it the generator is
+*   dispatched at webhook time, as the function form is. `gitCredentials`
+*   declares the named credentials every generated job inherits, and only the
+*   options form can carry it.
 *
 * @param groupName - The group name (must match what static jobs reference)
-* @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
+* @param fnOrConfig - The generator function, or a `{ needs, generate, gitCredentials }` config
 */
 function dynamicJob(groupName, fnOrConfig) {
 	const isConfig = typeof fnOrConfig !== "function";
@@ -28,10 +33,17 @@ function dynamicJob(groupName, fnOrConfig) {
 		value: groupName,
 		enumerable: false
 	});
-	if (isConfig) Object.defineProperty(tagged, DYNAMIC_JOB_NEEDS_TAG, {
+	if (isConfig && fnOrConfig.needs) Object.defineProperty(tagged, DYNAMIC_JOB_NEEDS_TAG, {
 		value: fnOrConfig.needs,
 		enumerable: false
 	});
+	if (isConfig && fnOrConfig.gitCredentials) {
+		validateGitCredentials(`dynamicJob('${groupName}')`, fnOrConfig.gitCredentials);
+		Object.defineProperty(tagged, DYNAMIC_JOB_GIT_CREDENTIALS_TAG, {
+			value: fnOrConfig.gitCredentials,
+			enumerable: false
+		});
+	}
 	return tagged;
 }
 /**
@@ -49,7 +61,15 @@ const DYNAMIC_JOB_NEEDS_TAG = Symbol.for("kici:dynamicJobNeeds");
 function getDynamicJobNeeds(fn) {
 	return fn[DYNAMIC_JOB_NEEDS_TAG];
 }
+const DYNAMIC_JOB_GIT_CREDENTIALS_TAG = Symbol.for("kici:dynamicJobGitCredentials");
+/**
+* Read the named git credentials a generator declared.
+* Returns undefined for the bare function form, which cannot declare any.
+*/
+function getDynamicJobGitCredentials(fn) {
+	return fn[DYNAMIC_JOB_GIT_CREDENTIALS_TAG];
+}
 //#endregion
-export { DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn };
+export { DYNAMIC_JOB_GIT_CREDENTIALS_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGitCredentials, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn };
 
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -44,6 +44,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js",
@@ -55,8 +60,8 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.6.1",
-    "@kici-dev/engine": "0.6.1"
+    "@kici-dev/core": "0.7.0",
+    "@kici-dev/engine": "0.7.0"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.6.1",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.6.1/90fe6f72-53bd-48ec-9d75-c6c8f5738975",
+  "name": "@kici-dev/sdk@0.7.0",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.7.0/194e6a78-3e3a-4ad2-b529-3d28614071bf",
   "creationInfo": {
-    "created": "2026-09-02T03:01:25Z",
+    "created": "2026-09-11T07:37:37Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.7.0",
       "name": "@kici-dev/core",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.7.0"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.7.0"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.7.0"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1604,73 +1604,73 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.140.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.10",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.7",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-yaml-2.9.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relationshipType": "DEPENDS_ON"
     },
     {