@config-bound/cli 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @config-bound/cli
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [87d2ab6]
+  - @config-bound/core@1.0.0
+  - @config-bound/schema-export@0.1.3
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robert Keyser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@config-bound/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for ConfigBound schema export and management",
   "keywords": [
     "cli",
@@ -17,46 +17,52 @@
   },
   "main": "./dist/main.js",
   "types": "./dist/main.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "clean": "rimraf dist coverage .turbo",
-    "dev": "tsx src/main.ts",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
-    "test:dev": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
-    "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage",
-    "lint": "eslint src/**/*.ts --fix",
-    "lint:ci": "eslint src/**/*.ts",
-    "format": "prettier --write --config ../../.config/.prettierrc --ignore-path ../../.config/.prettierignore src/**/*.ts",
-    "format:ci": "prettier --check --config ../../.config/.prettierrc --ignore-path ../../.config/.prettierignore src/**/*.ts"
-  },
   "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",
     "reflect-metadata": "^0.2.2",
     "ts-morph": "^24.0.0",
-    "tsx": "^4.20.6"
+    "tsx": "^4.20.6",
+    "@config-bound/core": "1.0.0",
+    "@config-bound/schema-export": "0.1.3"
   },
   "devDependencies": {
-    "@config-bound/eslint-config": "*",
+    "@nestjs/testing": "^11.1.18",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.10.1",
+    "@types/node": "^24.10.0",
     "eslint": "^9.39.1",
     "jest": "^30.2.0",
-    "rimraf": "^6.1.2",
+    "markdown-table": "^3.0.4",
+    "rimraf": "^6.1.0",
     "ts-jest": "^29.4.5",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.0",
+    "@config-bound/eslint-config": "0.0.0",
+    "@config-bound/typescript-config": "0.0.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/notr-ai/ConfigBound"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist coverage .turbo",
+    "dev": "tsx src/main.ts",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:dev": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
+    "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage",
+    "lint": "eslint src/**/*.ts --fix",
+    "lint:ci": "eslint src/**/*.ts",
+    "format": "prettier --write --config ../../.config/.prettierrc --ignore-path ../../.config/.prettierignore src/**/*.ts",
+    "format:ci": "prettier --check --config ../../.config/.prettierrc --ignore-path ../../.config/.prettierignore src/**/*.ts"
   }
-}
+}

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.core.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 {}