oss-maintainer-kit

A small CLI for open-source maintainers who want to check repository readiness and generate a starter Codex for Open Source application draft.

Quick Start: GitHub Action

Add this workflow to another repository:

name: OSS readiness

on:
  pull_request:
  push:

jobs:
  readiness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ritsuki36/oss-maintainer-kit@v0.3.0
        with:
          min-score: "80"

The action fails when the repository score is below the configured minimum.

Why this exists

Open-source maintainers often need to explain the value of their projects, keep maintenance files healthy, and prepare concise application text for support programs. oss-maintainer-kit keeps that work lightweight:

• checks basic OSS repository readiness
• highlights missing maintainer-facing files
• generates a starter Codex for Open Source application draft you can edit for the 500-character form fields
• works locally without API keys or external dependencies

Who this is for

• maintainers preparing for Codex for Open Source
• developers publishing a new OSS repository
• contributors checking whether a project has basic maintainer files
• people who want a simple repo health checklist before asking for feedback

Install

Clone the repository and run the CLI with Node.js 20 or newer:

git clone https://github.com/ritsuki36/oss-maintainer-kit.git
cd oss-maintainer-kit
npm run check -- .

Example output:

OSS maintainer readiness: oss-maintainer-kit
Score: 100/100

OK      README - Explains what the project does and how to use it.
OK      LICENSE - Makes reuse terms clear.
OK      CONTRIBUTING - Shows contributors how to open issues and pull requests.
OK      SECURITY - Gives reporters a safe path for vulnerabilities.
OK      CODE_OF_CONDUCT - Sets community expectations.
OK      package metadata - Helps users and tools identify the project.
OK      GitHub Actions - Runs repeatable checks for contributors and maintainers.

You can also run the source file directly:

node src/index.mjs check /path/to/repo

Usage

Check a repository:

node bin/oss-maintainer-kit.mjs check .

Output JSON for scripts or CI:

node bin/oss-maintainer-kit.mjs check . --format json

Require a minimum score and return a failing exit code when the repository is below it:

node bin/oss-maintainer-kit.mjs check . --min-score 80

Generate a Codex for Open Source application draft:

node bin/oss-maintainer-kit.mjs application . --repo https://github.com/owner/repo --role "core maintainer"

Save the draft to a file:

node bin/oss-maintainer-kit.mjs application . --repo https://github.com/owner/repo --role "core maintainer" --output draft.md

Print the static application template:

node bin/oss-maintainer-kit.mjs template

Examples

• examples/check-output.txt
• examples/application-draft.md

Use in CI

The reusable GitHub Action is the recommended way to keep basic maintainer files visible during pull requests.

name: OSS readiness

on:
  pull_request:
  push:

jobs:
  readiness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ritsuki36/oss-maintainer-kit@v0.3.0
        with:
          path: "."
          min-score: "80"
          format: json

Action inputs:

• path: repository path to check, defaults to .
• min-score: minimum passing score, defaults to 80
• format: text or json, defaults to text

Commands

check [path]

Scores a local repository against simple maintainer-readiness signals:

• README
• LICENSE
• CONTRIBUTING guide
• SECURITY policy
• CODE_OF_CONDUCT
• GitHub Actions workflows
• package metadata

Options:

• --format text|json: print human-readable output or structured JSON
• --min-score <0-100>: exit with code 1 when the repository score is below the threshold

application [path]

Creates a short, editable application draft using local repository signals. It does not submit anything and does not call OpenAI or GitHub APIs.

Options:

• --repo <url>: repository URL to include in the draft
• --role <text>: your maintainer role
• --org-id <id>: optional OpenAI organization ID placeholder
• --output <file> or -o <file>: save the generated draft instead of printing it

template

Prints templates/codex-for-oss-application.md.

Japanese note

Codex for Open Source 申請用に、OSSリポジトリの基本的な整備状況を確認し、申請文のたたき台を作るための小さなツールです。スター数が少ないプロジェクトでも、役割・利用価値・保守実績を説明しやすくすることを目的にしています。

License

MIT