Skip to content

feat(cartridge): scaffolder for boj-server cartridge skeletons (stand…#29

Closed
hyperpolymath wants to merge 1 commit into
mainfrom
add-cartridge-scaffolder
Closed

feat(cartridge): scaffolder for boj-server cartridge skeletons (stand…#29
hyperpolymath wants to merge 1 commit into
mainfrom
add-cartridge-scaffolder

Conversation

@hyperpolymath
Copy link
Copy Markdown
Owner

…ards#89 Phase 2b)

Adds iseriser cartridge --manifest <toml> --output <dir> which emits a complete boj-server cartridge skeleton at <output>/<iser>-mcp/:

-mcp/
├── README.adoc cartridge overview + build
├── cartridge.json registration manifest
├── mod.js JS-worker fallback path
├── panels/manifest.json observability panel registration
├── abi/
│ ├── README.adoc
│ ├── -mcp.ipkg Idris2 package
│ └── Mcp/Safe.idr exposure-gate contract + tools
├── ffi/
│ ├── README.adoc
│ ├── build.zig shared-shim wiring
│ └── _ffi.zig ADR-0006 5-symbol C-ABI
└── adapter/
├── README.adoc
├── build.zig
└── _adapter.zig unified gated adapter (4-protocol)

The cartridge is meant to be placed inside boj-server/cartridges/; the emitted Zig build files reference the shared invoke-shim at boj-server/ffi/zig/src/cartridge_shim.zig via ../../../.

Modelled on the k9iser-mcp pilot (boj-server#73). Skeleton-only: the exposure/transaction gate, the 5-symbol ABI plumbing, and the unified 4-protocol adapter are all production-ready; per-tool dispatch bodies are stubs ready for replacement.

Verified end-to-end against the actual boj-server tree:

  • zig build test on emitted ffi/ → 4/4 tests pass
  • zig build test on emitted adapter/ → 5/5 tests pass
  • idris2 --build on emitted .ipkg → SafeChapeliser type-checks (RC=0)
  • cargo test: 57 unit + 9 integration green (8 new tests added)
  • zig fmt --check on all emitted .zig files: clean
  • cartridge.json + panels/manifest.json parse as valid JSON

Two pilot-vs-scaffold deltas worth noting:

  • The pilot .ipkg ships depends = base, contrib which is invalid in Idris2 0.8.0 (parser stops at the comma). The scaffold emits depends = base to compile cleanly; contrib can be added on a separate depends line when actually needed.
  • The pilot's per-tool bodies (k9_load_manifest, k9_generate, ...) are k9iser-specific. The scaffold emits one example tool (<iser>_generate) plus a status panel; expand as the cartridge grows.

Refs hyperpolymath/standards#89, #90

🤖 Generated with Claude Code

Summary

Changes

RSR Quality Checklist

Required

  • Tests pass (just test or equivalent)
  • Code is formatted (just fmt or equivalent)
  • Linter is clean (no new warnings or errors)
  • No banned language patterns (no TypeScript, no npm/bun, no Go/Python)
  • No unsafe blocks without // SAFETY: comments
  • No banned functions (believe_me, unsafeCoerce, Obj.magic, Admitted, sorry)
  • SPDX license headers present on all new/modified source files
  • No secrets, credentials, or .env files included

As Applicable

  • .machine_readable/STATE.a2ml updated (if project state changed)
  • .machine_readable/ECOSYSTEM.a2ml updated (if integrations changed)
  • .machine_readable/META.a2ml updated (if architectural decisions changed)
  • Documentation updated for user-facing changes
  • TOPOLOGY.md updated (if architecture changed)
  • CHANGELOG or release notes updated
  • New dependencies reviewed for license compatibility (PMPL-1.0-or-later / MPL-2.0)
  • ABI/FFI changes validated (src/interface/abi/ and src/interface/ffi/ consistent)

Testing

Screenshots

…ards#89 Phase 2b)

Adds `iseriser cartridge --manifest <toml> --output <dir>` which emits a
complete boj-server cartridge skeleton at `<output>/<iser>-mcp/`:

  <iser>-mcp/
  ├── README.adoc                            cartridge overview + build
  ├── cartridge.json                         registration manifest
  ├── mod.js                                 JS-worker fallback path
  ├── panels/manifest.json                   observability panel registration
  ├── abi/
  │   ├── README.adoc
  │   ├── <iser>-mcp.ipkg                    Idris2 package
  │   └── <Iser>Mcp/Safe<Iser>.idr           exposure-gate contract + tools
  ├── ffi/
  │   ├── README.adoc
  │   ├── build.zig                          shared-shim wiring
  │   └── <iser>_ffi.zig                     ADR-0006 5-symbol C-ABI
  └── adapter/
      ├── README.adoc
      ├── build.zig
      └── <iser>_adapter.zig                 unified gated adapter (4-protocol)

The cartridge is meant to be placed inside `boj-server/cartridges/`; the
emitted Zig build files reference the shared invoke-shim at
`boj-server/ffi/zig/src/cartridge_shim.zig` via `../../../`.

Modelled on the k9iser-mcp pilot (boj-server#73).  Skeleton-only: the
exposure/transaction gate, the 5-symbol ABI plumbing, and the unified
4-protocol adapter are all production-ready; per-tool dispatch bodies
are stubs ready for replacement.

Verified end-to-end against the actual boj-server tree:
- `zig build test` on emitted ffi/   → 4/4 tests pass
- `zig build test` on emitted adapter/ → 5/5 tests pass
- `idris2 --build` on emitted .ipkg → SafeChapeliser type-checks (RC=0)
- `cargo test`: 57 unit + 9 integration green (8 new tests added)
- `zig fmt --check` on all emitted .zig files: clean
- `cartridge.json` + `panels/manifest.json` parse as valid JSON

Two pilot-vs-scaffold deltas worth noting:
- The pilot `.ipkg` ships `depends = base, contrib` which is invalid in
  Idris2 0.8.0 (parser stops at the comma).  The scaffold emits
  `depends = base` to compile cleanly; `contrib` can be added on a
  separate `depends` line when actually needed.
- The pilot's per-tool bodies (k9_load_manifest, k9_generate, ...) are
  k9iser-specific.  The scaffold emits one example tool
  (`<iser>_generate`) plus a status panel; expand as the cartridge grows.

Refs hyperpolymath/standards#89, #90

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hyperpolymath
Copy link
Copy Markdown
Owner Author

Closing as superseded. Branch tip (feat(cartridge): scaffolder for boj-server cartridge skeletons (standards#89 Phase 2b)) duplicates #24 which is already on main. Re-diff vs current main shows this branch would actually revert #25's depends = base, contrib fix back to depends = base — a regression. The intended feature is on main.

@hyperpolymath hyperpolymath deleted the add-cartridge-scaffolder branch May 21, 2026 07:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant