@tsparticles/cli 3.3.0 → 3.3.2

package/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    target-branch: "dev"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

package/.planning/codebase/ARCHITECTURE.md

@@ -1,3 +1,132 @@
-Architecture Overview
-- CLI entrypoint: src/cli.ts
-- Feature modules: src/create, src/build
+# Architecture
+
+**Analysis Date:** 2026-03-10
+
+## Pattern Overview
+
+Overall: Small modular CLI application organized as command modules with utility libraries and build tooling.
+
+Key Characteristics:
+
+- Single-process Node.js CLI built in TypeScript (compiled to ESM JavaScript).
+- Commands are organized as independent modules and registered with a central `commander`-based entrypoint.
+- Clear separation between "command" code (user-facing CLI actions) and utilities (I/O, template manipulation, subprocess execution).
+- Build scripts live under `src/build` and are implemented as programmatic build tasks callable from `build` command.
+
+## Layers
+
+Command Layer:
+
+- Purpose: Exposes CLI commands and their behaviors to end users.
+- Location: `src/cli.ts`, `src/create/*`, `src/build/*`
+- Contains: `commander` Command instances, argument parsing, user prompts.
+- Depends on: `src/utils/*` for filesystem and template operations, `prompts` for interactive input.
+- Used by: CLI entrypoint `src/cli.ts` registers commands for runtime.
+
+Core/Template Layer:
+
+- Purpose: Implement the core operations that create projects and manipulate templates.
+- Location: `src/create/preset/create-preset.ts`, `src/create/shape/create-shape.ts`, `src/create/plugin/create-plugin.ts`, `src/utils/template-utils.ts`, `src/utils/file-utils.ts`
+- Contains: file copy, token replacement, package.json updates, npm execution, webpack/package dist adjustments.
+- Depends on: `fs-extra`, `lookpath`, child_process `exec`.
+- Used by: Command actions in `src/create/*`.
+
+Build Tooling Layer:
+
+- Purpose: Project build and CI helpers exposed as `build` command.
+- Location: `src/build/*.ts` (`src/build/build.ts`, `src/build/build-tsc.ts`, `src/build/build-bundle.ts`, etc.)
+- Contains: tasks to run prettier, eslint, tsc, bundling and other project checks.
+- Depends on: dev tooling in `package.json` and runtime tools (SWC, Webpack, etc.).
+
+Utilities Layer:
+
+- Purpose: Shared helpers for string manipulation, file operations and token replacement.
+- Location: `src/utils/string-utils.ts`, `src/utils/file-utils.ts`, `src/utils/template-utils.ts`
+- Contains: helper functions with small focused responsibilities (e.g., `replaceTokensInFile`, `getDestinationDir`, `getRepositoryUrl`).
+
+Test Layer:
+
+- Purpose: Unit tests for templates and generator functions.
+- Location: `tests/*.test.ts`, `vitest.config.ts`
+
+## Data Flow
+
+Create command flow (example `preset`):
+
+1. User invokes CLI: `tsparticles-cli create preset <destination>` -> `src/cli.ts` boots and routes to `src/create/create.ts` -> `src/create/preset/preset.ts`.
+2. `preset.ts` gathers interactive input via `prompts` and computes `destPath` using `src/utils/file-utils.ts:getDestinationDir`.
+3. `createPresetTemplate` in `src/create/preset/create-preset.ts` runs sequence:
+   - copy empty template files (`src/utils/template-utils.ts:copyEmptyTemplateFiles`) -> uses `files` templates under repo
+   - copy project-specific files via `fs.copy`
+   - run a series of `replaceTokensInFile` operations (`src/utils/file-utils.ts`) to customize bundle/index/readme/package files
+   - run `runInstall` and `runBuild` (`src/utils/template-utils.ts`) which spawn subprocesses (`npm install`, `npm run build`) if `npm` found
+
+State Management:
+
+- Stateless CLI operations. Functions operate on input parameters and filesystem state. There is no in-memory application-wide state beyond individual command execution.
+
+## Key Abstractions
+
+Command Module:
+
+- Purpose: Encapsulate a single CLI command and its action handler.
+- Examples: `src/create/preset/preset.ts`, `src/create/shape/shape.ts`, `src/create/plugin/plugin.ts`, `src/create/create.ts`.
+- Pattern: Each command is a `commander.Command` with `argument` declarations and an `action` async function.
+
+Template Manipulation Utility:
+
+- Purpose: Replace tokens and patch files in a project template.
+- Examples: `src/utils/file-utils.ts` (`replaceTokensInFile`, `replaceTokensInFiles`), `src/utils/template-utils.ts` (`updatePackageFile`, `updateWebpackFile`).
+
+Build Task Modules:
+
+- Purpose: Implement discrete build subtasks called from `src/build/build.ts`.
+- Examples: `src/build/build-tsc.ts`, `src/build/build-bundle.ts`, `src/build/build-eslint.ts`.
+
+## Entry Points
+
+CLI Entrypoint:
+
+- Location: `src/cli.ts`
+- Triggers: Executed when package binary `dist/cli.js` is run (shebang present); `npm run build` ensures `dist/cli.js` is executable.
+- Responsibilities: Read package version (`package.json`), register `build` and `create` commands and parse `process.argv`.
+
+Create Command Aggregator:
+
+- Location: `src/create/create.ts`
+- Triggers: Registered by `src/cli.ts` as `create` command
+- Responsibilities: Add subcommands `plugin`, `preset`, `shape` from their respective modules.
+
+Build Aggregator:
+
+- Location: `src/build/build.ts`
+- Triggers: Registered by `src/cli.ts` as `build` command
+- Responsibilities: Compose and run smaller build tasks (prettier, lint, tsc, circular deps, dist packaging).
+
+## Error Handling
+
+Strategy: Throw and bubble errors from async functions; top-level command handlers are async and do not wrap all exceptions. Some tests and callers catch errors for logging.
+
+Patterns:
+
+- Synchronous validation: `getDestinationDir` checks destination existence and throws an Error if folder not empty (`src/utils/file-utils.ts:getDestinationDir`).
+- Subprocess execution: `exec` wrappers (`runInstall`, `runBuild`) return Promises and reject on `exec` error; calling code awaits and therefore receives the rejection (`src/utils/template-utils.ts`).
+- Tests catch and log errors selectively (`tests/*.test.ts`), but many command entrypoints do not add global try/catch.
+
+## Cross-Cutting Concerns
+
+Logging:
+
+- Approach: Minimal; code uses `console.error` in tests. No centralized logger present. Files: `tests/*`, most modules do not log.
+
+Validation:
+
+- Approach: Input validation is enforced by `prompts` validators and `getDestinationDir` pre-checks. See `src/create/*` for validators on required fields.
+
+Authentication:
+
+- Approach: Not applicable to this CLI: no remote APIs or credential storage.
+
+---
+
+_Architecture analysis: 2026-03-10_

package/.planning/codebase/CONCERNS.md

@@ -1,3 +1,105 @@
-Concerns
-- Some build scripts may lack tests
-- CI secrets should be reviewed
+# Codebase Concerns
+
+**Analysis Date:** 2026-03-10
+
+## Tech Debt
+
+**Regex-based token replacement (critical):**
+
+- Issue: `src/utils/file-utils.ts` implements `replaceTokensInFiles` and constructs a RegExp with `new RegExp(token.from, "g")` regardless of whether `token.from` is a `string` or a `RegExp`.
+- Files: `src/utils/file-utils.ts`, callers in `src/utils/template-utils.ts`, `src/create/preset/create-preset.ts` (many tokens are passed as `RegExp` literals).
+- Impact: When `token.from` is already a `RegExp` and flags are passed as the second argument to `RegExp` constructor, Node throws a TypeError. This makes token replacement fragile and causes runtime exceptions in template updates. Tests and callers may swallow the error (see `tests/create-preset.test.ts`) so the issue can be silent in CI but still indicate a bug.
+- Fix approach: Update `replaceTokensInFiles` to detect `RegExp` values and use them directly, or construct a `RegExp` only when `token.from` is a string. Example change in `src/utils/file-utils.ts`:
+
+```ts
+const regex = token.from instanceof RegExp ? token.from : new RegExp(String(token.from), "g");
+data = data.replace(regex, token.to);
+```
+
+Applying this fix ensures RegExp arguments are respected and avoids TypeErrors.
+
+**Template JSON changes performed with regex (moderate):**
+
+- Issue: `src/utils/template-utils.ts` updates `package.json` and `package.dist.json` using regex replacements (`replaceTokensInFile`) instead of reading and writing JSON.
+- Files: `src/utils/template-utils.ts`, `src/create/preset/create-preset.ts`.
+- Impact: Regex-based edits are brittle: formatting differences, comments, CRLF vs LF, or unexpected matches can break JSON structure or fail to update fields correctly.
+- Fix approach: Parse the JSON files with `fs.readJSON` / `fs.writeJSON` and modify the relevant fields (name, description, repository, files). This is more robust and easier to test. Example target: update `updatePackageFile` to `const pkg = await fs.readJSON(pkgPath); pkg.name = packageName; await fs.writeJSON(pkgPath, pkg, { spaces: 2 });`
+
+## Known Bugs
+
+**RegExp constructor TypeError during replacements:**
+
+- Symptoms: Token replacement throws TypeError when token pattern is a `RegExp` and code calls `new RegExp(token.from, "g")`.
+- Files: `src/utils/file-utils.ts` (replacement implementation).
+- Trigger: Calling any create/template flow that passes `RegExp` literals into tokens (e.g., `src/create/preset/create-preset.ts`).
+- Workaround: Tests and callers often wrap calls in try/catch (see `tests/create-preset.test.ts`) so tests still assert package.json existence, masking the problem. Do not rely on that; fix the replacement implementation.
+
+## Security Considerations
+
+**Arbitrary script execution via `npm install` / `npm run build`:**
+
+- Area: `src/utils/template-utils.ts` functions `runInstall` and `runBuild` execute `npm install` and `npm run build` in generated projects.
+- Files: `src/utils/template-utils.ts`, `src/create/*` where `runInstall` and `runBuild` are invoked (e.g., `src/create/preset/create-preset.ts`).
+- Risk: Running `npm install` in a directory containing an attacker-controlled `package.json` can execute lifecycle scripts (postinstall, preinstall). The CLI currently runs installs automatically during template creation, which can execute arbitrary code on the user's machine.
+- Current mitigation: `lookpath("npm")` is used to avoid running when `npm` is not available, but this does not mitigate script execution risks.
+- Recommendation: Do not run `npm install` / `npm run build` automatically. Instead:
+  - Require an explicit flag (e.g., `--install`) to run automatic installs, or
+  - Use `npm ci --ignore-scripts` or `npm install --ignore-scripts` as a safer default, and clearly warn users before running scripts, or
+  - Prompt for confirmation before running `npm` and print the exact command being run.
+
+## Performance Bottlenecks
+
+**Use of `child_process.exec` for long-running, high-output commands (moderate):**
+
+- Area: `src/utils/template-utils.ts` and `src/utils/file-utils.ts` (the latter uses `exec` in `getRepositoryUrl`).
+- Files: `src/utils/template-utils.ts` (`runInstall`, `runBuild`), `src/utils/file-utils.ts` (`getRepositoryUrl`).
+- Problem: `exec` buffers the full stdout/stderr and has a default buffer size; heavy outputs (e.g., `npm install`) can overflow the buffer and cause the subprocess to fail. Also, using `exec` hides streaming logs from the user.
+- Improvement path: Use `child_process.spawn` with streaming of stdout/stderr and proper error/exit-code handling. Stream logs to the console or into a logger so users see progress.
+
+## Fragile Areas
+
+**Broad regex replacements over multiple file types (fragile):**
+
+- Files: `src/utils/file-utils.ts`, call sites in `src/utils/template-utils.ts` and `src/create/*`.
+- Why fragile: Replacing text with global regexes across files risks accidental substitution (e.g., replacing occurrences in unrelated files). It also makes reasoning about what changed difficult.
+- Safe modification: Limit replacements to specific files and, where possible, use structured transforms (JSON AST edits for `package.json`, templating tools for code files) rather than blind regex.
+
+**No centralized logging or structured errors (minor):**
+
+- Files: `src/cli.ts`, `src/build/*.ts`, `src/create/*` — modules log via `console` or propagate exceptions.
+- Why fragile: Lack of a central logger and consistent error formatting makes debugging and user-facing error messages inconsistent. Adding a simple logging utility (e.g., `src/utils/logger.ts`) and top-level error handling in `src/cli.ts` would improve UX.
+
+## Dependencies at Risk
+
+**Self-referential devDependency:**
+
+- Files: `package.json` lists `"@tsparticles/cli": "latest"` in `devDependencies`.
+- Risk: This can lead to confusing local development semantics. It is common for monorepo setups but should be intentional.
+- Migration plan: If not required, remove the self-reference. If needed for local testing, ensure a documented developer workflow.
+
+## Missing Critical Features
+
+**Safe-by-default template creation (missing):**
+
+- Problem: Template creation runs `npm install`/`npm run build` by default. There is no opt-in flag to skip these actions for safer, faster creation in CI or sandboxed environments.
+- Blocks: CI runs, offline usage, and security-conscious users.
+- Recommendation: Add a `--no-install` / `--skip-install` option to `create` commands or a top-level config, and ensure `runInstall`/`runBuild` respect that option.
+
+## Test Coverage Gaps
+
+**Replacement function tests (high priority):**
+
+- What's not tested: `replaceTokensInFiles` behavior when `token.from` is a `RegExp` object vs a `string` (no explicit unit tests for this edge case).
+- Files: `src/utils/file-utils.ts`, tests should be added under `tests/file-utils.test.ts` or similar.
+- Risk: Future regressions and silent failures in template flows.
+- Priority: High — add targeted unit tests that exercise both `string` and `RegExp` token inputs and verify no exceptions are thrown and replacements occur as expected.
+
+**Integration tests should avoid running real npm:**
+
+- What's not tested safely: `createPresetTemplate` currently calls `runInstall` and `runBuild` which invoke `npm` and may perform network operations in CI.
+- Files: `tests/create-preset.test.ts`, `src/utils/template-utils.ts`.
+- Recommendation: Mock `lookpath` and `child_process.exec` in tests, or refactor `runInstall`/`runBuild` to accept an injectable runner (dependency injection) so tests can inject a no-op runner.
+
+---
+
+_Concerns audit: 2026-03-10_

package/.planning/codebase/CONVENTIONS.md

@@ -1,3 +1,91 @@
-Conventions
-- TypeScript + Prettier + ESLint
-- Organize by feature
+# Coding Conventions
+
+**Analysis Date:** 2026-03-10
+
+## Naming Patterns
+
+Files:
+
+- Pattern: kebab-case for source filenames and CLI commands
+  - Examples: `src/create/create.ts`, `src/create/preset/create-preset.ts`, `src/build/build-tsc.ts`
+
+Functions:
+
+- Pattern: camelCase for free functions and helpers
+  - Examples: `replaceTokensInFile` in `src/utils/file-utils.ts`, `createPresetTemplate` in `src/create/preset/create-preset.ts`
+
+Variables:
+
+- Pattern: camelCase for local variables and constants; use `const` when value is not reassigned
+  - Examples: `destPath`, `camelizedName` in `src/create/shape/create-shape.ts`
+
+Types / Interfaces:
+
+- Pattern: PascalCase for interfaces and type names
+  - Examples: `ReplaceTokensOptions`, `ReplaceTokensData` in `src/utils/file-utils.ts`
+
+Exports:
+
+- Pattern: named exports from modules (no default exports observed)
+  - Examples: `export async function replaceTokensInFiles` in `src/utils/file-utils.ts`
+
+## Code Style
+
+Formatting:
+
+- Prettier is used via the package `prettier` and project config referenced in `package.json` (`prettier": "@tsparticles/prettier-config"`).
+  - Scripts: `prettify:src`, `prettify:readme`, `prettify:ci:src` in `package.json`
+
+Linting:
+
+- ESLint is configured in `eslint.config.js` and reuses `@tsparticles/eslint-config` (see `eslint.config.js`).
+  - Scripts: `lint` (auto-fix) and `lint:ci` in `package.json`
+  - Rule note: `no-console` is disabled in `eslint.config.js` to allow `console` usage in CLI code and tests.
+
+TypeScript:
+
+- Strict TypeScript settings are enabled in `tsconfig.json` (many `strict` flags set: `strict`, `noImplicitAny`, `noUnusedLocals`, etc.).
+
+Doc comments:
+
+- Use JSDoc/TSDoc style comments on exported functions and complex helpers.
+  - Examples: function headers in `src/utils/string-utils.ts`, `src/utils/template-utils.ts`.
+
+## Import Organization
+
+- Pattern observed: third-party packages first, then Node built-ins, then local relative imports.
+  - Example from `src/create/preset/create-preset.ts`:
+    - `import { camelize, capitalize, dash } from "../../utils/string-utils.js";`
+    - `import fs from "fs-extra"`; `import path from "node:path"`;
+
+Path aliases:
+
+- Not detected. Imports use relative paths (e.g., `../../utils/*`) and explicit `.js` extension when imported from tests or other ESM contexts.
+
+## Error Handling
+
+- Pattern: functions either throw synchronous errors (`throw new Error(...)`) for validation or reject Promises when asynchronous operations fail.
+  - Example: `getDestinationDir` throws `new Error("Destination folder already exists and is not empty")` in `src/utils/file-utils.ts`.
+  - Example: `runInstall`/`runBuild` use the `exec` callback to `reject(error)` in `src/utils/template-utils.ts`.
+
+## Logging
+
+- Pattern: CLI code and tests use `console` for informational output and debugging. ESLint `no-console` is turned off to permit this.
+  - Files: `src/cli.ts`, tests in `tests/*.test.ts` (see `tests/file-utils.test.ts` where `console.log`/`console.error` is used).
+
+## Comments and Documentation
+
+- Public helpers include JSDoc comments (examples in `src/utils/*`). Maintain comments for exported functions to describe parameters and return values.
+
+## Function & Module Design
+
+- Small single-responsibility functions are the norm (examples: `replaceTokensInFiles`, `updatePackageFile`, `copyEmptyTemplateFiles`).
+- Modules export multiple named helpers rather than a default export (see `src/utils/template-utils.ts`).
+
+## Barrel files
+
+- Not used. Individual modules are imported with relative paths.
+
+---
+
+_Convention analysis: 2026-03-10_

package/.planning/codebase/INTEGRATIONS.md

@@ -1,3 +1,82 @@
-External Integrations
-- GitHub Actions for CI
-- npm registry for publishing
+# External Integrations
+
+**Analysis Date:** 2026-03-10
+
+## APIs & External Services
+
+This project is a local CLI tool focused on scaffolding and building tsParticles-related packages. There are minimal external service integrations.
+
+**Repository / Git:**
+
+- Git: CLI uses the `git` binary when available to obtain repository URL (`src/utils/file-utils.ts` uses `lookpath("git")` and executes `git config --get remote.origin.url`). No other GitHub API integration detected.
+
+**NPM Registry:**
+
+- Publishing: GitHub Actions workflow publishes packages to npm registry (`.github/workflows/npm-publish.yml`) using `pnpm publish` against `https://registry.npmjs.org`.
+  - Auth: CI uses OIDC/GitHub Actions environment for authentication as configured in `.github/workflows/npm-publish.yml` (permissions include `id-token: write`).
+
+## Data Storage
+
+**Databases:**
+
+- Not detected. The CLI operates on the local filesystem; no database clients (e.g. PostgreSQL, MongoDB) are referenced in `src/`.
+
+**File Storage:**
+
+- Local filesystem via `fs-extra` (`src/utils/file-utils.ts` and many create/template helpers). Templates are copied from `files/*` into target directories (`src/create/*`, e.g. `src/create/plugin/create-plugin.ts` uses `files/create-plugin`).
+
+**Caching:**
+
+- Not detected. No Redis or in-process caching libraries observed.
+
+## Authentication & Identity
+
+**Auth Provider:**
+
+- None for runtime. CI publishes to npm using GitHub Actions OIDC flow (see `.github/workflows/npm-publish.yml`). There are no runtime OAuth or Identity providers integrated into the CLI.
+
+## Monitoring & Observability
+
+**Error Tracking:**
+
+- Not detected. No Sentry, Datadog, or similar SDKs in dependencies.
+
+**Logs:**
+
+- Console logging used throughout the CLI (`console.log`, `console.warn`, `console.error`). See `src/build/*` and `src/create/*` for examples (e.g. `src/build/build.ts`, `src/build/build-prettier.ts`).
+
+## CI/CD & Deployment
+
+**Hosting:**
+
+- NPM registry for package distribution. Source is maintained in GitHub and CI runs on GitHub Actions (`.github/workflows/*`).
+
+**CI Pipeline:**
+
+- GitHub Actions pipelines:
+  - `Node.js CI` (`.github/workflows/node.js-ci.yml`) runs on push and PRs to `main`: installs via `pnpm install`, runs `pnpm run build:ci` and `pnpm test`.
+  - `Publish Packages` (`.github/workflows/npm-publish.yml`) publishes tags `v*` to npm, using OIDC-based auth and `pnpm publish`.
+
+## Environment Configuration
+
+**Required env vars:**
+
+- Not enforced in repo code. CI publishing relies on GitHub Actions OIDC configured in workflow; no runtime environment variables are required by the CLI itself.
+
+**Secrets location:**
+
+- Not present in repo. CI uses OIDC in the publish workflow. No local secrets files detected (no `.env`).
+
+## Webhooks & Callbacks
+
+**Incoming:**
+
+- Not detected. This is a CLI tool; it does not expose HTTP endpoints.
+
+**Outgoing:**
+
+- Not detected. The CLI does not make outbound HTTP API calls; templates and README files reference public CDNs (jsDelivr) and GitHub URLs but no HTTP client libraries are used.
+
+---
+
+_Integration audit: 2026-03-10_

package/.planning/codebase/STACK.md

@@ -1,11 +1,91 @@
-Project Technology Stack
+# Technology Stack
 
-Languages & Runtimes
-- TypeScript (src/)
-- Node.js for CLI
+**Analysis Date:** 2026-03-10
 
-Tools
-- Vitest, tsc, pnpm
+## Languages
 
-Config locations
-- package.json, tsconfig.json
+**Primary:**
+
+- TypeScript 5.x (project uses `typescript` ^5.9.3) - used across CLI source under `src/` (`src/**/*.ts`). See `package.json` and `tsconfig.json` (`package.json`: `dependencies`/`devDependencies`, `tsconfig.json`: `compilerOptions`).
+
+**Secondary:**
+
+- JavaScript (Node ESM runtime output in `dist/` / CLI entry `dist/cli.js`) - `package.json` `type: "module"` and `bin` field (`package.json`).
+
+## Runtime
+
+**Environment:**
+
+- Node.js (ES module, NodeNext resolution). CI workflows use Node 24 (`.github/workflows/node.js-ci.yml`). `tsconfig.json` `module: "NodeNext"`, `target: "ESNext"`.
+
+**Package Manager:**
+
+- pnpm (project declares `packageManager: "pnpm@10.32.0"` in `package.json`, lock file `pnpm-lock.yaml` present).
+- Lockfile: `pnpm-lock.yaml` (present).
+
+## Frameworks
+
+**Core:**
+
+- None web-framework-specific. This is a CLI application built with Node and TypeScript. CLI command framework: `commander` (`package.json` -> `dependencies`), commands live in `src/cli.ts`, `src/build/*`, `src/create/*`.
+
+**Testing:**
+
+- Vitest (`vitest` ^4.x) - config file: `vitest.config.ts`, tests located in `tests/*.test.ts`.
+
+**Build/Dev:**
+
+- TypeScript compiler (`tsc`) is used for building (`scripts.build:ts*` in `package.json`, `tsconfig.json` and `src/tsconfig.json`).
+- Prettier for formatting (configured via dependency `@tsparticles/prettier-config` referenced in `package.json`). Prettier is run by `src/build/build-prettier.ts` and scripts in `package.json`.
+- ESLint (`eslint`) with `@tsparticles/eslint-config` - linting run in `src/build/build-eslint.ts` and via `package.json` scripts.
+- Webpack used for bundling (dependency `webpack`, `swc-loader`, `@swc/core`) - bundling logic in `src/build/build-bundle.ts`.
+- dependency-cruiser used for circular dependency checks - config `.dependency-cruiser.cjs` and script `circular-deps` in `package.json`.
+
+## Key Dependencies
+
+**Critical:**
+
+- `typescript` ^5.9.3 - primary language toolchain (`package.json`).
+- `commander` ^14.x - CLI command framework (`src/cli.ts`, `package.json`).
+- `fs-extra` ^11.x - filesystem utilities used widely (`src/utils/file-utils.ts`, `package.json`).
+- `prettier` ^3.8.x - formatting; project references `@tsparticles/prettier-config` (`package.json`).
+- `eslint` ^10.x and TypeScript ESLint tooling (`package.json`, `src/build/build-eslint.ts`).
+
+**Infrastructure / Build:**
+
+- `webpack` ^5.x, `swc-loader`, `@swc/core` - bundling and fast transpilation (`package.json`, `src/build/build-bundle.ts`).
+- `vitest` ^4.x - test runner (`vitest.config.ts`, `package.json`).
+- `klaw` - used by prettier tooling to walk folders (`src/build/build-prettier.ts`).
+
+**Utilities:**
+
+- `prompts` - interactive prompts used in templates/generator code (`package.json`, `src/create/*`).
+- `lookpath` - used to detect `git` presence in `src/utils/file-utils.ts`.
+
+## Configuration
+
+**Environment:**
+
+- No project-level `.env` files detected. The CLI uses the local environment (executes `git` where available). See `src/utils/file-utils.ts` (calls `lookpath("git")` and runs `git config --get remote.origin.url`).
+
+**Build:**
+
+- TypeScript config: `tsconfig.json` (root) and `src/tsconfig.json` (per-source) - `module: NodeNext`, `target: ESNext`, strict compiler options.
+- Linting config is provided by `@tsparticles/eslint-config` (referenced in `package.json`). A dependency-cruiser configuration is present at `.dependency-cruiser.cjs`.
+- Prettier config is supplied via `@tsparticles/prettier-config` and `package.json` scripts rely on `src/build/build-prettier.ts`.
+
+## Platform Requirements
+
+**Development:**
+
+- Node.js >= 24 recommended (CI uses Node 24 in `.github/workflows/node.js-ci.yml`).
+- pnpm >= 10.x (project `packageManager` sets `pnpm@10.32.0`).
+- Git CLI for repository URL resolution used by templates (`src/utils/file-utils.ts`).
+
+**Production / Publishing:**
+
+- Packages are published to npm registry (see `.github/workflows/npm-publish.yml`). The CI uses GitHub Actions and OIDC for auth when publishing (`.github/workflows/npm-publish.yml`).
+
+---
+
+_Stack analysis: 2026-03-10_

package/.planning/codebase/STRUCTURE.md

@@ -1,3 +1,138 @@
-Structure
-- src/, files/, .github/
-- templates in files/
+# Codebase Structure
+
+**Analysis Date:** 2026-03-10
+
+## Directory Layout
+
+```
+[project-root]/
+├── src/                 # TypeScript source for CLI and build tasks
+│   ├── cli.ts           # CLI entrypoint (registers commands)
+│   ├── create/          # "create" command and subcommands
+│   │   ├── create.ts
+│   │   ├── plugin/
+│   │   │   ├── plugin.ts
+│   │   │   └── create-plugin.ts
+│   │   ├── preset/
+│   │   │   ├── preset.ts
+│   │   │   └── create-preset.ts
+│   │   └── shape/
+│   │       ├── shape.ts
+│   │       └── create-shape.ts
+│   ├── build/           # Build helper commands/tasks
+│   │   ├── build.ts
+│   │   ├── build-tsc.ts
+│   │   ├── build-bundle.ts
+│   │   └── ...
+│   └── utils/           # Shared utilities
+│       ├── file-utils.ts
+│       ├── template-utils.ts
+│       └── string-utils.ts
+├── files/               # Template files used by generators (not under src/ but referenced)
+├── tests/               # Vitest unit tests
+├── dist/                # Compiled ESM output (generated)
+├── package.json
+├── pnpm-lock.yaml
+├── tsconfig.json
+└── .planning/           # Mapping and planning docs
+```
+
+## Directory Purposes
+
+**src/**:
+
+- Purpose: Source code for the CLI tool and internal build tasks.
+- Contains: Command modules (`src/create/*`), build tasks (`src/build/*`), utilities (`src/utils/*`).
+- Key files: `src/cli.ts`, `src/create/create.ts`, `src/create/preset/create-preset.ts`.
+
+**src/create/**:
+
+- Purpose: Implements the `create` command and its subcommands.
+- Contains: `plugin`, `preset`, `shape` subfolders each exposing a `Command` instance and a template-creation implementation (`create-*.ts`).
+- Key files: `src/create/preset/preset.ts`, `src/create/preset/create-preset.ts`.
+
+**src/build/**:
+
+- Purpose: Build and CI helper tasks used by `pnpm run build` and `build` CLI command.
+- Contains: modular build steps: `build-prettier.ts`, `build-eslint.ts`, `build-tsc.ts`, bundling helpers.
+- Key files: `src/build/build.ts` (aggregator), `src/build/build-tsc.ts`.
+
+**src/utils/**:
+
+- Purpose: Shared helpers for filesystem operations, string handling, and template updates.
+- Contains: `file-utils.ts` (`replaceTokensInFile`, `getDestinationDir`), `template-utils.ts` (`runInstall`, `runBuild`, `updatePackageFile`).
+
+**files/**:
+
+- Purpose: Template projects that are copied into new destinations by `create` commands.
+- Note: Referenced by `src/create/*` code via relative paths (e.g., `path.join(__dirname, "..", "..", "files", "create-preset")` in `src/create/preset/create-preset.ts`).
+
+**tests/**:
+
+- Purpose: Unit tests using Vitest for template creation behavior.
+- Contains: `tests/create-shape.test.ts`, `tests/create-preset.test.ts`.
+
+## Key File Locations
+
+Entry Points:
+
+- `src/cli.ts`: boots the program, reads package version from `package.json`, registers `build` and `create` commands.
+
+Create commands:
+
+- `src/create/create.ts`: aggregates subcommands.
+- `src/create/preset/preset.ts`: CLI surface for `preset` command.
+- `src/create/preset/create-preset.ts`: implementation that writes files and runs install/build.
+
+Utilities:
+
+- `src/utils/file-utils.ts`: token replacement helpers and repository detection.
+- `src/utils/template-utils.ts`: file copying, package updates and running `npm` commands.
+
+Build tasks:
+
+- `src/build/build.ts`: orchestration of build steps called both in CI and local `pnpm run build`.
+
+## Naming Conventions
+
+Files:
+
+- Pattern: kebab-case for file names that represent commands or grouped concerns (e.g., `create-preset.ts`, `build-tsc.ts`).
+- Source modules are TypeScript (`.ts`) compiled to ESM JS in `dist/`.
+
+Directories:
+
+- Pattern: singular, descriptive names (`create`, `build`, `utils`, `files`).
+
+## Where to Add New Code
+
+New Feature (CLI command):
+
+- Primary code: add a new command module under `src/<feature>/` or create a subcommand under `src/create/`.
+- Registration: register the new `Command` in `src/cli.ts` or in `src/create/create.ts` for `create`-subcommands.
+- Tests: add unit tests under `tests/` following existing patterns (`tests/<feature>.test.ts`).
+
+New Utility:
+
+- Implementation: add new helper in `src/utils/` and export named functions; reuse in command modules.
+- Examples: `src/utils/new-util.ts` and update `src/utils/index.ts` (if created) to re-export it.
+
+Templates and Files:
+
+- Add new templates under `files/` and reference them from create implementations using `path.join(__dirname, "..", "..", "files", "<template>")`.
+
+## Special Directories
+
+dist/:
+
+- Purpose: Compiled ESM output for packaging and the `bin` entry (`dist/cli.js`).
+- Generated: Yes
+- Committed: No (should be generated during build)
+
+tests/tmp-files/:
+
+- Purpose: Tests write temporary projects into `tests/tmp-files/*` during execution and remove them afterwards (see `tests/*.test.ts`).
+
+---
+
+_Structure analysis: 2026-03-10_