feat: bec CLI — agent-first repo tooling, LMS-aligned schemas#4547
Draft
Asi0Flammeus wants to merge 7 commits into
Draft
feat: bec CLI — agent-first repo tooling, LMS-aligned schemas#4547Asi0Flammeus wants to merge 7 commits into
Asi0Flammeus wants to merge 7 commits into
Conversation
…t commands Python package at scripts/bec (click + jsonschema + pyyaml), installed via pip install -e. Content registry at content-types.yml (14 content types, categories, discipline codes, tags, languages). Canonical JSON schemas at scripts/bec/src/bec/schemas with root schemas/ symlink. 405 tests.
Agent-first repo orientation: content types, bec command reference, conventions (course IDs, BIP39 chapter IDs, image rules), validation workflow. bec agent-setup symlinks them to repo root.
- scripts/validation-format, proofreading-metadata, proofreading_report, course_report, video_deployment_overview, one-off scripts → to_delete/ - docs/PBN-template-repo removed (bec new scaffolds replace templates) - docs/50-planb-tags.md absorbed into schemas/tags-definitions.json - plans/bec-cli.md: implementation plan
LMS (bitcoin-learning-management-system) is the source of truth for content format — precedence: importer parsers > Zod schemas > Drizzle tables. ~110 verified edits from an 8-group adversarially-verified audit: relax required fields the importer treats as optional, open the tag vocabulary (importer lowercases and upserts any string), generic-UUID patterns instead of v4-strict, nullable unions matching nullable columns, add importer-consumed fields BEC never documented (course assignments/pricing, tutorial last_update_date, professor links/tips, conference id/original_language/proofreading), flatten word-content-scheme to the layout every other content schema uses. tags-definitions.json stays as the documented vocabulary.
- validate: malformed YAML no longer crashes the run; schema-aware null handling (no false warnings on nullable fields); content files validated with real jsonschema instead of a shallow field loop; missing metadata file is an error; per-file paths in --all output - add: chapter/part IDs are uuid4 (LMS uuidValidates them — BIP39 wordlist removed); quiz question.yml writes its id; lang and chapter-id validated; CRLF-safe markdown append; regional language codes (zh-Hans, sr-Latn, nb-NO) recognized - new: interactive enum prompts match case-insensitively (license was impossible to enter); valid placeholder webp; book scaffold writes required id; enums loaded from schemas instead of hardcoded copies - proofread: language-factor lookup case-consistency; project.yml reachable (stale builder.yml removed); no literal 'None' in YAML; tests no longer mutate real repo content - report: course analytics splits parts correctly; chapterId/partId values excluded from word counts; null video providers guarded - packaging: jsonschema>=4.18 + referencing declared; schemas shipped in package-data; bec report without subcommand shows help, exits 2 Tests: 444 passed (was 405). Full-repo validation: 2547/2677 pass (was 645), remaining 87 errors are genuine content defects.
The LMS importer computes Math.round(p.reward * 100) unguarded — a missing reward crashes the sync insert, same as course/tutorial.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
bec— a Python CLI (scripts/bec/, click + jsonschema) replacing the scattered validation/report/proofreading scripts with one tool:bec validate [path|--all]— full-repo validation in ~40s,--json, exit codes 0/1/2bec new course|tutorial|professor|event|resource— scaffolds that pass validation (all 10 resource types)bec add part|chapter|quiz|language— UUID part/chapter IDs, quiz numbering, language-file skeletonsbec proofread update|reward|batch-add|status— proofreading metadata + reward calculationbec report translation|images|video|proofreading|analytics [--all]— the 5 HTML/JSON reportsbec agent-setup— symlinks AGENTS.md / CLAUDE.md to repo rootSuperseded scripts moved to
to_delete/(validation-format, proofreading-metadata, proofreading_report, course_report, video_deployment_overview);docs/PBN-template-repo/removed (scaffolds replace it). Canonical schemas now live inscripts/bec/src/bec/schemas/(rootschemas/symlink kept).Schema alignment — LMS is the source of truth
All 24 JSON schemas were audited against what the LMS sync actually consumes (importer parsers > Zod > Drizzle,
bitcoin-learning-management-system@9fc35b345) by an 8-group multi-agent audit with adversarial verification of every edit (~110 edits applied).Full evidence-per-edit report: https://static.crqpt.com/bec-alignment-report.html · summary in
docs/reports/bec-lms-alignment-2026-06.mdValidation impact on the 2,677 current content items:
Notable: chapter/part IDs are generated as UUIDs (the LMS
uuidValidates them; the originally planned BIP39 word-IDs would have broken sync), quizquestion.ymlnow writes itsid(LMS primary key), and the glossary content schema was flattened — it previously false-failed every glossary markdown file.Code review
44 adversarially-confirmed findings fixed (crash-on-malformed-YAML, schema-aware null handling, case-insensitive enum prompts, valid placeholder webp, proofreading reward case bug, analytics part-collapsing, packaging deps). 444 tests pass.
Follow-ups (documented in the report, out of scope here)
.ymlfiles (traversal gap)assignment.ymlcourses/dev301testnet_only→test_onlytypo