blogwright 0.3.3 → 0.4.0-beta.0

package/dist/commands.d.ts

@@ -1,6 +1,58 @@
+import { type ResourceNode } from 'blogwright-core';
 import type { OpsContext } from './context.js';
+import { type GraphContext } from './graph.js';
+import { type StatusEntry } from './render.js';
 /** Create the full infrastructure graph. */
 export declare function bootstrap(ctx: OpsContext): Promise<void>;
+/**
+ * Refuse to destroy the site while any plugin's own state object still
+ * exists in the bucket - §State → Scoped state stores' "`blogwright
+ * destroy` therefore refuses while any `state/<env>.<plugin>.json` exists".
+ *
+ * A scope changes the state object's KEY, not the bucket it lives in
+ * (`StateStore`, `packages/core/src/state.ts`) - a scoped and an unscoped
+ * store for the same environment are constructed over the very same
+ * `names.bucket` - and the site's own bucket node empties every prefix
+ * before deleting the bucket (`deletePrefix(ctx.names.bucket, '')`,
+ * `nodes.ts`'s `bucketNode().delete()`). Without this guard, a site
+ * teardown deletes `state/<env>.<scope>.json` while every resource it
+ * records lives on: the plugin's next `destroy` then loads empty state,
+ * every node's `read()` returns false, and nothing is removed - the
+ * plugin's resources are silently orphaned.
+ *
+ * Reads the bucket, not the plugin registry, so the refusal holds even for
+ * a plugin that has since been uninstalled. Runs inside the teardown verbs
+ * themselves, not `createContext` - so no other command pays for the extra
+ * `listObjects` call and plugin discovery stays lazy - and ahead of
+ * `clearRunningMicrovms`/`destroyGraph` in each, so a refusal has zero side
+ * effects: nothing is terminated, nothing is deleted.
+ *
+ * BOTH teardown verbs call it: `destroy` (below) and `previewTeardown`,
+ * which runs the very same `destroyGraph(buildNodes(ctx), ctx)` over the
+ * very same `bucketNode().delete()` and so empties the preview stack's
+ * bucket - including a `state/<env>.<scope>.json` a plugin bootstrapped
+ * against that environment - in exactly the same way. Nothing about the
+ * orphaning above is specific to the site's own environment, so nothing
+ * about the guard is either.
+ *
+ * A MISSING BUCKET IS TREATED AS CLEAR, not as an error. `listObjects` does
+ * not swallow a 404 the way `getObjectText` does, so an environment whose
+ * bucket a previous (interrupted) teardown already deleted would otherwise
+ * fail here with a raw `NoSuchBucket` before a single non-bucket resource -
+ * roles, log groups, the CloudFront function, the delivery trio - had been
+ * cleaned up, on precisely the recovery path an operator reaches for after
+ * an interrupted teardown. A bucket that is gone holds no state object at
+ * all, scoped or otherwise, so there is nothing to protect and every reason
+ * to let the teardown finish: refusing here would CAUSE the orphaning this
+ * guard exists to prevent. Only `NoSuchBucket` is treated this way - every
+ * other failure (denied, throttled, a network fault) still propagates,
+ * because those say nothing about whether scoped state exists.
+ *
+ * Exported - like `readNodeStatus` above - so a test can pin its outcomes
+ * directly against a recording S3 client, rather than only through a full
+ * `destroy()` run over the entire production graph.
+ */
+export declare function assertNoScopedState(ctx: OpsContext): Promise<void>;
 /** Destroy the full infrastructure graph. */
 export declare function destroy(ctx: OpsContext, opts: {
     yes: boolean;
@@ -19,7 +71,7 @@ export declare function previewBootstrap(ctx: OpsContext): Promise<void>;
 export declare function previewDeploy(ctx: OpsContext, id: string, opts?: {
     refresh?: boolean;
 }): Promise<string>;
-/** Remove one PR's preview (delete its prefix). No invalidation — previews aren't cached. */
+/** Remove one PR's preview (delete its prefix). No invalidation - previews aren't cached. */
 export declare function previewDestroy(ctx: OpsContext, id: string): Promise<void>;
 /** List active previews (by prefix). */
 export declare function previewList(ctx: OpsContext): Promise<void>;
@@ -33,5 +85,20 @@ export declare function deleteSite(ctx: OpsContext): Promise<void>;
 export declare function history(ctx: OpsContext): Promise<void>;
 /** Show CloudWatch build logs for a given hash. */
 export declare function logs(ctx: OpsContext, hash: string): Promise<void>;
-/** Show the planned graph against live state (drift view). */
-export declare function status(ctx: OpsContext): Promise<void>;
+/**
+ * Read each node's live status against `ctx.state`: present/missing from
+ * `node.read(ctx)`, or an `error` entry carrying the message if it throws.
+ * A query, not a command - it never writes to the logger, so a caller (the
+ * CLI's own `status` below, and a plugin's `status` verb) decides how to
+ * report each entry. Iterates `nodes` in the order given (no `topoSort` -
+ * status is a read, not a reconcile, so dependency order doesn't matter).
+ */
+export declare function readNodeStatus<Ctx extends GraphContext>(nodes: ResourceNode<Ctx>[], ctx: Ctx): Promise<StatusEntry[]>;
+/**
+ * Show the planned graph against live state (drift view). `nodes` defaults to
+ * the production graph (`buildNodes(ctx)`) - every real call site is
+ * unchanged - but is a parameter, not reached-for, so a test (or a future
+ * caller) can hand this the same loop over a different node set without
+ * patching a module.
+ */
+export declare function status(ctx: OpsContext, nodes?: ResourceNode<OpsContext>[]): Promise<void>;

package/dist/commands.js

@@ -1,18 +1,42 @@
-import { colors, findRepoRoot } from 'blogwright-core';
+import { AwsError, colors, findRepoRoot } from 'blogwright-core';
+/*
+ * A STATIC, NON-OPTIONAL IMPORT, and deliberately the last one left in the
+ * CLI. Task 29 deleted every other reference to `blogwright-pds` from the
+ * dispatcher (`cli.ts` now knows no namespace by name; the package is
+ * discovered and dispatched as an ordinary plugin), and this one still
+ * stays, for two reasons:
+ *
+ *   - THE SPI HAS NO LIFECYCLE HOOKS. `Plugin` (`blogwright-core`'s
+ *     `plugin.ts`) declares `commands`, `nodes`, `configKey`,
+ *     `validateConfig` and `init` - nothing a plugin could register to be
+ *     called after a successful deploy. `deploy` below therefore reaches
+ *     this function by name, exactly as it always has; routing it through
+ *     plugin dispatch would mean inventing a hook the change spec does not
+ *     describe.
+ *   - THE PACKAGE SHIPS BY DEFAULT. `blogwright-pds` is a non-optional
+ *     `dependencies` entry of `packages/cli/package.json` - that is how the
+ *     bundled plugin reaches a consuming repo that depends on `blogwright`
+ *     alone - so the import can never fail to resolve, and no optional-
+ *     dependency guard is needed around it.
+ *
+ * `syncAfterDeploy` no-ops for any environment but `production` and for a
+ * site with no `pds` config block, so an unconfigured repo pays nothing for
+ * it. Both halves are asserted in `commands.test.ts`.
+ */
 import { syncAfterDeploy } from 'blogwright-pds';
 import { invalidateChanged, invalidateCloudFront, manifestKey, microvmLogGroup, runBuild, } from './deploy.js';
 import { applyGraph, destroyGraph } from './graph.js';
 import { clearRunningMicrovms } from './microvms.js';
 import { buildNodes, reconcileBuilderImage } from './nodes.js';
-import { formatDuration, renderHistoryTable, renderStatusTree, renderSummary, } from './render.js';
+import { formatDuration, logStatusEntries, renderHistoryTable, renderSummary, } from './render.js';
 import { buildRepoZip, COMMIT_FILE, listRepoFiles } from './repo.js';
 /** One line per invalidation outcome, shared by the summary card and logs. */
 function describeInvalidation(inv) {
     if (inv.mode === 'none')
-        return 'nothing changed — skipped';
+        return 'nothing changed - skipped';
     if (inv.mode === 'paths')
         return `${inv.count} changed path${inv.count === 1 ? '' : 's'}`;
-    return inv.count > 0 ? `everything (/*) — ${inv.count} paths over cap` : 'everything (/*)';
+    return inv.count > 0 ? `everything (/*) - ${inv.count} paths over cap` : 'everything (/*)';
 }
 /**
  * Canonical origin the live site is served from: the custom domain if configured,
@@ -34,11 +58,125 @@ export async function bootstrap(ctx) {
     if (typeof domain === 'string')
         ctx.logger.info(`Site will be served at https://${domain}`);
 }
+/**
+ * The prefix every state object - scoped or not - is filed under
+ * (`StateStore`, `packages/core/src/state.ts`). Not exported from core, so
+ * mirrored here rather than reached for; the guard below only ever reads
+ * this prefix, never constructs a key to write.
+ */
+const STATE_PREFIX = 'state/';
+/** The site's own unscoped state key - the one object under `STATE_PREFIX` the guard below must never treat as a plugin's. */
+function siteStateKey(env) {
+    return `${STATE_PREFIX}${env}.json`;
+}
+/**
+ * Every plugin scope with a `state/<env>.<scope>.json` object present under
+ * `STATE_PREFIX`, derived from a listing rather than the plugin registry -
+ * so {@link assertNoScopedState} holds even for a plugin that has since
+ * been uninstalled. Sorted, so the guard's message is deterministic
+ * regardless of the order S3 lists objects in.
+ */
+function scopedStateScopes(env, objects) {
+    const prefix = `${STATE_PREFIX}${env}.`;
+    const site = siteStateKey(env);
+    const scopes = objects
+        .map((o) => o.key)
+        .filter((key) => key !== site && key.startsWith(prefix) && key.endsWith('.json'))
+        .map((key) => key.slice(prefix.length, -'.json'.length));
+    return [...new Set(scopes)].sort();
+}
+/**
+ * Refuse to destroy the site while any plugin's own state object still
+ * exists in the bucket - §State → Scoped state stores' "`blogwright
+ * destroy` therefore refuses while any `state/<env>.<plugin>.json` exists".
+ *
+ * A scope changes the state object's KEY, not the bucket it lives in
+ * (`StateStore`, `packages/core/src/state.ts`) - a scoped and an unscoped
+ * store for the same environment are constructed over the very same
+ * `names.bucket` - and the site's own bucket node empties every prefix
+ * before deleting the bucket (`deletePrefix(ctx.names.bucket, '')`,
+ * `nodes.ts`'s `bucketNode().delete()`). Without this guard, a site
+ * teardown deletes `state/<env>.<scope>.json` while every resource it
+ * records lives on: the plugin's next `destroy` then loads empty state,
+ * every node's `read()` returns false, and nothing is removed - the
+ * plugin's resources are silently orphaned.
+ *
+ * Reads the bucket, not the plugin registry, so the refusal holds even for
+ * a plugin that has since been uninstalled. Runs inside the teardown verbs
+ * themselves, not `createContext` - so no other command pays for the extra
+ * `listObjects` call and plugin discovery stays lazy - and ahead of
+ * `clearRunningMicrovms`/`destroyGraph` in each, so a refusal has zero side
+ * effects: nothing is terminated, nothing is deleted.
+ *
+ * BOTH teardown verbs call it: `destroy` (below) and `previewTeardown`,
+ * which runs the very same `destroyGraph(buildNodes(ctx), ctx)` over the
+ * very same `bucketNode().delete()` and so empties the preview stack's
+ * bucket - including a `state/<env>.<scope>.json` a plugin bootstrapped
+ * against that environment - in exactly the same way. Nothing about the
+ * orphaning above is specific to the site's own environment, so nothing
+ * about the guard is either.
+ *
+ * A MISSING BUCKET IS TREATED AS CLEAR, not as an error. `listObjects` does
+ * not swallow a 404 the way `getObjectText` does, so an environment whose
+ * bucket a previous (interrupted) teardown already deleted would otherwise
+ * fail here with a raw `NoSuchBucket` before a single non-bucket resource -
+ * roles, log groups, the CloudFront function, the delivery trio - had been
+ * cleaned up, on precisely the recovery path an operator reaches for after
+ * an interrupted teardown. A bucket that is gone holds no state object at
+ * all, scoped or otherwise, so there is nothing to protect and every reason
+ * to let the teardown finish: refusing here would CAUSE the orphaning this
+ * guard exists to prevent. Only `NoSuchBucket` is treated this way - every
+ * other failure (denied, throttled, a network fault) still propagates,
+ * because those say nothing about whether scoped state exists.
+ *
+ * Exported - like `readNodeStatus` above - so a test can pin its outcomes
+ * directly against a recording S3 client, rather than only through a full
+ * `destroy()` run over the entire production graph.
+ */
+export async function assertNoScopedState(ctx) {
+    let objects;
+    try {
+        objects = await ctx.clients.s3.listObjects(ctx.names.bucket, STATE_PREFIX);
+    }
+    catch (err) {
+        // No bucket, no state objects - see this function's doc comment. Matched
+        // on the bucket's own error code rather than the broad `isNotFound`,
+        // which is equally true of `NoSuchKey` and of ANY 404 (`AwsError`,
+        // `packages/core/src/aws/errors.ts`): a spurious 404 from a non-AWS,
+        // S3-compatible endpoint (`--endpoint`) would otherwise read as "no
+        // scoped state" and let the teardown empty the bucket over a plugin's
+        // live state object - the exact orphaning this guard exists to prevent.
+        // Every other failure propagates, which ends the teardown safely rather
+        // than deleting past the guard.
+        if (err instanceof AwsError && err.code === 'NoSuchBucket')
+            return;
+        throw err;
+    }
+    const scopes = scopedStateScopes(ctx.env, objects);
+    if (scopes.length === 0)
+        return;
+    // The remedy MUST name the environment. `runPlugin` resolves a plugin
+    // command's environment as `values.env ?? envPositional ?? DEFAULT_ENV`
+    // with `DEFAULT_ENV = 'production'` (`plugin-commands.ts`), so an env-less
+    // `blogwright <scope> destroy --yes` silently targets production - always
+    // the wrong environment when this guard fires from `previewTeardown`,
+    // which builds `env: 'preview'` unconditionally (`cli.ts`'s `runPreview`).
+    // Printed against a preview refusal, the env-less form at best loads empty
+    // state and removes nothing, leaving the operator stuck in this same
+    // refusal, and at worst tears down the live production stack. `deriveNames`
+    // keys off `env` alone, so the positional below is the whole fix - and it
+    // covers both callers, because each passes the very environment it is
+    // tearing down.
+    const lines = scopes.map((scope) => `  - ${scope}: run \`blogwright ${scope} destroy ${ctx.env} --yes\` first`);
+    throw new Error(`refusing to destroy "${ctx.env}": ${scopes.length} plugin state object(s) still exist in ` +
+        `s3://${ctx.names.bucket}/${STATE_PREFIX}\n${lines.join('\n')}`);
+}
 /** Destroy the full infrastructure graph. */
 export async function destroy(ctx, opts) {
     if (!opts.yes) {
         throw new Error(`refusing to destroy "${ctx.env}" without --yes`);
     }
+    await assertNoScopedState(ctx);
     ctx.logger.info(colors.bold(`Destroying "${ctx.env}"`));
     // Running builder MicroVMs pin the image and make its deletion fail; clear them first
     // (or let the operator cancel and wait for in-flight builds to finish).
@@ -70,7 +208,7 @@ export async function deploy(ctx, opts = {}) {
         ...(opts.refresh ? { refresh: true } : {}),
     });
     const invalidation = await invalidateChanged(ctx, hash);
-    // Production content changed — mirror it to the PDS (non-fatal; see syncAfterDeploy).
+    // Production content changed - mirror it to the PDS (non-fatal; see syncAfterDeploy).
     await syncAfterDeploy(ctx);
     const url = siteBaseUrl(ctx);
     const rows = [
@@ -102,7 +240,7 @@ export async function rollback(ctx, hash, opts = {}) {
     });
     await invalidateChanged(ctx, hash);
     // A rollback changes production content too, but the PDS mirrors the *working tree*
-    // content, which a rollback does not restore — so only warn about the divergence.
+    // content, which a rollback does not restore - so only warn about the divergence.
     if (ctx.env === 'production' && ctx.config.pds) {
         ctx.logger.warn('rollback does not sync the PDS (records mirror the current repo content); ' +
             'check out the rolled-back revision and run `blogwright pds sync` if needed');
@@ -151,7 +289,7 @@ export async function previewDeploy(ctx, id, opts = {}) {
     ctx.logger.ok(`preview ready in ${formatDuration(Date.now() - startedAt)}: ${url}`);
     return url;
 }
-/** Remove one PR's preview (delete its prefix). No invalidation — previews aren't cached. */
+/** Remove one PR's preview (delete its prefix). No invalidation - previews aren't cached. */
 export async function previewDestroy(ctx, id) {
     assertPreviewId(id);
     const count = await ctx.clients.s3.deletePrefix(ctx.names.bucket, `previews/${id}/`);
@@ -172,6 +310,12 @@ export async function previewList(ctx) {
 export async function previewTeardown(ctx, opts) {
     if (!opts.yes)
         throw new Error('refusing to tear down the preview stack without --yes');
+    // The preview stack's teardown is the SITE teardown's graph over the
+    // preview environment's own bucket - same `destroyGraph(buildNodes(ctx))`,
+    // same `bucketNode().delete()` emptying every prefix - so a plugin
+    // bootstrapped against this environment is orphaned here in exactly the
+    // way `destroy` above is guarded against. See `assertNoScopedState`.
+    await assertNoScopedState(ctx);
     ctx.logger.info(colors.bold('Tearing down preview stack'));
     if (!(await clearRunningMicrovms(ctx)))
         return;
@@ -230,7 +374,7 @@ export async function logs(ctx, hash) {
         manifest = text ? JSON.parse(text) : undefined;
     }
     catch {
-        ctx.logger.warn(`manifest for ${hash} is unreadable — showing the unfiltered log window`);
+        ctx.logger.warn(`manifest for ${hash} is unreadable - showing the unfiltered log window`);
     }
     // Filter to the build's time window (± a minute) from the manifest.
     const startTime = manifest ? Date.parse(manifest.startedAt) - 60_000 : undefined;
@@ -247,37 +391,40 @@ export async function logs(ctx, hash) {
         ctx.logger.info(`${colors.dim(new Date(e.timestamp).toISOString())} ${e.message.trimEnd()}`);
     }
 }
-/** Show the planned graph against live state (drift view). */
-export async function status(ctx) {
-    ctx.logger.info(colors.bold(`Status for "${ctx.env}" (bucket ${ctx.names.bucket})`));
-    const pretty = ctx.ports.terminal.isInteractive;
+/**
+ * Read each node's live status against `ctx.state`: present/missing from
+ * `node.read(ctx)`, or an `error` entry carrying the message if it throws.
+ * A query, not a command - it never writes to the logger, so a caller (the
+ * CLI's own `status` below, and a plugin's `status` verb) decides how to
+ * report each entry. Iterates `nodes` in the order given (no `topoSort` -
+ * status is a read, not a reconcile, so dependency order doesn't matter).
+ */
+export async function readNodeStatus(nodes, ctx) {
     const entries = [];
-    for (const node of buildNodes(ctx)) {
+    for (const node of nodes) {
         let exists = false;
         try {
             exists = await node.read(ctx);
         }
         catch (err) {
-            if (pretty) {
-                entries.push({ title: node.title, state: 'error', detail: err.message });
-            }
-            else {
-                ctx.logger.warn(`${node.title}: read failed (${err.message})`);
-            }
+            entries.push({ title: node.title, state: 'error', detail: err.message });
             continue;
         }
         const outputs = ctx.state.resources[node.id];
         const detail = outputs ? JSON.stringify(outputs) : undefined;
-        if (pretty) {
-            entries.push({ title: node.title, state: exists ? 'present' : 'missing', detail });
-            continue;
-        }
-        // The plain form is the stable contract for CI logs and agents.
-        const mark = exists ? colors.green('present') : colors.yellow('missing');
-        ctx.logger.info(`  ${mark}  ${node.title} ${detail ? colors.dim(detail) : ''}`);
-    }
-    if (pretty) {
-        for (const line of renderStatusTree(entries))
-            ctx.logger.info(line);
+        entries.push({ title: node.title, state: exists ? 'present' : 'missing', detail });
     }
+    return entries;
+}
+/**
+ * Show the planned graph against live state (drift view). `nodes` defaults to
+ * the production graph (`buildNodes(ctx)`) - every real call site is
+ * unchanged - but is a parameter, not reached-for, so a test (or a future
+ * caller) can hand this the same loop over a different node set without
+ * patching a module.
+ */
+export async function status(ctx, nodes = buildNodes(ctx)) {
+    ctx.logger.info(colors.bold(`Status for "${ctx.env}" (bucket ${ctx.names.bucket})`));
+    const entries = await readNodeStatus(nodes, ctx);
+    logStatusEntries(entries, ctx.ports.terminal.isInteractive, ctx.logger);
 }

package/dist/config-block.d.ts

@@ -0,0 +1,34 @@
+/** The file a block is spliced into. */
+export interface ConfigSource {
+    readonly path: string;
+    readonly text: string;
+}
+/** A rendered block ready to splice in, and the key it is filed under. */
+export interface ConfigBlock {
+    readonly key: string;
+    readonly rendered: string;
+}
+/** One entry of a rendered block, matching `renderConfig`'s own entry shape. */
+export interface ConfigBlockEntry {
+    readonly prop: string;
+    readonly comment?: string | undefined;
+}
+/**
+ * Render `entries` as a `"key": { ... }` block in `renderConfig`'s style
+ * (`init.ts:42-69`): two-space indent per nesting level, an optional
+ * `// comment` suffix per entry, and a comma between entries but never after
+ * the last one. The result is meant to be handed to `spliceConfigBlock` as
+ * `block.rendered`, already indented as it will appear once inserted as a
+ * property of the top-level object.
+ */
+export declare function renderConfigBlock(key: string, entries: readonly ConfigBlockEntry[]): string;
+/**
+ * Splice `block.rendered` into `source.text` as a new property of the
+ * document's single top-level object, immediately before its closing brace.
+ * The document is scanned, never reparsed: every byte outside the inserted
+ * region - comments, indentation, trailing commas - comes back unchanged.
+ *
+ * Refuses rather than guessing when `block.key` is already present on the
+ * object, or when the document is not shaped as a single top-level object.
+ */
+export declare function spliceConfigBlock(source: ConfigSource, block: ConfigBlock): string;

package/dist/config-block.js

@@ -0,0 +1,262 @@
+/*
+ * Textual splice of a plugin's config block into an existing JSONC document.
+ * Config files carry meaningful comments written by the wizard (`init.ts:42`
+ * `renderConfig`), so the document is never round-tripped through a parse
+ * and a re-stringify here - doing that would discard every one of them.
+ * Instead this module scans the raw text with the same string- and
+ * comment-aware discipline as `stripJsonComments`
+ * (`packages/core/src/config.ts:153`) to find exactly where a new top-level
+ * key belongs, and splices the rendered block in around it, leaving every
+ * other byte of the file untouched.
+ */
+/**
+ * Render `entries` as a `"key": { ... }` block in `renderConfig`'s style
+ * (`init.ts:42-69`): two-space indent per nesting level, an optional
+ * `// comment` suffix per entry, and a comma between entries but never after
+ * the last one. The result is meant to be handed to `spliceConfigBlock` as
+ * `block.rendered`, already indented as it will appear once inserted as a
+ * property of the top-level object.
+ */
+export function renderConfigBlock(key, entries) {
+    if (entries.length === 0)
+        return `  "${key}": {}`;
+    const body = entries.map((entry, i) => {
+        const comma = i < entries.length - 1 ? ',' : '';
+        const comment = entry.comment ? ` // ${entry.comment}` : '';
+        return `    ${entry.prop}${comma}${comment}`;
+    });
+    return [`  "${key}": {`, ...body, '  }'].join('\n');
+}
+/** Decode a JSON string literal's escapes by hand, without parsing it as JSON. */
+function decodeStringLiteral(raw) {
+    let out = '';
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch !== '\\') {
+            out += ch;
+            continue;
+        }
+        const esc = raw[++i];
+        switch (esc) {
+            case 'n':
+                out += '\n';
+                break;
+            case 't':
+                out += '\t';
+                break;
+            case 'r':
+                out += '\r';
+                break;
+            case 'b':
+                out += '\b';
+                break;
+            case 'f':
+                out += '\f';
+                break;
+            case 'u':
+                out += String.fromCharCode(Number.parseInt(raw.slice(i + 1, i + 5), 16));
+                i += 4;
+                break;
+            default:
+                out += esc ?? '';
+        }
+    }
+    return out;
+}
+function shapeError(path, found) {
+    return new Error(`${path}: expected a single top-level JSON object, found ${found} - insert the block by hand instead`);
+}
+/**
+ * Scan `source.text` once, string- and comment-aware like `stripJsonComments`,
+ * to find the single top-level object's opening and closing brace, the last
+ * significant (non-whitespace, non-comment) character before that closing
+ * brace, and the set of keys already declared directly on that object. Raises
+ * rather than guessing when the document is not shaped that way.
+ *
+ * Key-position tracking (`expectKey`) is deliberately generic: opening any
+ * object, or a comma inside one, expects a key at *that* depth, not only at
+ * the top - the same test that decides whether a value is a key at all also
+ * runs for every nested object. `depth === 1` is the only thing that then
+ * scopes a found key into `topLevelKeys`, so a `"pds"` nested three objects
+ * down is read as a key (of its own object) and correctly not recorded as
+ * one of the document's own.
+ */
+function scanTopLevelObject(source) {
+    const { path, text } = source;
+    let inString = false;
+    let inLine = false;
+    let inBlock = false;
+    let depth = 0;
+    let openIndex = -1;
+    let closeIndex = -1;
+    let lastSignificantIndex = -1;
+    let stringStart = -1;
+    let expectKey = false;
+    const containers = [];
+    const topLevelKeys = new Set();
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inLine) {
+            if (ch === '\n')
+                inLine = false;
+            continue;
+        }
+        if (inBlock) {
+            if (ch === '*' && next === '/') {
+                inBlock = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\') {
+                i++;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+                lastSignificantIndex = i;
+                if (expectKey) {
+                    if (depth === 1)
+                        topLevelKeys.add(decodeStringLiteral(text.slice(stringStart + 1, i)));
+                    expectKey = false;
+                }
+            }
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            inLine = true;
+            i++;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            inBlock = true;
+            i++;
+            continue;
+        }
+        if (/\s/.test(ch))
+            continue;
+        // `ch` is now a significant character outside any string or comment.
+        if (openIndex === -1) {
+            if (ch !== '{')
+                throw shapeError(path, ch === '[' ? 'an array' : 'a bare value');
+            openIndex = i;
+            lastSignificantIndex = i;
+            depth = 1;
+            containers.push('object');
+            expectKey = true;
+            continue;
+        }
+        if (closeIndex !== -1)
+            throw shapeError(path, 'a second top-level value');
+        if (ch === '"') {
+            inString = true;
+            stringStart = i;
+            continue;
+        }
+        if (ch === '{' || ch === '[') {
+            depth++;
+            lastSignificantIndex = i;
+            containers.push(ch === '{' ? 'object' : 'array');
+            expectKey = ch === '{';
+            continue;
+        }
+        if (ch === '}' || ch === ']') {
+            depth--;
+            containers.pop();
+            if (depth === 0) {
+                closeIndex = i;
+            }
+            else {
+                lastSignificantIndex = i;
+            }
+            continue;
+        }
+        if (ch === ',') {
+            lastSignificantIndex = i;
+            expectKey = containers[containers.length - 1] === 'object';
+            continue;
+        }
+        lastSignificantIndex = i;
+    }
+    if (openIndex === -1)
+        throw shapeError(path, 'an empty document');
+    if (closeIndex === -1) {
+        throw shapeError(path, inString ? 'an unterminated string inside the object' : 'an unterminated object');
+    }
+    return { openIndex, closeIndex, lastSignificantIndex, topLevelKeys };
+}
+/**
+ * Starting at `from` (just past the last entry's value or its trailing
+ * comma), skip past a comment that trails on the *same line* - `"x" //
+ * note` or `"x" /* note *\/` - so that comment stays attached to the entry
+ * it documents instead of being displaced by whatever gets spliced in
+ * after it. Stops at the first line break, at `limit` (the object's closing
+ * brace), or at the first character that is neither trailing whitespace nor
+ * the start of such a comment.
+ */
+function skipTrailingComment(text, from, limit) {
+    let i = from;
+    for (;;) {
+        while (i < limit && (text[i] === ' ' || text[i] === '\t'))
+            i++;
+        if (i >= limit || text[i] === '\n' || text[i] === '\r')
+            return i;
+        if (text[i] === '/' && text[i + 1] === '/') {
+            i += 2;
+            while (i < limit && text[i] !== '\n' && text[i] !== '\r')
+                i++;
+            return i;
+        }
+        if (text[i] === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end === -1 || end + 2 > limit ? limit : end + 2;
+            continue;
+        }
+        return i;
+    }
+}
+/** True when `text` has a line break (LF or CRLF) starting at `at`. */
+function startsWithNewline(text, at) {
+    return text[at] === '\n' || (text[at] === '\r' && text[at + 1] === '\n');
+}
+/**
+ * Splice `block.rendered` into `source.text` as a new property of the
+ * document's single top-level object, immediately before its closing brace.
+ * The document is scanned, never reparsed: every byte outside the inserted
+ * region - comments, indentation, trailing commas - comes back unchanged.
+ *
+ * Refuses rather than guessing when `block.key` is already present on the
+ * object, or when the document is not shaped as a single top-level object.
+ */
+export function spliceConfigBlock(source, block) {
+    const { text, path } = source;
+    const scan = scanTopLevelObject(source);
+    if (scan.topLevelKeys.has(block.key)) {
+        throw new Error(`${path} already declares a "${block.key}" key - edit the file directly instead of ` +
+            'writing a new block for it');
+    }
+    // The comma belongs immediately after the last entry's own value, but the
+    // new block belongs after that entry's trailing comment (if any) - an
+    // operator's `// comment` on the last line documents that entry, not
+    // whatever gets spliced in next, and must not be pushed onto its own line
+    // in between.
+    const commaIndex = scan.lastSignificantIndex + 1;
+    const hasEntries = scan.lastSignificantIndex > scan.openIndex;
+    const hasTrailingComma = hasEntries && text[scan.lastSignificantIndex] === ',';
+    const commaPrefix = hasEntries && !hasTrailingComma ? ',' : '';
+    const blockIndex = skipTrailingComment(text, commaIndex, scan.closeIndex);
+    // Match the document's own line-ending convention rather than always
+    // injecting a bare `\n`, so a CRLF file does not end up with a mixed-ending
+    // splice or a spurious blank line before the closing brace.
+    const newline = text.includes('\r\n') ? '\r\n' : '\n';
+    const rendered = newline === '\n' ? block.rendered : block.rendered.replaceAll('\n', newline);
+    const needsTrailingNewline = !startsWithNewline(text, blockIndex);
+    const insertion = `${newline}${rendered}${needsTrailingNewline ? newline : ''}`;
+    return (text.slice(0, commaIndex) +
+        commaPrefix +
+        text.slice(commaIndex, blockIndex) +
+        insertion +
+        text.slice(blockIndex));
+}