@emiliosp/pi-maestro 0.0.0-stage → 0.1.0

package/src/tools/main/launch-verifier.ts

@@ -0,0 +1,270 @@
+/**
+ * Objective: Launch and validate one foreground verifier pass for the owner session.
+ * Used: When the owner invokes the launch-verifier tool.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
+import { Type } from 'typebox';
+import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
+import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
+import { AGENTS } from '#config/schema.ts';
+import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import {
+  assertDelegationResponse,
+  waitForDelegationResponse,
+} from '#tools/utils/pi-subagent-delegation.ts';
+import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { WORKFLOW_ROLES } from '#workflow/roles.ts';
+import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
+import {
+  VERIFIER_PASS_ERRORS,
+  VERIFIER_PASS_MESSAGES,
+} from '#workflow/verifier/completeVerifierPass.ts';
+import { hasProductChanges } from '#workflow/verifier/hasProductChanges.ts';
+import {
+  prepareVerifierLaunch,
+  type VerifierLaunch,
+} from '#workflow/verifier/prepareVerifierLaunch.ts';
+
+export const LAUNCH_VERIFIER_TOOL = {
+  NAME: 'maestro_launch_verifier',
+  LABEL: 'Launch Verifier',
+  DESCRIPTION:
+    'Launch the verifier in the current checkout for a completed builder candidate. The verifier runs in the foreground.',
+} as const;
+
+const LaunchVerifierToolParameters = Type.Object(
+  {
+    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+  },
+  { additionalProperties: false },
+);
+
+const MILLISECONDS_PER_MINUTE = 60_000;
+
+type CandidateReadyResult = {
+  outcome: typeof WORKFLOW_PHASES.CANDIDATE_READY;
+  specId: string;
+  revision: number;
+  phase: typeof WORKFLOW_PHASES.CANDIDATE_READY;
+  candidateCommit: string;
+  checkpointCommit: string;
+  handoff: VerifierHandoff;
+};
+
+type FindingsResult = {
+  outcome: typeof WORKFLOW_PHASES.FINDINGS_DECISION;
+  specId: string;
+  revision: number;
+  phase: typeof WORKFLOW_PHASES.FINDINGS_DECISION;
+  candidateCommit: string;
+  checkpointCommit: string;
+  handoff: VerifierHandoff;
+};
+
+type ProductChangesResult = {
+  outcome: typeof VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED;
+  error: typeof VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED;
+  message: typeof VERIFIER_PASS_MESSAGES.PRODUCT_FILES_MODIFIED;
+  specId: string;
+  revision: number;
+  phase: typeof WORKFLOW_PHASES.VERIFIER_RUNNING;
+  candidateCommit: string;
+  checkpointCommit: string;
+};
+
+type VerifierLaunchResult =
+  | CandidateReadyResult
+  | FindingsResult
+  | ProductChangesResult;
+
+type ReadTerminalVerifierResultInput = {
+  paths: MaestroPaths;
+  specId: string;
+  launch: VerifierLaunch;
+  state: WorkflowState;
+  productChanges: boolean;
+};
+
+const readTerminalVerifierResult = async ({
+  paths,
+  specId,
+  launch,
+  state,
+  productChanges,
+}: ReadTerminalVerifierResultInput): Promise<
+  CandidateReadyResult | FindingsResult
+> => {
+  if (
+    state.phase !== WORKFLOW_PHASES.CANDIDATE_READY &&
+    state.phase !== WORKFLOW_PHASES.FINDINGS_DECISION
+  ) {
+    throw new Error(
+      `Verifier returned with unexpected workflow phase "${state.phase}".`,
+    );
+  }
+
+  if (productChanges) {
+    throw new Error(
+      'Product files differ from the candidate after the verifier handoff.',
+    );
+  }
+
+  const repositoryStatus = await getRepositoryStatus(launch.repositoryRoot);
+
+  if (!repositoryStatus.clean) {
+    throw new Error(
+      'The verifier returned without committing its final handoff.',
+    );
+  }
+
+  const handoff = await readVerifierHandoff({
+    path: paths.getVerifierHandoffPath(specId),
+    specId,
+    revision: state.revision,
+  });
+
+  const expectedPhase =
+    handoff.findings.length > 0
+      ? WORKFLOW_PHASES.FINDINGS_DECISION
+      : WORKFLOW_PHASES.CANDIDATE_READY;
+
+  if (state.phase !== expectedPhase) {
+    throw new Error(
+      `Verifier handoff findings do not match workflow phase "${state.phase}".`,
+    );
+  }
+
+  const details = {
+    specId,
+    revision: state.revision,
+    candidateCommit: launch.candidateCommit,
+    checkpointCommit: launch.checkpointCommit,
+    handoff,
+  };
+
+  if (state.phase === WORKFLOW_PHASES.CANDIDATE_READY) {
+    return { ...details, outcome: state.phase, phase: state.phase };
+  }
+
+  return { ...details, outcome: state.phase, phase: state.phase };
+};
+
+type ReadVerifierResultInput = {
+  paths: MaestroPaths;
+  specId: string;
+  launch: VerifierLaunch;
+};
+
+const readVerifierResult = async ({
+  paths,
+  specId,
+  launch,
+}: ReadVerifierResultInput): Promise<VerifierLaunchResult> => {
+  try {
+    const state = await readWorkflowState(paths.getWorkflowPath(specId));
+
+    if (state.specId !== specId) {
+      throw new Error(
+        `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
+      );
+    }
+
+    const productChanges = await hasProductChanges({
+      repositoryRoot: launch.repositoryRoot,
+      candidateCommit: launch.candidateCommit,
+      workflowPath: paths.getWorkflowPath(specId),
+      handoffPath: paths.getVerifierHandoffPath(specId),
+    });
+
+    if (state.phase === WORKFLOW_PHASES.VERIFIER_RUNNING) {
+      if (productChanges) {
+        return {
+          outcome: VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED,
+          error: VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED,
+          message: VERIFIER_PASS_MESSAGES.PRODUCT_FILES_MODIFIED,
+          specId,
+          revision: state.revision,
+          phase: state.phase,
+          candidateCommit: launch.candidateCommit,
+          checkpointCommit: launch.checkpointCommit,
+        };
+      }
+
+      throw new Error(
+        'The verifier returned without recording a valid terminal handoff.',
+      );
+    }
+
+    return await readTerminalVerifierResult({
+      paths,
+      specId,
+      launch,
+      state,
+      productChanges,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    throw new Error(`Verifier protocol error: ${message}.`, { cause: error });
+  }
+};
+
+const formatVerifierResult = (result: VerifierLaunchResult): string => {
+  if (result.outcome === WORKFLOW_PHASES.CANDIDATE_READY) {
+    return `Verifier completed spec ${result.specId}. The workflow is candidate-ready.`;
+  }
+
+  if (result.outcome === WORKFLOW_PHASES.FINDINGS_DECISION) {
+    return `Verifier found ${result.handoff.findings.length} finding(s) for spec ${result.specId}. The workflow is waiting for owner decisions.`;
+  }
+
+  return `${result.message} The workflow remains verifier-running.`;
+};
+
+export const registerLaunchVerifierTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: LAUNCH_VERIFIER_TOOL.NAME,
+    label: LAUNCH_VERIFIER_TOOL.LABEL,
+    description: LAUNCH_VERIFIER_TOOL.DESCRIPTION,
+    parameters: LaunchVerifierToolParameters,
+    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+      const { paths, config } = await resolveToolLaunchContext(context.cwd);
+
+      const launch = await prepareVerifierLaunch({ paths, specId });
+
+      const request: SubagentDelegationRequest = {
+        requestId: randomUUID(),
+        ownerRunId: toolCallId,
+        nodeId: WORKFLOW_ROLES.VERIFIER,
+        // pi-subagents loads this name from agents/verifier.md through package.json.
+        agent: AGENTS.VERIFIER,
+        task: `Verify specId "${specId}" in the current checkout "${launch.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
+        context: 'fresh',
+        cwd: launch.repositoryRoot,
+        model: config.verifier.model,
+        thinking: config.verifier.thinking,
+        timeoutMs: config.verifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
+        result: { kind: 'text' },
+      };
+
+      const response = await waitForDelegationResponse({
+        piEventsBus: pi.events,
+        request,
+      });
+
+      assertDelegationResponse(response);
+      const result = await readVerifierResult({ paths, specId, launch });
+
+      return {
+        content: [{ type: 'text', text: formatVerifierResult(result) }],
+        details: result,
+      };
+    },
+  });
+};

package/src/tools/main/mark-spec-ready.ts

@@ -0,0 +1,53 @@
+/**
+ * Objective: Register owner approval for the current Maestro specification.
+ * Used: When the owner approves the initial spec or an authorized revision.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
+import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { markSpecReady } from '#workflow/spec/markSpecReady.ts';
+
+export const MARK_SPEC_READY_TOOL = {
+  NAME: 'maestro_mark_spec_ready',
+  LABEL: 'Mark Spec Ready',
+  DESCRIPTION:
+    'Approve the current spec.md after explicit owner approval and move the workflow to ready-for-builder. The owner must commit spec.md and workflow.json before launching the builder.',
+} as const;
+
+const MarkSpecReadyToolParameters = Type.Object(
+  {
+    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+  },
+  { additionalProperties: false },
+);
+
+export const registerMarkSpecReadyTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: MARK_SPEC_READY_TOOL.NAME,
+    label: MARK_SPEC_READY_TOOL.LABEL,
+    description: MARK_SPEC_READY_TOOL.DESCRIPTION,
+    parameters: MarkSpecReadyToolParameters,
+    async execute(_toolCallId, { specId }, _signal, _onUpdate, context) {
+      const { paths } = await resolveToolLaunchContext(context.cwd);
+
+      const state = await markSpecReady({
+        paths,
+        specId,
+        activeWorkflowSpecId: maestroSessionState.getActiveSpecId(),
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Spec ${state.specId} is approved at workflow revision ${state.revision} and ready-for-builder. Commit spec.md and workflow.json before launching the builder.`,
+          },
+        ],
+        details: state,
+      };
+    },
+  });
+};

package/src/tools/main/resolve-escalation.ts

@@ -0,0 +1,67 @@
+/**
+ * Objective: Register owner resolution of the current builder escalation.
+ * Used: When the owner keeps the approved contract and chooses an escalation resolution.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import {
+  ESCALATION_ID_PATTERN,
+  EscalationResolutionSchema,
+} from '#artifacts/escalation/schema.ts';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveBuilderEscalation } from '#workflow/escalation/resolveBuilderEscalation.ts';
+
+export const RESOLVE_ESCALATION_TOOL = {
+  NAME: 'maestro_resolve_escalation',
+  LABEL: 'Resolve Escalation',
+  DESCRIPTION:
+    'Record the explicit owner decision for the current builder escalation when the approved contract remains valid. Commit the resolution and workflow transition on the current branch, then return ready-for-builder without launching the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
+} as const;
+
+const ResolveEscalationToolParameters = Type.Object(
+  {
+    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+    escalationId: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
+    ...EscalationResolutionSchema.properties,
+  },
+  { additionalProperties: false },
+);
+
+export const registerResolveEscalationTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: RESOLVE_ESCALATION_TOOL.NAME,
+    label: RESOLVE_ESCALATION_TOOL.LABEL,
+    description: RESOLVE_ESCALATION_TOOL.DESCRIPTION,
+    parameters: ResolveEscalationToolParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+      const { specId, escalationId, ...resolution } = params;
+      const { paths } = await resolveToolLaunchContext(context.cwd);
+
+      const resolved = await resolveBuilderEscalation({
+        paths,
+        specId,
+        escalationId,
+        resolution,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Escalation ${resolved.escalation.id} resolved. Spec ${resolved.state.specId} is ready-for-builder. Launch the builder separately.`,
+          },
+        ],
+        details: {
+          specId: resolved.state.specId,
+          escalationId: resolved.escalation.id,
+          revision: resolved.state.revision,
+          phase: resolved.state.phase,
+          repositoryRoot: resolved.repositoryRoot,
+          checkpointCommit: resolved.checkpointCommit,
+        },
+      };
+    },
+  });
+};

package/src/tools/main/resolve-findings.ts

@@ -0,0 +1,123 @@
+/**
+ * Objective: Register owner decisions for current verifier findings.
+ * Used: When the owner invokes the resolve-findings tool.
+ */
+
+import { StringEnum } from '@earendil-works/pi-ai';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import {
+  FINDING_DECISIONS,
+  resolveFindings,
+} from '#workflow/findings/resolveFindings.ts';
+import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+
+export const RESOLVE_FINDINGS_TOOL = {
+  NAME: 'maestro_resolve_findings',
+  LABEL: 'Resolve Findings',
+  DESCRIPTION:
+    'Record the explicit owner decision for every current verifier finding when the approved contract remains valid. Commit the resolution and workflow transition on the current branch. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
+} as const;
+
+const FindingDecisionFields = {
+  findingId: Type.String({ minLength: 1 }),
+};
+
+const RejectFindingDecisionSchema = Type.Object(
+  {
+    ...FindingDecisionFields,
+    decision: StringEnum([FINDING_DECISIONS.REJECT] as const),
+    reason: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+const FixCodeFindingDecisionSchema = Type.Object(
+  {
+    ...FindingDecisionFields,
+    decision: StringEnum([FINDING_DECISIONS.FIX_CODE] as const),
+  },
+  { additionalProperties: false },
+);
+
+const FindingDecisionSchema = Type.Union([
+  RejectFindingDecisionSchema,
+  FixCodeFindingDecisionSchema,
+]);
+
+const ResolveFindingsToolParameters = Type.Object(
+  {
+    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+    decisions: Type.Array(FindingDecisionSchema, { minItems: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+type FindingResolutionDetails = {
+  specId: string;
+  revision: number;
+  phase: string;
+  repositoryRoot: string;
+  checkpointCommit: string;
+  rejectedFindingIds: string[];
+  findingsRequiringFixIds: string[];
+};
+
+const formatFindingIds = (findingIds: string[]): string =>
+  findingIds.length === 0 ? 'none' : findingIds.join(', ');
+
+const formatResolution = (details: FindingResolutionDetails): string => {
+  const rejected = formatFindingIds(details.rejectedFindingIds);
+  const requiringFix = formatFindingIds(details.findingsRequiringFixIds);
+
+  if (details.phase === WORKFLOW_PHASES.READY_FOR_BUILDER) {
+    return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is ready-for-builder. Launch the builder separately.`;
+  }
+
+  return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is candidate-ready.`;
+};
+
+export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: RESOLVE_FINDINGS_TOOL.NAME,
+    label: RESOLVE_FINDINGS_TOOL.LABEL,
+    description: RESOLVE_FINDINGS_TOOL.DESCRIPTION,
+    parameters: ResolveFindingsToolParameters,
+    async execute(
+      _toolCallId,
+      { specId, decisions },
+      _signal,
+      _onUpdate,
+      context,
+    ) {
+      const { paths } = await resolveToolLaunchContext(context.cwd);
+
+      const resolved = await resolveFindings({
+        paths,
+        specId,
+        decisions,
+      });
+
+      const details: FindingResolutionDetails = {
+        specId: resolved.state.specId,
+        revision: resolved.state.revision,
+        phase: resolved.state.phase,
+        repositoryRoot: resolved.repositoryRoot,
+        checkpointCommit: resolved.checkpointCommit,
+        rejectedFindingIds: resolved.findings
+          .filter(({ rejection }) => rejection !== null)
+          .map(({ id }) => id),
+        findingsRequiringFixIds: resolved.findings
+          .filter(({ rejection }) => rejection === null)
+          .map(({ id }) => id),
+      };
+
+      return {
+        content: [{ type: 'text', text: formatResolution(details) }],
+        details,
+      };
+    },
+  });
+};

package/src/tools/utils/pi-subagent-delegation.ts

@@ -0,0 +1,127 @@
+/**
+ * Objective: Coordinate foreground pi-subagents delegation responses.
+ * Used: By Pi tools that launch pi-subagents agents.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  SUBAGENT_DELEGATION_REQUEST_EVENT,
+  SUBAGENT_DELEGATION_RESPONSE_EVENT,
+  type SubagentDelegationRequest,
+  type SubagentDelegationResponse,
+} from 'pi-subagents/delegation';
+
+// pi-subagents exports SubagentDelegationStatus as a type, not runtime values.
+// TypeScript erases the type, so the adapter needs these constants for comparisons.
+export const DELEGATION_STATUSES = {
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  TIMED_OUT: 'timed_out',
+  INTERRUPTED: 'interrupted',
+  CANCELLED: 'cancelled',
+  INVALID_REQUEST: 'invalid_request',
+  TOOL_BUDGET_EXHAUSTED: 'tool_budget_exhausted',
+  STRUCTURED_OUTPUT_FAILED: 'structured_output_failed',
+  ACCEPTANCE_FAILED: 'acceptance_failed',
+  UNAVAILABLE_CONTEXT: 'unavailable_context',
+  DUPLICATE_NODE: 'duplicate_node',
+} as const;
+
+export const isDelegationErrorStatus = (status: string): boolean =>
+  status === DELEGATION_STATUSES.FAILED ||
+  status === DELEGATION_STATUSES.INVALID_REQUEST ||
+  status === DELEGATION_STATUSES.TOOL_BUDGET_EXHAUSTED ||
+  status === DELEGATION_STATUSES.STRUCTURED_OUTPUT_FAILED ||
+  status === DELEGATION_STATUSES.ACCEPTANCE_FAILED ||
+  status === DELEGATION_STATUSES.UNAVAILABLE_CONTEXT ||
+  status === DELEGATION_STATUSES.DUPLICATE_NODE;
+
+type MatchesDelegationRequestInput = {
+  request: SubagentDelegationRequest;
+  payload: unknown;
+};
+
+export const matchesDelegationRequest = ({
+  request,
+  payload,
+}: MatchesDelegationRequestInput): boolean => {
+  // JUSTIFICATION: pi-subagents owns this event contract and emits a terminal response for every matching request.
+  const response = payload as SubagentDelegationResponse;
+
+  return (
+    response.requestId === request.requestId &&
+    (response.ownerRunId === undefined ||
+      response.ownerRunId === request.ownerRunId) &&
+    (response.nodeId === undefined || response.nodeId === request.nodeId)
+  );
+};
+
+type WaitForDelegationResponseInput = {
+  piEventsBus: ExtensionAPI['events'];
+  request: SubagentDelegationRequest;
+};
+
+export const waitForDelegationResponse = async ({
+  piEventsBus,
+  request,
+}: WaitForDelegationResponseInput): Promise<SubagentDelegationResponse> => {
+  const { promise, resolve } =
+    Promise.withResolvers<SubagentDelegationResponse>();
+
+  const unsubscribe = piEventsBus.on(
+    SUBAGENT_DELEGATION_RESPONSE_EVENT,
+    (payload) => {
+      if (!matchesDelegationRequest({ request, payload })) {
+        return;
+      }
+
+      // JUSTIFICATION: matchesDelegationRequest accepts only the response for this pi-subagents request.
+      resolve(payload as SubagentDelegationResponse);
+    },
+  );
+
+  try {
+    try {
+      piEventsBus.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+
+      throw new Error(`Delegation request error: ${message}`, {
+        cause: error,
+      });
+    }
+
+    return await promise;
+  } finally {
+    unsubscribe();
+  }
+};
+
+export function assertDelegationResponse(
+  response: SubagentDelegationResponse,
+): void {
+  if (response.status === DELEGATION_STATUSES.COMPLETED) {
+    return;
+  }
+
+  const error = response.error ?? 'No delegation error details were provided.';
+
+  if (response.status === DELEGATION_STATUSES.TIMED_OUT) {
+    throw new Error(`Delegation timeout: ${error}`);
+  }
+
+  if (
+    response.status === DELEGATION_STATUSES.INTERRUPTED ||
+    response.status === DELEGATION_STATUSES.CANCELLED
+  ) {
+    throw new Error(`Delegation interruption: ${error}`);
+  }
+
+  if (isDelegationErrorStatus(response.status)) {
+    throw new Error(`Delegation error: ${error}`);
+  }
+
+  throw new Error(
+    `Protocol error: unsupported final response status "${response.status}".`,
+  );
+}

package/src/tools/utils/resolveToolLaunchContext.ts

@@ -0,0 +1,28 @@
+/**
+ * Objective: Resolve the repository context shared by Pi tools.
+ * Used: Whenever a Pi tool needs the current checkout, configuration, and paths.
+ */
+
+import { loadConfiguration } from '#config/loadConfiguration.ts';
+import type { MaestroConfig } from '#config/schema.ts';
+import { findRepositoryRoot } from '#git/repository/findRepositoryRoot.ts';
+import { MaestroPaths } from '#MaestroPaths.ts';
+
+export type ToolLaunchContext = {
+  repositoryRoot: string;
+  config: MaestroConfig;
+  paths: MaestroPaths;
+};
+
+export const resolveToolLaunchContext = async (
+  cwd: string,
+): Promise<ToolLaunchContext> => {
+  const repositoryRoot = await findRepositoryRoot(cwd);
+  const config = await loadConfiguration(repositoryRoot);
+
+  return {
+    repositoryRoot,
+    config,
+    paths: new MaestroPaths({ repositoryRoot, config }),
+  };
+};

package/src/utils/getFileSha256.ts

@@ -0,0 +1,13 @@
+/**
+ * Objective: Calculate the SHA-256 digest of a file.
+ * Used: When a workflow needs to compare a file with an in-memory baseline.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+export const getFileSha256 = async (path: string): Promise<string> => {
+  const contents = await readFile(path);
+
+  return createHash('sha256').update(contents).digest('hex');
+};

package/src/utils/is-errno-exception.ts

@@ -0,0 +1,9 @@
+/**
+ * Objective: Identify filesystem errors that expose a Node error code.
+ * Used: When filesystem operations handle specific error codes.
+ */
+
+export const isErrnoException = (
+  error: unknown,
+): error is NodeJS.ErrnoException =>
+  error instanceof Error && 'code' in error && typeof error.code === 'string';