infra-ts

infra-ts is a TypeScript infrastructure checkout system. Pure, immutable definitions compile into a dependency graph; a trusted infra.ts binds provider runtimes and environment policy; the CLI reconciles that graph and activates one logical environment per Git worktree.

Packages

• @infra-ts/core — pure definitions, refs, env manifests, graph compilation, and structured ExecutionContext.
• @infra-ts/runtime — validated stacks, graph checkout, dual-scope state, filesystem persistence, config loading, secure env activation, and Git integration.
• @infra-ts/neon — lightweight buildNeonProject.
• @infra-ts/neon/runtime — hybrid shared-project/environment-branch runtime.
• @infra-ts/cli — the sole infra-ts executable.
• infra-ts — umbrella whose root exports core only. It has no executable and no CLI dependency.

Stack config

infra.ts is executable trusted code. The CLI discovers exactly that filename from the current directory toward the filesystem root and requires one default defineStack(...) export.

import { buildNeonProject } from "@infra-ts/neon";
import { neonProjectProviderBinding } from "@infra-ts/neon/runtime";
import { defineStack } from "@infra-ts/runtime";

const database = buildNeonProject({
	projectName: "my-app-db",
	orgId: "org-example",
});

export default defineStack({
	name: "my-app",
	definitions: { database },
	providers: [neonProjectProviderBinding],
	environment: {
		default: "production",
		stage: (name) => (name === "production" ? "production" : "preview"),
	},
	git: { resolve: ({ branch }) => branch },
});

CLI

infra-ts checkout [environment] [--write-env .env.local] [--force] [--json]
infra-ts env [environment] [--stdout | --write .env] [--format dotenv|json] [--force] [--json]
infra-ts run [--environment name] -- <command> ...
infra-ts environment status
infra-ts environment list
infra-ts git install --trust-worktree-code
infra-ts git uninstall
infra-ts git sync
infra-ts git status
infra-ts git prune

Checkout executes resolve → prepare/reconcile → fetch env → activate. It rejects delete plans and partial graph reports and never destroys resources. Env/run/Git sync require non-stale active config and graph fingerprints. Secrets stay in memory by default. env --stdout is mutually exclusive with JSON and is the only command that deliberately prints values. run injects only the process projection with shell: false, repeated signal forwarding, and exact exit mapping.

CLI exits are 0 success, 1 invalid/pre-activation failure, 2 failure after activation completed, and 3 inactive status. JSON modes emit exactly one document.

State is identity-only. Shared provider identity lives under the Git common directory when available, while active checkout metadata is worktree-local. Explicit env materializations are preflighted and staged as one workspace transaction, mode 0600, and guarded by managed hashes so user edits require --force. The initially approved hash is retained through publication; omitted managed files are removed only when unedited, and recovery preserves later edits.

Neon environments

The Neon runtime is hybrid:

• one shared stored project ID per stack definition;
• one stored branch ID/name/ownership per logical environment;
• production stage selects and revalidates the project default branch;
• non-production environments create collision-resistant managed branch names and a read-write endpoint;
• env fetch uses only the stored project and branch identities;
• cleanup can delete only a stored managed, non-default, non-protected branch;
• project deletion exists only as an explicit SDK operation, clears every state address only after confirmed remote deletion, and is never used by checkout or Git prune.

Set NEON_API_KEY or authenticate with the Neon CLI. State never contains connection strings. Branch tuning drift blocks with structured conflicts; in-place branch updates are not implemented. Mutation waits track only operation IDs returned by the initiating API call. Project destroy is stack-reserved and cannot tombstone a concurrent replacement.

Development

bun install --frozen-lockfile
bun run fmt:check
bun run lint
bun run typecheck
bun run build
bun test
bun run docs:build
git diff --check

Two Neon E2Es are gated and intentionally excluded from the default run: direct hybrid provider lifecycle, and the repo-native separate-process CLI path covering checkout/env/run/noop/hooks/materialization and guarded cleanup.

License

Apache License 2.0