@config-bound/cli 0.1.0 → 0.2.1

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();
+  }
+}

package/src/services/bind-generator.service.ts

@@ -0,0 +1,248 @@
+import { Injectable } from '@nestjs/common';
+import * as path from 'path';
+import { FileWriterService } from './file-writer.service.js';
+
+const DIGIT_WORDS = new Map([
+  ['1', 'One'],
+  ['2', 'Two'],
+  ['3', 'Three'],
+  ['4', 'Four'],
+  ['5', 'Five'],
+  ['6', 'Six'],
+  ['7', 'Seven'],
+  ['8', 'Eight'],
+  ['9', 'Nine'],
+  ['10', 'Ten']
+]);
+
+function digitWordsPrefix(digits: string): string {
+  return DIGIT_WORDS.get(digits) ?? `N${digits}`;
+}
+
+export type BindGeneratorMode = 'package' | 'embedded';
+
+export interface BindNames {
+  kebab: string;
+  pascal: string;
+}
+
+export interface GeneratedFile {
+  relativePath: string;
+  content: string;
+}
+
+@Injectable()
+export class BindGeneratorService {
+  constructor(private readonly fileWriter: FileWriterService) {}
+
+  deriveNames(input: string): BindNames {
+    const kebab = input
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+
+    const pascal = kebab
+      .split('-')
+      .map((part) => {
+        // Handle numeric-leading segments (e.g. "1password" → "OnePassword")
+        const withoutLeadingDigits = part.replace(/^\d+/, digitWordsPrefix);
+        return (
+          withoutLeadingDigits.charAt(0).toUpperCase() +
+          withoutLeadingDigits.slice(1)
+        );
+      })
+      .join('');
+
+    return { kebab, pascal };
+  }
+
+  renderFiles(names: BindNames, mode: BindGeneratorMode): GeneratedFile[] {
+    if (mode === 'embedded') {
+      return [
+        {
+          relativePath: `${names.pascal}Bind.ts`,
+          content: this.renderBindClass(names)
+        }
+      ];
+    }
+
+    const packageDir = `bind-${names.kebab}`;
+    return [
+      {
+        relativePath: path.join(packageDir, 'src', `${names.pascal}Bind.ts`),
+        content: this.renderBindClass(names)
+      },
+      {
+        relativePath: path.join(packageDir, 'src', 'index.ts'),
+        content: this.renderIndex(names)
+      },
+      {
+        relativePath: path.join(packageDir, 'package.json'),
+        content: this.renderPackageJson(names)
+      },
+      {
+        relativePath: path.join(packageDir, 'tsconfig.json'),
+        content: this.renderTsConfig()
+      },
+      {
+        relativePath: path.join(packageDir, 'eslint.config.mjs'),
+        content: this.renderEslintConfig()
+      }
+    ];
+  }
+
+  writeFiles(files: GeneratedFile[], outputDir: string): void {
+    for (const file of files) {
+      const fullPath = path.join(outputDir, file.relativePath);
+      this.fileWriter.writeToFile(fullPath, file.content);
+    }
+  }
+
+  private renderBindClass(names: BindNames): string {
+    return `import { Bind } from '@config-bound/core/bind';
+
+/**
+ * Options for constructing a ${names.pascal}Bind.
+ * Add the SDK client / credential options for ${names.pascal} here.
+ */
+export interface ${names.pascal}BindOptions {
+  // e.g. token?: string; endpoint?: string;
+}
+
+/**
+ * A {@link Bind} that retrieves values from ${names.pascal}.
+ *
+ * Uses a static factory method ({@link ${names.pascal}Bind.create}) to pre-load all values
+ * into an in-memory map at startup, so that {@link ${names.pascal}Bind.retrieve} reads
+ * from memory without making additional network calls.
+ *
+ * @example
+ * \`\`\`typescript
+ * const bind = await ${names.pascal}Bind.create({ token: process.env.${names.kebab.toUpperCase().replace(/-/g, '_')}_TOKEN });
+ * const config = ConfigBound.createConfig(schema, { binds: [bind] });
+ * \`\`\`
+ */
+export class ${names.pascal}Bind extends Bind {
+  private readonly values: Map<string, unknown>;
+
+  private constructor(values: Map<string, unknown>) {
+    super('${names.pascal}');
+    this.values = values;
+  }
+
+  /**
+   * Creates a ${names.pascal}Bind by pre-loading values from the source.
+   *
+   * Call this once at application startup and pass the returned instance to
+   * \`ConfigBound.createConfig\`.
+   */
+  static async create(_options: ${names.pascal}BindOptions): Promise<${names.pascal}Bind> {
+    const values = new Map<string, unknown>();
+
+    // TODO: Initialize the SDK client using \`options\`, fetch values, and
+    // populate \`values\` with entries keyed by the full element path
+    // (format: "sectionName.elementName"). For example:
+    //
+    //   const client = new SdkClient(options);
+    //   const secrets = await client.listValues();
+    //   for (const secret of secrets) {
+    //     values.set(secret.path, secret.data);
+    //   }
+    return new ${names.pascal}Bind(values);
+  }
+
+  async retrieve<T>(elementName: string): Promise<T | undefined> {
+    return this.values.get(elementName) as T | undefined;
+  }
+}
+`;
+  }
+
+  private renderIndex(names: BindNames): string {
+    return `export { ${names.pascal}Bind, type ${names.pascal}BindOptions } from './${names.pascal}Bind.js';
+`;
+  }
+
+  private renderPackageJson(names: BindNames): string {
+    return `{
+  "name": "configbound-bind-${names.kebab}",
+  "version": "0.1.0",
+  "description": "${names.pascal} bind for ConfigBound",
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts --fix",
+    "lint:ci": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "format:ci": "prettier --check src/**/*.ts"
+  },
+  "keywords": ["configbound", "config", "${names.kebab}"],
+  "license": "MIT",
+  "dependencies": {
+    "@config-bound/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.0.0",
+    "jest": "^30.0.0",
+    "rimraf": "^6.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^6.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}
+`;
+  }
+
+  private renderTsConfig(): string {
+    return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+}
+`;
+  }
+
+  private renderEslintConfig(): string {
+    return `import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  { ignores: ['**/dist/**', '**/node_modules/**'] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+];
+`;
+  }
+}

package/src/services/config-discovery.service.spec.ts

@@ -45,7 +45,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config.ts',
       `
-      import { ConfigBound } from '@config-bound/config-bound';
+      import { ConfigBound } from '@config-bound/core';
       
       export const appConfig = ConfigBound.createConfig({
         name: 'MyApp',
@@ -66,7 +66,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       
       export const dbConfig = createConfig({
         name: 'Database',
@@ -86,7 +86,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config.ts',
       `
-      import { ConfigBound } from '@config-bound/config-bound';
+      import { ConfigBound } from '@config-bound/core';
       
       export default ConfigBound.createConfig({
         name: 'DefaultConfig',
@@ -107,7 +107,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'configs.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       
       export const config1 = createConfig({ name: 'Config1', sections: {} });
       export const config2 = createConfig({ name: 'Config2', sections: {} });
@@ -126,7 +126,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config1.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       export const config1 = createConfig({ name: 'Config1', sections: {} });
     `
     );
@@ -134,7 +134,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'subdir/config2.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       export const config2 = createConfig({ name: 'Config2', sections: {} });
     `
     );
@@ -148,7 +148,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config1.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       export const config1 = createConfig({ name: 'Config1', sections: {} });
     `
     );
@@ -156,7 +156,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'subdir/config2.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       export const config2 = createConfig({ name: 'Config2', sections: {} });
     `
     );
@@ -170,7 +170,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       const privateConfig = createConfig({ name: 'Private', sections: {} });
     `
     );
@@ -184,7 +184,7 @@ describe('ConfigDiscoveryService', () => {
     createTempFile(
       'config.spec.ts',
       `
-      import { createConfig } from '@config-bound/config-bound';
+      import { createConfig } from '@config-bound/core';
       export const testConfig = createConfig({ name: 'Test', sections: {} });
     `
     );

package/src/services/config-discovery.service.ts

@@ -1,8 +1,9 @@
 import { Injectable } from '@nestjs/common';
 import { Project, Node, SyntaxKind, SourceFile } from 'ts-morph';
 import * as path from 'path';
-import * as fs from 'fs';
-import { ensureError } from '@config-bound/config-bound/utilities';
+import { promises as fs } from 'fs';
+import { glob } from 'node:fs/promises';
+import { ensureError } from '@config-bound/core/utilities';
 
 export interface DiscoveredConfig {
   filePath: string;
@@ -18,7 +19,7 @@ export class ConfigDiscoveryService {
     searchPath: string,
     recursive: boolean = true
   ): Promise<DiscoveredConfig[]> {
-    const tsFiles = this.findTypeScriptFiles(searchPath, recursive);
+    const tsFiles = await this.findTypeScriptFiles(searchPath, recursive);
     const discovered: DiscoveredConfig[] = [];
 
     // Create a single project instance for all files
@@ -171,11 +172,10 @@ export class ConfigDiscoveryService {
     return undefined;
   }
 
-  private findTypeScriptFiles(
+  private async findTypeScriptFiles(
     searchPath: string,
     recursive: boolean
-  ): string[] {
-    const files: string[] = [];
+  ): Promise<string[]> {
     const excludedDirs = new Set([
       'node_modules',
       'dist',
@@ -192,46 +192,31 @@ export class ConfigDiscoveryService {
       'env'
     ]);
 
-    function traverse(dir: string) {
-      let entries;
-      try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-      } catch {
-        // Skip directories we can't read
-        return;
-      }
+    const stats = await fs.stat(searchPath);
+    if (stats.isFile()) {
+      return searchPath.endsWith('.ts') ? [searchPath] : [];
+    }
 
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
+    const pattern = recursive ? '**/*.ts' : '*.ts';
+    const files: string[] = [];
 
-        // Skip excluded directories and hidden directories
-        if (entry.isDirectory()) {
-          if (excludedDirs.has(entry.name) || entry.name.startsWith('.')) {
-            continue;
-          }
-          if (recursive) {
-            traverse(fullPath);
-          }
-        } else if (entry.isFile() && entry.name.endsWith('.ts')) {
-          // Skip test files and declaration files
-          if (
-            !entry.name.endsWith('.spec.ts') &&
-            !entry.name.endsWith('.test.ts') &&
-            !entry.name.endsWith('.d.ts')
-          ) {
-            files.push(fullPath);
-          }
-        }
+    for await (const file of glob(pattern, {
+      cwd: searchPath,
+      exclude: (p) =>
+        p
+          .split(path.sep)
+          .some((part) => excludedDirs.has(part) || part.startsWith('.'))
+    })) {
+      const name = path.basename(file);
+      if (
+        !name.endsWith('.spec.ts') &&
+        !name.endsWith('.test.ts') &&
+        !name.endsWith('.d.ts')
+      ) {
+        files.push(path.join(searchPath, file));
       }
     }
 
-    const stats = fs.statSync(searchPath);
-    if (stats.isDirectory()) {
-      traverse(searchPath);
-    } else if (stats.isFile() && searchPath.endsWith('.ts')) {
-      files.push(searchPath);
-    }
-
     return files;
   }
 }

package/src/services/config-loader.service.ts

@@ -2,10 +2,9 @@ import { Injectable } from '@nestjs/common';
 import * as path from 'path';
 import * as fs from 'fs';
 import { pathToFileURL } from 'url';
-import { Section } from '@config-bound/config-bound/section';
+import { Section } from '@config-bound/core/section';
 import {
   ConfigBound,
-  TypedConfigBound,
   ConfigSchema,
   ConfigLoaderException,
   ConfigFileNotFoundException,
@@ -16,12 +15,12 @@ import {
   InvalidConfigBoundInstanceException,
   ConfigFileParseException,
   MissingDependencyException
-} from '@config-bound/config-bound';
+} from '@config-bound/core';
 
 export interface LoadedConfig {
   name: string;
-  sections: Section[];
-  instance: ConfigBound | TypedConfigBound<ConfigSchema>;
+  sections: ReadonlyArray<Section>;
+  instance: ConfigBound<ConfigSchema>;
 }
 
 @Injectable()
@@ -94,10 +93,7 @@ export class ConfigLoaderService {
       const fileURL = pathToFileURL(fileToLoad).href;
       const module = await import(fileURL);
 
-      let configInstance:
-        | ConfigBound
-        | TypedConfigBound<ConfigSchema>
-        | undefined;
+      let configInstance: ConfigBound<ConfigSchema> | undefined;
 
       if (exportName && exportName !== 'default') {
         configInstance = module[exportName];
@@ -156,9 +152,7 @@ export class ConfigLoaderService {
             );
           }
 
-          configInstance = configExports[0][1] as
-            | ConfigBound
-            | TypedConfigBound<ConfigSchema>;
+          configInstance = configExports[0][1] as ConfigBound<ConfigSchema>;
         } else {
           // exportName === 'default' was explicitly requested, so use it even if invalid
           configInstance = defaultExport;
@@ -320,9 +314,7 @@ export class ConfigLoaderService {
           exportName !== 'default' &&
           this.isConfigBoundInstance(exportValue)
         ) {
-          const typedValue = exportValue as
-            | ConfigBound
-            | TypedConfigBound<ConfigSchema>;
+          const typedValue = exportValue as ConfigBound<ConfigSchema>;
           configs.set(exportName, {
             name: typedValue.name,
             sections: typedValue.sections,
@@ -365,7 +357,7 @@ export class ConfigLoaderService {
 
   private isConfigBoundInstance(
     value: unknown
-  ): value is ConfigBound | TypedConfigBound<ConfigSchema> {
+  ): value is ConfigBound<ConfigSchema> {
     return (
       value !== null &&
       value !== undefined &&