@suaveplan/installer - Plugin host + lifecycle for project boilerplating and asset installation: detect → prompts → plan → apply → postInstall, transactional apply with rollback, conflict policies, manifest discovery.

Summary

Plugin host for project boilerplating and asset installation. Pipelines plugins through detect → prompts → plan → apply → postInstall with transactional rollback, conflict resolution, and dry-run support.

Documentation tree

bin — (no submodules)
- suaveplan-install — (no submodules)
errors — (no submodules)
- errors — (no submodules)
disk-fs — Disk-backed implementation of MutableInstallerFs used by the suaveplan-install bin and any host-side code that want…
installer-fs — Re-exports the read-only InstallerFs interface from the types module and declares its mutating extension `MutableInst…
memory-fs — In-memory implementation of MutableInstallerFs. Used by the testing harness (runPlugin constructs one if the caller…
host — (no submodules) - conflict — Resolves the per-op conflict policy on…
- apply — (no submodules) - conflict — Resolves the per-op conflict policy on…
  - apply — (no submodules) - conflict — Resolves the per-op conflict policy on…
  - conflict — Resolves the per-op conflict policy on a target that already exists. Five policies are supported: error (raise `APP…
  - json-merge — Implements the deep-merge semantics used by patch-json ops with conflict: "merge". Match the conventions of `@suave…
  - text-patch — Applies an ordered sequence of TextEdits to a string. Used by patch-text ops to make targeted insertions/deletions/…
- detect — Runs a plugin's optional detect stage inside an OpenTelemetry span. The plugin reports what is already present in the…
- host — (no submodules) - conflict — Resolves the per-op conflict policy on…
- plan — Invokes plugin.plan(answers, ctx) and validates the returned FileOp[] against FileOpsSchema before letting them f…
- post-install — Runs the plugin's optional postInstall stage with abort propagation. This is where plugins do follow-up work that doe…
- prompts — Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is whe…
manifest — (no submodules)
- discover — Walks the consumer's node_modules tree and returns every installer plugin matching the naming conventions: first-part…
- manifest — (no submodules)
installer-fs.test-helpers — Convenience helpers for assertions against the in-memory installer fs in plugin tests. createMemoryFs(seed) is a thin…
run-plugin — End-to-end test harness for plugins. runPlugin(plugin, options) wires up an in-memory filesystem, a scripted CLI, a n…
script-cli — Non-TTY InstallerCli driven by pre-recorded answers. ScriptCli is the default CLI used by runPlugin — tests scrip…
error-codes — Defines the canonical error-code registry for @suaveplan/installer and the InstallerError class that carries those…

- [suaveplan-install](./src/bin/suaveplan-install.md) — _(no submodules)_- [errors](./src/errors/errors.md) — _(no submodules)_- [errors](./src/errors/errors.md) — _(no submodules)_- [disk-fs](./src/fs/disk-fs.md) — Disk-backed implementation of `MutableInstallerFs` used by the `suaveplan-install` bin and any host-side code that want…

installer-fs — Re-exports the read-only InstallerFs interface from the types module and declares its mutating extension `MutableInst…
memory-fs — In-memory implementation of MutableInstallerFs. Used by the testing harness (runPlugin constructs one if the caller…
host — (no submodules)- conflict — Resolves the per-op conflict policy on…
- apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - conflict — Resolves the per-op conflict policy on a target that already exists. Five policies are supported: error (raise `APP…
  - json-merge — Implements the deep-merge semantics used by patch-json ops with conflict: "merge". Match the conventions of `@suave…
  - text-patch — Applies an ordered sequence of TextEdits to a string. Used by patch-text ops to make targeted insertions/deletions/…
- detect — Runs a plugin's optional detect stage inside an OpenTelemetry span. The plugin reports what is already present in the…
- host — (no submodules)- conflict — Resolves the per-op conflict policy on…
- plan — Invokes plugin.plan(answers, ctx) and validates the returned FileOp[] against FileOpsSchema before letting them f…
- post-install — Runs the plugin's optional postInstall stage with abort propagation. This is where plugins do follow-up work that doe…
- prompts — Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is whe…
manifest — (no submodules)- discover — Walks the consumer's node_modules tree and returns every installer plugin matching the naming conventions: first-part…
- manifest — (no submodules)- installer-fs.test-helpers — Convenience helpers for assertions against the in-memory installer fs in plugin tests. createMemoryFs(seed) is a thin…
run-plugin — End-to-end test harness for plugins. runPlugin(plugin, options) wires up an in-memory filesystem, a scripted CLI, a n…
script-cli — Non-TTY InstallerCli driven by pre-recorded answers. ScriptCli is the default CLI used by runPlugin — tests scrip…
error-codes — Defines the canonical error-code registry for @suaveplan/installer and the InstallerError class that carries those…
suaveplan-install — (no submodules)- errors — (no submodules)- errors — (no submodules)- disk-fs — Disk-backed implementation of MutableInstallerFs used by the suaveplan-install bin and any host-side code that want…
installer-fs — Re-exports the read-only InstallerFs interface from the types module and declares its mutating extension `MutableInst…
memory-fs — In-memory implementation of MutableInstallerFs. Used by the testing harness (runPlugin constructs one if the caller…
host — (no submodules)- conflict — Resolves the per-op conflict policy on…
- apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - conflict — Resolves the per-op conflict policy on a target that already exists. Five policies are supported: error (raise `APP…
  - json-merge — Implements the deep-merge semantics used by patch-json ops with conflict: "merge". Match the conventions of `@suave…
  - text-patch — Applies an ordered sequence of TextEdits to a string. Used by patch-text ops to make targeted insertions/deletions/…
- detect — Runs a plugin's optional detect stage inside an OpenTelemetry span. The plugin reports what is already present in the…
- host — (no submodules)- conflict — Resolves the per-op conflict policy on…
- plan — Invokes plugin.plan(answers, ctx) and validates the returned FileOp[] against FileOpsSchema before letting them f…
- post-install — Runs the plugin's optional postInstall stage with abort propagation. This is where plugins do follow-up work that doe…
- prompts — Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is whe…
manifest — (no submodules)- discover — Walks the consumer's node_modules tree and returns every installer plugin matching the naming conventions: first-part…
- manifest — (no submodules)- installer-fs.test-helpers — Convenience helpers for assertions against the in-memory installer fs in plugin tests. createMemoryFs(seed) is a thin…
run-plugin — End-to-end test harness for plugins. runPlugin(plugin, options) wires up an in-memory filesystem, a scripted CLI, a n…
script-cli — Non-TTY InstallerCli driven by pre-recorded answers. ScriptCli is the default CLI used by runPlugin — tests scrip…
error-codes — Defines the canonical error-code registry for @suaveplan/installer and the InstallerError class that carries those…
suaveplan-install — (no submodules)- errors — (no submodules)- errors — (no submodules)- disk-fs — Disk-backed implementation of MutableInstallerFs used by the suaveplan-install bin and any host-side code that want…
installer-fs — Re-exports the read-only InstallerFs interface from the types module and declares its mutating extension `MutableInst…
memory-fs — In-memory implementation of MutableInstallerFs. Used by the testing harness (runPlugin constructs one if the caller…
host — (no submodules)- apply — (no submodules)…
- apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - apply — (no submodules)- conflict — Resolves the per-op conflict policy on…
  - conflict — Resolves the per-op conflict policy on a target that already exists. Five policies are supported: error (raise `APP…
  - json-merge — Implements the deep-merge semantics used by patch-json ops with conflict: "merge". Match the conventions of `@suave…
  - text-patch — Applies an ordered sequence of TextEdits to a string. Used by patch-text ops to make targeted insertions/deletions/…
- detect — Runs a plugin's optional detect stage inside an OpenTelemetry span. The plugin reports what is already present in the…
- host — (no submodules)- apply — (no submodules)…
- plan — Invokes plugin.plan(answers, ctx) and validates the returned FileOp[] against FileOpsSchema before letting them f…
- post-install — Runs the plugin's optional postInstall stage with abort propagation. This is where plugins do follow-up work that doe…
- prompts — Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is whe…
manifest — (no submodules)- discover — Walks the consumer's node_modules tree and returns every installer plugin matching the naming conventions: first-part…
- manifest — (no submodules)- installer-fs.test-helpers — Convenience helpers for assertions against the in-memory installer fs in plugin tests. createMemoryFs(seed) is a thin…
run-plugin — End-to-end test harness for plugins. runPlugin(plugin, options) wires up an in-memory filesystem, a scripted CLI, a n…
script-cli — Non-TTY InstallerCli driven by pre-recorded answers. ScriptCli is the default CLI used by runPlugin — tests scrip…
error-codes — Defines the canonical error-code registry for @suaveplan/installer and the InstallerError class that carries those…
suaveplan-install — (no submodules)- errors — (no submodules) - errors — (no submodules)- disk-fs — Disk-backed implementation of MutableInstallerFs used by the suaveplan-install bin and any host-side code that want…
installer-fs — Re-exports the read-only InstallerFs interface from the types module and declares its mutating extension `MutableInst…
memory-fs — In-memory implementation of MutableInstallerFs. Used by the testing harness (runPlugin constructs one if the caller…
host — (no submodules) - apply — (no submodules) - apply — (no submodules) - conflict — Resolves the per-op conflict policy on a target that already exists. Five policies are supported: error (raise `APP…
- json-merge — Implements the deep-merge semantics used by patch-json ops with conflict: "merge". Match the conventions of `@suave…
- text-patch — Applies an ordered sequence of TextEdits to a string. Used by patch-text ops to make targeted insertions/deletions/…
- detect — Runs a plugin's optional detect stage inside an OpenTelemetry span. The plugin reports what is already present in the…
- host — (no submodules) - plan — Invokes plugin.plan(answers, ctx) and validates the returned FileOp[] against FileOpsSchema before letting them f…
- post-install — Runs the plugin's optional postInstall stage with abort propagation. This is where plugins do follow-up work that doe…
- prompts — Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is whe…
manifest — (no submodules) - discover — Walks the consumer's node_modules tree and returns every installer plugin matching the naming conventions: first-part…
- manifest — (no submodules)- installer-fs.test-helpers — Convenience helpers for assertions against the in-memory installer fs in plugin tests. createMemoryFs(seed) is a thin…
run-plugin — End-to-end test harness for plugins. runPlugin(plugin, options) wires up an in-memory filesystem, a scripted CLI, a n…
script-cli — Non-TTY InstallerCli driven by pre-recorded answers. ScriptCli is the default CLI used by runPlugin — tests scrip…
error-codes — Defines the canonical error-code registry for @suaveplan/installer and the InstallerError class that carries those…

Quickstart

# Add a plugin to your project as a dev dep, then run the installer
bun add -D @suaveplan/install-agent-skills
npx @suaveplan/installer add agent-skills

Programmatic use

import {
    Host,
    DiskFs,
    type InstallerContext,
} from "@suaveplan/installer";

const fs = new DiskFs({ cwd: process.cwd() });
const host = new Host(ctx, fs);
const result = await host.run(myPlugin, {
    dryRun: false,
    force: false,
    noInteractive: true,
});
console.log(result.summary);

Testing harness

import { runPlugin, ScriptCli } from "@suaveplan/installer";

const result = await runPlugin(myPlugin, {
    answers: { name: "agent-skills" },
});
expect(result.summary.written).toBeGreaterThan(0);

Subpath exports

@suaveplan/installer — main barrel.
@suaveplan/installer/types — types-only.
@suaveplan/installer/errors — INSTALLER_CODES, InstallerError.
@suaveplan/installer/host — Host, stage runners, apply/conflict helpers.
@suaveplan/installer/fs — DiskFs, MemoryFs, MutableInstallerFs.
@suaveplan/installer/manifest — discoverPlugins, findPlugin, loadManifest, validateManifest.
@suaveplan/installer/testing — runPlugin, ScriptCli, assertWrote, createMemoryFs.

Module documentation

Every implementation file ships with a sibling .md covering Purpose, Features, Usage examples, API Reference, and Implementation Notes. See src/host/host.md, src/host/apply/apply.md, src/manifest/discover.md for the load-bearing modules.

License

MIT