oss-launch-lint

Find the launch gaps that make people leave your GitHub repo in the first 20 seconds.

oss-launch-lint is a tiny CLI for maintainers, indie developers, students, and AI-assisted builders who have working code but want the repository to feel ready before sharing it.

Why it is useful

Many useful repos lose visitors because the README, install path, license, CI status, or contribution path is unclear. This tool checks the boring-but-important launch details, generates concrete next actions, suggests GitHub topics, and can scaffold missing community files without overwriting your work.

What you get

Score: 72/100

Fail:
- No LICENSE file
- No issue templates
- README missing install instructions

Warn:
- CI exists but does not run tests
- package.json missing useful keywords

Next actions:
1. Add LICENSE
2. Add .github/ISSUE_TEMPLATE/bug_report.md
3. Add a copy-paste quickstart command

Installation

Run without installing:

npx oss-launch-lint@latest .

Or install globally:

npm install -g oss-launch-lint
oss-launch-lint .

From a source checkout:

git clone https://github.com/sjh9714/oss-launch-lint.git
cd oss-launch-lint
npm install
npm run build
node bin/oss-launch-lint --help

Quickstart

Audit the current repository and write launch assets:

npx oss-launch-lint@latest . --output launch-report.md --promotion-output promotion-copy.md

Print JSON for automation:

npx oss-launch-lint@latest . --json --no-promotion

Preview missing launch-readiness files without writing anything:

npx oss-launch-lint@latest . --fix --dry-run --no-promotion

Create missing scaffold files after confirmation:

npx oss-launch-lint@latest . --fix --no-promotion

Use in CI-style checks:

npx oss-launch-lint@latest . --fail-under 80 --github-step-summary --no-promotion

Try the included demo fixture:

node bin/oss-launch-lint tests/fixtures/demo-repo --output tmp/demo-report.md --promotion-output tmp/demo-promotion.md

Example output

Terminal summary:

Launch report written to launch-report.md
Promotion copy written to promotion-copy.md
Score: 95/100 (9 pass, 1 warn, 0 fail)

Generated report excerpt:

# Launch Readiness Report

## Score: 95/100

Pass: 9 | Warn: 1 | Fail: 0

## Suggested GitHub topics

open-source, github, developer-tools, cli, typescript, nodejs

--fix reports show the improvement after scaffolding:

## Fix summary

Score before fix: 5/100
Score after fix: 58/100
Scaffold: 7 written, 0 skipped

What it checks

• README presence and launch-critical section headings
• License, contributing guide, code of conduct, security policy, and changelog
• GitHub Actions workflow with meaningful run: verification commands
• Issue templates
• Package metadata and test script
• Topic suggestions from files, README text, and package keywords
• Release checklist and ethical launch note

Scores are weighted so launch-critical gaps, such as a missing README, license, CI, or test command, count more than nice-to-have launch polish.

Safe scaffolding

--fix can scaffold practical launch-readiness files:

• CONTRIBUTING.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/workflows/oss-launch-lint.yml

Safety rules:

• --fix --dry-run prints what would be created and writes nothing.
• --fix asks for confirmation before writing.
• --fix --yes skips the prompt for automation.
• Existing files are never overwritten unless --force is explicitly provided.

The workflow scaffold uses npx oss-launch-lint@latest so other repositories can add a launch-readiness gate without cloning this source repository.

GitHub Actions

oss-launch-lint can act as a launch-readiness quality gate:

npx oss-launch-lint@latest . --fail-under 80 --github-step-summary --no-promotion

See docs/github-actions.md for a copy-paste GitHub Actions workflow.

CLI options

oss-launch-lint [repoPath] [options]

Options:
  --output <file>             Markdown report path (default: launch-report.md)
                              Use - to print the Markdown report to stdout
  --promotion-output <file>   Promotion copy path (default: promotion-copy.md)
  --json                      Print documented JSON to stdout
  --no-promotion              Do not write promotion-copy.md
  --fix                       Scaffold missing launch-readiness files
  --dry-run                   With --fix, preview scaffold actions without writing files
  --yes                       With --fix, skip the interactive confirmation prompt
  --force                     With --fix, overwrite scaffold targets that already exist
  --fail-under <score>        Exit non-zero if the readiness score is below score
  --github-step-summary       Append the Markdown report to $GITHUB_STEP_SUMMARY
  --version, -v               Print version
  --help, -h                  Show help

JSON shape

{
  score: number;
  summary: { pass: number; warn: number; fail: number };
  checks: Array<{
    id: string;
    title: string;
    status: "pass" | "warn" | "fail";
    message: string;
    recommendation?: string;
  }>;
  topics: string[];
  nextActions: string[];
}

Demo and screenshots

For a quick text demo, run the fixture command above and open tmp/demo-report.md. The --fix example above shows the current before/after flow that should become the visual demo. For a visual demo, record the same commands with your terminal recorder of choice and show the generated report scrolling below the command output.

Development

npm install
npm test
npm run lint
npm run build
npm run format:check

Roadmap

• Expand --fix with language-specific templates.
• Add more language-specific package metadata checks.
• Add a terminal GIF or screenshot asset for the README.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md, run the verification commands above, and keep promotion-related features ethical and non-spammy.

Support

Open a GitHub issue with the repo type you audited, the command you ran, and the confusing output. Please do not share secrets, private tokens, or unreleased security details in public issues.

Maintained by @sjh9714.

License

MIT. See LICENSE.