https://github.com/sjh9714/oss-launch-lint
Audit whether a GitHub repo is ready for an ethical open-source launch.
https://github.com/sjh9714/oss-launch-lint
cli developer-tools github launch maintainer-tools open-source oss release-checklist typescript
Last synced: 16 days ago
JSON representation
Audit whether a GitHub repo is ready for an ethical open-source launch.
- Host: GitHub
- URL: https://github.com/sjh9714/oss-launch-lint
- Owner: sjh9714
- License: mit
- Created: 2026-05-24T02:31:47.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-24T03:55:48.000Z (about 1 month ago)
- Last Synced: 2026-05-24T04:28:34.711Z (about 1 month ago)
- Topics: cli, developer-tools, github, launch, maintainer-tools, open-source, oss, release-checklist, typescript
- Language: TypeScript
- Homepage: https://github.com/sjh9714/oss-launch-lint
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# oss-launch-lint
[](https://github.com/sjh9714/oss-launch-lint/actions/workflows/ci.yml)
[](LICENSE)
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
```text
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:
```bash
npx oss-launch-lint@latest .
```
Or install globally:
```bash
npm install -g oss-launch-lint
oss-launch-lint .
```
From a source checkout:
```bash
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:
```bash
npx oss-launch-lint@latest . --output launch-report.md --promotion-output promotion-copy.md
```
Print JSON for automation:
```bash
npx oss-launch-lint@latest . --json --no-promotion
```
Preview missing launch-readiness files without writing anything:
```bash
npx oss-launch-lint@latest . --fix --dry-run --no-promotion
```
Create missing scaffold files after confirmation:
```bash
npx oss-launch-lint@latest . --fix --no-promotion
```
Use in CI-style checks:
```bash
npx oss-launch-lint@latest . --fail-under 80 --github-step-summary --no-promotion
```
Try the included demo fixture:
```bash
node bin/oss-launch-lint tests/fixtures/demo-repo --output tmp/demo-report.md --promotion-output tmp/demo-promotion.md
```
## Example output
Terminal summary:
```text
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:
```markdown
# 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:
```text
## 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:
```bash
npx oss-launch-lint@latest . --fail-under 80 --github-step-summary --no-promotion
```
See [docs/github-actions.md](docs/github-actions.md) for a copy-paste GitHub Actions workflow.
## CLI options
```text
oss-launch-lint [repoPath] [options]
Options:
--output Markdown report path (default: launch-report.md)
Use - to print the Markdown report to stdout
--promotion-output 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 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
```ts
{
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
```bash
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](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](https://github.com/sjh9714).
## License
MIT. See [LICENSE](LICENSE).