@axelmth/repoflow-core

Core library for repoflow — config loading, repository abstractions, and workspace orchestration for multi-repo setups.

[!WARNING] Status: Pre-alpha — APIs will change without notice. Not ready for production use.

Install

npm i @axelmth/repoflow-core
# or
pnpm add @axelmth/repoflow-core

Usage

Load config

import { loadConfig } from '@axelmth/repoflow-core'

const config = await loadConfig() // walks up from cwd to find repoflow.config.ts

Workspace

import { loadConfig, Workspace } from '@axelmth/repoflow-core'

const config = await loadConfig()
const workspace = await Workspace.fromConfig(config)

// Sequential
await workspace.forEach(async (repo) => {
  console.log(repo.name, await repo.currentBranch())
})

// Parallel (max 4 concurrent)
await workspace.parallel(async (repo) => {
  await repo.pull()
})

Define config (typed helper)

import { defineConfig } from '@axelmth/repoflow-core'

export default defineConfig({
  repos: [
    { name: 'backend', url: '[email protected]:acme/backend.git' },
    { name: 'web',     url: '[email protected]:acme/web.git' },
  ],
  defaultBranch: 'main',
})

API

loadConfig(cwd?)

Walks up the directory tree from cwd (default: process.cwd()) to find repoflow.config.ts, loads it via tsx, validates with zod, and applies defaults. Supports ${ENV_VAR} interpolation.

Throws ConfigNotFoundError, ConfigValidationError, or MissingEnvVarError.

Workspace

| Method | Description | |---|---| | Workspace.load(cwd?) | Load config then build workspace | | Workspace.fromConfig(config) | Build workspace from already-loaded config | | workspace.forEach(fn) | Run async function sequentially over all repos | | workspace.parallel(fn) | Run async function with max 4 concurrent repos |

Repository (exposed as Repo)

| Method/Property | Description | |---|---| | repo.isPresent | Whether the repo directory exists on disk | | repo.clone() | Clone from repo.url into repo.path | | repo.pull() | Pull latest on current branch | | repo.checkout(branch) | Checkout branch | | repo.status() | Returns RepoStatus (ahead, behind, dirty) | | repo.currentBranch() | Current branch name | | repo.lastTag() | Most recent git tag | | repo.commitsSince(ref) | Commits since a ref | | repo.isClean() | Whether working tree is clean |

License

MIT — Axel Mathieu-Le Gall