@julianoczkowski/create-trimble-app 2.0.0

package/README.md

@@ -0,0 +1,191 @@
+# Create Modus App
+
+Interactive CLI to scaffold Modus 2.0 web component applications for React and Angular.
+
+**Templates are bundled directly** - no external downloads, works fully offline.
+
+## Quick Start
+
+```bash
+npx @julianoczkowski/create-trimble-app
+```
+
+## Features
+
+- 📦 **Bundled Templates** - Templates included in package, no network required
+- 🔒 **Secure** - No runtime external dependencies
+- ⚛️ **React** - React + Vite + Modus 2.0 Components + Cursor Rules
+- 🅰️ **Angular** - Angular + Modus 2.0 Web Components + Cursor Rules
+- 🎯 **Interactive** - Beautiful CLI with framework selection
+- ⚡ **Fast** - Local file copy, instant setup
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+npx @julianoczkowski/create-trimble-app
+```
+
+This will guide you through:
+
+1. Framework selection (React or Angular)
+2. Installation location choice
+3. Project name input
+4. Optional dependency installation
+
+### Command Line Options
+
+```bash
+# Create with project name
+npx @julianoczkowski/create-trimble-app my-app
+
+# Specify framework
+npx @julianoczkowski/create-trimble-app my-app --framework react
+
+# Install in current folder
+npx @julianoczkowski/create-trimble-app --current-folder
+
+# Preview without creating files
+npx @julianoczkowski/create-trimble-app my-app --dry-run
+
+# Enable verbose output
+npx @julianoczkowski/create-trimble-app my-app --verbose
+
+# Show CLI information
+npx @julianoczkowski/create-trimble-app --info
+
+# Skip dependency installation
+npx @julianoczkowski/create-trimble-app my-app --no-install
+
+# Show help
+npx @julianoczkowski/create-trimble-app --help
+```
+
+## CLI Options
+
+| Option                   | Description                            |
+| ------------------------ | -------------------------------------- |
+| `[project-name]`         | Name of the project to create          |
+| `-f, --framework <name>` | Framework to use (react, angular)      |
+| `--current-folder`       | Install in current folder              |
+| `--dry-run`              | Preview what would be created          |
+| `--verbose`              | Enable verbose output for debugging    |
+| `--info`                 | Show information about this CLI        |
+| `--no-install`           | Skip automatic dependency installation |
+| `-v, --version`          | Display version number                 |
+| `-h, --help`             | Display help                           |
+
+## Supported Frameworks
+
+| Framework      | Description  | What's Included                                                                                          |
+| -------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
+| ⚛️ **React**   | React + Vite | Modus 2.0 Components, TypeScript, Tailwind CSS, 40+ Cursor Rules, GitHub Templates, Code Quality Scripts |
+| 🅰️ **Angular** | Angular 20+  | Modus 2.0 Web Components, TypeScript, Tailwind CSS, 11 Cursor Rules, GitHub Workflows, Demo Components   |
+
+## What's Included in Each Template
+
+Both templates come fully configured with:
+
+```
+your-project/
+├── .cursor/           # Cursor IDE rules for Modus development
+├── .github/           # Issue templates, PR template, CI workflows
+├── .husky/            # Git hooks (pre-commit)
+├── .vscode/           # VS Code extensions & settings
+├── docs/              # Documentation
+├── scripts/           # Code quality check scripts
+├── src/               # Source code with demo components
+├── package.json       # All dependencies configured
+└── README.md          # Getting started guide
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    npx create-trimble-app                      │
+├─────────────────────────────────────────────────────────────┤
+│  1. Parse CLI arguments (Commander.js)                       │
+│  2. Interactive prompts (if needed)                          │
+│  3. Copy bundled template (local file copy)                  │
+│  4. Update package.json with project name                    │
+│  5. Install dependencies (optional)                          │
+│  6. Show success message                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+For detailed architecture documentation, see [docs/architecture.md](docs/architecture.md).
+
+## Security
+
+This CLI is designed with security as a priority:
+
+- **No External Downloads** - Templates are bundled in the npm package
+- **Works Offline** - No network required to create projects
+- **npm Provenance** - Published with provenance attestation
+- **Minimal Dependencies** - Only essential runtime dependencies
+
+Unlike other scaffolding tools that download templates from GitHub at runtime, this CLI bundles templates directly. This eliminates:
+
+- Supply chain attacks from compromised repositories
+- Network failures during project creation
+- Version drift between CLI and templates
+
+## Requirements
+
+- Node.js 18 or higher
+- npm, yarn, or pnpm
+
+## Development
+
+```bash
+# Clone this repository
+git clone https://github.com/julianoczkowski/create-trimble-app.git
+cd create-trimble-app
+
+# Install dependencies
+npm install
+
+# Run locally
+npm run dev
+
+# Run tests
+npm test
+
+# Test specific commands
+node bin/create-trimble-app.js --help
+node bin/create-trimble-app.js my-app --framework react --dry-run
+```
+
+For detailed testing instructions, see [docs/local-testing.md](docs/local-testing.md).
+
+## Documentation
+
+| Document                               | Description                    |
+| -------------------------------------- | ------------------------------ |
+| [Architecture](docs/architecture.md)   | How the CLI works internally   |
+| [Local Testing](docs/local-testing.md) | How to test during development |
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`npm test`)
+4. Commit your changes (`git commit -m 'Add some amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## License
+
+MIT © Julian Oczkowski
+
+## Related
+
+- [Modus Web Components Documentation](https://trimble-oss.github.io/modus-wc-2.0/main/?path=/docs/documentation-getting-started--docs)
+- [Modus Icons](https://modus-icons.trimble.com/)
+- [Trimble Modus Design System](https://modus.trimble.com)
+
+---
+
+**Made with ❤️ for the Modus community**

package/bin/create-trimble-app.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { cli } from "../src/cli.js";
+
+// Run the CLI
+cli().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@julianoczkowski/create-trimble-app",
+  "version": "2.0.0",
+  "description": "Interactive CLI to scaffold Modus 2.0 web component applications for React and Angular - templates bundled, works offline",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "create-trimble-app": "bin/create-trimble-app.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "dev": "node bin/create-trimble-app.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run test && npm audit"
+  },
+  "keywords": [
+    "modus",
+    "web-components",
+    "cli",
+    "scaffold",
+    "react",
+    "angular",
+    "trimble",
+    "create-app",
+    "boilerplate",
+    "starter",
+    "template",
+    "offline"
+  ],
+  "author": "Julian Oczkowski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/julianoczkowski/create-trimble-app.git"
+  },
+  "bugs": {
+    "url": "https://github.com/julianoczkowski/create-trimble-app/issues"
+  },
+  "homepage": "https://github.com/julianoczkowski/create-trimble-app#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^8.0.1",
+    "ora": "^8.0.1",
+    "prompts": "^2.4.2",
+    "update-notifier": "^7.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.0.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { scaffold } from "./scaffold.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load package.json for version info
+const packageJsonPath = join(__dirname, "..", "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+// Check for updates (non-blocking)
+async function checkForUpdates() {
+  try {
+    const { default: updateNotifier } = await import("update-notifier");
+    const notifier = updateNotifier({
+      pkg: packageJson,
+      updateCheckInterval: 1000 * 60 * 60 * 24, // 1 day
+    });
+    notifier.notify({ isGlobal: true });
+  } catch {
+    // Silently ignore update check failures
+  }
+}
+
+const program = new Command();
+
+program
+  .name("create-trimble-app")
+  .description(
+    "Interactive CLI to scaffold Modus 2.0 web component applications",
+  )
+  .version(packageJson.version, "-v, --version", "Display version number")
+  .argument("[project-name]", "Name of the project to create")
+  .option(
+    "-f, --framework <name>",
+    "Framework to use (react, angular)",
+    validateFramework,
+  )
+  .option(
+    "--current-folder",
+    "Install in current folder and use folder name as project name",
+  )
+  .option("--no-install", "Skip automatic dependency installation")
+  .option("--dry-run", "Preview what would be created without making changes")
+  .option("--verbose", "Enable verbose output for debugging")
+  .option("--info", "Show information about this CLI")
+  .addHelpText(
+    "after",
+    `
+${chalk.cyan("Examples:")}
+  ${chalk.gray("# Interactive mode - choose framework and name")}
+  $ npx @julianoczkowski/create-trimble-app
+
+  ${chalk.gray("# Create a React project")}
+  $ npx @julianoczkowski/create-trimble-app my-app --framework react
+
+  ${chalk.gray("# Create an Angular project")}
+  $ npx @julianoczkowski/create-trimble-app my-app --framework angular
+
+  ${chalk.gray("# Install in current folder")}
+  $ npx @julianoczkowski/create-trimble-app --current-folder
+
+  ${chalk.gray("# Preview without creating files")}
+  $ npx @julianoczkowski/create-trimble-app my-app --dry-run
+
+${chalk.cyan("Frameworks:")}
+  ${chalk.white("react")}    - React with Vite and Modus 2.0 Components
+  ${chalk.white("angular")}  - Angular with Modus 2.0 Web Components
+
+${chalk.cyan("Security:")}
+  Templates are bundled directly in this CLI package.
+  No external downloads - works offline, always consistent.
+  Use ${chalk.yellow("--info")} for more details.
+
+${chalk.cyan("More information:")}
+  ${chalk.blue("https://github.com/julianoczkowski/create-trimble-app")}
+`,
+  )
+  .action(async (projectName, options) => {
+    // Check for updates in background
+    checkForUpdates();
+
+    try {
+      await scaffold({
+        projectName,
+        framework: options.framework,
+        currentFolder: options.currentFolder,
+        install: options.install,
+        dryRun: options.dryRun,
+        verbose: options.verbose,
+        showInfo: options.info,
+      });
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+/**
+ * Validate framework option
+ * @param {string} value - Framework name
+ * @returns {string} - Validated framework name
+ */
+function validateFramework(value) {
+  const validFrameworks = ["react", "angular"];
+  const lowercaseValue = value.toLowerCase();
+
+  if (!validFrameworks.includes(lowercaseValue)) {
+    throw new Error(
+      `Invalid framework "${value}". Valid options: ${validFrameworks.join(", ")}`,
+    );
+  }
+
+  return lowercaseValue;
+}
+
+// Export for testing
+export async function cli(args = process.argv) {
+  await program.parseAsync(args);
+}
+
+// Run CLI if this is the main module
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  cli();
+}

package/src/frameworks.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function loadFrameworks() {
+  try {
+    const configPath = join(__dirname, "../templates/config.json");
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+
+    return Object.entries(config.frameworks)
+      .filter(([_id, framework]) => !framework.disabled)
+      .map(([id, framework]) => ({
+        id,
+        ...framework,
+      }));
+  } catch (error) {
+    throw new Error(
+      `Failed to load framework configurations: ${error.message}`,
+    );
+  }
+}
+
+export function getFrameworkById(frameworks, id) {
+  return frameworks.find((framework) => framework.id === id);
+}

package/src/scaffold.js

@@ -0,0 +1,209 @@
+import prompts from "prompts";
+import ora from "ora";
+import chalk from "chalk";
+import { loadFrameworks, getFrameworkById } from "./frameworks.js";
+import {
+  updatePackageJson,
+  validateProjectName,
+  getCurrentFolderName,
+} from "./utils/file.js";
+import { installDependencies } from "./utils/install.js";
+import { copyTemplate, getDetailedErrorMessage } from "./utils/git.js";
+import { logger } from "./utils/logger.js";
+
+export async function scaffold(options = {}) {
+  const { verbose = false, dryRun = false } = options;
+
+  // Set verbose mode
+  if (verbose) {
+    process.env.VERBOSE = "true";
+  }
+
+  // Show welcome screen
+  logger.welcome();
+
+  // Show security notice if requested
+  if (options.showInfo) {
+    logger.securityNotice();
+    process.exit(0);
+  }
+
+  const frameworks = loadFrameworks();
+
+  // 1. Framework Selection
+  let framework = options.framework;
+
+  if (!framework) {
+    const result = await prompts({
+      type: "select",
+      name: "framework",
+      message: "Select your framework:",
+      choices: frameworks.map((f) => ({
+        title: `${f.badge} ${f.name}`,
+        description: f.description + (f.note ? ` (${f.note})` : ""),
+        value: f.id,
+      })),
+    });
+    framework = result.framework;
+  }
+
+  if (!framework) {
+    console.log(chalk.yellow("X Cancelled"));
+    process.exit(0);
+  }
+
+  const config = getFrameworkById(frameworks, framework);
+
+  if (!config) {
+    console.error(chalk.red(`Error: Unknown framework "${framework}"`));
+    console.log(
+      chalk.yellow(
+        `Available frameworks: ${frameworks.map((f) => f.id).join(", ")}`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  // 2. Installation Location Choice
+  let installInCurrentFolder = options.currentFolder;
+  let projectName = options.projectName;
+
+  if (!installInCurrentFolder && !projectName) {
+    const currentFolderName = getCurrentFolderName();
+
+    const result = await prompts({
+      type: "select",
+      name: "installLocation",
+      message: "Where would you like to install your app?",
+      choices: [
+        {
+          title: `📁 Install in current directory (${currentFolderName})`,
+          description: "Use the current folder as your project directory",
+          value: "current",
+        },
+        {
+          title: "📂 Create new directory",
+          description: "Create a new folder for your project",
+          value: "new",
+        },
+      ],
+    });
+
+    if (!result.installLocation) {
+      console.log(chalk.yellow("X Cancelled"));
+      process.exit(0);
+    }
+
+    installInCurrentFolder = result.installLocation === "current";
+  }
+
+  // 3. Project Name
+  if (installInCurrentFolder) {
+    projectName = getCurrentFolderName();
+    console.log(chalk.blue(`📁 Using current folder name: ${projectName}`));
+  } else if (!projectName) {
+    const result = await prompts({
+      type: "text",
+      name: "projectName",
+      message: "Project name:",
+      initial: "my-modus-app",
+      validate: (name) => validateProjectName(name, false),
+    });
+    projectName = result.projectName;
+  } else {
+    const validation = validateProjectName(projectName, false);
+    if (validation !== true) {
+      console.error(chalk.red(`Error: ${validation}`));
+      process.exit(1);
+    }
+  }
+
+  if (!projectName) {
+    console.log(chalk.yellow("X Cancelled"));
+    process.exit(0);
+  }
+
+  const projectPath = installInCurrentFolder ? "." : projectName;
+
+  // Dry-run mode: show what would be created without executing
+  if (dryRun) {
+    console.log(chalk.cyan("\n🔍 Dry-run mode - no changes will be made\n"));
+    console.log(chalk.white("Would create project with:"));
+    console.log(chalk.gray(`  Framework: ${config.name}`));
+    console.log(chalk.gray(`  Project name: ${projectName}`));
+    console.log(
+      chalk.gray(
+        `  Location: ${installInCurrentFolder ? "Current directory" : `New directory: ${projectName}`}`,
+      ),
+    );
+    console.log(chalk.gray(`  Template: Bundled (included in CLI package)`));
+    console.log();
+    process.exit(0);
+  }
+
+  // 4. Copy Template
+  const spinner = ora(`📦 Creating ${config.name} project...`).start();
+
+  try {
+    await copyTemplate(framework, projectPath);
+    spinner.succeed(chalk.green(`Project created successfully!`));
+
+    // 5. Update package.json with project name
+    try {
+      await updatePackageJson(projectPath, {
+        name: projectName,
+      });
+      logger.success("Updated project configuration");
+    } catch (error) {
+      logger.warning("Could not update package.json name");
+      if (verbose) {
+        console.log(chalk.gray(`  Error: ${error.message}`));
+      }
+    }
+  } catch (error) {
+    spinner.fail(chalk.red(`Failed to create project`));
+    const detailedMessage = getDetailedErrorMessage(error);
+    console.error(chalk.red(`\n${detailedMessage}`));
+    process.exit(1);
+  }
+
+  // Visual separator before dependency installation
+  console.log(chalk.gray("═".repeat(60)));
+
+  // 6. Install Dependencies (optional)
+  let install = options.install;
+
+  if (install === undefined) {
+    const result = await prompts({
+      type: "confirm",
+      name: "install",
+      message: "📦 Install dependencies now (default: yes)?",
+      initial: true,
+    });
+    install = result.install;
+  }
+
+  if (install) {
+    const installSpinner = ora("Installing dependencies...").start();
+    try {
+      await installDependencies(projectPath);
+      installSpinner.succeed(chalk.green("Dependencies installed"));
+    } catch (error) {
+      installSpinner.fail(chalk.red("Failed to install dependencies"));
+      console.error(chalk.red(error.message));
+      console.log(
+        chalk.yellow(`\n💡 You can install dependencies manually by running:`),
+      );
+      const installCommand = installInCurrentFolder
+        ? "npm install"
+        : `cd ${projectName} && npm install`;
+      console.log(chalk.cyan(`   ${installCommand}`));
+    }
+  }
+
+  // Visual separator before final success message
+  console.log(chalk.gray("═".repeat(60)));
+
+  // 7. Success Message
+  logger.nextSteps(projectName, config.name, install, installInCurrentFolder);
+}

package/src/utils/file.js

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join, basename } from "path";
+import { cwd } from "process";
+
+export async function updatePackageJson(projectPath, updates) {
+  const packageJsonPath = join(projectPath, "package.json");
+
+  try {
+    if (!existsSync(packageJsonPath)) {
+      throw new Error("package.json not found in template");
+    }
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+    // Update only specified fields
+    Object.assign(packageJson, updates);
+
+    writeFileSync(
+      packageJsonPath,
+      JSON.stringify(packageJson, null, 2) + "\n",
+      "utf-8"
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to update package.json: ${error.message}. Contact julian_oczkowski@trimble.com`
+    );
+  }
+}
+
+export function getCurrentFolderName() {
+  return basename(cwd());
+}
+
+export function validateProjectName(name, isCurrentFolder = false) {
+  if (!name) return "Project name is required";
+
+  if (!/^[a-z0-9-_]+$/i.test(name)) {
+    return "Project name can't contain spaces. It can only contain letters, numbers, dashes.";
+  }
+
+  // Skip directory existence check if installing in current folder
+  if (!isCurrentFolder && existsSync(name)) {
+    return `Directory "${name}" already exists`;
+  }
+
+  return true;
+}