@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/blueprint/trust/scaffold.js

@@ -0,0 +1,64 @@
+/**
+ * Trust Dossier authoring scaffold.
+ *
+ * `dossier.ts` / `evidence.ts` / `gates.ts` / `ambiguity.ts` define strict
+ * validation for a blueprint's `## Trust Dossier` section, but nothing
+ * generates a starting template. `TRUST_DOSSIER_SCAFFOLD` is a complete,
+ * already-valid worked example — proven by `scaffold.test.ts` to pass
+ * `validateBlueprintTrust` under both the strict configuration
+ * `wp audit blueprint-trust` uses and the draft-preflight configuration
+ * `wp_blueprint_put` / `preparePromotionTrustGate` use — so an author can
+ * paste it in and edit the example values instead of hand-deriving the
+ * contract from source.
+ *
+ * `verified-at` / `verified-head` stay as inert, obviously-fake placeholders:
+ * `preparePromotionTrustGate` (./promotion.ts) overwrites both with the real
+ * timestamp/HEAD on every promotion attempt, so there is no need for this
+ * pure, dependency-free module to shell out to git.
+ */
+const PLACEHOLDER_HEAD = "0".repeat(40);
+export const TRUST_DOSSIER_SCAFFOLD = `## Trust Dossier
+
+<!-- Trust Dossier scaffold — generated by \`wp blueprint trust-dossier\`. -->
+<!-- Replace every example value below, then delete these comment lines before promotion. -->
+<!-- Constraints enforced by \`wp audit blueprint-trust\` / \`wp_blueprint_put\`: -->
+<!-- - All 5 "###" subsections below are required, verbatim, exactly once each. -->
+<!-- - Material Claims "repo:<path>" evidence must be a bare, existing repo-relative path -->
+<!--   (no ":line" suffix, no leading "/", no "../"). -->
+<!-- - "Residual Unknowns" must render exactly \`None.\` when nothing is outstanding. -->
+<!-- - Promotion Gates "Command" must be a \`wp\` facade call: \`wp typecheck\`, \`wp lint\` -->
+<!--   (no extra args), \`wp test --file <path>\` (repeatable), or -->
+<!--   \`wp audit <kind> [--json|--affected|--branch|--base <val>]\`. -->
+<!-- - No TBD, TODO, "decide during implementation", "open question", or <placeholder> tokens -->
+<!--   anywhere in the 5 subsections below. -->
+
+### Readiness Verdict
+
+- promotion-ready: true
+- unresolved-count: 0
+- verified-at: 1970-01-01T00:00:00.000Z
+- verified-head: ${PLACEHOLDER_HEAD}
+- trust-gate-version: v1
+
+### Material Claims
+
+| ID | Claim | Evidence |
+| --- | --- | --- |
+| C1 | Example material claim — replace with a real, falsifiable claim this blueprint depends on. | repo:README.md |
+
+### Material Decisions
+
+| ID | Decision | Chosen option | Rejected alternatives | Rationale |
+| --- | --- | --- | --- | --- |
+| D1 | Example material decision — replace with a real decision this blueprint locks in. | Example chosen option. | Example rejected alternative and why it lost. | Example rationale for the chosen option. |
+
+### Promotion Gates
+
+| Gate | Command | Expected outcome | Last result |
+| --- | --- | --- | --- |
+| typecheck | wp typecheck | Typecheck passes with zero errors. | pass (scaffold example — rerun and record the real result before promotion) |
+
+### Residual Unknowns
+
+None.
+`;

package/dist/esm/blueprint/trust/validator.d.ts

@@ -8,6 +8,7 @@ export type ValidateBlueprintTrustInput = {
     promotionCandidate?: boolean;
     requirePassingGates?: boolean;
     scanTaskAmbiguity?: boolean;
+    allowDeferredGates?: boolean;
 };
 export type BlueprintTrustViolation = TrustDossierViolation & {
     file: string;

package/dist/esm/blueprint/trust/validator.js

@@ -51,7 +51,8 @@ export function validateBlueprintTrust(input) {
                     message: error instanceof Error ? error.message : String(error),
                 });
             }
-            if (input.requirePassingGates !== false && !/^pass\b/iu.test(gate.lastResult))
+            if (input.requirePassingGates !== false &&
+                !isAcceptableGateResult(gate.lastResult, input.allowDeferredGates))
                 violations.push({
                     section: "Promotion Gates",
                     claimId: gate.gate,
@@ -64,3 +65,8 @@ export function validateBlueprintTrust(input) {
         violations: violations.map((v) => ({ ...v, file: input.file })),
     };
 }
+function isAcceptableGateResult(lastResult, allowDeferredGates) {
+    if (/^pass\b/iu.test(lastResult))
+        return true;
+    return allowDeferredGates === true && /^deferred:/iu.test(lastResult);
+}

package/dist/esm/blueprint/utils/archive.js

@@ -6,6 +6,7 @@
 import { access, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parseBlueprint } from "#core/parser";
+import { getBlueprintDocumentCandidates } from "./document-paths.js";
 import { resolveBlueprintRoot } from "./blueprint-root.js";
 /**
  * Validates that all tasks in a plan are complete.
@@ -111,7 +112,13 @@ export async function archiveBlueprint(slug, projectPath) {
     if (isAlreadyCompleted(slug)) {
         return { success: false, error: "Plan is already completed" };
     }
-    const paths = buildPlanPaths(projectPath, slug);
+    const paths = await buildPlanPaths(projectPath, slug);
+    if (paths.ambiguousPaths) {
+        return {
+            success: false,
+            error: `Plan ${slug} exists in both flat and folder forms; remove one before archiving: ${paths.ambiguousPaths.join(", ")}`,
+        };
+    }
     // Check if plan exists
     const planExists = await checkPlanExists(paths.sourcePath);
     if (!planExists) {
@@ -132,16 +139,31 @@ export async function archiveBlueprint(slug, projectPath) {
 /**
  * Builds source and target paths for archival.
  *
+ * Resolves the existing flat or folder document via the shared candidates;
+ * when neither shape exists, falls back to the canonical folder path so the
+ * caller reports the same "Plan not found" error as before.
+ *
  * @param projectPath - Root path of the project
  * @param slug - Plan slug
  * @returns Path information
  */
-function buildPlanPaths(projectPath, slug) {
+async function buildPlanPaths(projectPath, slug) {
     const plansDir = resolveBlueprintRoot(projectPath);
-    const sourcePath = path.join(plansDir, slug, "_overview.md");
+    const candidates = getBlueprintDocumentCandidates(plansDir, slug);
+    const existing = [];
+    for (const candidate of candidates) {
+        if (await checkPlanExists(candidate))
+            existing.push(candidate);
+    }
+    const sourcePath = existing[0] ?? candidates.at(-1) ?? path.join(plansDir, slug, "_overview.md");
     const sourceDir = path.dirname(sourcePath);
-    const targetDir = sourceDir;
-    return { sourcePath, sourceDir, targetDir, planName: slug };
+    return {
+        sourcePath,
+        sourceDir,
+        targetDir: sourceDir,
+        planName: slug,
+        ...(existing.length > 1 ? { ambiguousPaths: existing } : {}),
+    };
 }
 /**
  * Extracts plan name from slug (removes status prefix).

package/dist/esm/blueprint/utils/document-paths.d.ts

@@ -8,6 +8,13 @@ export interface BlueprintDocumentPath {
     slug: string;
     state: BlueprintStatus;
 }
+export interface BlueprintDocumentIdentity extends BlueprintDocumentPath {
+    documentPath: string;
+    folderDirectory: string;
+    folderPath: string;
+    lifecycleSlug: string;
+    stableSlug: string;
+}
 export declare function normalizeBlueprintPath(filePath: string): string;
 export declare function isBlueprintStatus(value: string | undefined): value is BlueprintStatus;
 export declare function isBlueprintSlugSegment(value: string | undefined): value is string;
@@ -18,5 +25,16 @@ export declare function getBlueprintDocumentPaths(root: string, state: Blueprint
     flat: string;
     folder: string;
 };
+export declare function resolveBlueprintDocumentIdentity(root: string, documentPath: string): BlueprintDocumentIdentity | null;
+export declare function folderBlueprintRequiredMessage(identity: {
+    readonly documentPath: string;
+    readonly lifecycleSlug: string;
+    readonly shape: BlueprintShape;
+}): string;
+export declare function assertFolderBlueprintIdentity(identity: {
+    readonly documentPath: string;
+    readonly lifecycleSlug: string;
+    readonly shape: BlueprintShape;
+}): void;
 export declare function getBlueprintDocumentCandidates(root: string, slug: string): string[];
 export declare function getBlueprintAlternateDocumentPath(root: string, filePath: string): string | null;

package/dist/esm/blueprint/utils/document-paths.js

@@ -22,7 +22,7 @@ export function isBlueprintSlugSegment(value) {
 export function parseBlueprintDocumentRelativePath(filePath) {
     const normalized = normalizeBlueprintPath(filePath);
     const parts = normalized.split("/").filter((segment) => segment.length > 0);
-    const [state, second, third] = parts;
+    const [state, second] = parts;
     if (!isBlueprintStatus(state)) {
         return null;
     }
@@ -38,13 +38,16 @@ export function parseBlueprintDocumentRelativePath(filePath) {
             state,
         };
     }
-    if (parts.length === 3 &&
-        isBlueprintSlugSegment(second) &&
-        third === BLUEPRINT_OVERVIEW_FILENAME) {
+    if (parts.length >= 3 && parts.at(-1) === BLUEPRINT_OVERVIEW_FILENAME) {
+        const slugSegments = parts.slice(1, -1);
+        if (!slugSegments.every((segment) => isBlueprintSlugSegment(segment))) {
+            return null;
+        }
+        const slug = slugSegments.join("/");
         return {
-            relativePath: `${state}/${second}/${BLUEPRINT_OVERVIEW_FILENAME}`,
+            relativePath: `${state}/${slug}/${BLUEPRINT_OVERVIEW_FILENAME}`,
             shape: "folder",
-            slug: second,
+            slug,
             state,
         };
     }
@@ -53,13 +56,13 @@ export function parseBlueprintDocumentRelativePath(filePath) {
 export function isBlueprintSupportingMarkdownRelativePath(filePath) {
     const normalized = normalizeBlueprintPath(filePath);
     const parts = normalized.split("/").filter((segment) => segment.length > 0);
-    const [state, slug, doc] = parts;
-    return (parts.length === 3 &&
+    const [state] = parts;
+    return (parts.length >= 3 &&
         isBlueprintStatus(state) &&
-        isBlueprintSlugSegment(slug) &&
-        typeof doc === "string" &&
-        doc.endsWith(".md") &&
-        doc !== BLUEPRINT_OVERVIEW_FILENAME);
+        parts.slice(1, -1).every((segment) => isBlueprintSlugSegment(segment)) &&
+        typeof parts.at(-1) === "string" &&
+        parts.at(-1).endsWith(".md") &&
+        parts.at(-1) !== BLUEPRINT_OVERVIEW_FILENAME);
 }
 export function getBlueprintDocumentPaths(root, state, slug) {
     const directory = path.join(root, state, slug);
@@ -69,6 +72,36 @@ export function getBlueprintDocumentPaths(root, state, slug) {
         folder: path.join(directory, BLUEPRINT_OVERVIEW_FILENAME),
     };
 }
+export function resolveBlueprintDocumentIdentity(root, documentPath) {
+    const relativePath = normalizeBlueprintPath(path.relative(root, documentPath));
+    const parsed = parseBlueprintDocumentRelativePath(relativePath);
+    if (!parsed)
+        return null;
+    const paths = getBlueprintDocumentPaths(root, parsed.state, parsed.slug);
+    return {
+        ...parsed,
+        documentPath: parsed.shape === "flat" ? paths.flat : paths.folder,
+        folderDirectory: paths.directory,
+        folderPath: paths.folder,
+        lifecycleSlug: `${parsed.state}/${parsed.slug}`,
+        stableSlug: parsed.slug,
+    };
+}
+export function folderBlueprintRequiredMessage(identity) {
+    if (identity.shape === "folder") {
+        return "";
+    }
+    return [
+        `Blueprint evidence requires folder shape; ${identity.documentPath} is a flat blueprint.`,
+        `Run: wp blueprint canonicalize ${identity.lifecycleSlug}`,
+        "Then commit the canonicalized path and rerun the evidence command.",
+    ].join(" ");
+}
+export function assertFolderBlueprintIdentity(identity) {
+    const message = folderBlueprintRequiredMessage(identity);
+    if (message)
+        throw new Error(message);
+}
 export function getBlueprintDocumentCandidates(root, slug) {
     const normalized = normalizeBlueprintPath(slug);
     const segments = normalized.split("/").filter((segment) => segment.length > 0);

package/dist/esm/build/cli-mcp-parity.js

@@ -187,6 +187,11 @@ export const CLI_MCP_PARITY_CLASSIFICATION = {
         classification: "direct-fallback-by-design",
         reason: "internal serialization wrapper spawned by the auto-update, wp update, and setup lanes; never agent-facing",
     },
+    "optional-tool-refresh": {
+        command: "optional-tool-refresh",
+        classification: "direct-fallback-by-design",
+        reason: "internal detached worker spawned by provider launch freshness; never agent-facing",
+    },
     init: {
         command: "init",
         classification: "unsafe-credentialed-destructive",
@@ -229,6 +234,11 @@ export const CLI_MCP_PARITY_CLASSIFICATION = {
         classification: "direct-fallback-by-design",
         reason: "long-running local preview server remains a direct CLI workflow",
     },
+    "public:readiness": {
+        command: "public:readiness",
+        classification: "direct-fallback-by-design",
+        reason: "public package readiness performs local package/tarball checks and is intentionally not a read-only MCP workflow",
+    },
     qa: {
         command: "qa",
         classification: "existing-mcp",

package/dist/esm/ci/act-replay.js

@@ -31,8 +31,105 @@ export function buildReplayWorkflowSource(sourceYaml, options) {
         : basename(options.workflowPath);
     workflow.name = `replay: ${originalName}`;
     workflow.on = normalizeWorkflowOnSection(workflow.on, options.eventName);
+    workflow.jobs = rewriteReplayJobs(workflow.jobs, options.eventName);
     return stringify(workflow);
 }
+function rewriteReplayJobs(jobs, eventName) {
+    if (typeof jobs !== "object" || jobs === null || Array.isArray(jobs)) {
+        return jobs;
+    }
+    return Object.fromEntries(Object.entries(jobs).map(([jobId, job]) => [
+        jobId,
+        rewriteReplayJob(job, eventName),
+    ]));
+}
+function rewriteReplayJob(job, eventName) {
+    if (typeof job !== "object" || job === null || Array.isArray(job)) {
+        return job;
+    }
+    const jobRecord = { ...job };
+    if (Array.isArray(jobRecord.steps)) {
+        jobRecord.steps = jobRecord.steps.map((step) => rewriteReplayStep(step, eventName));
+    }
+    return jobRecord;
+}
+function rewriteReplayStep(step, eventName) {
+    if (!isRecord(step) || !isSameRepoCheckoutStep(step, eventName)) {
+        return step;
+    }
+    const rewritten = {
+        name: typeof step.name === "string" ? step.name : "Use prepared local replay workspace",
+        run: [
+            'echo "wp ci act replay: using prepared local workspace instead of actions/checkout"',
+            "test -d .git",
+            "git rev-parse --is-inside-work-tree",
+            "git rev-parse --verify HEAD",
+        ].join("\n"),
+        "working-directory": "${{ github.workspace }}",
+    };
+    copyOptionalStepField(step, rewritten, "id");
+    copyOptionalStepField(step, rewritten, "if");
+    copyOptionalStepField(step, rewritten, "timeout-minutes");
+    copyOptionalStepField(step, rewritten, "continue-on-error");
+    return rewritten;
+}
+function isSameRepoCheckoutStep(step, eventName) {
+    if (typeof step.uses !== "string" || !/^actions\/checkout(?:@|$)/u.test(step.uses)) {
+        return false;
+    }
+    if (step.env !== undefined && step.env !== null) {
+        return false;
+    }
+    const withConfig = step.with;
+    if (withConfig === undefined || withConfig === null) {
+        return true;
+    }
+    if (!isRecord(withConfig)) {
+        return false;
+    }
+    if (hasAnyCheckoutInputExcept(withConfig, ["ref"])) {
+        return false;
+    }
+    return isCurrentReplayRef(withConfig.ref, eventName);
+}
+function isCurrentReplayRef(value, eventName) {
+    if (value === undefined || value === null || String(value).trim().length === 0) {
+        return true;
+    }
+    const normalized = normalizeGithubExpression(String(value));
+    if (normalized === null)
+        return false;
+    if (normalized === "github.sha") {
+        return true;
+    }
+    if (normalized ===
+        "github.event_name=='pull_request'&&github.event.pull_request.base.sha||github.sha") {
+        return eventName !== "pull_request";
+    }
+    return false;
+}
+function normalizeGithubExpression(value) {
+    const match = /^\$\{\{\s*([\s\S]*?)\s*\}\}$/u.exec(value.trim());
+    if (!match?.[1])
+        return null;
+    return match[1].replace(/"/gu, "'").replace(/\s+/gu, "");
+}
+function hasAnyCheckoutInputExcept(withConfig, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.entries(withConfig).some(([key, value]) => {
+        if (allowed.has(key))
+            return false;
+        return value !== undefined && value !== null && String(value).trim().length > 0;
+    });
+}
+function copyOptionalStepField(source, target, field) {
+    if (source[field] !== undefined) {
+        target[field] = source[field];
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export function createReplayWorkflow(options) {
     const sourcePath = resolve(options.cwd, options.workflowPath);
     const sourceYaml = readFileSync(sourcePath, "utf8");
@@ -42,11 +139,17 @@ export function createReplayWorkflow(options) {
     });
     const dir = mkdtempSync(join(tmpdir(), "wp-ci-act-replay-"));
     const workflowPath = join(dir, "workflow.yml");
-    writeFileSync(workflowPath, generatedYaml, "utf8");
-    return {
-        workflowPath,
-        cleanup() {
-            rmSync(dir, { recursive: true, force: true });
-        },
-    };
+    try {
+        writeFileSync(workflowPath, generatedYaml, "utf8");
+        return {
+            workflowPath,
+            cleanup() {
+                rmSync(dir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
 }

package/dist/esm/ci/act-runner.d.ts

@@ -6,6 +6,7 @@ export interface PublicCiActOptions {
     readonly workflow?: string;
     readonly workflowPath?: string;
     readonly job?: string;
+    readonly matrix?: readonly string[];
     readonly eventName?: CiActEventName;
     readonly eventPath?: string;
     readonly envProfile?: string;
@@ -22,6 +23,7 @@ export interface PublicCiActCommand {
     readonly actArgs: readonly string[];
 }
 export interface PreparedPublicCiActExecution {
+    readonly cwd: string;
     readonly command: PublicCiActCommand;
     readonly mode: CiActExecutionMode;
     readonly nonSecurityEquivalent: boolean;
@@ -36,5 +38,7 @@ export declare function buildPublicCiActArgs(options?: PublicCiActOptions, workf
 export declare function buildPublicCiActCommand(options?: PublicCiActOptions): PublicCiActCommand;
 export declare function preparePublicCiActExecution(options?: PublicCiActOptions): PreparedPublicCiActExecution;
 export declare function resolveCiActSecretEnvProfile(options?: PublicCiActOptions): string | undefined;
+export declare function shouldForceCiActSecretGate(envProfile: string | undefined): boolean;
 export declare function sanitizePublicCiActArgv(command: PublicCiActCommand): PublicCiActCommand;
 export declare function assertNoForbiddenCiActArgs(args: readonly string[]): void;
+export declare function normalizeCiActMatrixSelectors(selectors: readonly string[] | undefined): readonly string[];

package/dist/esm/ci/act-runner.js

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { buildSecretGateCommand } from "#secret-gate/runner.js";
 import { resolveSecretsConfigProfileEnvironment } from "#runtime/secrets-config.js";
 import { createReplayWorkflow, GENERATED_REPLAY_WORKFLOW_PLACEHOLDER, } from "./act-replay.js";
+import { prepareActGitWorkspace } from "./act-worktree-git.js";
 export { GENERATED_REPLAY_WORKFLOW_PLACEHOLDER } from "./act-replay.js";
 const DEFAULT_WORKFLOW = "ci-e2e";
 export const DEFAULT_PLATFORM_IMAGE = "ghcr.io/catthehacker/ubuntu:full-latest";
@@ -43,6 +44,7 @@ export function buildPublicCiActArgs(options = {}, workflowPathOverride) {
         "--rm",
     ];
     pushOption(args, "-j", options.job);
+    pushRepeatableOption(args, "--matrix", normalizeCiActMatrixSelectors(options.matrix));
     pushOption(args, "-e", options.eventPath ? resolve(cwd, options.eventPath) : undefined);
     pushOption(args, "--container-architecture", containerArchitecture);
     return args;
@@ -57,7 +59,7 @@ export function buildPublicCiActCommand(options = {}) {
         sink: "act",
         profile: secretEnvProfile,
         envProfile: options.envProfile ?? "secrets-only",
-        forceSecretGate: true,
+        forceSecretGate: shouldForceCiActSecretGate(options.envProfile),
         command: "act",
         args: actArgs,
     });
@@ -65,32 +67,63 @@ export function buildPublicCiActCommand(options = {}) {
 }
 export function preparePublicCiActExecution(options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const mode = resolveCiActExecutionMode(options);
-    const replay = mode === "replay"
-        ? createReplayWorkflow({
-            cwd,
-            workflowPath: resolveCiActWorkflowPath(options),
-            eventName: options.eventName ?? "pull_request",
-        })
-        : null;
-    const actArgs = buildPublicCiActArgs({ ...options, cwd }, replay ? replay.workflowPath : undefined);
-    const secretEnvProfile = resolveCiActSecretEnvProfile({ ...options, cwd }) ?? "preview";
-    const wrapped = buildSecretGateCommand({
-        sink: "act",
-        profile: secretEnvProfile,
-        envProfile: options.envProfile ?? "secrets-only",
-        forceSecretGate: true,
-        command: "act",
-        args: actArgs,
-    });
-    return {
-        command: { command: wrapped.command, args: wrapped.args, actArgs },
-        mode,
-        nonSecurityEquivalent: mode === "replay",
-        cleanup() {
+    let gitWorkspace = null;
+    let replay = null;
+    try {
+        gitWorkspace = prepareActGitWorkspace(cwd);
+        const executionCwd = gitWorkspace.cwd;
+        const mode = resolveCiActExecutionMode(options);
+        const sourceWorkflowPath = resolve(cwd, resolveCiActWorkflowPath(options));
+        replay =
+            mode === "replay"
+                ? createReplayWorkflow({
+                    cwd,
+                    workflowPath: sourceWorkflowPath,
+                    eventName: options.eventName ?? "pull_request",
+                })
+                : null;
+        const executionOptions = {
+            ...options,
+            cwd: executionCwd,
+            eventPath: options.eventPath ? resolve(cwd, options.eventPath) : undefined,
+        };
+        const actArgs = buildPublicCiActArgs(executionOptions, replay ? replay.workflowPath : sourceWorkflowPath);
+        if (gitWorkspace.prepared) {
+            actArgs.push("--bind");
+        }
+        const secretEnvProfile = resolveCiActSecretEnvProfile({ ...options, cwd }) ?? "preview";
+        const wrapped = buildSecretGateCommand({
+            sink: "act",
+            profile: secretEnvProfile,
+            envProfile: options.envProfile ?? "secrets-only",
+            forceSecretGate: shouldForceCiActSecretGate(options.envProfile),
+            command: "act",
+            args: actArgs,
+        });
+        return {
+            cwd: executionCwd,
+            command: { command: wrapped.command, args: wrapped.args, actArgs },
+            mode,
+            nonSecurityEquivalent: mode === "replay",
+            cleanup() {
+                try {
+                    replay?.cleanup();
+                }
+                finally {
+                    gitWorkspace?.cleanup();
+                }
+            },
+        };
+    }
+    catch (error) {
+        try {
             replay?.cleanup();
-        },
-    };
+        }
+        finally {
+            gitWorkspace?.cleanup();
+        }
+        throw error;
+    }
 }
 export function resolveCiActSecretEnvProfile(options = {}) {
     const secretEnvProfile = options.secretEnvProfile?.trim();
@@ -103,6 +136,9 @@ export function resolveCiActSecretEnvProfile(options = {}) {
     }
     return undefined;
 }
+export function shouldForceCiActSecretGate(envProfile) {
+    return envProfile !== "none" && envProfile !== "public";
+}
 export function sanitizePublicCiActArgv(command) {
     return {
         command: command.command,
@@ -126,11 +162,34 @@ export function assertNoForbiddenCiActArgs(args) {
     if (found)
         throw new Error(`Unsupported unsafe ci act argument: ${found}`);
 }
+export function normalizeCiActMatrixSelectors(selectors) {
+    if (!selectors)
+        return [];
+    return selectors.map((selector) => normalizeCiActMatrixSelector(selector));
+}
 function pushOption(args, flag, value) {
     if (value === undefined || value === "")
         return;
     args.push(flag, String(value));
 }
+function pushRepeatableOption(args, flag, values) {
+    for (const value of values) {
+        args.push(flag, value);
+    }
+}
+function normalizeCiActMatrixSelector(selector) {
+    const trimmed = selector.trim();
+    const delimiter = trimmed.indexOf(":");
+    if (trimmed.length === 0 || delimiter <= 0) {
+        throw new Error(`Invalid ci act matrix selector "${selector}". Use key:value with non-empty key and value.`);
+    }
+    const key = trimmed.slice(0, delimiter).trim();
+    const value = trimmed.slice(delimiter + 1).trim();
+    if (key.length === 0 || value.length === 0) {
+        throw new Error(`Invalid ci act matrix selector "${selector}". Use key:value with non-empty key and value.`);
+    }
+    return `${key}:${value}`;
+}
 function sanitizeArg(value) {
     if (/wp-ci-act-[^/\\]+[/\\]secrets\.env$/u.test(value))
         return "[INTERNAL_SECRET_FILE]";

package/dist/esm/ci/act-worktree-git.d.ts

@@ -0,0 +1,11 @@
+export interface PreparedActGitWorkspace {
+    readonly cwd: string;
+    readonly prepared: boolean;
+    cleanup(): void;
+}
+interface LinkedWorktreeGitMetadata {
+    readonly gitDir: string;
+}
+export declare function prepareActGitWorkspace(cwd: string): PreparedActGitWorkspace;
+export declare function readLinkedWorktreeGitMetadata(cwd: string): LinkedWorktreeGitMetadata | null;
+export {};