Merge pull request #2 from hyperweb-io/feat/create-gen-app-cli

feat: ship create-gen-app CLI, real integration tests, and license automation

Author: pyramation

.gitignore

@@ -2,4 +2,5 @@
 **/.DS_Store
 **/dist
 **/yarn-error.log
-lerna-debug.log
+lerna-debug.log
+test-output

package.json

@@ -31,6 +31,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "eslint-plugin-unused-imports": "^3.0.0",
+    "@jest/test-sequencer": "^29.6.2",
     "jest": "^29.6.2",
     "lerna": "^6",
     "prettier": "^3.0.2",

packages/create-gen-app/README.md

@@ -19,49 +19,75 @@ A TypeScript library for cloning and customizing template repositories with vari
 ## Features
 
 - Clone GitHub repositories or any git URL
-- Extract template variables from filenames and file contents using `__VARIABLE__` syntax
+- Extract template variables from filenames and file contents using `____VARIABLE____` syntax
 - Load custom questions from `.questions.json` or `.questions.js` files
 - Interactive prompts using inquirerer with CLI argument support
 - Stream-based file processing for efficient variable replacement
+- Auto-generate `LICENSE` file content (MIT, Apache-2.0, ISC) based on user answers
 
 ## Installation
 
 ```bash
 npm install create-gen-app
 ```
 
-## Usage
+## CLI Usage
+
+Install globally (or use `npx`) and run the CLI. It defaults to cloning `launchql/pgpm-boilerplates` and listing the templates under the root directory:
+
+```bash
+npm install -g create-gen-app
+
+# Select a template interactively and generate it into ./workspace
+create-gen-app --output ./workspace
+
+# Use the short alias and skip the prompt
+cga --template module --branch main --output ./module --LICENSE MIT
+```
+
+Key flags:
+
+- `--repo`, `--branch`, `--path`: point at any git repository / branch / subdirectory
+- `--template`: pick a folder inside `--path`; omitted means the CLI will prompt (or auto-select if only one)
+- `--output`: destination directory (defaults to `./<template>`); `--force` overwrites if it already exists
+- `--no-tty`: disable interactive mode for CI
+- `--version`: show the installed CLI version and exit
+- Any additional flags are forwarded as variable overrides (e.g. `--PACKAGE_NAME my-app`)
+
+## Library Usage
 
 ### Basic Usage
 
 ```typescript
-import { createGen } from 'create-gen-app';
+import { createGen } from "create-gen-app";
 
 await createGen({
-  templateUrl: 'https://github.com/user/template-repo',
-  outputDir: './my-new-project',
+  templateUrl: "https://github.com/user/template-repo",
+  outputDir: "./my-new-project",
   argv: {
-    PROJECT_NAME: 'my-project',
-    AUTHOR: 'John Doe'
-  }
+    PROJECT_NAME: "my-project",
+    AUTHOR: "John Doe",
+  },
 });
 ```
 
 ### Template Variables
 
-Variables in your template should be wrapped in double underscores:
+Variables in your template should be wrapped in `____` (four underscores) on both sides:
 
 **Filename variables:**
+
 ```
-__PROJECT_NAME__/
-  __MODULE_NAME__.ts
+____PROJECT_NAME____/
+  ____MODULE_NAME____.ts
 ```
 
 **Content variables:**
+
 ```typescript
-// __MODULE_NAME__.ts
-export const projectName = "__PROJECT_NAME__";
-export const author = "__AUTHOR__";
+// ____MODULE_NAME____.ts
+export const projectName = "____PROJECT_NAME____";
+export const author = "____AUTHOR____";
 ```
 
 ### Custom Questions
@@ -97,12 +123,12 @@ Or use `.questions.js` for dynamic questions:
 module.exports = {
   questions: [
     {
-      name: 'PROJECT_NAME',
-      type: 'text',
-      message: 'What is your project name?',
-      required: true
-    }
-  ]
+      name: "PROJECT_NAME",
+      type: "text",
+      message: "What is your project name?",
+      required: true,
+    },
+  ],
 };
 ```
 
@@ -113,6 +139,7 @@ module.exports = {
 Main function to create a project from a template.
 
 **Options:**
+
 - `templateUrl` (string): URL or path to the template repository
 - `outputDir` (string): Destination directory for the generated project
 - `argv` (Record<string, any>): Command-line arguments to pre-populate answers
@@ -133,17 +160,19 @@ Replace variables in all files and filenames.
 ## Variable Naming Rules
 
 Variables can contain:
+
 - Letters (a-z, A-Z)
 - Numbers (0-9)
-- Underscores (_)
+- Underscores (\_)
 - Must start with a letter or underscore
 
 Examples of valid variables:
-- `__PROJECT_NAME__`
-- `__author__`
-- `__CamelCase__`
-- `__snake_case__`
-- `__VERSION_1__`
+
+- `____PROJECT_NAME____`
+- `____author____`
+- `____CamelCase____`
+- `____snake_case____`
+- `____VERSION_1____`
 
 ## License
 

packages/create-gen-app/__tests__/cli.test.ts

@@ -0,0 +1,76 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import { runCli } from "../src/cli";
+import {
+  TEST_BRANCH,
+  TEST_REPO,
+  TEST_TEMPLATE,
+  buildAnswers,
+  cleanupWorkspace,
+  createTempWorkspace,
+} from "../test-utils/integration-helpers";
+
+jest.setTimeout(180_000);
+
+describe("CLI integration (GitHub templates)", () => {
+  it("generates a project using the real repo", async () => {
+    const workspace = createTempWorkspace("cli");
+    const answers = buildAnswers("cli");
+
+    const args = [
+      "--repo",
+      TEST_REPO,
+      "--branch",
+      TEST_BRANCH,
+      "--path",
+      ".",
+      "--template",
+      TEST_TEMPLATE,
+      "--output",
+      workspace.outputDir,
+      "--no-tty",
+    ];
+
+    for (const [key, value] of Object.entries(answers)) {
+      args.push(`--${key}`, value);
+    }
+
+    try {
+      const result = await runCli(args);
+      expect(result).toBeDefined();
+      if (!result) {
+        return;
+      }
+
+      expect(result.template).toBe(TEST_TEMPLATE);
+      expect(result.outputDir).toBe(path.resolve(workspace.outputDir));
+
+      const pkgPath = path.join(workspace.outputDir, "package.json");
+      expect(fs.existsSync(pkgPath)).toBe(true);
+
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      expect(pkg.name).toBe(answers.PACKAGE_IDENTIFIER);
+      expect(pkg.license).toBe(answers.LICENSE);
+
+      const licenseContent = fs.readFileSync(
+        path.join(workspace.outputDir, "LICENSE"),
+        "utf8"
+      );
+      expect(licenseContent).toContain("MIT License");
+      expect(licenseContent).toContain(answers.USERFULLNAME);
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it("prints version and exits when --version is provided", async () => {
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await runCli(["--version"]);
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringMatching(/create-gen-app v/));
+    logSpy.mockRestore();
+  });
+});
+

packages/create-gen-app/__tests__/create-gen-flow.test.ts

@@ -0,0 +1,57 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import { createGen } from "../src";
+import {
+  TEST_BRANCH,
+  TEST_REPO,
+  TEST_TEMPLATE,
+  buildAnswers,
+  cleanupWorkspace,
+  createTempWorkspace,
+} from "../test-utils/integration-helpers";
+
+jest.setTimeout(180_000);
+
+describe("createGen integration (GitHub templates)", () => {
+  it("clones the default repo and generates the module template", async () => {
+    const workspace = createTempWorkspace("flow");
+
+    try {
+      const answers = buildAnswers("flow");
+      const result = await createGen({
+        templateUrl: TEST_REPO,
+        fromBranch: TEST_BRANCH,
+        fromPath: TEST_TEMPLATE,
+        outputDir: workspace.outputDir,
+        argv: answers,
+        noTty: true,
+      });
+
+      expect(result).toBe(workspace.outputDir);
+
+      const packageJsonPath = path.join(workspace.outputDir, "package.json");
+      expect(fs.existsSync(packageJsonPath)).toBe(true);
+
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      expect(pkg.name).toBe(answers.PACKAGE_IDENTIFIER);
+      expect(pkg.license).toBe(answers.LICENSE);
+      expect(pkg.author).toContain(answers.USERFULLNAME);
+
+      const questionsJsonPath = path.join(
+        workspace.outputDir,
+        ".questions.json"
+      );
+      expect(fs.existsSync(questionsJsonPath)).toBe(false);
+
+      const licensePath = path.join(workspace.outputDir, "LICENSE");
+      expect(fs.existsSync(licensePath)).toBe(true);
+      const licenseContent = fs.readFileSync(licensePath, "utf8");
+      expect(licenseContent).toContain(answers.USERFULLNAME);
+      expect(licenseContent).toContain("MIT License");
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+});
+