sugarcraft / sugar-plugin-installer
Composer installer for SugarCraft plugin packages (type sugar-plugin): stages each package to the user or project bundle directory that the root project's extra selects, and never runs plugin code.
Package info
github.com/sugarcraft/sugar-plugin-installer
Type:composer-plugin
pkg:composer/sugarcraft/sugar-plugin-installer
Requires
- php: ^8.3
- composer-plugin-api: ^2.0
Requires (Dev)
- composer/composer: ^2.7
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 01:04:10 UTC
README
A Composer plugin that installs SugarCraft plugin packages (type: sugar-plugin)
into the bundle tree that candy-code reads, instead of into vendor/.
Original work: there is no upstream port, so no Mirrors charmbracelet/...
citation applies.
composer require sugarcraft/sugar-plugin-installer
The root project must allow the plugin to run, and it must say where plugins go:
{
"config": {
"allow-plugins": {
"sugarcraft/sugar-plugin-installer": true
}
},
"extra": {
"sugar-plugin-installer": {
"scope": "project"
}
}
}
Where a plugin lands
The root project's composer.json selects the scope. Plugin packages never set it.
extra.sugar-plugin-installer |
Staged to |
|---|---|
absent, or {}, or "scope": "user" |
~/.candy-code/bundles/<name> |
"scope": "project" |
<project>/.candy-code/bundles/<name> |
"scope": "project", "root": "<path>" |
<path>/.candy-code/bundles/<name> |
<name>is the part of the package name after the vendor slash.sugarcraft/candy-discordstages to.../bundles/candy-discord.<project>is the directory of the rootcomposer.jsonthat Composer loaded: the file named byCOMPOSER, or./composer.json. Composer does not always change into that directory, so the tree follows the file, not the working directory.- A relative
rootis resolved against<project>. An absoluterootis used as given.rootapplies only underprojectscope. Underuserscope it is validated but unused. <path>must be a directory the user can write to. The installer creates the.candy-code/bundlestree on install.
Refused with an exception, before anything is written:
- a
scopeother thanuserorproject("global","USER",null, a number) - a section that is not an object, or a non-empty list
- an unknown key in the section (so a typo such as
"scoep"cannot fall back to user scope) - a
rootthat is not a non-empty string - a
rootthat starts with~underprojectscope. PHP does not expand the home shorthand, so~/workwould stage under the project at a literal~directory and candy-code would never find it. Write the absolute path (for example/home/you/work). Underuserscope therootis unused, so a~value there is accepted. - a package name that cannot be a directory name
- a package whose staging directory another installed
sugar-pluginalready uses. Names that differ only by vendor (acme/candy-xandsugarcraft/candy-x) share one directory. This check sees the packages installed in this project. It does not see a tree another project staged under user scope. - a home directory that is not an absolute
HOMEorUSERPROFILE, underuserscope. Project scope never reads the home directory.
The section is enforced when a sugar-plugin package is downloaded, installed or
updated, not when Composer starts. A malformed section therefore refuses only the
install or update of a plugin. It does not break other Composer commands.
Composer also asks where an installed plugin lives on dump-autoload, show,
validate and remove. Those commands do not need a valid section, or a home
directory under user scope. They use the
staged tree that exists: the root tree when the section names one, then the
project tier, then the user tier, then the directory Composer recorded for the
package. composer remove therefore still deletes a
plugin staged under a section that has since been broken.
What the installer does, and does not do
- It stages files only. Composer's downloader fills the directory.
composer removedeletes it, andcomposer updatewrites the new version to the same place. - One exception outside the staged tree: a package's declared
binentries are linked into the project'svendor/binon install and update, and the links are removed on remove, as Composer does for any package. The links point into the staged directory; no other file is written outside it. - It never runs plugin code.
- It never edits
trustedBundleChannels, and it never writes the channel ledger. Trust stays a user-tier decision in candy-code. - It does not check the staged tree's contents. A package's
autoload.filesentries still run when the project's Composer autoloader loads. Treat a plugin package with the same trust you give any Composer dependency. - Changing
scopeorrootafter an install does not move the staged tree.removeandupdatefind the tree where it sits and delete it. They check the configured tier, the project and user default tiers, and the directory Composer recorded for the package invendor/composer/installed.jsonafter its last save. The recorded directory is what keeps a tree findable after arootchange or a droppedrootkey. A tree counts only when itscomposer.jsonnames the package, so another package's tree is never touched. A plaincomposer installleaves the tree where it is. To move it,composer removeandcomposer requirethe package again, orcomposer updateit to a new version. - The home directory is taken from
HOME, or fromUSERPROFILEwhenHOMEis empty. candy-code's own home resolution has extra hardening that this package does not copy, because a plugin library must not depend on candy-code.
Checklist items not applied
The new-lib checklist in plan_plugin.md section 7 applies to this package as
follows.
| Item | Status and reason |
|---|---|
composer.json, phpunit.xml, README.md, CALIBER_LEARNINGS.md, src/, tests/ |
Done. |
No repositories[] in the lib manifest; no candy-code require |
Done. tools/check-plugin-deps.php and tools/check-path-repos.php --no-lib-path-repos pass. |
No per-lib composer.lock |
Done. /*/composer.lock is gitignored. |
Root composer.json |
require, repositories[] (a path entry, as the root does for every sibling) and allow-plugins entries. The checked-in rule in AGENTS.md and plan section 7 asks for both. |
Root composer.lock |
Not refreshed in this change. A root composer update is needed to record the new require. |
docs/MATCHUPS.md, PROJECT_NAMES.md, root README.md table |
Done. Original-work rows; the root README row carries the package icon. |
codecov.yml |
Done. |
docs/index.html tile, docs/_data/<slug>.json and body, php tools/gen-docs.php |
Skipped. The site catalogues libraries and apps, and this package is install tooling with no page of its own yet. The site's library count does not move: the count is derived from docs/MATCHUPS.md, and this package sits under ## Composer tooling (outside the catalog counts), so the site stays at "forty-three" and php tools/gen-docs.php --check passes at 43. |
support.docs in composer.json |
Dropped. It would point at a docs/lib/sugar-plugin-installer.html page that is not generated, so the entry is left out until that page exists. |
media/icons/sugar-plugin-installer.png |
Done. The icon is in the root media/icons/, and the root README row references it. |
.github/workflows/vhs.yml |
Skipped. Non-visual, so exempt. |
php tools/check-one-type-per-file.php, php tools/check-lib-licenses.php, php tools/check-child-lifetimes.php |
Applied. The package holds one type per file and carries the root LICENSE. It starts no child processes, so the lifetime check expects no change. The integration test runs composer through exec, which is a test-only child and is not exposed by the library. |
Tests
cd sugar-plugin-installer && composer install && vendor/bin/phpunit
ComposerIntegrationTest runs the real composer against a scratch project,
with a scratch HOME, COMPOSER_HOME, cache and network disabled. It requires
the installer and a sample sugar-plugin package by path repository, then checks
the staged tree and that the trust list and ledger bytes do not change, across
require and remove. It skips with a reason when composer is not on PATH.
Plan
plan_plugin.md sections 5.1 (install behavior), 5.3 (Composer phase 4), 5.5
(who writes which composer.json), and 0.2 O5, O6 and O8.