Build Aff v2 CLI prototype

[tanishqkancharla]

Summary

• Adds the Aff v2 prototype under packages/affordance/src/v2 with bottom-up CLI, group, command, input, and middleware builders.
• Adds focused Aff v2 tests for routes/help, input parsing, middleware runtime semantics, middleware types, and command-line parsing.
• Documents the Aff v2 public API with concise JSDoc and tracks remaining rollout work in specs/affordance-orpc-middleware-spec.md.

Where this is paused

• Phase 10 has started but is intentionally paused after named option aliases.
• Named option aliases are implemented for Aff.option(schema, { aliases }) and Aff.flag({ aliases }).
• Duplicate/conflicting aliases are validated during command construction.

Tracking

• Notion task: https://app.notion.com/p/Finish-Affordance-v2-and-migrate-Libretto-379ac9fb35f18145b8a4ea831475c0d4

Verification

• pnpm -s --filter affordance check

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
libretto	Ready	Preview, Comment	Jun 8, 2026 9:18pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
libretto-docs	Ignored	Preview	Jun 8, 2026 9:18pm

[github-actions]

I’ll verify GitHub PR access first using the required gh pr commands. If either fails, I’ll stop without inspecting local diffs.
GitHub API access is available. I’ll use the PR diff and spec from GitHub as the source of truth, and I’ll ignore lockfile changes as requested.
The installed gh pr diff does not accept a path filter after the PR number, so I’ll inspect per-file patches through the GitHub API instead of falling back to local git.
The environment allows only gh pr view and gh pr diff through bash. I’ll use the full PR diff output from gh pr diff 382 for the detailed inspection.
The full PR diff is large and was captured to a local tool-output file. I’ll read that captured diff in chunks to review the implementation without making changes.

OpenCode Review

📋 Detailed Review

Spec Analysis

• Build Aff v2 separately under packages/affordance/src/v2, exposed as Aff.
• Implement bottom-up CLI, group, command, input, and middleware builders.
• Support route metadata, direct invocation, command-line execution, help rendering, Standard Schema input validation, options/flags, aliases, and oRPC-style middleware.
• Keep v1 SimpleCLI and package root exports unchanged during these phases.
• Add focused v2 tests under packages/affordance/test/v2.
• Phase 10 is paused after named option aliases; passthrough args, global options, variadic args, appended help, duplicate route validation, and missing handler validation remain intentionally incomplete.

Changed Files

• .agents/skills/glimpse-changes/SKILL.md: Updates Glimpse skill usage and review workflow docs.
• .agents/skills/glimpse-changes/assets/annotations.css: Adds annotation sidebar styling.
• .agents/skills/glimpse-changes/assets/annotations.js: Adds browser-side annotation behavior.
• .agents/skills/glimpse-changes/assets/critique-base.css: Adds base rendered-review styles.
• .agents/skills/glimpse-changes/assets/critique-markdown.css: Adds markdown and diff rendering styles.
• .agents/skills/glimpse-changes/assets/jetbrains-mono-nerd.woff2: Adds bundled font asset.
• .agents/skills/glimpse-changes/bin/glimpse-changes.js: Adds bundled Glimpse renderer CLI.
• .agents/skills/glimpse-changes/package.json: Adds skill-local package metadata.
• .fallowrc.json: Removes fallow configuration.
• .oxfmtrc.json: Adds oxfmt configuration.
• AGENTS.md: Updates repository check workflow guidance.
• package.json: Adds root check/format scripts and swaps fallow for oxfmt/npm-run-all2.
• packages/affordance/package.json: Adds Aff v2 dependencies and check/format scripts.
• packages/affordance/src/v2/command.ts: Adds command builder, command handler, input, and command middleware support.
• packages/affordance/src/v2/group.ts: Adds group builder and group middleware support.
• packages/affordance/src/v2/help.ts: Adds help rendering and route/help path helpers.
• packages/affordance/src/v2/index.ts: Adds Aff v2 public API, app construction, route flattening, invoke, and exec.
• packages/affordance/src/v2/input/input.ts: Adds Standard Schema input definitions, option/flag helpers, parsing, validation, and aliases.
• packages/affordance/src/v2/input/parser.ts: Adds Teg-based command-line parser.
• packages/affordance/src/v2/middleware.ts: Adds middleware types, builders, and runtime composition.
• packages/affordance/test/v2/input-types.spec.ts: Adds input inference type tests.
• packages/affordance/test/v2/input.spec.ts: Adds input parsing, validation, Standard Schema, and alias tests.
• packages/affordance/test/v2/middleware-types.spec.ts: Adds middleware context/input type contract tests.
• packages/affordance/test/v2/middleware.spec.ts: Adds runtime middleware behavior tests.
• packages/affordance/test/v2/parser.spec.ts: Adds parser tokenization tests.
• packages/affordance/test/v2/routes-and-help.spec.ts: Adds route, invoke, exec, and help tests.
• packages/libretto/package.json: Adds package-level check script.
• packages/libretto/skills-lock.json: Updates Glimpse skill lock metadata.
• packages/libretto/src/shared/state/session-state.ts: Updates Zod URL schema usage.
• packages/libretto/test/basic.spec.ts: Updates Zod URL schema usage.
• packages/libretto/test/workflow-zod-schema.spec.ts: Updates Zod URL schema usage.
• pnpm-lock.yaml: Lockfile updates ignored for review.
• pnpm-workspace.yaml: Updates pnpm metadata settings.
• skills-lock.json: Adds Glimpse skill lock metadata.
• specs/affordance-orpc-middleware-spec.md: Adds Aff v2 phased implementation spec.
• turbo.json: Adds check and format tasks.

Simplicity Assessment

• packages/affordance/src/v2/index.ts:3709-3776 has similar execution flow in invoke(...) and exec(...): route lookup, unexpected-input checks, parsing, and runMiddlewares(...). This is acceptable for the prototype, but it could be simplified by extracting a small shared runCommandRoute(route, rawInput, initialContext) helper once the API stabilizes.
• packages/affordance/src/v2/command.ts:3293-3339 builds input definitions during .arguments(...)/.options(...) and again in .handle(...). The current version is still small, but storing the current input definition directly in the builder state would remove the duplicate createInputDefinition(...) call path.
• packages/affordance/src/v2/input/input.ts:4044-4083 keeps alias normalization and alias validation in one place, which is the right level of abstraction for the named alias goal. I did not find unnecessary alias-specific builder layers.
• packages/affordance/src/v2/middleware.ts:4388-4413 uses a direct recursive middleware runner rather than introducing a pipeline abstraction. This is appropriately minimal for the required oRPC-style semantics.

Correctness Assessment

• No blocking correctness issues found in the implemented Aff v2 phases.
• packages/affordance/src/v2/input/parser.ts:4206-4210 does not accept separated option values that begin with -, so --count -1 is parsed as a missing --count value followed by another option-like token. Inline values such as --count=-1 still work, and negative separated values are not listed as a current requirement, so this is non-blocking.
• packages/affordance/src/v2/index.ts:3816-3823 intentionally resolves the longest command-path prefix and lets the input layer reject leftover positional arguments. That correctly supports errors like status extra while preserving nested command matching.
• packages/affordance/src/v2/middleware.ts:4404-4409 preserves downstream errors through next() because it does not catch or wrap exceptions. This satisfies the middleware error propagation goal.
• packages/affordance/src/v2/input/input.ts:4059-4083 validates duplicate and conflicting aliases at command construction time through createInputDefinition(...), matching the PR description.

Summary

The PR implements the paused Aff v2 prototype phases in line with the spec: separate Aff APIs, focused v2 tests, Standard Schema input support, command-line parsing, help rendering, middleware runtime semantics, type contracts, and named option aliases. I did not find any merge-blocking functional defects in the implemented scope.

Required Actions

None

Suggestions

• Consider extracting the duplicated command execution path in packages/affordance/src/v2/index.ts:3709-3776 once the prototype stabilizes.
• If separated negative option values are expected, adjust packages/affordance/src/v2/input/parser.ts:4206-4210; otherwise the current inline --option=-1 behavior is sufficient for now.

github run