dsh-featherhunter-plugin-base 0.0.0-stage → 0.0.2-drill

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

@@ -0,0 +1,199 @@
+/**
+ * README block extraction and normalized comparison.
+ *
+ * The five plugin repositories hand-write four README blocks (contact, star
+ * history, thanks, author plugins) in slightly different shapes. This module
+ * (a) locates those blocks in a README text, (b) parses each shape leniently
+ * into a comparable structure, and (c) compares two blocks by *content*
+ * (members / links / texts / widths / thanks table data), reporting pure
+ * formatting differences separately.
+ *
+ * It is deliberately dependency-free (no node: imports) so both the ./node
+ * entry and the fixture extraction script can use it.
+ */
+/** Kind of a managed README block. */
+export type ReadmeBlockKind = "contact" | "star-history" | "thanks" | "more";
+/** A line that looks like merge-conflict residue; writers must stop. */
+export interface SuspiciousLine {
+    /** 1-based line number. */
+    line: number;
+    /** The offending line, verbatim. */
+    text: string;
+    reason: "conflict-start" | "conflict-separator" | "conflict-end" | "merge-conflict-residue";
+}
+/** Raw block slices located in a README text. */
+export interface LocatedBlocks {
+    /** Raw block text per kind; null when the block is absent. */
+    blocks: Record<ReadmeBlockKind, string | null>;
+    /** Block kinds in the order they appear in the file. */
+    order: ReadmeBlockKind[];
+    /** Merge-conflict residue / suspicious lines found anywhere in the file. */
+    suspicious: SuspiciousLine[];
+}
+/**
+ * Locate the four managed blocks in a README text.
+ *
+ * Boundaries are the next managed-block start (or EOF), trimmed of blank lines
+ * and trailing `---` rules. Block order is recorded but never assumed: the
+ * five repos currently order the blocks differently.
+ */
+export declare function locateReadmeBlocks(markdown: string): LocatedBlocks;
+/** Find merge-conflict residue. Writers must stop and hand the file to a human. */
+export declare function findSuspiciousLines(markdown: string): SuspiciousLine[];
+/** Parse an HTML attribute string into a lower-cased attribute map. */
+export declare function parseAttributes(attributeText: string): Record<string, string>;
+/** File name of an image src, dropping directory prefix, query and hash. */
+export declare function assetName(src: string): string;
+/** Parsed block heading; `sub` is the small label (CONNECT / THANKS / MORE). */
+export interface ParsedHeading {
+    sub: string | null;
+    text: string;
+}
+/** Parse the heading of a managed block in either HTML or Markdown form. */
+export declare function parseHeading(raw: string): ParsedHeading | null;
+/** One group (chat group QR code) inside the contact block. */
+export interface ContactGroup {
+    /** Table header text, e.g. 飞书群（主）. */
+    title: string;
+    /** Image src exactly as written (relative or absolute). */
+    src: string;
+    /** Image file name; stable across relative prefixes and CDN URLs. */
+    asset: string;
+    /** Rendered image width, if any. */
+    width: number | null;
+    alt: string;
+}
+/** Parsed contact block. */
+export interface ParsedContactBlock {
+    variant: "html-heading" | "markdown-heading";
+    heading: ParsedHeading | null;
+    welcome: string | null;
+    groups: ContactGroup[];
+}
+/** Parse the contact block in either heading variant. */
+export declare function parseContactBlock(raw: string): ParsedContactBlock;
+/** A dark/light `<source>` inside a `<picture>`. */
+export interface StarSource {
+    /** "dark" / "light" when declared, otherwise null. */
+    media: string | null;
+    src: string;
+    /** Image file name, stable across CDN URLs and cache busters. */
+    asset: string;
+}
+/** The visible star history image. */
+export interface StarImage {
+    alt: string;
+    src: string;
+    asset: string;
+    width: number | null;
+}
+/** Parsed star history block. */
+export interface ParsedStarHistoryBlock {
+    variant: "picture-link" | "picture" | "markdown-image" | "unknown";
+    /** Click-through link around the picture, e.g. deck's star-history.html. */
+    link: string | null;
+    sources: StarSource[];
+    image: StarImage | null;
+    /** Caption below the image (im keeps a two-axis explanation). */
+    caption: string | null;
+}
+/** Parse the star history block in any of its four current shapes. */
+export declare function parseStarHistoryBlock(raw: string): ParsedStarHistoryBlock;
+/** One table cell of the thanks table. */
+export interface ThanksCell {
+    /** Visible text (links reduced to their label). */
+    text: string;
+    /** Link targets found in the cell, in order. */
+    links: string[];
+}
+/** One row of the thanks table. */
+export interface ThanksRow {
+    cells: ThanksCell[];
+}
+/** Parsed thanks block. */
+export interface ParsedThanksBlock {
+    variant: "html-heading" | "markdown-heading";
+    heading: ParsedHeading | null;
+    /** Language of the table markers (THANKS-TABLE-ZH / -EN). */
+    lang: "zh" | "en" | null;
+    headers: string[];
+    rows: ThanksRow[];
+    /** Non-table prose around the table, kept for fixtures but not compared. */
+    prose: string | null;
+}
+/** Parse the thanks block, including the empty-table case used by ilife. */
+export declare function parseThanksBlock(raw: string): ParsedThanksBlock;
+/** One plugin row in the "more from the author" block. */
+export interface MoreItem {
+    name: string;
+    url: string;
+    description: string;
+}
+/** Parsed "more from the author" block. */
+export interface ParsedMoreBlock {
+    variant: "html-heading" | "markdown-heading";
+    heading: ParsedHeading | null;
+    intro: string | null;
+    items: MoreItem[];
+    footer: string | null;
+}
+/** Parse the "more from the author" block. Rows are returned in file order. */
+export declare function parseMoreBlock(raw: string): ParsedMoreBlock;
+/** Formatting-only differences; they never make a block content-different. */
+export type FormatStage = "line-endings" | "whitespace" | "quotes" | "attribute-order" | "self-closing";
+/** A formatting difference kind (`markup` = structural markup beyond the stages). */
+export type FormatDifferenceKind = FormatStage | "heading-variant" | "markup";
+/** One detected pure-format difference. */
+export interface FormatDifference {
+    kind: FormatDifferenceKind;
+    /** Set when the difference was found at README level. */
+    block?: ReadmeBlockKind;
+}
+/** Content difference dimensions required by the equivalence criterion. */
+export type DifferenceDimension = "presence" | "members" | "links" | "text" | "width" | "table" | "image";
+/** One content difference, addressed by a structural path. */
+export interface Difference {
+    dimension: DifferenceDimension;
+    path: string;
+    expected: unknown;
+    actual: unknown;
+}
+/** Comparison options. */
+export interface CompareOptions {
+    /**
+     * How image sources are compared. `basename` (default) ignores relative/CDN
+     * prefixes and `?v=` cache busters; `exact` compares the raw src.
+     */
+    imageSrc?: "basename" | "exact";
+}
+/** Result of comparing one managed block. */
+export interface BlockComparison {
+    kind: ReadmeBlockKind;
+    /** Raw text is byte-identical. */
+    identical: boolean;
+    /** Content is equivalent under the F18 criterion. */
+    equivalent: boolean;
+    contentDifferences: Difference[];
+    /** Only populated when content is equivalent but raw text differs. */
+    formatDifferences: FormatDifference[];
+}
+/** Result of comparing two READMEs. */
+export interface ReadmeComparison {
+    equivalent: boolean;
+    blocks: Record<ReadmeBlockKind, BlockComparison>;
+    contentDifferences: Difference[];
+    formatDifferences: FormatDifference[];
+    order: {
+        expected: ReadmeBlockKind[];
+        actual: ReadmeBlockKind[];
+        same: boolean;
+    };
+    /** Merge-conflict residue from the actual README: callers must stop. */
+    suspicious: SuspiciousLine[];
+}
+/** Canonical form that erases whitespace, quote, attribute-order and self-close style. */
+export declare function canonicalizeMarkup(markup: string): string;
+/** Compare one managed block; null means the block is absent. */
+export declare function compareBlocks(kind: ReadmeBlockKind, expectedRaw: string | null, actualRaw: string | null, options?: CompareOptions): BlockComparison;
+/** Compare two READMEs (raw text or already-located blocks) block by block. */
+export declare function compareReadmeBlocks(expected: string | LocatedBlocks, actual: string | LocatedBlocks, options?: CompareOptions): ReadmeComparison;

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;

package/dist/node/renderers.d.ts

@@ -0,0 +1,48 @@
+import type { Group, Manifest } from "../core/types";
+import type { BlockRenderOptions } from "./types";
+/** jsDelivr base of the published data package (exact-version images). */
+export declare const DEFAULT_CDN_BASE = "https://cdn.jsdelivr.net/npm/dsh-featherhunter-plugin-base";
+/** Whole-card image width used by the README contact table (spec rule 9). */
+export declare const CONTACT_CARD_WIDTH = 260;
+/** Fixed wording of the contact block, independent of the group data. */
+export declare const CONTACT_TEXT: {
+    readonly sub: "CONNECT";
+    readonly heading: {
+        readonly zh: "反馈与联系";
+        readonly en: "Feedback and Contact";
+    };
+    readonly welcome: {
+        readonly zh: "👏欢迎提交PR、ISSUE。星星之火可以燎原🔥有任何建议、意见、想法、吐槽、idea都可以进群交流。";
+        readonly en: "👏Welcome PRs and issues. A single spark can start a prairie fire 🔥. Any suggestion, opinion, idea or rant — come join the group and talk.";
+    };
+};
+/**
+ * Cache-busting date for a limited-time card (`YYYYMMDD`), or null for a
+ * permanent card.
+ *
+ * A card counts as limited-time when the manifest marks it with `validUntil`
+ * or the published file name carries a `YYYY-MM-DD` date. The date in the
+ * file name wins; otherwise the manifest `updatedAt` date is used, because
+ * GitHub's camo proxy caches images by URL and a new QR code must get a new
+ * URL.
+ */
+export declare function contactCardCacheDate(group: Group, manifest: Manifest): string | null;
+/**
+ * Absolute pristine CDN URL of one published card image.
+ *
+ * Shape: `<cdnBase>@<manifest.version>/data/img/<card>[?v=YYYYMMDD]`. The
+ * base must be an absolute https URL — README images are never relative or
+ * copied into the plugin repositories.
+ */
+export declare function contactCardUrl(group: Group, manifest: Manifest, options?: BlockRenderOptions): string;
+/**
+ * Render the README contact block content (no markers).
+ *
+ * Keeps the pre-migration structure: heading, centered wrapper, welcome line,
+ * one header row and one row of {@link CONTACT_CARD_WIDTH}-wide whole cards.
+ * Modal-only fields (`title`, `subtitle`, `note`, `qr`) never appear here.
+ *
+ * @param options data + language + image base; `variant` selects the standard
+ *   CONNECT h2 (default) or ilife's Markdown `##` heading.
+ */
+export declare function renderContactBlock(options?: BlockRenderOptions): string;

package/dist/node/types.d.ts

@@ -0,0 +1,56 @@
+import type { Lang, Manifest } from "../core/types";
+/**
+ * Heading form of a rendered block. Most repositories use an HTML <h2>
+ * heading; ilife (and the prompt MORE block) use a Markdown `##` heading.
+ */
+export type HeadingVariant = "html-heading" | "markdown-heading";
+/** Shared options for the README block renderers. */
+export interface BlockRenderOptions {
+    /** Manifest to render from; defaults to the packaged baseline manifest. */
+    manifest?: Manifest;
+    /** Published package version, used for precise CDN URLs. */
+    version?: string;
+    /** Target language of the generated block. */
+    lang?: Lang;
+    /** CDN base URL override (tests / mirrors). */
+    cdnBase?: string;
+    /** Heading form override; renderers default to their repository convention. */
+    variant?: HeadingVariant;
+}
+/** Marker names of the four managed README blocks. */
+export type BlockName = "contact" | "star-history" | "thanks" | "more";
+export interface VerifyResult {
+    ok: boolean;
+    errors: string[];
+}
+/** Options for the README writer (ticket 08). */
+export interface ReadmeSyncOptions {
+    /** Repository roots to update. */
+    roots: string[];
+    /** `init` may insert missing marker pairs; `sync` only rewrites marked text. */
+    command?: "init" | "sync";
+    /** Report drift without writing. */
+    check?: boolean;
+    /** Process every target root and keep going after per-file errors. */
+    all?: boolean;
+    dryRun?: boolean;
+    /** Manifest to render from; defaults to the packaged baseline manifest. */
+    manifest?: Manifest;
+    /** Published package version, used for precise CDN URLs. */
+    version?: string;
+    /** CDN base URL override (tests / mirrors). */
+    cdnBase?: string;
+    /** Target language override; detected from the README when omitted. */
+    lang?: Lang;
+    /** Heading form override; detected from the README when omitted. */
+    variant?: HeadingVariant;
+}
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "dsh-featherhunter-plugin-base",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2-drill",
+  "description": "FeatherHunter DSH plugin shared base: settings-panel contact modal / author plugins card widgets and README block renderers",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "readme",
+    "contact"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "default": "./dist/node/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-base": "dist/node/cli.js"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:demo": "node build.mjs --demo",
+    "build:data": "node scripts/run-ts.mjs build-data",
+    "data:check": "node scripts/run-ts.mjs build-data --check",
+    "contact:update": "node scripts/run-ts.mjs contact-update",
+    "readme:init": "node dist/node/cli.js readme:init",
+    "readme:sync": "node dist/node/cli.js readme:sync",
+    "readme:check": "node dist/node/cli.js readme:sync --check",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:network": "node scripts/cdn-smoke.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "esbuild": "^0.28.2",
+    "jpeg-js": "^0.4.4",
+    "jsdom": "^30.1.3",
+    "pngjs": "^7.0.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}