@jackwener/opencli 1.7.14 → 1.7.15

package/dist/src/build-manifest.js

@@ -209,6 +209,28 @@ export async function buildManifest() {
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+export function findManifestMetadataIssues(entries) {
+    const issues = [];
+    for (const entry of entries) {
+        if (!Array.isArray(entry.args))
+            continue;
+        for (const arg of entry.args) {
+            if (!arg.positional)
+                continue;
+            const help = typeof arg.help === 'string' ? arg.help.trim() : '';
+            if (help === '') {
+                issues.push({
+                    site: entry.site,
+                    command: entry.name,
+                    arg: arg.name,
+                    sourceFile: entry.sourceFile,
+                    reason: 'positional arg missing non-empty `help` text',
+                });
+            }
+        }
+    }
+    return issues;
+}
 /**
  * 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
@@ -278,6 +300,18 @@ async function main() {
             + `Always run via tsx (\`npm run build-manifest\`), not against compiled dist/.\n`);
         process.exit(1);
     }
+    const metadataIssues = findManifestMetadataIssues(entries);
+    if (metadataIssues.length > 0) {
+        process.stderr.write(`❌ ${metadataIssues.length} positional arg(s) missing \`help\` text:\n`);
+        for (const issue of metadataIssues) {
+            const where = issue.sourceFile ? ` (${issue.sourceFile})` : '';
+            process.stderr.write(`  - ${issue.site}/${issue.command} positional "${issue.arg}"${where}\n`);
+        }
+        process.stderr.write(`\nEvery positional arg must declare a non-empty \`help\` string so\n`
+            + `\`opencli <site> <cmd> --help\` shows callers what the parameter is for.\n`
+            + `Add \`help: '...'\` to each arg above and re-run the build.\n`);
+        process.exit(1);
+    }
     const existing = readExistingManifest(OUTPUT);
     if (existing) {
         const removed = diffRemovedEntries(existing, entries);

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 { ManifestImportError, diffRemovedEntries, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
+import { ManifestImportError, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -222,6 +222,113 @@ describe('manifest helper rules', () => {
         expect(diffRemovedEntries(prev, prev)).toEqual([]);
         expect(diffRemovedEntries([], next)).toEqual([]);
     });
+    it('findManifestMetadataIssues flags positionals with empty/missing help', () => {
+        // The build-time hard gate. A positional with `help: ''` or no `help` at
+        // all renders `Arguments:\n  <name>` with a blank trailing column —
+        // unrecoverable for both humans and agents reading help. Failing closed
+        // here is the only way to keep help text trustworthy as adapters land.
+        //
+        // Semantic quality (e.g. what does an *optional* positional mean when
+        // omitted?) is intentionally NOT enforced — that belongs to the planned
+        // Arg metadata v2 advisory pass.
+        const entries = [
+            // Positional with usable help — clean.
+            {
+                site: 'demo',
+                name: 'ok',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'q', positional: true, required: true, help: 'Search query' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/ok.js',
+            },
+            // Positional with empty help string — must flag.
+            {
+                site: 'demo',
+                name: 'empty-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'user', positional: true, required: false, help: '' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/empty.js',
+            },
+            // Positional with whitespace-only help — must flag.
+            {
+                site: 'demo',
+                name: 'whitespace-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'id', positional: true, required: true, help: '   ' },
+                ],
+                type: 'js',
+            },
+            // Positional with no help field at all — must flag.
+            {
+                site: 'demo',
+                name: 'missing-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'name', positional: true, required: true },
+                ],
+                type: 'js',
+            },
+            // NON-positional flag with empty help — must NOT flag (gate is
+            // intentionally scoped to positionals; named flags carry the flag
+            // name itself in the help line).
+            {
+                site: 'demo',
+                name: 'flag-only',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'limit', required: false, help: '' },
+                ],
+                type: 'js',
+            },
+        ];
+        const issues = findManifestMetadataIssues(entries);
+        expect(issues).toHaveLength(3);
+        expect(issues.map(i => `${i.site}/${i.command}/${i.arg}`).sort()).toEqual([
+            'demo/empty-help/user',
+            'demo/missing-help/name',
+            'demo/whitespace-help/id',
+        ]);
+        // sourceFile flows through when present so the build error points at the
+        // exact file to fix.
+        const emptyHelp = issues.find(i => i.command === 'empty-help');
+        expect(emptyHelp?.sourceFile).toBe('demo/empty.js');
+    });
+    it('findManifestMetadataIssues returns [] for fully-documented entries', () => {
+        expect(findManifestMetadataIssues([])).toEqual([]);
+        expect(findManifestMetadataIssues([
+            {
+                site: 'demo',
+                name: 'no-args',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [],
+                type: 'js',
+            },
+        ])).toEqual([]);
+    });
     it('parseBuildManifestArgs reads --allow-removals[=N]', () => {
         expect(parseBuildManifestArgs([]).allowRemovals).toBe(0);
         expect(parseBuildManifestArgs(['--allow-removals=5']).allowRemovals).toBe(5);