publishport-opencli 1.8.4-pp.1

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "publishport-opencli",
+  "version": "1.8.4-pp.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Make any website or Electron App your CLI. AI-powered.",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "main": "dist/src/main.js",
+  "bin": {
+    "opencli": "dist/src/main.js"
+  },
+  "exports": {
+    ".": "./dist/src/main.js",
+    "./registry": "./dist/src/registry-api.js",
+    "./errors": "./dist/src/errors.js",
+    "./types": "./dist/src/types.js",
+    "./utils": "./dist/src/utils.js",
+    "./logger": "./dist/src/logger.js",
+    "./launcher": "./dist/src/launcher.js",
+    "./browser/cdp": "./dist/src/browser/cdp.js",
+    "./browser/page": "./dist/src/browser/page.js",
+    "./browser/utils": "./dist/src/browser/utils.js",
+    "./download": "./dist/src/download/index.js",
+    "./download/article-download": "./dist/src/download/article-download.js",
+    "./download/media-download": "./dist/src/download/media-download.js",
+    "./download/progress": "./dist/src/download/progress.js",
+    "./pipeline": "./dist/src/pipeline/index.js"
+  },
+  "files": [
+    "dist/src/",
+    "clis/",
+    "skills/opencli-*/**",
+    "cli-manifest.json",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/main.ts",
+    "dev:bun": "bun src/main.ts",
+    "build": "npm run clean-dist && npm run copy-yaml && npm run build-manifest",
+    "prebuild-manifest": "tsc --build && node -e \"require('fs').chmodSync('dist/src/main.js', 0o755)\"",
+    "build-manifest": "tsx src/build-manifest.ts",
+    "clean-dist": "node scripts/clean-dist.cjs",
+    "copy-yaml": "node scripts/copy-yaml.cjs",
+    "start": "node dist/src/main.js",
+    "start:bun": "bun dist/src/main.js",
+    "preuninstall": "node -e \"fetch('http://127.0.0.1:'+(process.env.OPENCLI_DAEMON_PORT||'19825')+'/shutdown',{method:'POST',headers:{'X-OpenCLI':'1'},signal:AbortSignal.timeout(3000)}).catch(()=>{})\" || true",
+    "postinstall": "node scripts/postinstall.js || true; node scripts/fetch-adapters.js || true",
+    "typecheck": "tsc --noEmit",
+    "prepare": "[ -d src ] && npm run build || true",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --project unit --project extension --project adapter",
+    "test:bun": "bun vitest run --project unit --project extension --project adapter",
+    "test:adapter": "vitest run --project adapter",
+    "test:all": "vitest run",
+    "test:e2e": "vitest run --project e2e",
+    "advise:listing-id-pairing": "node scripts/check-listing-id-pairing.mjs",
+    "check:silent-column-drop": "node scripts/check-silent-column-drop.mjs",
+    "check:typed-error-lint": "node scripts/check-typed-error-lint.mjs",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "keywords": [
+    "cli",
+    "browser",
+    "web",
+    "ai"
+  ],
+  "author": "jackwener",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackwener/opencli.git"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.0",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
+    "undici": "^6.27.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^27.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.2",
+    "@types/turndown": "^5.0.6",
+    "@types/ws": "^8.5.13",
+    "jsdom": "^29.0.2",
+    "tsx": "^4.19.3",
+    "typescript": "^6.0.2",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.1.0"
+  },
+  "overrides": {
+    "postcss": "^8.5.10",
+    "vitepress": {
+      "vite": "6.4.2"
+    }
+  }
+}

package/scripts/check-doc-coverage.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# check-doc-coverage.sh — Verify every adapter in clis/ has a doc page.
+#
+# Exit codes:
+#   0 — all adapters have docs
+#   1 — at least one adapter is missing documentation
+#
+# Usage:
+#   bash scripts/check-doc-coverage.sh          # report only
+#   bash scripts/check-doc-coverage.sh --strict  # exit 1 on missing docs
+
+set -euo pipefail
+
+STRICT=false
+if [[ "${1:-}" == "--strict" ]]; then
+  STRICT=true
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+SRC_DIR="$ROOT_DIR/clis"
+DOCS_DIR="$ROOT_DIR/docs/adapters"
+
+missing=()
+covered=0
+total=0
+
+for adapter_dir in "$SRC_DIR"/*/; do
+  adapter_name="$(basename "$adapter_dir")"
+  # Skip internal directories (e.g., _shared)
+  [[ "$adapter_name" == _* ]] && continue
+  # Skip directories that only contain utility files (prefixed with _)
+  has_commands=false
+  for f in "$adapter_dir"*; do
+    fname="$(basename "$f")"
+    [[ "$fname" == _* ]] && continue
+    [[ "$fname" == *.test.* ]] && continue
+    has_commands=true
+    break
+  done
+  [[ "$has_commands" == false ]] && continue
+  total=$((total + 1))
+
+  # Check if doc exists in browser/ or desktop/ subdirectories
+  if [[ -f "$DOCS_DIR/browser/$adapter_name.md" ]] || \
+     [[ -f "$DOCS_DIR/desktop/$adapter_name.md" ]]; then
+    covered=$((covered + 1))
+  else
+    # Handle directory name mismatches (e.g., discord-app -> discord)
+    alt_name="${adapter_name%-app}"
+    if [[ "$alt_name" != "$adapter_name" ]] && \
+       { [[ -f "$DOCS_DIR/browser/$alt_name.md" ]] || \
+         [[ -f "$DOCS_DIR/desktop/$alt_name.md" ]]; }; then
+      covered=$((covered + 1))
+    else
+      missing+=("$adapter_name")
+    fi
+  fi
+done
+
+echo "📊 Doc Coverage: $covered/$total adapters documented"
+echo ""
+
+if [[ ${#missing[@]} -gt 0 ]]; then
+  echo "⚠️  Missing docs for ${#missing[@]} adapter(s):"
+  for name in "${missing[@]}"; do
+    echo "   - $name  →  create docs/adapters/browser/$name.md or docs/adapters/desktop/$name.md"
+  done
+  echo ""
+  if $STRICT; then
+    echo "❌ Doc check failed (--strict mode)."
+    exit 1
+  else
+    echo "💡 Run with --strict to fail CI on missing docs."
+    exit 0
+  fi
+else
+  echo "✅ All adapters have documentation."
+  exit 0
+fi

package/scripts/check-listing-id-pairing.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * check-listing-id-pairing.mjs — advisory report on listing↔detail id round-tripping.
+ *
+ * Soft convention (NOT a CI gate): when a site exposes both a listing-class
+ * command (search / hot / recent / trending / top / feed / popular / new /
+ * list) AND a detail-class command (read / article / paper / post / detail /
+ * view / job / page / book / movie / show / chapter / question / answer /
+ * tweet / video / track), it's usually nicer for agents if every listing row
+ * carries an id-shaped column whose value round-trips into the detail
+ * command. Without that, the agent has to re-search by title or scrape a URL
+ * to follow up.
+ *
+ * Why advisory and not a gate: whether a listing should pair with a detail
+ * is a case-by-case product/UX call (topic-string trending, profile-attribute
+ * key/value rows, UI-only sessions etc. legitimately don't pair). Forcing
+ * authors through an exempt list every PR was higher cognitive cost than the
+ * silent-loss bugs the rule actually catches. See PR #1311 thread for the
+ * "anti-pattern vs case-by-case" filter.
+ *
+ * What this script does:
+ *  1. Group cli-manifest.json entries by site.
+ *  2. For each site that has both classes, walk every listing entry and
+ *     check `columns` for at least one id-shaped name.
+ *  3. Print a report. Always exits 0 — never fails CI.
+ *
+ * Usage:
+ *   node scripts/check-listing-id-pairing.mjs   # print advisory report
+ *   npm run advise:listing-id-pairing
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MANIFEST = resolve(__dirname, '..', 'cli-manifest.json');
+
+/**
+ * Listing-class commands. Each row represents a single fetchable entity
+ * (post / paper / job / ...). The id of that entity must round-trip into
+ * the site's detail command.
+ */
+const LISTING_NAMES = new Set([
+    'search', 'hot', 'recent', 'trending', 'top', 'feed', 'popular',
+    'list', 'best', 'newest', 'latest', 'rising', 'controversial',
+    'home', 'timeline', 'browse', 'discover', 'jobs',
+    'unanswered', 'bounties', 'tag', 'user', 'venue',
+    'category', 'subreddit', 'question',
+]);
+
+/**
+ * Listing-class commands whose rows are sub-resources within a parent
+ * thread/session, NOT independently fetchable. Excluded from the rule:
+ *
+ * - `comments` / `replies` / `reviews` / `answer-list` / `thread-list`
+ *   — rows are comments under a parent post; the detail command fetches
+ *   the parent, not the comment
+ * - `ask` / `new` / `show` for AI-chat / agent-session sites — rows are
+ *   conversation turns within one session, not separately addressable
+ *
+ * These are intentionally NOT in `LISTING_NAMES` so the rule doesn't
+ * fire on them.
+ */
+
+
+const DETAIL_NAMES = new Set([
+    'read', 'article', 'paper', 'post', 'detail', 'view', 'job',
+    'page', 'book', 'movie', 'show-detail', 'chapter', 'tweet',
+    'video', 'track', 'note', 'review', 'item', 'product', 'episode',
+    'thread', 'comment-detail', 'profile-detail', 'shop',
+]);
+
+/** Columns whose name implies "this is an id you can pass to detail". */
+const ID_COLUMN_PATTERNS = [
+    /^id$/i,
+    /_id$/i,
+    /Id$/,
+    /^short_id$/i,
+    /^jk$/i,             // indeed
+    /^tid$/i,            // hupu / thread id
+    /^bvid$/i,           // bilibili
+    /^aid$/i,            // anime / bilibili av
+    /^asin$/i,           // amazon
+    /^sku$/i,            // jd / retail product SKU
+    /^isbn$/i,           // book sites
+    /^doi$/i,            // arxiv / openreview
+    /^slug$/i,           // dev.to / lobsters short slug
+    /^hn_id$/i,
+    /^username$/i,       // user-keyed detail (profile commands)
+    /^handle$/i,
+    /^uri$/i,            // bluesky AT URI (at://did:.../...)
+];
+
+function isUrlDetailCommand(entry) {
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    const primaryArg = args.find((arg) => arg?.positional || arg?.required) ?? args[0];
+    if (!primaryArg) return false;
+    const name = String(primaryArg.name ?? '').toLowerCase();
+    if (name === 'url' || name === 'url-or-id') return true;
+
+    const help = String(primaryArg.help ?? '').toLowerCase();
+    if (!help) return false;
+
+    // Accept only explicit "this argument may be a URL" wording. Phrases
+    // like "id from URL" mean callers must extract an id before invoking
+    // the detail command, so listing.url must not satisfy the id-pair gate.
+    return (
+        /^full\b[^()]*\burl\b/.test(help) ||
+        /\burl\s+or\s+[^()]*\bid\b/.test(help) ||
+        /\bor\s+(?:a\s+)?full\b[^()]*\burl\b/.test(help) ||
+        /\bor\s+url\b/.test(help) ||
+        /\burl\s*,\s*or\b/.test(help)
+    );
+}
+
+function isIdColumn(col, detailCommands) {
+    if (ID_COLUMN_PATTERNS.some((re) => re.test(col))) return true;
+    if (/^url$/i.test(col)) {
+        return detailCommands.some(isUrlDetailCommand);
+    }
+    return false;
+}
+
+function classify(name) {
+    if (LISTING_NAMES.has(name)) return 'listing';
+    if (DETAIL_NAMES.has(name)) return 'detail';
+    return 'other';
+}
+
+function main() {
+    const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+
+    const bySite = new Map();
+    for (const entry of manifest) {
+        if (!entry?.site || !entry?.name) continue;
+        if (!bySite.has(entry.site)) bySite.set(entry.site, []);
+        bySite.get(entry.site).push(entry);
+    }
+
+    const findings = [];
+    let scannedSites = 0;
+    let scannedListings = 0;
+
+    for (const [site, entries] of bySite) {
+        // Only `access: 'read'` detail commands count — write commands like
+        // `instagram/post` or `instagram/note` create remote state, they don't
+        // fetch by id, so the listing→detail pairing rule doesn't apply.
+        const readDetail = entries.filter(
+            (e) => classify(e.name) === 'detail' && e.access === 'read',
+        );
+        const hasListing = entries.some((e) => classify(e.name) === 'listing');
+        if (!hasListing || readDetail.length === 0) continue;
+        scannedSites++;
+
+        for (const entry of entries) {
+            if (classify(entry.name) !== 'listing') continue;
+            scannedListings++;
+            const columns = Array.isArray(entry.columns) ? entry.columns : [];
+            if (!columns.some((col) => isIdColumn(col, readDetail))) {
+                findings.push({
+                    site,
+                    name: entry.name,
+                    columns,
+                    detail: readDetail.map((e) => e.name),
+                });
+            }
+        }
+    }
+
+    console.log(`Scanned ${scannedSites} site(s) with both listing and read-detail commands.`);
+    console.log(`Checked ${scannedListings} listing command(s).`);
+
+    if (findings.length === 0) {
+        console.log('OK — every listing carries an id-shaped column.');
+        return;
+    }
+
+    console.log('');
+    console.log(`Advisory: ${findings.length} listing(s) without a round-trippable id column.`);
+    console.log('Some of these are legitimate (topic strings, profile-attribute rows, UI-only');
+    console.log('sessions); others may be worth adding an id to. Use judgment, not a gate.');
+    console.log('');
+    for (const v of findings) {
+        console.log(`  • ${v.site}/${v.name}`);
+        console.log(`      columns: [${v.columns.join(', ')}]`);
+        console.log(`      detail commands on this site: ${v.detail.join(', ')}`);
+    }
+    console.log('');
+    console.log('See docs/conventions/listing-detail-id-pairing.md for context and patterns.');
+}
+
+main();

package/scripts/check-silent-column-drop.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * check-silent-column-drop.mjs — CI gate for newly introduced table-output loss.
+ *
+ * This gate intentionally uses a baseline. The repo currently has known
+ * silent-column-drop findings, and blocking every existing violation would make
+ * the first CI adoption PR too large. The invariant enforced here is:
+ *
+ *   no new silent-column-drop signatures beyond scripts/silent-column-drop-baseline.json
+ *
+ * When a follow-up sweep fixes existing violations, run:
+ *
+ *   node scripts/check-silent-column-drop.mjs --update-baseline
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const DIST_AUDIT = resolve(PROJECT_ROOT, 'dist', 'src', 'convention-audit.js');
+const BASELINE_PATH = resolve(__dirname, 'silent-column-drop-baseline.json');
+const UPDATE = process.argv.includes('--update-baseline');
+
+if (!existsSync(DIST_AUDIT)) {
+  console.error('dist/src/convention-audit.js not found. Run npm run build before this check.');
+  process.exit(1);
+}
+
+const { runConventionAudit } = await import(pathToFileURL(DIST_AUDIT).href);
+const report = runConventionAudit({ projectRoot: PROJECT_ROOT });
+const category = report.categories.find((item) => item.rule === 'silent-column-drop');
+const current = sortRecords((category?.violations ?? []).map(toBaselineRecord));
+
+if (UPDATE) {
+  writeFileSync(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
+  console.log(`Updated ${relative(BASELINE_PATH)} with ${current.length} silent-column-drop baseline entr${current.length === 1 ? 'y' : 'ies'}.`);
+  process.exit(0);
+}
+
+if (!existsSync(BASELINE_PATH)) {
+  console.error(`${relative(BASELINE_PATH)} not found. Run node scripts/check-silent-column-drop.mjs --update-baseline.`);
+  process.exit(1);
+}
+
+const baseline = sortRecords(JSON.parse(readFileSync(BASELINE_PATH, 'utf-8')));
+const baselineSignatures = new Set(baseline.map(signature));
+const currentSignatures = new Set(current.map(signature));
+const added = current.filter((record) => !baselineSignatures.has(signature(record)));
+const resolved = baseline.filter((record) => !currentSignatures.has(signature(record)));
+
+console.log(`Silent-column-drop gate: current=${current.length}, baseline=${baseline.length}, new=${added.length}, resolved=${resolved.length}`);
+
+if (resolved.length > 0) {
+  console.log('');
+  console.log('Resolved baseline entries detected. Consider shrinking the baseline:');
+  for (const record of resolved) {
+    console.log(`  - ${record.command} ${record.file} missing=[${record.missing.join(', ')}]`);
+  }
+}
+
+if (added.length === 0) {
+  console.log('OK - no new silent-column-drop violations.');
+  process.exit(0);
+}
+
+console.log('');
+console.log('New silent-column-drop violations:');
+for (const record of added) {
+  console.log(`  - ${record.command} ${record.file} missing=[${record.missing.join(', ')}]`);
+}
+console.log('');
+console.log('Fix the adapter columns, or if this is an intentional baseline adoption, run:');
+console.log('  node scripts/check-silent-column-drop.mjs --update-baseline');
+process.exit(1);
+
+function toBaselineRecord(violation) {
+  const missing = Array.isArray(violation.details?.missing)
+    ? violation.details.missing.map(String).sort()
+    : [];
+  return {
+    command: String(violation.command ?? ''),
+    file: String(violation.file ?? ''),
+    missing,
+  };
+}
+
+function signature(record) {
+  return `${record.command}\0${record.file}\0${record.missing.join('\0')}`;
+}
+
+function sortRecords(records) {
+  return records
+    .map((record) => ({
+      command: String(record.command),
+      file: String(record.file),
+      missing: Array.isArray(record.missing) ? record.missing.map(String).sort() : [],
+    }))
+    .sort((a, b) => signature(a).localeCompare(signature(b)));
+}
+
+function relative(file) {
+  return file.replace(`${PROJECT_ROOT}/`, '');
+}

package/scripts/check-typed-error-lint.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * check-typed-error-lint.mjs — CI gate for newly introduced silent failures.
+ *
+ * Baseline mode keeps adoption small: existing findings are recorded in
+ * scripts/typed-error-lint-baseline.json, while CI rejects any new
+ * silent-clamp / silent-empty-fallback / silent-sentinel signatures.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const DIST_AUDIT = resolve(PROJECT_ROOT, 'dist', 'src', 'convention-audit.js');
+const BASELINE_PATH = resolve(__dirname, 'typed-error-lint-baseline.json');
+const UPDATE = process.argv.includes('--update-baseline');
+const RULES = new Set(['silent-clamp', 'silent-empty-fallback', 'silent-sentinel']);
+
+if (!existsSync(DIST_AUDIT)) {
+  console.error('dist/src/convention-audit.js not found. Run npm run build before this check.');
+  process.exit(1);
+}
+
+const { runConventionAudit } = await import(pathToFileURL(DIST_AUDIT).href);
+const report = runConventionAudit({ projectRoot: PROJECT_ROOT });
+const current = addOccurrenceIndexes(sortRecords(report.categories
+  .filter((category) => RULES.has(category.rule))
+  .flatMap((category) => category.violations.map(toBaselineRecord))));
+
+if (UPDATE) {
+  writeFileSync(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
+  console.log(`Updated ${relative(BASELINE_PATH)} with ${current.length} typed-error lint baseline entr${current.length === 1 ? 'y' : 'ies'}.`);
+  process.exit(0);
+}
+
+if (!existsSync(BASELINE_PATH)) {
+  console.error(`${relative(BASELINE_PATH)} not found. Run node scripts/check-typed-error-lint.mjs --update-baseline.`);
+  process.exit(1);
+}
+
+const baseline = addOccurrenceIndexes(sortRecords(JSON.parse(readFileSync(BASELINE_PATH, 'utf-8'))));
+const baselineSignatures = new Set(baseline.map(signature));
+const currentSignatures = new Set(current.map(signature));
+const added = current.filter((record) => !baselineSignatures.has(signature(record)));
+const resolved = baseline.filter((record) => !currentSignatures.has(signature(record)));
+
+console.log(`Typed-error lint gate: current=${current.length}, baseline=${baseline.length}, new=${added.length}, resolved=${resolved.length}`);
+
+if (resolved.length > 0) {
+  console.log('');
+  console.log('Resolved baseline entries detected. Consider shrinking the baseline:');
+  for (const record of resolved) {
+    console.log(`  - ${record.rule} ${record.command} ${record.file}:${record.line}`);
+  }
+}
+
+if (added.length === 0) {
+  console.log('OK - no new typed-error lint violations.');
+  process.exit(0);
+}
+
+console.log('');
+console.log('New typed-error lint violations:');
+for (const record of added) {
+  console.log(`  - ${record.rule} ${record.command} ${record.file}:${record.line}`);
+  if (record.text) console.log(`    ${record.text}`);
+}
+console.log('');
+console.log('Fix the silent fallback, or if this is an intentional baseline adoption, run:');
+console.log('  node scripts/check-typed-error-lint.mjs --update-baseline');
+process.exit(1);
+
+function toBaselineRecord(violation) {
+  return {
+    rule: String(violation.rule ?? ''),
+    command: String(violation.command ?? ''),
+    file: String(violation.file ?? ''),
+    line: Number(violation.line ?? 0),
+    text: String(violation.details?.text ?? ''),
+  };
+}
+
+function signature(record) {
+  return `${record.rule}\0${record.command}\0${record.file}\0${record.text}\0${record.occurrence}`;
+}
+
+function sortRecords(records) {
+  return records
+    .map((record) => ({
+      rule: String(record.rule),
+      command: String(record.command),
+      file: String(record.file),
+      line: Number(record.line ?? 0),
+      text: String(record.text ?? ''),
+      occurrence: Number(record.occurrence ?? 0),
+    }))
+    .sort((a, b) => stableOrder(a).localeCompare(stableOrder(b)));
+}
+
+function addOccurrenceIndexes(records) {
+  const seen = new Map();
+  return records.map((record) => {
+    const key = `${record.rule}\0${record.command}\0${record.file}\0${record.text}`;
+    const occurrence = seen.get(key) ?? 0;
+    seen.set(key, occurrence + 1);
+    return { ...record, occurrence };
+  });
+}
+
+function stableOrder(record) {
+  return `${record.rule}\0${record.command}\0${record.file}\0${record.text}\0${record.line}`;
+}
+
+function relative(file) {
+  return file.replace(`${PROJECT_ROOT}/`, '');
+}

package/scripts/clean-dist.cjs

@@ -0,0 +1,13 @@
+/**
+ * Remove dist/ before a fresh build so deleted source modules do not leave
+ * stale compiled files behind.
+ */
+const { existsSync, rmSync } = require('fs');
+
+if (existsSync('dist')) {
+  rmSync('dist', { recursive: true, force: true });
+}
+
+if (existsSync('tsconfig.tsbuildinfo')) {
+  rmSync('tsconfig.tsbuildinfo', { force: true });
+}

package/scripts/copy-yaml.cjs

@@ -0,0 +1,12 @@
+/**
+ * Copy YAML support files to dist/.
+ * (Adapters are JS-first and no longer need yaml copying.)
+ */
+const { copyFileSync, mkdirSync, existsSync } = require('fs');
+
+// Copy external CLI registry to dist/
+const extSrc = 'src/external-clis.yaml';
+if (existsSync(extSrc)) {
+  mkdirSync('dist/src', { recursive: true });
+  copyFileSync(extSrc, 'dist/src/external-clis.yaml');
+}