@emiliosp/pi-maestro 0.5.2 → 0.6.0

package/src/git/command.ts

@@ -1,172 +0,0 @@
-/**
- * Objective: Run Git commands with consistent errors and timeouts.
- * Used: By Maestro Git modules for every Git operation.
- */
-
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-
-const execFileAsync = promisify(execFile);
-
-export const DEFAULT_GIT_TIMEOUT_MS = 10_000;
-
-export type GitCommandResult = {
-  arguments: readonly string[];
-  cwd: string;
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-};
-
-export const GIT_COMMAND_ERROR_CODES = {
-  COMMAND_FAILED: 'command-failed',
-  EXECUTION_FAILED: 'execution-failed',
-  NOT_FOUND: 'not-found',
-  TIMEOUT: 'timeout',
-} as const;
-
-export type GitCommandErrorCode =
-  (typeof GIT_COMMAND_ERROR_CODES)[keyof typeof GIT_COMMAND_ERROR_CODES];
-
-type GitCommandErrorInput = {
-  code: GitCommandErrorCode;
-  message: string;
-  arguments: readonly string[];
-  cwd: string;
-  stdout: string;
-  stderr: string;
-  exitCode?: number | null;
-  cause: unknown;
-};
-
-export class GitCommandError extends Error {
-  readonly code: GitCommandErrorCode;
-  readonly arguments: readonly string[];
-  readonly cwd: string;
-  readonly stdout: string;
-  readonly stderr: string;
-  readonly exitCode: number | null;
-
-  constructor({
-    code,
-    message,
-    arguments: gitArguments,
-    cwd,
-    stdout,
-    stderr,
-    exitCode = null,
-    cause,
-  }: GitCommandErrorInput) {
-    super(message, { cause });
-    this.name = 'GitCommandError';
-    this.code = code;
-    this.arguments = gitArguments;
-    this.cwd = cwd;
-    this.stdout = stdout;
-    this.stderr = stderr;
-    this.exitCode = exitCode;
-  }
-}
-
-type GitExecutionError = {
-  message: string;
-  code?: string | number;
-  killed?: boolean;
-  stdout?: string;
-  stderr?: string;
-};
-
-const isGitExecutionError = (value: unknown): value is GitExecutionError =>
-  value instanceof Error;
-
-const isNumericExitCode = (value: unknown): value is number =>
-  typeof value === 'number';
-
-type RunGitCommandInput = {
-  arguments: readonly string[];
-  cwd?: string;
-  timeoutMs?: number;
-  environment?: NodeJS.ProcessEnv;
-};
-
-// git <arguments>
-export const runGitCommand = async ({
-  arguments: gitArguments,
-  cwd = process.cwd(),
-  timeoutMs = DEFAULT_GIT_TIMEOUT_MS,
-  environment,
-}: RunGitCommandInput): Promise<GitCommandResult> => {
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
-    throw new RangeError('Git command timeout must be a positive integer.');
-  }
-
-  try {
-    const { stdout, stderr } = await execFileAsync('git', [...gitArguments], {
-      cwd,
-      encoding: 'utf8',
-      env: environment,
-      killSignal: 'SIGKILL',
-      timeout: timeoutMs,
-      windowsHide: true,
-    });
-
-    return {
-      arguments: gitArguments,
-      cwd,
-      stdout,
-      stderr,
-      exitCode: 0,
-    };
-  } catch (error) {
-    const executionError: GitExecutionError = isGitExecutionError(error)
-      ? error
-      : new Error('Git command failed with an unknown error.', {
-          cause: error,
-        });
-
-    const stdout = executionError.stdout ?? '';
-    const stderr = executionError.stderr ?? '';
-
-    if (executionError.killed) {
-      throw new GitCommandError({
-        code: GIT_COMMAND_ERROR_CODES.TIMEOUT,
-        message: `Git command timed out after ${timeoutMs} ms.`,
-        arguments: gitArguments,
-        cwd,
-        stdout,
-        stderr,
-        cause: error,
-      });
-    }
-
-    if (executionError.code === 'ENOENT') {
-      throw new GitCommandError({
-        code: GIT_COMMAND_ERROR_CODES.NOT_FOUND,
-        message: 'Git executable was not found.',
-        arguments: gitArguments,
-        cwd,
-        stdout,
-        stderr,
-        cause: error,
-      });
-    }
-
-    const exitCode = isNumericExitCode(executionError.code)
-      ? executionError.code
-      : null;
-
-    throw new GitCommandError({
-      code:
-        exitCode === null
-          ? GIT_COMMAND_ERROR_CODES.EXECUTION_FAILED
-          : GIT_COMMAND_ERROR_CODES.COMMAND_FAILED,
-      message: `Git command failed: ${executionError.message}`,
-      arguments: gitArguments,
-      cwd,
-      stdout,
-      stderr,
-      exitCode,
-      cause: error,
-    });
-  }
-};

package/src/git/commits/createCommit.ts

@@ -1,76 +0,0 @@
-/**
- * Objective: Create a checkpoint commit containing exactly the expected paths.
- * Used: When Maestro records a workflow checkpoint.
- */
-
-import { isAbsolute, relative } from 'node:path';
-import { runGitCommand } from '#git/command.ts';
-import { getStagedPaths } from '#git/commits/getStagedPaths.ts';
-import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
-
-export const WORKFLOW_CHECKPOINT_COMMIT_MESSAGE = 'maestro workflow checkpoint';
-
-type HasSamePathsInput = {
-  actual: readonly string[];
-  expected: readonly string[];
-};
-
-const hasSamePaths = ({ actual, expected }: HasSamePathsInput): boolean => {
-  if (actual.length !== expected.length) {
-    return false;
-  }
-
-  return actual.every((path) => expected.includes(path));
-};
-
-// git add <path>...
-// git diff --cached --name-only -z
-// git commit --message <message>
-// git rev-parse --verify HEAD^{commit}
-type CreateCommitInput = {
-  repositoryRoot: string;
-  expectedPaths: readonly string[];
-  message?: string;
-};
-
-export const createCommit = async ({
-  repositoryRoot,
-  expectedPaths,
-  message = WORKFLOW_CHECKPOINT_COMMIT_MESSAGE,
-}: CreateCommitInput): Promise<string> => {
-  const expectedGitPaths = expectedPaths.map((path) => {
-    if (
-      !isAbsolute(path) ||
-      !isPathStrictlyWithin({ parent: repositoryRoot, candidate: path })
-    ) {
-      throw new Error(
-        `Checkpoint path must be inside the repository: ${path}.`,
-      );
-    }
-
-    return relative(repositoryRoot, path);
-  });
-
-  await runGitCommand({
-    arguments: ['add', '--', ...expectedPaths],
-    cwd: repositoryRoot,
-  });
-
-  const stagedPaths = await getStagedPaths(repositoryRoot);
-
-  if (!hasSamePaths({ actual: stagedPaths, expected: expectedGitPaths })) {
-    throw new Error('Checkpoint has staged paths outside the expected set.');
-  }
-
-  await runGitCommand({
-    arguments: ['commit', '--message', message],
-    cwd: repositoryRoot,
-  });
-
-  const result = await runGitCommand({
-    arguments: ['rev-parse', '--verify', 'HEAD^{commit}'],
-    cwd: repositoryRoot,
-  });
-
-  return result.stdout.trim();
-};

package/src/git/commits/createWorkflowCheckpointCommit.ts

@@ -1,24 +0,0 @@
-/**
- * Objective: Create a workflow checkpoint commit containing exactly the expected paths.
- * Used: When Maestro records a workflow checkpoint.
- */
-
-import {
-  createCommit,
-  WORKFLOW_CHECKPOINT_COMMIT_MESSAGE,
-} from '#git/commits/createCommit.ts';
-
-type CreateWorkflowCheckpointCommitInput = {
-  repositoryRoot: string;
-  expectedPaths: readonly string[];
-};
-
-export const createWorkflowCheckpointCommit = async ({
-  repositoryRoot,
-  expectedPaths,
-}: CreateWorkflowCheckpointCommitInput): Promise<string> =>
-  createCommit({
-    repositoryRoot,
-    expectedPaths,
-    message: WORKFLOW_CHECKPOINT_COMMIT_MESSAGE,
-  });

package/src/git/commits/findCommitByMessage.ts

@@ -1,39 +0,0 @@
-/**
- * Objective: Find a commit by its exact subject.
- * Used: When Maestro finds a checkpoint by its subject.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// Finds a commit whose subject exactly matches the given message.
-// git log --all --format=%H%x00%s --fixed-strings --grep=<message>
-type FindCommitByMessageInput = {
-  repositoryRoot: string;
-  message: string;
-};
-
-export const findCommitByMessage = async ({
-  repositoryRoot,
-  message,
-}: FindCommitByMessageInput): Promise<string | undefined> => {
-  const result = await runGitCommand({
-    arguments: [
-      'log',
-      '--all',
-      '--format=%H%x00%s',
-      '--fixed-strings',
-      `--grep=${message}`,
-    ],
-    cwd: repositoryRoot,
-  });
-
-  for (const line of result.stdout.split(/\r?\n/)) {
-    const [commit, subject] = line.split('\0');
-
-    if (subject === message) {
-      return commit;
-    }
-  }
-
-  return undefined;
-};

package/src/git/commits/getStagedPaths.ts

@@ -1,23 +0,0 @@
-/**
- * Objective: List staged paths.
- * Used: When Maestro checks the exact paths staged for a checkpoint.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// Parses Git's NUL-delimited path output.
-const parsePaths = (output: string): readonly string[] =>
-  output.split('\0').filter((path) => path.length > 0);
-
-// Lists the paths currently staged for commit.
-// git diff --cached --name-only -z
-export const getStagedPaths = async (
-  repositoryRoot: string,
-): Promise<readonly string[]> => {
-  const result = await runGitCommand({
-    arguments: ['diff', '--cached', '--name-only', '-z'],
-    cwd: repositoryRoot,
-  });
-
-  return parsePaths(result.stdout);
-};

package/src/git/history/getParentCommit.ts

@@ -1,25 +0,0 @@
-/**
- * Objective: Read the parent of a commit.
- * Used: When Maestro checks a checkpoint parent.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// Gets a commit's direct parent.
-// git rev-parse --verify <commit>^
-type GetParentCommitInput = {
-  repositoryRoot: string;
-  commit: string;
-};
-
-export const getParentCommit = async ({
-  repositoryRoot,
-  commit,
-}: GetParentCommitInput): Promise<string> => {
-  const result = await runGitCommand({
-    arguments: ['rev-parse', '--verify', `${commit}^`],
-    cwd: repositoryRoot,
-  });
-
-  return result.stdout.trim();
-};

package/src/git/repository/assertRepositoryTrusted.ts

@@ -1,16 +0,0 @@
-/**
- * Objective: Check that Git can inspect this repository.
- * Used: When Maestro checks that Git can inspect a repository.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// git status --porcelain=v1 --untracked-files=no
-export async function assertRepositoryTrusted(
-  repositoryRoot: string,
-): Promise<void> {
-  await runGitCommand({
-    arguments: ['status', '--porcelain=v1', '--untracked-files=no'],
-    cwd: repositoryRoot,
-  });
-}

package/src/git/repository/findRepositoryRoot.ts

@@ -1,19 +0,0 @@
-/**
- * Objective: Find the repository root from a working directory.
- * Used: When Maestro discovers the Git root from a working directory.
- */
-
-import { realpath } from 'node:fs/promises';
-import { runGitCommand } from '#git/command.ts';
-
-// git rev-parse --path-format=absolute --show-toplevel
-export const findRepositoryRoot = async (
-  cwd: string = process.cwd(),
-): Promise<string> => {
-  const result = await runGitCommand({
-    arguments: ['rev-parse', '--path-format=absolute', '--show-toplevel'],
-    cwd,
-  });
-
-  return realpath(result.stdout.trim());
-};

package/src/git/repository/getCurrentBranch.ts

@@ -1,18 +0,0 @@
-/**
- * Objective: Read the current Git branch.
- * Used: When Maestro reports the branch of the current checkout.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// git symbolic-ref --quiet --short HEAD
-export const getCurrentBranch = async (
-  repositoryRoot: string,
-): Promise<string> => {
-  const result = await runGitCommand({
-    arguments: ['symbolic-ref', '--quiet', '--short', 'HEAD'],
-    cwd: repositoryRoot,
-  });
-
-  return result.stdout.replace(/\r?\n$/, '');
-};

package/src/git/repository/getHeadCommit.ts

@@ -1,18 +0,0 @@
-/**
- * Objective: Read the current HEAD commit.
- * Used: When Maestro records a workflow commit.
- */
-
-import { runGitCommand } from '#git/command.ts';
-
-// git rev-parse --verify HEAD^{commit}
-export const getHeadCommit = async (
-  repositoryRoot: string,
-): Promise<string> => {
-  const result = await runGitCommand({
-    arguments: ['rev-parse', '--verify', 'HEAD^{commit}'],
-    cwd: repositoryRoot,
-  });
-
-  return result.stdout.replace(/\r?\n$/, '');
-};

package/src/git/repository/getRepositoryStatus.ts

@@ -1,74 +0,0 @@
-/**
- * Objective: Read all staged, unstaged, and untracked changes in the current checkout.
- * Used: When Maestro checks whether the current checkout is clean.
- */
-
-import { type GitCommandResult, runGitCommand } from '#git/command.ts';
-
-export type RepositoryStatus = {
-  clean: boolean;
-  staged: readonly string[];
-  unstaged: readonly string[];
-  untracked: readonly string[];
-};
-
-const parseRepositoryStatus = (result: GitCommandResult): RepositoryStatus => {
-  const staged: string[] = [];
-  const unstaged: string[] = [];
-  const untracked: string[] = [];
-  const records = result.stdout.split('\0');
-
-  for (let index = 0; index < records.length; index += 1) {
-    const record = records[index];
-
-    if (record.length === 0) {
-      continue;
-    }
-
-    const indexStatus = record[0];
-    const worktreeStatus = record[1];
-    const path = record.slice(3);
-
-    if (indexStatus === '?' && worktreeStatus === '?') {
-      untracked.push(path);
-      continue;
-    }
-
-    if (indexStatus !== ' ') {
-      staged.push(path);
-    }
-
-    if (worktreeStatus !== ' ') {
-      unstaged.push(path);
-    }
-
-    if (
-      indexStatus === 'R' ||
-      indexStatus === 'C' ||
-      worktreeStatus === 'R' ||
-      worktreeStatus === 'C'
-    ) {
-      index += 1;
-    }
-  }
-
-  return {
-    clean:
-      staged.length === 0 && unstaged.length === 0 && untracked.length === 0,
-    staged,
-    unstaged,
-    untracked,
-  };
-};
-
-// git status --porcelain=v1 --untracked-files=all -z
-export const getRepositoryStatus = async (
-  repositoryRoot: string,
-): Promise<RepositoryStatus> => {
-  const result = await runGitCommand({
-    arguments: ['status', '--porcelain=v1', '--untracked-files=all', '-z'],
-    cwd: repositoryRoot,
-  });
-
-  return parseRepositoryStatus(result);
-};

package/src/git/utils/hasGitExitCode.ts

@@ -1,19 +0,0 @@
-/**
- * Objective: Identify a Git command failure with a specific exit code.
- * Used: By Maestro Git modules when handling unsuccessful commands.
- */
-
-import { GIT_COMMAND_ERROR_CODES, GitCommandError } from '#git/command.ts';
-
-type HasGitExitCodeInput = {
-  error: unknown;
-  exitCode: number;
-};
-
-export const hasGitExitCode = ({
-  error,
-  exitCode,
-}: HasGitExitCodeInput): boolean =>
-  error instanceof GitCommandError &&
-  error.code === GIT_COMMAND_ERROR_CODES.COMMAND_FAILED &&
-  error.exitCode === exitCode;

package/src/utils/write-atomically.ts

@@ -1,41 +0,0 @@
-/**
- * Objective: Safely replace a file with complete UTF-8 content.
- * Used: When Maestro writes state or artifact files.
- */
-
-import { randomUUID } from 'node:crypto';
-import { type FileHandle, open, rename, rm } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-
-const temporaryPathFor = (path: string): string =>
-  join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
-
-type WriteAtomicallyInput = {
-  path: string;
-  content: string;
-};
-
-export const writeAtomically = async ({
-  path,
-  content,
-}: WriteAtomicallyInput): Promise<void> => {
-  const temporaryPath = temporaryPathFor(path);
-  let file: FileHandle | undefined;
-
-  try {
-    file = await open(temporaryPath, 'wx', 0o600);
-    await file.writeFile(content, 'utf8');
-    await file.sync();
-    await file.close();
-    file = undefined;
-    await rename(temporaryPath, path);
-  } finally {
-    try {
-      if (file !== undefined) {
-        await file.close();
-      }
-    } finally {
-      await rm(temporaryPath, { force: true });
-    }
-  }
-};

package/src/utils/write-json-atomically.ts

@@ -1,28 +0,0 @@
-/**
- * Objective: Serialize JSON and replace its destination atomically.
- * Used: When Maestro writes workflow state and artifact JSON files.
- */
-
-import { writeAtomically } from '#utils/write-atomically.ts';
-
-const jsonContent = (data: unknown): string => {
-  const content = JSON.stringify(data, null, 2);
-
-  if (content === undefined) {
-    throw new Error('JSON data must be serializable.');
-  }
-
-  return `${content}\n`;
-};
-
-type WriteJsonAtomicallyInput = {
-  path: string;
-  data: unknown;
-};
-
-export const writeJsonAtomically = async ({
-  path,
-  data,
-}: WriteJsonAtomicallyInput): Promise<void> => {
-  await writeAtomically({ path, content: jsonContent(data) });
-};