blogwright-core 0.3.3 → 0.4.0-beta.1

package/dist/state.d.ts

@@ -9,14 +9,35 @@ export interface OpsState {
 }
 export declare function emptyState(env: string): OpsState;
 /**
- * S3-backed topology state. Lives at `s3://<bucket>/state/<env>.json` so it is shared
- * across machines and is the single source of truth for what has been provisioned.
+ * S3-backed topology state: the single source of truth for what has been provisioned.
+ *
+ * An unscoped store (three constructor arguments) keys `s3://<bucket>/state/<env>.json`.
+ * This is on-disk identity for every environment that already exists - it must never move,
+ * or every existing site's state becomes unreadable.
+ *
+ * A store scoped to a plugin (the fourth argument) keys
+ * `s3://<bucket>/state/<env>.<plugin>.json` instead, so a plugin's resources are recorded
+ * separately from the site's: `blogwright <plugin> destroy` never touches, and never
+ * discards, the site's own record of what exists.
+ *
+ * Scoping changes the key, not the bucket - a scoped and an unscoped store for the same
+ * environment are constructed over the same `names.bucket` (see
+ * `packages/cli/src/context.ts:134`) and both objects live side by side under that
+ * bucket's `state/` prefix. That prefix is not itself a safety boundary: the site's own
+ * bucket node empties it wholesale before deleting the bucket
+ * (`deletePrefix(ctx.names.bucket, '')`, `packages/cli/src/nodes.ts:66`), which would take
+ * every `state/<env>.<plugin>.json` with it. Keeping the two records genuinely independent
+ * is therefore a CLI-level policy, not something this class enforces: `blogwright destroy`
+ * is expected to refuse while any `state/<env>.<plugin>.json` exists, naming that plugin's
+ * `blogwright <plugin> destroy --yes`, so plugins are always torn down before the site that
+ * hosts them. `StateStore` itself is a store, not a policy - it does not add that guard.
  */
 export declare class StateStore {
     private readonly s3;
     private readonly bucket;
     private readonly env;
-    constructor(s3: S3Client, bucket: string, env: string);
+    private readonly key;
+    constructor(s3: S3Client, bucket: string, env: string, scope?: string);
     load(): Promise<OpsState>;
     save(state: OpsState): Promise<void>;
     delete(): Promise<void>;

package/dist/state.js

@@ -1,27 +1,54 @@
 export function emptyState(env) {
     return { version: 1, env, updatedAt: undefined, resources: {} };
 }
-function stateKey(env) {
-    return `state/${env}.json`;
+/** Namespace shape a plugin manifest declares - reused here so a scope can't smuggle a `/` or `..` into the key. */
+const SCOPE_PATTERN = /^[a-z0-9-]+$/;
+function stateKey(env, scope) {
+    return scope === undefined ? `state/${env}.json` : `state/${env}.${scope}.json`;
 }
 /**
- * S3-backed topology state. Lives at `s3://<bucket>/state/<env>.json` so it is shared
- * across machines and is the single source of truth for what has been provisioned.
+ * S3-backed topology state: the single source of truth for what has been provisioned.
+ *
+ * An unscoped store (three constructor arguments) keys `s3://<bucket>/state/<env>.json`.
+ * This is on-disk identity for every environment that already exists - it must never move,
+ * or every existing site's state becomes unreadable.
+ *
+ * A store scoped to a plugin (the fourth argument) keys
+ * `s3://<bucket>/state/<env>.<plugin>.json` instead, so a plugin's resources are recorded
+ * separately from the site's: `blogwright <plugin> destroy` never touches, and never
+ * discards, the site's own record of what exists.
+ *
+ * Scoping changes the key, not the bucket - a scoped and an unscoped store for the same
+ * environment are constructed over the same `names.bucket` (see
+ * `packages/cli/src/context.ts:134`) and both objects live side by side under that
+ * bucket's `state/` prefix. That prefix is not itself a safety boundary: the site's own
+ * bucket node empties it wholesale before deleting the bucket
+ * (`deletePrefix(ctx.names.bucket, '')`, `packages/cli/src/nodes.ts:66`), which would take
+ * every `state/<env>.<plugin>.json` with it. Keeping the two records genuinely independent
+ * is therefore a CLI-level policy, not something this class enforces: `blogwright destroy`
+ * is expected to refuse while any `state/<env>.<plugin>.json` exists, naming that plugin's
+ * `blogwright <plugin> destroy --yes`, so plugins are always torn down before the site that
+ * hosts them. `StateStore` itself is a store, not a policy - it does not add that guard.
  */
 export class StateStore {
     s3;
     bucket;
     env;
-    constructor(s3, bucket, env) {
+    key;
+    constructor(s3, bucket, env, scope) {
         this.s3 = s3;
         this.bucket = bucket;
         this.env = env;
+        if (scope !== undefined && !SCOPE_PATTERN.test(scope)) {
+            throw new Error(`state store scope must be lowercase alphanumeric/dashes, got "${scope}" for s3://${bucket}`);
+        }
+        this.key = stateKey(env, scope);
     }
     async load() {
         // getObjectText returns undefined only when the object/bucket does not exist (a fresh
-        // environment). A present-but-corrupt document must NOT be silently treated as empty —
-        // that would cause duplicate-resource creation — so let a parse error surface.
-        const text = await this.s3.getObjectText(this.bucket, stateKey(this.env));
+        // environment). A present-but-corrupt document must NOT be silently treated as empty -
+        // that would cause duplicate-resource creation - so let a parse error surface.
+        const text = await this.s3.getObjectText(this.bucket, this.key);
         // Strictly undefined: a present-but-empty (zero-byte) state object is
         // corruption, not a fresh environment, and must hit the guard below.
         if (text === undefined)
@@ -30,14 +57,14 @@ export class StateStore {
             return JSON.parse(text);
         }
         catch (err) {
-            throw new Error(`state/${this.env}.json in s3://${this.bucket} is not valid JSON — refusing to proceed with empty state`, { cause: err });
+            throw new Error(`${this.key} in s3://${this.bucket} is not valid JSON - refusing to proceed with empty state`, { cause: err });
         }
     }
     async save(state) {
         state.updatedAt = new Date().toISOString();
-        await this.s3.putObject(this.bucket, stateKey(this.env), JSON.stringify(state, null, 2), 'application/json');
+        await this.s3.putObject(this.bucket, this.key, JSON.stringify(state, null, 2), 'application/json');
     }
     async delete() {
-        await this.s3.deleteObject(this.bucket, stateKey(this.env)).catch(() => undefined);
+        await this.s3.deleteObject(this.bucket, this.key).catch(() => undefined);
     }
 }

package/dist/util.d.ts

@@ -1,3 +1,26 @@
+/**
+ * The fixed timestamp every reproducible zip in this repo stamps its entries
+ * with, so identical input bytes always produce identical archive bytes.
+ *
+ * **Constructed from local parts on purpose, and the obvious `Date.UTC` form is
+ * a bug.** A zip's DOS timestamp is *local* time, and `fflate` reads it with
+ * `getFullYear()`/`getMonth()`/`getDate()`, so a `Date` fixed in UTC lands on a
+ * different local date in every zone. Two things follow, and this repo shipped
+ * both:
+ *
+ * - `new Date('1980-01-01T00:00:00Z')` is 1979-12-31 local anywhere west of
+ *   Greenwich, and `fflate` throws `date not in range 1980-2099` outright -
+ *   so `blogwright bootstrap`, `deploy` and `analytics bootstrap` all failed
+ *   for most of the Americas while passing in CI, which runs `TZ=UTC`.
+ * - Even where it did not throw, the encoded timestamp differed by zone, so
+ *   the archive was *not* reproducible - the property the constant exists to
+ *   provide. The crash was hiding that.
+ *
+ * A local-constructed 1980-01-02 is 1980-01-02 in every zone by construction:
+ * in range everywhere, and byte-identical everywhere. The second of January
+ * rather than the first so that no offset can push it below the 1980 floor.
+ */
+export declare const REPRODUCIBLE_ZIP_MTIME: Date;
 export declare function sleep(ms: number): Promise<void>;
 export interface RetryOptions {
     attempts?: number;

package/dist/util.js

@@ -1,4 +1,27 @@
 import { isRetryable } from './aws/errors.js';
+/**
+ * The fixed timestamp every reproducible zip in this repo stamps its entries
+ * with, so identical input bytes always produce identical archive bytes.
+ *
+ * **Constructed from local parts on purpose, and the obvious `Date.UTC` form is
+ * a bug.** A zip's DOS timestamp is *local* time, and `fflate` reads it with
+ * `getFullYear()`/`getMonth()`/`getDate()`, so a `Date` fixed in UTC lands on a
+ * different local date in every zone. Two things follow, and this repo shipped
+ * both:
+ *
+ * - `new Date('1980-01-01T00:00:00Z')` is 1979-12-31 local anywhere west of
+ *   Greenwich, and `fflate` throws `date not in range 1980-2099` outright -
+ *   so `blogwright bootstrap`, `deploy` and `analytics bootstrap` all failed
+ *   for most of the Americas while passing in CI, which runs `TZ=UTC`.
+ * - Even where it did not throw, the encoded timestamp differed by zone, so
+ *   the archive was *not* reproducible - the property the constant exists to
+ *   provide. The crash was hiding that.
+ *
+ * A local-constructed 1980-01-02 is 1980-01-02 in every zone by construction:
+ * in range everywhere, and byte-identical everywhere. The second of January
+ * rather than the first so that no offset can push it below the 1980 floor.
+ */
+export const REPRODUCIBLE_ZIP_MTIME = new Date(1980, 0, 2);
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blogwright-core",
-  "version": "0.3.3",
+  "version": "0.4.0-beta.1",
   "type": "module",
   "sideEffects": false,
   "files": [