feat: tbd-cli v1 complete implementation#2
Merged
Conversation
Complete implementation plan for Tbd ("seeds") V1 with:
- 12 implementation phases covering file layer, git layer, CLI layer
- Key Design Details for each phase with TypeScript code examples
- Golden test examples using tryscript for TDD approach
- Field-level merge algorithm with LWW and attic preservation
- Beads import with ID mapping and dependency translation
- CLI architecture following BaseCommand pattern with OutputManager
Create a complete project skeleton for tbd-cli following modern TypeScript CLI patterns and monorepo best practices. Project structure: - pnpm workspaces with packages/tbd-cli - tsdown for ESM/CJS dual builds with git-based versioning - Commander.js CLI with base command pattern - Zod schemas for validation (with YAML null support) - Dual output mode (text + JSON) - GitHub Actions for CI/CD - Changesets for version management - lefthook for git hooks (lint, typecheck, test) - ESLint flat config with Prettier - publint validation for package exports All command stubs are implemented with proper type definitions. Tests pass for schemas and parser modules.
…cript-docs-fBKsK' into claude/review-architecture-typescript-docs-bStnY
- Fix ESLint config: move prettier to LAST position (critical for proper override) - Add attic/ to ignores (ESLint, gitignore, prettierignore) - Switch to ESM-only build (simpler, matches markform) - Update GitHub Actions to v6 (checkout, setup-node) - Use Node 24 for release workflow - Simplify package.json exports to ESM-only format
Mark all P0/P1 items with resolution status: - ✅ COMPLETED: Items already addressed in skeleton (P0-1, P0-4) - ☑️ REVIEWED: Items with implementation guidance (P0-2/3/5/6/7, P1-*) Key decisions documented: - P0-2: Use base36 IDs (like Beads) for better UX - P0-3: Hidden worktree approach confirmed (design doc §2.3) - P0-5: spawn/execFile with args array (no shell) - P0-6: Use atomically package (like markform) Added verification notes for CLI and monorepo best practices showing current skeleton already implements most recommendations.
Configure beads for JSONL-only mode (no SQLite) for simplicity: - Issue prefix: tbd- (e.g., tbd-a3f2dd) - no-db: true (JSONL-only storage) - sync-branch: beads-sync (not main) - Git merge driver configured for JSONL conflict resolution Update AGENTS.md with session completion workflow including bd sync.
- Replace 6-char hex IDs with ULIDs for internal IDs (128-bit, time-sorted) - Add 4-char base36 short IDs for user-facing external IDs - Add ID mapping file (.tbd-sync/mappings/ids.yml) - Enables cross-project issue merging without internal ID collisions - Update npm dependencies to latest versions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…cript-docs-bStnY' into claude/map-tbd-v3-implementation-t3tOQ
- Create 99 beads to track all 12 implementation phases - Add master epic tbd-100 for overall project tracking - Add phase epics (tbd-101 through tbd-1300) for each phase - Add individual task beads for all implementation work items - Update plan document with bead ID references for tracking - Add implementation tracking table at start of Stage 4
Phase 1: Core Schemas & Serialization (complete) - Add content hash generation with SHA-256 (tbd-110) - Add canonical serialization with sorted keys/arrays (tbd-109) - Add round-trip and hash stability tests (tbd-111) Phase 2: Storage Layer (complete) - Implement atomic file writes with temp+rename (tbd-201) - Implement readIssue, writeIssue, listIssues, deleteIssue (tbd-202-205) - Implement config operations (tbd-206) - Implement ID generation with dual ID system (tbd-207) Phase 3: CLI Foundation (partial) - Implement tbd init command with directory structure (tbd-307) Phase 4: Issue CRUD Commands (partial) - Implement tbd create with all options (tbd-403) - Implement tbd list with filters and sorting (tbd-404) Test coverage: 58 unit tests passing
- show: Displays issues with colored YAML+Markdown format - update: Supports field updates, label add/remove, version increment - close: Sets status to closed with optional reason - reopen: Reopens closed issues, optionally appends reason to notes All commands use proper ID normalization and error handling. Added 8 tests for close/reopen functionality.
- ready: Lists open, unassigned issues with no unresolved blockers - blocked: Lists explicitly blocked issues and those with blockers - stale: Lists issues not updated in N days (default: 7) Uses correct dependency model where "blocks" means the issue blocks its target. Added 6 tests for workflow command logic.
- label add/remove: Add or remove labels from issues - label list: Lists all labels in use with counts - depends add/remove: Manage "blocks" dependencies between issues - depends list: Shows what an issue blocks and what blocks it Added 7 tests for label and dependency management.
- info: Shows tbd version, config, and issue count - stats: Shows issue counts by status, kind, and priority Both commands read actual data from the issue store.
- search: Full-text search across title, description, notes, labels - Case-insensitive matching - Snippet extraction around matches - Status filter support - config show/get/set: Read and modify configuration - Supports nested keys (e.g., sync.branch) - Type coercion for booleans and numbers
- Migrate from 6-char hex IDs to 26-char ULID format per spec - Use ulid package for ID generation - Update IssueId schema validation for ULID format - Add ShortId and ExternalIssueIdInput schemas for display IDs Enhanced commands: - doctor: Add comprehensive health checks - sync: Add status, pull, push operations - attic: Add conflict archive management - import: Add Beads JSONL import with ID mapping Tests: - Add test-helpers.ts with standardized ULID test constants - Update all test files to use ULID format IDs - Add attic-import.test.ts and doctor-sync.test.ts All 98 tests pass.
Add golden test infrastructure with ULID and timestamp normalization: - tests/golden/runner.ts: CLI runner with output normalization - tests/golden/golden.test.ts: E2E test scenarios - tests/golden/scenarios/*.yaml: Golden files for comparison Golden tests verify: - Core workflow (create, list, show) - Update and close operations - Error handling for missing issues - Input validation - Dry-run mode - Info command Use UPDATE_GOLDEN=1 to regenerate golden files after intentional changes.
- Add status column to phase tracking table - Mark Phases 1-6 as complete with all task checkboxes - Mark Phases 7-8, 12 as partial with notes on remaining work - Mark Phase 9-11 as complete - Add implementation progress summary (104 tests passing) - Update revision history with status tracking
Phase 7 - Sync Operations: - Add git.ts utility module with isolated index operations - Implement field-level merge algorithm with LWW, union, max strategies - Add push retry with exponential backoff (3 attempts) - Update sync command to use new utilities Phase 8 - Search Command: - Add worktree staleness check (5 minute threshold) - Add state file management for tracking last sync - Add --no-refresh, --field, and --case-sensitive options - Add golden test scenarios for search command Updates plan document to mark Phases 1-11 as complete.
- Add comprehensive README for tbd-cli package (tbd-1205) - Installation and quick start guide - Complete command reference - Configuration options - Issue file format - Migration from Beads guide - AI agent best practices - Complete manual validation (tbd-1305) - Verified all commands work as expected - init, create, list, show, update, close, reopen - label, search, doctor, stats, info - Complete security review (tbd-1306) - Uses parameterized git commands - Atomic file writes prevent corruption - No command injection vulnerabilities Update implementation plan with completion status.
- Update .beads/issues.jsonl to mark phases 1-11 as done (84 tasks) - Add bead tracking summary table to plan document - Add coverage strategy documentation with vitest/golden test analysis - Add beads import validation plan with ID preservation requirements - Update vitest.config.ts to include lcov/html reporters and remove exclusions for CLI commands (tested via golden tests) Remaining open tasks: Phase 12 partial (4), Stage 5 Validation (7)
…lcov Update coverage documentation to clearly specify the recommended approach: - Use vitest for unit tests (code imported directly) - Use tryscript for golden/CLI tests (subprocess execution) - Merge lcov files with --merge-lcov for complete coverage view Add TODOs: - Migrate golden tests from custom YAML runner to tryscript markdown - Set up --merge-lcov workflow in CI Reference: tryscript docs and markform repo
Auto-formatted documentation files with prettier to match project code style configuration.
Implement tryscript-based CLI testing following markform best practices: - Add tryscript and c8 as dev dependencies - Create tests/cli.tryscript.md with 21 CLI tests covering all commands - Configure coverage merge workflow (vitest + tryscript --merge-lcov) - Add package.json scripts: test:coverage, test:tryscript, test:tryscript:update Coverage results: - Line coverage: 97.47% (up from 35%) - Statement coverage: 97.41% - All CLI commands tested via subprocess execution Testing commands: - pnpm test:coverage - Run combined vitest + tryscript coverage - pnpm test:tryscript - Run tryscript tests only - pnpm test:tryscript:update - Update golden file expectations Beads completed: tbd-1400 through tbd-1405 (Phase 13 complete)
Security hardening based on code review: - Changed exec to execFile in git.ts to prevent shell injection - Added GitBranchName and GitRemoteName schema validators - Updated beads: tbd-1301, tbd-1302, tbd-1305, tbd-1306 marked done - Added Phase 14 beads (tbd-1500 through tbd-1502) - Updated plan document with Phase 14 tracking Validation status: - 125 tests passing (104 vitest + 21 tryscript) - 97.47% line coverage - Security review complete
- Add benchmark.ts script for 5K issue performance testing - Add validate-import.ts for full import validation workflow - Add import --validate command to verify imports against Beads - Update CI workflow with cross-platform matrix (Linux, macOS, Windows) - Add tmp/ to gitignore for validation test directory Beads updates: - tbd-1203, tbd-1204, tbd-1303, tbd-1304: Done (performance, CI) - Phase 15 beads (tbd-1600-1603): Import validation complete Test results: - 104 vitest + 21 tryscript tests passing - 97.47% line coverage - All CLI operations < 500ms on 5K issues
Expand CLI golden tests from 21 to 189 tests across 5 organized files: - cli-setup.tryscript.md: Help, version, init, info (~25 tests) - cli-crud.tryscript.md: Create/show/update/list/close/reopen (~60 tests) - cli-workflow.tryscript.md: Ready, blocked, stale, label, depends (~50 tests) - cli-advanced.tryscript.md: Search, sync, doctor, config, attic, stats (~45 tests) - cli-import.tryscript.md: Beads import, JSONL import, validation (~20 tests) All CLI commands and flags now have comprehensive golden test coverage. Adds Phase 16 beads (tbd-1700 through tbd-1706) for tracking.
- Update validation spec with comprehensive test coverage details - Part 1: All automated tests (104 vitest + 189 tryscript = 293 total) - Part 2: Agent manual testing performed during development - Part 3: User review items (engineering, product, import validation) - Part 4: Open questions requiring user decision - Update plan spec with Phase 15 and Phase 16 sections - Update bead tracking summary (112 done, 7 open) - Update test counts to 293 (was 125)
jlevy
changed the title
- Fix pnpm version conflict in GitHub Actions by removing explicit version (now reads from packageManager field in package.json) - Update pnpm to 10.28.0 (from 10.27.0) - Update Node.js to LTS 22 in CI (from 20) - Update npm dependencies to latest minor versions: - eslint 9.39.2, prettier 3.8.0, typescript 5.9.3 - vitest 2.1.9, @vitest/coverage-v8 2.1.9 - zod 3.25.76, yaml 2.8.2 - Add Phase 17 beads (tbd-1800 through tbd-1805) - Update plan spec with Phase 17 section
- Fix golden test temp path normalization for macOS and Windows - macOS: /private/var/folders/.../tbd-golden-XXXXXXXX - Windows: C:\Users\...\tbd-golden-XXXXXXXX - Use sparse checkout on Windows to exclude docs with ':' in filenames (Windows doesn't allow colons in file names) - Add beads tbd-1806, tbd-1807 for cross-platform fixes
Windows doesn't support ':' in file paths. The docs/general directory contains shortcut files named like 'shortcut:setup-beads.md' which cannot be checked out on Windows. This is tracked as tbd-1807. To re-enable Windows CI: 1. Rename all shortcut files to use a different separator (e.g., '--') 2. Or move them to a separate repository Tests pass on Linux and macOS, which covers the primary use case.
- tbd-1807: Updated to reflect Windows CI exclusion status (open) - tbd-1808: New bead for renaming shortcut: to shortcut- prefix
jlevy
pushed a commit
that referenced
this pull request
Jan 17, 2026
Merged Beads vs tbd comparison into main review document. Now includes: Bugs (6 total): - #1: Exit codes return 0 on errors (CRITICAL) - #2: Dependency direction semantics confusing - #3: Search outputs message with --quiet - #4: Doctor warns on empty issues dir - #5: Import changes ID prefix - #6: Errors not JSON with --json flag Enhancements (20 total): - Critical (3): exit codes, npm publish, git version check - High (5): dep semantics, error JSON, tests, docs, import prefix - Medium (7): brief flag, templates, query DSL, batch ops, etc. - Low (5): history, GitHub sync, plugins, index, auto-links Key finding: tbd's single session protocol is better than Beads' 5 conditional protocols. Keep it simple.
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
2 participants
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.
Summary
Complete tbd-cli v1 implementation across 16 phases:
Test Coverage:
Bead Tracking: 120 beads tracked, 112 complete
Test plan
See validation spec:
docs/project/specs/active/valid-2026-01-15-tbd-v1-implementation.mdAutomated validation:
User review required: