blogwright 0.3.2 → 0.4.0-beta.0

package/dist/nodes.js

@@ -54,7 +54,7 @@ function bucketNode() {
 }
 function logGroupNode(id, title, name, days, 
 // CloudFront vended log delivery exists only in us-east-1, so its log group
-// must live there too — regardless of the stack's primary region.
+// must live there too - regardless of the stack's primary region.
 usEast1 = false) {
     const logs = (ctx) => (usEast1 ? ctx.clients.logsUsEast1 : ctx.clients.logs);
     const region = (ctx) => (usEast1 ? 'us-east-1' : ctx.config.region);
@@ -92,7 +92,7 @@ const LAMBDA_TRUST = {
     ],
 };
 /** IAM role Lambda assumes while building the MicroVM image. */
-/** Apply the build role's inline policy (idempotent — used by create + update). */
+/** Apply the build role's inline policy (idempotent - used by create + update). */
 async function applyBuildRolePolicy(ctx) {
     // The build role is BOTH the image-build role AND the MicroVM's ambient runtime
     // identity (via IMDS), so it needs the build's runtime S3 permissions: read the
@@ -104,7 +104,7 @@ async function applyBuildRolePolicy(ctx) {
             { Effect: 'Allow', Action: ['s3:ListBucket'], Resource: `arn:aws:s3:::${ctx.names.bucket}` },
             {
                 // s3:PutObjectTagging is required even though the tags ride on the PUT
-                // itself (x-amz-tagging header) — AWS checks it as a distinct action, and
+                // itself (x-amz-tagging header) - AWS checks it as a distinct action, and
                 // PutObject does not imply it. Without it every tagged upload 403s.
                 Effect: 'Allow',
                 Action: ['s3:PutObject', 's3:PutObjectTagging', 's3:DeleteObject'],
@@ -158,7 +158,7 @@ async function applyExecRolePolicy(ctx) {
                 Resource: `arn:aws:s3:::${ctx.names.bucket}/*`,
             },
             {
-                // s3:PutObjectTagging: see the build role — a tagged PUT needs it explicitly.
+                // s3:PutObjectTagging: see the build role - a tagged PUT needs it explicitly.
                 Effect: 'Allow',
                 Action: ['s3:PutObject', 's3:PutObjectTagging', 's3:DeleteObject'],
                 Resource: siteWriteResource(ctx),
@@ -235,7 +235,7 @@ async function imageInput(ctx) {
 }
 /**
  * Poll until the image reaches its expected terminal state, treating a timeout (still
- * CREATING/UPDATING) as failure — never success. For updates, require the version to
+ * CREATING/UPDATING) as failure - never success. For updates, require the version to
  * advance past `priorVersion` so a stale pre-update state can't be read as done.
  */
 async function awaitImageSettled(ctx, arn, expected, priorVersion) {
@@ -272,7 +272,7 @@ export function builderImageAction(image, recorded, hash, logGroup) {
  * Create, rebuild, or leave the MicroVM builder image, depending on what's deployed:
  * create it if missing, rebuild it if the agent bundle (or its log group) changed or the
  * last build is unhealthy, otherwise no-op. Idempotent and cheap in the common case (a
- * single GetMicrovmImage + hash compare), so it's safe to run before every deploy — which
+ * single GetMicrovmImage + hash compare), so it's safe to run before every deploy - which
  * is how build-agent changes propagate through CI without a separate `bootstrap`.
  */
 export async function reconcileBuilderImage(ctx) {
@@ -333,12 +333,12 @@ function microvmImageNode() {
         },
     };
 }
-/** ACM certificate (us-east-1) — only present when a custom domain is configured. */
+/** ACM certificate (us-east-1) - only present when a custom domain is configured. */
 function certificateNode() {
     return {
         id: 'acm-certificate',
         // Depends on the bucket so state (with the cert ARN) can be saved before the long
-        // ISSUED wait — the id sorts before 'bucket', so without this it would run first.
+        // ISSUED wait - the id sorts before 'bucket', so without this it would run first.
         dependsOn: ['bucket'],
         title: 'ACM certificate',
         async read(ctx) {
@@ -373,7 +373,7 @@ function certificateNode() {
             let initial = await ctx.clients.acm.describeCertificate(arn);
             if (initial.status === 'PENDING_VALIDATION' && initial.validation.length === 0) {
                 // ACM populates the validation ResourceRecords asynchronously after
-                // RequestCertificate — an empty set here is that race, not "nothing to
+                // RequestCertificate - an empty set here is that race, not "nothing to
                 // validate". Acting on it would skip record creation entirely and the
                 // issuance poll below could never succeed.
                 initial = await pollUntil(() => ctx.clients.acm.describeCertificate(arn), (s) => s.status !== 'PENDING_VALIDATION' || s.validation.length > 0, { intervalMs: 5_000, timeoutMs: 5 * 60_000 });
@@ -383,7 +383,7 @@ function certificateNode() {
             }
             if (initial.status !== 'ISSUED' && initial.validation.length > 0) {
                 if (ctx.preview) {
-                    // Preview domain is a Route53 hosted zone — create the validation records for you.
+                    // Preview domain is a Route53 hosted zone - create the validation records for you.
                     const zoneId = await ctx.clients.route53.hostedZoneId(domain);
                     if (!zoneId)
                         throw new Error(`no Route53 hosted zone found for ${domain}`);
@@ -454,7 +454,7 @@ const PREVIEW_FUNCTION_CODE = `function handler(event) {
 /**
  * CloudFront Function (viewer-request) for staging/production: resolve a directory URL
  * to its index document (`/projects/` → `/projects/index.html`). Required because the S3
- * origin is the private REST endpoint (via OAC), which — unlike an S3 website endpoint —
+ * origin is the private REST endpoint (via OAC), which - unlike an S3 website endpoint -
  * does no index-document resolution, so `DefaultRootObject` only covers the apex. The
  * `/site` origin path is applied by the distribution, so this function must not add it.
  */
@@ -496,7 +496,7 @@ function routerFunctionNode(preview) {
 /**
  * Find the distribution a crashed earlier bootstrap created but never recorded in
  * state. The deterministic comment (`"<siteName> <env>"`) narrows candidates; identity
- * is confirmed by CallerReference — comments are editable in the console, while the
+ * is confirmed by CallerReference - comments are editable in the console, while the
  * reference is immutable for the distribution's life and collision-free across
  * environments by construction.
  */
@@ -548,7 +548,7 @@ function distributionNode(hasDomain, preview) {
                     functionArn: String(output(ctx, 'cloudfront-function').arn),
                     // Previews are served uncached (per-PR content, host-routed); staging/production
                     // keep the default cache policy. Non-preview stacks map the S3 REST origin's
-                    // 403/404 (a missing key) to the site's 404 page — or, in SPA mode, to
+                    // 403/404 (a missing key) to the site's 404 page - or, in SPA mode, to
                     // /index.html with a 200 so client-side routes deep-link correctly.
                     ...(preview
                         ? { cachePolicyId: CACHING_DISABLED }
@@ -563,8 +563,8 @@ function distributionNode(hasDomain, preview) {
             }
             catch (err) {
                 // A crashed earlier bootstrap can leave a distribution in AWS that state never
-                // recorded. Retrying then 409s on the duplicate alias — CloudFront's CNAME
-                // conflict check fires before the CallerReference idempotency match — so adopt
+                // recorded. Retrying then 409s on the duplicate alias - CloudFront's CNAME
+                // conflict check fires before the CallerReference idempotency match - so adopt
                 // the orphan instead. No verified match means the alias belongs to a foreign
                 // distribution: that conflict is real and must surface.
                 const conflict = err instanceof AwsError &&
@@ -599,7 +599,7 @@ function distributionNode(hasDomain, preview) {
         },
         async update(ctx) {
             // A domain added (or changed) after the first bootstrap must reach the
-            // existing distribution — the certificate node validates the cert, but
+            // existing distribution - the certificate node validates the cert, but
             // only this reconcile attaches the alias + viewer certificate.
             const id = output(ctx, 'cloudfront-distribution').id;
             if (typeof id !== 'string')
@@ -607,7 +607,7 @@ function distributionNode(hasDomain, preview) {
             if (!ctx.domain) {
                 // Deliberately no automatic alias removal: dropping --domain from a
                 // later run must not detach a live site's hostname.
-                ctx.logger.ok('no domain configured — existing aliases left as-is');
+                ctx.logger.ok('no domain configured - existing aliases left as-is');
                 return;
             }
             const alias = preview ? `*.${ctx.domain}` : ctx.domain;
@@ -635,6 +635,52 @@ function distributionNode(hasDomain, preview) {
         },
     };
 }
+/**
+ * True when `delivery` is the one this site's node created. AWS permits exactly
+ * one delivery source per distribution, so the analytics plugin necessarily
+ * hangs its own delivery off the site's source: ownership is the destination a
+ * delivery feeds, and nothing else. The final `:`-separated segment of a
+ * `delivery-destination` ARN is its name, which is derived from the environment
+ * (`deriveNames`) and therefore also matches the previous stack's delivery on a
+ * destroy → bootstrap cycle - exactly the delivery the ConflictException retry
+ * exists to remove.
+ *
+ * Position cannot stand in for this (`findDeliveryIdBySource` takes whichever
+ * delivery AWS lists first), and neither can the recorded `destination` output:
+ * it is empty precisely when the retry needs it, because `putDeliverySource`
+ * throws the Conflict before `putDeliveryDestination` ever runs.
+ */
+function isOwnDelivery(delivery, destinationName) {
+    return delivery.deliveryDestinationArn.split(':').pop() === destinationName;
+}
+/**
+ * The ids of the site's own deliveries on `names.deliverySource`, after
+ * refusing outright when the shared source carries a delivery the site did not
+ * create. Both the `delete()` teardown and the ConflictException retry call
+ * this BEFORE deleting anything: each of them goes on to delete the delivery
+ * source, and AWS rejects that while another delivery is attached - a refusal
+ * `deleteDeliverySource` does not catch (it swallows only not-found). Refusing
+ * up front turns a teardown that throws part-way, after the site's own delivery
+ * is already gone, into an actionable stop with nothing removed.
+ */
+async function ownDeliveryIdsOrRefuse(ctx) {
+    const deliveries = await ctx.clients.logsUsEast1.deliveriesForSource(ctx.names.deliverySource);
+    const foreign = deliveries.filter((d) => !isOwnDelivery(d, ctx.names.deliveryDestination));
+    if (foreign.length > 0) {
+        const listed = foreign
+            .map((d) => `${d.id} (destination ${d.deliveryDestinationArn})`)
+            .join(', ');
+        throw new Error(`delivery source ${ctx.names.deliverySource} still carries ` +
+            `${foreign.length === 1 ? 'a delivery' : `${foreign.length} deliveries`} this site does ` +
+            `not own (${listed}); removing the source would break whoever does. Tear that stack ` +
+            `down first, then retry: blogwright analytics destroy ${ctx.env} --yes`);
+    }
+    // Filtered, not `deliveries.map(...)`: the throw above already guarantees every
+    // delivery here is the site's own, but that is a non-local guarantee. Re-applying
+    // the predicate makes the name and the body agree on their own, so softening the
+    // refusal cannot silently start feeding foreign ids to the delete loop.
+    return deliveries.filter((d) => isOwnDelivery(d, ctx.names.deliveryDestination)).map((d) => d.id);
+}
 /** Wire CloudFront access logs to the CloudWatch log group via vended log delivery. */
 function logDeliveryNode() {
     async function wire(ctx) {
@@ -663,13 +709,21 @@ function logDeliveryNode() {
             }
             catch (err) {
                 // delete() below leaves the delivery plumbing behind, and PutDeliverySource
-                // refuses to repoint an existing source at a new distribution ARN — so a
+                // refuses to repoint an existing source at a new distribution ARN - so a
                 // destroy → bootstrap cycle hits ConflictException here. Remove the stale
                 // delivery/source/destination trio and retry once.
                 if (!(err instanceof AwsError && /Conflict/i.test(err.code)))
                     throw err;
-                ctx.logger.step('stale log delivery from a previous stack — removing and retrying');
-                for (const id of await ctx.clients.logsUsEast1.deliveriesForSource(ctx.names.deliverySource)) {
+                ctx.logger.step('stale log delivery from a previous stack - removing and retrying');
+                // Refuse before deleting anything when the source is shared: removing it
+                // IS the retry (PutDeliverySource will not repoint a source that still
+                // exists), so a foreign delivery forecloses the retry entirely. Deleting
+                // only the site's own delivery and pressing on would leave the stack with
+                // no CloudWatch delivery and a failed bootstrap - worse than the conflict
+                // being healed. Only the site's own ids are removed here; the old loop
+                // deleted every delivery on the source, silently unwiring the other owner.
+                const ownDeliveryIds = await ownDeliveryIdsOrRefuse(ctx);
+                for (const id of ownDeliveryIds) {
                     await ctx.clients.logsUsEast1.deleteDelivery(id);
                 }
                 await ctx.clients.logsUsEast1.deleteDeliverySource(ctx.names.deliverySource);
@@ -682,10 +736,11 @@ function logDeliveryNode() {
             // delivery source/destination persist, and a later bootstrap against a new
             // distribution ARN fails with ConflictException ("Update to existing Delivery Source
             // with new ResourceId is not allowed"). Delete the delivery first (it references both),
-            // then the source and destination. The id isn't in state, so look it up by source name.
-            const deliveryId = await ctx.clients.logsUsEast1.findDeliveryIdBySource(ctx.names.deliverySource);
-            if (deliveryId)
-                await ctx.clients.logsUsEast1.deleteDelivery(deliveryId);
+            // then the source and destination. The ids aren't in state, so look them up by source
+            // name - which also settles whether this site still owns the source at all.
+            const deliveryIds = await ownDeliveryIdsOrRefuse(ctx);
+            for (const id of deliveryIds)
+                await ctx.clients.logsUsEast1.deleteDelivery(id);
             await ctx.clients.logsUsEast1.deleteDeliverySource(ctx.names.deliverySource);
             await ctx.clients.logsUsEast1.deleteDeliveryDestination(ctx.names.deliveryDestination);
         },
@@ -731,12 +786,12 @@ const GITHUB_OIDC_URL = 'token.actions.githubusercontent.com';
 // this value, but the API requires one.
 const GITHUB_OIDC_THUMBPRINT = '6938fd4d98bab03faadb97b34396831e3780aea1';
 /**
- * IAM role a GitHub Actions workflow assumes via OIDC — to deploy/destroy previews
+ * IAM role a GitHub Actions workflow assumes via OIDC - to deploy/destroy previews
  * (preview stack, any ref) or to deploy production (main branch only, plus CloudFront
  * invalidation and read access to the PDS credentials secret).
  */
 function githubOidcRoleNode(preview) {
-    const roleName = (ctx) => `${ctx.names.prefix}-gh`;
+    const roleName = (ctx) => ctx.names.githubRole;
     return {
         id: 'gh-oidc-role',
         // Production deploys invalidate the distribution, so its ARN must be in state.
@@ -763,7 +818,7 @@ function githubOidcRoleNode(preview) {
 /**
  * The workflow's OIDC subject claim, scoped per environment to match how each one
  * deploys: previews from any PR ref; staging from pushes to main; production from the
- * `production` GitHub Environment (release-gated — see production.yml), which lets
+ * `production` GitHub Environment (release-gated - see production.yml), which lets
  * deploys be gated behind environment protection rules.
  */
 export function oidcSubClaim(repo, env, preview) {
@@ -829,6 +884,18 @@ export function oidcRolePolicyStatements(ctx) {
             // refresh tokens are single-use, so every sync persists the rotated
             // session (PutSecretValue via the upsert helper, which tries CreateSecret
             // first when the secret is missing).
+            //
+            // The `??` default duplicates the pds plugin's own `resolvePdsSecretName`
+            // deliberately, and must NOT be replaced by an import of it: this
+            // resource graph carries no plugin knowledge, which is the whole point of
+            // the plugin owning its own node (`packages/pds/src/nodes.ts`). Core
+            // stopped defaulting `pds.secretName`, so without this default the
+            // template literal would happily interpolate `undefined` into a live IAM
+            // policy - `applyOidcRole` rewrites this whole document on every
+            // `blogwright bootstrap`, so a wrong ARN here is a broken permission and
+            // not a test failure. Task 59 deletes this statement together with the
+            // `ctx.config.pds` branch around it; the duplication lives only until
+            // then.
             statements.push({
                 Effect: 'Allow',
                 Action: [
@@ -836,7 +903,7 @@ export function oidcRolePolicyStatements(ctx) {
                     'secretsmanager:PutSecretValue',
                     'secretsmanager:CreateSecret',
                 ],
-                Resource: `arn:aws:secretsmanager:${ctx.config.region}:${ctx.accountId}:secret:${ctx.config.pds.secretName}-*`,
+                Resource: `arn:aws:secretsmanager:${ctx.config.region}:${ctx.accountId}:secret:${ctx.config.pds.secretName ?? `${ctx.config.siteName}/atproto`}-*`,
             });
         }
     }
@@ -872,7 +939,7 @@ async function applyOidcRole(ctx, roleName) {
 }
 /**
  * Route53 wildcard record pointing *.<domain> at the preview CloudFront
- * distribution — A/AAAA alias records (free queries, apex-safe), not a CNAME.
+ * distribution - A/AAAA alias records (free queries, apex-safe), not a CNAME.
  */
 function previewDnsNode() {
     async function upsertAliases(ctx) {
@@ -885,7 +952,7 @@ function previewDnsNode() {
         const cf = String(output(ctx, 'cloudfront-distribution').domainName);
         const out = output(ctx, 'preview-dns');
         // Route53 refuses A/AAAA alongside a CNAME at the same name, so clear any
-        // CNAME first — a pre-0.2.1 bootstrap's (recorded in state) or an
+        // CNAME first - a pre-0.2.1 bootstrap's (recorded in state) or an
         // operator's manual workaround (pointing at the distribution). Deleting a
         // record that is not there is a no-op.
         if (out.type !== 'ALIAS') {
@@ -979,4 +1046,3 @@ export function buildNodes(ctx) {
     }
     return nodes;
 }
-//# sourceMappingURL=nodes.js.map

package/dist/plugin-commands.d.ts

@@ -0,0 +1,298 @@
+/**
+ * OWNERSHIP: this module and its test file (`plugin-commands.test.ts`) are
+ * created here, by task 10, which is their sole author for the whole plan.
+ * Tasks 13 (the generic `blogwright <plugin> init` action), 16 (the generic
+ * `bootstrap`/`status`/`destroy` lifecycle verbs) and 17 (`blogwright plugin
+ * list`) all extend the SAME dispatch surface and the SAME test file rather
+ * than re-creating either - on the plan's dependency graph none of the three
+ * later tasks depends on either of the other two, so without one named
+ * owner here, three tasks would each try to create these two files from
+ * scratch and collide. Extend this module; never recreate it.
+ *
+ * `runPlugin` is generic dispatch for `blogwright <plugin> <action>`: the
+ * fall-through `cli.ts` reaches once the first positional is neither a
+ * built-in command nor `plugin` itself (`KNOWN_COMMANDS`,
+ * `known-commands.ts`). It:
+ *
+ *   1. Runs `discover` (over the `fs`/`loader` ports the caller supplies -
+ *      see `runPlugin`'s `ports` parameter) to find the installed plugin
+ *      claiming `command` as its namespace.
+ *   2. Matches the LONGEST declared action against the leading positionals,
+ *      so a multi-word action such as `secret status` dispatches by
+ *      declaration - never by hand-rolled positional shifting. `cli.ts`'s
+ *      `runPds` branch shifted positionals to reach `secret status` and
+ *      `secret delete`; task 29 deleted it, and this step is now the only
+ *      thing that resolves a multi-word action anywhere in the CLI.
+ *   3. Resolves the environment exactly the way every built-in command
+ *      already does: the first positional left over once the action is
+ *      consumed, overridden by `--env`, defaulting to `production`.
+ *   4. Builds the ONE `OpsContext` this dispatch needs, now that the real
+ *      environment is confirmed, validates the matched plugin's OWN config
+ *      block off that context's raw `configDocument` (`resolvePluginConfig`,
+ *      `plugins.ts` - the dispatched plugin's block and no other), adapts
+ *      the context into the narrow `PluginContext` the SPI promises
+ *      (`toPluginContext`, below) with the validated block on
+ *      `pluginConfig`, and runs the matched command, mapping a normal return
+ *      to exit code 0.
+ *
+ * Steps 1-3 run BEFORE any `OpsContext` is built - see `runPlugin`'s own
+ * doc comment for why an earlier, provisional-context version of this
+ * function was wrong, not merely wasteful.
+ *
+ * TASK 13 - the generic `init` action, and PRECEDENCE. Step 2 above matches
+ * a plugin's own `commands` FIRST; the generic `init` action (`runGenericInit`,
+ * below) is only ever reached once that match has already failed AND the
+ * leading word is exactly `init`. This is the whole of §CLI → `blogwright
+ * <plugin> init`'s precedence rule: a plugin declaring its own `init`
+ * command owns whatever `blogwright <plugin> init` does, full stop - pds's
+ * `init` creates the standard.site publication record
+ * (`packages/pds/src/commands.ts:118`) and writes no config block at all,
+ * and it must never be shadowed by a generic config writer. Nothing here
+ * requires a declared `init` command to write config; the generic action
+ * applies only where NO `init` command is declared. The other half of the
+ * rule - a plugin may not declare BOTH an `init` command and an `init?(io)`
+ * contributor, because the contributor would then never run - is a
+ * discovery-time rejection in `plugins.ts`'s collision pass, not something
+ * this dispatcher has to account for: by the time a plugin reaches here it
+ * has at most one of the two.
+ *
+ * The generic action itself needs none of the AWS-reaching machinery
+ * `makeContext` builds (accountId, clients, state) - only the two ports a
+ * plugin's `init?(io)` contributor is typed against (`fs`, `terminal`) and
+ * the resolved environment/repo root `runPlugin` already has before any
+ * `OpsContext` exists. Building a real context just to splice a text file
+ * would additionally require a runnable AWS session before an operator has
+ * even finished being asked their plugin's questions - so it deliberately
+ * does not.
+ *
+ * TASK 16 - the generic `bootstrap`/`status`/`destroy` lifecycle verbs, and
+ * PRECEDENCE. Like `init`, these three are only ever reached once step 2's
+ * `matchAction` has already failed to match the plugin's own `commands` -
+ * but the precedence differs by verb:
+ *
+ *   - `bootstrap` and `destroy` are ALWAYS the generic verbs. A plugin may
+ *     not import the CLI (§CLI → Plugin dispatch), and so cannot run the
+ *     engine (`applyGraph`/`destroyGraph`, `graph.ts`) itself - there is no
+ *     way for a plugin's own `bootstrap`/`destroy` command to do what these
+ *     verbs need to do. A plugin declaring either as one of its own
+ *     `commands` is therefore rejected at discovery, naming the plugin and
+ *     the colliding action - `plugins.ts`'s `rejectDeclaredLifecycleCollisions`,
+ *     beside `rejectDeclaredInitCollisions` in the same collision pass (see
+ *     that module's DECISION note) - so `matchAction` never has a real
+ *     `bootstrap`/`destroy` command to match against in the first place.
+ *   - `status` is the generic verb ONLY UNLESS the plugin declares its own -
+ *     `read()` lives on the plugin's own nodes, no engine call is needed,
+ *     so there is nothing stopping a plugin from implementing `status`
+ *     itself (pds's `secret status` is a precedent for a plugin owning its
+ *     own status reporting). A declared `status` command is therefore left
+ *     alone: `matchAction` already matches it in step 2, and the generic
+ *     verb below is never reached for that plugin.
+ *
+ * All three are further gated on `plugin.nodes` being declared at all
+ * (`genericLifecycleCommand`, below): a plugin with no `nodes` contributor
+ * gains none of the three, and asking for one falls through to the same
+ * unknown-action refusal every other unmatched action gets - it is not a
+ * special case, because `genericLifecycleCommand` returns `undefined` for
+ * exactly that plugin, the same way an undeclared `init` contributor leaves
+ * `runGenericInit` unreached above.
+ *
+ * Each of the three runs the CLI's own engine - `applyGraph`, `destroyGraph`
+ * (`graph.ts`) and `readNodeStatus` (`commands.ts`) - over `plugin.nodes(ctx)`
+ * against a context built by `toPluginContext` (below), which by this task
+ * re-points `store`/`state`/`save()` at a `StateStore` scoped to the
+ * plugin's own name (`state/<env>.<plugin>.json`) rather than the site's.
+ * `destroy` additionally refuses without `--yes`, mirroring the site verb's
+ * own contract (`commands.ts`'s `destroy`), and deletes the scoped state
+ * object itself once `destroyGraph` has torn down every node - mirroring
+ * `commands.ts`'s own `destroy`/`previewTeardown`, both of which call
+ * `ctx.store.delete()` right after `destroyGraph`.
+ *
+ * TASK 17 - the built-in `plugin` namespace (`runPluginNamespace`, at the
+ * foot of this module) is a SECOND entry point, not an action of the generic
+ * dispatch above: `plugin` is reserved (`known-commands.ts`), so no installed
+ * plugin can claim it and `runPlugin` never sees it. It lives here because it
+ * is the same surface - the actions an operator types after `blogwright` -
+ * and shares this module's discovery call and its unknown-action refusal
+ * shape. See its own section comment for why `cli.ts` must dispatch it before
+ * `createContext`.
+ */
+import { type Plugin, type PluginContext, type Terminal } from 'blogwright-core';
+import { type ContextOptions, type OpsContext } from './context.js';
+import { type Logger } from './logger.js';
+import type { PackageManager, Ports } from './ports.js';
+/**
+ * The parsed flag values `main`'s single `parseArgs` call produces, as far
+ * as generic plugin dispatch reads them. `main` passes its own `values`
+ * object here directly - this interface only narrows what `runPlugin` reads
+ * off it, the same way `cli.ts`'s hand-rolled `PreviewValues` narrows the
+ * same shared object for itself. `PdsValues` was the other such narrowing
+ * until task 29 deleted it with the rest of the pds branch, which is why
+ * `identifier` below matters: this interface, and `serialiseFlags` under
+ * it, are now the only thing that carries `--identifier` to `pds login`.
+ */
+export interface PluginValues {
+    env?: string | undefined;
+    domain?: string | undefined;
+    config?: string | undefined;
+    endpoint?: string | undefined;
+    hash?: string | undefined;
+    id?: string | undefined;
+    identifier?: string | undefined;
+    plain: boolean;
+    refresh: boolean;
+    yes: boolean;
+    help: boolean;
+}
+/**
+ * Adapt an `OpsContext` into the narrow `PluginContext` a plugin command
+ * runs against. This is an ADAPTATION, not an assignment: an `OpsContext`
+ * carries thirteen of `PluginContext`'s sixteen members and none of
+ * `pluginConfig`, `siteState` or `record`, so a bare assignment is
+ * `TS2739`. This function supplies exactly those three - plus the
+ * two-member `ports` `PluginPorts` narrows the CLI's six-member `Ports`
+ * to, and the plugin's own scoped `store`/`state`/`save()` (below) - and
+ * passes every other member through unchanged. No cast, no `any`, anywhere
+ * in it.
+ *
+ * `pluginConfig` is supplied by the CALLER rather than read here, because
+ * this function is handed a plugin's NAME and not the plugin: `runPlugin`
+ * calls `resolvePluginConfig(plugin, ctx.configDocument)` (`plugins.ts`)
+ * first, so an invalid block fails BEFORE the scoped `store.load()` below
+ * makes the dispatch's first AWS call and long before the command does any
+ * work. The parameter is required, with no `{}` default: the dispatcher
+ * erases `TConfig` (it dispatches `Plugin<unknown>` and returns
+ * `PluginContext<unknown>`), so a forgotten argument could not be caught
+ * anywhere downstream - `pnpm typecheck` catching it here is the only
+ * check there is.
+ *
+ * `siteState` is `ops.state` passed through as the read-only view the SPI
+ * promises - a plugin reads the site's own recorded outputs through it (the
+ * analytics log-delivery node reads the site's CloudFront distribution
+ * through it), but never writes it. It is deliberately NOT the scoped load
+ * below: overwriting it would leave a plugin unable to see the site's own
+ * outputs at all.
+ *
+ * `store`, `state` and `save()` are the ONE thing this function gets that a
+ * bare assignment from `OpsContext` would not: a `StateStore` scoped to
+ * `pluginName` (`state/<env>.<pluginName>.json`, `StateStore`'s fourth
+ * constructor argument - `packages/core/src/state.ts`), its own freshly
+ * loaded `OpsState`, and a `save()` that persists THAT state through THAT
+ * store - never the site's own `state/<env>.json`. This is why the function
+ * is `async` where a straight field-for-field adaptation would not need to
+ * be: building the plugin's own `state` requires awaiting the scoped
+ * store's `load()`. Before this existed (tasks 10-15), `OpsContext`'s
+ * `store`/`state`/`save()` typechecked straight through as `PluginContext`'s
+ * of the same names with no error - the TYPES lined up even though the
+ * STORAGE did not - which is why nothing before this task may call a
+ * plugin's `nodes(ctx)`: doing so would have silently recorded a plugin's
+ * resources into the site's own state document instead of its own, and
+ * `record`, below, closes exactly that gap by writing into the scoped
+ * `state.resources` rather than the site's.
+ */
+export declare function toPluginContext(ops: OpsContext, pluginName: string, pluginConfig: unknown): Promise<PluginContext<unknown>>;
+/**
+ * The generic lifecycle verbs `plugin` actually answers, as `{ action,
+ * summary }` pairs, for the two places that LIST a plugin's actions: the
+ * unknown-action refusal ({@link renderActions}, below) and `--help`
+ * (`cli.ts`'s `renderPluginSection`). Exported for the second of those;
+ * both must list exactly what {@link genericLifecycleCommand} would
+ * dispatch, or the listing advertises a verb the dispatcher refuses (or,
+ * worse, hides one that works - the state this function was added to fix,
+ * where a nodes-only plugin's refusal printed a heading and nothing at
+ * all).
+ *
+ * Gated on `plugin.nodes` exactly as `genericLifecycleCommand` is, so a
+ * plugin with no `nodes` contributor advertises none of the three. A verb
+ * the plugin declares ITSELF is omitted here rather than listed twice: only
+ * `status` can be declared (`bootstrap`/`destroy` are rejected at
+ * discovery, `plugins.ts`'s `rejectDeclaredLifecycleCollisions`), and its
+ * own command already appears in the caller's declared-command lines -
+ * where `matchAction`'s precedence means that is the one that actually
+ * runs.
+ */
+export declare function genericLifecycleActions(plugin: Plugin<unknown>): {
+    action: string;
+    summary: string;
+}[];
+/**
+ * Handle `blogwright <command> <action> [env] [args]` once `command` has
+ * failed the `KNOWN_COMMANDS` membership test - i.e. it is either an
+ * installed plugin's namespace or entirely unknown.
+ *
+ * `ports` - the `fs`/`loader` pair `discover` needs - is supplied by the
+ * caller (`cli.ts`, from a small factory `bin.ts` wires to the real
+ * adapters) rather than read off an `OpsContext` built here. An EARLIER
+ * version of this function built a throwaway `OpsContext` first (via
+ * `makeContext`, guessing `production` or `--env`'s value) purely to reach
+ * its `ports.fs`/`ports.loader` for discovery, then rebuilt a second
+ * context once the real environment was known. That guess was not merely
+ * wasteful - it was WRONG on a repo whose only config file is for a
+ * non-default environment: `blogwright <plugin> <action> staging` on a repo
+ * with `config/staging.jsonc` and neither `config/production.jsonc` nor
+ * `ops.config.jsonc` made the throwaway build's `loadConfig` call
+ * (`context.ts`) throw `no config found for environment "production"` -
+ * naming an environment the operator never asked for, before the real one
+ * (`staging`) was ever read off the positionals. That is worse than the
+ * silent fallback-to-production this dispatcher exists to avoid, because
+ * the message actively misleads.
+ *
+ * `discover` only ever needed `Pick<Ports, 'fs' | 'loader'>` - both of which
+ * `createContext` builds BEFORE it loads any config (`context.ts`), and
+ * `cli.ts`'s `init` branch already constructs a `FileSystem` directly with
+ * no context at all - so threading the same two ports in from the caller
+ * removes the guess completely: the environment is resolved from
+ * `command`'s matched action BEFORE any `OpsContext` - throwaway or real -
+ * is built, and exactly one `makeContext` call happens, with the confirmed
+ * environment, reusing the SAME `fs`/`loader` discovery already used rather
+ * than letting a second call default fresh ones.
+ *
+ * EXIT CODES, and a deliberate deviation tasks 13/16/17 must not assume away.
+ * This task's definition of done asks that "a plugin command's return value
+ * maps to the process exit code". It cannot: `PluginCommand.run` is declared
+ * `Promise<void>` (`blogwright-core`'s `plugin.ts`), and the change spec names
+ * no return-code channel. So there is no value to map. What this dispatcher
+ * owns it returns - 0 once `run` resolves, 1 for an unknown plugin and 1 for an
+ * unknown action - and a command that genuinely fails signals it by REJECTING,
+ * which propagates to `bin.ts`'s error path. Adding actions here (tasks 13, 16,
+ * 17) means following that contract: reject to fail, do not invent a numeric
+ * return the SPI has nowhere to carry.
+ */
+export declare function runPlugin(command: string, rest: string[], values: PluginValues, terminal: Terminal, logger: Logger, makeContext: (opts: ContextOptions) => Promise<OpsContext>, ports: Pick<Ports, 'fs' | 'loader'>): Promise<number>;
+/**
+ * What `add` and `remove` need beyond the `fs`/`loader` pair `list` runs on.
+ * A single object rather than four more positional parameters, and every
+ * member is a FACTORY or a value rather than a live port, so a refusal path
+ * pays for none of them:
+ *
+ *   - `values` - the same parsed flags `runPlugin` reads (`--yes`, `--env`,
+ *     and the context overrides `remove`'s teardown branch forwards).
+ *   - `makePackages` - the `PackageManager` port, built at the composition
+ *     root. Called at most once per invocation, and never by `list` or by any
+ *     refusal.
+ *   - `cliVersion` - the running CLI's own version (`context.ts`'s
+ *     `cliVersion`), resolved there because this module may not touch
+ *     `node:fs`. Called only once `add` has decided it is going to install
+ *     something.
+ *   - `makeContext` - the ONE `OpsContext` `remove`'s "tear it down first"
+ *     branch needs, and the only path in this namespace that builds one at
+ *     all. Never called for `add`, for `list`, or for a `remove` that does
+ *     not run a teardown.
+ */
+export interface PluginNamespaceDeps {
+    readonly values: PluginValues;
+    readonly makePackages: () => PackageManager;
+    readonly cliVersion: () => Promise<string>;
+    readonly makeContext: (opts: ContextOptions) => Promise<OpsContext>;
+}
+/**
+ * Handle `blogwright plugin <action>`. Dispatched by `cli.ts` ahead of any
+ * `OpsContext` - see this section's own comment above for why that placement
+ * is load-bearing rather than merely tidy.
+ *
+ * An absent or unrecognised action lists the namespace's actions and returns
+ * 1, the same shape `runPlugin` refuses an unknown action of an installed
+ * plugin in. `add` and `remove` share this function's name resolution and
+ * validation - one gate, so the two verbs cannot disagree about what
+ * `analytics` means or about what is a package name at all.
+ */
+export declare function runPluginNamespace(rest: readonly string[], terminal: Terminal, logger: Logger, ports: Pick<Ports, 'fs' | 'loader'>, deps: PluginNamespaceDeps): Promise<number>;