[3m1n3nc3]

Summary

Adds a plugin model on top of the existing Hook registry, so packages and apps can extend the driver setup and the ark console without editing core files. This is the first "Next priorities" item in the roadmap.

Hook

• Hook.listen(name, positions) adds callbacks next to the Hook.on() one instead of replacing it, and returns a function that removes them.
• Hook.emit() runs the on() callback, then the listen() callbacks in order, awaiting each async one. It still returns the first callback's result, so existing callers behave the same.
• has(), off() and clear() cover listen() callbacks too.

Plugins (@arkstack/foundry, re-exported by @arkstack/common)

• ArkstackPlugin base class with name, drivers, hooks(), commands() and register().
• Plugins registry: use, has, get, all, commands, remove, clear, assertSupports. Installing the same name twice is a no-op. Plugin hooks go through Hook.listen().
• HookMap type so hooks(): HookMap gets typed callbacks from HookRegistry.

Drivers (@arkstack/contract)

• ArkstackKitDriver.prepare(app, { publicPath, middleware }) runs assets, middleware, routes and the error handler, and fires the new driver:prepare hook at before, router (just before routes) and after.
• prepare() first checks installed plugins against the driver's name and throws for one that does not support it.
• app.use(...plugins) on Arkstack forwards to Plugins.use().
• The express, express-inertia, h3 and fastify templates now call driver.prepare() in boot().

Console

• @arkstack/console and @arkstack/console-slim add Plugins.commands() to the base commands. ark already loads src/core/bootstrap.ts first, so plugins installed there are picked up.

Docs

• New docs/guide/plugins.md, Hook.listen() and driver:prepare in the hooks guide, roadmap item marked done.

Upgrade note

Existing apps keep working. To get the driver:prepare hook, replace the four driver calls in src/core/app.ts boot() with driver.prepare() as shown in the plugins guide.

Tests

• New: packages/foundry/tests/plugins.test.ts, Hook.listen cases in hook.test.ts, packages/contract/tests/prepare.test.ts, and an Express end-to-end test where a plugin adds middleware and a route.
• foundry, contract, common and driver tests pass. The only failures are the ones already on main that need Postgres on :5432 (auth middleware tests) and the console command-surface test that runs pnpm prepare.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!