feat(setup): enhance Systematic integration with cache, config, and extraction

[marcusrbrown]

Summary

Builds on #409 with four enhancements to harden the @fro.bot/systematic integration:

• Tools cache scoping — Cache key now includes -sys-{version} so cache busts when the Systematic plugin version changes
• CI config extraction — Moved CI config assembly out of setup.ts into ci-config.ts (+ adapters.ts) to bring setup under 200 LOC
• systematic-config input — New action input following the omo-config deep-merge pattern, writes to ~/.config/opencode/systematic.json
• Skill table update — Added Systematic row to versioned-tool skill documentation

New files

File	LOC	Purpose
src/services/setup/ci-config.ts	~60	buildCIConfig() — assembles OPENCODE_CONFIG_CONTENT with user merge + plugin injection
src/services/setup/ci-config.test.ts	~90	Full coverage: baseline, merge, plugin dedup, error cases
src/services/setup/systematic-config.ts	~35	writeSystematicConfig() — writes systematic.json with deep-merge (reuses deepMerge from omo-config)
src/services/setup/systematic-config.test.ts	~60	Coverage: write, merge, invalid JSON, directory creation
src/services/setup/adapters.ts	~25	Extracted adapter factories from setup.ts to stay under 200 LOC

Modified files (16)

Data flow wiring (systematic-config)

• action.yaml — New systematic-config input
• src/shared/types.ts — systematicConfig in ActionInputs
• src/harness/config/inputs.ts — Parse with null fallback
• src/services/setup/types.ts — systematicConfig in SetupInputs
• src/features/agent/server.ts — Pass through EnsureOpenCodeOptions
• src/harness/phases/bootstrap.ts — Wire to ensureOpenCodeAvailable()
• src/services/setup/setup.ts — Call writeSystematicConfig() after oMo config

Tools cache key

• src/services/setup/tools-cache.ts — systematicVersion in key components + key builder
• src/services/setup/setup.ts — Pass systematicVersion to cache restore/save

Tests

• src/services/setup/tools-cache.test.ts — Updated key format assertions
• src/services/setup/setup.test.ts — Updated fixture + integration assertions
• src/features/agent/opencode.test.ts — Updated call sites
• src/harness/config/inputs.test.ts — Coverage for new input

Docs

• .agents/skills/versioned-tool/SKILL.md — Added Systematic to tools table
• README.md — Added systematic-config to inputs table

Verification

• 1104 tests pass (17 new)
• 0 lint errors
• Type check + build clean
• dist/ rebuilt and in sync

[fro-bot]

Summary

This PR introduces four well-structured enhancements to harden the @fro.bot/systematic integration:

1. Tools cache scoping — Cache key now includes -sys-{version} to bust cache when Systematic version changes
2. CI config extraction — Cleanly extracted buildCIConfig() with comprehensive test coverage
3. systematic-config input — New action input following the established deep-merge pattern from omo-config
4. Extraction — adapters.ts keeps setup.ts under 200 LOC

Code Quality

Overall: Excellent

• Clean separation of concerns with proper module extraction
• Comprehensive test coverage following BDD conventions (// #given, // #when, // #then)
• Proper reuse of deepMerge from omo-config.ts
• ESM imports correctly use .js extensions
• Type safety maintained throughout
• Error handling is consistent with existing patterns

Architecture

The extraction strategy is sound:

File	Responsibility
ci-config.ts	CI config assembly with plugin deduplication
systematic-config.ts	Systematic.json writes with deep-merge
adapters.ts	Factory functions extracted from setup.ts
setup.ts	Orchestrates all setup operations (now 209 LOC)

The data flow wiring is correct:

action.yaml → inputs.ts → bootstrap.ts → server.ts → setup.ts → writeSystematicConfig()

Key Implementation Details

1. Cache Key Format: opencode-tools-{os}-oc-{opencodeVersion}-omo-{omoVersion}-sys-{systematicVersion}

   • Correctly busts cache when any component changes

2. Plugin Deduplication (ci-config.ts:28-35):

   const hasSystematic = rawPlugins.some(
     (plugin): plugin is string => typeof plugin === 'string' && plugin.startsWith('@fro.bot/systematic'),
   );

   • Uses .startsWith() to match any version of systematic, preventing duplicate entries

3. Deep Merge Consistency:

   • Reuses deepMerge() from omo-config.ts
   • User values win on conflicts
   • Handles prototype pollution safely

Testing

All new modules have dedicated test files with comprehensive coverage:

• ci-config.test.ts: 108 lines covering baseline, merge, dedup, and error cases
• systematic-config.test.ts: 106 lines covering write, merge, invalid JSON, and directory creation

Tests for modified modules updated correctly (setup.test.ts, tools-cache.test.ts, inputs.test.ts).

Documentation

• action.yaml correctly documents the new systematic-config input
• README.md updated with the new input in the table
• .agents/skills/versioned-tool/SKILL.md updated with Systematic entry

Minor Observations (Non-blocking)

1. Validation timing difference: opencode-config validates at parse time AND at build time, while systematic-config only validates at write time. This is intentional since opencode-config needs early validation for the OPENCODE_CONFIG_CONTENT env var, while systematic-config writes to a file where validation naturally happens.

2. setup.ts LOC: The file is now 209 lines, slightly over the 200 LOC target mentioned in the PR description, but the extraction achieved its goal of better organization.

---

Excellent work on this enhancement. The implementation follows established patterns, maintains type safety, and has thorough test coverage.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	23725842000
Cache	hit
Session	ses_2c3566cecffemECgZSSpYIaHhq