cli-forge 0.10.1 → 0.12.0

package/dist/lib/test-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-harness.js","sourceRoot":"","sources":["../../src/lib/test-harness.ts"],"names":[],"mappings":";;;AACA,iDAA6C;AA8B7C;;;GAGG;AACH,MAAa,WAAW;IACd,GAAG,CAAiB;IAE5B,YAAY,GAAW;QACrB,IAAI,GAAG,YAAY,0BAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;YACf,WAAW,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAc;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAExC,OAAO;YACL,IAAI,EAAE,IAAI;YACV,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY;SACpC,CAAC;IACJ,CAAC;CACF;AAtBD,kCAsBC;AAED,SAAS,WAAW,CAAC,GAAgB;IACnC,IAAI,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,CAAC;QAC/B,GAAG,CAAC,aAAa,CAAC,OAAO,GAAG,GAAG,EAAE;YAC/B,6BAA6B;QAC/B,CAAC,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,kBAAkB,EAAE,CAAC;QAC7C,WAAW,CAAC,GAAG,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/lib/utils.ts"],"names":[],"mappings":"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"}

package/dist/middleware/zod.d.ts

@@ -0,0 +1,4 @@
+import { ParsedArgs } from '@cli-forge/parser';
+import { MiddlewareFunction } from '../lib/public-api';
+import type { z, ZodObject, ZodPipe } from 'zod';
+export declare function zodMiddleware<TArgs extends ParsedArgs, TSchema extends ZodObject | ZodPipe<ZodObject>>(schema: TSchema): MiddlewareFunction<TArgs, TArgs & z.infer<TSchema>>;

package/dist/middleware/zod.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodMiddleware = zodMiddleware;
+/*
+ * Middleware that uses a Zod schema to validate and transform command arguments.
+ * @param schema The Zod schema to use for validation and transformation.
+ * @returns A middleware function that applies the Zod schema to the command arguments.
+ */
+function zodMiddleware(schema) {
+    return async (args) => {
+        const parsed = (await schema.parseAsync(args));
+        if (typeof parsed !== 'object') {
+            throw new Error('Zod schema did not return an object');
+        }
+        return { ...args, ...parsed };
+    };
+}
+//# sourceMappingURL=zod.js.map

package/dist/middleware/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../src/middleware/zod.ts"],"names":[],"mappings":";;AASA,sCAWC;AAhBD;;;;GAIG;AACH,SAAgB,aAAa,CAG3B,MAAe;IACf,OAAO,KAAK,EAAE,IAAW,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAqB,CAAC;QACnE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1 @@
+export * from './middleware/zod';

package/dist/middleware.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./middleware/zod"), exports);
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":";;;AAAA,2DAAiC"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "cli-forge",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "dependencies": {
     "tslib": "^2.3.0",
-    "@cli-forge/parser": "0.10.1"
+    "@cli-forge/parser": "0.12.0"
   },
   "peerDependencies": {
-    "markdown-factory": "0.2.0",
-    "tsx": "4.19.0"
+    "markdown-factory": "^0.2.0",
+    "tsx": "^4.19.0",
+    "zod": "^4.1.13"
   },
   "peerDependenciesMeta": {
     "markdown-factory": {
@@ -17,22 +18,40 @@
     "tsx": {
       "optional": true,
       "dev": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "type": "commonjs",
-  "main": "./src/index.js",
-  "typings": "./src/index.d.ts",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
   "license": "ISC",
+  "homepage": "https://craigory.dev/cli-forge/",
   "repository": {
     "type": "git",
     "directory": "packages/cli-forge",
     "url": "https://github.com/AgentEnder/cli-forge"
   },
   "bin": {
-    "cli-forge": "./bin/cli.js"
+    "cli-forge": "./cli.js"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware": {
+      "require": "./dist/middleware.js",
+      "types": "./dist/middleware.d.ts"
+    },
+    "./middleware/*": {
+      "require": "./dist/middleware/*.js",
+      "types": "./dist/middleware/*.d.ts"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "types": "./src/index.d.ts"
-}
+  }
+}

package/project.json

@@ -0,0 +1,7 @@
+{
+  "name": "cli-forge",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/cli-forge/src",
+  "projectType": "library",
+  "tags": []
+}

package/src/bin/cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { cli } from '../lib/public-api';
+import { generateDocumentationCommand } from './commands/generate-documentation';
+import { initCommand } from './commands/init';
+
+const mycli = cli('cli-forge', {
+  description: "CLI tool for working with cli-forge based CLI's.",
+}).commands(generateDocumentationCommand, initCommand);
+
+export default mycli;
+
+if (require.main === module) {
+  (async () => {
+    await mycli.forge();
+  })();
+}

package/src/bin/commands/generate-documentation.ts

@@ -0,0 +1,403 @@
+import type { ParsedArgs } from '@cli-forge/parser';
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { join as joinPathFragments, normalize } from 'node:path/posix';
+import { pathToFileURL } from 'node:url';
+
+import cli, { ArgumentsOf, CLI } from '../..';
+import { Documentation, generateDocumentation } from '../../lib/documentation';
+import { ensureDirSync } from '../utils/fs';
+import { InternalCLI } from '../../lib/internal-cli';
+
+type mdfactory = typeof import('markdown-factory');
+
+type GenerateDocsArgs = ArgumentsOf<typeof withGenerateDocumentationArgs>;
+
+export function withGenerateDocumentationArgs<T extends ParsedArgs>(
+  cmd: CLI<T>
+) {
+  return cmd
+    .positional('cli', {
+      type: 'string',
+      description: 'Path to the cli that docs should be generated for.',
+      required: true,
+    })
+    .option('output', {
+      alias: ['o'],
+      type: 'string',
+      description: 'Where should the documentation be output?',
+      default: 'docs',
+    })
+    .option('format', {
+      type: 'string',
+      description: 'What format should the documentation be output in?',
+      default: 'md',
+      choices: ['json', 'md'],
+    })
+    .option('export', {
+      type: 'string',
+      description:
+        'The name of the export that contains the CLI instance. By default, docs will be generated for the default export.',
+    })
+    .option('tsconfig', {
+      type: 'string',
+      description:
+        'Specifies the `tsconfig` used when loading typescript based CLIs.',
+    });
+}
+
+export const generateDocumentationCommand: CLI<any, any, any> = cli('generate-documentation', {
+  description: 'Generate documentation for the given CLI',
+  examples: [
+    'cli-forge generate-documentation ./bin/my-cli',
+    'cli-forge generate-documentation ./bin/my-cli --format json',
+    'cli-forge generate-documentation ./bin/my-cli --export mycli',
+  ],
+  builder: (b) => withGenerateDocumentationArgs(b),
+  handler: async (args) => {
+    const cliModule = await loadCLIModule(args);
+    const cli = readCLIFromModule(cliModule, args);
+
+    const documentation = generateDocumentation(cli);
+    if (args.format === 'md') {
+      await generateMarkdownDocumentation(documentation, args);
+    } else if (args.format === 'json') {
+      const outfile = args.output.endsWith('json')
+        ? args.output
+        : join(args.output, cli.name + '.json');
+      const outdir = dirname(outfile);
+      ensureDirSync(outdir);
+      writeFileSync(outfile, JSON.stringify(documentation, null, 2));
+    }
+  },
+});
+
+async function generateMarkdownDocumentation(
+  docs: Documentation,
+  args: GenerateDocsArgs
+) {
+  const md = await importMarkdownFactory();
+  await generateMarkdownForSingleCommand(docs, args.output, args.output, md);
+}
+
+async function generateMarkdownForSingleCommand(
+  docs: Documentation,
+  out: string,
+  docsRoot: string,
+  md: mdfactory
+) {
+  const subcommands = docs.subcommands;
+  const outdir = subcommands.length ? out : dirname(out);
+  const outname = subcommands.length ? 'index' : docs.name;
+
+  ensureDirSync(outdir);
+
+  writeFileSync(
+    join(outdir, outname + '.md'),
+    md.h1(
+      docs.name,
+      ...[
+        [md.bold('Usage:'), md.code(docs.usage)].join(' '),
+        docs.description,
+        getPositionalArgsFragment(docs.positionals, md),
+        getFlagArgsFragment(docs.options, 'Flags', md),
+        ...docs.groupedOptions.map((group) =>
+          getFlagArgsFragment(
+            Object.fromEntries(group.keys.map((key) => [key.key, key])),
+            group.label,
+            md
+          )
+        ),
+        getSubcommandsFragment(docs.subcommands, outdir, docsRoot, md),
+        getExamplesFragment(docs.examples, md),
+        getEpilogueFragment(docs.epilogue, md),
+      ].filter(isTruthy)
+    )
+  );
+  for (const subcommand of docs.subcommands) {
+    await generateMarkdownForSingleCommand(
+      subcommand,
+      join(outdir, subcommand.name),
+      docsRoot,
+      md
+    );
+  }
+}
+
+function formatOption(option: Documentation['options'][string], md: mdfactory) {
+  return md.h3(
+    option.deprecated ? md.strikethrough(option.key) : option.key,
+    ...[
+      option.deprecated ? md.bold(md.italics('Deprecated')) : undefined,
+      md.bold('Type:') +
+        ' ' +
+        ('items' in option && option.type === 'array'
+          ? `${option.items}[]`
+          : option.type),
+      option.description,
+      option.default !== undefined
+        ? renderDefaultValueSection(option.default, md)
+        : undefined,
+      // No need to show required if it's required and has a default, as its not actually required to pass.
+      option.required && !option.default ? md.bold('Required') : undefined,
+      'choices' in option && option.choices
+        ? md.bold('Valid values:') +
+          ' ' +
+          (() => {
+            const choicesAsString = (
+              typeof option.choices === 'function'
+                ? option.choices()
+                : option.choices
+            ).map((t: any) => md.code(t.toString()));
+            return choicesAsString.join(', ');
+          })()
+        : undefined,
+      option.alias?.length
+        ? md.h4('Aliases', md.ul(...option.alias))
+        : undefined,
+    ].filter(isTruthy)
+  );
+}
+
+function getPositionalArgsFragment(
+  positionals: Documentation['positionals'],
+  md: mdfactory
+) {
+  if (positionals?.length === 0) {
+    return undefined;
+  }
+  return md.h2(
+    'Positional Arguments',
+    ...positionals.map((positional) => formatOption(positional, md))
+  );
+}
+
+function getFlagArgsFragment(
+  options: Documentation['options'],
+  label: string,
+  md: mdfactory
+) {
+  if (Object.keys(options).length === 0) {
+    return undefined;
+  }
+  return md.h2(
+    label,
+    ...Object.values(options).map((option) => formatOption(option, md))
+  );
+}
+
+function getSubcommandsFragment(
+  subcommands: Documentation['subcommands'],
+  outdir: string,
+  docsRoot: string,
+  md: mdfactory
+) {
+  if (subcommands.length === 0) {
+    return undefined;
+  }
+  return md.h2(
+    'Subcommands',
+    ...subcommands.map((subcommand) =>
+      md.link(
+        './' +
+          joinPathFragments(
+            normalize(relative(docsRoot, outdir)),
+            subcommand.name + '.md'
+          ),
+        subcommand.name
+      )
+    )
+  );
+}
+
+function isTruthy<T>(value: T | undefined | null): value is T {
+  return !!value;
+}
+
+async function importMarkdownFactory(): Promise<mdfactory> {
+  try {
+    return await import('markdown-factory');
+  } catch {
+    throw new Error(
+      'Could not find markdown-factory. Please install it to generate markdown documentation.'
+    );
+  }
+}
+
+function isCLI(obj: unknown): obj is InternalCLI {
+  if (obj instanceof InternalCLI) {
+    return true;
+  }
+  if (typeof obj !== 'object' || !obj) {
+    return false;
+  }
+  if (!('constructor' in obj)) {
+    return false;
+  }
+  if (!('name' in obj.constructor)) {
+    return false;
+  }
+  return obj.constructor.name === InternalCLI.name;
+}
+
+function getExamplesFragment(
+  examples: string[],
+  md: typeof import('markdown-factory')
+): string | undefined {
+  if (examples.length === 0) {
+    return undefined;
+  }
+  return md.h2(
+    'Examples',
+    ...examples.map((example) => md.codeBlock(example, 'shell'))
+  );
+}
+
+/**
+ * Reads the CLI instance from the provided module. For some reason,
+ * when importing a module that uses `export default` in typescript
+ * the default export is nested under a `default` property on the module...
+ * We for code that looks like `export default 5`, on import we get back
+ * `{ default: {default: 5}}`. To work around this, and make things work
+ * we try to read the CLI instance from the module in a few different ways.
+ *
+ * @param cliModule The imported module
+ * @param exportSpecifier The name of the export to read the CLI from. Defaults to `default`.
+ * @returns A CLI instance.
+ */
+function readCLIFromModule(
+  cliModule: any,
+  args: GenerateDocsArgs
+): InternalCLI {
+  let cli = cliModule;
+  if (args.export) {
+    cli = cliModule[args.export] ?? cliModule['default']?.[args.export];
+  } else {
+    cli =
+      cliModule['default']?.['default'] ?? cliModule['default'] ?? cliModule;
+  }
+  if (!isCLI(cli)) {
+    throw new Error(
+      `${args.cli}${args.export ? '#' + args.export : ''} is not a CLI.`
+    );
+  }
+  return cli;
+}
+
+/**
+ * Detects whether a file should be loaded as ESM or CJS.
+ * Checks file extension first (.mjs/.mts = ESM, .cjs/.cts = CJS),
+ * then falls back to the nearest package.json's "type" field.
+ */
+function detectModuleType(filePath: string): 'esm' | 'cjs' {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+
+  // Explicit extensions take precedence
+  if (ext === 'mjs' || ext === 'mts') {
+    return 'esm';
+  }
+  if (ext === 'cjs' || ext === 'cts') {
+    return 'cjs';
+  }
+
+  // Find nearest package.json and check "type" field
+  const absolutePath = isAbsolute(filePath)
+    ? filePath
+    : join(process.cwd(), filePath);
+  let dir = dirname(absolutePath);
+  const root = dirname(dir);
+
+  while (dir !== root) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.type === 'module' ? 'esm' : 'cjs';
+      } catch {
+        // Ignore parse errors, continue searching
+      }
+    }
+    dir = dirname(dir);
+  }
+
+  // Default to CJS (Node.js default)
+  return 'cjs';
+}
+
+async function loadCLIModule(
+  args: ArgumentsOf<typeof withGenerateDocumentationArgs>
+) {
+  if (isAbsolute(args.cli)) {
+    args.cli = relative(process.cwd(), args.cli);
+  }
+
+  const cliPath = [
+    args.cli,
+    `${args.cli}.ts`,
+    `${args.cli}.js`,
+    `${args.cli}.cjs`,
+    `${args.cli}.mjs`,
+    join(args.cli, 'index.ts'),
+    join(args.cli, 'index.js'),
+    join(args.cli, 'index.cjs'),
+    join(args.cli, 'index.mjs'),
+  ].find((f) => {
+    const p = isAbsolute(f) ? f : join(process.cwd(), f);
+    console.log('Checking for CLI at', p);
+    return existsSync(p);
+  });
+
+  if (!cliPath) {
+    throw new Error(`Could not find CLI module at ${args.cli}
+
+      Ensure that the path is correct and that the CLI module exists.`);
+  }
+
+  const moduleType = detectModuleType(cliPath);
+
+  try {
+    if (moduleType === 'esm') {
+      const tsx = (await import('tsx/esm/api')) as typeof import('tsx/esm/api');
+      return tsx.tsImport(cliPath, {
+        tsconfig: args.tsconfig,
+        parentURL: pathToFileURL(
+          join(process.cwd(), 'fake-file-for-import.ts')
+        ).toString(),
+      });
+    } else {
+      const tsx = (await import('tsx/cjs/api')) as typeof import('tsx/cjs/api');
+      return tsx.require(cliPath, join(process.cwd(), 'fake-file-for-require.ts'));
+    }
+  } catch {
+    try {
+      return await import(cliPath);
+    } catch (e) {
+      if (cliPath.endsWith('.ts')) {
+        console.warn(
+          '[cli-forge]: Generating docs for a typescript CLI requires installing `tsx` as a dev dependency, targeting the build artifacts instead, or otherwise registering a typescript loader with node.'
+        );
+      }
+      throw e;
+    }
+  }
+}
+
+function getEpilogueFragment(
+  epilogue: string | undefined,
+  md: typeof import('markdown-factory')
+) {
+  if (!epilogue) {
+    return undefined;
+  }
+  return md.blockQuote(epilogue);
+}
+
+function renderDefaultValueSection(defaultValue: unknown, md: mdfactory) {
+  const json = JSON.stringify(defaultValue, null, 2);
+  if (json.split('\n').length > 1) {
+    return md.lines(md.bold('Default:'), md.codeBlock(json, 'json'));
+  } else {
+    return md.bold('Default:') + ' ' + md.code(json);
+  }
+}