repo-aeo

Audit and improve repository discoverability: GitHub metadata and topics, README structure, AGENTS.md, the npm publish surface, llms.txt and structured data.

Zero runtime dependencies. Node >= 18. Read-only by default.

Install

npm install --save-dev repo-aeo
npx repo-aeo --help

Commands

| Command | What it does | Writes? | | --- | --- | --- | | rdk init | scaffolds .discoverability/project.yml and the minimal safe files | with --apply | | rdk audit | Discoverability Score 0–100 + findings with severity/why/fix/effort | never | | rdk fix | applies only safe, idempotent autofixes | with --apply | | rdk npm-surface | package.json publish surface + npm pack --dry-run hygiene | never | | rdk github-sync | pushes description/homepage/topics to GitHub | with --apply --ack --reason --plan-digest | | rdk channels | lists every distribution channel: mechanism, applicability, recorded status, next action | never | | rdk submit | runs a distribution channel --channel <id> (default awesome-list): previews, then submits and records it under the guard | with --apply --ack --reason --plan-digest | | rdk track | campaign dashboard over .discoverability/submissions.json: live status (--json), adopt pre-ledger rdk/* PRs (--adopt), sync recorded statuses from live probes (--sync) | --adopt/--sync with --apply --ack --reason --plan-digest | | rdk skill install | links the agent skill into OpenCode/Claude/Codex skill dirs (uninstall, status, --project) | with the subcommand |

Output formats

npx repo-aeo audit --format json             # machine readable (stdout is pure JSON)
npx repo-aeo audit --format markdown         # full human report
npx repo-aeo audit --format github-comment   # compact PR comment (marker: <!-- rdk-discoverability-audit -->)
npx repo-aeo audit --out report.md           # also write to a file

Safety model

• audit is read-only and offline by default; --online adds link checks and GitHub API reads.
• fix/init are dry-run by default and write only with --apply.
• github-sync requires --apply --ack <ACK> --reason "<why>" --plan-digest <DIGEST> (the digest of the dry-run preview, so the write binds to the approved plan).
• channels is read-only and needs neither gh nor a network.
• submit previews the whole channel campaign offline; executing a channel additionally requires the same guard chain (gh for git-pr) and records every submission in .discoverability/submissions.json.
• Listings-only: nothing in this package publishes, tags, releases or force-pushes; web-form and publish channels are prepared and handed to a human or CI to complete.

Programmatic use

import { audit, planPatches, renderGithubComment } from 'repo-aeo';

const report = await audit(process.cwd(), { online: false });
console.log(report.score.total, report.findings.length);
console.log(renderGithubComment(report));

Development

npm test        # node --test
node bin/rdk.js audit --online