@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/registry.test.js

@@ -7,13 +7,14 @@ describe('cli() registration', () => {
     it('registers a command and returns it', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'hello',
+            name: 'hello', access: 'read',
             description: 'A test command',
             strategy: Strategy.PUBLIC,
             browser: false,
         });
         expect(cmd.site).toBe('test-registry');
         expect(cmd.name).toBe('hello');
+        expect(cmd.access).toBe('read');
         expect(cmd.strategy).toBe(Strategy.PUBLIC);
         expect(cmd.browser).toBe(false);
         expect(cmd.args).toEqual([]);
@@ -21,7 +22,7 @@ describe('cli() registration', () => {
     it('puts registered command in the registry', () => {
         cli({
             site: 'test-registry',
-            name: 'registered',
+            name: 'registered', access: 'read',
             description: 'test',
         });
         const registry = getRegistry();
@@ -30,7 +31,7 @@ describe('cli() registration', () => {
     it('defaults strategy to COOKIE when browser is true', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'default-strategy',
+            name: 'default-strategy', access: 'read',
         });
         expect(cmd.strategy).toBe(Strategy.COOKIE);
         expect(cmd.browser).toBe(true);
@@ -38,7 +39,7 @@ describe('cli() registration', () => {
     it('defaults strategy to PUBLIC when browser is false', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'no-browser',
+            name: 'no-browser', access: 'read',
             browser: false,
         });
         expect(cmd.strategy).toBe(Strategy.PUBLIC);
@@ -46,7 +47,7 @@ describe('cli() registration', () => {
     it('preserves LOCAL strategy on registration', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'local-strategy',
+            name: 'local-strategy', access: 'read',
             description: 'reads local credentials',
             strategy: Strategy.LOCAL,
             browser: false,
@@ -55,15 +56,15 @@ describe('cli() registration', () => {
         expect(cmd.browser).toBe(false);
     });
     it('overwrites existing command on re-registration', () => {
-        cli({ site: 'test-registry', name: 'overwrite', description: 'v1' });
-        cli({ site: 'test-registry', name: 'overwrite', description: 'v2' });
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v1' });
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v2' });
         const reg = getRegistry();
         expect(reg.get('test-registry/overwrite')?.description).toBe('v2');
     });
     it('registers aliases as alternate registry keys for the same command', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'canonical',
+            name: 'canonical', access: 'read',
             description: 'test aliases',
             aliases: ['compat', 'legacy-name'],
         });
@@ -76,18 +77,24 @@ describe('cli() registration', () => {
     it('preserves defaultFormat on the registered command', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'plain-default',
+            name: 'plain-default', access: 'read',
             description: 'prefers plain output',
             defaultFormat: 'plain',
         });
         expect(cmd.defaultFormat).toBe('plain');
         expect(getRegistry().get('test-registry/plain-default')?.defaultFormat).toBe('plain');
     });
+    it('rejects commands without explicit access metadata', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'missing-access',
+        })).toThrow("Command test-registry/missing-access must declare access: 'read' | 'write'");
+    });
 });
 describe('fullName', () => {
     it('returns site/name', () => {
         const cmd = {
-            site: 'bilibili', name: 'hot', description: '', args: [],
+            site: 'bilibili', name: 'hot', access: 'read', description: '', args: [],
         };
         expect(fullName(cmd)).toBe('bilibili/hot');
     });
@@ -95,14 +102,14 @@ describe('fullName', () => {
 describe('strategyLabel', () => {
     it('returns strategy string', () => {
         const cmd = {
-            site: 'test', name: 'test', description: '', args: [],
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
             strategy: Strategy.INTERCEPT,
         };
         expect(strategyLabel(cmd)).toBe('intercept');
     });
     it('returns public when no strategy set', () => {
         const cmd = {
-            site: 'test', name: 'test', description: '', args: [],
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
         };
         expect(strategyLabel(cmd)).toBe('public');
     });
@@ -111,7 +118,7 @@ describe('registerCommand', () => {
     it('registers a pre-built command', () => {
         const cmd = {
             site: 'test-registry',
-            name: 'direct-reg',
+            name: 'direct-reg', access: 'read',
             description: 'directly registered',
             args: [],
             strategy: Strategy.HEADER,
@@ -125,7 +132,7 @@ describe('registerCommand', () => {
 describe('normalizeCommand (via registerCommand)', () => {
     it('COOKIE + domain → navigateBefore is the domain URL', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-domain', description: '', args: [],
+            site: 'test-norm', name: 'cookie-domain', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'x.com',
         });
         const cmd = getRegistry().get('test-norm/cookie-domain');
@@ -134,7 +141,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('COOKIE without domain → navigateBefore is true (auth context, no URL)', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-nodomain', description: '', args: [],
+            site: 'test-norm', name: 'cookie-nodomain', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE,
         });
         const cmd = getRegistry().get('test-norm/cookie-nodomain');
@@ -143,7 +150,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('INTERCEPT → navigateBefore is true (auth context)', () => {
         registerCommand({
-            site: 'test-norm', name: 'intercept', description: '', args: [],
+            site: 'test-norm', name: 'intercept', access: 'read', description: '', args: [],
             strategy: Strategy.INTERCEPT, domain: 'example.com',
         });
         const cmd = getRegistry().get('test-norm/intercept');
@@ -152,7 +159,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('PUBLIC → browser false, navigateBefore undefined', () => {
         registerCommand({
-            site: 'test-norm', name: 'public', description: '', args: [],
+            site: 'test-norm', name: 'public', access: 'read', description: '', args: [],
             strategy: Strategy.PUBLIC,
         });
         const cmd = getRegistry().get('test-norm/public');
@@ -161,7 +168,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('LOCAL → browser false, navigateBefore undefined', () => {
         registerCommand({
-            site: 'test-norm', name: 'local', description: '', args: [],
+            site: 'test-norm', name: 'local', access: 'read', description: '', args: [],
             strategy: Strategy.LOCAL,
         });
         const cmd = getRegistry().get('test-norm/local');
@@ -172,7 +179,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('explicit navigateBefore: false overrides COOKIE + domain', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-override', description: '', args: [],
+            site: 'test-norm', name: 'cookie-override', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'amazon.com', navigateBefore: false,
         });
         const cmd = getRegistry().get('test-norm/cookie-override');
@@ -181,7 +188,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('explicit navigateBefore URL overrides strategy default', () => {
         registerCommand({
-            site: 'test-norm', name: 'explicit-url', description: '', args: [],
+            site: 'test-norm', name: 'explicit-url', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'x.com',
             navigateBefore: 'https://x.com/explore',
         });

package/dist/src/serialization.d.ts

@@ -24,15 +24,19 @@ export declare function serializeCommand(cmd: CliCommand): {
     name: string;
     aliases: string[];
     description: string;
+    access: import("./registry.js").CommandAccess;
     strategy: string;
     browser: boolean;
     args: SerializedArg[];
     columns: string[];
     domain: string | null;
+    example: string;
     deprecated: string | boolean | null;
     replacedBy: string | null;
 };
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export declare function formatCommandExample(cmd: CliCommand): string;
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export declare function formatRegistryHelpText(cmd: CliCommand): string;

package/dist/src/serialization.js

@@ -26,11 +26,13 @@ export function serializeCommand(cmd) {
         name: cmd.name,
         aliases: cmd.aliases ?? [],
         description: cmd.description,
+        access: cmd.access,
         strategy: strategyLabel(cmd),
         browser: !!cmd.browser,
         args: cmd.args.map(serializeArg),
         columns: cmd.columns ?? [],
         domain: cmd.domain ?? null,
+        example: formatCommandExample(cmd),
         deprecated: cmd.deprecated ?? null,
         replacedBy: cmd.replacedBy ?? null,
     };
@@ -51,6 +53,29 @@ function summarizeChoices(choices) {
         return choices.join(', ');
     return `${choices.slice(0, 4).join(', ')}, ... (+${choices.length - 4} more)`;
 }
+function formatValuePlaceholder(name) {
+    return `<${name}>`;
+}
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export function formatCommandExample(cmd) {
+    if (cmd.example?.trim())
+        return cmd.example.trim();
+    const parts = ['opencli', cmd.site, cmd.name];
+    for (const arg of cmd.args) {
+        if (arg.positional && arg.required) {
+            parts.push(formatValuePlaceholder(arg.name));
+        }
+    }
+    for (const arg of cmd.args) {
+        if (arg.positional || !arg.required)
+            continue;
+        parts.push(`--${arg.name}`);
+        if (arg.type !== 'bool' && arg.type !== 'boolean')
+            parts.push(formatValuePlaceholder(arg.name));
+    }
+    parts.push('-f', 'yaml');
+    return parts.join(' ');
+}
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export function formatRegistryHelpText(cmd) {
     const lines = [];
@@ -61,7 +86,7 @@ export function formatRegistryHelpText(cmd) {
         lines.push(`  ${prefix}: ${summarizeChoices(a.choices)}${def}`);
     }
     const meta = [];
-    meta.push(`Strategy: ${strategyLabel(cmd)}`);
+    meta.push(`Access: ${cmd.access}`);
     meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
     if (cmd.domain)
         meta.push(`Domain: ${cmd.domain}`);
@@ -72,6 +97,7 @@ export function formatRegistryHelpText(cmd) {
     if (cmd.aliases?.length)
         meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
     lines.push(meta.join(' | '));
+    lines.push(`Example: ${formatCommandExample(cmd)}`);
     if (cmd.columns?.length)
         lines.push(`Output columns: ${cmd.columns.join(', ')}`);
     return '\n' + lines.join('\n') + '\n';

package/dist/src/serialization.test.js

@@ -1,11 +1,11 @@
 import { describe, expect, it } from 'vitest';
 import { Strategy } from './registry.js';
-import { formatRegistryHelpText, serializeCommand } from './serialization.js';
+import { formatCommandExample, formatRegistryHelpText, serializeCommand } from './serialization.js';
 describe('formatRegistryHelpText', () => {
     it('summarizes long choices lists so help text stays readable', () => {
         const cmd = {
             site: 'demo',
-            name: 'dynamic',
+            name: 'dynamic', access: 'read',
             description: 'Demo command',
             strategy: Strategy.PUBLIC,
             browser: false,
@@ -24,6 +24,7 @@ describe('formatRegistryHelpText', () => {
         const cmd = {
             site: 'demo',
             name: 'get',
+            access: 'read',
             aliases: ['metadata'],
             description: 'Demo command',
             strategy: Strategy.COOKIE,
@@ -32,8 +33,29 @@ describe('formatRegistryHelpText', () => {
         };
         expect(serializeCommand(cmd)).toMatchObject({
             command: 'demo/get',
+            access: 'read',
             aliases: ['metadata'],
         });
         expect(formatRegistryHelpText(cmd)).toContain('Aliases: metadata');
     });
+    it('surfaces access and canonical examples instead of strategy as primary help metadata', () => {
+        const cmd = {
+            site: 'bilibili',
+            name: 'hot',
+            access: 'read',
+            description: 'Bilibili hot videos',
+            strategy: Strategy.COOKIE,
+            browser: true,
+            args: [],
+        };
+        expect(formatCommandExample(cmd)).toBe('opencli bilibili hot -f yaml');
+        expect(serializeCommand(cmd)).toMatchObject({
+            command: 'bilibili/hot',
+            access: 'read',
+            example: 'opencli bilibili hot -f yaml',
+        });
+        expect(formatRegistryHelpText(cmd)).toContain('Access: read');
+        expect(formatRegistryHelpText(cmd)).toContain('Example: opencli bilibili hot -f yaml');
+        expect(formatRegistryHelpText(cmd)).not.toContain('Strategy:');
+    });
 });

package/dist/src/types.d.ts

@@ -130,6 +130,8 @@ export interface IPage {
     setActivePage?(page?: string): void;
     /** Send a raw CDP command via chrome.debugger passthrough. */
     cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Accept or dismiss the currently open JavaScript alert/confirm/prompt dialog. */
+    handleJavaScriptDialog?(accept: boolean, promptText?: string): Promise<void>;
     /** List cross-origin iframe targets in snapshot order. */
     frames?(): Promise<Array<{
         index: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.10",
+  "version": "1.7.12",
   "publishConfig": {
     "access": "public"
   },
@@ -42,7 +42,7 @@
     "dev": "tsx src/main.ts",
     "dev:bun": "bun src/main.ts",
     "build": "npm run clean-dist && tsc && npm run copy-yaml && npm run build-manifest",
-    "build-manifest": "node dist/src/build-manifest.js",
+    "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",
@@ -57,6 +57,9 @@
     "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"

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}/`, '');
+}