blogwright 0.3.3 → 0.4.0-beta.1

package/README.md

@@ -3,7 +3,7 @@
 Deploy a static site to AWS from one CLI: S3 + CloudFront hosting, builds in an
 isolated **Lambda MicroVM**, PR previews, keyless GitHub-OIDC CI deploys, and
 optional [standard.site](https://standard.site) (AT Protocol) publishing. No
-CloudFormation, no Terraform, no CDK — the infrastructure is a reconcilable
+CloudFormation, no Terraform, no CDK - the infrastructure is a reconcilable
 dependency graph the CLI applies directly through signed AWS API calls.
 
 Works with any static site that installs and builds with pnpm: an Astro blog at
@@ -14,7 +14,7 @@ ends in a directory of files to serve.
 
 - Node ≥ 22 and pnpm (your site must build with `pnpm build`)
 - AWS credentials in the ambient provider chain (`aws sso login`, env vars, or
-  an assumed role — whatever your shell already has)
+  an assumed role - whatever your shell already has)
 - A git or jj repository (deploys are keyed to your revision hash)
 
 ## Get running
@@ -28,12 +28,12 @@ pnpm exec blogwright deploy    # zip → build in a MicroVM → live site
 ```
 
 `init` asks four questions (site name, region, optional domain, optional GitHub
-repo). `bootstrap` prints the CloudFront domain — and, if you set a domain, the
+repo). `bootstrap` prints the CloudFront domain - and, if you set a domain, the
 ACM validation CNAMEs to add to DNS. `deploy` streams the build log with live
 progress and ends with a summary card and your URL. The `bw` alias works
 everywhere `blogwright` does.
 
-No TTY? Create the config by hand — only two fields are required:
+No TTY? Create the config by hand - only two fields are required:
 
 ```jsonc
 // config/production.jsonc
@@ -44,7 +44,7 @@ No TTY? Create the config by hand — only two fields are required:
 
 | Command | What it does |
 | --- | --- |
-| `init` | First-run wizard — writes `config/production.jsonc` |
+| `init` | First-run wizard - writes `config/production.jsonc` |
 | `bootstrap [env]` | Create/reconcile the infrastructure (idempotent; re-run after config changes) |
 | `deploy [env]` | Zip the repo, build in a MicroVM, sync to S3, invalidate only changed paths |
 | `status [env]` | Planned infrastructure vs live state, as a drift tree |
@@ -57,7 +57,7 @@ No TTY? Create the config by hand — only two fields are required:
 
 `deploy --refresh` re-uploads every file, even unchanged ones. Deploys normally
 skip content-identical files, but S3 only writes object metadata (content type,
-tags) on a PUT — so use it once after an upgrade that fixes a content type or
+tags) on a PUT - so use it once after an upgrade that fixes a content type or
 adds tags, to push that metadata onto live objects.
 
 Environment defaults to `production`; pass `staging` (or anything) positionally.
@@ -72,7 +72,7 @@ Everything beyond `region` + `siteName` has sensible defaults:
 ```jsonc
 {
   "region": "us-east-1",
-  "siteName": "myblog",             // names every AWS resource — never change it
+  "siteName": "myblog",             // names every AWS resource - never change it
   "domain": "blog.example.com",     // ACM cert + CloudFront alias
   "githubRepo": "you/your-repo",    // enables keyless CI deploys (OIDC)
 
@@ -85,14 +85,14 @@ Everything beyond `region` + `siteName` has sensible defaults:
 ```
 
 `sourceInclude` is for artifacts you build *before* deploying (a wasm bundle, a
-generated dataset) with toolchains the builder image deliberately lacks — run
+generated dataset) with toolchains the builder image deliberately lacks - run
 your pre-build, then `blogwright deploy`; a missing entry fails fast with a
 pointer.
 
 ## CI deploys (no stored keys)
 
 With `githubRepo` set, `bootstrap` provisions a GitHub-OIDC role. Your workflow
-assumes it and deploys — no AWS secrets in GitHub:
+assumes it and deploys - no AWS secrets in GitHub:
 
 ```yaml
 permissions: { id-token: write, contents: read }
@@ -115,14 +115,14 @@ a prefix delete.
 
 ## Output modes
 
-Pretty by default on a TTY — live build progress, a deploy summary card, drift
+Pretty by default on a TTY - live build progress, a deploy summary card, drift
 trees. Piped output and CI get stable, line-oriented plain text automatically;
 `--plain` forces it (ideal for agents), and `NO_COLOR` disables colour only.
 
 ## standard.site publishing
 
 Add a `pds` section to the config and your posts mirror to your AT Protocol
-PDS as standard.site records after every production deploy — OAuth
+PDS as standard.site records after every production deploy - OAuth
 confidential client, keys in Secrets Manager, rkeys derived from URL paths
 (exposed as the `blogwright/rkey` subpath so your site renders matching link
 tags). Setup order matters; see the

package/agent/agent-manifest.json

@@ -1,3 +1,3 @@
 {
-  "hash": "8b1cae617b0b"
+  "hash": "05d2ebaa501a"
 }

package/agent/server.js

@@ -53,7 +53,7 @@ var AwsError = class extends Error {
 	requestId;
 	service;
 	constructor(opts) {
-		super(`${opts.service}: ${opts.code} — ${opts.message} (HTTP ${opts.statusCode})`);
+		super(`${opts.service}: ${opts.code} - ${opts.message} (HTTP ${opts.statusCode})`);
 		this.name = "AwsError";
 		this.service = opts.service;
 		this.code = opts.code;
@@ -78,7 +78,7 @@ function isRetryable(err) {
 //#region ../core/dist/aws/xml.js
 /**
 * Minimal XML helpers for the handful of AWS REST-XML / query responses this CLI
-* reads (S3, STS, IAM, CloudFront). Not a general XML parser — it extracts tag
+* reads (S3, STS, IAM, CloudFront). Not a general XML parser - it extracts tag
 * contents by name, which is sufficient for the flat response shapes we consume.
 */
 const ENTITIES = {
@@ -112,7 +112,7 @@ function textTag(xml, name) {
 	return inner === void 0 ? void 0 : decodeEntities(inner.trim());
 }
 /**
-* Like {@link textTag} but verbatim — no trimming. For values where whitespace
+* Like {@link textTag} but verbatim - no trimming. For values where whitespace
 * is data, like S3 object keys (a trimmed key would target a different object).
 */
 function rawTextTag(xml, name) {
@@ -5719,8 +5719,25 @@ const GLOBAL_SERVICES = /* @__PURE__ */ new Set([
 	"cloudfront",
 	"route53"
 ]);
+/**
+* Turns a core `ServiceKey` or a plugin-supplied `ServiceDescriptor` into one shape.
+* The single resolution helper every `service`-keyed site reads.
+*/
+function resolveService(service) {
+	if (typeof service === "string") return {
+		name: service,
+		signingName: SIGNING_NAMES[service],
+		global: GLOBAL_SERVICES.has(service)
+	};
+	return {
+		name: service.service,
+		signingName: service.signingName,
+		global: service.global ?? false
+	};
+}
 function resolveEndpoint(service, region, override) {
-	const signingRegion = GLOBAL_SERVICES.has(service) ? "us-east-1" : region;
+	const resolved = resolveService(service);
+	const signingRegion = resolved.global ? "us-east-1" : region;
 	if (override) {
 		const url = new URL(override);
 		return {
@@ -5732,7 +5749,7 @@ function resolveEndpoint(service, region, override) {
 	}
 	return {
 		protocol: "https:",
-		host: canonicalHost(service, region),
+		host: canonicalHost(resolved.name, region),
 		signingRegion,
 		override: false
 	};
@@ -7113,6 +7130,7 @@ var SigningClient = class {
 		this.transport = opts.transport ?? fetchTransport;
 	}
 	async send(opts) {
+		const resolved = resolveService(opts.service);
 		const ep = resolveEndpoint(opts.service, this.region, this.endpointOverride);
 		const [hostname, portStr] = ep.host.split(":");
 		const port = portStr ? Number(portStr) : void 0;
@@ -7135,7 +7153,7 @@ var SigningClient = class {
 			...opts.body !== void 0 ? { body: opts.body } : {}
 		});
 		const signed = await new import_dist_cjs$1.SignatureV4({
-			service: SIGNING_NAMES[opts.service],
+			service: resolved.signingName,
 			region: ep.signingRegion,
 			credentials: async () => {
 				const c = await this.credentials();
@@ -7146,7 +7164,7 @@ var SigningClient = class {
 				};
 			},
 			sha256: import_main.Sha256,
-			uriEscapePath: opts.service !== "s3"
+			uriEscapePath: resolved.name !== "s3"
 		}).sign(request);
 		const qs = Object.keys(query).map((k) => `${escape(k)}=${escape(query[k])}`).join("&");
 		const url = `${ep.protocol}//${ep.host}${opts.path}${qs ? `?${qs}` : ""}`;
@@ -7157,7 +7175,7 @@ var SigningClient = class {
 				headers: signed.headers,
 				body: opts.body
 			});
-			if (response.statusCode >= 300) throw parseError(opts.service, response);
+			if (response.statusCode >= 300) throw parseError(resolved.name, response);
 			return response;
 		}, { retryable: [
 			"GET",
@@ -7634,7 +7652,7 @@ function unzipSync(data, opts) {
 let credCache;
 /**
 * Resolve the MicroVM's execution-role credentials. Tries standard env vars first
-* (Lambda-style), then the ECS/container credentials endpoint — covering both ways
+* (Lambda-style), then the ECS/container credentials endpoint - covering both ways
 * the exec role might be exposed inside the MicroVM.
 */
 async function resolveCredentials() {
@@ -7766,7 +7784,7 @@ const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 /**
 * Whether a built file must be PUT again. Content-identical files are normally
 * skipped (that is what keeps a redeploy cheap and its invalidation narrow),
-* but S3 writes object metadata — content type, tags — only on a PUT, so a
+* but S3 writes object metadata - content type, tags - only on a PUT, so a
 * metadata fix would never reach them. `refresh` forces the upload.
 */
 function shouldUpload(existingEtag, md5, refresh) {
@@ -7781,12 +7799,12 @@ function isAccessDenied(err) {
 * Upload the site files, degrading gracefully when the role may not tag.
 *
 * Object tags ride on the PUT (`x-amz-tagging`), but AWS still checks
-* `s3:PutObjectTagging` as a distinct action — a role granted only `s3:PutObject`
+* `s3:PutObjectTagging` as a distinct action - a role granted only `s3:PutObject`
 * gets a 403 and the whole upload fails. Tags are metadata, not content: rather
 * than fail a deploy whose files are otherwise fine, drop the tags for the rest
 * of the run and say so. (A stack bootstrapped on a version that grants the
 * action never takes this path; one upgrading in place does, until it
-* re-bootstraps — and a CI deploy role cannot fix its own IAM.)
+* re-bootstraps - and a CI deploy role cannot fix its own IAM.)
 */
 function createSiteUploader(s3, log) {
 	let taggingDenied = false;
@@ -7797,14 +7815,14 @@ function createSiteUploader(s3, log) {
 		} catch (err) {
 			if (!isAccessDenied(err)) throw err;
 			taggingDenied = true;
-			log("warning: this role cannot tag objects (s3:PutObjectTagging denied) — uploading untagged. Run `blogwright bootstrap <env>` to grant it, then redeploy with --refresh to tag the existing objects.");
+			log("warning: this role cannot tag objects (s3:PutObjectTagging denied) - uploading untagged. Run `blogwright bootstrap <env>` to grant it, then redeploy with --refresh to tag the existing objects.");
 		}
 		await s3.putObject(bucket, key, content, type);
 	};
 }
 /**
 * The lowercase extension of a key, or undefined when it has none (`LICENSE`,
-* `_headers`) — a leading dot is a dotfile, not an extension (`.nojekyll`).
+* `_headers`) - a leading dot is a dotfile, not an extension (`.nojekyll`).
 * Splitting the whole path would treat an extensionless *key* as its own
 * extension, which both mistypes files and produces nonsense diagnostics.
 */
@@ -7816,8 +7834,8 @@ function extensionOf(path) {
 }
 /**
 * Content type for a key, or {@link DEFAULT_CONTENT_TYPE} when the extension is
-* unmapped or absent. The default is deliberate — it makes a browser download
-* rather than mis-render an unknown payload — but a *silently* wrong header is
+* unmapped or absent. The default is deliberate - it makes a browser download
+* rather than mis-render an unknown payload - but a *silently* wrong header is
 * how the .webmanifest gap survived, so runBuild logs unmapped extensions.
 */
 function contentType(path) {
@@ -7925,7 +7943,7 @@ async function runBuild(s3, payload, log) {
 	const uploaded = /* @__PURE__ */ new Set();
 	const changedKeys = /* @__PURE__ */ new Set();
 	const unmapped = /* @__PURE__ */ new Set();
-	if (payload.refresh) log("refresh: re-uploading every file (metadata — content type, tags — may have changed)");
+	if (payload.refresh) log("refresh: re-uploading every file (metadata - content type, tags - may have changed)");
 	for (const file of built) {
 		const key = prefix + relative(distDir, file).split("\\").join("/");
 		uploaded.add(key);
@@ -7938,7 +7956,7 @@ async function runBuild(s3, payload, log) {
 		await uploadSiteFile(payload.bucket, key, content, type, payload.objectTags);
 		changedKeys.add(key);
 	}
-	if (unmapped.size > 0) log(`warning: no content type mapped for extension(s) ${[...unmapped].sort().join(", ")} — serving them as ${DEFAULT_CONTENT_TYPE}`);
+	if (unmapped.size > 0) log(`warning: no content type mapped for extension(s) ${[...unmapped].sort().join(", ")} - serving them as ${DEFAULT_CONTENT_TYPE}`);
 	for (const key of existing.keys()) if (!uploaded.has(key)) {
 		await s3.deleteObject(payload.bucket, key);
 		changedKeys.add(key);
@@ -7998,7 +8016,7 @@ function startBuild(payload) {
 }
 /**
 * Poll s3://<bucket>/build/pending/ for jobs (the build trigger). Drains one unbuilt job
-* per tick — multiple targets (concurrent PR previews) each have their own key. The
+* per tick - multiple targets (concurrent PR previews) each have their own key. The
 * MicroVM's ambient IMDS credentials are the build role, which holds the site-write perms.
 */
 let polling = false;

package/dist/adapters/fetch-ping.d.ts

@@ -1,7 +1,7 @@
 /**
  * Fetch adapter for the PingBuilder port: opens a connection to the builder
  * MicroVM's proxy endpoint to wake the resumed agent's event loop. Errors never
- * cross the port — the ping is best-effort by contract, and the agent's HTTP/1
+ * cross the port - the ping is best-effort by contract, and the agent's HTTP/1
  * server may not even parse the request.
  */
 import type { PingBuilder } from '../ports.js';

package/dist/adapters/fetch-ping.js

@@ -1,7 +1,7 @@
 /**
  * Fetch adapter for the PingBuilder port: opens a connection to the builder
  * MicroVM's proxy endpoint to wake the resumed agent's event loop. Errors never
- * cross the port — the ping is best-effort by contract, and the agent's HTTP/1
+ * cross the port - the ping is best-effort by contract, and the agent's HTTP/1
  * server may not even parse the request.
  */
 /** A nudge only needs the connection to land; never hold a poll cycle longer than this. */
@@ -14,12 +14,12 @@ export function createFetchPing(fetchImpl = fetch) {
                 headers: { 'X-aws-proxy-auth': token, 'X-aws-proxy-port': '8080' },
                 signal: AbortSignal.timeout(PING_TIMEOUT_MS),
             });
-            // Release the connection — an unread body pins an undici socket per
+            // Release the connection - an unread body pins an undici socket per
             // poll cycle until GC.
             await res.body?.cancel();
         }
         catch {
-            /* expected — the point is the wake-up, not the response */
+            /* expected - the point is the wake-up, not the response */
         }
     };
 }

package/dist/adapters/node-module-loader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node adapter for the ModuleLoader port: the only file outside the
+ * composition root that imports `node:module`. Resolution goes through
+ * `createRequire` anchored on the caller's directory (Node's own CJS/ESM
+ * resolver, which understands `exports` maps, symlinked `node_modules`, and
+ * pnpm's workspace layout); loading goes through a dynamic `import()` over
+ * the resolved file's URL, so both CJS and ESM plugin packages work.
+ */
+import type { ModuleLoader } from '../ports.js';
+/** Build the real Node adapter for the ModuleLoader port. */
+export declare function createNodeModuleLoader(): ModuleLoader;

package/dist/adapters/node-module-loader.js

@@ -0,0 +1,146 @@
+/**
+ * Node adapter for the ModuleLoader port: the only file outside the
+ * composition root that imports `node:module`. Resolution goes through
+ * `createRequire` anchored on the caller's directory (Node's own CJS/ESM
+ * resolver, which understands `exports` maps, symlinked `node_modules`, and
+ * pnpm's workspace layout); loading goes through a dynamic `import()` over
+ * the resolved file's URL, so both CJS and ESM plugin packages work.
+ */
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+function isModuleNotFound(err) {
+    return err instanceof Error && err.code === 'MODULE_NOT_FOUND';
+}
+/** Wrap a resolver failure with the specifier and directory, preserving the cause. */
+function resolutionFailure(operation, specifier, fromDir, err) {
+    return new Error(`failed to ${operation} "${specifier}" from ${fromDir}: ${err.message}`, { cause: err });
+}
+/**
+ * Resolve `specifier`'s entry-point file via `require.resolve`, anchored on
+ * `fromDir`. A missing module (`MODULE_NOT_FOUND`) is a normal "not
+ * installed" outcome and returns `{ found: false }`; anything else - a
+ * malformed specifier, an `exports` map that blocks the subpath, a
+ * filesystem error - is unexpected and raises with context.
+ */
+function resolveEntryPoint(specifier, fromDir) {
+    const require = createRequire(join(fromDir, 'package.json'));
+    try {
+        return { found: true, path: require.resolve(specifier) };
+    }
+    catch (err) {
+        if (isModuleNotFound(err))
+            return { found: false };
+        throw resolutionFailure('resolve', specifier, fromDir, err);
+    }
+}
+/**
+ * True when `path` exists, parses as a JSON object, and carries a non-empty
+ * `name` - i.e. is genuinely a package manifest, not merely a `package.json`
+ * that happens to sit in the walk's path. A dual-package layout
+ * (`exports: {".": "./dist/index.js"}` plus a `dist/package.json` stub of
+ * `{"type": "module"}`) has exactly such a stub as the nearest file on disk:
+ * it carries no `name` and no `blogwright` field, so treating it as the
+ * manifest would make discovery conclude the package is not a plugin and
+ * skip it silently. Any read or parse failure - the file is absent, or is not
+ * valid JSON - answers `false` so the walk continues upward, rather than
+ * raising: a stray malformed `package.json` above the real one (unrelated to
+ * this resolution) must not abort the walk before it reaches the manifest
+ * that does carry a `name`.
+ */
+async function isPackageManifest(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return false;
+        const name = parsed.name;
+        return typeof name === 'string' && name.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk up from `entryFile` to the nearest `package.json` **that is a package
+ * manifest** - one carrying a `name` (see {@link isPackageManifest}). This -
+ * not `require.resolve('<specifier>/package.json')` - is how
+ * `packageJsonPathFor` finds a plugin's manifest.
+ *
+ * The direct subpath throws under Node's exports encapsulation whenever a
+ * package's `exports` map omits `"./package.json"`, which is true of every
+ * published package in this repo:
+ *
+ * ```
+ * require.resolve('blogwright-pds/package.json')
+ *   -> ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './package.json' is not
+ *      defined by "exports" in .../blogwright-pds/package.json
+ * ```
+ *
+ * (verified 2026-07-26 against this workspace; `blogwright-pds`'s `exports`
+ * map lists only `.` and `./rkey`). Walking up from the already-resolved
+ * entry file sidesteps `exports` entirely - it is a directory walk over the
+ * real filesystem, not a second module resolution - so it works against any
+ * package regardless of what its `exports` map declares. A map-backed test
+ * fake cannot reproduce the throw above (a fake has no `exports` map to
+ * enforce), which is why this behaviour is proven by an integration test
+ * against this real adapter (`node-module-loader.test.ts`) rather than a fake.
+ * Do not "simplify" this back to the direct subpath.
+ *
+ * The `name`-carrying qualifier was added 2026-08-29: without it, the walk
+ * stops at the *first* `package.json` it finds above the entry file, which
+ * for a dual-package layout is the `dist/package.json` stub, not the real
+ * manifest one directory further up. Skipping past a name-less manifest costs
+ * one extra read per level and closes that gap.
+ */
+async function nearestPackageJson(entryFile) {
+    let dir = dirname(entryFile);
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (await isPackageManifest(candidate))
+            return { found: true, path: candidate };
+        const parent = dirname(dir);
+        if (parent === dir)
+            return { found: false };
+        dir = parent;
+    }
+}
+/** Build the real Node adapter for the ModuleLoader port. */
+export function createNodeModuleLoader() {
+    return {
+        async resolve(specifier, fromDir) {
+            return resolveEntryPoint(specifier, fromDir);
+        },
+        async packageJsonPathFor(specifier, fromDir) {
+            const entry = resolveEntryPoint(specifier, fromDir);
+            if (!entry.found)
+                return entry;
+            const manifest = await nearestPackageJson(entry.path);
+            if (!manifest.found) {
+                // The walk reached the filesystem root with no package.json above a
+                // module Node itself just resolved - an environment inconsistency,
+                // not a "not installed" outcome, so it raises rather than reporting
+                // `{ found: false }`.
+                throw resolutionFailure('locate the package.json for', specifier, fromDir, new Error(`no package.json found above resolved entry point ${entry.path}`));
+            }
+            return manifest;
+        },
+        async load(path) {
+            try {
+                return (await import(pathToFileURL(path).href));
+            }
+            catch (err) {
+                throw new Error(`failed to load module at ${path}: ${err.message}`, {
+                    cause: err,
+                });
+            }
+        },
+    };
+}

package/dist/adapters/process-package-manager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Process adapter for the PackageManager port: detects which package manager
+ * governs the repo from the lockfile it wrote (read through the injected
+ * FileSystem port, never node:fs), then shells out to it for add/remove. One
+ * of only two modules that may import node:child_process (the other is
+ * process-vcs.ts); failures are translated with the command, its arguments
+ * and the directory before they cross the port, mirroring runVcsCommand.
+ */
+import { type FileSystem } from 'blogwright-core';
+import type { AddPackageOptions, PackageManager, PackageManagerName } from '../ports.js';
+/** A verbose install/uninstall can exceed the 1 MiB default buffer, same rationale as process-vcs.ts. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** The shape of `execFile`, promisified - injectable so tests exercise command
+ * construction and error translation without spawning a process. */
+type ExecFileAsync = (command: string, args: string[], options: {
+    cwd: string;
+    maxBuffer: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** Exported for tests, so the negative case's expected list is derived, not hand-copied. */
+export declare const PACKAGE_MANAGER_LOCKFILES: Readonly<Record<PackageManagerName, string>>;
+/** Exported for tests: the exact argument vector `add` shells out with, per manager. */
+export declare function addArgs(manager: PackageManagerName, spec: string, opts: AddPackageOptions): string[];
+/** Exported for tests: the exact argument vector `remove` shells out with, per manager. */
+export declare function removeArgs(manager: PackageManagerName, name: string): string[];
+/**
+ * Build the process package-manager adapter. `detect` probes `repoRoot` for
+ * each candidate lockfile through `fs`; `add`/`remove` resolve their own repo
+ * root (`findRepoRoot`, starting from `startDir` - `process.cwd()` in
+ * production) and manager, then shell out from that directory. `runProcess`
+ * and `startDir` are injectable so tests can exercise the whole add/remove
+ * pipeline - repo/manager resolution, command construction, and error
+ * translation - without spawning a process or depending on the real cwd.
+ */
+export declare function createProcessPackageManager(fs: FileSystem, options?: {
+    runProcess?: ExecFileAsync;
+    startDir?: string;
+}): PackageManager;
+export {};

package/dist/adapters/process-package-manager.js

@@ -0,0 +1,116 @@
+/**
+ * Process adapter for the PackageManager port: detects which package manager
+ * governs the repo from the lockfile it wrote (read through the injected
+ * FileSystem port, never node:fs), then shells out to it for add/remove. One
+ * of only two modules that may import node:child_process (the other is
+ * process-vcs.ts); failures are translated with the command, its arguments
+ * and the directory before they cross the port, mirroring runVcsCommand.
+ */
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { findRepoRoot } from 'blogwright-core';
+const run = promisify(execFile);
+/** A verbose install/uninstall can exceed the 1 MiB default buffer, same rationale as process-vcs.ts. */
+export const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+ * The module-level table `detect` and command-building read from - a named
+ * constant rather than a chain of literals at each call site. The binary
+ * invoked for a manager is its own key (`pnpm`, `npm`, `yarn`, `bun`).
+ */
+const PACKAGE_MANAGERS = {
+    pnpm: {
+        lockfile: 'pnpm-lock.yaml',
+        addVerb: 'add',
+        removeVerb: 'remove',
+        devFlag: '--save-dev',
+        exactFlag: '--save-exact',
+    },
+    npm: {
+        lockfile: 'package-lock.json',
+        addVerb: 'install',
+        removeVerb: 'uninstall',
+        devFlag: '--save-dev',
+        exactFlag: '--save-exact',
+    },
+    yarn: {
+        lockfile: 'yarn.lock',
+        addVerb: 'add',
+        removeVerb: 'remove',
+        devFlag: '--dev',
+        exactFlag: '--exact',
+    },
+    bun: {
+        lockfile: 'bun.lock',
+        addVerb: 'add',
+        removeVerb: 'remove',
+        devFlag: '--dev',
+        exactFlag: '--exact',
+    },
+};
+/** Exported for tests, so the negative case's expected list is derived, not hand-copied. */
+export const PACKAGE_MANAGER_LOCKFILES = Object.fromEntries(Object.entries(PACKAGE_MANAGERS).map(([name, spec]) => [name, spec.lockfile]));
+/** Probe each candidate lockfile in `repoRoot` through `fs`; first match wins. */
+async function detectManager(fs, repoRoot) {
+    for (const [name, spec] of Object.entries(PACKAGE_MANAGERS)) {
+        if (await fs.exists(join(repoRoot, spec.lockfile)))
+            return name;
+    }
+    const lockfiles = Object.values(PACKAGE_MANAGERS)
+        .map((spec) => spec.lockfile)
+        .join(', ');
+    throw new Error(`no supported package manager detected in ${repoRoot} - looked for ${lockfiles}`);
+}
+/** Exported for tests: the exact argument vector `add` shells out with, per manager. */
+export function addArgs(manager, spec, opts) {
+    const { addVerb, devFlag, exactFlag } = PACKAGE_MANAGERS[manager];
+    const args = [addVerb, spec];
+    if (opts.dev)
+        args.push(devFlag);
+    if (opts.exact)
+        args.push(exactFlag);
+    return args;
+}
+/** Exported for tests: the exact argument vector `remove` shells out with, per manager. */
+export function removeArgs(manager, name) {
+    return [PACKAGE_MANAGERS[manager].removeVerb, name];
+}
+/**
+ * Build the process package-manager adapter. `detect` probes `repoRoot` for
+ * each candidate lockfile through `fs`; `add`/`remove` resolve their own repo
+ * root (`findRepoRoot`, starting from `startDir` - `process.cwd()` in
+ * production) and manager, then shell out from that directory. `runProcess`
+ * and `startDir` are injectable so tests can exercise the whole add/remove
+ * pipeline - repo/manager resolution, command construction, and error
+ * translation - without spawning a process or depending on the real cwd.
+ */
+export function createProcessPackageManager(fs, options = {}) {
+    const runProcess = options.runProcess ?? run;
+    const startDir = options.startDir ?? process.cwd();
+    async function runPackageCommand(cwd, command, args) {
+        try {
+            await runProcess(command, args, { cwd, maxBuffer: MAX_OUTPUT_BYTES });
+        }
+        catch (err) {
+            throw new Error(`${command} ${args.join(' ')} failed in ${cwd}: ${err.message}`, {
+                cause: err,
+            });
+        }
+    }
+    async function resolveRepo() {
+        const repoRoot = await findRepoRoot(fs, startDir);
+        const manager = await detectManager(fs, repoRoot);
+        return { repoRoot, manager };
+    }
+    return {
+        detect: (repoRoot) => detectManager(fs, repoRoot),
+        async add(spec, opts = {}) {
+            const { repoRoot, manager } = await resolveRepo();
+            await runPackageCommand(repoRoot, manager, addArgs(manager, spec, opts));
+        },
+        async remove(name) {
+            const { repoRoot, manager } = await resolveRepo();
+            await runPackageCommand(repoRoot, manager, removeArgs(manager, name));
+        },
+    };
+}

package/dist/adapters/process-vcs.d.ts

@@ -1,12 +1,13 @@
 /**
- * Process adapter for the Vcs port: shells out to jj/git. The only module
- * outside the build-agent that may import node:child_process; failures are
- * translated with the command and directory before they cross the port.
+ * Process adapter for the Vcs port: shells out to jj/git. One of only two
+ * modules outside the build-agent that may import node:child_process (the
+ * other is process-package-manager.ts); failures are translated with the
+ * command and directory before they cross the port.
  */
 import type { Vcs } from '../ports.js';
 /**
  * Build the jj/git process adapter. The revision hash prefers jj's git commit
  * id (jj auto-commits the working copy), falling back to git HEAD; listings
- * honor .gitignore — tracked files plus untracked files that are not ignored.
+ * honor .gitignore - tracked files plus untracked files that are not ignored.
  */
 export declare function createProcessVcs(): Vcs;