dsh-featherhunter-plugin-base 0.0.1 → 0.0.2-drill

package/dist/node/index.d.ts

@@ -1,33 +1,10 @@
 import type { Manifest, PluginEntry } from "../core/types";
+import { BLOCK_MARKERS } from "./readme-sync";
 import type { BlockRenderOptions, VerifyResult } from "./types";
 export * from "./types";
 export * from "./readme-compare";
-/** Managed-block markers. Writers only ever touch the text between them. */
-export declare const BLOCK_MARKERS: {
-    readonly contact: {
-        readonly start: "<!-- dsh-base:contact:start -->";
-        readonly end: "<!-- dsh-base:contact:end -->";
-    };
-    readonly starHistory: {
-        readonly start: "<!-- dsh-base:star-history:start -->";
-        readonly end: "<!-- dsh-base:star-history:end -->";
-    };
-    readonly thanks: {
-        readonly start: "<!-- dsh-base:thanks:start -->";
-        readonly end: "<!-- dsh-base:thanks:end -->";
-    };
-    readonly more: {
-        readonly start: "<!-- dsh-base:more:start -->";
-        readonly end: "<!-- dsh-base:more:end -->";
-    };
-};
-/**
- * Render the contact block (README table of groups).
- *
- * Placeholder implementation: ticket 06 replaces it with the two-variant
- * renderer plus snapshot fixtures.
- */
-export declare function renderContactBlock(options?: BlockRenderOptions): string;
+export * from "./renderers";
+export * from "./readme-sync";
 /** Render the star-history block. Placeholder until ticket 10. */
 export declare function renderStarHistoryBlock(options?: BlockRenderOptions): string;
 /** Render the thanks block. Placeholder until ticket 10. */

package/dist/node/index.js

@@ -2,9 +2,9 @@
 var BASELINE = {
   "manifest": {
     "schema": 1,
-    "version": "0.0.1",
-    "revision": 1,
-    "updatedAt": "2026-10-23T00:00:00+08:00",
+    "version": "0.0.2-drill",
+    "revision": 2,
+    "updatedAt": "2026-10-31T00:00:00+08:00",
     "fallbackUrl": "https://github.com/FeatherHunter/featherhunter-plugin-manage",
     "groups": [
       {
@@ -79,10 +79,10 @@ var BASELINE = {
           "zh": "DSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4\u5FAE\u4FE1\u7FA4\u4E8C\u7EF4\u7801",
           "en": "DSH plugin community group WeChat QR code"
         },
-        "card": "card-wechat-2026-10-23.png",
+        "card": "card-wechat-2026-11-06.png",
         "qr": {
           "kind": "remote",
-          "path": "qr-wechat-2026-10-23.png"
+          "path": "qr-wechat-2026-11-06.png"
         },
         "title": {
           "zh": "DSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4",
@@ -92,7 +92,7 @@ var BASELINE = {
           "zh": "\u7FA4\u804A\uFF1ADSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4",
           "en": "Group chat: DSH Plugin Community"
         },
-        "validUntil": "2026-10-30"
+        "validUntil": "2026-11-06"
       }
     ],
     "plugins": [
@@ -174,6 +174,19 @@ function sortByOrder(items) {
   return [...items].sort((a, b) => a.order - b.order);
 }
 
+// src/node/readme-sync.ts
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
 // src/node/readme-compare.ts
 var MORE_HEADING = /\bMORE\b|作者的其他作品|More from the author|More by the author/i;
 var THANKS_HEADING = /\bTHANKS\b|致谢|\bThanks\b|\bContributors\b/i;
@@ -788,35 +801,372 @@ function compareReadmeBlocks(expected, actual, options = {}) {
   };
 }
 
-// src/node/index.ts
-var BLOCK_MARKERS = {
-  contact: { start: "<!-- dsh-base:contact:start -->", end: "<!-- dsh-base:contact:end -->" },
-  starHistory: {
-    start: "<!-- dsh-base:star-history:start -->",
-    end: "<!-- dsh-base:star-history:end -->"
+// src/node/renderers.ts
+var DEFAULT_CDN_BASE = "https://cdn.jsdelivr.net/npm/dsh-featherhunter-plugin-base";
+var CONTACT_CARD_WIDTH = 260;
+var CONTACT_TEXT = {
+  sub: "CONNECT",
+  heading: {
+    zh: "\u53CD\u9988\u4E0E\u8054\u7CFB",
+    en: "Feedback and Contact"
   },
-  thanks: { start: "<!-- dsh-base:thanks:start -->", end: "<!-- dsh-base:thanks:end -->" },
-  more: { start: "<!-- dsh-base:more:start -->", end: "<!-- dsh-base:more:end -->" }
+  welcome: {
+    zh: "\u{1F44F}\u6B22\u8FCE\u63D0\u4EA4PR\u3001ISSUE\u3002\u661F\u661F\u4E4B\u706B\u53EF\u4EE5\u71CE\u539F\u{1F525}\u6709\u4EFB\u4F55\u5EFA\u8BAE\u3001\u610F\u89C1\u3001\u60F3\u6CD5\u3001\u5410\u69FD\u3001idea\u90FD\u53EF\u4EE5\u8FDB\u7FA4\u4EA4\u6D41\u3002",
+    en: "\u{1F44F}Welcome PRs and issues. A single spark can start a prairie fire \u{1F525}. Any suggestion, opinion, idea or rant \u2014 come join the group and talk."
+  }
 };
+var DATE_IN_FILENAME = /(\d{4})-(\d{2})-(\d{2})/;
+var DATE_IN_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})/;
 function resolveManifest(options) {
   return options.manifest ?? BASELINE.manifest;
 }
 function resolveLang(options) {
   return options.lang ?? "zh";
 }
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function contactCardCacheDate(group, manifest) {
+  const fromCard = DATE_IN_FILENAME.exec(group.card);
+  if (fromCard !== null) return fromCard[1] + fromCard[2] + fromCard[3];
+  if (group.validUntil === void 0) return null;
+  const fromManifest = DATE_IN_TIMESTAMP.exec(manifest.updatedAt);
+  if (fromManifest === null) {
+    throw new Error(
+      "manifest.updatedAt must start with YYYY-MM-DD when a group has validUntil (group: " + group.id + ")"
+    );
+  }
+  return fromManifest[1] + fromManifest[2] + fromManifest[3];
+}
+function contactCardUrl(group, manifest, options = {}) {
+  const base = (options.cdnBase ?? DEFAULT_CDN_BASE).replace(/\/+$/, "");
+  if (!/^https:\/\/[^\s"'<>]+$/i.test(base)) {
+    throw new Error('contact CDN base must be an absolute https URL (got "' + base + '")');
+  }
+  const card = group.card.trim();
+  if (card === "") throw new Error('contact group "' + group.id + '" has an empty card file name');
+  if (card.includes("/") || card.includes("\\") || /^[a-z]+:/i.test(card)) {
+    throw new Error('contact card must be a bare file name under data/img/ (got "' + card + '")');
+  }
+  const version = options.version ?? manifest.version;
+  if (version === "") throw new Error("contact CDN URL needs a manifest version");
+  let url = base + "@" + version + "/data/img/" + card;
+  const cacheDate = contactCardCacheDate(group, manifest);
+  if (cacheDate !== null) url += "?v=" + cacheDate;
+  return url;
+}
+function contactHeading(lang, options) {
+  const text = CONTACT_TEXT.heading[lang];
+  if (options.variant === "markdown-heading") return "## " + text;
+  return '<h2 align="center"><sub>' + CONTACT_TEXT.sub + "</sub><br>" + text + "</h2>";
+}
 function renderContactBlock(options = {}) {
   const manifest = resolveManifest(options);
   const lang = resolveLang(options);
   const groups = sortByOrder(manifest.groups);
-  const rows = groups.map((group) => `| ${pickText(group.readmeTitle, lang)} | ![${pickText(group.alt, lang)}](${group.card}) |`).join("\n");
+  if (groups.length === 0) throw new Error("contact block needs at least one group in the manifest");
+  const headerCells = groups.map((group) => '<td align="center"><b>' + escapeAttribute(pickText(group.readmeTitle, lang)) + "</b></td>").join("");
+  const cardCells = groups.map((group) => {
+    const src = contactCardUrl(group, manifest, options);
+    const alt = escapeAttribute(pickText(group.alt, lang));
+    return '<td><img src="' + src + '" width="' + CONTACT_CARD_WIDTH + '" alt="' + alt + '" /></td>';
+  }).join("");
   return [
-    BLOCK_MARKERS.contact.start,
-    "| \u7FA4 | \u4E8C\u7EF4\u7801 |",
-    "| --- | --- |",
-    rows,
-    BLOCK_MARKERS.contact.end
+    contactHeading(lang, options),
+    "",
+    '<div align="center">',
+    "",
+    CONTACT_TEXT.welcome[lang],
+    "",
+    '<table align="center"><tr>' + headerCells + "</tr><tr>" + cardCells + "</tr></table>",
+    "",
+    "</div>"
   ].join("\n");
 }
+
+// src/node/readme-sync.ts
+var THANKS_ZH_MARKERS = {
+  start: "<!-- THANKS-TABLE-ZH-START -->",
+  end: "<!-- THANKS-TABLE-ZH-END -->"
+};
+var THANKS_EN_MARKERS = {
+  start: "<!-- THANKS-TABLE-EN-START -->",
+  end: "<!-- THANKS-TABLE-EN-END -->"
+};
+var BLOCK_MARKERS = {
+  contact: { start: "<!-- CONTACT-START -->", end: "<!-- CONTACT-END -->" },
+  more: { start: "<!-- MORE-START -->", end: "<!-- MORE-END -->" },
+  starHistory: { start: "<!-- STAR-HISTORY-START -->", end: "<!-- STAR-HISTORY-END -->" },
+  thanks: {
+    ...THANKS_ZH_MARKERS,
+    zh: THANKS_ZH_MARKERS,
+    en: THANKS_EN_MARKERS
+  }
+};
+function detectContact(raw) {
+  const parsed = parseContactBlock(raw);
+  const heading = parsed.heading?.text ?? "";
+  const lang = /[A-Za-z]/.test(heading) ? "en" : "zh";
+  const variant = parsed.variant === "markdown-heading" ? "markdown-heading" : "html-heading";
+  return { lang, variant };
+}
+function locateLegacyContact(markdown) {
+  const headingPattern = /^(?:<h2\b[^\n]*?(?:CONNECT|反馈与联系|Feedback and Contact)[^\n]*?|<sub>\s*CONNECT\s*<\/sub>[^\n]*?|<h2\b[^\n]*?>[^\n]*?(?:反馈与联系|Feedback and Contact)[^\n]*?>|##\s+[^\n]*(?:反馈与联系|Feedback and Contact)[^\n]*)\s*$/im;
+  const heading = headingPattern.exec(markdown);
+  if (heading === null) return null;
+  const start = heading.index;
+  const closingDiv = /^[ \t]*<\/div>[ \t]*$/m;
+  const rest = markdown.slice(start + heading[0].length);
+  const closing = closingDiv.exec(rest);
+  if (closing === null) return null;
+  return { start, end: start + heading[0].length + closing.index + closing[0].length };
+}
+var BLOCK_DEFINITIONS = [
+  {
+    name: "contact",
+    label: "contact",
+    markers: [{ start: BLOCK_MARKERS.contact.start, end: BLOCK_MARKERS.contact.end }],
+    render: (context) => renderContactBlock(context),
+    locateLegacy: locateLegacyContact,
+    detect: detectContact
+  },
+  // Reserved for ticket 09: renderer + legacy anchor for the author-plugins
+  // (MORE) block. Marker pair is fixed now so init/sync never invents one.
+  {
+    name: "more",
+    label: "more",
+    markers: [{ start: BLOCK_MARKERS.more.start, end: BLOCK_MARKERS.more.end }]
+  },
+  // Reserved for ticket 10.
+  {
+    name: "star-history",
+    label: "star-history",
+    markers: [{ start: BLOCK_MARKERS.starHistory.start, end: BLOCK_MARKERS.starHistory.end }]
+  },
+  // Reserved for ticket 10. One marker pair per language; which pair exists
+  // tells the language of the README.
+  {
+    name: "thanks",
+    label: "thanks",
+    markers: [
+      { lang: "zh", start: THANKS_ZH_MARKERS.start, end: THANKS_ZH_MARKERS.end },
+      { lang: "en", start: THANKS_EN_MARKERS.start, end: THANKS_EN_MARKERS.end }
+    ]
+  }
+];
+function blockDefinition(name) {
+  return BLOCK_DEFINITIONS.find((definition) => definition.name === name);
+}
+function implementedBlockDefinitions() {
+  return BLOCK_DEFINITIONS.filter((definition) => definition.render !== void 0);
+}
+function writeFileAtomic(filePath, content, hooks = {}) {
+  const directory = dirname(filePath);
+  const tempPath = join(
+    directory,
+    "." + basename(filePath) + "." + process.pid + "." + randomBytes(6).toString("hex") + ".tmp"
+  );
+  let mode;
+  try {
+    mode = statSync(filePath).mode & 511;
+  } catch {
+    mode = void 0;
+  }
+  try {
+    writeFileSync(tempPath, content, "utf8");
+    if (mode !== void 0) chmodSync(tempPath, mode);
+    hooks.beforeRename?.(tempPath);
+    renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      if (existsSync(tempPath)) unlinkSync(tempPath);
+    } catch {
+    }
+    throw error;
+  }
+}
+function detectLineEnding(markdown) {
+  return markdown.includes("\r\n") ? "\r\n" : "\n";
+}
+function markerIndexes(markdown, token) {
+  const indexes = [];
+  let from = 0;
+  for (; ; ) {
+    const index = markdown.indexOf(token, from);
+    if (index === -1) return indexes;
+    indexes.push(index);
+    from = index + token.length;
+  }
+}
+function renderSegment(definition, markerSet, context) {
+  if (definition.render === void 0) throw new Error("block has no renderer: " + definition.name);
+  return definition.render({ ...context, lang: markerSet.lang ?? context.lang });
+}
+function applyMarkerSet(markdown, definition, markerSet, context, command) {
+  const errors = [];
+  const { start, end } = markerSet;
+  const starts = markerIndexes(markdown, start);
+  const ends = markerIndexes(markdown, end);
+  const eol = detectLineEnding(markdown);
+  if (starts.length === 0 && ends.length === 0) {
+    if (definition.render === void 0) {
+      return { markdown, changed: false, status: "skipped", errors };
+    }
+    if (command === "sync") {
+      errors.push(definition.label + " markers are missing; run readme:init first");
+      return { markdown, changed: false, status: "skipped", errors };
+    }
+    const legacy = definition.locateLegacy?.(markdown) ?? null;
+    if (legacy === null) {
+      errors.push(
+        "cannot locate the legacy " + definition.label + " block; add " + start + " / " + end + " markers manually"
+      );
+      return { markdown, changed: false, status: "skipped", errors };
+    }
+    const content = renderSegment(definition, markerSet, context).split(/\r?\n/).join(eol);
+    const replacement = start + eol + content + eol + end;
+    return {
+      markdown: markdown.slice(0, legacy.start) + replacement + markdown.slice(legacy.end),
+      changed: true,
+      status: "inserted",
+      errors
+    };
+  }
+  if (starts.length === 1 && ends.length === 1 && starts[0] < ends[0]) {
+    if (definition.render === void 0) {
+      return { markdown, changed: false, status: "skipped", errors };
+    }
+    const startIndex = starts[0];
+    const endIndex = ends[0];
+    const inner = markdown.slice(startIndex + start.length, endIndex);
+    const content = renderSegment(definition, markerSet, context).split(/\r?\n/).join(eol);
+    const expectedInner = eol + content + eol;
+    if (inner === expectedInner) {
+      return { markdown, changed: false, status: "unchanged", errors };
+    }
+    const next = markdown.slice(0, startIndex + start.length) + expectedInner + markdown.slice(endIndex);
+    return { markdown: next, changed: true, status: "updated", errors };
+  }
+  if (starts.length > 1 || ends.length > 1) {
+    errors.push(
+      "duplicate " + definition.label + " markers (" + start + " x" + starts.length + ", " + end + " x" + ends.length + "); refusing to guess"
+    );
+  } else if (starts.length !== ends.length) {
+    errors.push(
+      "unpaired " + definition.label + " markers (" + start + " x" + starts.length + ", " + end + " x" + ends.length + ")"
+    );
+  } else {
+    errors.push("end marker appears before start marker for the " + definition.label + " block");
+  }
+  return { markdown, changed: false, status: "skipped", errors };
+}
+function detectContext(markdown, options) {
+  let lang = options.lang;
+  let variant = options.variant;
+  for (const definition of BLOCK_DEFINITIONS) {
+    if (definition.detect === void 0) continue;
+    let raw = null;
+    for (const markerSet of definition.markers) {
+      const starts = markerIndexes(markdown, markerSet.start);
+      const ends = markerIndexes(markdown, markerSet.end);
+      if (starts.length === 1 && ends.length === 1 && starts[0] < ends[0]) {
+        raw = markdown.slice(starts[0] + markerSet.start.length, ends[0]);
+        break;
+      }
+    }
+    if (raw === null) {
+      const legacy = definition.locateLegacy?.(markdown) ?? null;
+      if (legacy !== null) raw = markdown.slice(legacy.start, legacy.end);
+    }
+    if (raw === null) continue;
+    const detected = definition.detect(raw);
+    lang ??= detected.lang;
+    variant ??= detected.variant;
+  }
+  return {
+    manifest: options.manifest,
+    version: options.version,
+    cdnBase: options.cdnBase,
+    lang: lang ?? "zh",
+    variant
+  };
+}
+function updateReadme(options) {
+  const readmePath = resolve(options.root, options.readme ?? "README.md");
+  const command = options.command ?? "sync";
+  const result = {
+    readmePath,
+    ok: false,
+    changed: false,
+    written: false,
+    blocks: [],
+    errors: []
+  };
+  let markdown;
+  try {
+    markdown = readFileSync(readmePath, "utf8");
+  } catch (error) {
+    const code = error.code;
+    result.errors.push(
+      code === "ENOENT" ? "README not found: " + readmePath : "cannot read " + readmePath + ": " + error.message
+    );
+    return result;
+  }
+  const suspicious = findSuspiciousLines(markdown);
+  if (suspicious.length > 0) {
+    for (const line of suspicious) {
+      result.errors.push(
+        readmePath + ":" + line.line + ": suspicious merge-conflict residue (" + line.reason + '): "' + line.text + '"; refusing to modify the README, fix it manually first'
+      );
+    }
+    return result;
+  }
+  const context = detectContext(markdown, options);
+  let next = markdown;
+  for (const definition of implementedBlockDefinitions()) {
+    for (const markerSet of definition.markers) {
+      const applied = applyMarkerSet(next, definition, markerSet, context, command);
+      next = applied.markdown;
+      result.blocks.push({ name: definition.name, status: applied.status });
+      for (const error of applied.errors) result.errors.push(readmePath + ": " + error);
+    }
+  }
+  if (result.errors.length > 0) return result;
+  result.changed = next !== markdown;
+  if (options.check === true) {
+    if (result.changed) {
+      result.errors.push(
+        readmePath + ": managed blocks are out of date; run readme:" + command + " to fix"
+      );
+      return result;
+    }
+    result.ok = true;
+    return result;
+  }
+  if (result.changed) {
+    writeFileAtomic(readmePath, next);
+    result.written = true;
+  }
+  result.ok = true;
+  return result;
+}
+function updateReadmes(options) {
+  const files = options.roots.map(
+    (root) => updateReadme({
+      root,
+      command: options.command ?? "sync",
+      check: options.check,
+      manifest: options.manifest,
+      version: options.version,
+      cdnBase: options.cdnBase,
+      lang: options.lang,
+      variant: options.variant
+    })
+  );
+  return { ok: files.every((file) => file.ok), files };
+}
+
+// src/node/index.ts
 function renderStarHistoryBlock(options = {}) {
   return [BLOCK_MARKERS.starHistory.start, "", BLOCK_MARKERS.starHistory.end].join("\n");
 }
@@ -837,12 +1187,20 @@ function sortedPlugins(manifest, selfId) {
   return sortByOrder(manifest.plugins).filter((plugin) => plugin.id !== selfId);
 }
 export {
+  BLOCK_DEFINITIONS,
   BLOCK_MARKERS,
+  CONTACT_CARD_WIDTH,
+  CONTACT_TEXT,
+  DEFAULT_CDN_BASE,
   assetName,
+  blockDefinition,
   canonicalizeMarkup,
   compareBlocks,
   compareReadmeBlocks,
+  contactCardCacheDate,
+  contactCardUrl,
   findSuspiciousLines,
+  implementedBlockDefinitions,
   locateReadmeBlocks,
   parseAttributes,
   parseContactBlock,
@@ -855,5 +1213,8 @@ export {
   renderStarHistoryBlock,
   renderThanksBlock,
   sortedPlugins,
-  verifyBlock
+  updateReadme,
+  updateReadmes,
+  verifyBlock,
+  writeFileAtomic
 };

package/dist/node/readme-sync.d.ts

@@ -0,0 +1,143 @@
+import type { Lang } from "../core/types";
+import type { BlockName, BlockRenderOptions, HeadingVariant, ReadmeSyncOptions } from "./types";
+/** One marker pair managed inside a README. */
+export interface BlockMarkerSet {
+    /** Language of the segment; unset = the block's default language. */
+    lang?: Lang;
+    start: string;
+    end: string;
+}
+/** Options handed to a block renderer; `lang` is always resolved. */
+export interface BlockRenderContext extends BlockRenderOptions {
+    lang: Lang;
+}
+/** Half-open character range of a legacy (pre-marker) block in a README. */
+export interface LegacyBlockSpan {
+    start: number;
+    end: number;
+}
+/**
+ * One managed README block.
+ *
+ * Ticket 09/10 only need to fill in `render` (and, when the block is new like
+ * the MORE block on ilife, `locateLegacy`) for the reserved entries.
+ */
+export interface BlockDefinition {
+    name: BlockName;
+    /** Human-readable name used in CLI diagnostics. */
+    label: string;
+    /** Marker pairs the engine owns. `thanks` has one pair per language. */
+    markers: readonly BlockMarkerSet[];
+    /**
+     * Render the content between the marker pair. A definition without a
+     * renderer is reserved: its markers are validated when present but never
+     * rewritten.
+     */
+    render?: (context: BlockRenderContext) => string;
+    /** Locate the pre-marker block extent in a README (used by `readme:init`). */
+    locateLegacy?: (markdown: string) => LegacyBlockSpan | null;
+    /** Recover the language and heading variant from a current block text. */
+    detect?: (raw: string) => {
+        lang?: Lang;
+        variant?: HeadingVariant;
+    };
+}
+export declare const BLOCK_MARKERS: {
+    readonly contact: {
+        readonly start: "<!-- CONTACT-START -->";
+        readonly end: "<!-- CONTACT-END -->";
+    };
+    readonly more: {
+        readonly start: "<!-- MORE-START -->";
+        readonly end: "<!-- MORE-END -->";
+    };
+    readonly starHistory: {
+        readonly start: "<!-- STAR-HISTORY-START -->";
+        readonly end: "<!-- STAR-HISTORY-END -->";
+    };
+    readonly thanks: {
+        readonly start: "<!-- THANKS-TABLE-ZH-START -->";
+        readonly end: "<!-- THANKS-TABLE-ZH-END -->";
+        readonly zh: {
+            readonly start: "<!-- THANKS-TABLE-ZH-START -->";
+            readonly end: "<!-- THANKS-TABLE-ZH-END -->";
+        };
+        readonly en: {
+            readonly start: "<!-- THANKS-TABLE-EN-START -->";
+            readonly end: "<!-- THANKS-TABLE-EN-END -->";
+        };
+    };
+};
+/**
+ * Registry of the managed README blocks.
+ *
+ * Order is documentation order, not README order: the engine locates every
+ * block by its markers, so block order inside a README never matters.
+ */
+export declare const BLOCK_DEFINITIONS: readonly BlockDefinition[];
+/** Look up one block definition by name. */
+export declare function blockDefinition(name: BlockName): BlockDefinition | undefined;
+/** Definitions that can be rendered today (reserved blocks are skipped). */
+export declare function implementedBlockDefinitions(): BlockDefinition[];
+/** Result of updating one README file. */
+export interface ReadmeFileResult {
+    /** Absolute path of the README. */
+    readmePath: string;
+    ok: boolean;
+    /** The README content must change (or would change when `check`). */
+    changed: boolean;
+    /** The engine actually wrote the file. */
+    written: boolean;
+    blocks: Array<{
+        name: BlockName;
+        status: "inserted" | "updated" | "unchanged" | "skipped";
+    }>;
+    errors: string[];
+}
+/** Options for one README target. */
+export interface ReadmeTargetOptions extends BlockRenderOptions {
+    /** Directory that contains the README (`--root`). */
+    root: string;
+    /** README path relative to `root`; default `README.md`. */
+    readme?: string;
+}
+/** Options for one `readme:init` / `readme:sync` file update. */
+export interface ReadmeUpdateOptions extends ReadmeTargetOptions {
+    /** `init` may insert missing markers; `sync` only rewrites marked text. */
+    command?: "init" | "sync";
+    /** Report drift without writing. */
+    check?: boolean;
+}
+/** Result of updating several README files. */
+export interface ReadmeBatchResult {
+    ok: boolean;
+    files: ReadmeFileResult[];
+}
+/** Hooks used by tests to observe the atomic-write window. */
+export interface AtomicWriteHooks {
+    /** Called after the temp file is complete but before the rename. */
+    beforeRename?: (tempPath: string) => void;
+}
+/**
+ * Write a file atomically: full content goes to a sibling temp file first, the
+ * original permissions are copied, and only then the temp file is renamed over
+ * the destination. A failure before the rename leaves the original untouched
+ * and removes the temp file.
+ */
+export declare function writeFileAtomic(filePath: string, content: string, hooks?: AtomicWriteHooks): void;
+/**
+ * Update one README.
+ *
+ * `init` seeds missing marker pairs at the legacy block position; `sync`
+ * only rewrites already-marked text. In both modes a README with suspicious
+ * merge-conflict residue or broken markers is left byte-identical.
+ */
+export declare function updateReadme(options: ReadmeUpdateOptions): ReadmeFileResult;
+/**
+ * Update every target root (CLI `--root`, repeatable).
+ *
+ * All targets are processed even when one fails, so a maintainer sees every
+ * problem in one run; `--all` (the CLI flag) merely mirrors that policy for
+ * the multi-repository workflow.
+ */
+export declare function updateReadmes(options: ReadmeSyncOptions): ReadmeBatchResult;