feat(voyage)!: marketplace handoff — rename plugins/ultraplan-local to plugins/voyage [skip-docs]
Session 5 of voyage-rebrand (V6). Operator-authorized cross-plugin scope. - git mv plugins/ultraplan-local plugins/voyage (rename detected, history preserved) - .claude-plugin/marketplace.json: voyage entry replaces ultraplan-local - CLAUDE.md: voyage row in plugin list, voyage in design-system consumer list - README.md: bulk rename ultra*-local commands -> trek* commands; ultraplan-local refs -> voyage; type discriminators (type: trekbrief/trekreview); session-title pattern (voyage:<command>:<slug>); v4.0.0 release-note paragraph - plugins/voyage/.claude-plugin/plugin.json: homepage/repository URLs point to monorepo voyage path - plugins/voyage/verify.sh: drop URL whitelist exception (no longer needed) Closes voyage-rebrand. bash plugins/voyage/verify.sh PASS 7/7. npm test 361/361.
This commit is contained in:
parent
8f1bf9b7b4
commit
7a90d348ad
149 changed files with 26 additions and 33 deletions
56
plugins/voyage/examples/01-add-verbose-flag/REGENERATED.md
Normal file
56
plugins/voyage/examples/01-add-verbose-flag/REGENERATED.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
# Regeneration log — 01-add-verbose-flag
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Last regenerated | 2026-05-01 |
|
||||
| trekplan version | 3.1.0 |
|
||||
| Claude Code version | ≥ 2.1.105 (PreCompact-hook) |
|
||||
| Source brief author | Hand-calibrated example, not LLM-generated |
|
||||
| Plan author | Hand-calibrated to demonstrate plan_version 1.7 schema + manifest YAML |
|
||||
|
||||
## What this is
|
||||
|
||||
A complete walk-through of the four-stage pipeline for one realistic
|
||||
small task: adding a `--verbose` flag to a hypothetical `small-auth`
|
||||
CLI parser. Every artifact is hand-calibrated, not LLM-generated, so
|
||||
fork-ers can study the *shape* without worrying about whether an
|
||||
LLM hallucinated something.
|
||||
|
||||
## What "regenerate" means
|
||||
|
||||
If the artifact format changes (frontmatter schema, manifest YAML
|
||||
keys, progress.json version), this example needs to be re-built so
|
||||
fork-ers don't learn an obsolete shape.
|
||||
|
||||
Triggers for regeneration:
|
||||
|
||||
- `plan_version` bumps
|
||||
- Frontmatter schema additions to `brief.md` or `research/*.md`
|
||||
- New required keys in manifest YAML
|
||||
- `progress.json` schema bump beyond `schema_version: "1"`
|
||||
|
||||
When regenerating: do **not** run an actual LLM-driven pipeline against
|
||||
this brief. Hand-calibrate against the new schema so the example stays
|
||||
deterministic and reviewable.
|
||||
|
||||
## Project assumed
|
||||
|
||||
A fictional `small-auth` CLI with this layout:
|
||||
|
||||
```
|
||||
small-auth/
|
||||
├── package.json
|
||||
├── src/
|
||||
│ ├── cli.mjs # 80-line argv parser (hand-rolled)
|
||||
│ └── commands/
|
||||
│ ├── login.mjs
|
||||
│ ├── logout.mjs
|
||||
│ ├── whoami.mjs
|
||||
│ ├── token-refresh.mjs
|
||||
│ ├── users-list.mjs
|
||||
│ └── users-create.mjs
|
||||
└── tests/ # 24 tests, node:test
|
||||
```
|
||||
|
||||
This project is **not** in the plugin repo. The example artifacts
|
||||
reference it as if it were the cwd of an `/trekexecute` run.
|
||||
55
plugins/voyage/examples/01-add-verbose-flag/brief.md
Normal file
55
plugins/voyage/examples/01-add-verbose-flag/brief.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
type: trekbrief
|
||||
brief_version: 1.0
|
||||
slug: add-verbose-flag
|
||||
task: Add a --verbose flag to the small-auth CLI parser
|
||||
research_topics: 1
|
||||
research_status: complete
|
||||
brief_quality: ready
|
||||
created: 2026-05-01
|
||||
---
|
||||
|
||||
# Add `--verbose` flag to small-auth CLI
|
||||
|
||||
## Intent
|
||||
|
||||
The `small-auth` CLI parser has six commands (`login`, `logout`, `whoami`,
|
||||
`token-refresh`, `users-list`, `users-create`) and currently emits only
|
||||
final results — no progress, no timings, no internal step trace. Operators
|
||||
debugging slow `token-refresh` calls or mis-routed `users-list` queries
|
||||
have no signal between "started" and "finished".
|
||||
|
||||
We want a `--verbose` flag that, when passed, prints structured progress
|
||||
lines to stderr without changing stdout output. Stdout stays the
|
||||
machine-parseable contract; stderr becomes the human-readable trace.
|
||||
|
||||
## Goal
|
||||
|
||||
Add a single `--verbose` boolean flag, recognized by all six commands,
|
||||
that emits one stderr line per internal step. No other behavioral
|
||||
changes. The default (`--verbose` absent) produces output byte-identical
|
||||
to today's CLI.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- `small-auth login --verbose alice` exits 0 and writes ≥ 3 stderr lines
|
||||
prefixed `[verbose]` covering: argument parse, credential lookup,
|
||||
session-token issue.
|
||||
- `small-auth login alice` (no flag) writes exactly the same stdout as
|
||||
before this change — verified by golden-file diff against
|
||||
`tests/golden/login.stdout`.
|
||||
- `--verbose` works in any position: `small-auth --verbose login alice`,
|
||||
`small-auth login --verbose alice`, `small-auth login alice --verbose`.
|
||||
- `--verbose` short form is `-v`. `-vv` is **not** recognized — only one
|
||||
level. Document this in `--help`.
|
||||
- All six commands accept the flag without rejection. Commands that have
|
||||
no internal steps to trace (`whoami`) still accept the flag silently.
|
||||
- Existing 24 tests in `tests/` continue to pass. Two new tests added:
|
||||
one stdout-stability test, one stderr-content test for `login`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Log levels beyond on/off (no `--debug`, `--trace`).
|
||||
- Structured JSON logging — stderr stays plain text in this iteration.
|
||||
- Logging configuration via env vars or config file.
|
||||
- Any command other than the six listed.
|
||||
251
plugins/voyage/examples/01-add-verbose-flag/plan.md
Normal file
251
plugins/voyage/examples/01-add-verbose-flag/plan.md
Normal file
|
|
@ -0,0 +1,251 @@
|
|||
# Add `--verbose` flag to small-auth CLI
|
||||
|
||||
plan_version: 1.7
|
||||
|
||||
> **Plan quality: A** (92/100) — APPROVE
|
||||
>
|
||||
> Generated by trekplan v3.1.0 on 2026-05-01.
|
||||
|
||||
## Context
|
||||
|
||||
The `small-auth` CLI has six commands and emits only final results; no
|
||||
progress, no internal step trace. Operators debugging slow `token-refresh`
|
||||
or mis-routed `users-list` calls have no signal between "started" and
|
||||
"finished". This plan adds a `--verbose` / `-v` flag that, when set,
|
||||
emits structured progress lines to stderr without changing stdout. The
|
||||
default path stays byte-identical.
|
||||
|
||||
This is a textbook minimal-scope addition: the parser is small,
|
||||
centralized, and already supports global flags.
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Changes in this plan"
|
||||
cli["src/cli.mjs<br/>parse globalFlags"]
|
||||
ctx["ctx object<br/>+ verbose: boolean"]
|
||||
login["src/commands/login.mjs<br/>+ 3 verbose calls"]
|
||||
token["src/commands/token-refresh.mjs<br/>+ 4 verbose calls"]
|
||||
userlist["src/commands/users-list.mjs<br/>+ 2 verbose calls"]
|
||||
usercreate["src/commands/users-create.mjs<br/>+ 3 verbose calls"]
|
||||
logout["src/commands/logout.mjs<br/>+ 2 verbose calls"]
|
||||
whoami["src/commands/whoami.mjs<br/>(accepts flag, no traces)"]
|
||||
help["src/cli.mjs<br/>--help text"]
|
||||
tests["tests/cli-verbose-flag.test.mjs<br/>tests/cli-no-verbose-stability.test.mjs"]
|
||||
|
||||
cli --> ctx
|
||||
ctx --> login
|
||||
ctx --> token
|
||||
ctx --> userlist
|
||||
ctx --> usercreate
|
||||
ctx --> logout
|
||||
ctx --> whoami
|
||||
cli --> help
|
||||
login --> tests
|
||||
end
|
||||
```
|
||||
|
||||
## Codebase Analysis
|
||||
|
||||
- **Tech stack:** Node.js ≥ 18, no external runtime dependencies, `node:test` for tests
|
||||
- **Key patterns:** hand-rolled argv parser, two-pass extract (globals → command), handler contract `run(positional, flags, ctx)`
|
||||
- **Relevant files:** `src/cli.mjs`, `src/commands/{login,logout,whoami,token-refresh,users-list,users-create}.mjs`, `tests/`
|
||||
- **Reusable code:** existing `[error]` stderr pattern at `src/cli.mjs:67` — mirror it for `[verbose]`
|
||||
- **External tech:** none
|
||||
- **Recent git activity:** parser last changed in commit `ab1c2d3` (added `--version`); pattern still current
|
||||
|
||||
## Research Sources
|
||||
|
||||
*Internal research only — see `research/01-cli-parser-conventions.md`.*
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
Each step targets 1–2 files and one focused change. TDD structure: test
|
||||
or stability harness comes before behavior change.
|
||||
|
||||
### Step 1: Capture golden stdout for stability test
|
||||
|
||||
- **Files:** `tests/golden/login.stdout` (new file), `tests/golden/whoami.stdout` (new file), `tests/golden/users-list.stdout` (new file)
|
||||
- **Changes:** Run current CLI for three representative commands, save stdout byte-for-byte. Use `node src/cli.mjs login alice > tests/golden/login.stdout` and similar.
|
||||
- **Verify:** `wc -c tests/golden/*.stdout` → expected: each file > 0 bytes
|
||||
- **Checkpoint:** `git commit -m "test(small-auth): capture pre-change golden stdout for verbose-flag stability"`
|
||||
- **On failure:** revert files; do not proceed. Likely cause: CLI itself broken — investigate before continuing.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- tests/golden/login.stdout
|
||||
- tests/golden/whoami.stdout
|
||||
- tests/golden/users-list.stdout
|
||||
min_file_count: 3
|
||||
commit_message_pattern: "^test\\(small-auth\\): capture"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain: []
|
||||
```
|
||||
|
||||
### Step 2: Add stability test (must FAIL initially — verbose not yet wired)
|
||||
|
||||
- **Files:** `tests/cli-no-verbose-stability.test.mjs` (new file)
|
||||
- **Changes:** Three subtests, one per golden file. Each runs `node src/cli.mjs <cmd> ...` and asserts stdout `===` `readFileSync('tests/golden/<cmd>.stdout')`. The test should PASS today (no behavior change yet) — it's the canary for step 5 onwards.
|
||||
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass
|
||||
- **Checkpoint:** `git commit -m "test(small-auth): stdout stability harness for verbose-flag work"`
|
||||
- **On failure:** if subtests fail, the goldens are wrong — re-run step 1.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- tests/cli-no-verbose-stability.test.mjs
|
||||
min_file_count: 1
|
||||
commit_message_pattern: "^test\\(small-auth\\): stdout stability"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: tests/cli-no-verbose-stability.test.mjs
|
||||
pattern: "tests/golden/login\\.stdout"
|
||||
```
|
||||
|
||||
### Step 3: Extend parser to recognize `--verbose` and `-v`
|
||||
|
||||
- **Files:** `src/cli.mjs`
|
||||
- **Changes:** At `src/cli.mjs:34` (alias table) add `'-v': '--verbose'`. At `src/cli.mjs:48` (globalFlags loop) add `'--verbose'` case that sets `globalFlags.verbose = true`. Default the field to `false`. The flag is consumed (removed from argv) like `--help` and `--version`.
|
||||
- **Verify:** `node src/cli.mjs --verbose login alice 2>&1 | head -1` → expected: no parse error
|
||||
- **Checkpoint:** `git commit -m "feat(cli): recognize --verbose / -v as global flag"`
|
||||
- **On failure:** revert `src/cli.mjs`; rerun stability test to confirm clean baseline.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- src/cli.mjs
|
||||
min_file_count: 1
|
||||
commit_message_pattern: "^feat\\(cli\\): recognize --verbose"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: src/cli.mjs
|
||||
pattern: "globalFlags\\.verbose"
|
||||
```
|
||||
|
||||
### Step 4: Pass `verbose` into handler `ctx`
|
||||
|
||||
- **Files:** `src/cli.mjs`
|
||||
- **Changes:** At `src/cli.mjs:62` (ctx construction) add `verbose: globalFlags.verbose` to the ctx literal. No handler changes yet.
|
||||
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (handlers ignore the new field for now)
|
||||
- **Checkpoint:** `git commit -m "feat(cli): thread verbose into command handler ctx"`
|
||||
- **On failure:** stability tests fail → ctx mutation broke something. Bisect by reverting and adding back one line at a time.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- src/cli.mjs
|
||||
min_file_count: 1
|
||||
commit_message_pattern: "^feat\\(cli\\): thread verbose"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: src/cli.mjs
|
||||
pattern: "verbose: globalFlags\\.verbose"
|
||||
```
|
||||
|
||||
### Step 5: Wire verbose output in `login`, `token-refresh`, `users-list`, `users-create`, `logout`
|
||||
|
||||
- **Files:** `src/commands/login.mjs`, `src/commands/token-refresh.mjs`, `src/commands/users-list.mjs`, `src/commands/users-create.mjs`, `src/commands/logout.mjs`
|
||||
- **Changes:** At each internal step (3 for login, 4 for token-refresh, 2 for users-list, 3 for users-create, 2 for logout — 14 call sites total), add `if (ctx.verbose) ctx.stderr.write(\`[verbose] <step description>\\n\`);`. Step descriptions per file:
|
||||
- login: "parsing argv", "credential lookup", "issuing session token"
|
||||
- token-refresh: "parsing argv", "validating refresh token", "rotating session token", "persisting new token"
|
||||
- users-list: "parsing argv", "querying user store"
|
||||
- users-create: "parsing argv", "validating input", "writing user record"
|
||||
- logout: "parsing argv", "invalidating session token"
|
||||
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (stdout unchanged when flag absent)
|
||||
- **Checkpoint:** `git commit -m "feat(commands): emit verbose stderr trace for 5 commands"`
|
||||
- **On failure:** stability tests fail → likely a stray `console.log` or `ctx.stdout.write` instead of `ctx.stderr.write`. Re-grep all five files for `stdout` mentions added in this step.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- src/commands/login.mjs
|
||||
- src/commands/token-refresh.mjs
|
||||
- src/commands/users-list.mjs
|
||||
- src/commands/users-create.mjs
|
||||
- src/commands/logout.mjs
|
||||
min_file_count: 5
|
||||
commit_message_pattern: "^feat\\(commands\\): emit verbose"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: src/commands/login.mjs
|
||||
pattern: "ctx\\.verbose"
|
||||
- path: src/commands/token-refresh.mjs
|
||||
pattern: "ctx\\.verbose"
|
||||
```
|
||||
|
||||
### Step 6: Add verbose-content test for `login`
|
||||
|
||||
- **Files:** `tests/cli-verbose-flag.test.mjs` (new file)
|
||||
- **Changes:** Single test: spawn `node src/cli.mjs login --verbose alice`, capture stderr, assert exit 0, assert stderr contains all three expected verbose lines: "[verbose] parsing argv", "[verbose] credential lookup", "[verbose] issuing session token", in that order.
|
||||
- **Verify:** `node --test tests/cli-verbose-flag.test.mjs` → expected: 1 pass
|
||||
- **Checkpoint:** `git commit -m "test(small-auth): assert --verbose emits expected stderr trace"`
|
||||
- **On failure:** if assertion misses a line, check step 5 for typos in the `[verbose]` strings; if exit code != 0, check that login still works without verbose (regression).
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- tests/cli-verbose-flag.test.mjs
|
||||
min_file_count: 1
|
||||
commit_message_pattern: "^test\\(small-auth\\): assert --verbose"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: tests/cli-verbose-flag.test.mjs
|
||||
pattern: "\\[verbose\\] credential lookup"
|
||||
```
|
||||
|
||||
### Step 7: Update `--help` text
|
||||
|
||||
- **Files:** `src/cli.mjs`
|
||||
- **Changes:** At the help-text constant (`src/cli.mjs:78`), add a line under "Global flags": ` -v, --verbose emit per-step trace to stderr (single level only)`.
|
||||
- **Verify:** `node src/cli.mjs --help | grep -E "verbose"` → expected: 1 line containing "emit per-step trace"
|
||||
- **Checkpoint:** `git commit -m "docs(cli): document --verbose / -v in --help text"`
|
||||
- **On failure:** revert just the constant; help text isn't load-bearing.
|
||||
- **Manifest:**
|
||||
```yaml
|
||||
manifest:
|
||||
expected_paths:
|
||||
- src/cli.mjs
|
||||
min_file_count: 1
|
||||
commit_message_pattern: "^docs\\(cli\\): document --verbose"
|
||||
bash_syntax_check: []
|
||||
forbidden_paths: []
|
||||
must_contain:
|
||||
- path: src/cli.mjs
|
||||
pattern: "emit per-step trace"
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
Final acceptance run after step 7:
|
||||
|
||||
```bash
|
||||
node --test tests/ # all 26 tests pass (24 + 2 new)
|
||||
node src/cli.mjs login alice > /tmp/out 2>/dev/null
|
||||
diff /tmp/out tests/golden/login.stdout # exit 0
|
||||
node src/cli.mjs login --verbose alice 2>/tmp/err 1>/dev/null
|
||||
grep -c "\[verbose\]" /tmp/err # ≥ 3
|
||||
node src/cli.mjs --help | grep -c "\-v, --verbose" # 1
|
||||
```
|
||||
|
||||
## Plan-critic notes
|
||||
|
||||
- No deferred decisions: every step names its files, lines, and exact
|
||||
string changes.
|
||||
- TDD: stability harness (step 2) precedes behavior changes (steps 3-5).
|
||||
- Verify commands are runnable, not "test it works".
|
||||
- Steps 5 wires 5 files in one commit; this is over the 1–2 file
|
||||
guideline but is justified by symmetry — the change is mechanical
|
||||
and atomic across the five files; splitting would create five tiny
|
||||
commits with no test value between them.
|
||||
|
||||
## Execution Strategy
|
||||
|
||||
Single session, 7 steps, ~15-20 minutes. No parallel decomposition needed.
|
||||
112
plugins/voyage/examples/01-add-verbose-flag/progress.json
Normal file
112
plugins/voyage/examples/01-add-verbose-flag/progress.json
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
{
|
||||
"schema_version": "1",
|
||||
"slug": "add-verbose-flag",
|
||||
"plan": ".claude/projects/2026-05-01-add-verbose-flag/plan.md",
|
||||
"plan_path": ".claude/projects/2026-05-01-add-verbose-flag/plan.md",
|
||||
"plan_version": "1.7",
|
||||
"mode": "single",
|
||||
"session_start_sha": "ab1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9",
|
||||
"started_at": "2026-05-01T10:14:32Z",
|
||||
"updated_at": "2026-05-01T10:31:08Z",
|
||||
"status": "completed",
|
||||
"current_step": 7,
|
||||
"total_steps": 7,
|
||||
"steps": [
|
||||
{
|
||||
"n": 1,
|
||||
"title": "Capture golden stdout for stability test",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:14:32Z",
|
||||
"completed_at": "2026-05-01T10:16:01Z",
|
||||
"commit_sha": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0",
|
||||
"files_changed": [
|
||||
"tests/golden/login.stdout",
|
||||
"tests/golden/whoami.stdout",
|
||||
"tests/golden/users-list.stdout"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 2,
|
||||
"title": "Add stability test (must FAIL initially — verbose not yet wired)",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:16:01Z",
|
||||
"completed_at": "2026-05-01T10:18:42Z",
|
||||
"commit_sha": "d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1",
|
||||
"files_changed": [
|
||||
"tests/cli-no-verbose-stability.test.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 3,
|
||||
"title": "Extend parser to recognize --verbose and -v",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:18:42Z",
|
||||
"completed_at": "2026-05-01T10:20:55Z",
|
||||
"commit_sha": "e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
|
||||
"files_changed": [
|
||||
"src/cli.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 4,
|
||||
"title": "Pass verbose into handler ctx",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:20:55Z",
|
||||
"completed_at": "2026-05-01T10:22:13Z",
|
||||
"commit_sha": "f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3",
|
||||
"files_changed": [
|
||||
"src/cli.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 5,
|
||||
"title": "Wire verbose output in login, token-refresh, users-list, users-create, logout",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:22:13Z",
|
||||
"completed_at": "2026-05-01T10:27:34Z",
|
||||
"commit_sha": "a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
|
||||
"files_changed": [
|
||||
"src/commands/login.mjs",
|
||||
"src/commands/token-refresh.mjs",
|
||||
"src/commands/users-list.mjs",
|
||||
"src/commands/users-create.mjs",
|
||||
"src/commands/logout.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 6,
|
||||
"title": "Add verbose-content test for login",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:27:34Z",
|
||||
"completed_at": "2026-05-01T10:29:51Z",
|
||||
"commit_sha": "b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
|
||||
"files_changed": [
|
||||
"tests/cli-verbose-flag.test.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
},
|
||||
{
|
||||
"n": 7,
|
||||
"title": "Update --help text",
|
||||
"status": "completed",
|
||||
"started_at": "2026-05-01T10:29:51Z",
|
||||
"completed_at": "2026-05-01T10:31:08Z",
|
||||
"commit_sha": "c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
|
||||
"files_changed": [
|
||||
"src/cli.mjs"
|
||||
],
|
||||
"verify_passed": true
|
||||
}
|
||||
],
|
||||
"stats": {
|
||||
"total_duration_ms": 996000,
|
||||
"verify_failures": 0,
|
||||
"manifest_failures": 0,
|
||||
"rollbacks": 0
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
type: trekresearch-brief
|
||||
research_version: 1.0
|
||||
question: How does small-auth currently parse arguments and where should --verbose hook in?
|
||||
confidence: 0.85
|
||||
dimensions: 4
|
||||
created: 2026-05-01
|
||||
---
|
||||
|
||||
# CLI parser conventions in small-auth
|
||||
|
||||
## Executive Summary
|
||||
|
||||
`small-auth` uses a hand-rolled argv parser at `src/cli.mjs:12-58` with a
|
||||
two-pass approach: first pass extracts global flags (currently
|
||||
`--help`, `--version`), second pass dispatches to command handlers in
|
||||
`src/commands/*.mjs`. Adding `--verbose` requires touching only the
|
||||
first-pass extractor and a new `verbose` parameter in the handler
|
||||
contract — six command handlers each get a one-line update.
|
||||
|
||||
The parser does **not** use `commander`, `yargs`, or any external
|
||||
library — this is intentional (zero deps) and consistent with the
|
||||
plugin marketplace's broader convention. We keep that.
|
||||
|
||||
`stderr` is currently unused except for fatal errors. Adding verbose
|
||||
output to stderr does not collide with anything.
|
||||
|
||||
Confidence: 0.85. The 0.15 uncertainty is around whether
|
||||
`--verbose` should propagate into nested helper modules
|
||||
(`src/lib/auth-token.mjs` calls `src/lib/db.mjs`); the plan should
|
||||
either pass `verbose` via a context object or use a module-scoped
|
||||
log function. Both work; the brief doesn't specify, so the planner
|
||||
will choose.
|
||||
|
||||
## Dimensions
|
||||
|
||||
### 1. Argument-parsing layer
|
||||
|
||||
The parser at `src/cli.mjs:12-58` returns
|
||||
`{globalFlags: {help, version}, command, positional, commandFlags}`.
|
||||
We add `verbose: boolean` to `globalFlags`. The two-pass design means
|
||||
`--verbose` works in any position automatically — no extra effort.
|
||||
|
||||
`-v` short form maps to `--verbose` via the existing alias table at
|
||||
`src/cli.mjs:34`.
|
||||
|
||||
### 2. Command-handler contract
|
||||
|
||||
Each handler in `src/commands/*.mjs` exports
|
||||
`async function run(positional, flags, ctx)`. Today `ctx` is
|
||||
`{stdout, stderr, env}`. We extend `ctx` with `verbose: boolean` so
|
||||
handlers can branch on it without re-reading globalFlags.
|
||||
|
||||
### 3. Internal log emission pattern
|
||||
|
||||
Existing fatal errors call `ctx.stderr.write(\`[error] ...\\n\`)`. The
|
||||
verbose pattern matches: `if (ctx.verbose) ctx.stderr.write(\`[verbose] ...\\n\`)`.
|
||||
No log helper needed for this iteration — six call sites total. Refactoring
|
||||
into a `verbose()` helper is reasonable but not required for the goal.
|
||||
|
||||
### 4. Test infrastructure
|
||||
|
||||
Tests live in `tests/*.test.mjs` using `node:test`. Existing tests run
|
||||
the CLI as a subprocess via `child_process.execFile` and assert on
|
||||
exit code + stdout. Two new tests are needed:
|
||||
|
||||
- `tests/cli-verbose-flag.test.mjs` — assert `login --verbose alice`
|
||||
exits 0, stderr contains "[verbose]", stdout matches golden file.
|
||||
- `tests/cli-no-verbose-stability.test.mjs` — assert
|
||||
`login alice` stdout is byte-identical to `tests/golden/login.stdout`.
|
||||
|
||||
## Citations
|
||||
|
||||
- `src/cli.mjs:12-58` — parser implementation
|
||||
- `src/commands/login.mjs:8-42` — typical handler shape
|
||||
- `tests/cli-help.test.mjs:14` — subprocess testing pattern
|
||||
- `package.json:scripts.test` — `node --test tests/*.test.mjs`
|
||||
|
||||
## Brief anchoring
|
||||
|
||||
Brief task: "Add a --verbose flag to the small-auth CLI parser".
|
||||
This research answers the planner's first question: where to hook
|
||||
into. The parser is small and centralized, so the change is
|
||||
minimal-scope.
|
||||
|
||||
The brief's success criteria around byte-identical default stdout
|
||||
maps directly to the stability test in dimension 4.
|
||||
224
plugins/voyage/examples/02-real-cli/REGENERATED.md
Normal file
224
plugins/voyage/examples/02-real-cli/REGENERATED.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# REGENERATED.md — examples/02-real-cli
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Calibrated against | trekplan v3.4.1 |
|
||||
| Last regenerated | 2026-05-04 (B3 session) |
|
||||
| Source brief author | Hand-authored by operator (B1 session, 2026-05-04) |
|
||||
| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) |
|
||||
| Pipeline run | B3 session, 2026-05-04 (commits `c4cf49f` → `da68c2f`) |
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
`examples/02-real-cli/` is the first **runnable** trekplan example.
|
||||
Unlike `examples/01-add-verbose-flag/` (which ships a frozen brief, plan,
|
||||
and research as artifacts but no executable code), this example ships a
|
||||
working ~80-line Node.js CLI (`tally`), a passing test suite, and known
|
||||
fixture data — all designed to be the input for a real pipeline run.
|
||||
|
||||
The fixture's purpose is twofold:
|
||||
|
||||
1. **End-to-end pipeline validation:** running `/trekresearch`,
|
||||
`/trekplan`, and `/trekexecute` against `brief.md` must
|
||||
produce green commits that satisfy all 10 brief Success Criteria. This
|
||||
is the controlled environment used to verify pipeline correctness on
|
||||
release-validation passes (see "Regeneration triggers" below).
|
||||
|
||||
2. **Cache-prefix measurement target (Spor C, planned):** the next track
|
||||
in the post-v3.4.0 roadmap will use this fixture under
|
||||
`CLAUDE_CODE_FORK_SUBAGENT` to measure cache-prefix preservation
|
||||
semantics. The fixture is small enough to fit comfortably under the
|
||||
150-250K context window where Path C measurements need to happen.
|
||||
|
||||
The brief deliberately picks a small, well-scoped feature (single boolean
|
||||
flag with regex semantics) so the pipeline output is predictable and
|
||||
testable, while still exercising the full plan/execute machinery
|
||||
(manifest YAML, plan-critic, scope-guardian, per-step verify, progress.json).
|
||||
|
||||
## Baseline (delivered by B2, 2026-05-04, commit `c8146c1`)
|
||||
|
||||
`tally` — an 80-line zero-dep Node.js CLI that counts literal-substring
|
||||
occurrences of a pattern in a text file. Three flags (`--json`,
|
||||
`-i`/`--ignore-case`, `--lines`), `--help`, exit codes 0/1/2.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
examples/02-real-cli/
|
||||
├── tally.mjs # CLI (80 lines, hand-rolled argv parser)
|
||||
├── tests/tally.test.mjs # 10 node:test cases (all pass ~2.2s)
|
||||
├── fixtures/
|
||||
│ ├── sample.txt # 9 lines, known counts (foo×7, Foo×1, /fo+/g×9, .×4)
|
||||
│ ├── poem.txt # 5 lines, "foo" --lines = 3, total = 4
|
||||
└── REGENERATED.md # this file
|
||||
```
|
||||
|
||||
Baseline preconditions verified by B2:
|
||||
|
||||
- `grep -c 'foo' fixtures/sample.txt` returns 4 lines containing `foo`
|
||||
(literal `foo` count = 7 across those lines).
|
||||
- regex `/fo+/g` matchAll on `sample.txt` = 9 (greater than literal `foo`
|
||||
count, as required by brief SC #1).
|
||||
- `--lines foo poem.txt` = 3, total `foo` in `poem.txt` = 4 (exercises
|
||||
`--lines` distinction in baseline tests).
|
||||
|
||||
## Pipeline run (delivered by B3, 2026-05-04)
|
||||
|
||||
The pipeline ran against `brief.md` (research_topics: 0, hand-authored).
|
||||
Each phase produced an artifact in
|
||||
`.claude/projects/2026-05-04-examples-02-real-cli/`.
|
||||
|
||||
### `/trekresearch`
|
||||
|
||||
**Outcome: skipped (intentionally).**
|
||||
|
||||
Brief declares `research_topics: 0` and `research_status: complete`.
|
||||
The brief's "Research Plan" section is explicit:
|
||||
|
||||
> No external research needed — this is a pure Node.js stdlib + `node:test`
|
||||
> task, the codebase fixture is self-contained, and the regex semantics
|
||||
> needed (`new RegExp(p)` + `String.prototype.matchAll`) are well-documented
|
||||
> MDN material.
|
||||
|
||||
Following the prompt's guidance ("Ikke kjør Gemini-bridge eller
|
||||
community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was
|
||||
not invoked. No research file was written; `research/` directory does not
|
||||
exist for this project. Downstream commands (`/trekplan`) auto-discover
|
||||
research files but do not require them — the missing directory is fine
|
||||
per the soft-mode `research-validator` contract.
|
||||
|
||||
### `/trekplan`
|
||||
|
||||
**Outcome: plan.md with 4 steps; plan-validator strict PASS;
|
||||
plan-critic 0 BLOCKER (4 MAJOR fixed in revision); scope-guardian
|
||||
PASS — ALIGNED.**
|
||||
|
||||
`plan.md` headers:
|
||||
|
||||
```
|
||||
# Add `--regex`/`-r` mode to the `tally` CLI fixture
|
||||
plan_version: 1.7
|
||||
|
||||
## Context
|
||||
## Codebase Analysis
|
||||
## Research Sources
|
||||
## Implementation Plan
|
||||
### Step 1: Add `--regex`/`-r` parsing and `compileRegex` helper
|
||||
### Step 2: Wire regex counting path in `main()`
|
||||
### Step 3: Update `--help` text to document `--regex`/`-r`
|
||||
### Step 4: Add 4 new tests covering the regex path
|
||||
## Verification
|
||||
## Plan-critic notes
|
||||
## Scope-guardian notes
|
||||
## Execution Strategy
|
||||
```
|
||||
|
||||
Adversarial-review summary:
|
||||
|
||||
| Reviewer | Verdict | Findings |
|
||||
|----------|---------|----------|
|
||||
| `plan-critic` | REVISE → re-run after fixes | 0 BLOCKER, 4 MAJOR (non-assertive verify in step 1; unchained verify in step 2; SC #9 final-block mismatch; `compileRegex` 'g' flag rationale missing). All 4 fixed. |
|
||||
| `scope-guardian` | PASS — ALIGNED | 0 creep, 0 material gaps. Every brief SC and Non-Goal mapped to a step or manifest constraint. |
|
||||
|
||||
Manifest YAML on every step uses `forbidden_paths: examples/02-real-cli/package.json`
|
||||
to enforce the brief's "no package.json" Non-Goal. `must_contain` patterns
|
||||
require named symbols (`flags.regex`, `compileRegex`, `--regex 'fo+'`,
|
||||
`-r short form`, `invalid regex`) so the verifier confirms substantive
|
||||
changes, not just file modifications.
|
||||
|
||||
### `/trekexecute`
|
||||
|
||||
**Outcome: 4 commits, all green, all `verify_passed: true`.**
|
||||
|
||||
`progress.json` summary:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1",
|
||||
"plan_version": "1.7",
|
||||
"mode": "single-session",
|
||||
"status": "completed",
|
||||
"total_steps": 4,
|
||||
"current_step": 4
|
||||
}
|
||||
```
|
||||
|
||||
Step-by-step:
|
||||
|
||||
| Step | Commit | Title | Verify |
|
||||
|------|--------|-------|--------|
|
||||
| 1 | `c4cf49f` | feat(tally): parse --regex/-r flag and add compileRegex helper | flag parsed, literal count = 7 |
|
||||
| 2 | `44d7f33` | feat(tally): wire regex counting path in main with invalid-regex exit-2 | OK1, OK2, OK3, OK4 (4 chained assertions) |
|
||||
| 3 | `c6ff4fa` | docs(tally): document --regex / -r in --help text | `--help \| grep -c -- "--regex"` = 1 |
|
||||
| 4 | `da68c2f` | test(tally): add 4 tests for --regex/-r path covering SC #1, #2, #4, #5 | tests 14, pass 14, fail 0, duration_ms 3162.74 |
|
||||
|
||||
Constraint compliance:
|
||||
|
||||
- `tally.mjs`: 93 lines (under 100-line cap, +13 from 80-line baseline)
|
||||
- `tests/tally.test.mjs`: 14 tests (exactly at 14-test cap, +4 from 10-test baseline)
|
||||
- Test wall-clock: 3.16 s (under 5 s cap)
|
||||
- `package.json`: not created (Non-Goal enforced)
|
||||
- Files outside `examples/02-real-cli/`: zero
|
||||
- Hook safety: zero shutdown/halt/reboot/poweroff/mkfs words in commit
|
||||
bodies or verify commands
|
||||
|
||||
### Success Criteria status (10/10 PASS)
|
||||
|
||||
| SC | Verifier | Result |
|
||||
|----|----------|--------|
|
||||
| #1 | flag in 3 positions, all exit 0, same count | PASS (all = 9) |
|
||||
| #2 | `-r 'fo+' sample.txt` == long form | PASS (both = 9) |
|
||||
| #3 | `tally '.' sample.txt` (= 4) << `tally --regex '.' sample.txt` (= 209) | PASS |
|
||||
| #4 | `tally --regex '[' sample.txt` exits 2, stderr `^tally: invalid regex` | PASS |
|
||||
| #5 | `--json --regex 'fo+'` includes `flags.regex: true` | PASS |
|
||||
| #6 | `tally 'foo' sample.txt` = 7 (= B2 baseline) | PASS |
|
||||
| #7 | tests ≥ 12, ≥ 2 names contain `--regex` or `-r` | PASS (14 tests, 4 named) |
|
||||
| #8 | `tally --help` contains `--regex` line | PASS |
|
||||
| #9 | `REGENERATED.md` walk-through filled in | PASS (this file) |
|
||||
| #10 | no `package.json` created | PASS |
|
||||
|
||||
## How to re-run this example
|
||||
|
||||
```bash
|
||||
cd /path/to/trekplan
|
||||
|
||||
# 1. Re-run the pipeline against the existing brief
|
||||
# (research is skipped — research_topics: 0)
|
||||
/trekplan --project .claude/projects/2026-05-04-examples-02-real-cli
|
||||
/trekexecute --project .claude/projects/2026-05-04-examples-02-real-cli
|
||||
|
||||
# 2. Verify all 10 Success Criteria from brief.md hold (commands above)
|
||||
node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass
|
||||
|
||||
# 3. Smoke-test individual SC commands:
|
||||
node examples/02-real-cli/tally.mjs --regex 'fo+' examples/02-real-cli/fixtures/sample.txt
|
||||
# expected: 9
|
||||
node examples/02-real-cli/tally.mjs -r 'fo+' examples/02-real-cli/fixtures/sample.txt
|
||||
# expected: 9
|
||||
node examples/02-real-cli/tally.mjs --json --regex 'fo+' examples/02-real-cli/fixtures/sample.txt | python3 -m json.tool
|
||||
# expected: {"pattern": "fo+", "count": 9, "flags": {..., "regex": true}}
|
||||
node examples/02-real-cli/tally.mjs --help | grep -- "--regex"
|
||||
# expected: " -r, --regex Interpret <pattern> as a JavaScript regular expression"
|
||||
```
|
||||
|
||||
If any of those expected values changes, the pipeline output has drifted
|
||||
and `examples/02-real-cli/` should be re-baselined (see "Regeneration
|
||||
triggers" below).
|
||||
|
||||
## Regeneration triggers
|
||||
|
||||
When to re-run this example:
|
||||
|
||||
- trekplan minor version bump (e.g. v3.4 → v3.5)
|
||||
- `plan_version` schema bump
|
||||
- Manifest YAML required-key additions
|
||||
- `progress.json` schema bump
|
||||
- Pipeline-output format change (brief / research / plan / progress)
|
||||
|
||||
When regenerating: re-run the pipeline against the existing `brief.md` and
|
||||
update this file plus the `examples/02-real-cli/` artifacts. The
|
||||
"baseline" portion of the fixture (`tally.mjs` minus the regex feature,
|
||||
the fixture text files, and the original 10 baseline tests) stays stable
|
||||
across regenerations — only the pipeline outputs and any drift in the
|
||||
extended `tally.mjs` change. If you want a clean re-run, reset to commit
|
||||
`c8146c1` (B2 baseline) before invoking the pipeline.
|
||||
5
plugins/voyage/examples/02-real-cli/fixtures/poem.txt
Normal file
5
plugins/voyage/examples/02-real-cli/fixtures/poem.txt
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
foo on this line
|
||||
nothing here
|
||||
foo and foo here
|
||||
silence
|
||||
foo
|
||||
9
plugins/voyage/examples/02-real-cli/fixtures/sample.txt
Normal file
9
plugins/voyage/examples/02-real-cli/fixtures/sample.txt
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
Foo bar baz
|
||||
The quick brown fox jumps over the foo
|
||||
foo foo bar foo
|
||||
food for thought.
|
||||
fooo, fooooo, very loud
|
||||
This line has no match here.
|
||||
A line without the magic word
|
||||
And another one without it
|
||||
The end. Final period.
|
||||
93
plugins/voyage/examples/02-real-cli/tally.mjs
Executable file
93
plugins/voyage/examples/02-real-cli/tally.mjs
Executable file
|
|
@ -0,0 +1,93 @@
|
|||
#!/usr/bin/env node
|
||||
import { readFileSync } from 'node:fs';
|
||||
|
||||
const HELP = `Usage: tally [options] <pattern> <file>
|
||||
|
||||
Count literal-substring occurrences of <pattern> in <file>.
|
||||
|
||||
Options:
|
||||
-i, --ignore-case Case-insensitive matching
|
||||
--lines Count lines containing pattern (not total occurrences)
|
||||
-r, --regex Interpret <pattern> as a JavaScript regular expression
|
||||
--json Emit a JSON object on stdout
|
||||
-h, --help Show this help and exit
|
||||
|
||||
Exit codes: 0=success 1=file error 2=invalid argv
|
||||
`;
|
||||
|
||||
function fail(msg, code = 2) {
|
||||
process.stderr.write(`tally: ${msg}\n`);
|
||||
process.exit(code);
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const positional = [];
|
||||
const flags = { json: false, ignoreCase: false, lines: false, regex: false };
|
||||
for (const a of argv) {
|
||||
if (a === '--json') flags.json = true;
|
||||
else if (a === '-i' || a === '--ignore-case') flags.ignoreCase = true;
|
||||
else if (a === '--lines') flags.lines = true;
|
||||
else if (a === '--regex' || a === '-r') flags.regex = true;
|
||||
else if (a === '-h' || a === '--help') { process.stdout.write(HELP); process.exit(0); }
|
||||
else if (a.startsWith('-')) fail(`unknown flag: ${a}`);
|
||||
else positional.push(a);
|
||||
}
|
||||
if (positional.length !== 2) fail('expected <pattern> <file>');
|
||||
return { pattern: positional[0], file: positional[1], flags };
|
||||
}
|
||||
|
||||
function compileRegex(pattern) {
|
||||
try { return new RegExp(pattern, 'g'); }
|
||||
catch (e) { fail(`invalid regex: ${e.message}`); }
|
||||
}
|
||||
|
||||
function countOccurrences(text, pattern, ignoreCase) {
|
||||
if (pattern.length === 0) return 0;
|
||||
const haystack = ignoreCase ? text.toLowerCase() : text;
|
||||
const needle = ignoreCase ? pattern.toLowerCase() : pattern;
|
||||
let count = 0, idx = 0;
|
||||
while ((idx = haystack.indexOf(needle, idx)) !== -1) { count++; idx += needle.length; }
|
||||
return count;
|
||||
}
|
||||
|
||||
function countLines(text, pattern, ignoreCase) {
|
||||
if (pattern.length === 0) return 0;
|
||||
const needle = ignoreCase ? pattern.toLowerCase() : pattern;
|
||||
let count = 0;
|
||||
for (const line of text.split('\n')) {
|
||||
const haystack = ignoreCase ? line.toLowerCase() : line;
|
||||
if (haystack.includes(needle)) count++;
|
||||
}
|
||||
return count;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const { pattern, file, flags } = parseArgs(process.argv.slice(2));
|
||||
let text;
|
||||
try {
|
||||
text = readFileSync(file, 'utf8');
|
||||
} catch (err) {
|
||||
const what = err.code === 'ENOENT' ? 'file not found' : 'read error';
|
||||
process.stderr.write(`tally: ${what}: ${file}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
let count;
|
||||
if (flags.regex) {
|
||||
const re = compileRegex(pattern);
|
||||
count = (text.match(re) || []).length;
|
||||
} else if (flags.lines) {
|
||||
count = countLines(text, pattern, flags.ignoreCase);
|
||||
} else {
|
||||
count = countOccurrences(text, pattern, flags.ignoreCase);
|
||||
}
|
||||
if (flags.json) {
|
||||
process.stdout.write(JSON.stringify({
|
||||
pattern, file, count,
|
||||
flags: { json: flags.json, ignoreCase: flags.ignoreCase, lines: flags.lines, regex: flags.regex },
|
||||
}) + '\n');
|
||||
} else {
|
||||
process.stdout.write(count + '\n');
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
127
plugins/voyage/examples/02-real-cli/tests/tally.test.mjs
Normal file
127
plugins/voyage/examples/02-real-cli/tests/tally.test.mjs
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { dirname, resolve } from 'node:path';
|
||||
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const TALLY = resolve(here, '..', 'tally.mjs');
|
||||
const SAMPLE = resolve(here, '..', 'fixtures', 'sample.txt');
|
||||
const POEM = resolve(here, '..', 'fixtures', 'poem.txt');
|
||||
|
||||
function run(...args) {
|
||||
return spawnSync('node', [TALLY, ...args], { encoding: 'utf8' });
|
||||
}
|
||||
|
||||
test('plain count: tally foo sample.txt prints 7', () => {
|
||||
const r = run('foo', SAMPLE);
|
||||
assert.equal(r.status, 0);
|
||||
assert.equal(r.stdout.trim(), '7');
|
||||
assert.equal(r.stderr, '');
|
||||
});
|
||||
|
||||
test('JSON output: tally --json foo sample.txt parses with count 7', () => {
|
||||
const r = run('--json', 'foo', SAMPLE);
|
||||
assert.equal(r.status, 0);
|
||||
const parsed = JSON.parse(r.stdout);
|
||||
assert.equal(parsed.count, 7);
|
||||
assert.equal(parsed.pattern, 'foo');
|
||||
assert.equal(parsed.flags.json, true);
|
||||
assert.equal(parsed.flags.ignoreCase, false);
|
||||
assert.equal(parsed.flags.lines, false);
|
||||
});
|
||||
|
||||
test('case-sensitive default: tally Foo sample.txt prints 1', () => {
|
||||
const r = run('Foo', SAMPLE);
|
||||
assert.equal(r.status, 0);
|
||||
assert.equal(r.stdout.trim(), '1');
|
||||
});
|
||||
|
||||
test('case-insensitive: tally -i Foo == tally -i foo (and exceeds case-sensitive)', () => {
|
||||
const ri1 = run('-i', 'Foo', SAMPLE);
|
||||
const ri2 = run('-i', 'foo', SAMPLE);
|
||||
const rcs = run('foo', SAMPLE);
|
||||
assert.equal(ri1.status, 0);
|
||||
assert.equal(ri2.status, 0);
|
||||
assert.equal(ri1.stdout, ri2.stdout);
|
||||
assert.ok(Number(ri1.stdout) > Number(rcs.stdout));
|
||||
});
|
||||
|
||||
test('--lines mode: tally --lines foo poem.txt prints 3 (not total occurrences 4)', () => {
|
||||
const lines = run('--lines', 'foo', POEM);
|
||||
const total = run('foo', POEM);
|
||||
assert.equal(lines.status, 0);
|
||||
assert.equal(total.status, 0);
|
||||
assert.equal(lines.stdout.trim(), '3');
|
||||
assert.equal(total.stdout.trim(), '4');
|
||||
});
|
||||
|
||||
test('flag in last position: tally foo sample.txt --json equals tally --json foo sample.txt', () => {
|
||||
const last = run('foo', SAMPLE, '--json');
|
||||
const first = run('--json', 'foo', SAMPLE);
|
||||
assert.equal(last.status, 0);
|
||||
assert.equal(first.status, 0);
|
||||
assert.equal(last.stdout, first.stdout);
|
||||
});
|
||||
|
||||
test('missing argument: tally foo exits 2 with stderr', () => {
|
||||
const r = run('foo');
|
||||
assert.equal(r.status, 2);
|
||||
assert.match(r.stderr, /^tally: /);
|
||||
assert.equal(r.stdout, '');
|
||||
});
|
||||
|
||||
test('unknown flag: tally --unknown foo sample.txt exits 2 with stderr', () => {
|
||||
const r = run('--unknown', 'foo', SAMPLE);
|
||||
assert.equal(r.status, 2);
|
||||
assert.match(r.stderr, /^tally: /);
|
||||
assert.equal(r.stdout, '');
|
||||
});
|
||||
|
||||
test('file not found: tally foo /does/not/exist exits 1 with stderr', () => {
|
||||
const r = run('foo', '/does/not/exist');
|
||||
assert.equal(r.status, 1);
|
||||
assert.match(r.stderr, /^tally: /);
|
||||
assert.equal(r.stdout, '');
|
||||
});
|
||||
|
||||
test('--help: stdout contains "Usage:", exit 0', () => {
|
||||
const r = run('--help');
|
||||
assert.equal(r.status, 0);
|
||||
assert.match(r.stdout, /Usage:/);
|
||||
assert.match(r.stdout, /--ignore-case/);
|
||||
});
|
||||
|
||||
// --- Tests for --regex / -r mode (added in plan step 4, Spor B B3) ---
|
||||
|
||||
test("--regex 'fo+' counts more matches than literal 'foo' (long form, exit 0)", () => {
|
||||
const literal = run('foo', SAMPLE);
|
||||
const regex = run('--regex', 'fo+', SAMPLE);
|
||||
assert.equal(literal.status, 0);
|
||||
assert.equal(regex.status, 0);
|
||||
assert.ok(Number(regex.stdout) >= Number(literal.stdout),
|
||||
`regex count (${regex.stdout.trim()}) should be >= literal count (${literal.stdout.trim()})`);
|
||||
});
|
||||
|
||||
test("-r short form equals --regex long form (same stdout)", () => {
|
||||
const short = run('-r', 'fo+', SAMPLE);
|
||||
const long = run('--regex', 'fo+', SAMPLE);
|
||||
assert.equal(short.status, 0);
|
||||
assert.equal(long.status, 0);
|
||||
assert.equal(short.stdout, long.stdout);
|
||||
});
|
||||
|
||||
test("--regex '[' exits 2 with stderr 'tally: invalid regex'", () => {
|
||||
const r = run('--regex', '[', SAMPLE);
|
||||
assert.equal(r.status, 2);
|
||||
assert.equal(r.stdout, '');
|
||||
assert.match(r.stderr, /^tally: invalid regex/);
|
||||
});
|
||||
|
||||
test("--json --regex 'fo+' includes flags.regex === true in output", () => {
|
||||
const r = run('--json', '--regex', 'fo+', SAMPLE);
|
||||
assert.equal(r.status, 0);
|
||||
const parsed = JSON.parse(r.stdout);
|
||||
assert.equal(parsed.flags.regex, true);
|
||||
assert.ok(typeof parsed.count === 'number' && parsed.count > 0);
|
||||
});
|
||||
73
plugins/voyage/examples/README.md
Normal file
73
plugins/voyage/examples/README.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# Examples
|
||||
|
||||
Complete kalibrerte walk-throughs of the trekplan pipeline for
|
||||
realistic tasks. Each example shows the four artifacts a project
|
||||
directory contains after a full run:
|
||||
|
||||
- `brief.md` — task brief from `/trekbrief`
|
||||
- `research/*.md` — research briefs from `/trekresearch`
|
||||
- `plan.md` — implementation plan from `/trekplan`
|
||||
- `progress.json` — execution log from `/trekexecute`
|
||||
|
||||
These are **hand-calibrated**, not LLM-generated. The point is to give
|
||||
a fork-er a deterministic reference — what the artifacts look like
|
||||
when everything goes right, with a small but real task.
|
||||
|
||||
## Running pipeline yourself
|
||||
|
||||
For your own work, point the four commands at a real project directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/projects/2026-05-01-my-task
|
||||
/trekbrief
|
||||
/trekresearch --project .claude/projects/2026-05-01-my-task
|
||||
/trekplan --project .claude/projects/2026-05-01-my-task
|
||||
/trekexecute --project .claude/projects/2026-05-01-my-task
|
||||
```
|
||||
|
||||
The artifacts in each example mirror that flow.
|
||||
|
||||
## Examples
|
||||
|
||||
### 01-add-verbose-flag
|
||||
|
||||
**Task:** add a `--verbose` flag to a small CLI parser. Touches one
|
||||
parser file and six command handlers; adds two tests.
|
||||
|
||||
**Why this example:** small enough to read end-to-end in 10 minutes,
|
||||
but exercises every artifact (research with brief-anchoring, plan with
|
||||
manifests, progress.json with multi-step git history). Demonstrates
|
||||
how `plan_version: 1.7` schema looks in real life — including the
|
||||
manifest YAML block per step and the `must_contain` list-of-dicts
|
||||
form.
|
||||
|
||||
**What to study first:**
|
||||
|
||||
1. `brief.md` — note the explicit `Out of scope` section and concrete
|
||||
`Success Criteria` (no "make it work" hand-waving).
|
||||
2. `plan.md` Step 1 — note that the FIRST step captures golden output
|
||||
*before* any behavior change. This is the stability harness pattern.
|
||||
3. `plan.md` Step 5 — note that this step touches 5 files in one
|
||||
commit, and the plan justifies the deviation from the 1–2 file
|
||||
guideline. Plan-critic should accept that justification.
|
||||
4. `progress.json` — every step has both `commit_sha` and
|
||||
`verify_passed`. Resumes work from the last completed step.
|
||||
|
||||
## Regeneration
|
||||
|
||||
Each example has a `REGENERATED.md` documenting the version it was
|
||||
calibrated against. When the artifact format changes, the example
|
||||
needs to be re-built. See the `REGENERATED.md` file in each example
|
||||
for triggers and procedure.
|
||||
|
||||
## Adding a new example
|
||||
|
||||
If you have a small, realistic task (touches 1-3 files, has a clear
|
||||
success criterion, finishes in under 30 minutes) and want to add it
|
||||
as an example:
|
||||
|
||||
1. Create `examples/NN-slug-here/` with the same four artifacts.
|
||||
2. Add a `REGENERATED.md` documenting the calibration date and version.
|
||||
3. Add a section to this README under `## Examples`.
|
||||
4. Open an issue on the marketplace describing what the example
|
||||
teaches that 01 doesn't already teach.
|
||||
Loading…
Add table
Add a link
Reference in a new issue