Manifest adapter: publish non-Gleam packages (AI skill / plugin marketplaces)

[tylerbutler]

Motivation

Trellis's most valuable subsystems — the changelog engine (fragments, version plan/apply, ripple), tag machinery (exact + moving series tags, GitHub Releases), release pr, the scheduler, and ci matrix/outputs — are language-agnostic in their logic. And the git_only lifecycle already is the publishing model for registry-less package types: changelog → version → tag → GitHub Release.

The concrete motivating case is AI skill / Claude Code plugin marketplace repos: a root marketplace.json index over plugins/* directories, each with a .claude-plugin/plugin.json carrying name and version, consumed via git refs. The index duplicates member versions — exactly the drift trellis exists to prevent ("Configure nothing that can be derived. Verify anything that must be duplicated.").

The only hard coupling to Gleam is the manifest seam: discovery (gleam.toml presence), identity (name/version fields), dependency edges (path deps), and version write-back all assume one file format.

Proposal: a declarative manifest adapter

No plugin system, no registry backends. A small config table that redefines the manifest seam; everything downstream reuses existing code.

Target repo shape

my-marketplace/
├── trellis.toml                        # config home — no gleam.toml to live in
├── .claude-plugin/
│   └── marketplace.json                # the index: { plugins: [{name, source, version, …}] }
└── plugins/
    ├── code-reviewer/
    │   ├── .claude-plugin/plugin.json  # { "name": "code-reviewer", "version": "1.2.0", … }
    │   ├── commands/…
    │   └── skills/…
    └── deploy-helper/
        └── .claude-plugin/plugin.json

Config sketch

# trellis.toml — same [tools.trellis] table, new home. Root discovery walks up
# to the first gleam.toml OR trellis.toml carrying the table.
[tools.trellis]
members = ["plugins/*"]

[tools.trellis.adapter]
# The manifest's presence marks a member (replaces "has a gleam.toml"),
# relative to the member dir. Format derived from extension: .json/.toml/.yaml.
manifest = ".claude-plugin/plugin.json"
name = "name"          # dotted path into the manifest
version = "version"    # dotted path; version apply does a surgical edit here
# no `deps` key → flat graph. Graph consumers degrade cleanly: topo order =
# member order, ripple bumps never fire, path-dep rewrite is a no-op.

[tools.trellis.publish.lifecycle]
default = "git_only"   # no registry; `hex` under an adapter is a doctor error

# Version sync — modeled on the existing manifest.toml lock-patching:
# surgical, not templated, so hand-written fields (description, owner,
# category) are never touched. `files` is a glob. A rule with entries/match
# is index-shaped: walk to the array at `entries`, find the element whose
# `match` field equals the member's name, write into it. A rule without
# them is direct-shaped: each matched file is one object belonging to the
# member whose directory contains it.
[tools.trellis.adapter]
sync = [
  {
    files = "**/marketplace.json",
    entries = "plugins",              # path to the array of entries
    match = "name",                   # entry field ↔ member's name
    sync = { version = "version" },   # index field ← member manifest path
  },
]

[tools.trellis.publish]
package_tags = ["exact", "major"]          # moving v1 tags are the pinning
exact_tag_format = "{name}-v{version}"     # story for git-ref marketplace
series_tag_format = "{name}-v{series}"     # consumers

Behavior per subsystem under an adapter

Subsystem	Behavior
Discovery, list, ci matrix	Unchanged — glob + manifest presence
Changelog, version plan/apply	Unchanged, plus: bump writes to the adapter's version path, then patches files matched by sync rules
tag, release pr, GitHub Releases	Unchanged verbatim
run built-ins	Absent — custom [tools.trellis.tasks] only
publish, lockfile	Refused (exit 2) — git_only tops out the lifecycle
Idempotency	Already covered: tag plan computes "current version not yet tagged"
doctor	Drops gleam checks; adds: manifest parses, name matches directory, every index entry resolves to a member, every releasable member has an index entry, index version matches manifest (fixable, like stale locks today)

A release, end to end

trellis changelog new --package code-reviewer --kind Added --body "Support monorepo diffs"
trellis version apply        # plugin.json 1.2.0→1.3.0, marketplace.json patched, CHANGELOG rendered
trellis tag create --push --github-release   # code-reviewer-v1.3.0 (immutable) + code-reviewer-v1 (moved)

New surface required

1. trellis.toml as an alternative config home (root discovery change)
2. The four-key [tools.trellis.adapter] table
3. Surgical version edits for JSON and YAML (TOML exists)
4. The sync rules + matching doctor checks

Everything else is reuse.

Note: the multi-line inline tables in the sync array assume TOML 1.1 (released 2025-12). Verified empirically: toml = "1.1.2" parses them and toml_edit = "0.25.12" round-trips edits preserving formatting — both already pinned in Cargo.toml. Users whose editor/linter TOML tooling still targets 1.0 may see false syntax errors in their config; trellis itself is fine.

Deliberately out of scope (for now)

• Registry backends beyond Hex — git_only covers the motivating case
• Artifact packaging (zip a plugin dir onto the GitHub Release) — possible follow-up for archive-consuming marketplaces
• Adapter-declared dependency edges (e.g. package.json workspace deps) — flat graph only in v1
• Standalone skills as members. Skills version through their containing plugin's plugin.json; SKILL.md frontmatter needs no version field of its own, so no frontmatter parsing is required.

Open questions

1. One adapter per workspace, or per-glob? Sketch says per-workspace. Mixed repos (Gleam packages + a plugins/ dir) would need adapters = [{members = [...], …}] — deferred; it's the feature that turns four keys into a subsystem.
2. Positioning. This makes "A workspace CLI for Gleam monorepos" inexact. Cheapest honest framing: Gleam stays the native, batteries-included ecosystem; the adapter is the escape hatch. (Also touches the trellis-gleam crate name.)

[tylerbutler]

Worked example: APM (Agent Package Manager)

microsoft/apm is a dependency manager for AI agent context (skills, prompts, instructions, MCP servers). It validates the adapter design almost exactly — and stresses it in one interesting place.

What an APM package is

A directory with an apm.yml manifest and a .apm/ source tree (skills, prompts, instructions, agents, hooks). The manifest requires exactly two fields — name and a SemVer version (package anatomy):

name: my-pkg
version: 1.0.0
dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0

There is no registry: packages are distributed as git repos, consumers pin git tags (owner/repo#v1.0.0), and apm.lock.yaml pins resolved commits and content hashes.

Adapter config for an APM monorepo

# trellis.toml
[tools.trellis]
members = ["packages/*"]

[tools.trellis.adapter]
manifest = "apm.yml"       # YAML — the concrete case behind YAML manifest support
name = "name"
version = "version"

[tools.trellis.publish.lifecycle]
default = "git_only"       # APM consumes git tags; nothing to publish beyond them

[tools.trellis.publish]
package_tags = ["exact"]
exact_tag_format = "{name}-v{version}"   # consumers pin repo#my-pkg-v1.0.0

Release flow is unchanged trellis: fragment → version apply bumps apm.yml → tag create --push --github-release. APM's #ref syntax accepts any git ref, so per-package {name}-v{version} tags work for a multi-package repo, and the lockfile's commit pinning makes them safe.

APM is simpler than the Claude marketplace case: no root index file, so the adapter.index sync block isn't needed. Four adapter keys plus existing lifecycle/tag settings cover it.

Where APM stresses the design

APM dependencies are git refs, not path deps. In a monorepo where sibling package B depends on sibling A, B's manifest pins owner/repo#a-v1.2.0 — a ref to its own repository. That's duplicated, drifting state of exactly the kind trellis targets: when A releases 1.3.0, B's pin should advance and B should ripple-bump — the git-ref analog of the Hex path-dep rewrite. Supporting it needs the deferred item above (adapter-declared dependency edges: a deps path in the manifest plus recognition that a ref points at a workspace sibling) and a rewrite step at tag time.

For v1's flat graph, a cheap middle ground: doctor warns when a workspace-internal ref pins a version that doesn't match the sibling's current manifest version.

Smaller notes:

• APM has its own scripts block run via apm run <name> — trellis custom tasks can wrap apm install / apm compile for CI; no built-ins needed, as designed.
• Doctor's adapter checks (manifest parses, name matches directory, valid semver) apply as-is.

[tylerbutler]

Worked example: tylerbutler/agent-marketplace (Claude Code plugin marketplace)

This is the motivating layout from the issue body, checked against the real repo — which turns out to be messier than the sketch in ways that sharpen the design, and which contains live drift that makes the doctor case concrete.

What's actually in the repo

Five plugin dirs (base, fff, gleam, repo-tools, workflows) under plugins/, plus:

• Two marketplace indexes: .claude-plugin/marketplace.json (Claude Code) and a root marketplace.json (Copilot CLI).
• Two copies of each plugin manifest: .claude-plugin/plugin.json and a top-level plugin.json per plugin.

So each plugin's version lives in four places: two manifests + an entry in each index. All are at 0.1.0 today, so version drift hasn't bitten yet — it will on the first real release.

Drift that exists right now

• The two indexes disagree: .claude-plugin/marketplace.json lists six plugins including specialists, and plugins/specialists does not exist. The root index correctly lists five.
• The duplicate manifests have already diverged: plugins/base/plugin.json has an mcpServers key its .claude-plugin/plugin.json twin lacks.

Both are exactly the checks proposed for doctor, failing in the wild before trellis exists.

Sibling deps

None — Claude plugins have no inter-plugin dependency concept and none of these reference each other. The v1 flat graph holds (same as the APM example above).

Design change: glob-based sync rules

A single index-sync table isn't enough for this repo (two indexes + mirrored member manifests). Rather than listing four targets, sync rules take a glob, and the presence of entries/match distinguishes the two write shapes — no mode flag:

[tools.trellis.adapter]
manifest = ".claude-plugin/plugin.json"   # canonical manifest; version apply writes here
name = "name"
version = "version"

# Direct shape (no entries/match): each matched file is one object
# describing one package, resolved to the member whose directory contains
# it; a match outside any member is a doctor error (no version to write).
# Index shape (entries/match present): each matched file describes all
# packages — walk to the array at `entries`, find the element whose
# `match` field equals the member's name, write into that element.
sync = [
  { files = "plugins/*/plugin.json", sync = { version = "version" } },
  {
    files = "**/marketplace.json",
    entries = "plugins",
    match = "name",
    sync = { version = "version" },
  },
]

Globs fit trellis idiom — members, exclude, and package_tags_overrides are already glob-keyed. The multi-line inline tables assume TOML 1.1; the pinned toml 1.1.2 and toml_edit 0.25.12 both handle them (verified: parse + format-preserving surgical edit).

Doctor rules that fall out

• A sync glob matching zero files → warning (typo protection, same as task-exclusion globs).
• A direct-shape match outside any member directory → error.
• An index entry naming no member → error (catches the specialists ghost today).
• Synced fields disagreeing with the canonical manifest → fixable finding, like stale manifest.toml locks.

The issue body's sync section has been updated to this shape: the index case is just a sync rule with entries/match.