Operations interfaces for dependency injection.
This is the core pattern enabling testability without mocks. All side effects (git, npm, fs, process) are abstracted into interfaces.
Design principles: - All operations accept a single
optionsobject parameter - All fallible operations returnResultfrom@ryanatkn/belt- Never throwErrorin operations - returnResultwithok: false- Usenullfor expected "not found" cases (not errors) - Includelog?: Loggerin options where logging is usefulProduction usage: ```typescript import {default_gitops_operations} from './operations_defaults.js'; const result = await ops.git.current_branch_name({cwd: '/path'}); if (!result.ok) { throw new TaskError(result.message); } const branch = result.value; ```
Test usage: ```typescript const mock_ops = create_mock_operations(); const result = await publish_repos(repos, {...options, ops: mock_ops}); // Assert on result without any real git/npm calls ```
See operations_defaults.ts for real implementations. See test files (*.test.ts) for mock implementations.
8 declarations
BuildOperations Build operations for validating packages compile before publishing.
build_packageBuilds a package using gro build.
(options: {
repo: LocalRepo;
log?: Logger;
}) => Promise<Result<object, {message: string; output?: string}>>ChangesetOperations Changeset operations for reading and predicting versions from .changeset/*.md files.
has_changesetsChecks if a repo has any changeset files. Returns true if changesets exist, false if none found.
(options: {
repo: LocalRepo;
}) => Promise<Result<{value: boolean}, {message: string}>>read_changesetsReads all changeset files from a repo. Returns array of changeset info, or error if reading fails.
(options: {
repo: LocalRepo;
log?: Logger;
}) => Promise<Result<{value: Array<ChangesetInfo>}, {message: string}>>predict_next_versionPredicts the next version based on changesets. Returns null if no changesets found (expected, not an error). Returns error Result if changesets exist but can't be read/parsed.
(options: {
repo: LocalRepo;
log?: Logger;
}) => Promise<Result<{version: string; bump_type: BumpType}, {message: string}> | null>FsOperations File system operations for reading and writing files.
readFileReads a file from the file system.
(options: {
path: string;
encoding: BufferEncoding;
}) => Promise<Result<{value: string}, {message: string}>>writeFileWrites a file to the file system.
(options: {
path: string;
content: string;
}) => Promise<Result<object, {message: string}>>GitOperations Git operations for branch management, commits, tags, and workspace state.
All operations return Result instead of throwing errors.
current_branch_nameGets the current branch name.
(options?: {
cwd?: string;
}) => Promise<Result<{value: string}, {message: string}>>current_commit_hashGets the current commit hash.
(options?: {
branch?: string;
cwd?: string;
}) => Promise<Result<{value: string}, {message: string}>>check_clean_workspaceChecks if the workspace is clean (no uncommitted changes).
(options?: {
cwd?: string;
}) => Promise<Result<{value: boolean}, {message: string}>>checkoutChecks out a branch.
(options: {branch: string; cwd?: string}) => Promise<Result<object, {message: string}>>pullPulls changes from remote.
(options?: {
origin?: string;
branch?: string;
cwd?: string;
}) => Promise<Result<object, {message: string}>>switch_branchSwitches to a branch, optionally pulling.
(options: {
branch: string;
pull?: boolean;
cwd?: string;
}) => Promise<Result<object, {message: string}>>has_remoteChecks if a remote exists.
(options?: {
remote?: string;
cwd?: string;
}) => Promise<Result<{value: boolean}, {message: string}>>addStages files for commit.
(options: {
files: string | Array<string>;
cwd?: string;
}) => Promise<Result<object, {message: string}>>commitCreates a commit.
(options: {message: string; cwd?: string}) => Promise<Result<object, {message: string}>>add_and_commitStages files and creates a commit.
(options: {
files: string | Array<string>;
message: string;
cwd?: string;
}) => Promise<Result<object, {message: string}>>has_changesChecks if there are any uncommitted changes.
(options?: {cwd?: string}) => Promise<Result<{value: boolean}, {message: string}>>get_changed_filesGets a list of changed files.
(options?: {
cwd?: string;
}) => Promise<Result<{value: Array<string>}, {message: string}>>tagCreates a git tag.
(options: {
tag_name: string;
message?: string;
cwd?: string;
}) => Promise<Result<object, {message: string}>>push_tagPushes a tag to remote.
(options: {
tag_name: string;
origin?: string;
cwd?: string;
}) => Promise<Result<object, {message: string}>>stashStashes uncommitted changes.
(options?: {message?: string; cwd?: string}) => Promise<Result<object, {message: string}>>stash_popPops the most recent stash.
(options?: {cwd?: string}) => Promise<Result<object, {message: string}>>has_file_changedChecks if a specific file changed between two commits.
(options: {
from_commit: string;
to_commit: string;
file_path: string;
cwd?: string;
}) => Promise<Result<{value: boolean}, {message: string}>>GitopsOperations Combined operations interface grouping all gitops functionality. This is the main interface injected into publishing and validation workflows.
changesetgitprocessnpmpreflightfsbuildNpmOperations NPM registry operations for package availability checks and authentication. Includes exponential backoff for waiting on package propagation.
wait_for_packageWaits for a package version to be available on NPM. Uses exponential backoff with configurable timeout.
(options: {
pkg: string;
version: string;
wait_options?: WaitOptions;
log?: Logger;
}) => Promise<Result<object, {message: string; timeout?: boolean}>>check_package_availableChecks if a package version is available on NPM.
(options: {
pkg: string;
version: string;
log?: Logger;
}) => Promise<Result<{value: boolean}, {message: string}>>check_authChecks npm authentication status.
() => Promise<Result<{username: string}, {message: string}>>check_registryChecks if npm registry is reachable.
() => Promise<Result<object, {message: string}>>installInstalls npm dependencies.
(options?: {
cwd?: string;
}) => Promise<Result<object, {message: string; stderr?: string}>>cache_cleanCleans the npm cache.
Uses npm cache clean --force to clear stale cache entries.
() => Promise<Result<object, {message: string}>>PreflightOperations Preflight validation operations to ensure repos are ready for publishing. Validates workspace state, branches, builds, and npm authentication.
run_preflight_checksRuns preflight validation checks before publishing.
(options: {
repos: Array<LocalRepo>;
preflight_options: PreflightOptions;
git_ops?: GitOperations;
npm_ops?: NpmOperations;
build_ops?: BuildOperations;
changeset_ops?: ChangesetOperations;
}) => Promise<PreflightResult>ProcessOperations Process spawning operations for running shell commands.
spawnSpawns a child process and waits for completion.
(options: {
cmd: string;
args: Array<string>;
spawn_options?: SpawnOptions;
}) => Promise<Result<{stdout?: string; stderr?: string}, {message: string; stderr?: string}>>