@config-bound/cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @config-bound/cli
 
+## 0.2.0
+
+### Minor Changes
+
+- f2299f6: Add `configbound generate bind` command
+
+  Scaffolds the boilerplate for a new custom bind — either as an embedded TypeScript class or a publishable npm package. Handles class structure, static `create()` factory, and cache setup so you can focus on the implementation.
+
+### Patch Changes
+
+- Updated dependencies [02b3369]
+- Updated dependencies [ac54dea]
+- Updated dependencies [0f899ee]
+  - @config-bound/config-bound@0.2.0
+  - @config-bound/schema-export@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@config-bound/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI tool for ConfigBound schema export and management",
   "keywords": [
     "cli",
@@ -32,8 +32,8 @@
   "dependencies": {
     "@config-bound/config-bound": "*",
     "@config-bound/schema-export": "*",
-    "@nestjs/common": "^10.4.15",
-    "@nestjs/core": "^10.4.15",
+    "@nestjs/common": "^11.1.18",
+    "@nestjs/core": "^11.1.18",
     "chalk": "^4.1.2",
     "esbuild-register": "^3.6.0",
     "nest-commander": "^3.15.0",
@@ -43,13 +43,15 @@
   },
   "devDependencies": {
     "@config-bound/eslint-config": "*",
+    "@nestjs/testing": "^11.1.18",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
     "eslint": "^9.39.1",
     "jest": "^30.2.0",
+    "markdown-table": "^3.0.4",
     "rimraf": "^6.1.2",
     "ts-jest": "^29.4.5",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.0"
   },
   "publishConfig": {
     "access": "public",

package/scripts/generate-docs.ts

@@ -0,0 +1,362 @@
+/**
+ * Generates CLI reference documentation for the docs site.
+ *
+ * WHAT IT DOES:
+ * Boots the Nest CLI application, extracts command metadata from
+ * registered CommandRunner instances, and generates markdown reference pages
+ * combining authored prose with derived options tables.
+ *
+ * DEPENDENCIES:
+ * - @config-bound/cli package with Nest application and command runners
+ * - apps/cli/src/cli.module.ts and command classes
+ *
+ * OUTPUT:
+ * - apps/docs/reference/cli/*.md (index, list, export, generate-bind)
+ *
+ * RUN VIA:
+ * npm run docs:cli (from repo root)
+ */
+
+import 'reflect-metadata';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { markdownTable } from 'markdown-table';
+import { CommandFactory } from 'nest-commander';
+import { CliModule } from '../src/cli.module.js';
+import { ExportCommand } from '../src/commands/export.command.js';
+import { ListCommand } from '../src/commands/list.command.js';
+import { GenerateBindCommand } from '../src/commands/generate-bind.command.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+interface CommanderOption {
+  flags: string;
+  description: string;
+  defaultValue: unknown;
+  hidden: boolean;
+  long: string;
+}
+
+interface CommandRunner {
+  command: { options: CommanderOption[] };
+}
+
+/**
+ * A page definition. `sections` is authored prose; `optionsHeading` marks where
+ * the derived options table is injected. Pages without options omit the heading.
+ */
+interface PageSpec {
+  filename: string;
+  frontmatterDescription: string;
+  title: string;
+  intro: string;
+  usage: string;
+  positionalArgs?: { name: string; description: string; default?: string }[];
+  /** Heading text under which the derived options table is rendered. */
+  optionsHeading: string;
+  sections: { heading: string; body: string }[];
+  related: { text: string; link: string }[];
+}
+
+// ─── Rendering ─────────────────────────────────────────────────────────────
+
+const SCRIPT_NAME = 'generate-docs';
+const GENERATED_NOTICE = `<!-- This file is generated by scripts/generate-cli-docs.mjs. Do not edit it directly. -->`;
+
+function renderOptionsTable(options: CommanderOption[]): string {
+  const visible = options.filter(
+    (opt) => !opt.hidden && opt.long !== '--help' && opt.long !== '--version',
+  );
+
+  const rows = visible.map((opt) => [
+    `\`${opt.flags}\``,
+    opt.description,
+    opt.defaultValue !== undefined && opt.defaultValue !== null
+      ? `\`${String(opt.defaultValue)}\``
+      : '—'
+  ]);
+
+  return markdownTable([
+    ['Flag', 'Description', 'Default'],
+    ...rows
+  ]);
+}
+
+function renderPage(spec: PageSpec, runner: CommandRunner | null): string {
+  const parts: string[] = [
+    `---\ndescription: ${spec.frontmatterDescription}\n---`,
+    GENERATED_NOTICE,
+    `# ${spec.title}`,
+    spec.intro,
+    `## Usage\n\n\`\`\`text\n${spec.usage}\n\`\`\``,
+  ];
+
+  if (spec.positionalArgs && spec.positionalArgs.length > 0) {
+    const rows = spec.positionalArgs.map((a) => [
+      `\`${a.name}\``,
+      a.description,
+      a.default ?? 'Required'
+    ]);
+    const argsTable = markdownTable([
+      ['Argument', 'Description', 'Default'],
+      ...rows
+    ]);
+    parts.push(`### Arguments\n\n${argsTable}`);
+  }
+
+  if (runner) {
+    parts.push(`### ${spec.optionsHeading}\n\n${renderOptionsTable(runner.command.options)}`);
+  }
+
+  for (const section of spec.sections) {
+    parts.push(`## ${section.heading}\n\n${section.body}`);
+  }
+
+  if (spec.related.length > 0) {
+    const links = spec.related.map((r) => `- [${r.text}](${r.link})`).join('\n');
+    parts.push(`## Related\n\n${links}`);
+  }
+
+  return parts.join('\n\n');
+}
+
+// ─── Page definitions ───────────────────────────────────────────────────────
+// Authored prose lives here. Derived content (options tables) is injected at
+// render time from the live CommandRunner instances.
+
+const INDEX_PAGE = `---
+description: The ConfigBound CLI provides tools to discover, inspect, and export configuration schemas without writing code.
+---
+
+${GENERATED_NOTICE}
+
+# CLI
+
+The \`@config-bound/cli\` package provides the \`configbound\` command — a set of tools for working with ConfigBound configurations from the terminal.
+
+## Installation
+
+\`\`\`bash
+npm install --save-dev @config-bound/cli
+\`\`\`
+
+After installation, \`npx configbound\` runs the CLI. For global use:
+
+\`\`\`bash
+npm install --global @config-bound/cli
+\`\`\`
+
+## Commands
+
+| Command | Description |
+| ------- | ----------- |
+| [\`configbound list\`](./list) | Discover and display all ConfigBound configurations in a directory tree |
+| [\`configbound export\`](./export) | Export a configuration schema to JSON, YAML, or \`.env\` format |
+| [\`configbound generate bind\`](./generate-bind) | Scaffold a new bind — embedded class or publishable package |
+
+## How discovery works
+
+\`list\` and \`export\` both use config discovery — scanning source files for ConfigBound configurations. Discovery reads the actual exports from your TypeScript files. No separate manifest or registration step is required.
+
+\`export\` auto-selects a config when only one is found. When multiple configs exist in the same project, it prompts for selection. Pass \`--config\` and \`--name\` explicitly to skip discovery entirely.
+
+## CLI vs. library
+
+The CLI is a companion to the library, not a replacement for it. Schema definition, validation, and value resolution all happen in code. The CLI's job is to inspect what the library produces — listing what configs exist and exporting their schemas as artifacts.`;
+
+const LIST_SPEC: PageSpec = {
+  filename: 'list.md',
+  frontmatterDescription:
+    'Discover and display all ConfigBound configurations in a project using configbound list.',
+  title: 'configbound list',
+  intro:
+    '`list` scans a directory tree for ConfigBound configurations and prints what it finds, grouped by file.\n\nUse it to confirm that discovery works correctly, or to get the exact file paths and export names needed for `configbound export --config ... --name ...`.',
+  usage: 'configbound list [path] [options]',
+  positionalArgs: [{ name: 'path', description: 'Directory to search', default: 'Current working directory' }],
+  optionsHeading: 'Options',
+  sections: [
+    {
+      heading: 'Examples',
+      body: `\`\`\`bash
+# List all configs in the current project
+configbound list
+
+# Search a specific directory
+configbound list ./src
+
+# Search non-recursively
+configbound list --recursive false
+\`\`\``,
+    },
+    {
+      heading: 'Output',
+      body: `Results are grouped by file. Each entry shows the export name, whether it is a default or named export, the config's display name if set, and the line number:
+
+\`\`\`text
+📄 src/config/app.config.ts
+   default (default) - My App Config :42
+
+📄 src/config/db.config.ts
+   default (default) - Database Config :18
+   dbConfig (named) - Database Config (read-only) :67
+\`\`\`
+
+When a file has multiple exports, each is listed separately. Use the export name with \`--name\` when running \`export\`:
+
+\`\`\`bash
+configbound export --config src/config/db.config.ts --name dbConfig
+\`\`\``,
+    },
+  ],
+  related: [{ text: '`configbound export`', link: './export' }],
+};
+
+const EXPORT_SPEC: PageSpec = {
+  filename: 'export.md',
+  frontmatterDescription:
+    'Export a ConfigBound configuration schema to JSON, YAML, or .env format using configbound export.',
+  title: 'configbound export',
+  intro:
+    '`export` loads a ConfigBound configuration and serializes its schema to JSON, YAML, or `.env` format. The output goes to stdout by default, or to a file with `--output`.\n\nThis is the CLI surface for schema export. For the programmatic equivalent, see [Export your configuration schema](/how-to/schema-export). For why schema export matters, see [Schema as the Source of Truth](/explanation/schema-source-of-truth).',
+  usage: 'configbound export [options]',
+  optionsHeading: 'Options',
+  sections: [
+    {
+      heading: 'Discovery',
+      body: `When \`--config\` is omitted, \`export\` scans the current directory for ConfigBound configurations:
+
+- One config found: selected automatically.
+- Multiple configs found: a numbered menu is displayed and you choose.
+- No configs found: the command exits and suggests using \`--config\`.
+
+Pass \`--config\` to skip discovery entirely. When the file has more than one export, also pass \`--name\` to identify which one to export.`,
+    },
+    {
+      heading: 'Examples',
+      body: `\`\`\`bash
+# Auto-discover and export to stdout as JSON
+configbound export
+
+# Export a specific file as YAML
+configbound export --config ./src/config/app.config.ts --format yaml
+
+# Write JSON output to a file
+configbound export --output ./docs/schema.json
+
+# Named export from a file with multiple configs
+configbound export --config ./src/config/all.ts --name databaseConfig
+
+# Generate a .env file including normally-omitted elements
+configbound export --format env --include-omitted --output .env.example
+\`\`\``,
+    },
+    {
+      heading: 'Omitted elements',
+      body: 'Elements defined with `omitFromSchema: true` are excluded from exported output by default. The intent is to keep sensitive or internal fields out of generated artifacts. Pass `--include-omitted` to override this — useful when generating a complete `.env.example` for onboarding or local development.',
+    },
+  ],
+  related: [
+    { text: '`configbound list`', link: './list' },
+    { text: 'Export your configuration schema', link: '/how-to/schema-export' },
+    { text: 'Schema as the Source of Truth', link: '/explanation/schema-source-of-truth' },
+  ],
+};
+
+const GENERATE_BIND_SPEC: PageSpec = {
+  filename: 'generate-bind.md',
+  frontmatterDescription: 'Scaffold a new custom bind using configbound generate bind.',
+  title: 'configbound generate bind',
+  intro:
+    '`generate bind` scaffolds the boilerplate for a new bind. It handles the repetitive parts — class structure, factory pattern, cache setup — so you can focus on the implementation.',
+  usage: 'configbound generate bind <name> [options]',
+  positionalArgs: [
+    { name: 'name', description: 'The bind name in kebab-case (e.g. `vault`, `aws-ssm`, `1password`)', default: 'Required' },
+  ],
+  optionsHeading: 'Options',
+  sections: [
+    {
+      heading: 'Generation modes',
+      body: `**\`embedded\`** generates a single TypeScript class file. The bind lives in your project and is not published. Use this when the bind is specific to one application.
+
+**\`package\`** generates a full npm package scaffold: \`package.json\`, \`tsconfig.json\`, \`eslint.config.mjs\`, and a \`src/\` directory containing the bind class and an index. Use this when you intend to publish the bind for others to use.`,
+    },
+    {
+      heading: 'Examples',
+      body: `\`\`\`bash
+# Interactive — prompts for embedded or package
+configbound generate bind vault
+
+# Non-interactive embedded bind
+configbound generate bind vault --type embedded
+
+# Non-interactive package scaffold
+configbound generate bind aws-ssm --type package
+
+# Preview what would be generated without writing anything
+configbound generate bind 1password --type package --dry-run
+\`\`\``,
+    },
+    {
+      heading: 'What gets generated',
+      body: `Both modes produce a class that extends \`Bind\` with a static async \`create()\` factory and a synchronous \`retrieve()\` method. The generated code includes inline comments explaining what to fill in.
+
+The factory pattern pre-loads values into a cache at startup. \`retrieve()\` reads from that cache synchronously. This satisfies the \`Bind\` contract without requiring changes to the core library.`,
+    },
+    {
+      heading: 'Name derivation',
+      body: 'The kebab-case name you provide is used to derive the class name. `vault` becomes `VaultBind`. `aws-ssm` becomes `AwsSsmBind`. Leading digits are replaced with words: `1password` becomes `OnepasswordBind`.',
+    },
+  ],
+  related: [
+    { text: 'Create a custom bind', link: '/how-to/custom-bind' },
+    {
+      text: '`Bind` API reference',
+      link: '/reference/api/@config-bound.config-bound.bind.bind.Class.Bind',
+    },
+  ],
+};
+
+// ─── Main ──────────────────────────────────────────────────────────────────
+
+function writeDocFile(outDir: string, filename: string, content: string): void {
+  writeFileSync(resolve(outDir, filename), content + '\n', 'utf-8');
+  console.log(`  generated: reference/cli/${filename}`);
+}
+
+async function main(): Promise<void> {
+  // Optional output directory override (defaults to apps/docs/reference/cli).
+  // Used for custom builds or testing. Normal builds use the default.
+  const outDir = process.argv[2] ?? resolve(import.meta.dirname, '../../apps/docs/reference/cli');
+
+  const app = await CommandFactory.createWithoutRunning(CliModule, { logger: false });
+
+  const listRunner = app.get(ListCommand) as CommandRunner;
+  const exportRunner = app.get(ExportCommand) as CommandRunner;
+  const generateBindRunner = app.get(GenerateBindCommand) as CommandRunner;
+
+  if (!listRunner?.command?.options) {
+    throw new Error(`[${SCRIPT_NAME}] Failed to retrieve ListCommand with valid options`);
+  }
+  if (!exportRunner?.command?.options) {
+    throw new Error(`[${SCRIPT_NAME}] Failed to retrieve ExportCommand with valid options`);
+  }
+  if (!generateBindRunner?.command?.options) {
+    throw new Error(`[${SCRIPT_NAME}] Failed to retrieve GenerateBindCommand with valid options`);
+  }
+
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  console.log(`[${SCRIPT_NAME}] Generating CLI reference docs...`);
+  writeDocFile(outDir, 'index.md', INDEX_PAGE);
+  writeDocFile(outDir, LIST_SPEC.filename, renderPage(LIST_SPEC, listRunner));
+  writeDocFile(outDir, EXPORT_SPEC.filename, renderPage(EXPORT_SPEC, exportRunner));
+  writeDocFile(outDir, GENERATE_BIND_SPEC.filename, renderPage(GENERATE_BIND_SPEC, generateBindRunner));
+  console.log(`[${SCRIPT_NAME}] Done.`);
+
+  await app.close();
+}
+
+main().catch((err: unknown) => {
+  console.error(`[${SCRIPT_NAME}] Unexpected error:`, err);
+  process.exit(1);
+});

package/src/cli.module.ts

@@ -1,19 +1,25 @@
 import { Module } from '@nestjs/common';
 import { ListCommand } from './commands/list.command.js';
 import { ExportCommand } from './commands/export.command.js';
+import { GenerateCommand } from './commands/generate.command.js';
+import { GenerateBindCommand } from './commands/generate-bind.command.js';
 import { ConfigDiscoveryService } from './services/config-discovery.service.js';
 import { ConfigLoaderService } from './services/config-loader.service.js';
 import { SchemaExportService } from './services/schema-export.service.js';
 import { FileWriterService } from './services/file-writer.service.js';
+import { BindGeneratorService } from './services/bind-generator.service.js';
 
 @Module({
   providers: [
     ListCommand,
     ExportCommand,
+    GenerateCommand,
+    GenerateBindCommand,
     ConfigDiscoveryService,
     ConfigLoaderService,
     SchemaExportService,
-    FileWriterService
+    FileWriterService,
+    BindGeneratorService
   ]
 })
 export class CliModule {}

package/src/commands/generate-bind.command.ts

@@ -0,0 +1,175 @@
+import { Command, CommandRunner, Option } from 'nest-commander';
+import {
+  BindGeneratorService,
+  type BindGeneratorMode,
+  type BindNames
+} from '../services/bind-generator.service.js';
+import chalk from 'chalk';
+import * as readline from 'readline';
+import * as path from 'path';
+
+interface GenerateBindCommandOptions {
+  output?: string;
+  type?: BindGeneratorMode;
+  dryRun?: boolean;
+}
+
+@Command({
+  name: 'bind',
+  description: 'Scaffold a new bind',
+  arguments: '<name>',
+  argsDescription: {
+    name: 'The bind name in kebab-case (e.g. 1password, vault, aws-ssm)'
+  }
+})
+export class GenerateBindCommand extends CommandRunner {
+  constructor(private readonly generatorService: BindGeneratorService) {
+    super();
+  }
+
+  async run(
+    [name]: string[],
+    options?: GenerateBindCommandOptions
+  ): Promise<void> {
+    if (!name) {
+      this.command.error(
+        'bind name is required.\nUsage: configbound generate bind <name>'
+      );
+    }
+
+    const names = this.generatorService.deriveNames(name);
+    const outputDir = options?.output
+      ? path.resolve(options.output)
+      : process.cwd();
+
+    const mode: BindGeneratorMode = options?.type ?? (await this.promptMode());
+
+    const files = this.generatorService.renderFiles(names, mode);
+
+    if (options?.dryRun) {
+      console.log(chalk.blue('\nFiles that would be generated:\n'));
+      for (const file of files) {
+        const fullPath = path.join(outputDir, file.relativePath);
+        console.log(chalk.cyan(`  ${fullPath}`));
+        console.log(chalk.gray('  ' + '─'.repeat(60)));
+        console.log(
+          file.content
+            .split('\n')
+            .map((line) => chalk.gray(`  ${line}`))
+            .join('\n')
+        );
+        console.log();
+      }
+      console.log(chalk.yellow('Dry run — no files written.'));
+      return;
+    }
+
+    console.log(
+      chalk.blue(
+        `\nGenerating ${mode === 'package' ? 'community bind package' : 'embedded bind class'} for ${chalk.bold(names.pascal)}...\n`
+      )
+    );
+
+    this.generatorService.writeFiles(files, outputDir);
+
+    console.log(chalk.green('Done! Generated files:'));
+    for (const file of files) {
+      console.log(chalk.cyan(`  ${path.join(outputDir, file.relativePath)}`));
+    }
+
+    this.printNextSteps(names, mode, outputDir);
+  }
+
+  private async promptMode(): Promise<BindGeneratorMode> {
+    console.log(chalk.blue('\nWhat would you like to generate?\n'));
+    console.log(
+      `  ${chalk.cyan('1.')} Community bind package ${chalk.gray('(package.json, tsconfig, src/) — standalone, publishable to npm')}`
+    );
+    console.log(
+      `  ${chalk.cyan('2.')} Embedded bind class file ${chalk.gray('— lives in your project, not published')}`
+    );
+
+    while (true) {
+      const answer = await new Promise<string>((resolve) => {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        rl.question(chalk.yellow('\nSelect (1 or 2): '), (ans) => {
+          rl.close();
+          resolve(ans.trim());
+        });
+      });
+
+      if (answer === '1') return 'package';
+      if (answer === '2') return 'embedded';
+
+      console.log(chalk.red('  Invalid selection. Please enter 1 or 2.'));
+    }
+  }
+
+  private printNextSteps(
+    names: BindNames,
+    mode: BindGeneratorMode,
+    outputDir: string
+  ): void {
+    console.log(chalk.blue('\nNext steps:\n'));
+
+    if (mode === 'package') {
+      const packageDir = path.join(outputDir, `bind-${names.kebab}`);
+      console.log(
+        `  ${chalk.cyan('1.')} Add your SDK dependency to ${chalk.bold(path.join(packageDir, 'package.json'))}`
+      );
+      console.log(
+        `  ${chalk.cyan('2.')} Fill in the ${chalk.bold(`create()`)} method in ${chalk.bold(path.join(packageDir, 'src', `${names.pascal}Bind.ts`))}`
+      );
+      console.log(
+        `  ${chalk.cyan('3.')} Run ${chalk.bold('npm install')} in the package directory`
+      );
+      console.log(
+        `  ${chalk.cyan('4.')} When ready to publish, set ${chalk.bold('"private": false')} in package.json`
+      );
+    } else {
+      const classFile = path.join(outputDir, `${names.pascal}Bind.ts`);
+      console.log(
+        `  ${chalk.cyan('1.')} Add your SDK to your project's dependencies`
+      );
+      console.log(
+        `  ${chalk.cyan('2.')} Fill in the ${chalk.bold(`create()`)} method in ${chalk.bold(classFile)}`
+      );
+      console.log(
+        `  ${chalk.cyan('3.')} Pass an instance to ${chalk.bold('ConfigBound.createConfig(..., { binds: [bind] })')}`
+      );
+    }
+
+    console.log();
+  }
+
+  @Option({
+    flags: '-o, --output <dir>',
+    description: 'Output directory (default: current directory)'
+  })
+  parseOutput(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--type <type>',
+    description:
+      'Generation mode: package or embedded (skips interactive prompt)'
+  })
+  parseType(val: string): BindGeneratorMode {
+    if (val !== 'package' && val !== 'embedded') {
+      throw new Error(`Invalid type: ${val}. Must be "package" or "embedded".`);
+    }
+    return val;
+  }
+
+  @Option({
+    flags: '--dry-run',
+    description: 'Preview generated files without writing'
+  })
+  parseDryRun(): boolean {
+    return true;
+  }
+}

package/src/commands/generate.command.ts

@@ -0,0 +1,13 @@
+import { Command, CommandRunner } from 'nest-commander';
+import { GenerateBindCommand } from './generate-bind.command.js';
+
+@Command({
+  name: 'generate',
+  description: 'Generate new ConfigBound components',
+  subCommands: [GenerateBindCommand]
+})
+export class GenerateCommand extends CommandRunner {
+  async run(): Promise<void> {
+    this.command.help();
+  }
+}