blogwright-pds 0.3.2 → 0.4.0-beta.0

package/dist/nodes.js

@@ -0,0 +1,177 @@
+/**
+ * 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 { resolvePdsSecretName } from './config.js';
+/** The graph id this plugin records the grant under, in its own scoped state. */
+const NODE_ID = 'pds-oidc-policy';
+/**
+ * The inline policy's name on the role. Deliberately the **package** name and
+ * not the `pds` CLI namespace: this string is on-the-wire IAM state that
+ * `delete()` has to find again through `listRolePolicies` on a later run, while
+ * a namespace is a local label a manifest can re-declare (core's
+ * `resolveNamespaceCollisions` renames a colliding one). A rename of the
+ * namespace must not orphan a live IAM object.
+ */
+const POLICY_NAME = 'blogwright-pds';
+/**
+ * The site graph's node id for the GitHub OIDC deploy role
+ * (`packages/cli/src/nodes.ts`). Only the role's ARN is recorded there, which
+ * is why the *name* comes from `ctx.names.githubRole` and this id is used only
+ * to confirm the site has been bootstrapped.
+ */
+const SITE_OIDC_ROLE_NODE = 'gh-oidc-role';
+/**
+ * The shared preview stack's environment name - the one environment this grant
+ * must never reach. The CLI spells it as a literal at its single call site
+ * (`runPreview`, `packages/cli/src/cli.ts`), so there is no exported constant
+ * to import; see {@link buildPdsNodes} for why the skip is written against
+ * `ctx.env` and not `ctx.preview`.
+ */
+const PREVIEW_ENV = 'preview';
+/** The three actions the post-deploy PDS sync needs: it reads the OAuth secret and writes the rotated session back. */
+const SECRET_ACTIONS = [
+    'secretsmanager:GetSecretValue',
+    'secretsmanager:PutSecretValue',
+    'secretsmanager:CreateSecret',
+];
+/**
+ * The policy document, scoped to this plugin's own secret. The trailing `-*`
+ * matches the six random characters Secrets Manager appends to a secret's ARN.
+ * A `*` resource here would hand the deploy role every secret in the account,
+ * including every other plugin's - the scoping is the point of the node.
+ */
+function policyDocument(ctx, secretName) {
+    return {
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Effect: 'Allow',
+                Action: SECRET_ACTIONS,
+                Resource: `arn:aws:secretsmanager:${ctx.config.region}:${ctx.accountId}:secret:${secretName}-*`,
+            },
+        ],
+    };
+}
+/**
+ * The deploy role's name, once the site's state proves the role exists. The
+ * name itself is always derivable (`deriveNames`), so the presence check is
+ * against the site's recorded ARN - the only thing the site's node records for
+ * that role - and not against the name.
+ */
+function requireRoleName(ctx) {
+    if (ctx.siteState.resources[SITE_OIDC_ROLE_NODE]?.arn === undefined) {
+        throw new Error(`the site's GitHub OIDC deploy role is not in the "${ctx.env}" state - run \`blogwright bootstrap --env ${ctx.env}\` before \`blogwright pds bootstrap\``);
+    }
+    return ctx.names.githubRole;
+}
+/**
+ * The plugin's grant on the site's deploy role. `secretName` is resolved once,
+ * at graph-build time, where the `pds` block's presence is already the
+ * condition for building the node at all.
+ */
+function oidcPolicyNode(secretName) {
+    function recordGrant(ctx, roleName) {
+        ctx.record(NODE_ID, { roleName, policyName: POLICY_NAME });
+    }
+    async function applyPolicy(ctx) {
+        const roleName = requireRoleName(ctx);
+        await ctx.clients.iam.putRolePolicy(roleName, POLICY_NAME, policyDocument(ctx, secretName));
+        recordGrant(ctx, roleName);
+    }
+    return {
+        id: NODE_ID,
+        // The role belongs to the site's graph, not this one - there is no node
+        // here to depend on. `requireRoleName` is what orders this after the site.
+        dependsOn: [],
+        title: 'PDS secret access on the deploy role',
+        async read(ctx) {
+            const roleName = requireRoleName(ctx);
+            if (!(await ctx.clients.iam.listRolePolicies(roleName)).includes(POLICY_NAME))
+                return false;
+            recordGrant(ctx, roleName);
+            return true;
+        },
+        create: applyPolicy,
+        // Re-put rather than leave the document as found: a changed `secretName`
+        // must reach the live policy, exactly as the site's own role node
+        // re-applies its document on every `blogwright bootstrap`.
+        update: applyPolicy,
+        async delete(ctx) {
+            // No role recorded means no role, and therefore no document of ours on
+            // it. Teardown after `blogwright destroy` is a no-op here, not the
+            // `blogwright bootstrap` failure the apply path raises: there is nothing
+            // an operator could do to make it succeed.
+            if (ctx.siteState.resources[SITE_OIDC_ROLE_NODE]?.arn === undefined)
+                return;
+            const roleName = ctx.names.githubRole;
+            // Delete only this plugin's own named document, and only when it is
+            // there - a second `pds destroy` must not fail on a NoSuchEntity, and no
+            // other policy name on this shared role is ever read or written.
+            if (!(await ctx.clients.iam.listRolePolicies(roleName)).includes(POLICY_NAME))
+                return;
+            await ctx.clients.iam.deleteRolePolicy(roleName, POLICY_NAME);
+        },
+    };
+}
+/**
+ * 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 function buildPdsNodes(ctx) {
+    const pds = ctx.config.pds;
+    if (!pds || !ctx.config.githubRepo || ctx.env === PREVIEW_ENV)
+        return [];
+    return [oidcPolicyNode(resolvePdsSecretName(pds, ctx.config.siteName))];
+}

package/dist/oauth.d.ts

@@ -1,5 +1,5 @@
 /**
- * atproto OAuth (confidential client) for standard.site publishing — the only
+ * atproto OAuth (confidential client) for standard.site publishing - the only
  * module that touches @atproto/oauth-client-node. The blog itself is the OAuth
  * client: its metadata + JWKS are static files on the site (client-metadata.ts),
  * the private key and session live in the Secrets Manager secret (secret.ts),
@@ -14,11 +14,11 @@ export declare function generateClientKey(kid: string): Promise<Jwk>;
 export declare function publicClientJwk(clientKey: Jwk): Promise<Record<string, unknown>>;
 /**
  * Check that the deployed /oauth/ documents match what this CLI would send the
- * authorization server. Run before login/init — a stale or missing deployment
+ * authorization server. Run before login/init - a stale or missing deployment
  * would otherwise fail deep inside the OAuth flow.
  */
 export declare function verifyClientAssets(ctx: PdsContext, fetchImpl?: typeof fetch): Promise<void>;
-/** The authorize/callback surface of NodeOAuthClient — injectable for tests. */
+/** The authorize/callback surface of NodeOAuthClient - injectable for tests. */
 interface OauthFlow {
     authorize(input: string): Promise<URL>;
     callback(params: URLSearchParams): Promise<{
@@ -40,7 +40,7 @@ export interface LoginDeps {
  */
 export declare function login(ctx: PdsContext, identifier: string, deps: LoginDeps): Promise<string>;
 /**
- * Restore the stored OAuth session (transparently refreshing — the rotated
+ * Restore the stored OAuth session (transparently refreshing - the rotated
  * refresh token lands back in the secret) and wrap it as a PdsClient. The
  * session's fetchHandler adds DPoP + auth headers and handles nonce retries.
  */

package/dist/oauth.js

@@ -1,5 +1,5 @@
 /**
- * atproto OAuth (confidential client) for standard.site publishing — the only
+ * atproto OAuth (confidential client) for standard.site publishing - the only
  * module that touches @atproto/oauth-client-node. The blog itself is the OAuth
  * client: its metadata + JWKS are static files on the site (client-metadata.ts),
  * the private key and session live in the Secrets Manager secret (secret.ts),
@@ -18,7 +18,7 @@ function requireDomain(ctx) {
 }
 function requireClientKey(secret, pds) {
     if (!secret.clientKey) {
-        throw new Error(`secret "${pds.secretName}" has no OAuth client key — run \`blogwright pds keygen\``);
+        throw new Error(`secret "${pds.secretName}" has no OAuth client key - run \`blogwright pds keygen\``);
     }
     return secret.clientKey;
 }
@@ -43,7 +43,7 @@ async function buildClient(ctx, clientKey) {
         // state, and syncs can run concurrently (overlapping CI deploys). Providing
         // a lock tells the library it holds the only instance, which disables its
         // invalid_grant recovery (re-read the store and adopt a concurrently
-        // rotated session) and instead deletes the session — destroying the valid
+        // rotated session) and instead deletes the session - destroying the valid
         // token a parallel sync just persisted. A process-local lock cannot
         // serialize cross-process refreshes, so lock-less with recovery is correct.
     });
@@ -78,12 +78,14 @@ export async function publicClientJwk(clientKey) {
     // Round-trip through JSON: drops `d: undefined` left by the getter and
     // matches exactly what the committed jwks.json file will contain.
     const plain = JSON.parse(JSON.stringify(source));
+    // `d` is the private key component: it must be absent from the key set, not present-and-undefined.
+    // eslint-disable-next-line e18e/no-delete-property
     delete plain.d;
     return plain;
 }
 /**
  * Check that the deployed /oauth/ documents match what this CLI would send the
- * authorization server. Run before login/init — a stale or missing deployment
+ * authorization server. Run before login/init - a stale or missing deployment
  * would otherwise fail deep inside the OAuth flow.
  */
 export async function verifyClientAssets(ctx, fetchImpl = fetch) {
@@ -98,17 +100,17 @@ export async function verifyClientAssets(ctx, fetchImpl = fetch) {
     for (const [url, expected] of expectations) {
         const res = await fetchImpl(url);
         if (!res.ok) {
-            throw new Error(`${url} is not deployed (HTTP ${res.status}) — commit public/oauth/* and release first`);
+            throw new Error(`${url} is not deployed (HTTP ${res.status}) - commit public/oauth/* and release first`);
         }
         let deployed;
         try {
             deployed = await res.json();
         }
         catch {
-            throw new Error(`${url} is not valid JSON — re-run \`blogwright pds keygen\` and redeploy`);
+            throw new Error(`${url} is not valid JSON - re-run \`blogwright pds keygen\` and redeploy`);
         }
         if (!deepEqual(deployed, expected)) {
-            throw new Error(`${url} does not match the local client configuration — ` +
+            throw new Error(`${url} does not match the local client configuration - ` +
                 're-run `blogwright pds keygen`, commit public/oauth/*, and release before logging in');
         }
     }
@@ -134,10 +136,10 @@ export async function login(ctx, identifier, deps) {
         params = new URL(pasted.trim()).searchParams;
     }
     catch {
-        throw new Error('that was not a URL — paste the full callback address, query string and all');
+        throw new Error('that was not a URL - paste the full callback address, query string and all');
     }
     if (params.get('error')) {
-        throw new Error(`authorization failed: ${params.get('error')} — ${params.get('error_description') ?? ''}`);
+        throw new Error(`authorization failed: ${params.get('error')} - ${params.get('error_description') ?? ''}`);
     }
     const { session } = await flow.callback(params);
     ctx.logger.ok(`logged in as ${session.did}`);
@@ -149,7 +151,7 @@ function sessionExpired(err) {
     return err instanceof OAuthResponseError && err.error === 'invalid_grant';
 }
 /**
- * Restore the stored OAuth session (transparently refreshing — the rotated
+ * Restore the stored OAuth session (transparently refreshing - the rotated
  * refresh token lands back in the secret) and wrap it as a PdsClient. The
  * session's fetchHandler adds DPoP + auth headers and handles nonce retries.
  */
@@ -158,7 +160,7 @@ export async function openPdsRepo(ctx) {
     const secret = await loadPdsSecret(ctx);
     const clientKey = requireClientKey(secret, pds);
     if (!secret.did || !secret.session) {
-        throw new Error(`secret "${pds.secretName}" has no OAuth session — run \`blogwright pds login\``);
+        throw new Error(`secret "${pds.secretName}" has no OAuth session - run \`blogwright pds login\``);
     }
     const client = await buildClient(ctx, clientKey);
     try {
@@ -168,9 +170,8 @@ export async function openPdsRepo(ctx) {
     catch (err) {
         if (sessionExpired(err)) {
             throw new Error('the stored OAuth session is no longer valid (refresh tokens expire after 180 idle ' +
-                'days, and rotation races invalidate them) — re-run `blogwright pds login`', { cause: err });
+                'days, and rotation races invalidate them) - re-run `blogwright pds login`', { cause: err });
         }
         throw err;
     }
 }
-//# sourceMappingURL=oauth.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The SPI declaration this package default-exports: the `pds` namespace, the
+ * six actions `blogwright pds <action>` has always answered, the `pds` config
+ * key with this package's own validator, and the one resource node
+ * (`nodes.ts`) the plugin contributes to the graph engine.
+ *
+ * Every command here is a WRAPPER and nothing more. It parses its own flags
+ * out of the token array the host hands it and calls the matching function in
+ * `commands.ts`, whose signature is unchanged and which stays individually
+ * exported - `deploy` still calls `syncAfterDeploy(ctx)` with a plain
+ * `OpsContext` and never goes through this table.
+ *
+ * The context boundary is a plain assignment, not a conversion: every command
+ * function takes `PdsContext`, which `context.ts` declares as a `Pick` over
+ * core's `PluginContext<PdsConfig>`, so handing this module's `ctx` straight
+ * to `keygen`/`login`/… is an ordinary argument assignment the compiler
+ * checks. `nodes` is the exception, and deliberately so: it takes the FULL
+ * `PluginContext<PdsConfig>`, because its node reads `siteState`, `names`,
+ * `accountId` and `record()` - members no command context carries, and which
+ * only a lifecycle verb's dispatch boundary builds.
+ *
+ * `bootstrap`, `status` and `destroy` are absent on purpose. They are the
+ * host's generic lifecycle verbs over `nodes`, and a plugin declaring
+ * `bootstrap` or `destroy` is rejected at load
+ * (`packages/cli/src/plugins.ts`); `status` would merely shadow the generic
+ * one. So is `init` as a CONFIG CONTRIBUTOR (`Plugin.init`): `pds init` means
+ * the publication-setup command below, and declaring a contributor would let
+ * the host's generic `blogwright <plugin> init` shadow it.
+ */
+import type { PdsConfig, Plugin } from 'blogwright-core';
+import { init, keygen, login, secretDelete, secretStatus, sync } from './commands.js';
+/**
+ * The command functions the six declared actions wrap. Defaulted to the real
+ * ones ({@link pdsCommandFunctions}) and injectable through
+ * {@link createPdsPlugin}, which is the same default-parameter seam
+ * `commands.ts` already uses for `generateClientKey`, `openPdsRepo` and
+ * `oauthLogin`: the alternative for a test is patching the module, which
+ * DEVELOPMENT.md §Hexagonal architecture bans, and no port exists that would
+ * reveal what `login` was handed - it fetches the deployed `/oauth/`
+ * documents through the global `fetch` before the identifier is ever used.
+ * Nothing in production ever supplies this.
+ */
+export interface PdsCommandFunctions {
+    keygen: typeof keygen;
+    login: typeof login;
+    init: typeof init;
+    sync: typeof sync;
+    secretStatus: typeof secretStatus;
+    secretDelete: typeof secretDelete;
+}
+/**
+ * Build the plugin over a given set of command functions. Exported for tests
+ * only - see {@link PdsCommandFunctions}; every consumer uses the package's
+ * default export, which is {@link createPdsPlugin} called with the real ones.
+ *
+ * `validateConfig` and `nodes` are the imported functions THEMSELVES, not
+ * wrappers around them: this package owns `validatePdsConfig` and
+ * `buildPdsNodes` outright, and a wrapper is the one place a filter or a
+ * re-ordering could later appear between the host and what those two return.
+ */
+export declare function createPdsPlugin(fns?: PdsCommandFunctions): Plugin<PdsConfig>;
+/**
+ * The package's default export, and since task 29 the LIVE path for
+ * `blogwright pds <action>`: task 26 added the `blogwright.plugin` manifest
+ * field to this package's `package.json`, which is what makes discovery
+ * import it at all, and task 29 deleted the CLI's `runPds` branch that used
+ * to answer the namespace ahead of plugin dispatch. Remove that manifest
+ * field and the namespace does not fall back to anything - it stops
+ * existing.
+ */
+declare const pdsPlugin: Plugin<PdsConfig>;
+export default pdsPlugin;

package/dist/plugin.js

@@ -0,0 +1,160 @@
+/**
+ * The SPI declaration this package default-exports: the `pds` namespace, the
+ * six actions `blogwright pds <action>` has always answered, the `pds` config
+ * key with this package's own validator, and the one resource node
+ * (`nodes.ts`) the plugin contributes to the graph engine.
+ *
+ * Every command here is a WRAPPER and nothing more. It parses its own flags
+ * out of the token array the host hands it and calls the matching function in
+ * `commands.ts`, whose signature is unchanged and which stays individually
+ * exported - `deploy` still calls `syncAfterDeploy(ctx)` with a plain
+ * `OpsContext` and never goes through this table.
+ *
+ * The context boundary is a plain assignment, not a conversion: every command
+ * function takes `PdsContext`, which `context.ts` declares as a `Pick` over
+ * core's `PluginContext<PdsConfig>`, so handing this module's `ctx` straight
+ * to `keygen`/`login`/… is an ordinary argument assignment the compiler
+ * checks. `nodes` is the exception, and deliberately so: it takes the FULL
+ * `PluginContext<PdsConfig>`, because its node reads `siteState`, `names`,
+ * `accountId` and `record()` - members no command context carries, and which
+ * only a lifecycle verb's dispatch boundary builds.
+ *
+ * `bootstrap`, `status` and `destroy` are absent on purpose. They are the
+ * host's generic lifecycle verbs over `nodes`, and a plugin declaring
+ * `bootstrap` or `destroy` is rejected at load
+ * (`packages/cli/src/plugins.ts`); `status` would merely shadow the generic
+ * one. So is `init` as a CONFIG CONTRIBUTOR (`Plugin.init`): `pds init` means
+ * the publication-setup command below, and declaring a contributor would let
+ * the host's generic `blogwright <plugin> init` shadow it.
+ */
+import { init, keygen, login, secretDelete, secretStatus, sync } from './commands.js';
+import { validatePdsConfig } from './config.js';
+import { buildPdsNodes } from './nodes.js';
+/**
+ * The CLI namespace this plugin claims. Kept distinct from
+ * {@link PDS_CONFIG_KEY} below even though the two strings coincide today: a
+ * namespace is a dispatch label the host may have to disambiguate against
+ * another plugin's, while the config key names a block in an operator's
+ * committed config file that nothing may rename underneath them.
+ */
+const PDS_NAMESPACE = 'pds';
+/** The single top-level config key this package owns end to end. */
+const PDS_CONFIG_KEY = 'pds';
+/** One line for `blogwright --help`, distilled from the CLI's own `pds` usage block. */
+const PDS_DESCRIPTION = 'standard.site (AT Protocol) publishing: OAuth client, publication setup and record sync';
+/** The flag `pds login` reads the account to authorize from. */
+const IDENTIFIER_FLAG = '--identifier';
+/** The confirmation flag `pds secret delete` refuses to run without. */
+const YES_FLAG = '--yes';
+/** The real command functions - what the package's default export is built over. */
+const pdsCommandFunctions = {
+    keygen,
+    login,
+    init,
+    sync,
+    secretStatus,
+    secretDelete,
+};
+/**
+ * The value of a `--flag value` pair in the tokens the host supplies, or
+ * `undefined` when the flag is absent - which is what makes the wrapped
+ * function's own refusal (`pds login requires --identifier <handle-or-did>`)
+ * the single place that message lives.
+ *
+ * The next token is taken verbatim, with no "does it look like a flag?"
+ * guard, because the host cannot produce a dangling flag: `serialiseFlags`
+ * (`packages/cli/src/plugin-commands.ts`) emits a string flag only as the
+ * pair `--name value`, and `parseArgs` has already consumed every `--flag` out
+ * of the positionals before the remainder reaches a plugin.
+ */
+function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return args[index + 1];
+}
+/**
+ * The six actions, with the exact action strings the CLI's deleted `pds`
+ * dispatch used to accept - `secret status` and `secret delete` declared as
+ * the two-word actions they are. Since task 29 these declarations are the
+ * only definition of the namespace's actions: the host matches them
+ * longest-first, in place of the positional shifting `runPds` hand-rolled.
+ * Renaming or dropping one here removes the action from the CLI.
+ */
+function pdsCommands(fns) {
+    return [
+        {
+            action: 'keygen',
+            summary: 'generate the OAuth client key: private JWK into Secrets Manager, public documents into public/oauth/',
+            async run(ctx) {
+                await fns.keygen(ctx);
+            },
+        },
+        {
+            action: 'login',
+            summary: `interactive OAuth bootstrap, storing the session in Secrets Manager (${IDENTIFIER_FLAG} <handle-or-did>)`,
+            async run(ctx, args) {
+                await fns.login(ctx, { identifier: flagValue(args, IDENTIFIER_FLAG) });
+            },
+        },
+        {
+            action: 'init',
+            summary: 'create or update the standard.site publication record and write the site verification files',
+            async run(ctx) {
+                await fns.init(ctx);
+            },
+        },
+        {
+            action: 'sync',
+            summary: 'reconcile site.standard.document records with the content collection (production only)',
+            async run(ctx) {
+                await fns.sync(ctx);
+            },
+        },
+        {
+            action: 'secret status',
+            summary: 'show the secret metadata - never the value',
+            async run(ctx) {
+                await fns.secretStatus(ctx);
+            },
+        },
+        {
+            action: 'secret delete',
+            summary: `delete the secret, logging out and discarding the key (${YES_FLAG})`,
+            async run(ctx, args) {
+                await fns.secretDelete(ctx, { yes: args.includes(YES_FLAG) });
+            },
+        },
+    ];
+}
+/**
+ * Build the plugin over a given set of command functions. Exported for tests
+ * only - see {@link PdsCommandFunctions}; every consumer uses the package's
+ * default export, which is {@link createPdsPlugin} called with the real ones.
+ *
+ * `validateConfig` and `nodes` are the imported functions THEMSELVES, not
+ * wrappers around them: this package owns `validatePdsConfig` and
+ * `buildPdsNodes` outright, and a wrapper is the one place a filter or a
+ * re-ordering could later appear between the host and what those two return.
+ */
+export function createPdsPlugin(fns = pdsCommandFunctions) {
+    return {
+        name: PDS_NAMESPACE,
+        description: PDS_DESCRIPTION,
+        commands: pdsCommands(fns),
+        configKey: PDS_CONFIG_KEY,
+        validateConfig: validatePdsConfig,
+        nodes: buildPdsNodes,
+    };
+}
+/**
+ * The package's default export, and since task 29 the LIVE path for
+ * `blogwright pds <action>`: task 26 added the `blogwright.plugin` manifest
+ * field to this package's `package.json`, which is what makes discovery
+ * import it at all, and task 29 deleted the CLI's `runPds` branch that used
+ * to answer the namespace ahead of plugin dispatch. Remove that manifest
+ * field and the namespace does not fall back to anything - it stops
+ * existing.
+ */
+const pdsPlugin = createPdsPlugin();
+export default pdsPlugin;

package/dist/rkey.d.ts

@@ -15,7 +15,7 @@ export declare const tidFromPath: (path: string) => string;
 /** Exported only for tests. */
 export declare const extractDate: (path: string) => string | undefined;
 /**
- * Canonical URL path for a blog post — the shape `src/pages/posts/index.astro` links
+ * Canonical URL path for a blog post - the shape `src/pages/posts/index.astro` links
  * (trailing slash). Rkeys derive from this string, so slugs must never change after
  * publication.
  */

package/dist/rkey.js

@@ -25,7 +25,7 @@ export const tidFromPath = (path) => {
         if (Number.isNaN(date.getTime())) {
             // A date-like digit pattern that is not a real date (e.g. a product
             // slug "sku-3456-78-90"). The reference implementation throws here, so
-            // no existing record can hold a date-derived TID for such a path —
+            // no existing record can hold a date-derived TID for such a path -
             // falling back to the whole-path hash cannot diverge from live rkeys.
             tid = hashBits(path, 63);
         }
@@ -69,11 +69,10 @@ const encodeTid = (n) => {
 const BASE32 = '234567abcdefghijklmnopqrstuvwxyz';
 // --- example-specific helpers (not vendored) ---
 /**
- * Canonical URL path for a blog post — the shape `src/pages/posts/index.astro` links
+ * Canonical URL path for a blog post - the shape `src/pages/posts/index.astro` links
  * (trailing slash). Rkeys derive from this string, so slugs must never change after
  * publication.
  */
 export const postPath = (slug) => `/posts/${slug}/`;
 /** AT-URI of the standard.site document record for a post. */
 export const documentUri = (did, slug) => `at://${did}/site.standard.document/${tidFromPath(postPath(slug))}`;
-//# sourceMappingURL=rkey.js.map

package/dist/secret.d.ts

@@ -9,7 +9,7 @@
 import type { Jwk, NodeSavedSession, NodeSavedSessionStore } from '@atproto/oauth-client-node';
 import type { SecretsManagerClient } from 'blogwright-core';
 import type { PdsContext } from './context.js';
-/** The client surface secret persistence needs — structural, so tests can stub it. */
+/** The client surface secret persistence needs - structural, so tests can stub it. */
 export type SecretsStore = Pick<SecretsManagerClient, 'getSecretValue' | 'upsertSecret'>;
 export interface PdsSecret {
     version: 1;
@@ -23,13 +23,13 @@ export interface PdsSecret {
 /** Parse the secret JSON, rejecting the pre-OAuth app-password shape. */
 export declare function parsePdsSecret(raw: string, secretName: string): PdsSecret;
 /**
- * Fetch and parse the secret. Called only at keygen/login/sync time —
+ * Fetch and parse the secret. Called only at keygen/login/sync time -
  * secret material must never be loaded during context creation.
  */
 export declare function loadPdsSecret(ctx: PdsContext): Promise<PdsSecret>;
 /**
  * Read-modify-write the secret; starts from an empty v1 value when absent.
- * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value —
+ * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value -
  * the migration entry point; every other writer must reject it.
  */
 export declare function updatePdsSecret(secrets: SecretsStore, secretName: string, mutate: (secret: PdsSecret) => PdsSecret, opts?: {
@@ -38,7 +38,7 @@ export declare function updatePdsSecret(secrets: SecretsStore, secretName: strin
 }): Promise<PdsSecret>;
 /**
  * NodeOAuthClient session store backed by the secret. `set` runs on login and
- * on every refresh-token rotation — persisting it is what keeps the CI session
+ * on every refresh-token rotation - persisting it is what keeps the CI session
  * alive; `del` clears only the session (client key and DID survive a logout).
  */
 export declare function sessionStoreForSecret(secrets: SecretsStore, secretName: string): NodeSavedSessionStore;

package/dist/secret.js

@@ -29,7 +29,7 @@ function isLegacySecret(parsed) {
 export function parsePdsSecret(raw, secretName) {
     const parsed = parseJsonObject(raw, secretName);
     if (isLegacySecret(parsed)) {
-        throw new Error(`secret "${secretName}" holds app-password credentials — app passwords are no longer ` +
+        throw new Error(`secret "${secretName}" holds app-password credentials - app passwords are no longer ` +
             'supported; run `blogwright pds keygen` then `blogwright pds login`');
     }
     if (parsed.version !== 1) {
@@ -38,20 +38,20 @@ export function parsePdsSecret(raw, secretName) {
     return parsed;
 }
 /**
- * Fetch and parse the secret. Called only at keygen/login/sync time —
+ * Fetch and parse the secret. Called only at keygen/login/sync time -
  * secret material must never be loaded during context creation.
  */
 export async function loadPdsSecret(ctx) {
     const pds = requirePdsConfig(ctx);
     const raw = await ctx.clients.secrets.getSecretValue(pds.secretName);
     if (!raw) {
-        throw new Error(`no secret at "${pds.secretName}" — create it with \`blogwright pds keygen\``);
+        throw new Error(`no secret at "${pds.secretName}" - create it with \`blogwright pds keygen\``);
     }
     return parsePdsSecret(raw, pds.secretName);
 }
 /**
  * Read-modify-write the secret; starts from an empty v1 value when absent.
- * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value —
+ * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value -
  * the migration entry point; every other writer must reject it.
  */
 export async function updatePdsSecret(secrets, secretName, mutate, opts = {}) {
@@ -66,7 +66,7 @@ export async function updatePdsSecret(secrets, secretName, mutate, opts = {}) {
 }
 /**
  * NodeOAuthClient session store backed by the secret. `set` runs on login and
- * on every refresh-token rotation — persisting it is what keeps the CI session
+ * on every refresh-token rotation - persisting it is what keeps the CI session
  * alive; `del` clears only the session (client key and DID survive a logout).
  */
 export function sessionStoreForSecret(secrets, secretName) {
@@ -83,7 +83,7 @@ export function sessionStoreForSecret(secrets, secretName) {
         async set(sub, session) {
             // Retried: this write persists a just-rotated single-use refresh token.
             // If it throws, the OAuth library revokes the new token and deletes the
-            // session — one Secrets Manager throttle at exactly the wrong moment
+            // session - one Secrets Manager throttle at exactly the wrong moment
             // would otherwise force an interactive re-login.
             let lastError;
             for (let attempt = 0; attempt < 3; attempt++) {
@@ -107,4 +107,3 @@ export function sessionStoreForSecret(secrets, secretName) {
         },
     };
 }
-//# sourceMappingURL=secret.js.map