feat(cli): add clidoc OpenCLI docgen and CI validation

.github/workflows/ci.yml

@@ -31,6 +31,11 @@ jobs:
               exit 1
             }
           done
+      - name: Generate OpenCLI spec
+        run: node packages/cli/dist/index.js docgen --output packages/cli/opencli.json
+      - uses: bhouston/clidoc-action@v1
+        with:
+          files: packages/cli/opencli.json
       - run: pnpm tsc
       - run: pnpm lint
       - run: pnpm test --coverage

.gitignore

@@ -9,3 +9,4 @@ profile-output
 packages/hdrify-vscode-extension/media
 publish
 release-artifacts
+packages/cli/opencli.json

packages/cli/package.json

@@ -48,6 +48,8 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
+    "@clidoc/core": "^1.0.0",
+    "@clidoc/yargs": "^0.1.0",
     "hdrify": "workspace:*",
     "sharp": "^0.34.5",
     "yargs": "^18.0.0",

packages/cli/src/index.ts

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
 
+import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { fileCommands } from 'yargs-file-commands';
+import { createDocgenCommand, fromYargs } from '@clidoc/yargs';
+import { handleOpenCliRequest, infoFromPackageJson } from '@clidoc/core';
+import type { OpenCliDocument } from '@clidoc/core';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const commandsDir = path.join(__dirname, 'commands');
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '../package.json'), 'utf8'));
+const info = infoFromPackageJson(pkg);
 
 function isCommandError(msg: string): boolean {
   const lower = msg.toLowerCase();
@@ -24,10 +30,12 @@ function isCommandError(msg: string): boolean {
  * the caller handles exit codes.
  */
 export async function runCli(argv: string[]): Promise<unknown> {
+  let document: OpenCliDocument;
   const y = yargs(argv)
     .scriptName('hdrify')
     .usage('$0 <command> [options]')
     .command(await fileCommands({ commandDirs: [commandsDir] }))
+    .command(createDocgenCommand(() => document))
     .demandCommand(1, 'You must specify a command.')
     .help()
     .alias('h', 'help')
@@ -44,13 +52,19 @@ export async function runCli(argv: string[]): Promise<unknown> {
       if (err) throw err;
       throw new Error(msg);
     });
+  // generate the document once every command, including docgen, is registered
+  document = fromYargs(y, info);
 
   if (argv.length === 0) {
     console.error('You must specify a command.\n');
     y.showHelp();
     return;
   }
 
+  if (await handleOpenCliRequest(argv, () => document)) {
+    return;
+  }
+
   try {
     return await y.parse();
   } catch (error) {