bansos-add-entry

name	bansos-add-entry
description	Add or review a new bansos.dev listing efficiently. Use when an AI agent needs to research a promo/freebie/program source, convert it into validated bansos.dev data, run or prepare `npx bansosdev add`, create/update a submission issue or PR, or check whether a proposed bansos entry follows wauputr4/bansos contribution rules.

Bansos Add Entry

Goal

Turn a source link or user-provided promo details into one clean bansos.dev entry with clear evidence, contributor attribution, and a valid submission path.

Workflow

1. Read the source page or user-provided evidence before writing copy. If the source is current, browse or otherwise verify the latest terms, dates, pricing, quotas, and eligibility.
2. Extract only fields supported by bansos.dev: id, title, provider, description, benefits, promoCode, validity, requirements, tips, publishedAt, contributor, ctaLink, source, tags, featured, and status.
3. Prefer the public CLI path unless the user explicitly asks for maintainer/direct mode.
4. Validate locally with npx bansosdev add ... --mode json before asking a user to submit, opening an issue, or preparing a PR.
5. If the user asks you to implement directly in the repo, update src/lib/data/bansos.json through the repo script where possible and preserve existing formatting. If the script rewrites unrelated JSON formatting, restore the file and apply a scoped entry-only patch instead.
6. Create a concise PR/issue body that mentions the source link, contributor, validity, and any uncertainty.
7. For an existing GitHub issue submission, check for duplicates, create a branch, add the entry, regenerate src/lib/data/commit-contributors.json, verify locally, open a PR that closes the issue, then follow review feedback until CI is green. If the user asks to finish the flow, merge the PR, thank the issue author, and close or confirm closure of the issue.

Data Rules

• Use kebab-case lowercase IDs, for example tokenrouter-dev-credits.
• Keep benefits and requirements as short lists; split CLI values with |.
• Use comma-separated tags, for example AI,Gratisan,Course.
• Use validity.type as fixed, uncertain, or forever.
• For fixed, include a real calendar date as validity.date in YYYY-MM-DD.
• Use publishedAt in YYYY-MM-DD; reject impossible dates like 2026-02-31.
• Set status to active, expired, or upcoming based on source evidence and current date.
• Always include both contributor.name and contributor.url when contributor metadata is known.
• Use source for evidence links that should render on the detail page. Do not use src.
• Keep claims traceable. If a benefit is community-reported, say so in copy or tips instead of presenting it as guaranteed.

CLI Pattern

Use this shape for public submissions:

npx bansosdev add \
  --id contoh-bansos \
  --title "Contoh Bansos Developer" \
  --provider "Provider" \
  --description "Deskripsi singkat bansos." \
  --benefits "Benefit satu|Benefit dua" \
  --validity-type fixed \
  --validity-date 2026-06-30 \
  --validity-desc "Selama kuota masih ada" \
  --published-at 2026-06-13 \
  --requirements "Buat akun|Klaim program" \
  --cta-link "https://example.com" \
  --source "https://example.com/changelog-or-proof" \
  --contributor-name "Nama Kontributor" \
  --contributor-url "https://example.com" \
  --tags "Cloud,Gratisan" \
  --status active \
  --mode json

After JSON validation, run the same command without --mode json to get the GitHub issue URL.

For maintainers only, use --mode direct with BANSOSDEV_GITHUB_TOKEN when the user has explicitly provided or configured the token.

Maintainer PR Loop

When turning an issue into a PR:

1. Validate the issue JSON and official source before editing.
2. Keep the data diff focused on the new or changed listing.
3. Run node scripts/generate-commit-contributors.mjs after data changes.
4. Run npm run lint, npm run check, and npm run build before opening or merging broad data PRs.
5. Inspect review threads, not only flat comments. Fix unresolved, non-outdated actionable comments.
6. Wait for the latest CI run to finish successfully before merging.
7. Reply to the submission issue with what was changed and link the merged PR.

References

• Read references/bansos-entry-rules.md when you need field-level guidance, PR rules, or example issue/PR wording.