aeoptimize 0.5.3 → 0.6.1

package/fixtures/v0.6/rule-corpus.ts

@@ -0,0 +1,326 @@
+export type RuleFixtureKind = 'positive' | 'negative' | 'boundary';
+
+export interface FixtureDocument {
+  url: string;
+  title: string;
+  html: string;
+  markdown: string;
+  headings: Array<{ level: number; text: string }>;
+  paragraphs: string[];
+  jsonLd: Array<{ '@type'?: string; '@context'?: string; [key: string]: unknown }>;
+  metaTags: Record<string, string>;
+  links: Array<{ href: string; text: string; rel?: string }>;
+  rawText: string;
+}
+
+export interface RuleFixtureCase {
+  purpose: string;
+  document: Partial<FixtureDocument>;
+  expected: {
+    score: number;
+    issues: number;
+    suggestions: number;
+  };
+}
+
+export interface RuleFixtureSet {
+  positive: RuleFixtureCase;
+  negative: RuleFixtureCase;
+  boundary: RuleFixtureCase;
+}
+
+const words = (count: number, prefix = 'word') =>
+  Array.from({ length: count }, (_, index) => `${prefix}${index}`).join(' ');
+
+const repeatedWords = (count: number, word = 'word') =>
+  Array.from({ length: count }, () => word).join(' ');
+
+const stuffedText = (
+  'Buy cheap widgets now. Cheap widgets are the best widgets. ' +
+  'Our widgets are cheap widgets for sale. Get cheap widgets today. ' +
+  'Cheap widgets online cheap widgets store cheap widgets deals. ' +
+  'Best cheap widgets cheap widgets review cheap widgets comparison. ' +
+  'Order cheap widgets cheap widgets shipping cheap widgets discount. '
+).repeat(3);
+
+export const ruleFixtureCorpusVersion = '0.6.0';
+
+export const ruleFixtureCorpus: Record<string, RuleFixtureSet> = {
+  'heading-hierarchy': {
+    positive: {
+      purpose: 'A descriptive H1 followed by nested sections receives the full structure score.',
+      document: {
+        headings: [
+          { level: 1, text: 'Release guide' },
+          { level: 2, text: 'Verification' },
+          { level: 3, text: 'CLI checks' },
+        ],
+        rawText: 'A short release guide with a clear outline.',
+      },
+      expected: { score: 10, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A document with no headings triggers the deterministic missing-outline finding.',
+      document: { headings: [], rawText: 'Unstructured content.' },
+      expected: { score: 0, issues: 1, suggestions: 0 },
+    },
+    boundary: {
+      purpose: 'Multiple H1 elements are not treated as an automatic error when the outline does not skip levels.',
+      document: {
+        headings: [
+          { level: 1, text: 'Primary title' },
+          { level: 1, text: 'Secondary region title' },
+          { level: 2, text: 'Details' },
+        ],
+        rawText: 'Readable content.',
+      },
+      expected: { score: 10, issues: 0, suggestions: 0 },
+    },
+  },
+  'paragraph-length': {
+    positive: {
+      purpose: 'Short focused paragraphs remain below the configured readability heuristic.',
+      document: { paragraphs: ['A concise paragraph.', 'Another concise paragraph.'] },
+      expected: { score: 8, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A majority of paragraphs above 150 words triggers the configured long-paragraph finding.',
+      document: { paragraphs: [repeatedWords(151), repeatedWords(151), 'A short paragraph.'] },
+      expected: { score: 3, issues: 1, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Exactly 150 words is the non-penalized threshold boundary.',
+      document: { paragraphs: [repeatedWords(150)] },
+      expected: { score: 8, issues: 0, suggestions: 0 },
+    },
+  },
+  'list-usage': {
+    positive: {
+      purpose: 'Long content containing a genuine list receives the full scannability score.',
+      document: { html: `<ul><li>First</li><li>Second</li></ul>${words(301)}`, rawText: words(301) },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Long content with no list receives a low-impact review suggestion.',
+      document: { html: `<p>${words(301)}</p>`, rawText: words(301) },
+      expected: { score: 4, issues: 0, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Content at exactly 300 words is not forced into a list merely to satisfy the heuristic.',
+      document: { html: `<p>${words(300)}</p>`, rawText: words(300) },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+  },
+  'self-contained-statements': {
+    positive: {
+      purpose: 'Paragraphs that name their subject remain independently understandable.',
+      document: {
+        paragraphs: [
+          'Aeoptimize reports deterministic content-readiness findings.',
+          'The GitHub Action is advisory by default.',
+          'Project owners choose whether a threshold should block CI.',
+        ],
+      },
+      expected: { score: 8, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A majority of dangling pronoun or transition openings triggers a review finding.',
+      document: {
+        paragraphs: [
+          'This is important for the release.',
+          'They require additional context.',
+          'However, it varies by project.',
+          'The release is versioned for users.',
+          'The report is publicly available.',
+        ],
+      },
+      expected: { score: 3, issues: 1, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Exactly twenty percent dangling openings is the non-penalized ratio boundary.',
+      document: {
+        paragraphs: [
+          'This needs context for the reader.',
+          'The package is explicitly versioned.',
+          'The Action is advisory by default.',
+          'The report remains stable for automation.',
+          'The fixture is publicly reviewable.',
+        ],
+      },
+      expected: { score: 8, issues: 0, suggestions: 1 },
+    },
+  },
+  'data-stats-presence': {
+    positive: {
+      purpose: 'A quantitative claim with explicit source language is not flagged as unsourced.',
+      document: { rawText: 'According to the linked release report, 20 users completed the test.' },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A quantitative claim without a detectable source receives an evidence warning.',
+      document: { rawText: 'The package serves 20 users.' },
+      expected: { score: 3, issues: 1, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Content without quantitative claims is not penalized or encouraged to invent numbers.',
+      document: { rawText: 'The package exposes a deterministic local lint.' },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+  },
+  'clear-definitions': {
+    positive: {
+      purpose: 'Several explicit definitions receive the full clarity score.',
+      document: { rawText: 'A lint is a repeatable check. A fixture means a controlled input. A release refers to a published version.' },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Content without definitions receives a clarity suggestion.',
+      document: { rawText: 'Install the package and run the command.' },
+      expected: { score: 1, issues: 0, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'A semantic definition list is accepted without requiring a prose pattern.',
+      document: { html: '<dl><dt>Fixture</dt><dd>A controlled input.</dd></dl>', rawText: 'Fixture: a controlled input.' },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+  },
+  attribution: {
+    positive: {
+      purpose: 'Accurate author, date, and source language receive the full attribution score.',
+      document: {
+        metaTags: { author: 'Fixture Author', date: '2026-08-22' },
+        rawText: 'According to the release evidence, the focused checks passed.',
+      },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Authored or time-sensitive content with no attribution signals receives a suggestion.',
+      document: { metaTags: {}, rawText: 'A time-sensitive release note.' },
+      expected: { score: 0, issues: 0, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Author plus source language reaches the no-suggestion threshold without inventing a date.',
+      document: { metaTags: { author: 'Fixture Author' }, rawText: 'Source: local release verification.' },
+      expected: { score: 3, issues: 0, suggestions: 0 },
+    },
+  },
+  'json-ld-presence': {
+    positive: {
+      purpose: 'Present JSON-LD is detected without awarding extra points for schema count.',
+      document: { jsonLd: [{ '@context': 'https://schema.org', '@type': 'SoftwareApplication' }] },
+      expected: { score: 8, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Missing JSON-LD produces an informational finding but no score penalty because schema is optional.',
+      document: { jsonLd: [] },
+      expected: { score: 8, issues: 1, suggestions: 0 },
+    },
+    boundary: {
+      purpose: 'Presence and completeness are separate rules, preventing a duplicate penalty in the presence rule.',
+      document: { jsonLd: [{}] },
+      expected: { score: 8, issues: 0, suggestions: 0 },
+    },
+  },
+  'json-ld-completeness': {
+    positive: {
+      purpose: 'JSON-LD with context and type receives the full completeness score.',
+      document: { jsonLd: [{ '@context': 'https://schema.org', '@type': 'SoftwareApplication' }] },
+      expected: { score: 12, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A JSON-LD object missing both required fields receives the deterministic completeness warning.',
+      document: { jsonLd: [{}] },
+      expected: { score: 0, issues: 1, suggestions: 0 },
+    },
+    boundary: {
+      purpose: 'No structured data receives no completeness penalty because optional absence belongs to the presence rule.',
+      document: { jsonLd: [] },
+      expected: { score: 12, issues: 0, suggestions: 0 },
+    },
+  },
+  'robots-txt-ai-config': {
+    positive: {
+      purpose: 'An indexable page receives the full page-level crawler score.',
+      document: { metaTags: { robots: 'index,follow' } },
+      expected: { score: 8, issues: 0, suggestions: 1 },
+    },
+    negative: {
+      purpose: 'A noindex directive triggers the deterministic critical finding.',
+      document: { metaTags: { robots: 'noindex,nofollow' } },
+      expected: { score: 0, issues: 1, suggestions: 0 },
+    },
+    boundary: {
+      purpose: 'A nofollow-only directive is not confused with noindex; site-level crawler access remains a separate check.',
+      document: { metaTags: { robots: 'nofollow,noarchive' } },
+      expected: { score: 8, issues: 0, suggestions: 1 },
+    },
+  },
+  'meta-description-quality': {
+    positive: {
+      purpose: 'A page-specific readable summary receives the full metadata score.',
+      document: { metaTags: { description: 'A deterministic release guide covering package, Action, and rollback verification.' } },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'A missing description receives a warning without claiming a ranking outcome.',
+      document: { metaTags: {} },
+      expected: { score: 0, issues: 1, suggestions: 0 },
+    },
+    boundary: {
+      purpose: 'A long but page-specific description is not penalized by a fabricated fixed-length limit.',
+      document: { metaTags: { description: `A page-specific release explanation ${repeatedWords(180, 'context')}.` } },
+      expected: { score: 7, issues: 0, suggestions: 0 },
+    },
+  },
+  'content-boilerplate-ratio': {
+    positive: {
+      purpose: 'Paragraph content at sixty percent of extracted text receives the full heuristic score.',
+      document: { paragraphs: [words(60, 'content')], rawText: `${words(60, 'content')} ${words(40, 'navigation')}` },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Very little paragraph content relative to total text receives a review suggestion.',
+      document: { paragraphs: [words(20, 'content')], rawText: `${words(20, 'content')} ${words(80, 'navigation')}` },
+      expected: { score: 1, issues: 0, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'Exactly forty percent paragraph content stays at the documented middle threshold instead of the low band.',
+      document: { paragraphs: [words(40, 'content')], rawText: `${words(40, 'content')} ${words(60, 'navigation')}` },
+      expected: { score: 3, issues: 0, suggestions: 0 },
+    },
+  },
+  'keyword-stuffing-detection': {
+    positive: {
+      purpose: 'Long content with diverse vocabulary receives the full repetition score.',
+      document: { rawText: words(80, 'term') },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Low-diversity language repeated across sentences triggers the stuffing heuristic.',
+      document: { rawText: stuffedText },
+      expected: { score: 0, issues: 1, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'A short sample below fifty words is not classified from insufficient repetition evidence.',
+      document: { rawText: repeatedWords(49, 'widget') },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+  },
+  'content-uniqueness-signals': {
+    positive: {
+      purpose: 'A verifiable original measurement plus a code example receives the full heuristic score.',
+      document: { rawText: 'Our research measured the documented fixture under controlled inputs.', html: '<pre><code>npm run check</code></pre>' },
+      expected: { score: 5, issues: 0, suggestions: 0 },
+    },
+    negative: {
+      purpose: 'Generic prose with no original evidence or example remains at the base score.',
+      document: { rawText: 'The package checks content.', html: '<p>The package checks content.</p>' },
+      expected: { score: 2, issues: 0, suggestions: 1 },
+    },
+    boundary: {
+      purpose: 'A code sample alone adds one point but cannot masquerade as original research.',
+      document: { rawText: 'Run the documented command.', html: '<pre><code>aeoptimize --version</code></pre>' },
+      expected: { score: 3, issues: 0, suggestions: 1 },
+    },
+  },
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "aeoptimize",
-  "version": "0.5.3",
-  "description": "CLI toolkit that transforms SEO-optimized websites into AI-search-ready content",
+  "version": "0.6.1",
+  "description": "Deterministic content-readiness lint for static websites and documentation",
   "type": "module",
   "main": "./dist/core/index.js",
   "bin": {
-    "aeoptimize": "./dist/cli/index.js",
-    "aeo": "./dist/cli/index.js",
-    "aeo-cli": "./dist/cli/index.js"
+    "aeoptimize": "dist/cli/index.js",
+    "aeo": "dist/cli/index.js",
+    "aeo-cli": "dist/cli/index.js"
   },
   "exports": {
     ".": "./dist/core/index.js",
@@ -18,16 +18,28 @@
     "dist/",
     "skills/",
     "agents/",
+    "fixtures/",
+    "examples/github-action-sample/",
+    "scripts/verify-release-candidate.sh",
+    "scripts/verify-release-v0.6.sh",
     ".claude-plugin/",
+    "docs/methodology.md",
+    "docs/release-v0.6.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "ROADMAP.md",
+    "SECURITY.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
+    "check": "npm test && npm run build",
+    "release:check": "bash scripts/verify-release-candidate.sh",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm test && npm run build"
+    "prepublishOnly": "npm run release:check"
   },
   "keywords": [
     "aeo",
@@ -41,25 +53,28 @@
     "vite-plugin",
     "nextjs-plugin"
   ],
-  "homepage": "https://github.com/dexuwang627-cloud/aeoptimize",
+  "homepage": "https://github.com/cucuwang/aeoptimize",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dexuwang627-cloud/aeoptimize.git"
+    "url": "git+https://github.com/cucuwang/aeoptimize.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cucuwang/aeoptimize/issues"
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "dependencies": {
     "chalk": "^5.3.0",
-    "puppeteer-core": "^24.0.0",
-    "cheerio": "^1.0.0",
+    "puppeteer-core": "^25.7.0",
+    "cheerio": "^1.2.0",
     "commander": "^12.0.0",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^24.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.10"
   }
 }

package/scripts/verify-release-candidate.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd)
+cd "$REPO_ROOT"
+
+for command_name in git jq mktemp node npm; do
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    echo "missing required command: $command_name" >&2
+    exit 2
+  fi
+done
+
+if [ "${ALLOW_DIRTY_RELEASE_CHECK:-0}" != "1" ] && [ -n "$(git status --porcelain)" ]; then
+  echo "release candidate must be built from a clean worktree" >&2
+  exit 1
+fi
+
+VERIFY_BASE=${TMPDIR:-/tmp}
+VERIFY_BASE=${VERIFY_BASE%/}
+VERIFY_ROOT=$(mktemp -d "$VERIFY_BASE/aeoptimize-release-candidate.XXXXXX")
+PACK_ROOT="$VERIFY_ROOT/pack"
+CONSUMER_ROOT="$VERIFY_ROOT/consumer"
+PACK_JSON="$VERIFY_ROOT/pack.json"
+
+cleanup() {
+  case "$VERIFY_ROOT" in
+    "$VERIFY_BASE"/aeoptimize-release-candidate.*)
+      rm -rf -- "$VERIFY_ROOT"
+      ;;
+    *)
+      echo "Refusing to remove unexpected verification path: $VERIFY_ROOT" >&2
+      ;;
+  esac
+}
+
+trap cleanup EXIT
+mkdir -p "$PACK_ROOT"
+
+npm run check
+bash action/test-contract.sh
+npm --cache "$VERIFY_ROOT/npm-cache" audit --audit-level=high
+npm_config_dry_run=false npm --cache "$VERIFY_ROOT/npm-cache" \
+  pack --json --pack-destination "$PACK_ROOT" > "$PACK_JSON"
+
+PACKAGE_FILENAME=$(jq -er '.[0].filename' "$PACK_JSON")
+PACKAGE_VERSION=$(jq -er '.[0].version' "$PACK_JSON")
+PACKAGE_FILE_COUNT=$(jq -er '.[0].files | length' "$PACK_JSON")
+PACKAGE_UNPACKED_SIZE=$(jq -er '.[0].unpackedSize' "$PACK_JSON")
+PACKAGE_TARBALL="$PACK_ROOT/$PACKAGE_FILENAME"
+PACKAGE_SHA256=$(node -e "const crypto=require('node:crypto');const fs=require('node:fs');console.log(crypto.createHash('sha256').update(fs.readFileSync(process.argv[1])).digest('hex'))" "$PACKAGE_TARBALL")
+
+jq -e '
+  (.[0].files | map(.path) | index("dist/cli/index.js")) != null and
+  (.[0].files | map(.path) | index("fixtures/v0.6/rule-corpus.ts")) != null and
+  (.[0].files | map(.path) | index("examples/github-action-sample/.github/workflows/aeoptimize.yml")) != null and
+  (.[0].files | map(.path) | index("scripts/verify-release-candidate.sh")) != null and
+  (.[0].files | map(.path) | index("scripts/verify-release-v0.6.sh")) != null
+' "$PACK_JSON" >/dev/null
+
+npm_config_dry_run=false npm --cache "$VERIFY_ROOT/npm-cache" install \
+  --ignore-scripts --no-audit --no-fund \
+  --prefix "$CONSUMER_ROOT" "$PACKAGE_TARBALL" >/dev/null
+
+for binary in aeoptimize aeo aeo-cli; do
+  BINARY_VERSION=$("$CONSUMER_ROOT/node_modules/.bin/$binary" --version)
+  if [ "$BINARY_VERSION" != "$PACKAGE_VERSION" ]; then
+    echo "$binary returned $BINARY_VERSION; expected $PACKAGE_VERSION" >&2
+    exit 1
+  fi
+done
+
+MANIFEST=$(jq -n \
+  --arg version "$PACKAGE_VERSION" \
+  --arg filename "$PACKAGE_FILENAME" \
+  --arg sha256 "$PACKAGE_SHA256" \
+  --argjson fileCount "$PACKAGE_FILE_COUNT" \
+  --argjson unpackedSize "$PACKAGE_UNPACKED_SIZE" \
+  '{version: $version, filename: $filename, sha256: $sha256, fileCount: $fileCount, unpackedSize: $unpackedSize}')
+
+if [ -n "${RELEASE_MANIFEST_OUT:-}" ]; then
+  printf '%s\n' "$MANIFEST" > "$RELEASE_MANIFEST_OUT"
+fi
+
+printf '%s\n' "$MANIFEST"
+echo "Release candidate checks passed."

package/scripts/verify-release-v0.6.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+set -u
+
+PACKAGE_NAME=aeoptimize
+REPOSITORY=cucuwang/aeoptimize
+EXPECTED_COMMIT=${1:-}
+EXPECTED_PACKAGE_SHA256=${2:-}
+EXPECTED_REPOSITORY_URL=git+https://github.com/cucuwang/aeoptimize.git
+EXPECTED_HOMEPAGE=https://github.com/cucuwang/aeoptimize
+EXPECTED_BUGS_URL=https://github.com/cucuwang/aeoptimize/issues
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+PACKAGE_JSON="$SCRIPT_DIR/../package.json"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "missing required command: node" >&2
+  exit 2
+fi
+
+EXPECTED_VERSION=$(node -e "const fs=require('node:fs');const packageJson=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(packageJson.version)" "$PACKAGE_JSON")
+EXPECTED_TAG="v$EXPECTED_VERSION"
+
+if [ -z "$EXPECTED_COMMIT" ] || [ -z "$EXPECTED_PACKAGE_SHA256" ]; then
+  echo "usage: $0 <expected-release-commit> <expected-package-sha256>" >&2
+  exit 2
+fi
+
+if ! [[ "$EXPECTED_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "expected-release-commit must be a lowercase 40-character Git SHA" >&2
+  exit 2
+fi
+
+if ! [[ "$EXPECTED_PACKAGE_SHA256" =~ ^[0-9a-f]{64}$ ]]; then
+  echo "expected-package-sha256 must be a lowercase 64-character SHA-256" >&2
+  exit 2
+fi
+
+for command_name in awk curl jq npm git mktemp; do
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    echo "missing required command: $command_name" >&2
+    exit 2
+  fi
+done
+
+VERIFY_BASE=${TMPDIR:-/tmp}
+VERIFY_BASE=${VERIFY_BASE%/}
+VERIFY_ROOT=$(mktemp -d "$VERIFY_BASE/aeoptimize-release-verify.XXXXXX")
+REGISTRY_JSON="$VERIFY_ROOT/registry.json"
+RELEASE_JSON="$VERIFY_ROOT/release.json"
+PACKAGE_TARBALL="$VERIFY_ROOT/$PACKAGE_NAME-$EXPECTED_VERSION.tgz"
+CONSUMER_ROOT="$VERIFY_ROOT/consumer"
+FAILURES=0
+
+cleanup() {
+  if [ "${KEEP_VERIFY_ROOT:-0}" = "1" ]; then
+    echo "Verification workspace preserved: $VERIFY_ROOT"
+    return
+  fi
+
+  case "$VERIFY_ROOT" in
+    "$VERIFY_BASE"/aeoptimize-release-verify.*)
+      rm -rf -- "$VERIFY_ROOT"
+      ;;
+    *)
+      echo "Refusing to remove unexpected verification path: $VERIFY_ROOT" >&2
+      ;;
+  esac
+}
+
+trap cleanup EXIT
+
+pass() {
+  echo "PASS: $1"
+}
+
+note() {
+  echo "INFO: $1"
+}
+
+fail() {
+  echo "FAIL: $1" >&2
+  FAILURES=$((FAILURES + 1))
+}
+
+if curl -fsS "https://registry.npmjs.org/$PACKAGE_NAME" > "$REGISTRY_JSON"; then
+  latest=$(jq -r '."dist-tags".latest // empty' "$REGISTRY_JSON")
+  if [ "$latest" = "$EXPECTED_VERSION" ]; then
+    pass "npm latest is $EXPECTED_VERSION"
+  else
+    fail "npm latest is ${latest:-missing}; expected $EXPECTED_VERSION"
+  fi
+
+  if jq -e --arg version "$EXPECTED_VERSION" '.versions[$version] != null' "$REGISTRY_JSON" >/dev/null; then
+    pass "npm contains exact version $EXPECTED_VERSION"
+
+    published_git_head=$(jq -r --arg version "$EXPECTED_VERSION" '.versions[$version].gitHead // empty' "$REGISTRY_JSON")
+    if [ -z "$published_git_head" ]; then
+      note "npm does not expose gitHead; tarball SHA-256 remains the artifact identity gate"
+    elif [ "$published_git_head" = "$EXPECTED_COMMIT" ]; then
+      pass "npm gitHead matches $EXPECTED_COMMIT"
+    else
+      fail "npm gitHead is $published_git_head; expected $EXPECTED_COMMIT"
+    fi
+
+    published_repository=$(jq -r --arg version "$EXPECTED_VERSION" '(.versions[$version].repository | if type == "object" then .url else . end) // empty' "$REGISTRY_JSON")
+    published_homepage=$(jq -r --arg version "$EXPECTED_VERSION" '.versions[$version].homepage // empty' "$REGISTRY_JSON")
+    published_bugs=$(jq -r --arg version "$EXPECTED_VERSION" '.versions[$version].bugs.url // empty' "$REGISTRY_JSON")
+
+    if [ "$published_repository" = "$EXPECTED_REPOSITORY_URL" ] && \
+       [ "$published_homepage" = "$EXPECTED_HOMEPAGE" ] && \
+       [ "$published_bugs" = "$EXPECTED_BUGS_URL" ]; then
+      pass "npm repository identity matches $REPOSITORY"
+    else
+      fail "npm repository identity does not match $REPOSITORY"
+    fi
+
+    tarball_url=$(jq -r --arg version "$EXPECTED_VERSION" '.versions[$version].dist.tarball // empty' "$REGISTRY_JSON")
+    if [ -n "$tarball_url" ] && curl -fLsS "$tarball_url" -o "$PACKAGE_TARBALL"; then
+      package_sha256=$(node -e "const crypto=require('node:crypto');const fs=require('node:fs');const path=process.argv[1];console.log(crypto.createHash('sha256').update(fs.readFileSync(path)).digest('hex'))" "$PACKAGE_TARBALL")
+      if [ "$package_sha256" = "$EXPECTED_PACKAGE_SHA256" ]; then
+        pass "npm tarball SHA-256 matches the verified candidate"
+      else
+        fail "npm tarball SHA-256 is ${package_sha256:-missing}; expected $EXPECTED_PACKAGE_SHA256"
+      fi
+    else
+      fail "npm tarball could not be downloaded for SHA-256 verification"
+    fi
+
+    if npm --cache "$VERIFY_ROOT/npm-cache" install \
+      --ignore-scripts --no-audit --no-fund \
+      --prefix "$CONSUMER_ROOT" "$PACKAGE_TARBALL" >/dev/null; then
+      for binary in aeoptimize aeo aeo-cli; do
+        binary_version=$("$CONSUMER_ROOT/node_modules/.bin/$binary" --version 2>/dev/null || true)
+        if [ "$binary_version" = "$EXPECTED_VERSION" ]; then
+          pass "$binary resolves to $EXPECTED_VERSION from the public package"
+        else
+          fail "$binary returned ${binary_version:-no version}; expected $EXPECTED_VERSION"
+        fi
+      done
+    else
+      fail "clean consumer installation failed for the verified package tarball"
+    fi
+  else
+    fail "npm does not contain exact version $EXPECTED_VERSION"
+  fi
+else
+  fail "npm registry metadata could not be fetched"
+fi
+
+tag_lines=$(git ls-remote --tags "https://github.com/$REPOSITORY.git" \
+  "refs/tags/$EXPECTED_TAG" "refs/tags/$EXPECTED_TAG^{}" 2>/dev/null || true)
+tag_commit=$(printf '%s\n' "$tag_lines" | awk -v peeled="refs/tags/$EXPECTED_TAG^{}" '$2 == peeled { print $1 }')
+if [ -z "$tag_commit" ]; then
+  tag_commit=$(printf '%s\n' "$tag_lines" | awk -v direct="refs/tags/$EXPECTED_TAG" '$2 == direct { print $1 }')
+fi
+
+if [ "$tag_commit" = "$EXPECTED_COMMIT" ]; then
+  pass "$EXPECTED_TAG points to $EXPECTED_COMMIT"
+else
+  fail "$EXPECTED_TAG points to ${tag_commit:-missing}; expected $EXPECTED_COMMIT"
+fi
+
+release_status=$(curl -sS -o "$RELEASE_JSON" -w '%{http_code}' \
+  "https://api.github.com/repos/$REPOSITORY/releases/tags/$EXPECTED_TAG" || true)
+if [ "$release_status" = "200" ]; then
+  release_state=$(jq -r '[.tag_name, (.draft | tostring), (.prerelease | tostring)] | @tsv' "$RELEASE_JSON")
+  if [ "$release_state" = "$EXPECTED_TAG"$'\tfalse\tfalse' ]; then
+    pass "GitHub Release is published for $EXPECTED_TAG"
+  else
+    fail "GitHub Release is not a published non-prerelease for $EXPECTED_TAG"
+  fi
+else
+  fail "GitHub Release lookup returned HTTP ${release_status:-error}"
+fi
+
+if [ "$FAILURES" -ne 0 ]; then
+  echo "$FAILURES release verification check(s) failed." >&2
+  exit 1
+fi
+
+echo "All public release checks passed."