SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9bf56a806b0d74d40ca05bb61c6e5e025b4fb8c9
skills/plugins/document-navigator/docs/devtools/tooling/installer
History
admin 9bf56a806b Move docs/ package mirror into document-navigator plugin 
Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-30 01:10:00 +01:00
..
src
Move docs/ package mirror into document-navigator plugin
2026-05-30 01:10:00 +01:00
README.md
Move docs/ package mirror into document-navigator plugin
2026-05-30 01:10:00 +01:00

README.md

@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)
  • 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

Reference in New Issue View Git Blame Copy Permalink