@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.bca7d0ccee53

package/dist/session/provider-cli/provider-cli.deterministic.js

@@ -0,0 +1,375 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../../shared/git/git.js";
+import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
+import { completionPhaseFromDispatch, debugCompletionPhaseOrder, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, qaCompletionGateOrder, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact } from "../phase-completion.js";
+import { emitArchitectStructuredEvents, emitCompletionArtifactRecorded, emitQaArtifactRecorded, emitQaGateAccepted, emitQaStructuredEvents, isDebugCompletionPhaseForProvider, nextQaGate, phaseCompleteEventType, qaArtifactRootForDispatch, readQaCompletionArtifactBundle, readQaGateArtifact } from "./provider-cli.artifacts.js";
+import { deterministicBrowserCheck, deterministicBrowserSidecar, hasLaunchTarget, writeQaSidecarFiles } from "./provider-cli.qa-sidecars.js";
+import { buildProviderCliCommand, formatProviderCliCommand, isPullRequestCheckRepairDispatch, isPullRequestCommentsDispatch, singleLine } from "./provider-cli.prompts.js";
+import { estimatedDeterministicUsage, exactRedactionSecrets } from "./provider-cli.runtime.js";
+import { buildProviderUsageEvent } from "./provider-usage.js";
+import { writeCiRepairReadinessManifest } from "./ci-repair-readiness.js";
+import { deterministicArchitectPayload, deterministicCompletionPayload, deterministicQaGatePayload } from "./provider-cli.deterministic-payloads.js";
+export class DeterministicProviderCliService {
+    git;
+    constructor(git = new GitClient()) {
+        this.git = git;
+    }
+    async runDraft(context) {
+        const content = JSON.stringify(deterministicDraftPayload(context.dispatch));
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content,
+            eventType: "draft_complete"
+        });
+        await context.emit(buildProviderUsageEvent(context.dispatch, estimatedDeterministicUsage()));
+        return { summary: "forge-bridge generated deterministic draft." };
+    }
+    async runImplementation(context) {
+        const { dispatch, worktree } = context;
+        const phase = completionPhaseFromDispatch(dispatch);
+        const developCycle = usesDevelopCycleCompletion(dispatch);
+        const debugCycle = usesDebugCycleCompletion(dispatch);
+        const providerCommand = buildProviderCliCommand(dispatch);
+        const providerCommandText = formatProviderCliCommand(providerCommand);
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+        const artifactRoot = path.join(metadataRoot, "artifacts");
+        await fs.mkdir(artifactRoot, { recursive: true });
+        const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
+        if (!laneCommand) {
+            throw new Error(`Lane command for lane '${dispatch.execution.lane}' phase '${dispatch.cycleRun.phase}' was not resolved.`);
+        }
+        const specBody = `${buildSpecBody(laneCommand, dispatch.workItem, phase)}
+## Execution
+
+- Provider: ${singleLine(dispatch.execution.provider)}
+- Model: ${singleLine(dispatch.execution.model)}
+- Command: ${providerCommandText}
+`;
+        const specPath = path.join(metadataRoot, "spec.md");
+        await fs.writeFile(specPath, specBody, "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-lane-command" }) + "\n", "utf8");
+        const changesetPath = path.join(worktree.worktreePath, "FORGE_PHASE5_CHANGESET.md");
+        const changesetBody = `# Forge Phase 5 bridge changeset\n\nWork item: ${dispatch.workItem.id}\nTitle: ${dispatch.workItem.title}\nBranch: ${worktree.branchName}\nProvider: ${singleLine(dispatch.execution.provider)}\nModel: ${singleLine(dispatch.execution.model)}\nCommand: ${providerCommandText}\n\nThis deterministic file is written by forge-bridge run-once through the shared session/worktree service path.\n`;
+        await fs.writeFile(changesetPath, changesetBody, "utf8");
+        await this.git.run(worktree.worktreePath, ["add", "FORGE_PHASE5_CHANGESET.md"]);
+        await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge changeset for ${dispatch.workItem.id.slice(0, 8)}`]);
+        await context.emit({
+            role: "worker",
+            kind: "file_edit",
+            content: `Created bridge changeset at ${changesetPath}`,
+            eventType: "changeset"
+        });
+        const phases = debugCycle
+            ? debugCompletionPhaseOrder
+            : developCycle
+                ? ["implementation", "self_review", "validation"]
+                : [phase];
+        const completionArtifacts = [];
+        for (const completionPhase of phases) {
+            await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: completionPhase,
+                producedBy: "forge-bridge",
+                redactionSecrets: exactRedactionSecrets(dispatch)
+            }, isDebugCompletionPhaseForProvider(completionPhase)
+                ? expectedDebugCompletionToolName(completionPhase)
+                : expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
+            const completionArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, completionPhase);
+            if (!completionArtifact) {
+                throw new Error(`Deterministic provider did not produce the Forge ${completionPhase} completion artifact.`);
+            }
+            completionArtifacts.push(completionArtifact);
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, completionArtifact);
+            await context.emit({
+                role: "assistant",
+                kind: "message",
+                content: `${completionPhase.replace(/_/g, " ")} complete. forge-bridge produced deterministic phase artifacts.`,
+                eventType: phaseCompleteEventType(completionPhase)
+            });
+        }
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
+        return {
+            summary: `forge-bridge completed ${worktree.branchName} (${debugCycle ? "debug cycle" : developCycle ? "develop cycle" : phase}).`,
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-lane-command",
+                status: "approved"
+            },
+            artifact: completionArtifacts[0],
+            artifacts: completionArtifacts
+        };
+    }
+    async runArchitect(context) {
+        const { dispatch, worktree } = context;
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+        await fs.mkdir(metadataRoot, { recursive: true });
+        const specBody = `---\ntitle: "${dispatch.workItem.title}"\nstatus: pending_approval\nproduced_by: forge-bridge\n---\n\n# ${dispatch.workItem.title}\n\nArchitect plan pending approval.\n`;
+        const specPath = path.join(metadataRoot, "spec.md");
+        await fs.writeFile(specPath, specBody, "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "pending_approval", produced_by: "forge-bridge" }) + "\n", "utf8");
+        await writeCompletionArtifact({
+            worktreePath: worktree.worktreePath,
+            workItemId: dispatch.workItem.id,
+            phase: "architect",
+            producedBy: "forge-bridge",
+            redactionSecrets: exactRedactionSecrets(dispatch),
+            architectCycle: true
+        }, expectedCompletionToolName("architect"), deterministicArchitectPayload(dispatch));
+        const artifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "architect");
+        if (!artifact) {
+            throw new Error("Deterministic provider did not produce the Forge Architect completion artifact.");
+        }
+        await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
+        await emitArchitectStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, artifact);
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: "Architect plan complete. forge-bridge produced deterministic planning artifacts.",
+            eventType: "architect_complete"
+        });
+        return {
+            summary: "forge-bridge completed Architect plan (deterministic).",
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-bridge",
+                status: "pending_approval"
+            },
+            artifact,
+            artifacts: [artifact]
+        };
+    }
+    async runQa(context) {
+        const { dispatch, worktree } = context;
+        await context.emit({
+            role: "worker",
+            kind: "message",
+            content: `Planning ${dispatch.execution.provider} QA checks through forge-bridge.`,
+            eventType: "qa_plan"
+        });
+        const qaBrowser = dispatch.qaBrowser;
+        const launchTarget = qaBrowser?.launchTarget ?? null;
+        const missingLaunchTarget = qaBrowser?.required === true && !hasLaunchTarget(launchTarget);
+        const browserSidecar = !missingLaunchTarget && qaBrowser?.required === true && launchTarget
+            ? deterministicBrowserSidecar(dispatch.workItem.id, launchTarget, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
+            : null;
+        const browserChecks = browserSidecar && launchTarget
+            ? [deterministicBrowserCheck(launchTarget, browserSidecar.relativePath)]
+            : [];
+        const sidecars = await writeQaSidecarFiles(worktree.worktreePath, browserSidecar ? [browserSidecar] : []);
+        const summary = missingLaunchTarget
+            ? "QA blocked because browser testing is required but no app launch target was provided."
+            : "All checks passed. forge-bridge QA completed.";
+        const criterion = dispatch.workItem.acceptanceCriteria.trim() || "Forge QA evidence exists";
+        for (const gate of qaCompletionGateOrder) {
+            await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: "qa",
+                producedBy: "forge-bridge",
+                redactionSecrets: exactRedactionSecrets(dispatch),
+                qaCycle: true,
+                ownerType: dispatch.cycleRun.ownerType ?? undefined,
+                ownerId: dispatch.cycleRun.ownerId ?? undefined
+            }, expectedQaCompletionToolName(gate), deterministicQaGatePayload({
+                gate,
+                criterion,
+                summary,
+                missingLaunchTarget,
+                browserChecks,
+                sidecars
+            }));
+            const gateArtifact = await readQaGateArtifact(qaArtifactRootForDispatch(worktree.worktreePath, dispatch.workItem.id, dispatch), gate);
+            if (gateArtifact) {
+                await emitQaGateAccepted(context.emit, worktree.worktreePath, gateArtifact, nextQaGate(gate));
+            }
+        }
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId);
+        if (!qaArtifact) {
+            throw new Error("Deterministic QA did not produce the complete durable QA artifact bundle.");
+        }
+        await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
+        await emitQaStructuredEvents(context.emit, qaArtifact);
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
+        return {
+            summary: missingLaunchTarget ? "forge-bridge QA blocked." : "forge-bridge QA passed.",
+            artifact: qaArtifact,
+            artifacts: [qaArtifact]
+        };
+    }
+    async runCiRepair(context) {
+        return await this.runPullRequestRepair(context, "ci_repair");
+    }
+    async runConflictResolve(context) {
+        return await this.runPullRequestRepair(context, "conflict_resolve");
+    }
+    async runPullRequestRepair(context, route) {
+        const { dispatch, worktree } = context;
+        const repairChecks = route === "ci_repair" || isPullRequestCheckRepairDispatch(dispatch);
+        const addressComments = isPullRequestCommentsDispatch(dispatch);
+        let repairArtifact = null;
+        let repairSpec = null;
+        if (repairChecks) {
+            const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+            await fs.mkdir(metadataRoot, { recursive: true });
+            const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
+            if (!laneCommand)
+                throw new Error("Deterministic CI repair could not materialize the approved lane spec.");
+            const specBody = buildSpecBody(laneCommand, dispatch.workItem, "ci_repair");
+            const specPath = path.join(metadataRoot, "spec.md");
+            await fs.writeFile(specPath, specBody, "utf8");
+            await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), `${JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-lane-command" })}\n`, "utf8");
+            repairSpec = { repoPath: worktree.worktreePath, path: specPath, body: specBody, producedBy: "forge-lane-command", status: "approved" };
+            await writeCiRepairReadinessManifest(dispatch, worktree.worktreePath, specPath, context.runtimeEnvironment);
+            const reference = await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: "ci_repair",
+                producedBy: "forge-deterministic-provider",
+            }, expectedCompletionToolName("ci_repair"), deterministicCiRepairPayload());
+            repairArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "ci_repair");
+            if (!repairArtifact)
+                throw new Error(`Deterministic CI repair did not produce ${reference.path}.`);
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, repairArtifact);
+        }
+        await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge ${repairChecks ? "ci repair" : addressComments ? "pr comments" : "conflict resolve"} for ${dispatch.workItem.id.slice(0, 8)}`]);
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: repairChecks
+                ? `Deterministic CI repair completed for ${worktree.branchName}.`
+                : addressComments
+                    ? `Deterministic PR comment addressing completed for ${worktree.branchName}.`
+                    : `Deterministic conflict resolve completed for ${worktree.branchName}.`,
+            eventType: repairChecks ? "pr_checks_complete" : addressComments ? "pr_comments_complete" : "conflict_resolve_complete"
+        });
+        return {
+            summary: repairChecks
+                ? `forge-bridge repaired PR checks for ${worktree.branchName}.`
+                : addressComments
+                    ? `forge-bridge addressed PR comments for ${worktree.branchName}.`
+                    : `forge-bridge resolved conflicts for ${worktree.branchName}.`,
+            spec: repairSpec,
+            artifact: repairArtifact,
+            artifacts: repairArtifact ? [repairArtifact] : [],
+        };
+    }
+}
+function deterministicCiRepairPayload() {
+    const command = { command: "forge deterministic ci-repair validation", exit_code: 0, status: "pass", summary: "Deterministic CI repair fixture passed." };
+    return {
+        status: "pass",
+        summary: "Deterministic CI repair handoff is ready for provider checks.",
+        failed_checks: [{ name: "CI / deterministic", provider_state: "failure", workflow: ".github/workflows/ci.yml", job: "deterministic", step: "fixture" }],
+        root_cause: { classification: "test expectation mismatch", summary: "Deterministic fixture failure repaired.", evidence: ["Fixture provider reported the expected failed check."] },
+        changed_files: [],
+        no_code_action: { action: "deterministic_fixture", reason: "The deterministic provider models the repair without a product diff." },
+        narrow_validation: [command],
+        workflow_validation: [{ step: "deterministic fixture", equivalence: "supported", command: command.command, exit_code: 0, status: "pass", summary: command.summary }],
+        broader_validation: [command],
+        remaining_risks: [],
+        provider_state: "ready_for_rerun",
+        ready_for_push: true,
+    };
+}
+function deterministicDraftPayload(dispatch) {
+    const kind = dispatch.draft?.kind ?? "work_item";
+    if (kind === "work_order_decomposition") {
+        return {
+            summary: "Fake decompose proposed a Feature DAG for the Work Order.",
+            blockedReason: "",
+            candidates: [
+                {
+                    origin: "agent",
+                    key: "intake-submission",
+                    title: "Customer intake submission",
+                    summary: "Collect, validate, de-duplicate, and confirm incoming customer requests.",
+                    planningPacket: "# Customer intake submission\n\nPlan Stories for request form validation, attachment support, duplicate prevention, and submission confirmation.",
+                    sortOrder: 10,
+                    dependsOn: []
+                },
+                {
+                    origin: "agent",
+                    key: "review-queue",
+                    title: "Reviewer triage queue",
+                    summary: "Provide reviewer triage, assignment, notes, status transitions, and audit trail.",
+                    planningPacket: "# Reviewer triage queue\n\nPlan Stories for queue filtering, assignment, reviewer notes, status changes, and immutable audit trail.",
+                    sortOrder: 20,
+                    dependsOn: ["intake-submission"]
+                }
+            ]
+        };
+    }
+    if (kind === "feature_decomposition") {
+        return {
+            summary: "Fake decompose proposed a Story DAG for the Feature.",
+            blockedReason: "",
+            candidates: [
+                {
+                    origin: "agent",
+                    key: "foundation",
+                    title: "Build the feature foundation",
+                    description: "Create the persistence, API, and UI shell needed by the feature.",
+                    acceptanceCriteria: "Scenario: Foundation exists\nGiven the Feature is selected\nWhen the foundation is delivered\nThen downstream Stories can build on stable contracts",
+                    points: 3,
+                    sortOrder: 10,
+                    dependsOn: []
+                },
+                {
+                    origin: "agent",
+                    key: "workflow-behavior",
+                    title: "Implement the primary workflow behavior",
+                    description: "Implement the main user-visible behavior for the feature after the foundation is ready.",
+                    acceptanceCriteria: "Scenario: Workflow behavior works\nGiven the foundation Story is complete\nWhen the user performs the primary workflow\nThen the expected state change and feedback are visible",
+                    points: 5,
+                    sortOrder: 20,
+                    dependsOn: ["foundation"]
+                },
+                {
+                    origin: "agent",
+                    key: "audit-and-tests",
+                    title: "Add audit coverage and regression tests",
+                    description: "Add audit/evidence behavior and automated regression coverage for the feature.",
+                    acceptanceCriteria: "Scenario: Feature is verifiable\nGiven the workflow behavior is complete\nWhen validation runs\nThen audit evidence and tests cover the expected outcomes",
+                    points: 3,
+                    sortOrder: 30,
+                    dependsOn: ["workflow-behavior"]
+                }
+            ]
+        };
+    }
+    if (kind === "work_order") {
+        return {
+            title: "Deterministic runner Work Order draft",
+            summary: "Forge Runner generated this deterministic Work Order draft.",
+            objective: "Validate runner-backed Draft generation.",
+            planningPacket: "Runner-backed draft generation returned a Work Order JSON payload.",
+            decompositionContext: "Use this deterministic fixture only in bridge tests.",
+            assumptions: ["Forge Runner dispatch is available."],
+            warnings: []
+        };
+    }
+    if (kind === "story") {
+        return {
+            title: "Deterministic runner Story draft",
+            description: "Forge Runner generated this deterministic Story draft.",
+            acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a Story draft, then JSON is returned.",
+            points: 3
+        };
+    }
+    return {
+        title: "Deterministic runner Work Item draft",
+        description: "Forge Runner generated this deterministic Work Item draft.",
+        acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a draft, then JSON is returned.",
+        reproSteps: "Run Draft with a Forge Runner provider selected.",
+        systemInfo: "forge-bridge deterministic provider",
+        points: 1
+    };
+}

package/dist/session/provider-cli/provider-cli.process.d.ts

@@ -0,0 +1,48 @@
+import { type LaunchCommand } from "../../shared/process/windows-launch.js";
+export type ProviderCliCommand = LaunchCommand;
+export interface ProviderProcessRunRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: string;
+    readonly captureOutput?: boolean;
+}
+export interface ProviderProcessRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ProviderProcessRunner {
+    run(request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<ProviderProcessRunResult>;
+}
+export interface ProviderProcessHandlers {
+    onStarted?(): Promise<void> | void;
+    onStdoutLine?(line: string): Promise<void> | void;
+    onStderrLine?(line: string): Promise<void> | void;
+}
+interface ProviderChildEnvironmentOptions {
+    readonly parentEnv?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDir?: string;
+}
+export declare function buildProviderChildEnvironment(requestEnv?: Readonly<Record<string, string>>, options?: ProviderChildEnvironmentOptions): NodeJS.ProcessEnv;
+export declare class StreamingProviderProcessRunner implements ProviderProcessRunner {
+    run(request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<ProviderProcessRunResult>;
+}
+export declare function resolveCodexNpmDirectLaunch(commandPath: string, args: readonly string[]): LaunchCommand | null;
+/**
+ * Avoids cmd.exe's nested-quote handling for package-manager shims. That
+ * quoting loses executable paths containing spaces after the command is
+ * wrapped by the Windows Job Object supervisor.
+ */
+export declare function resolvePackageManagerDirectLaunch(commandPath: string, args: readonly string[]): LaunchCommand | null;
+/**
+ * Resolves Windows commands without spawning where.exe. Runtime launches can
+ * happen while the machine is under enough process pressure for where.exe to
+ * miss its timeout; returning the unresolved package-manager name in that case
+ * makes Node fall back to a shell shim that cannot survive Job Object wrapping.
+ */
+export declare function resolveWindowsCommandFromPath(command: string, pathValue?: string, pathExtValue?: string): string | null;
+export declare function chooseWindowsCommandCandidate(candidates: readonly string[]): string | null;
+export {};