blogwright 0.3.2 → 0.4.0-beta.0

package/dist/plugins.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Plugin discovery: finds every installed `blogwright-*` package that
+ * declares a `blogwright.plugin` manifest field, loads it, and validates its
+ * default export against core's `Plugin` contract.
+ *
+ * The candidate set is the UNION of two sources, each resolved from its own
+ * directory - see `collectCandidates` below - because a consuming repo
+ * depends on `blogwright`, not on `blogwright-pds`: scanning the consumer's
+ * own `package.json` alone would never find a plugin bundled inside the CLI
+ * itself.
+ *
+ * Collect, never throw, for anything candidate-specific: a broken plugin -
+ * one that fails to resolve, whose manifest is malformed, or whose default
+ * export fails validation - becomes an entry in `failures`, not a thrown
+ * error that aborts the whole discovery pass. One bad dependency must not
+ * make `blogwright deploy` (or any other built-in command) unusable. The
+ * only things this module *does* throw for are the two preconditions
+ * discovery cannot proceed without at all: the repo's own `package.json` and
+ * the CLI's own `package.json`, both read before any candidate is resolved.
+ *
+ * The same collect-never-throw rule governs the two namespace-collision
+ * checks this module applies itself, after a candidate has already loaded
+ * and validated cleanly: a plugin whose declared name is one the CLI
+ * dispatches itself (`RESERVED_COMMANDS`, `known-commands.ts` - a leaf
+ * module with no imports of its own, so this domain module never has to
+ * import the composition root just to read it), and two plugins that
+ * declare the same name as each other. §CLI → Namespace collisions calls
+ * this "rejected with an error", but - exactly like a malformed manifest or
+ * a failed `validatePlugin` check above - that rejection is a reported
+ * `failures` entry, not a thrown one. Throwing here would let a single
+ * colliding plugin abort discovery for every other, unrelated plugin and
+ * every built-in command that runs it; `blogwright plugin list` (task 17)
+ * depends on the collect outcome too, since it is the one place a collision
+ * becomes visible to a human.
+ *
+ * `pds` is deliberately absent from `RESERVED_COMMANDS`, and adding it would
+ * now BREAK the namespace rather than merely shadow it. Task 29 deleted
+ * `cli.ts`'s hardcoded `command === 'pds'` branch: there is no built-in
+ * `pds` command left for a reservation to protect, and `blogwright pds
+ * <action>` is answered by the bundled `blogwright-pds` package, which
+ * declares the plugin name `pds` and is discovered here like any other
+ * plugin. Reserving the name would therefore aim
+ * `resolveNamespaceCollisions` below at that bundled plugin itself: it would
+ * become a `failures` entry rather than an installed one, and the namespace
+ * would stop working outright - `blogwright pds sync` exiting 1 with `no
+ * built-in command or installed plugin claims "pds"`, `blogwright --help`
+ * listing none of its six actions, and `blogwright plugin list` reporting it
+ * as reserved for a built-in command that no longer exists. Verified by
+ * adding `'pds'` to the set: discovery rejects the real bundled package and
+ * this file's real-disk integration cases fail on exactly that reason
+ * string. So the name stays unreserved on purpose, pinned by a test below.
+ *
+ * DECISION (task 13, record here for task 16 to find): a plugin's declared
+ * ACTIONS can collide with a generic action the CLI contributes, distinct
+ * from the namespace collisions above. §CLI → `blogwright <plugin> init`
+ * names exactly one such collision a boundary check can reject: a plugin
+ * declaring BOTH an `init` command in its own `commands` AND an `init?(io)`
+ * contributor is unsatisfiable, because a declared command always wins
+ * dispatch (`plugin-commands.ts`'s `matchAction` matches a plugin's own
+ * `commands` before the generic action is ever considered), so the
+ * contributor would ask its questions nowhere. That check - `rejectDeclaredInitCollisions`
+ * below - lives HERE, in this module's collision pass, rather than in core's
+ * `validatePlugin` (`blogwright-core`'s `plugin.ts`), for the same reason the
+ * namespace checks do: it is about actions the *CLI* contributes generically
+ * (the config-writing `init`), which core must not know exists, and this
+ * module already reports a plugin-level rejection as a `failures` entry
+ * rather than a thrown error. §CLI → Plugin lifecycle adds the sibling rule
+ * for `bootstrap`/`destroy` (always generic; a plugin may never declare
+ * either, full stop - no "unless paired with a contributor" nuance, since
+ * there is no bootstrap/destroy contributor to pair with). Task 16 adds
+ * `rejectDeclaredLifecycleCollisions` below, a sibling function called from
+ * the same place in `discover`, with that rule, so every declared-action
+ * collision rejection greps to this one module instead of splitting across
+ * whichever of the two tasks happened to land first. `status` is deliberately
+ * NOT part of that rule: a plugin may declare its own `status` command
+ * freely - `read()` lives on the plugin's own nodes, so no engine call is
+ * required the way `bootstrap`/`destroy` need one - and `plugin-commands.ts`'s
+ * ordinary `matchAction` precedence (a plugin's own commands win before any
+ * generic fallback is even considered) already gives a declared `status`
+ * command priority with no boundary check needed here.
+ *
+ * DECISION (task 19, recorded here plainly because task 28 has to reason
+ * about it when pds's config validation moves out of core): a plugin's own
+ * config block is validated for the ONE plugin being DISPATCHED, in the
+ * dispatch path (`runPlugin` calls {@link resolvePluginConfig} below), and
+ * never for every discovered plugin. Two reasons, and neither is taste:
+ *
+ *   - `createContext` (`context.ts`) is the path every built-in command
+ *     takes and it accepts no plugin list, so validating there would have to
+ *     run `discover` on `deploy`, `status` and `bootstrap` - breaking the
+ *     laziness rule (§CLI -> Plugin discovery: a built-in command loads no
+ *     plugin module) that task 10's own test pins. There is no seam in
+ *     `createContext` through which the dispatched plugin ALONE could be
+ *     reached, because at that point no plugin has been chosen yet.
+ *   - Validating every discovered plugin, wherever it happened, would let an
+ *     unrelated plugin's malformed block abort a command that has nothing to
+ *     do with it. A block for a plugin that is not installed is already
+ *     valid and inert - the same contract `pds` has today - and a block for
+ *     an installed plugin that is not the one being run is inert for exactly
+ *     the same reason: nothing reads it.
+ *
+ * The corollary is that `blogwright <plugin> <action>` is the only thing
+ * that reports a bad block, and it reports only its own plugin's.
+ */
+import { type Plugin } from 'blogwright-core';
+import type { Ports } from './ports.js';
+/** Why one candidate package failed to become a usable plugin. */
+interface PluginLoadFailure {
+    readonly packageName: string;
+    readonly reason: string;
+}
+/**
+ * A successfully loaded, `validatePlugin`-passing plugin together with the
+ * package it came from - the provenance `blogwright plugin list` (task 17)
+ * reports, and nothing else needs.
+ *
+ * `packageJsonPath` is the path `ModuleLoader.packageJsonPathFor` resolved,
+ * NOT one derived from `ModuleLoader.resolve`'s entry file: a package
+ * published with the standard dual-package layout has its entry point in
+ * `dist/` beside a name-less `{"type":"module"}` stub, so walking up one
+ * directory from the entry file finds the wrong `package.json` entirely (see
+ * that port method's own doc comment). Carried as the PATH rather than a
+ * parsed `version`, so the one command that shows a version reads it lazily
+ * and `--help`/dispatch, which never show one, pay nothing for a field they
+ * do not use.
+ */
+interface InstalledPlugin {
+    readonly packageName: string;
+    readonly packageJsonPath: string;
+    readonly plugin: Plugin;
+}
+/**
+ * `discover`'s result: every collection is always an array, never
+ * `null`/`undefined`.
+ *
+ * `plugins` is exactly `installed.map((entry) => entry.plugin)`, derived once
+ * inside `discover` so the two can never disagree. It stays alongside
+ * `installed` because the three callers that dispatch or render a plugin -
+ * `runPlugin`, `buildHelp` and the `init` wizard - want the `Plugin` and
+ * nothing else, and should not have to unwrap an envelope to serve the one
+ * caller (`blogwright plugin list`) that also names the package it came from.
+ */
+export interface DiscoveryResult {
+    readonly plugins: readonly Plugin[];
+    readonly installed: readonly InstalledPlugin[];
+    readonly failures: readonly PluginLoadFailure[];
+}
+/**
+ * Discover every installed plugin reachable from `repoRoot` (the consuming
+ * repo) and `cliPackageDir` (the CLI's own package directory, from
+ * {@link cliPackageDir} in `context.ts`). Never throws for a candidate-level
+ * problem - see the module comment - only for the two repo-level
+ * preconditions `collectCandidates` reads first.
+ */
+export declare function discover(repoRoot: string, cliPackageDir: string, ports: Pick<Ports, 'fs' | 'loader'>): Promise<DiscoveryResult>;
+/**
+ * Resolve the config block ONE plugin owns into the value the dispatcher puts
+ * on `ctx.pluginConfig` - `runPlugin`'s single call, made for the plugin
+ * being DISPATCHED and no other (see the module comment's task-19 DECISION
+ * for why the scope is one plugin rather than every discovered one).
+ *
+ * The block is read off the RAW config document (`OpsContext.configDocument`,
+ * `context.ts`), never off `OpsConfig`, which has no index signature to reach
+ * a plugin's key through. `pluginBlock` returning `unknown` and the plugin's
+ * own `validateConfig` narrowing it is the sanctioned boundary: the very next
+ * step after the read validates it.
+ *
+ * The validator IS called when the plugin's key is ABSENT from the document,
+ * with `undefined`. That is the whole point of it: a validator is the only
+ * thing that can turn an absent block into the plugin's own defaults, and a
+ * repo that installs a plugin without writing its block is a valid,
+ * documented configuration. Handing `{}` straight through instead would put a
+ * block on `ctx.pluginConfig` that never went through the plugin's own
+ * defaulting - typed as total, `undefined` at runtime in every defaulted
+ * field - and nothing downstream could catch it, because the dispatcher
+ * erases `TConfig` (`Plugin<unknown>`, `PluginContext<unknown>`).
+ *
+ * `{}` is returned ONLY where there is no validator to call: a plugin that
+ * declares no `configKey` (a `Plugin<never>`, which cannot read
+ * `pluginConfig` at all) or no `validateConfig` - probed with `typeof ===
+ * 'function'`, the way this module and `plugin-commands.ts` both probe the
+ * `init` contributor, because core's `validatePlugin` type-checks neither
+ * member. `pluginConfig` is a required member, so `undefined` is not an
+ * option there - DEVELOPMENT.md's no-null rule.
+ *
+ * A validator's own rejection is re-raised with the plugin's name and the key
+ * in front of it and the plugin's message VERBATIM behind it, so an operator
+ * reading `blogwright analytics bootstrap`'s failure learns which plugin
+ * refused which key without the plugin having to name itself in every message
+ * it writes. It propagates - never swallowed, never downgraded to a warning -
+ * and exits non-zero through `bin.ts`'s error path.
+ */
+export declare function resolvePluginConfig(plugin: Plugin<unknown>, configDocument: Readonly<Record<string, unknown>>): unknown;
+export {};