blogwright-pds 0.3.3 → 0.4.0-beta.0

package/dist/client-metadata.d.ts

@@ -8,8 +8,8 @@ import type { OAuthClientMetadataInput } from '@atproto/oauth-client-node';
 import type { OpsConfig, PdsConfig } from 'blogwright-core';
 /**
  * Repo-relative paths of the committed OAuth client documents. The segments
- * under the public dir are protocol-fixed — they must mirror the URL paths in
- * the client metadata — so only the public dir itself is configurable.
+ * under the public dir are protocol-fixed - they must mirror the URL paths in
+ * the client metadata - so only the public dir itself is configurable.
  */
 export declare function clientDocumentPaths(cfg: Pick<OpsConfig, 'paths'>): {
     clientMetadata: string;
@@ -22,7 +22,7 @@ export declare function jwksUrl(domain: string): string;
 export declare function callbackUrl(domain: string): string;
 /** The client metadata document served at clientMetadataUrl(domain). */
 export declare function clientMetadata(domain: string, pds: PdsConfig): OAuthClientMetadataInput;
-/** The JWKS document served at jwksUrl(domain) — public key material only. */
+/** The JWKS document served at jwksUrl(domain) - public key material only. */
 export declare function jwksDocument(publicJwk: Record<string, unknown>): {
     keys: [typeof publicJwk];
 };

package/dist/client-metadata.js

@@ -6,8 +6,8 @@
  */
 /**
  * Repo-relative paths of the committed OAuth client documents. The segments
- * under the public dir are protocol-fixed — they must mirror the URL paths in
- * the client metadata — so only the public dir itself is configurable.
+ * under the public dir are protocol-fixed - they must mirror the URL paths in
+ * the client metadata - so only the public dir itself is configurable.
  */
 export function clientDocumentPaths(cfg) {
     return {
@@ -43,7 +43,7 @@ export function clientMetadata(domain, pds) {
         jwks_uri: jwksUrl(domain),
     };
 }
-/** The JWKS document served at jwksUrl(domain) — public key material only. */
+/** The JWKS document served at jwksUrl(domain) - public key material only. */
 export function jwksDocument(publicJwk) {
     if (publicJwk.d !== undefined)
         throw new Error('jwksDocument received a private JWK (has "d")');

package/dist/commands.d.ts

@@ -3,7 +3,7 @@ import { generateClientKey, login as oauthLogin, openPdsRepo, verifyClientAssets
 import { type OpenRepo, type SyncSummary } from './sync.js';
 /**
  * Generate the OAuth confidential-client key: private JWK into the secret
- * (clearing any session — client auth is bound to the key), public half into
+ * (clearing any session - client auth is bound to the key), public half into
  * the two committed /oauth/ documents the site serves.
  */
 export declare function keygen(ctx: PdsContext, repoRoot?: string, generateKey?: typeof generateClientKey): Promise<void>;
@@ -19,7 +19,7 @@ export declare function secretDelete(ctx: PdsContext, opts: {
 }): Promise<void>;
 /**
  * One-time (idempotent) publication setup: create the site.standard.publication
- * record — or update it when the committed well-known file already names one — and
+ * record - or update it when the committed well-known file already names one - and
  * write the two site files the user commits.
  */
 export declare function init(ctx: PdsContext, repoRoot?: string, openRepo?: typeof openPdsRepo, verifyAssets?: typeof verifyClientAssets): Promise<void>;
@@ -27,7 +27,7 @@ export declare function init(ctx: PdsContext, repoRoot?: string, openRepo?: type
 export declare function sync(ctx: PdsContext, repoRoot?: string, openRepo?: OpenRepo): Promise<void>;
 /**
  * Post-deploy hook: reconcile the PDS after a successful production deploy.
- * Never fatal — a PDS outage must not fail a good site deploy; the next deploy
+ * Never fatal - a PDS outage must not fail a good site deploy; the next deploy
  * re-reconciles. No-op unless production, configured, and initialised.
  */
 export declare function syncAfterDeploy(ctx: PdsContext, repoRoot?: string, doSync?: (ctx: PdsContext, repoRoot: string) => Promise<SyncSummary>): Promise<void>;

package/dist/commands.js

@@ -7,7 +7,7 @@ import { PUBLICATION_COLLECTION, publicationRecord, readWellKnownUri, requirePds
 import { rkeyFromUri } from './xrpc.js';
 /**
  * Generate the OAuth confidential-client key: private JWK into the secret
- * (clearing any session — client auth is bound to the key), public half into
+ * (clearing any session - client auth is bound to the key), public half into
  * the two committed /oauth/ documents the site serves.
  */
 export async function keygen(ctx, repoRoot, generateKey = generateClientKey) {
@@ -18,7 +18,7 @@ export async function keygen(ctx, repoRoot, generateKey = generateClientKey) {
     const kid = `${ctx.config.siteName}-oauth-${new Date().toISOString().slice(0, 10)}`;
     const clientKey = await generateKey(kid);
     await updatePdsSecret(ctx.clients.secrets, pds.secretName, (secret) => ({ ...secret, clientKey, session: undefined }), 
-    // keygen is the migration entry point — a legacy app-password value is replaced
+    // keygen is the migration entry point - a legacy app-password value is replaced
     { replaceLegacy: true, tags: ctx.tags });
     ctx.logger.ok(`stored private key "${kid}" in secret "${pds.secretName}"`);
     const docPaths = clientDocumentPaths(ctx.config);
@@ -30,7 +30,7 @@ export async function keygen(ctx, repoRoot, generateKey = generateClientKey) {
         await ctx.ports.fs.writeText(join(root, path), `${JSON.stringify(body, null, 2)}\n`);
         ctx.logger.info(`  wrote ${path}`);
     }
-    ctx.logger.info(colors.bold(`Commit ${ctx.config.paths.publicDir}/oauth/* and release — then run \`blogwright pds login\`.`));
+    ctx.logger.info(colors.bold(`Commit ${ctx.config.paths.publicDir}/oauth/* and release - then run \`blogwright pds login\`.`));
 }
 /** Interactive OAuth bootstrap; see oauth.ts#login for the flow. */
 export async function login(ctx, opts, runLogin = oauthLogin) {
@@ -46,7 +46,7 @@ export async function secretStatus(ctx) {
     const pds = requirePdsConfig(ctx);
     const meta = await ctx.clients.secrets.describeSecret(pds.secretName);
     if (!meta) {
-        ctx.logger.info(`no secret at "${pds.secretName}" — create it with \`blogwright pds keygen\``);
+        ctx.logger.info(`no secret at "${pds.secretName}" - create it with \`blogwright pds keygen\``);
         return;
     }
     ctx.logger.info(`  name          ${meta.name}`);
@@ -75,7 +75,7 @@ export async function secretDelete(ctx, opts) {
 }
 /**
  * One-time (idempotent) publication setup: create the site.standard.publication
- * record — or update it when the committed well-known file already names one — and
+ * record - or update it when the committed well-known file already names one - and
  * write the two site files the user commits.
  */
 export async function init(ctx, repoRoot, openRepo = openPdsRepo, verifyAssets = verifyClientAssets) {
@@ -92,7 +92,7 @@ export async function init(ctx, repoRoot, openRepo = openPdsRepo, verifyAssets =
         // would publish document records that point at a publication this account
         // does not own, silently breaking standard.site verification.
         throw new Error(`${wellKnownPath(ctx.config)} points at ${existingUri}, which belongs to a different ` +
-            `account than ${did} — delete the file to create a fresh publication, or log in ` +
+            `account than ${did} - delete the file to create a fresh publication, or log in ` +
             `with the owning account`);
     }
     let publicationUri;
@@ -111,7 +111,7 @@ export async function init(ctx, repoRoot, openRepo = openPdsRepo, verifyAssets =
     await ctx.ports.fs.writeText(join(root, ctx.config.paths.atprotoJson), `${JSON.stringify({ did, publicationUri }, null, 2)}\n`);
     ctx.logger.info(`  wrote ${wellKnown}`);
     ctx.logger.info(`  wrote ${ctx.config.paths.atprotoJson}`);
-    ctx.logger.info(colors.bold('Commit both files and deploy — they verify the publication and the post link tags.'));
+    ctx.logger.info(colors.bold('Commit both files and deploy - they verify the publication and the post link tags.'));
 }
 /** Reconcile PDS records against local content. Production only. */
 export async function sync(ctx, repoRoot, openRepo = openPdsRepo) {
@@ -130,13 +130,13 @@ function logSummary(ctx, s) {
     for (const slug of s.updated)
         ctx.logger.info(`  updated  ${slug}`);
     if (s.orphans.length > 0) {
-        ctx.logger.warn(`${s.orphans.length} PDS record(s) have no local post (rkeys: ${s.orphans.join(', ')}) — ` +
+        ctx.logger.warn(`${s.orphans.length} PDS record(s) have no local post (rkeys: ${s.orphans.join(', ')}) - ` +
             'not deleted; remove them manually if intended');
     }
 }
 /**
  * Post-deploy hook: reconcile the PDS after a successful production deploy.
- * Never fatal — a PDS outage must not fail a good site deploy; the next deploy
+ * Never fatal - a PDS outage must not fail a good site deploy; the next deploy
  * re-reconciles. No-op unless production, configured, and initialised.
  */
 export async function syncAfterDeploy(ctx, repoRoot, doSync = (c, r) => syncPds(c, r, openPdsRepo)) {
@@ -145,7 +145,7 @@ export async function syncAfterDeploy(ctx, repoRoot, doSync = (c, r) => syncPds(
     const root = repoRoot ?? (await findRepoRoot(ctx.ports.fs));
     const initialised = await readWellKnownUri(ctx.ports.fs, root, ctx.config).catch(() => undefined);
     if (!initialised) {
-        ctx.logger.info('standard.site publishing not initialised (`blogwright pds init`) — skipping');
+        ctx.logger.info('standard.site publishing not initialised (`blogwright pds init`) - skipping');
         return;
     }
     try {

package/dist/config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * This package owns the `pds` config key end to end: validating the block
+ * core's `parseConfig` hands off unvalidated, and deriving the
+ * `<siteName>/atproto` default `secretName`.
+ *
+ * `validatePdsConfig` and `resolvePdsSecretName` were lifted verbatim from
+ * `packages/core/src/config.ts` (the `cfg.pds` branch of `validateConfig` and
+ * the `secretName` line of `mergeConfig`) - same checks, same message
+ * strings, same `new URL(...)` try/catch ordering, so a non-URL resolver
+ * still reports "must be a URL" before an `http://` one reports "must be
+ * https". Core's copies are now gone: these are the only ones.
+ *
+ * One case core never had to answer is answered here: an ABSENT block. Core
+ * gated its checks behind `if (cfg.pds)`, so nothing validated a document
+ * with no `pds` key; the host now calls a plugin's validator with
+ * `undefined` in exactly that case, and {@link NO_PDS_SECTION_MESSAGE} is
+ * what this package returns to an operator for it.
+ */
+import type { PdsConfig } from 'blogwright-core';
+/**
+ * A `pds` config block whose `secretName` has been resolved: never absent,
+ * where core's own `PdsConfig` declares it optional because core no longer
+ * defaults it. `requirePdsConfig` (`sync.ts`) returns this - built from
+ * {@link resolvePdsSecretName} - so every call site downstream keeps a total
+ * type on `secretName` with no cast and no `!`.
+ */
+export interface ResolvedPdsConfig extends PdsConfig {
+    secretName: string;
+}
+/**
+ * What an ABSENT `pds` block reports. The same sentence `requirePdsConfig`
+ * (`sync.ts`) has always raised for a repo that has not written one, declared
+ * here and imported there so the two refusals cannot drift into two different
+ * sentences for one situation - whichever of them an operator happens to
+ * reach first.
+ */
+export declare const NO_PDS_SECTION_MESSAGE = "config has no \"pds\" section - add it to config/production.jsonc";
+/**
+ * Validate a raw `pds` config block, boundary-checked as `unknown` because it
+ * comes off `parseConfigDocument`'s `raw` half (a plugin's block has no type
+ * until its own package narrows it). Throws with the same message strings
+ * core's `validateConfig` raises today for these checks.
+ */
+export declare function validatePdsConfig(raw: unknown): PdsConfig;
+/**
+ * Resolve the secret name a `pds` block uses: the explicit `secretName` when
+ * present, otherwise `<siteName>/atproto`.
+ */
+export declare function resolvePdsSecretName(pds: PdsConfig, siteName: string): string;

package/dist/config.js

@@ -0,0 +1,94 @@
+/**
+ * This package owns the `pds` config key end to end: validating the block
+ * core's `parseConfig` hands off unvalidated, and deriving the
+ * `<siteName>/atproto` default `secretName`.
+ *
+ * `validatePdsConfig` and `resolvePdsSecretName` were lifted verbatim from
+ * `packages/core/src/config.ts` (the `cfg.pds` branch of `validateConfig` and
+ * the `secretName` line of `mergeConfig`) - same checks, same message
+ * strings, same `new URL(...)` try/catch ordering, so a non-URL resolver
+ * still reports "must be a URL" before an `http://` one reports "must be
+ * https". Core's copies are now gone: these are the only ones.
+ *
+ * One case core never had to answer is answered here: an ABSENT block. Core
+ * gated its checks behind `if (cfg.pds)`, so nothing validated a document
+ * with no `pds` key; the host now calls a plugin's validator with
+ * `undefined` in exactly that case, and {@link NO_PDS_SECTION_MESSAGE} is
+ * what this package returns to an operator for it.
+ */
+/** Characters permitted in a Secrets Manager secret name. */
+const SECRET_NAME_PATTERN = /^[\w/+=.@-]+$/;
+/**
+ * What an ABSENT `pds` block reports. The same sentence `requirePdsConfig`
+ * (`sync.ts`) has always raised for a repo that has not written one, declared
+ * here and imported there so the two refusals cannot drift into two different
+ * sentences for one situation - whichever of them an operator happens to
+ * reach first.
+ */
+export const NO_PDS_SECTION_MESSAGE = 'config has no "pds" section - add it to config/production.jsonc';
+/** Template pds's default `secretName` is derived from - the one home for it in this package. */
+function defaultSecretName(siteName) {
+    return `${siteName}/atproto`;
+}
+/**
+ * Validate a raw `pds` config block, boundary-checked as `unknown` because it
+ * comes off `parseConfigDocument`'s `raw` half (a plugin's block has no type
+ * until its own package narrows it). Throws with the same message strings
+ * core's `validateConfig` raises today for these checks.
+ */
+export function validatePdsConfig(raw) {
+    // ABSENT is not MALFORMED, and the two want different sentences. The host
+    // calls this with `undefined` whenever the document carries no `pds` key
+    // (`resolvePluginConfig`, `packages/cli/src/plugins.ts`) - deliberately, so
+    // a plugin with derivable defaults can supply them. This plugin has none:
+    // `name` is an operator's choice and nothing can invent it, so an absent
+    // block is a refusal. But it is the ORDINARY first-run refusal, not a
+    // defect in a block that was written, so it names the missing section and
+    // how to create it rather than a key inside a block that does not exist.
+    // Without this guard the first statement below dereferences `undefined` and
+    // the operator gets a bare `TypeError` instead (the defect task 29's
+    // changeset named as a known issue).
+    //
+    // `null` joins `undefined` because that is the behaviour a `"pds": null`
+    // document has always had: core's own check was gated behind `if (cfg.pds)`
+    // and skipped it, and `requirePdsConfig`'s `if (!pds)` then reported it as
+    // an absent section. Every other present value stays MALFORMED and falls
+    // through to the key-naming checks below, which is where a string, a number
+    // or an array already reported `config.pds.name is required`.
+    if (raw === undefined || raw === null)
+        throw new Error(NO_PDS_SECTION_MESSAGE);
+    const cfg = raw;
+    if (!cfg.name?.trim())
+        throw new Error('config.pds.name is required');
+    if (cfg.handleResolver !== undefined) {
+        let resolver;
+        try {
+            resolver = new URL(cfg.handleResolver);
+        }
+        catch {
+            throw new Error(`config.pds.handleResolver must be a URL, got "${cfg.handleResolver}"`);
+        }
+        if (resolver.protocol !== 'https:') {
+            throw new Error(`config.pds.handleResolver must be https, got "${cfg.handleResolver}"`);
+        }
+    }
+    // `secretName` is optional on `PdsConfig` now that core no longer defaults
+    // it, so the character class applies only to a value that is actually
+    // present. An absent one is not malformed - it selects the
+    // `<siteName>/atproto` default `resolvePdsSecretName` supplies, which
+    // trivially satisfies the class. The guard is a narrowing, not a behaviour
+    // change: the previous unguarded call handed `undefined` to `RegExp.test`,
+    // which coerced it to the string "undefined" and matched, so an absent
+    // `secretName` passed this check before the guard existed too.
+    if (cfg.secretName !== undefined && !SECRET_NAME_PATTERN.test(cfg.secretName)) {
+        throw new Error(`config.pds.secretName has invalid characters: "${cfg.secretName}"`);
+    }
+    return cfg;
+}
+/**
+ * Resolve the secret name a `pds` block uses: the explicit `secretName` when
+ * present, otherwise `<siteName>/atproto`.
+ */
+export function resolvePdsSecretName(pds, siteName) {
+    return pds.secretName ?? defaultSecretName(siteName);
+}

package/dist/content.d.ts

@@ -4,7 +4,7 @@ export interface PostMeta {
     /**
      * Content-collection id: frontmatter `slug` when set, else the file path
      * under the content dir minus its `.md`/`.mdx` extension and any trailing
-     * `/index` segment — matching the id Astro's glob loader produces.
+     * `/index` segment - matching the id Astro's glob loader produces.
      */
     slug: string;
     title: string;
@@ -14,14 +14,14 @@ export interface PostMeta {
 /**
  * Parse the flat frontmatter subset used by src/content.config.ts: scalar
  * `key: value` lines where value is a bare token, a quoted string, a date, or a
- * boolean. Deliberately not a YAML parser — the schema is flat by construction.
+ * boolean. Deliberately not a YAML parser - the schema is flat by construction.
  */
 export declare function parseFrontmatter(source: string, file: string): Record<string, string>;
 /**
  * Enumerate publishable posts from the content collection, mirroring the Astro
  * glob-loader ids: `.md`/`.mdx` files, a frontmatter `slug` wins outright, a
  * trailing `/index` segment is dropped, drafts excluded. (Astro additionally
- * github-slugifies unusual path segments — keep file names lowercase-kebab, as
+ * github-slugifies unusual path segments - keep file names lowercase-kebab, as
  * the rkey derived here must match the id the site builds its link tags from.)
  */
 export declare function listPublishablePosts(fs: FileSystem, repoRoot: string, contentDir?: string): Promise<PostMeta[]>;

package/dist/content.js

@@ -5,7 +5,7 @@ const REQUIRED_FIELDS = ['title', 'description', 'pubDate'];
 /**
  * Parse the flat frontmatter subset used by src/content.config.ts: scalar
  * `key: value` lines where value is a bare token, a quoted string, a date, or a
- * boolean. Deliberately not a YAML parser — the schema is flat by construction.
+ * boolean. Deliberately not a YAML parser - the schema is flat by construction.
  */
 export function parseFrontmatter(source, file) {
     const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
@@ -34,7 +34,7 @@ export function parseFrontmatter(source, file) {
  * Enumerate publishable posts from the content collection, mirroring the Astro
  * glob-loader ids: `.md`/`.mdx` files, a frontmatter `slug` wins outright, a
  * trailing `/index` segment is dropped, drafts excluded. (Astro additionally
- * github-slugifies unusual path segments — keep file names lowercase-kebab, as
+ * github-slugifies unusual path segments - keep file names lowercase-kebab, as
  * the rkey derived here must match the id the site builds its link tags from.)
  */
 export async function listPublishablePosts(fs, repoRoot, contentDir = DEFAULT_CONTENT_DIR) {

package/dist/context.d.ts

@@ -1,32 +1,42 @@
 /**
- * The narrow slice of the host CLI's context this feature package depends on.
- * The CLI's OpsContext satisfies it structurally, so the dispatch boundary is
- * a plain assignment — this package never imports CLI types.
+ * The narrow slice of the host CLI's context this feature package depends on,
+ * expressed as a narrowing of core's `PluginContext`. The CLI's `OpsContext`
+ * satisfies it structurally, so the dispatch boundary is a plain assignment -
+ * this package never imports CLI types.
  */
-import type { FileSystem, OpsConfig, SecretsManagerClient, Terminal } from 'blogwright-core';
-/** Leveled logger surface the pds commands report through. */
-export interface PdsLogger {
-    info(msg: string): void;
-    step(msg: string): void;
-    ok(msg: string): void;
-    warn(msg: string): void;
-    error(msg: string): void;
-}
-/** The ports the pds feature crosses: repo files and the operator's terminal. */
-export interface PdsPorts {
-    fs: FileSystem;
-    terminal: Terminal;
-}
-/** Everything a pds command needs from its host — config, secrets, ports, logging. */
-export interface PdsContext {
-    env: string;
-    domain: string | undefined;
-    config: OpsConfig;
+import type { PdsConfig, PluginContext, PluginLogger, PluginPorts, SecretsManagerClient } from 'blogwright-core';
+/** Leveled logger surface the pds commands report through - core's `PluginLogger`. */
+export type PdsLogger = PluginLogger;
+/** The ports the pds feature crosses: repo files and the operator's terminal - core's `PluginPorts`. */
+export type PdsPorts = PluginPorts;
+/**
+ * Everything a pds command needs from its host - config, secrets, ports,
+ * logging. A `Pick` over core's `PluginContext<PdsConfig>` of exactly the
+ * members pds uses today - `env`, `domain`, `config`, `ports` (already
+ * exactly the `fs`/`terminal` pair `PluginPorts` names), `logger` and
+ * optional `tags` - plus `clients`, narrowed here to the one client pds
+ * calls rather than picked verbatim: `PluginContext.clients` is the full
+ * `AwsClients`, and `test-support.ts` builds a context supplying only
+ * `secrets`.
+ *
+ * Everything else on `PluginContext` is left out on purpose. `preview`,
+ * `names` and `accountId` are host surface pds has never needed.
+ * `pluginConfig`, `state`, `store`, `siteState`, `record()` and `save()` are
+ * all built at a dispatch boundary that no pds command function runs behind:
+ * `deploy` calls `syncAfterDeploy(ctx)` with a plain `OpsContext`
+ * (`packages/cli/src/commands.ts`), which has none of them, so picking any
+ * of the six would break that call. The plugin's one resource node
+ * (`nodes.ts`) takes a full `PluginContext<PdsConfig>` instead, because only
+ * the lifecycle verbs have a dispatch boundary to build one.
+ *
+ * `Pick`, never `Omit`: an `Omit` of those six dispatch-boundary members
+ * from `PluginContext`'s sixteen would drag `preview`, `names` and
+ * `accountId` back in, and `createTestContext`
+ * (`packages/pds/src/test-support.ts`) would have to fabricate a whole
+ * `Names` to keep compiling.
+ */
+export interface PdsContext extends Pick<PluginContext<PdsConfig>, 'env' | 'domain' | 'config' | 'ports' | 'logger' | 'tags'> {
     clients: {
         secrets: SecretsManagerClient;
     };
-    ports: PdsPorts;
-    logger: PdsLogger;
-    /** Resource tags the host applies to created AWS resources (the secret). */
-    tags?: Record<string, string> | undefined;
 }

package/dist/context.js

@@ -1,6 +1,7 @@
 /**
- * The narrow slice of the host CLI's context this feature package depends on.
- * The CLI's OpsContext satisfies it structurally, so the dispatch boundary is
- * a plain assignment — this package never imports CLI types.
+ * The narrow slice of the host CLI's context this feature package depends on,
+ * expressed as a narrowing of core's `PluginContext`. The CLI's `OpsContext`
+ * satisfies it structurally, so the dispatch boundary is a plain assignment -
+ * this package never imports CLI types.
  */
 export {};

package/dist/index.d.ts

@@ -2,6 +2,21 @@
  * Public surface of blogwright-pds: the pds command entry points the CLI
  * dispatches to, plus the context types that name the dependency boundary.
  * The rkey implementation is the separate `blogwright-pds/rkey` subpath.
+ *
+ * The default export is the package's `Plugin` declaration (`plugin.ts`) -
+ * the whole SPI surface in one object. It sits BESIDE the named exports, not
+ * instead of them, though the split is now lopsided: since task 29 deleted
+ * the CLI's `runPds` branch, the six command functions reach `blogwright pds
+ * <action>` through the default export's declared commands, not by name, and
+ * `syncAfterDeploy` is the one named export the CLI's shipped code still
+ * imports at runtime - the post-deploy sync, which has no lifecycle hook in
+ * the SPI to carry it (see the import comment in the CLI's `commands.ts`).
+ * The type exports below are load-bearing too, not dead surface: the CLI's
+ * `context.test.ts` imports `PdsContext` to assert `OpsContext` still
+ * satisfies it by plain assignment. The command functions stay exported as
+ * this package's own public API; `plugin.ts` builds its declarations from
+ * them.
  */
 export * from './commands.js';
 export type { PdsContext, PdsLogger, PdsPorts } from './context.js';
+export { default } from './plugin.js';

package/dist/index.js

@@ -2,5 +2,20 @@
  * Public surface of blogwright-pds: the pds command entry points the CLI
  * dispatches to, plus the context types that name the dependency boundary.
  * The rkey implementation is the separate `blogwright-pds/rkey` subpath.
+ *
+ * The default export is the package's `Plugin` declaration (`plugin.ts`) -
+ * the whole SPI surface in one object. It sits BESIDE the named exports, not
+ * instead of them, though the split is now lopsided: since task 29 deleted
+ * the CLI's `runPds` branch, the six command functions reach `blogwright pds
+ * <action>` through the default export's declared commands, not by name, and
+ * `syncAfterDeploy` is the one named export the CLI's shipped code still
+ * imports at runtime - the post-deploy sync, which has no lifecycle hook in
+ * the SPI to carry it (see the import comment in the CLI's `commands.ts`).
+ * The type exports below are load-bearing too, not dead surface: the CLI's
+ * `context.test.ts` imports `PdsContext` to assert `OpsContext` still
+ * satisfies it by plain assignment. The command functions stay exported as
+ * this package's own public API; `plugin.ts` builds its declarations from
+ * them.
  */
 export * from './commands.js';
+export { default } from './plugin.js';

package/dist/nodes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The resource topography this plugin owns: one node attaching a
+ * `blogwright-pds`-named **inline policy** to the site's GitHub-OIDC deploy
+ * role, granting Secrets Manager access to the plugin's own secret.
+ *
+ * The grant lives here rather than in the site's resource graph because it is
+ * plugin topography: the site graph currently branches on `ctx.config.pds` and
+ * interpolates this plugin's secret name into an IAM ARN
+ * (`packages/cli/src/nodes.ts`), which is the CLI knowing something only this
+ * package should know. Moving it here is safe because IAM inline policies are
+ * *named*: the site's `<env>-deploy` document and this plugin's
+ * `blogwright-pds` document are independent objects on the same role, created,
+ * reconciled and removed with no read of each other. That is what makes the
+ * migration additive - both grants are live at once until the site's statement
+ * is removed a release later - and it is why `delete()` can safely remove this
+ * document without touching the role's own.
+ *
+ * The node's own state (the site's deploy role) is not something this plugin
+ * creates, so `read()` never reports the role - only whether the policy this
+ * plugin owns is attached to it.
+ */
+import type { PdsConfig, PluginContext, ResourceNode } from 'blogwright-core';
+/**
+ * A node in this plugin's own graph. Instantiated on the context the
+ * lifecycle verbs build (`PluginContext<PdsConfig>`), not on the SPI's bare
+ * `ResourceNode` default (`PluginContext<never>`), so a caller - the plugin's
+ * `nodes(ctx)` member, or a test - can invoke a node's methods with the very
+ * context it was handed. `ResourceNode`'s methods are method-declared and
+ * therefore bivariant in their parameter, so this is still assignable to the
+ * `ResourceNode[]` `Plugin.nodes` declares.
+ */
+type PdsNode = ResourceNode<PluginContext<PdsConfig>>;
+/**
+ * The nodes `blogwright-pds` contributes, for the plugin's `nodes(ctx)` member
+ * to return.
+ *
+ * Empty - a no-op `pds bootstrap`, not a failure - in three cases:
+ *
+ * 1. The site configures no `pds` block.
+ * 2. `config.githubRepo` is unset. A non-preview site graph only adds the
+ *    deploy role when it is set (`packages/cli/src/nodes.ts`), so such a site
+ *    is fully bootstrapped and simply has no role to attach to.
+ * 3. The target environment is the shared **preview** stack. That one is a
+ *    privilege boundary, not an absence: the preview stack's role does exist
+ *    (`buildNodes` adds `githubOidcRoleNode(true)` for it unconditionally),
+ *    but its OIDC trust policy accepts the subject claim `repo:<owner>/<repo>:*`
+ *    - **any ref** - where production accepts only the release-gated
+ *    `repo:...:environment:production` (`oidcSubClaim`). The site's own graph
+ *    withholds exactly this Secrets Manager statement from that role for that
+ *    reason, and `resolvePdsSecretName` is environment-independent
+ *    (`<siteName>/atproto`), so there is ONE PDS credential for the whole
+ *    site: granting it here would let anyone who can push a branch read or
+ *    rotate the site's ATProto session. `staging` is NOT a preview stack -
+ *    the site already grants it this statement - so the skip is on the
+ *    preview environment specifically, never on "not production".
+ *
+ * The preview check is `ctx.env === PREVIEW_ENV` and deliberately **not**
+ * `ctx.preview`, which would be dead code here: `runPlugin` builds its
+ * `ContextOptions` with no `preview` key at all
+ * (`packages/cli/src/plugin-commands.ts`), `createContext` defaults the flag to
+ * `false` (`context.ts`) and `toPluginContext` copies it, so `ctx.preview` is
+ * `false` for every plugin context the CLI builds - including the one
+ * `blogwright pds bootstrap --env preview` produces. `ctx.env` is what carries
+ * the stack's identity into a plugin.
+ *
+ * The `pds` block is read from `ctx.config`, not `ctx.pluginConfig`: core's
+ * `OpsConfig` still declares `pds` as a typed member (it keeps the type after
+ * the validation moves here), and the CLI does not populate `pluginConfig`
+ * from a plugin's own validator until later in this migration.
+ */
+export declare function buildPdsNodes(ctx: PluginContext<PdsConfig>): PdsNode[];
+export {};