Support multi-plugin repositories with a collection manifest

[galligan]

Problem

A bb plugin package manifest describes exactly one plugin, and a direct git: install currently treats the repository root as that plugin's root. This effectively requires either:

• one repository per plugin, or
• publishing every plugin package to npm before it can be installed remotely.

That is awkward for teams that develop several related plugins in one Bun/npm/pnpm workspace alongside shared tooling, docs, fixtures, and design apps.

Claude Code marketplaces provide useful prior art: a repository-level .claude-plugin/marketplace.json lists multiple independently installable plugins and points each entry at a relative directory within the repository.

Proposal

Support an optional repository-level bb plugin collection manifest, for example .bb/plugins.json:

{
  "$schema": "https://getbb.dev/schemas/plugins.schema.json",
  "schemaVersion": 1,
  "name": "galligan-bb-plugins",
  "plugins": [
    {
      "name": "agent-sidebar",
      "source": "./plugins/agent-sidebar"
    },
    {
      "name": "gitbutler-status",
      "source": "./plugins/gitbutler-status"
    }
  ]
}

Each source directory would remain a complete, ordinary bb plugin package with its own package.json and bb manifest. The repository manifest is only an index; it should not duplicate or override the package manifest's identity, compatibility, branding, or entry points.

A possible CLI shape:

bb plugin install git:https://github.com/galligan/bb-workbench.git@main --plugin agent-sidebar

The exact command syntax is open for discussion. A lower-level --subdirectory plugins/agent-sidebar option could provide the underlying primitive, while --plugin resolves a named entry from the repository manifest.

Expected behavior

• One Git or local repository can contain multiple independently installable plugins.
• Installation selects one plugin rather than enabling the whole collection.
• Relative sources resolve from the repository root.
• Each selected directory is validated using the existing plugin package-manifest rules.
• Installed provenance retains the repository URL, requested ref, resolved commit, and plugin subdirectory so outdated, update, rollback, and status continue to work.
• A repository/commit is cloned or cached once when practical, even if several plugins from it are installed.
• Private repositories continue to use the existing Git credential flow.
• Local development works with the same collection manifest as remote Git installation.

Safety requirements

• Reject absolute paths, empty paths, .. traversal, and symlinks that resolve outside the checked-out repository.
• Reject duplicate collection entry names and conflicting plugin IDs.
• Do not allow collection metadata to weaken engines.bb, engines.bbPluginSdk, artifact metadata, or existing managed-install validation.
• A broken entry should fail independently without invalidating already-installed sibling plugins.

npm compatibility

This should complement, not replace, the existing npm installation path:

bb plugin install npm:bb-plugin-agent-sidebar@^1.0.0

Monorepos should still be able to publish individual workspace packages to npm. The repository manifest would mainly improve Git/local distribution, discovery, and development before or without npm publication.

Implementation note

The plugin persistence/update model already carries a Git subdirectory field, while direct Git installs currently record the subdirectory as null. That appears to provide some groundwork for retaining subdirectory provenance.

Acceptance criteria

• Document and validate a versioned repository-manifest schema.
• Install a named plugin whose package lives below the repository root.
• Add coverage for local paths, Git refs/commits, update checks, rollback, private-source behavior, and path traversal/symlink escapes.
• Document how repository collections relate to standalone Git packages, npm packages, and bb's official bundled plugin catalog.

Prior art

Claude Code's repository marketplace manifest supports a plugins array with relative source paths, an optional shared pluginRoot, and dedicated Git-subdirectory sources:

https://code.claude.com/docs/en/plugin-marketplaces

[SawyerHood]

Will make sure to get to this. At one point there was code for an entire marketplace system but I removed it because no one had a use for it, but now is the time to add it back!

[galligan]

@SawyerHood Awesome, thanks! While we're at it, one more concrete use case for this came out of building Plugin Studio: discovering source plugins inside projects that are already configured in bb. Note: Plugin Studio is bb-mate evolved, and more deeply integrated to bb …which I'm putting the "finishing" touches on now!

Right now Studio has to infer those plugins from the package.json files. We’ve made that bounded and safe, but supporting all the different things we might need to account for adds a lot complexity.

Having something dedicated, like a .bb/plugins.json manifest could dramatically simplify discovery, along the lines of the marketplace system you're alluding to. Example:

{
  "$schema": "https://getbb.dev/schemas/plugins.schema.json",
  "schemaVersion": 1,
  "name": "my-plugin-collection",
  "plugins": [
    {
      "name": "linear",
      "source": "./plugins/linear"
    },
    {
      "name": "plugin-studio",
      "source": "./plugins/studio"
    }
  ]
}

Studio could read the collection manifest from each configured project root (or nested sources since it's specific), inspect only those directories, and continue treating each plugin’s existing package.json bb manifest as authoritative. In the example it's just a lightweight index and would not duplicate plugin metadata, compatibility requirements, branding, or entry points. Could be useful for:

• discovering local source plugins during development;
• installing individual plugins from multi-plugin repositories; and
• eventually presenting repository or team plugin catalogs.

For now we'll keep the bounded workspace scanning in the Plugin Studio but consider this a vote for some sort of manifest file!

[SawyerHood]

I'm tackling this, marketplaces, and publishing the SDK right now!