oss-bootstrap

Bootstrap, verify, audit, and sync open-source JavaScript/TypeScript repositories.

oss-bootstrap is a repo lifecycle tool. It does more than generate files once: it helps you create a clean starter, check whether the repo works, detect drift, and sync template-backed standards over time.

Why

Most generators stop after scaffolding.

oss-bootstrap is built around this loop:

init -> verify -> audit -> sync

That gives you one tool for:

• starting a new OSS library
• standardizing an existing repo
• detecting missing standards
• keeping multiple repos aligned over time

MVP scope

v1 supports one robust starter path:

• starter-lib-ts

It includes:

• TypeScript library starter files
• community health documents
• CI and release workflow templates
• repo-local AGENTS.md
• lifecycle commands: init, verify, audit, sync

Install

Run locally from this repo:

node src/cli.js --help

Or from the workspace root:

npm run oss:bootstrap -- --help

Release Readiness

v0.1.0 means one starter path is stable enough to use end to end:

• init can scaffold a repo from starter-lib-ts
• audit reports required repo standards correctly
• sync can detect and repair managed-file drift
• verify can pass after dependencies are installed in the generated repo

Before tagging a release in this repo, run:

npm run check

That command lint-checks this CLI code and runs a generated-repo smoke test for the full lifecycle loop.

Usage

Initialize a new repo

node src/cli.js init \
  --target ../demo-lib \
  --name demo-lib \
  --description "A demo OSS library" \
  --github-user Hazel-Lin \
  --author-name "Hazel Lin" \
  --author-email "hazel@example.com"

Verify a repo

node src/cli.js verify --target ../demo-lib

Audit an existing repo

node src/cli.js audit --target ../demo-lib

Sync standards into an existing repo

node src/cli.js sync --target ../demo-lib --dry-run

Command summary

• init: scaffold a new repo from starter-lib-ts
• verify: run required checks and core scripts, then return PASS or FAIL
• audit: inspect a repo for missing standards and drift
• sync: write template-backed standard files back into an existing repo

Output contract

Lifecycle commands should always give you:

• a clear status
• a short summary
• actionable next steps when incomplete
• JSON output when requested

v1 guardrails

• one strong starter beats many partial ones
• sync only manages template-owned standard files
• user product code stays out of scope
• publishing remains manual

Versioning

This project stays in manual 0.x versioning for v1:

• 0.1.x for fixes, doc improvements, and tighter validation without changing the core workflow
• 0.2.0 and later when a new stable capability or starter is added
• 1.0.0 only after the lifecycle contract is stable enough for long-term external use

Docs

• init behavior
• audit behavior
• verify behavior
• sync behavior

Next

• richer drift rules
• starter-specific audit packs
• config file support
• additional starter types after the lifecycle loop is solid