@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/build-manifest.js

@@ -5,8 +5,21 @@
  * Scans all JS CLI definitions in clis/ and pre-compiles them into a single
  * manifest.json for instant cold-start registration.
  *
- * Usage: npx tsx src/build-manifest.ts
+ * Usage: npx tsx src/build-manifest.ts [--allow-removals[=N]]
+ *
  * Output: cli-manifest.json next to clis/
+ *
+ * Safety invariants:
+ *   - Adapters whose source file does not call `cli(...)` are silently
+ *     skipped (they are helpers / type modules, not commands).
+ *   - Adapters that look like commands but fail to import are reported as
+ *     failures, the manifest is NOT written, and the process exits 1. This
+ *     prevents a stale dist or a broken adapter from silently dropping
+ *     other adapters' entries (root cause of the "manifest lost 478 lines"
+ *     incident).
+ *   - Net-deletions vs the existing committed manifest abort the build by
+ *     default; pass `--allow-removals=N` (or just `--allow-removals` for any
+ *     amount) to confirm an intentional removal.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -14,12 +27,27 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { getErrorMessage } from './errors.js';
 import { fullName, getRegistry } from './registry.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+import { isRecord } from './utils.js';
 const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
-import { isRecord } from './utils.js';
 const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+/**
+ * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
+ * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
+ * decide whether to abort or aggregate failures across the whole scan.
+ */
+export class ManifestImportError extends Error {
+    filePath;
+    cause;
+    constructor(filePath, cause) {
+        super(`failed to scan ${filePath}: ${getErrorMessage(cause)}`);
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = 'ManifestImportError';
+    }
+}
 function toManifestArgs(args) {
     return args.map(arg => ({
         name: arg.name,
@@ -39,14 +67,15 @@ function toModulePath(filePath, site) {
 export function normalizeManifestPath(relativePath) {
     return relativePath.replace(/\\/g, '/');
 }
-function toManifestRelativePath(filePath) {
-    return normalizeManifestPath(path.relative(CLIS_DIR, filePath));
+function toManifestRelativePath(filePath, clisDir) {
+    return normalizeManifestPath(path.relative(clisDir, filePath));
 }
 function isCliCommandValue(value, site) {
     return isRecord(value)
         && typeof value.site === 'string'
         && value.site === site
         && typeof value.name === 'string'
+        && (value.access === 'read' || value.access === 'write')
         && Array.isArray(value.args);
 }
 function toManifestEntry(cmd, modulePath, sourceFile) {
@@ -55,6 +84,8 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         name: cmd.name,
         aliases: cmd.aliases,
         description: cmd.description ?? '',
+        access: cmd.access,
+        example: cmd.example,
         domain: cmd.domain,
         strategy: (cmd.strategy ?? 'public').toString().toLowerCase(),
         browser: cmd.browser ?? true,
@@ -69,12 +100,30 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         navigateBefore: cmd.navigateBefore,
     };
 }
-export async function loadManifestEntries(filePath, site, importer = moduleHref => import(moduleHref)) {
+/**
+ * Load all manifest entries from a single adapter file.
+ *
+ * Returns `[]` for files that do not register a CLI command (helpers, types).
+ * Throws `ManifestImportError` when a file looks like a CLI module but its
+ * import or post-import processing fails — callers must decide whether to
+ * surface or aggregate the failure.
+ *
+ * The third argument `clisDir` is used to compute the POSIX-style
+ * `sourceFile` relative path; it defaults to the package's `clis/` dir so
+ * existing test callers stay backward-compatible.
+ */
+export async function loadManifestEntries(filePath, site, importer = moduleHref => import(moduleHref), clisDir = CLIS_DIR) {
+    let src;
+    try {
+        src = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new ManifestImportError(filePath, err);
+    }
+    // Helper / test modules that do not call cli() are not commands.
+    if (!CLI_MODULE_PATTERN.test(src))
+        return [];
     try {
-        const src = fs.readFileSync(filePath, 'utf-8');
-        // Helper/test modules should not appear as CLI commands in the manifest.
-        if (!CLI_MODULE_PATTERN.test(src))
-            return [];
         const modulePath = toModulePath(filePath, site);
         const registry = getRegistry();
         const before = new Map(registry.entries());
@@ -93,7 +142,7 @@ export async function loadManifestEntries(filePath, site, importer = moduleHref
                 .map(([, cmd]) => cmd);
         // Manifest paths are cross-platform artifacts; keep them POSIX-style even
         // when build-manifest runs on Windows.
-        const sourceRelative = toManifestRelativePath(filePath);
+        const sourceRelative = toManifestRelativePath(filePath, clisDir);
         const seen = new Set();
         return runtimeCommands
             .filter((cmd) => {
@@ -107,42 +156,142 @@ export async function loadManifestEntries(filePath, site, importer = moduleHref
             .map(cmd => toManifestEntry(cmd, modulePath, sourceRelative));
     }
     catch (err) {
-        // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
-        process.stderr.write(`Warning: failed to scan ${filePath}: ${getErrorMessage(err)}\n`);
-        return [];
+        throw new ManifestImportError(filePath, err);
     }
 }
-export async function buildManifest() {
+/**
+ * Scan a `clis/` directory and aggregate per-adapter results. Import
+ * failures are collected in `failures` instead of crashing the whole scan,
+ * but the caller (e.g. `main()`) is expected to fail loud if any failure
+ * is present.
+ */
+export async function scanClisDir(clisDir, importer = moduleHref => import(moduleHref)) {
     const manifest = new Map();
-    // Scan JS adapters directly from clis/.
-    // Adapters are now JS-first — no compilation step needed.
-    if (fs.existsSync(CLIS_DIR)) {
-        for (const site of fs.readdirSync(CLIS_DIR)) {
-            const siteDir = path.join(CLIS_DIR, site);
-            if (!fs.statSync(siteDir).isDirectory())
-                continue;
-            for (const file of fs.readdirSync(siteDir)) {
-                if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js') {
-                    const filePath = path.join(siteDir, file);
-                    const entries = await loadManifestEntries(filePath, site);
+    const failures = [];
+    if (!fs.existsSync(clisDir)) {
+        return { entries: [], failures };
+    }
+    for (const site of fs.readdirSync(clisDir)) {
+        const siteDir = path.join(clisDir, site);
+        if (!fs.statSync(siteDir).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(siteDir)) {
+            if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js') {
+                const filePath = path.join(siteDir, file);
+                try {
+                    const entries = await loadManifestEntries(filePath, site, importer, clisDir);
                     for (const entry of entries) {
                         const key = `${entry.site}/${entry.name}`;
                         manifest.set(key, entry);
                     }
                 }
+                catch (err) {
+                    if (err instanceof ManifestImportError) {
+                        failures.push(err);
+                        continue;
+                    }
+                    throw err;
+                }
             }
         }
     }
-    return [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
+    const entries = [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
+    return { entries, failures };
+}
+export async function buildManifest() {
+    return scanClisDir(CLIS_DIR);
 }
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+/**
+ * Diff helper: returns site/name keys that exist in `prev` but not in
+ * `next`. Used as a safety net to detect accidental mass-deletions caused
+ * by silently failing adapter imports.
+ */
+export function diffRemovedEntries(prev, next) {
+    const nextKeys = new Set(next.map(e => `${e.site}/${e.name}`));
+    return prev
+        .map(e => `${e.site}/${e.name}`)
+        .filter(key => !nextKeys.has(key))
+        .sort();
+}
+/**
+ * Parse `--allow-removals` and `--allow-removals=N` from argv.
+ * Bare `--allow-removals` disables the safety net (`Infinity`); the
+ * numeric form sets an explicit upper bound.
+ */
+export function parseBuildManifestArgs(argv) {
+    let allowRemovals = 0;
+    for (const arg of argv) {
+        if (arg === '--allow-removals') {
+            allowRemovals = Number.POSITIVE_INFINITY;
+            continue;
+        }
+        const m = arg.match(/^--allow-removals=(\d+)$/);
+        if (m) {
+            allowRemovals = Number.parseInt(m[1], 10);
+            continue;
+        }
+    }
+    return { allowRemovals };
+}
+function readExistingManifest(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function main() {
-    const manifest = await buildManifest();
+    // Runtime guard: refuse to run from dist/. tsc transitively emits this
+    // file (the test file imports from it) so dist/src/build-manifest.js
+    // physically exists. If a developer or agent runs that compiled copy,
+    // any stale dist will silently break adapter imports — the exact failure
+    // mode this script is meant to prevent. Direct them at the tsx entry
+    // before they can shoot themselves in the foot.
+    if (fileURLToPath(import.meta.url).includes(`${path.sep}dist${path.sep}`)) {
+        process.stderr.write(`❌ Refusing to run build-manifest from dist/.\n`
+            + `   Stale compiled output silently drops adapters that import renamed/removed exports.\n`
+            + `   Run \`npm run build-manifest\` (or \`tsx src/build-manifest.ts\`) from the source tree instead.\n`);
+        process.exit(1);
+    }
+    const args = parseBuildManifestArgs(process.argv.slice(2));
+    const { entries, failures } = await buildManifest();
+    if (failures.length > 0) {
+        process.stderr.write(`❌ ${failures.length} adapter(s) failed to load:\n`);
+        for (const failure of failures) {
+            const rel = path.relative(PACKAGE_ROOT, failure.filePath) || failure.filePath;
+            process.stderr.write(`  - ${rel}: ${getErrorMessage(failure.cause)}\n`);
+        }
+        process.stderr.write(`\nManifest NOT written. Likely cause: stale dist/ or a broken adapter import.\n`
+            + `Always run via tsx (\`npm run build-manifest\`), not against compiled dist/.\n`);
+        process.exit(1);
+    }
+    const existing = readExistingManifest(OUTPUT);
+    if (existing) {
+        const removed = diffRemovedEntries(existing, entries);
+        if (removed.length > args.allowRemovals) {
+            process.stderr.write(`❌ ${removed.length} manifest entries would be removed; refusing to overwrite.\n`);
+            const preview = removed.slice(0, 20);
+            for (const key of preview)
+                process.stderr.write(`  - ${key}\n`);
+            if (removed.length > preview.length) {
+                process.stderr.write(`  ... ${removed.length - preview.length} more\n`);
+            }
+            process.stderr.write(`\nIf this removal is intentional, rerun with `
+                + `\`--allow-removals=${removed.length}\` (or \`--allow-removals\` to disable the check).\n`);
+            process.exit(1);
+        }
+    }
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-    fs.writeFileSync(OUTPUT, serializeManifest(manifest));
-    console.log(`✅ Manifest compiled: ${manifest.length} entries → ${OUTPUT}`);
+    fs.writeFileSync(OUTPUT, serializeManifest(entries));
+    console.log(`✅ Manifest compiled: ${entries.length} entries → ${OUTPUT}`);
     // Restore executable permissions on bin entries.
     // tsc does not preserve the +x bit, so after a clean rebuild the CLI
     // entry-point loses its executable permission, causing "Permission denied".

package/dist/src/build-manifest.test.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, getRegistry, Strategy } from './registry.js';
-import { loadManifestEntries, normalizeManifestPath, serializeManifest } from './build-manifest.js';
+import { ManifestImportError, diffRemovedEntries, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -24,11 +24,12 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'dynamic' });`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'dynamic', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => ({
             command: cli({
                 site,
                 name: 'dynamic',
+                access: 'read',
                 description: 'dynamic command',
                 strategy: Strategy.PUBLIC,
                 browser: false,
@@ -53,6 +54,7 @@ describe('manifest helper rules', () => {
             {
                 site,
                 name: 'dynamic',
+                access: 'read',
                 description: 'dynamic command',
                 domain: 'localhost',
                 strategy: 'public',
@@ -87,11 +89,12 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `cli({ site: '${site}', name: 'legacy' });`);
+        fs.writeFileSync(file, `cli({ site: '${site}', name: 'legacy', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => {
             cli({
                 site,
                 name: 'legacy',
+                access: 'read',
                 description: 'legacy command',
                 deprecated: 'legacy is deprecated',
                 replacedBy: 'opencli demo new',
@@ -102,6 +105,7 @@ describe('manifest helper rules', () => {
             {
                 site,
                 name: 'legacy',
+                access: 'read',
                 description: 'legacy command',
                 strategy: 'cookie',
                 browser: true,
@@ -123,16 +127,18 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `export const screen = cli({ site: '${site}', name: 'screen' });`);
+        fs.writeFileSync(file, `export const screen = cli({ site: '${site}', name: 'screen', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => ({
             screen: cli({
                 site,
                 name: 'screen',
+                access: 'read',
                 description: 'capture screen',
             }),
             status: cli({
                 site,
                 name: 'status',
+                access: 'read',
                 description: 'show status',
             }),
         }));
@@ -147,7 +153,7 @@ describe('manifest helper rules', () => {
     it('serializes manifest json with a trailing newline', () => {
         const serialized = serializeManifest([{
                 site: 'demo',
-                name: 'status',
+                name: 'status', access: 'read',
                 description: '',
                 strategy: 'public',
                 browser: false,
@@ -157,4 +163,78 @@ describe('manifest helper rules', () => {
         expect(serialized.endsWith('\n')).toBe(true);
         expect(serialized).toContain('\n]');
     });
+    it('throws ManifestImportError when an adapter looks like a CLI module but fails to import', async () => {
+        // Reproduces the "stale dist drops adapters silently" incident: the file
+        // matches the cli() pattern (so it's not just a helper), but the importer
+        // throws — we want the failure surfaced, not swallowed.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-fail-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'broken.ts');
+        fs.writeFileSync(file, `export const command = cli({ site: 'demo', name: 'broken', access: 'read' });`);
+        const importer = async () => { throw new Error('boom: stale dist'); };
+        await expect(loadManifestEntries(file, 'demo', importer))
+            .rejects.toBeInstanceOf(ManifestImportError);
+        try {
+            await loadManifestEntries(file, 'demo', importer);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ManifestImportError);
+            const e = err;
+            expect(e.filePath).toBe(file);
+            expect(e.message).toContain('boom: stale dist');
+        }
+    });
+    it('still silently skips files that do not call cli() even if the importer would have thrown', async () => {
+        // The cli() pattern check happens before importing — we don't even ask
+        // the importer about helper modules, so a thrown import does not turn
+        // them into failures.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-helper-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'helper.ts');
+        fs.writeFileSync(file, `export const helper = () => 42;`);
+        const importer = async () => { throw new Error('should never be called'); };
+        await expect(loadManifestEntries(file, 'demo', importer)).resolves.toEqual([]);
+    });
+    it('scanClisDir aggregates per-adapter import failures instead of silently dropping them', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-clis-'));
+        tempDirs.push(root);
+        const siteDir = path.join(root, 'demo');
+        fs.mkdirSync(siteDir);
+        fs.writeFileSync(path.join(siteDir, 'good.js'), `export const cmd = cli({ site: 'demo', name: 'good', access: 'read' });`);
+        fs.writeFileSync(path.join(siteDir, 'broken.js'), `export const cmd = cli({ site: 'demo', name: 'broken', access: 'read' });`);
+        const importer = async (href) => {
+            if (href.endsWith('broken.js'))
+                throw new Error('stale dist drops broken');
+            return { cmd: cli({ site: 'demo', name: 'good', access: 'read', description: 'ok' }) };
+        };
+        const result = await scanClisDir(root, importer);
+        expect(result.failures).toHaveLength(1);
+        expect(result.failures[0]).toBeInstanceOf(ManifestImportError);
+        expect(result.failures[0].filePath).toMatch(/broken\.js$/);
+        expect(result.failures[0].message).toContain('stale dist drops broken');
+        expect(result.entries.map(e => e.name)).toEqual(['good']);
+        getRegistry().delete('demo/good');
+    });
+    it('diffRemovedEntries returns site/name keys present only in prev', () => {
+        const prev = [
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '2', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'b', name: '3', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        const next = [
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        expect(diffRemovedEntries(prev, next)).toEqual(['a/2', 'b/3']);
+        expect(diffRemovedEntries(prev, prev)).toEqual([]);
+        expect(diffRemovedEntries([], next)).toEqual([]);
+    });
+    it('parseBuildManifestArgs reads --allow-removals[=N]', () => {
+        expect(parseBuildManifestArgs([]).allowRemovals).toBe(0);
+        expect(parseBuildManifestArgs(['--allow-removals=5']).allowRemovals).toBe(5);
+        expect(parseBuildManifestArgs(['--allow-removals=0']).allowRemovals).toBe(0);
+        // Bare flag is the explicit "I know what I'm doing" escape hatch.
+        expect(parseBuildManifestArgs(['--allow-removals']).allowRemovals).toBe(Number.POSITIVE_INFINITY);
+        // Unknown flags are ignored.
+        expect(parseBuildManifestArgs(['--something-else']).allowRemovals).toBe(0);
+    });
 });

package/dist/src/capabilityRouting.test.js

@@ -4,7 +4,7 @@ import { shouldUseBrowserSession } from './capabilityRouting.js';
 function makeCmd(partial) {
     return {
         site: 'test',
-        name: 'command',
+        name: 'command', access: 'read',
         description: '',
         args: [],
         ...partial,