@rindrics/initrepo 0.0.1 → 0.1.5

package/docs/adr/0001-simple-module-structure-over-ddd.md

@@ -0,0 +1,111 @@
+# ADR 0001: Simple Module Structure Over DDD
+
+## Status
+
+Accepted
+
+## Context
+
+We are building `@rindrics/initrepo`, a CLI tool that generates project scaffolding with:
+
+- CI/CD workflows (test, lint, tagpr, release)
+- husky configuration
+- Language-specific setup (TypeScript initially)
+- GitHub repository setup (repo creation, tags, branch protection)
+
+The tool has two main commands:
+
+1. `init` - Initialize a new project with all configurations
+2. `replace-devcode` - Replace development placeholder with production name and enable release workflow
+
+We needed to decide on an appropriate architecture for this tool.
+
+## Decision
+
+We chose a **simple module-based structure** instead of Domain-Driven Design (DDD).
+
+### Chosen Structure
+
+```text
+src/
+├── cli.ts                    # CLI entry point (Commander.js)
+├── commands/
+│   ├── init.ts               # init command implementation
+│   └── replace-devcode.ts    # replace-devcode command implementation
+├── generators/
+│   ├── languages/            # Language-specific logic
+│   │   ├── index.ts          # Common interface & factory
+│   │   └── typescript.ts     # TypeScript generator
+│   ├── project.ts            # package.json, etc.
+│   ├── cicd.ts               # GitHub Actions workflows
+│   └── husky.ts              # husky setup
+├── github/
+│   └── client.ts             # GitHub API operations (Octokit)
+├── templates/
+│   ├── common/               # Language-agnostic templates
+│   └── typescript/           # TypeScript-specific templates
+└── types.ts                  # Shared type definitions
+```
+
+### Why Not DDD?
+
+DDD excels when:
+
+- Complex business rules exist (aggregates, value objects, domain events)
+- A ubiquitous language with domain experts is needed
+- The domain model evolves over time
+
+This tool is essentially a **file generation utility**:
+
+- **Input**: Project name, language, options
+- **Output**: Generated files, GitHub repository
+
+There are no:
+
+- Domain entities to model
+- Complex business invariants to protect
+- Data persistence requiring repository patterns
+- Use cases complex enough to warrant a separate application layer
+
+### Language Support Strategy
+
+Languages are supported through two mechanisms:
+
+1. **`generators/languages/*.ts`** - Logic for each language (what files to generate, what dependencies to include, CI configuration)
+2. **`templates/{lang}/`** - Actual template files for each language
+
+A common `LanguageGenerator` interface ensures consistent behavior:
+
+```typescript
+interface LanguageGenerator {
+  name: string;
+  getFiles(): GeneratedFile[];
+  getDependencies(): Dependencies;
+  getCiConfig(): CiConfig;
+}
+```
+
+Adding a new language requires:
+
+1. Implementing `LanguageGenerator` in `generators/languages/`
+2. Adding templates in `templates/{lang}/`
+3. Registering in the factory function
+
+## Consequences
+
+### Positive
+
+- **Simplicity**: Code is easy to navigate and understand
+- **Testability**: Each module can be tested in isolation
+- **Extensibility**: New generators or languages can be added without touching existing code
+- **Right-sized**: No unnecessary abstraction layers
+- **Fast development**: Less boilerplate, quicker iterations
+
+### Negative
+
+- **Limited structure for growth**: If the tool grows significantly in complexity, we may need to introduce more structure
+- **No enforced boundaries**: Developers must exercise discipline to maintain separation of concerns
+
+### Neutral
+
+- If complex domain logic emerges (e.g., conditional generation rules, plugin systems), we can introduce targeted patterns without full DDD adoption

package/package.json

@@ -1,10 +1,40 @@
 {
   "name": "@rindrics/initrepo",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @rindrics/initrepo",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "0.1.5",
+  "description": "setup GitHub repo with dev tools",
+  "type": "module",
+  "bin": {
+    "initrepo": "./dist/cli.js"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "bun build src/cli.ts --outdir dist --target node",
+    "lint": "biome lint src",
+    "format": "biome format src --write",
+    "check": "biome check src",
+    "test": "bun test",
+    "clean": "rm -rf test-* dist",
+    "prepare": "husky"
+  },
+  "keywords": ["cli", "scaffold", "setup", "repository"],
+  "author": "Rindrics",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rindrics/initrepo.git"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^20.2.0",
+    "@types/ejs": "^3.1.5",
+    "bun-types": "^1.0.0",
+    "husky": "^9.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "ejs": "^3.1.0",
+    "octokit": "^5.0.5"
+  }
 }

package/src/cli.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test';
+import packageJson from '../package.json';
+import { createProgram } from './cli';
+
+describe('CLI', () => {
+  test('should have correct name from package.json', () => {
+    const program = createProgram();
+    expect(program.name()).toBe(packageJson.name);
+  });
+
+  test('should have correct version from package.json', () => {
+    const program = createProgram();
+    expect(program.version()).toBe(packageJson.version);
+  });
+
+  test('should have description', () => {
+    const program = createProgram();
+    expect(program.description()).toBe('Rapid repository setup CLI tool');
+  });
+});

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import packageJson from '../package.json';
+import { registerInitCommand } from './commands/init';
+import { registerPrepareReleaseCommand } from './commands/prepare-release';
+
+const { version: VERSION, name: NAME } = packageJson;
+
+export function createProgram(): Command {
+  const program = new Command();
+
+  program
+    .name(NAME)
+    .description('Rapid repository setup CLI tool')
+    .version(VERSION);
+
+  registerInitCommand(program);
+  registerPrepareReleaseCommand(program);
+
+  return program;
+}
+
+// Run CLI when executed directly
+if (import.meta.main) {
+  const program = createProgram();
+  program.parse();
+}

package/src/commands/init.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { Command } from 'commander';
+import * as projectGenerator from '../generators/project';
+import {
+  initProject,
+  promptYesNo,
+  registerInitCommand,
+  validateLanguage,
+} from './init';
+
+describe('init command', () => {
+  describe('validateLanguage', () => {
+    test('should accept typescript', () => {
+      expect(validateLanguage('typescript')).toBe('typescript');
+    });
+
+    test('should throw for unsupported language', () => {
+      expect(() => validateLanguage('python')).toThrow(
+        'Unsupported language: python',
+      );
+    });
+  });
+
+  describe('initProject', () => {
+    let consoleSpy: ReturnType<typeof spyOn>;
+    let generateProjectSpy: ReturnType<typeof spyOn>;
+
+    beforeEach(() => {
+      consoleSpy = spyOn(console, 'log').mockImplementation(() => {});
+      // Mock generateProject to avoid file operations and network calls
+      generateProjectSpy = spyOn(
+        projectGenerator,
+        'generateProject',
+      ).mockResolvedValue(undefined);
+    });
+
+    afterEach(() => {
+      consoleSpy.mockRestore();
+      generateProjectSpy.mockRestore();
+    });
+
+    test('should log project creation message', async () => {
+      await initProject({
+        projectName: 'test-project',
+        lang: 'typescript',
+        isDevcode: false,
+      });
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Creating project: test-project (typescript)',
+      );
+    });
+
+    test('should include devcode label when isDevcode is true', async () => {
+      await initProject({
+        projectName: 'test-project',
+        lang: 'typescript',
+        isDevcode: true,
+      });
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Creating project: test-project (typescript) [devcode]',
+      );
+    });
+
+    test('should pass author option to generateProject', async () => {
+      await initProject({
+        projectName: 'test-project',
+        lang: 'typescript',
+        isDevcode: false,
+        author: 'custom-author',
+      });
+
+      expect(generateProjectSpy).toHaveBeenCalledWith({
+        projectName: 'test-project',
+        lang: 'typescript',
+        isDevcode: false,
+        author: 'custom-author',
+      });
+    });
+  });
+
+  describe('registerInitCommand', () => {
+    test('should register init command to program', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      expect(initCmd).toBeDefined();
+      expect(initCmd?.description()).toContain('npm publish');
+    });
+
+    test('should have --devcode option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const devcodeOption = initCmd?.options.find(
+        (opt) => opt.long === '--devcode',
+      );
+      expect(devcodeOption).toBeDefined();
+    });
+
+    test('should have --author option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const authorOption = initCmd?.options.find(
+        (opt) => opt.long === '--author',
+      );
+      expect(authorOption).toBeDefined();
+    });
+
+    test('should have --create-repo option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const createRepoOption = initCmd?.options.find(
+        (opt) => opt.long === '--create-repo',
+      );
+      expect(createRepoOption).toBeDefined();
+    });
+
+    test('should have --no-create-repo option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const noCreateRepoOption = initCmd?.options.find(
+        (opt) => opt.long === '--no-create-repo',
+      );
+      expect(noCreateRepoOption).toBeDefined();
+    });
+
+    test('should have --no-devcode option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const noDevcodeOption = initCmd?.options.find(
+        (opt) => opt.long === '--no-devcode',
+      );
+      expect(noDevcodeOption).toBeDefined();
+    });
+
+    test('should have --private option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const privateOption = initCmd?.options.find(
+        (opt) => opt.long === '--private',
+      );
+      expect(privateOption).toBeDefined();
+    });
+
+    test('should have --no-private option', () => {
+      const program = new Command();
+      registerInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === 'init');
+      const noPrivateOption = initCmd?.options.find(
+        (opt) => opt.long === '--no-private',
+      );
+      expect(noPrivateOption).toBeDefined();
+    });
+  });
+});

package/src/commands/init.ts

@@ -0,0 +1,172 @@
+import * as readline from 'node:readline/promises';
+import type { Command } from 'commander';
+import { generateProject } from '../generators/project';
+import type { InitOptions, Language } from '../types';
+import { createGitHubRepo, hasGitHubToken } from '../utils/github-repo';
+
+const SUPPORTED_LANGUAGES: Language[] = ['typescript'];
+
+export function validateLanguage(lang: string): Language {
+  if (!SUPPORTED_LANGUAGES.includes(lang as Language)) {
+    throw new Error(
+      `Unsupported language: ${lang}. Supported: ${SUPPORTED_LANGUAGES.join(', ')}`,
+    );
+  }
+  return lang as Language;
+}
+
+/**
+ * Prompts user with a yes/no question
+ */
+export async function promptYesNo(
+  question: string,
+  defaultValue = false,
+): Promise<boolean> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const hint = defaultValue ? '(Y/n)' : '(y/N)';
+
+  try {
+    const answer = await rl.question(`${question} ${hint}: `);
+    if (answer.trim() === '') {
+      return defaultValue;
+    }
+    return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+export interface InitProjectOptions extends InitOptions {
+  createRepo?: boolean;
+  isPrivate?: boolean;
+}
+
+export async function initProject(options: InitProjectOptions): Promise<void> {
+  const devcodeLabel = options.isDevcode ? ' [devcode]' : '';
+  console.log(
+    `Creating project: ${options.projectName} (${options.lang})${devcodeLabel}`,
+  );
+
+  // Generate project files
+  await generateProject(options);
+  console.log(`✅ Project files created at ./${options.projectName}`);
+
+  // Create GitHub repository if requested
+  if (options.createRepo) {
+    if (!hasGitHubToken()) {
+      console.warn('⚠️  GITHUB_TOKEN not set, skipping repository creation');
+      console.warn(
+        '   Set GITHUB_TOKEN environment variable to enable repo creation',
+      );
+    } else {
+      try {
+        console.log('📦 Creating GitHub repository...');
+        const result = await createGitHubRepo({
+          name: options.projectName,
+          description: options.isDevcode
+            ? `[devcode] ${options.projectName}`
+            : undefined,
+          isPrivate: options.isPrivate ?? false,
+        });
+
+        if (result.alreadyExisted) {
+          console.log(`ℹ️  Repository already exists: ${result.url}`);
+          console.log(`   Labels ensured: tagpr:minor, tagpr:major`);
+        } else {
+          console.log(`✅ GitHub repository created: ${result.url}`);
+          console.log(`   Labels created: tagpr:minor, tagpr:major`);
+        }
+
+        console.log(`\n   To push your code:`);
+        console.log(`   cd ${options.projectName}`);
+        console.log(`   git init`);
+        console.log(`   git add .`);
+        console.log(`   git commit -m "chore: initial commit"`);
+        console.log(`   git remote add origin ${result.cloneUrl}`);
+        console.log(`   git push -u origin main`);
+      } catch (error) {
+        console.error(
+          `❌ Failed to create GitHub repository: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+  }
+}
+
+interface InitCommandOptions {
+  lang: string;
+  devcode?: boolean;
+  author?: string;
+  createRepo?: boolean;
+  private?: boolean;
+}
+
+export function registerInitCommand(program: Command): void {
+  program
+    .command('init <project-name>')
+    .description(
+      'Initialize a new project. <project-name> is the name used for npm publish.',
+    )
+    .option('-l, --lang <language>', 'Project language', 'typescript')
+    .option(
+      '-d, --devcode',
+      'Use devcode mode (adds private: true to package.json)',
+    )
+    .option('--no-devcode', 'Not a devcode project')
+    .option(
+      '-a, --author <name>',
+      'Package author (defaults to npm whoami for TypeScript)',
+    )
+    .option(
+      '--create-repo',
+      'Create GitHub repository and tagpr labels (requires GITHUB_TOKEN)',
+    )
+    .option('--no-create-repo', 'Skip GitHub repository creation')
+    .option('-p, --private', 'Make GitHub repository private')
+    .option('--no-private', 'Make GitHub repository public')
+    .action(async (projectName: string, opts: InitCommandOptions) => {
+      const lang = validateLanguage(opts.lang);
+
+      // Determine if devcode - prompt if not specified
+      let isDevcode: boolean;
+      if (opts.devcode !== undefined) {
+        isDevcode = opts.devcode;
+      } else {
+        isDevcode = await promptYesNo(
+          `Is "${projectName}" a developmental code?`,
+          false,
+        );
+      }
+
+      // Determine if create repo - prompt if not specified
+      let createRepo: boolean;
+      if (opts.createRepo !== undefined) {
+        createRepo = opts.createRepo;
+      } else {
+        createRepo = await promptYesNo('Create GitHub repo?', true);
+      }
+
+      // Determine if private repo - prompt only if creating repo and not specified
+      let isPrivate = false;
+      if (createRepo) {
+        if (opts.private !== undefined) {
+          isPrivate = opts.private;
+        } else {
+          isPrivate = await promptYesNo('Make repo private?', false);
+        }
+      }
+
+      await initProject({
+        projectName,
+        lang,
+        isDevcode,
+        author: opts.author,
+        createRepo,
+        isPrivate,
+      });
+    });
+}