@loucompanion/forge-bridge 0.1.1-dev.242bb53ef13f

package/dist/session/internals.d.ts

@@ -0,0 +1,7 @@
+export { parseRunOnceDispatchPacket, failureResult } from "./session.types.js";
+export type { SessionEventSink, SessionService } from "./session.base.js";
+export type { ApiKeySecretGrant, DispatchCycleRun, DispatchExecution, DispatchLease, DispatchSession, DispatchRepo, DispatchServerLocalConfig, DispatchWorkItem, RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchArtifact, RunnerDispatchEvent, RunnerDispatchSpec, RunnerEventLine } from "./session.types.js";
+export { DeterministicProviderCliService, buildProviderCliCommand } from "./provider-cli/provider-cli.service.js";
+export type { ProviderCliService } from "./provider-cli/provider-cli.base.js";
+export type { ProviderCliCommand } from "./provider-cli/provider-cli.service.js";
+export type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli/provider-cli.types.js";

package/dist/session/internals.js

@@ -0,0 +1,2 @@
+export { parseRunOnceDispatchPacket, failureResult } from "./session.types.js";
+export { DeterministicProviderCliService, buildProviderCliCommand } from "./provider-cli/provider-cli.service.js";

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

@@ -0,0 +1,3 @@
+export { DeterministicProviderCliService, buildProviderCliCommand } from "./provider-cli.service.js";
+export type { ProviderCliService } from "./provider-cli.base.js";
+export type { ProviderCliCommand } from "./provider-cli.service.js";

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

@@ -0,0 +1 @@
+export { DeterministicProviderCliService, buildProviderCliCommand } from "./provider-cli.service.js";

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

@@ -0,0 +1,6 @@
+import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
+import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
+export interface ProviderCliService {
+    runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>): Promise<ProviderCliRunResult>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+import { GitClient } from "../../shared/git/git.js";
+import type { ProviderCliService } from "./provider-cli.base.js";
+import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
+import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
+export interface ProviderCliCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export declare class DeterministicProviderCliService implements ProviderCliService {
+    private readonly git;
+    constructor(git?: GitClient);
+    runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>): Promise<ProviderCliRunResult>;
+}
+export declare function formatProviderCliCommand(command: ProviderCliCommand): string;
+export declare function buildProviderCliCommand(dispatch: RunOnceDispatchPacket): ProviderCliCommand;

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

@@ -0,0 +1,111 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../../shared/git/git.js";
+export class DeterministicProviderCliService {
+    git;
+    constructor(git = new GitClient()) {
+        this.git = git;
+    }
+    async runImplementation(context) {
+        const { dispatch, worktree } = context;
+        const providerCommand = buildProviderCliCommand(dispatch);
+        const providerCommandText = formatProviderCliCommand(providerCommand);
+        const metadataRoot = path.join(worktree.repoPath, ".forge", "work-items", dispatch.workItem.id);
+        const artifactRoot = path.join(metadataRoot, "artifacts");
+        await fs.mkdir(artifactRoot, { recursive: true });
+        const specBody = `---\nwork_item_id: ${dispatch.workItem.id}\nstatus: approved\nlane: ${dispatch.execution.lane}\nprovider: ${yamlQuotedScalar(dispatch.execution.provider)}\nmodel: ${yamlQuotedScalar(dispatch.execution.model)}\nprovider_command: ${yamlQuotedScalar(providerCommandText)}\n---\n\n# Forge bridge implementation spec\n\nImplement **${dispatch.workItem.title}**.\n\nAcceptance:\n- prepare a task-scoped git worktree\n- emit newline JSON runner events\n- produce Forge phase artifacts\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: "approved", produced_by: "forge-bridge" }) + "\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 verdict = {
+            schema_version: 1,
+            status: "pass",
+            checks: [{ name: "forge_bridge_run_once", status: "pass" }],
+            metrics: { files_changed: 1 },
+            produced_by: "forge-bridge",
+            content_hash: sha256(changesetBody)
+        };
+        const verdictJson = JSON.stringify(verdict);
+        const report = `# Implementation report\n\nforge-bridge prepared \`${worktree.branchName}\` and created \`${changesetPath}\`.\n`;
+        const artifactPath = path.join(artifactRoot, "implementation.verdict.json");
+        await fs.writeFile(artifactPath, verdictJson + "\n", "utf8");
+        await fs.writeFile(path.join(artifactRoot, "implementation.report.md"), report, "utf8");
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: "Implementation complete. forge-bridge produced deterministic phase artifacts.",
+            eventType: "implementation_complete"
+        });
+        return {
+            summary: `forge-bridge completed ${worktree.branchName}.`,
+            spec: {
+                repoPath: worktree.repoPath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-bridge",
+                status: "approved"
+            },
+            artifact: {
+                repoPath: worktree.repoPath,
+                path: artifactPath,
+                verdictJson,
+                report,
+                producedBy: "forge-bridge",
+                status: "pass"
+            }
+        };
+    }
+    async runQa(dispatch, emit) {
+        await emit({
+            role: "worker",
+            kind: "message",
+            content: `Running ${dispatch.execution.provider} QA checks through forge-bridge.`,
+            eventType: "qa_analysis"
+        });
+        await emit({
+            role: "assistant",
+            kind: "message",
+            content: "All checks passed. forge-bridge QA completed.",
+            eventType: "qa_complete"
+        });
+        return {
+            summary: "forge-bridge QA passed."
+        };
+    }
+}
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+export function formatProviderCliCommand(command) {
+    return [command.command, ...command.args].map(singleLine).join(" ");
+}
+function yamlQuotedScalar(value) {
+    return JSON.stringify(singleLine(value));
+}
+function singleLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export function buildProviderCliCommand(dispatch) {
+    const provider = dispatch.execution.provider.trim();
+    const normalizedProvider = provider.toLowerCase();
+    const model = dispatch.execution.model.trim();
+    if (normalizedProvider === "codex") {
+        return { command: "codex", args: ["exec", "--model", model] };
+    }
+    if (normalizedProvider === "cursor") {
+        return { command: "cursor-agent", args: ["--model", model] };
+    }
+    return { command: provider, args: ["--model", model] };
+}

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

@@ -0,0 +1,12 @@
+import type { RunOnceDispatchPacket, RunnerDispatchArtifact, RunnerDispatchEvent, RunnerDispatchSpec } from "../session.types.js";
+import type { WorktreeHandle } from "../../worktree/worktree.types.js";
+export interface ProviderCliRunContext {
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly worktree: WorktreeHandle;
+    emit(event: RunnerDispatchEvent): Promise<void>;
+}
+export interface ProviderCliRunResult {
+    readonly summary: string;
+    readonly spec?: RunnerDispatchSpec | null;
+    readonly artifact?: RunnerDispatchArtifact | null;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/session/session.base.d.ts

@@ -0,0 +1,7 @@
+import type { RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchEvent } from "./session.types.js";
+export interface SessionEventSink {
+    emit(event: RunnerDispatchEvent): Promise<void>;
+}
+export interface SessionService {
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+}

package/dist/session/session.base.js

@@ -0,0 +1 @@
+export {};

package/dist/session/session.service.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderCliService } from "./provider-cli/provider-cli.base.js";
+import type { SessionEventSink, SessionService } from "./session.base.js";
+import type { RunOnceDispatchPacket, RunOnceResultPacket } from "./session.types.js";
+import type { WorktreeService } from "../worktree/worktree.base.js";
+export declare class BridgeSessionService implements SessionService {
+    private readonly worktrees;
+    private readonly providerCli;
+    constructor(worktrees?: WorktreeService, providerCli?: ProviderCliService);
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+}

package/dist/session/session.service.js

@@ -0,0 +1,92 @@
+import { redactSecrets } from "../shared/redaction/redaction.js";
+import { DeterministicProviderCliService } from "./provider-cli/provider-cli.service.js";
+import { GitWorktreeService } from "../worktree/worktree.service.js";
+export class BridgeSessionService {
+    worktrees;
+    providerCli;
+    constructor(worktrees = new GitWorktreeService(), providerCli = new DeterministicProviderCliService()) {
+        this.worktrees = worktrees;
+        this.providerCli = providerCli;
+    }
+    async runOnce(dispatch, sink, signal) {
+        validateApiKeySecretGrant(dispatch);
+        const redactionSecrets = exactSecrets(dispatch);
+        const events = [];
+        const emit = async (event) => {
+            throwIfAborted(signal);
+            const redacted = redactSecrets(event, redactionSecrets);
+            events.push(redacted);
+            await sink.emit(redacted);
+        };
+        throwIfAborted(signal);
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: "forge-bridge accepted run-once dispatch.",
+            eventType: "dispatch_accepted"
+        });
+        const worktree = await this.worktrees.prepare({
+            repo: dispatch.repo,
+            workItem: dispatch.workItem,
+            baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
+            allowedRepoRoot: dispatch.serverLocal.repoRoot,
+            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees
+        });
+        throwIfAborted(signal);
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Prepared worktree ${worktree.branchName}.`,
+            eventType: "worktree_prepared"
+        });
+        try {
+            throwIfAborted(signal);
+            const isQa = dispatch.execution.role.toLowerCase() === "qa" || dispatch.execution.lane.toLowerCase() === "qa";
+            const run = isQa
+                ? await this.providerCli.runQa(dispatch, emit)
+                : await this.providerCli.runImplementation({
+                    dispatch,
+                    worktree,
+                    emit
+                });
+            return redactSecrets({
+                schemaVersion: 1,
+                exitCode: 0,
+                summary: run.summary,
+                events,
+                spec: run.spec ?? null,
+                artifact: run.artifact ?? null
+            }, redactionSecrets);
+        }
+        finally {
+            await this.worktrees.release(worktree);
+        }
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new Error(String(signal.reason ?? "Dispatch cancelled."));
+    }
+}
+function validateApiKeySecretGrant(dispatch) {
+    if (!dispatch.execution.requiresApiKeySecretGrant) {
+        return;
+    }
+    if (dispatch.execution.authKind !== "api_key") {
+        throw new Error("API-key secret grant requires api_key execution.");
+    }
+    const grant = dispatch.apiKeySecretGrant;
+    if (!grant?.secret) {
+        throw new Error("API-key secret grant is missing.");
+    }
+    if (grant.provider.toLowerCase() !== dispatch.execution.provider.toLowerCase()) {
+        throw new Error("API-key secret grant provider does not match dispatch provider.");
+    }
+    const expiresAt = Date.parse(grant.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+        throw new Error("API-key secret grant is expired.");
+    }
+}
+function exactSecrets(dispatch) {
+    return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
+}

package/dist/session/session.types.d.ts

@@ -0,0 +1,107 @@
+export interface RunOnceDispatchPacket {
+    readonly schemaVersion: 1;
+    readonly userId: string;
+    readonly workItem: DispatchWorkItem;
+    readonly repo: DispatchRepo;
+    readonly cycleRun: DispatchCycleRun;
+    readonly session: DispatchSession;
+    readonly lease: DispatchLease;
+    readonly execution: DispatchExecution;
+    readonly serverLocal: DispatchServerLocalConfig;
+    readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
+}
+export interface DispatchWorkItem {
+    readonly id: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly description: string;
+    readonly acceptanceCriteria: string;
+    readonly reproSteps: string;
+    readonly systemInfo: string;
+}
+export interface DispatchRepo {
+    readonly id: string;
+    readonly name: string;
+    readonly remoteUrl: string;
+    readonly defaultBranch: string;
+    readonly cloneOnDemand: boolean;
+    readonly serverLocalPath?: string | null;
+}
+export interface DispatchCycleRun {
+    readonly id: string;
+    readonly kind: string;
+    readonly phase: string;
+    readonly requestedBase: string;
+    readonly baseBranch: string;
+    readonly expectedCurrentBranch?: string | null;
+    readonly attempt: number;
+    readonly model: string;
+}
+export interface DispatchSession {
+    readonly id: string;
+    readonly model: string;
+    readonly lane: string;
+}
+export interface DispatchLease {
+    readonly id: string;
+    readonly worktreeKey: string;
+    readonly lane: string;
+    readonly fencingToken: string;
+    readonly expiresAt: string;
+}
+export interface DispatchExecution {
+    readonly provider: string;
+    readonly model: string;
+    readonly authKind: string;
+    readonly location: string;
+    readonly runnerId?: string | null;
+    readonly repoId: string;
+    readonly role: string;
+    readonly lane: string;
+    readonly requiresApiKeySecretGrant: boolean;
+}
+export interface ApiKeySecretGrant {
+    readonly grantId: string;
+    readonly provider: string;
+    readonly secret: string;
+    readonly expiresAt: string;
+}
+export interface DispatchServerLocalConfig {
+    readonly repoRoot: string;
+    readonly cleanupWorktrees: boolean;
+}
+export interface RunnerDispatchEvent {
+    readonly role: string;
+    readonly kind: string;
+    readonly content: string;
+    readonly eventType: string;
+}
+export interface RunnerDispatchSpec {
+    readonly repoPath: string;
+    readonly path: string;
+    readonly body: string;
+    readonly producedBy: string;
+    readonly status: string;
+}
+export interface RunnerDispatchArtifact {
+    readonly repoPath: string;
+    readonly path: string;
+    readonly verdictJson: string;
+    readonly report: string;
+    readonly producedBy: string;
+    readonly status: string;
+}
+export interface RunOnceResultPacket {
+    readonly schemaVersion: 1;
+    readonly exitCode: number;
+    readonly summary: string;
+    readonly events: readonly RunnerDispatchEvent[];
+    readonly spec?: RunnerDispatchSpec | null;
+    readonly artifact?: RunnerDispatchArtifact | null;
+}
+export interface RunnerEventLine {
+    readonly type: "runner_event";
+    readonly event: RunnerDispatchEvent;
+}
+export declare function parseRunOnceDispatchPacket(value: unknown): RunOnceDispatchPacket;
+export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[]): RunOnceResultPacket;

package/dist/session/session.types.js

@@ -0,0 +1,151 @@
+export function parseRunOnceDispatchPacket(value) {
+    const packet = asObject(value, "dispatch packet");
+    const schemaVersion = requiredNumber(packet, "schemaVersion");
+    if (schemaVersion !== 1) {
+        throw new Error(`Unsupported dispatch schemaVersion: ${schemaVersion}`);
+    }
+    return {
+        schemaVersion: 1,
+        userId: requiredString(packet, "userId"),
+        workItem: parseWorkItem(packet.workItem),
+        repo: parseRepo(packet.repo),
+        cycleRun: parseCycleRun(packet.cycleRun),
+        session: parseSession(packet.session),
+        lease: parseLease(packet.lease),
+        execution: parseExecution(packet.execution),
+        serverLocal: parseServerLocal(packet.serverLocal),
+        apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant)
+    };
+}
+export function failureResult(summary, events = []) {
+    return {
+        schemaVersion: 1,
+        exitCode: 1,
+        summary,
+        events
+    };
+}
+function parseWorkItem(value) {
+    const item = asObject(value, "workItem");
+    return {
+        id: requiredString(item, "id"),
+        kind: requiredString(item, "kind"),
+        title: requiredString(item, "title"),
+        description: optionalString(item, "description") ?? "",
+        acceptanceCriteria: optionalString(item, "acceptanceCriteria") ?? "",
+        reproSteps: optionalString(item, "reproSteps") ?? "",
+        systemInfo: optionalString(item, "systemInfo") ?? ""
+    };
+}
+function parseRepo(value) {
+    const repo = asObject(value, "repo");
+    return {
+        id: requiredString(repo, "id"),
+        name: requiredString(repo, "name"),
+        remoteUrl: optionalString(repo, "remoteUrl") ?? "",
+        defaultBranch: requiredString(repo, "defaultBranch"),
+        cloneOnDemand: requiredBoolean(repo, "cloneOnDemand"),
+        serverLocalPath: optionalString(repo, "serverLocalPath")
+    };
+}
+function parseCycleRun(value) {
+    const cycle = asObject(value, "cycleRun");
+    return {
+        id: requiredString(cycle, "id"),
+        kind: requiredString(cycle, "kind"),
+        phase: requiredString(cycle, "phase"),
+        requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
+        baseBranch: optionalString(cycle, "baseBranch") ?? "develop",
+        expectedCurrentBranch: optionalString(cycle, "expectedCurrentBranch"),
+        attempt: requiredNumber(cycle, "attempt"),
+        model: requiredString(cycle, "model")
+    };
+}
+function parseSession(value) {
+    const session = asObject(value, "session");
+    return {
+        id: requiredString(session, "id"),
+        model: requiredString(session, "model"),
+        lane: requiredString(session, "lane")
+    };
+}
+function parseLease(value) {
+    const lease = asObject(value, "lease");
+    return {
+        id: requiredString(lease, "id"),
+        worktreeKey: requiredString(lease, "worktreeKey"),
+        lane: requiredString(lease, "lane"),
+        fencingToken: requiredString(lease, "fencingToken"),
+        expiresAt: requiredString(lease, "expiresAt")
+    };
+}
+function parseExecution(value) {
+    const execution = asObject(value, "execution");
+    return {
+        provider: requiredString(execution, "provider"),
+        model: requiredString(execution, "model"),
+        authKind: requiredString(execution, "authKind"),
+        location: requiredString(execution, "location"),
+        runnerId: optionalString(execution, "runnerId"),
+        repoId: requiredString(execution, "repoId"),
+        role: requiredString(execution, "role"),
+        lane: requiredString(execution, "lane"),
+        requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant")
+    };
+}
+function parseApiKeySecretGrant(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const grant = asObject(value, "apiKeySecretGrant");
+    return {
+        grantId: requiredString(grant, "grantId"),
+        provider: requiredString(grant, "provider"),
+        secret: requiredString(grant, "secret"),
+        expiresAt: requiredString(grant, "expiresAt")
+    };
+}
+function parseServerLocal(value) {
+    const serverLocal = asObject(value, "serverLocal");
+    return {
+        repoRoot: requiredString(serverLocal, "repoRoot"),
+        cleanupWorktrees: requiredBoolean(serverLocal, "cleanupWorktrees")
+    };
+}
+function asObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function requiredString(source, key) {
+    const value = source[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function optionalString(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string when provided.`);
+    }
+    return value;
+}
+function requiredBoolean(source, key) {
+    const value = source[key];
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean.`);
+    }
+    return value;
+}
+function requiredNumber(source, key) {
+    const value = source[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a finite number.`);
+    }
+    return value;
+}

package/dist/shared/git/git.d.ts

@@ -0,0 +1,6 @@
+import { type ProcessRunner } from "../process/process.js";
+export declare class GitClient {
+    private readonly processRunner;
+    constructor(processRunner?: ProcessRunner);
+    run(cwd: string, args: readonly string[]): Promise<string>;
+}

package/dist/shared/git/git.js

@@ -0,0 +1,18 @@
+import { NodeProcessRunner } from "../process/process.js";
+export class GitClient {
+    processRunner;
+    constructor(processRunner = new NodeProcessRunner()) {
+        this.processRunner = processRunner;
+    }
+    async run(cwd, args) {
+        const result = await this.processRunner.run({
+            command: "git",
+            args,
+            cwd
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim()}`);
+        }
+        return result.stdout;
+    }
+}

package/dist/shared/path/path.d.ts

@@ -0,0 +1,4 @@
+export declare function isSubPath(root: string, candidate: string): boolean;
+export declare function resolveExistingDirectoryPath(inputPath: string): Promise<string>;
+export declare function ensureDirectory(inputPath: string): Promise<string>;
+export declare function safeSegment(value: string, fallback: string): string;

package/dist/shared/path/path.js

@@ -0,0 +1,29 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export function isSubPath(root, candidate) {
+    const normalizedRoot = path.resolve(root);
+    const normalizedCandidate = path.resolve(candidate);
+    const relative = path.relative(normalizedRoot, normalizedCandidate);
+    return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+export async function resolveExistingDirectoryPath(inputPath) {
+    const stat = await fs.stat(inputPath);
+    if (!stat.isDirectory()) {
+        throw new Error(`Path is not a directory: ${inputPath}`);
+    }
+    return await fs.realpath(inputPath);
+}
+export async function ensureDirectory(inputPath) {
+    await fs.mkdir(inputPath, { recursive: true });
+    return await resolveExistingDirectoryPath(inputPath);
+}
+export function safeSegment(value, fallback) {
+    const segment = value
+        .trim()
+        .split("")
+        .map((ch) => (/[a-zA-Z0-9_-]/.test(ch) ? ch : "-"))
+        .join("")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return segment.length > 0 ? segment : fallback;
+}

package/dist/shared/process/process.d.ts

@@ -0,0 +1,16 @@
+export interface ProcessRunRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+}
+export interface ProcessRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ProcessRunner {
+    run(request: ProcessRunRequest): Promise<ProcessRunResult>;
+}
+export declare class NodeProcessRunner implements ProcessRunner {
+    run(request: ProcessRunRequest): Promise<ProcessRunResult>;
+}

package/dist/shared/process/process.js

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+export class NodeProcessRunner {
+    async run(request) {
+        return await new Promise((resolve, reject) => {
+            const child = spawn(request.command, request.args, {
+                cwd: request.cwd,
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+            let stdout = "";
+            let stderr = "";
+            child.on("error", reject);
+            const stdoutReader = readline.createInterface({ input: child.stdout });
+            const stderrReader = readline.createInterface({ input: child.stderr });
+            stdoutReader.on("line", (line) => {
+                stdout += `${line}\n`;
+            });
+            stderrReader.on("line", (line) => {
+                stderr += `${line}\n`;
+            });
+            child.on("close", (code) => {
+                stdoutReader.close();
+                stderrReader.close();
+                resolve({
+                    exitCode: code ?? 1,
+                    stdout,
+                    stderr
+                });
+            });
+        });
+    }
+}