Add IO position enrichment tool + backfill Eventide H90 (#212)

[jeffreylouden]

Context

Starts #212 — spatial ordering of hardware I/O ports (columnPosition / rowPosition) so the Studio setup graph can render port layouts. The schema, validator, and SQLite build already supported these fields; what was missing was a documented convention, a tool to assign them, and real data. This PR adds all three, using the Eventide H90 as the validation case.

What's in here

1. Convention — documented in schema/CONTEXT.md (via generate-context.ts) and CLAUDE.md:

• columnPosition: 1-based left-to-right per position edge (column 1 = leftmost).
• rowPosition: 1-based top-to-bottom (row 1 = topmost). Stacked ports share a column, differ by row.
• Numbered independently per edge; placed right after position.

2. Tool — new pnpm enrich-io <slug> [--dry-run] [--open]:

• Interactive (Node built-in readline, no new deps), reads lines via readline's async iterator so it works with both interactive typing and piped input.
• Writes back with the yaml Document API, preserving comments/formatting and inserting the keys in canonical order.
• Prints the product URL for viewing port photos (images aren't stored in this repo).

3. H90 backfill/correction — the entry's I/O was incomplete (5 of 14 jacks; missing all audio ins/outs and MIDI Out) and mis-positioned (Bottom). Rewritten to all 14 discrete rear-panel jacks, one entry per physical jack (maxConnections: 1), confirmed against the H90 Quick Reference Guide's rear-panel diagram:

• Inputs 1–4 and Outputs 1–4 as 2×2 grids (exercising both column and row), Exp/Ctl 1–2, USB-C, Power, MIDI In, MIDI Out/Thru.

Verification

• pnpm validate ✅ (no new warnings), pnpm typecheck ✅, pnpm lint ✅
• pnpm build → confirmed hardware_io.column_position/row_position populate for all 14 H90 ports
• enrich-io smoke-tested: all-Enter → no changes; dry-run reports without writing; real write preserves formatting

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added optional columnPosition/rowPosition metadata to control hardware IO ordering (left-to-right, top-to-bottom).
  • Introduced interactive pnpm enrich-io <slug> to set/update IO positions and write changes back to YAML (supports --dry-run, and optional URL opening).

• Bug Fixes

  • Corrected the Eventide H90 Harmonizer IO listing so all rear-panel jacks are properly included and positioned.

• Documentation

  • Updated port ordering conventions and clarified that each io entry maps to a single physical jack.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5c7a479

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
catalog	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a70441d-901d-4f7b-8311-aaf8b7e38c7f

📥 Commits

Reviewing files that changed from the base of the PR and between 2bf01d5 and 5c7a479.

📒 Files selected for processing (1)

• data/hardware/eventide-audio-h90-harmonizer.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• data/hardware/eventide-audio-h90-harmonizer.yaml

---

Walkthrough

Adds optional columnPosition and rowPosition metadata, an interactive pnpm enrich-io <slug> YAML editor, generated documentation, and a complete positional IO backfill for the Eventide H90 Harmonizer.

Changes

IO Position Enrichment

Layer / File(s)	Summary
Position conventions and documentation CLAUDE.md, scripts/generate-context.ts, schema/CONTEXT.md	Documents per-edge 1-based port ordering and the one-physical-jack IO modeling rule.
Interactive enrichment workflow scripts/enrich-io.ts, package.json	Adds interactive position editing with validation, clearing, dry-run support, YAML formatting preservation, and CLI wiring.
Eventide H90 IO backfill data/hardware/eventide-audio-h90-harmonizer.yaml, .changeset/io-positions-enrichment.md	Defines audio, expression, USB, power, and MIDI connectors with explicit positions and records the minor catalog update.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant EnrichIO
  participant HardwareYAML
  Operator->>EnrichIO: run pnpm enrich-io <slug>
  EnrichIO->>HardwareYAML: parse and validate io entries
  EnrichIO-->>Operator: prompt for columnPosition and rowPosition
  Operator->>EnrichIO: enter, clear, or update values
  EnrichIO->>HardwareYAML: write ordered position fields
  HardwareYAML-->>Operator: updated YAML and change summary

Loading

Possibly related issues

• catalog#212 — The changes implement the issue’s IO positioning conventions, enrichment workflow, documentation, and initial Eventide H90 backfill.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding an IO position enrichment tool and backfilling the Eventide H90 entry.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch io-positions-h90-enrich

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@data/hardware/eventide-audio-h90-harmonizer.yaml`:
- Around line 143-160: Update the MIDI In and MIDI Out/Thru entries in the H90
hardware definition so their position metadata uses the appropriate physical
side edge (Left or Right) rather than Top, while preserving their existing
connection and layout metadata.
- Around line 18-23: Reorder the hardware I/O fields in each affected entry so
the required keys remain contiguous: name, signalFlow, category, type,
connection, maxConnections, and position. Move connectorDetail and other
optional fields after position and the ordering fields, consistently updating
all listed entries.
- Around line 13-100: Update the audio jack definitions for Input 1, Input 2,
Input 3, Input 4, Output 1, Output 2, Output 3, and Output 4 so their type
metadata represents both selectable instrument and line levels rather than
hard-coding Input 1–2 as instrument and the others as line; preserve the
existing connector, routing, and positional fields.

In `@scripts/enrich-io.ts`:
- Around line 143-149: Validate slugArg against the documented safe slug format
and reject any traversal characters or path separators before the path.join call
in the enrichment entrypoint. Only construct the hardware YAML path after
validation, preserving the existing error-and-exit behavior for invalid slugs
and missing files.

In `@scripts/generate-context.ts`:
- Around line 282-285: Update the rowPosition documentation in the generated
context description to use the source convention’s single, unambiguous axis;
remove the “front-to-back” wording and explicitly define row order consistently
for all edge orientations, including Top/Bottom. Keep the columnPosition and
single-row guidance aligned with this convention.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b076638-3f36-4805-8693-b7be2c7f1c3c

📥 Commits

Reviewing files that changed from the base of the PR and between f87ec25 and 4e40606.

📒 Files selected for processing (7)

• .changeset/io-positions-enrichment.md
• CLAUDE.md
• data/hardware/eventide-audio-h90-harmonizer.yaml
• package.json
• schema/CONTEXT.md
• scripts/enrich-io.ts
• scripts/generate-context.ts