From f703a537a0f1709fea8164d3f7aab74853b72be5 Mon Sep 17 00:00:00 2001 From: Peter Krenesky Date: Sat, 27 Jun 2026 09:00:01 -0700 Subject: [PATCH 1/2] spec: FR-024 plugin/catalog library-API + shared-store contract Formalize quoin's exported plugin install/list/remove + catalog-loading API as a stable contract, and record the shared ~/.ix/filament store + ts-plugin-kit source model as the cross-tool interop contract (filament-ide interoperates over the store rather than importing quoin). Add the FR to spec.md's Plugins index. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../FR-024-plugin-catalog-library-api.md | 63 +++++++++++++++++++ spec/spec.md | 1 + 2 files changed, 64 insertions(+) create mode 100644 spec/functional/FR-024-plugin-catalog-library-api.md diff --git a/spec/functional/FR-024-plugin-catalog-library-api.md b/spec/functional/FR-024-plugin-catalog-library-api.md new file mode 100644 index 0000000..025f291 --- /dev/null +++ b/spec/functional/FR-024-plugin-catalog-library-api.md @@ -0,0 +1,63 @@ +--- +id: FR-024 +title: "Expose plugin and catalog operations as a stable library API" +relationships: + - target: "ix://agent-ix/quoin/StR-003" + type: "traces_to" + - target: "ix://agent-ix/quoin/US-003" + type: "implements" +type: FR +--- + +# FR-024: Expose plugin and catalog operations as a stable library API + +## Description + +The package SHALL export its plugin install/list/remove and catalog-loading +operations — `installPlugin`, `listPlugins`, `removePlugin`, `parseSourceArg`, +`loadCatalog`, and `filamentModulesDir` — as a stable, semver-governed library API +from `@agent-ix/quoin`, so that other Node tools can manage and read the same +shared plugin store (`~/.ix/filament/registry.json` and `~/.ix/filament/modules/`) +identically to the `quoin` CLI, in service of +[StR-003](../stakeholder/StR-003-shared-catalog.md). + +The durable cross-tool contract is the **shared store layout** plus the +`@agent-ix/ts-plugin-kit` source/registry model: a consumer may either import this +library (Node tools) or interoperate at the store level over the same registry and +module directories (as filament-ide does, to avoid pulling quoin's CLI dependency +tree into a desktop bundle). Either way an install/removal by one tool is observed +by the other. + +This formalizes the existing exports as a consumed contract: the CLI behavior in +[FR-019](./FR-019-manage-plugin-registry.md) and the catalog assembly in +[FR-007](./FR-007-assemble-module-roots.md) become reusable from a library import, +not only the command line. + +## Behavior + +- The package entry point SHALL export `installPlugin`, `listPlugins`, + `removePlugin`, `parseSourceArg`, `loadCatalog`, and `filamentModulesDir`. +- The exported operations SHALL read and write the same shared store paths as the + CLI, so an install or removal performed through the library is observable by the + CLI and vice versa. +- The package SHALL treat a breaking change to this exported surface as a + semver-major change, so downstream consumers can pin against it. + +## Acceptance Criteria + +| ID | Criteria | Verification | +| ----------- | ---------------------------------------------------------------------------------------------------- | ---------------------- | +| FR-024-AC-1 | The package entry point exports the named plugin and catalog operations | Test (index.test.ts) | +| FR-024-AC-2 | A plugin installed through `installPlugin` is listed by `listPlugins` and assembled by `loadCatalog` | Test (index.test.ts) | +| FR-024-AC-3 | A library-performed install/removal targets the same shared store the CLI uses | Test (plugins.test.ts) | + +## Dependencies + +- **Upstream**: [StR-003](../stakeholder/StR-003-shared-catalog.md) shared + catalog; the CLI plugin operations [FR-019](./FR-019-manage-plugin-registry.md) + and catalog assembly [FR-007](./FR-007-assemble-module-roots.md) whose internals + this surface re-exports. +- **Downstream**: filament-ide interoperates over the same shared store via + `@agent-ix/ts-plugin-kit` and these store conventions — rather than importing this + library — to install, list, remove, and load plugins + (`ix://agent-ix/filament-ide/FR-023`, `ix://agent-ix/filament-ide/FR-020`). diff --git a/spec/spec.md b/spec/spec.md index de66dfb..a0bc8b9 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -144,6 +144,7 @@ index; the files are authoritative. - [FR-017](./functional/FR-017-reconcile-default-modules.md) — reconcile the default module set into the shared store. - [FR-018](./functional/FR-018-map-plugin-sources.md) — map plugin source arguments to typed sources. - [FR-019](./functional/FR-019-manage-plugin-registry.md) — install, list, and remove plugins through the registry. +- [FR-024](./functional/FR-024-plugin-catalog-library-api.md) — expose plugin and catalog operations as a stable library API. **Workflows** From f9afe9f61a5c57765fc1a93394a4a91eb4558b03 Mon Sep 17 00:00:00 2001 From: Peter Krenesky Date: Sat, 27 Jun 2026 11:45:30 -0700 Subject: [PATCH 2/2] chore: prettier-ignore spec/ (quire-managed, not prettier-formatted) Co-Authored-By: Claude Opus 4.8 (1M context) --- .prettierignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.prettierignore b/.prettierignore index d1b5d1a..f17f6ac 100644 --- a/.prettierignore +++ b/.prettierignore @@ -37,3 +37,6 @@ tmp/ __pycache__/ *.pyc *.egg-info/ + +# Spec artifacts (quire-managed, not prettier-formatted) +spec/