mirror of
https://github.com/github/spec-kit.git
synced 2026-07-03 20:36:23 +08:00
b7e67f55bf
* Add community bundle submission path * Address bundle submission review feedback * Align bundle submission triage label * Clarify bundle submission review scope * Clarify community bundle catalog listing
163 lines
9.4 KiB
Markdown
163 lines
9.4 KiB
Markdown
# Bundles
|
|
|
|
Bundles compose existing Spec Kit components — extensions, presets, workflows, and steps — into a single, versioned, installable unit. Where extensions and presets are primitives, a bundle is a curated stack that declares everything a team or role needs and installs it in one step through each component's own machinery. Bundles add no new runtime behavior of their own: they are a distribution and composition layer over the primitives you already use.
|
|
|
|
A bundle is described by a `bundle.yml` manifest and is discovered through the same catalog stack as other components. Installing a bundle resolves its declared components against pinned versions, checks for the single cross-bundle conflict point (the active integration), and applies each component idempotently with full provenance tracking so it can be cleanly removed or refreshed later.
|
|
|
|
## Search Available Bundles
|
|
|
|
```bash
|
|
specify bundle search [query]
|
|
```
|
|
|
|
| Option | Description |
|
|
| ----------- | ---------------------------- |
|
|
| `--offline` | Do not access the network |
|
|
| `--json` | Emit machine-readable JSON |
|
|
|
|
Searches all active catalogs for bundles matching the query. Without a query, lists every available bundle with its version, role, source, and a trust indicator (`verified` for org-curated catalog entries, `community` otherwise) so you can judge trust before installing.
|
|
|
|
## Bundle Info
|
|
|
|
```bash
|
|
specify bundle info <bundle_id>
|
|
```
|
|
|
|
| Option | Description |
|
|
| ------------ | --------------------------------- |
|
|
| `--offline` | Do not access the network |
|
|
| `--json` | Emit machine-readable JSON |
|
|
|
|
Shows full metadata for a bundle along with the **fully expanded component set** it installs — every extension, preset, step, and workflow with its pinned version, plus preset priority and strategy. The output also includes a trust indicator (`verified` vs `community`) so you can judge trust before installing. This preview is the same plan `install` applies, so you can see exactly what will be added before committing. Foreseeable overlaps with components already provided by installed bundles are surfaced here as well.
|
|
|
|
## Install a Bundle
|
|
|
|
```bash
|
|
specify bundle install <bundle_id | path>
|
|
```
|
|
|
|
| Option | Description |
|
|
| ---------------- | ------------------------------------------------------------------ |
|
|
| `--integration` | Override the integration used when initializing/installing |
|
|
| `--offline` | Do not access the network |
|
|
|
|
Installs a bundle's full component set through each primitive's machinery. The argument may be a catalog bundle id, or a local path to a built `.zip` artifact, a bundle directory, or a `bundle.yml` file; local sources install directly without consulting the catalog stack.
|
|
|
|
If the current directory is not yet a Spec Kit project, `install` initializes one first so a fresh checkout reaches a working state in a single command. `--integration` selects the integration when initializing a new project, and confirms the target when a bundle pins a specific integration but the project's active integration can't be determined (missing or unreadable `.specify/integration.json`). It does **not** override an already-initialized project's active integration: if a bundle targets a different integration than the project's, install aborts with no changes. Integration-agnostic bundles inherit the project's active integration. Installation is idempotent — components already present are skipped. On failure, no provenance record is written (a failed install records nothing), and the components installed during that run are removed on a best-effort basis — removal errors are swallowed, so partial on-disk state may remain.
|
|
|
|
## Update Bundles
|
|
|
|
```bash
|
|
specify bundle update [<bundle_id>]
|
|
```
|
|
|
|
| Option | Description |
|
|
| ------------ | ------------------------------------ |
|
|
| `--all` | Update every installed bundle |
|
|
| `--offline` | Do not access the network |
|
|
|
|
Re-resolves a bundle and **refreshes** its components through each primitive's update path, bringing already-installed components up to the bundle's newly pinned versions while preserving primitive-level overrides (such as preset priority). Provide a bundle id, or use `--all` to update everything installed.
|
|
|
|
> **Pin enforcement is install-time only.** Idempotency checks are id-based, not version-aware: a component that is already present is skipped during `install` without comparing its on-disk version to the manifest pin. Version pins are therefore guaranteed to be applied only when the bundler actually installs a component for the first time or refreshes it. Run `specify bundle update` to re-apply every owned component at its pinned version.
|
|
|
|
## Remove a Bundle
|
|
|
|
```bash
|
|
specify bundle remove <bundle_id>
|
|
```
|
|
|
|
Uninstalls only the components this bundle contributed, leaving any component that another installed bundle still needs in place (no collateral removals).
|
|
|
|
## List Installed Bundles
|
|
|
|
```bash
|
|
specify bundle list
|
|
```
|
|
|
|
| Option | Description |
|
|
| -------- | ---------------------------- |
|
|
| `--json` | Emit machine-readable JSON |
|
|
|
|
Lists the bundles installed in the project with their versions, component counts, and install timestamps.
|
|
|
|
## Initialize a Project with a Bundle
|
|
|
|
```bash
|
|
specify bundle init [<bundle_id>]
|
|
```
|
|
|
|
| Option | Description |
|
|
| ---------------- | ---------------------------------------- |
|
|
| `--integration` | Integration override |
|
|
| `--offline` | Do not access the network |
|
|
|
|
Ensures the current directory is a Spec Kit project (initializing it idempotently if needed), then optionally installs the given bundle. Useful as an explicit one-step bootstrap for a new checkout.
|
|
|
|
## Validate a Bundle
|
|
|
|
```bash
|
|
specify bundle validate
|
|
```
|
|
|
|
| Option | Description |
|
|
| ------------ | ------------------------------------------------------------------- |
|
|
| `--path` | Bundle directory or `bundle.yml` (default: current directory) |
|
|
| `--offline` | Verify references against bundled/installed components only |
|
|
|
|
Reports whether a `bundle.yml` is well-formed and whether every declared component reference resolves. References are checked against bundled components, the project's installed components, and — when online — the active catalogs. Validation fails only when a reference is definitively absent everywhere it could be checked: that is, when an active catalog is reachable and confirms the component is missing. References that cannot be verified — because validation is offline, or because a catalog is unreachable — are downgraded to warnings so authoring can continue, rather than failing the run.
|
|
|
|
## Build a Bundle Artifact
|
|
|
|
```bash
|
|
specify bundle build
|
|
```
|
|
|
|
| Option | Description |
|
|
| ----------- | ------------------------------------------------------- |
|
|
| `--path` | Bundle directory (default: current directory) |
|
|
| `--output` | Output directory for the artifact |
|
|
|
|
Produces a single versioned, distributable `.zip` artifact from a bundle directory. The artifact embeds the manifest and can be installed directly with `specify bundle install <artifact.zip>`.
|
|
|
|
## Publish a Bundle
|
|
|
|
Bundle authors validate and package bundles locally, then host the generated artifact and catalog metadata where users can access it. A bundle catalog entry points at the bundle artifact, but the components declared inside `bundle.yml` still resolve through bundled components, installed components, or active extension, preset, workflow, and step catalogs.
|
|
|
|
If your bundle references components from non-default catalogs, document those catalog URLs and test the install path from a clean project with those catalogs added. Community bundle submissions should include that dependency-resolution evidence in the [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue.
|
|
|
|
## Manage Catalog Sources
|
|
|
|
Bundles are discovered through a priority-ordered stack of catalog sources (project, user, and built-in scopes).
|
|
|
|
### List the Catalog Stack
|
|
|
|
```bash
|
|
specify bundle catalog list
|
|
```
|
|
|
|
Prints the active, priority-ordered catalog stack with each source's scope and install policy.
|
|
|
|
### Add a Catalog Source
|
|
|
|
```bash
|
|
specify bundle catalog add <url>
|
|
```
|
|
|
|
| Option | Description |
|
|
| ------------- | ------------------------------------------------------- |
|
|
| `--policy` | `install-allowed` or `discovery-only` |
|
|
| `--priority` | Source priority (lower = higher precedence; default 10) |
|
|
| `--id` | Explicit source id |
|
|
|
|
Registers a project-scoped catalog source and persists it.
|
|
|
|
### Remove a Catalog Source
|
|
|
|
```bash
|
|
specify bundle catalog remove <id_or_url>
|
|
```
|
|
|
|
Removes a project-scoped catalog source. Built-in default sources cannot be deleted.
|
|
|
|
> **Note:** `search` and `info` work anywhere — with no project they fall back to the built-in/user catalog stack. The remaining state-changing commands (`list`, `update`, `remove`, `catalog`) require a project already initialized with `specify init`. `install` and `init` will initialize a project on demand when run in an uninitialized directory.
|