@tsparticles/cli 3.3.0 → 3.3.1

package/.planning/codebase/ARCHITECTURE.md

@@ -1,3 +1,100 @@
-Architecture Overview
-- CLI entrypoint: src/cli.ts
-- Feature modules: src/create, src/build
+# Architecture
+
+**Analysis Date:** 2026-03-08
+
+## Pattern Overview
+
+**Overall:** Modular CLI application structured as command modules (command-per-file) with utility layers for filesystem and template operations.
+
+**Key Characteristics:**
+
+- Command-oriented boundaries implemented with `commander` (commands registered in `src/cli.ts` and `src/create/*`, `src/build/*`).
+- Utilities are centralized under `src/utils/` for file operations, templating, and string manipulation.
+- Build-related logic is under `src/build/` and creation/template generation logic under `src/create/`.
+
+## Layers
+
+**CLI / Entry Layer:**
+
+- Purpose: Expose CLI commands and wiring.
+- Location: `src/cli.ts`
+- Contains: Program initialization, command registration (`build`, `create`).
+- Depends on: `src/build/*`, `src/create/*`.
+- Used by: End users invoking the installed binary.
+
+**Command Implementations:**
+
+- Purpose: Implement individual subcommands for build and create flows.
+- Location: `src/create/*` (e.g. `src/create/create.ts`, `src/create/preset/*`, `src/create/plugin/*`, `src/create/shape/*`) and `src/build/*` (e.g. `src/build/build.ts`, `src/build/build-*.ts`).
+- Contains: Command definitions, argument parsing (uses `commander`), orchestration of utilities.
+- Depends on: `src/utils/*` for filesystem and templating, `fs-extra`, `prettier`, `webpack` where needed.
+
+**Utilities / Core Logic:**
+
+- Purpose: Reusable helpers for file operations, token replacement, template manipulation, and string utilities.
+- Location: `src/utils/` (`file-utils.ts`, `template-utils.ts`, `string-utils.ts`).
+- Contains: `replaceTokensInFile`, `runInstall`, `runBuild`, copy filter helpers, string transforms.
+- Depends on: `fs-extra`, `lookpath`, `child_process` (`exec`).
+
+**Files & Templates:**
+
+- Purpose: Template resources used to scaffold projects.
+- Location: `files/` (e.g., `files/create-shape`, `files/create-preset`, `files/create-plugin`, `files/empty-project`).
+
+## Data Flow
+
+Create flow (example `create shape`):
+
+1. User runs CLI: `tsparticles-cli create shape <dest>` (`src/cli.ts` -> `src/create/create.ts` -> `src/create/shape/*`).
+2. Command handler calls `createShapeTemplate` in `src/create/shape/create-shape.ts`.
+3. `createShapeTemplate` copies template files from `files/create-shape` to destination using `fs-extra` and `template-utils.copyEmptyTemplateFiles`.
+4. Token replacement and file updates are performed using `src/utils/file-utils.ts` functions like `replaceTokensInFile` and helpers in `src/utils/template-utils.ts`.
+5. Optional lifecycle commands `runInstall` and `runBuild` invoke external commands (`npm install`, `npm run build`) via `child_process.exec` if `npm` is present (checked via `lookpath`).
+
+State Management:
+
+- Stateless CLI; state is the filesystem and created project files. No in-memory long-lived state across runs.
+
+## Key Abstractions
+
+**Template Updater:**
+
+- Purpose: Replace tokens and update produced scaffold files.
+- Examples: `src/utils/file-utils.ts` (`replaceTokensInFile`), `src/utils/template-utils.ts` (`updatePackageFile`, `updateWebpackFile`, `updatePackageDistFile`).
+- Pattern: Imperative token-replacement using regexes and file writes.
+
+**Command Modules:**
+
+- Purpose: Each subcommand is an isolated module exposing a `Command` (from `commander`).
+- Examples: `src/create/create.ts`, `src/build/build.ts`, `src/create/shape/create-shape.ts`.
+
+## Entry Points
+
+**CLI Entrypoint:**
+
+- Location: `src/cli.ts`
+- Triggers: Node process when user runs `tsparticles-cli` or package `bin` mapping.
+- Responsibilities: Read package version (`package.json`), register commands and parse args.
+
+## Error Handling
+
+Strategy:
+
+- Try/catch around file operations and external command execution; errors logged to console with `console.error` and boolean success values returned (e.g., `src/build/*` functions return `Promise<boolean>`). Examples: `src/build/build-prettier.ts`, `src/build/build-bundle.ts`.
+
+Patterns:
+
+- Propagate failures by throwing or returning `false` and logging details.
+- `replaceTokensInFiles` performs read/replace/write with no specialized rollback.
+
+## Cross-Cutting Concerns
+
+Logging: `console.log`, `console.warn`, `console.error` used across `src/build/*` and `src/utils/*`.
+
+Validation: Input validation is minimal — `commander` performs CLI argument parsing; `getDestinationDir` validates destination directory emptiness in `src/utils/file-utils.ts`.
+
+Authentication: Not applicable; tool is local and does not call external authenticated services.
+
+---
+
+_Architecture analysis: 2026-03-08_

package/.planning/codebase/CONCERNS.md

@@ -1,3 +1,102 @@
-Concerns
-- Some build scripts may lack tests
-- CI secrets should be reviewed
+# Codebase Concerns
+
+**Analysis Date:** 2026-03-08
+
+## Tech Debt
+
+1. Minimal input validation and transactional safety when writing files
+
+- Issue: `replaceTokensInFiles` and other template-updating functions perform read/replace/write in-place without atomic writes or rollback. A failed intermediate step can leave partially updated files.
+- Files: `src/utils/file-utils.ts`, `src/utils/template-utils.ts`, `src/create/shape/create-shape.ts`
+- Impact: Corrupted template output when an operation fails mid-flow; harder to recover from errors.
+- Fix approach: Write to temporary files and rename atomically (use `fs-extra` `outputFile` + `move`), or create the target in a staging directory and move into destination once all transformations succeed.
+
+2. Running external commands directly in template flow (`npm install`, `npm run build`)
+
+- Issue: `runInstall` and `runBuild` call `exec("npm install")` and `exec("npm run build")` without timeouts or stdout/stderr piping; they rely on `lookpath` only.
+- Files: `src/utils/template-utils.ts` (functions `runInstall`, `runBuild`)
+- Impact: Tests or CI running on environments lacking `npm` may silently skip or hang if `lookpath` returns true but command misbehaves; poor control over failure modes.
+- Fix approach: Use spawned child process with streaming logs and a configurable timeout, or provide a dry-run flag. In tests, mock these exec calls to avoid long-running operations.
+
+3. Prettier plugin compatibility workaround
+
+- Issue: `src/build/build-prettier.ts` contains a TODO disabling Prettier check for `prettier-plugin-multiline-arrays` compatibility with Prettier 3.0.0.
+- Files: `src/build/build-prettier.ts` (line with TODO)
+- Impact: Formatting checks may be inconsistent across CI and local dev environments.
+- Fix approach: Update dependencies to versions compatible with Prettier 3.x or pin Prettier to a compatible 2.x in CI until plugins are updated. Add a CI check that fails early with a clear error message.
+
+## Known Bugs
+
+None detected by static analysis in the repository. Tests pass in CI (workflow present) but no failing patterns discovered in code scan.
+
+## Security Considerations
+
+1. Running external commands with user-provided template inputs
+
+- Risk: If destination paths or template tokens contain malicious content, shell commands executed via `exec` could be abused.
+- Files: `src/utils/template-utils.ts` (`runInstall`, `runBuild`), `src/utils/file-utils.ts` (token replacement using regex from code, not user input directly).
+- Current mitigation: `exec` is invoked with static commands (`npm install`) and not interpolated with user-supplied strings. `replaceTokensInFile` uses regex replacements defined in code.
+- Recommendation: Avoid invoking shell with interpolated user input. If needed, sanitize inputs and prefer `spawn` with argument arrays.
+
+2. Reading git remote URL via `exec` in `getRepositoryUrl`
+
+- Risk: `exec` result is returned directly; if git not present it rejects.
+- Files: `src/utils/file-utils.ts` (`getRepositoryUrl`)
+- Recommendation: Wrap with timeout and sanitize output before using it in template substitution.
+
+## Performance Bottlenecks
+
+1. Synchronous/serial file traversal in prettify
+
+- Problem: `prettier` formatting in `prettifySrc` iterates files sequentially (`for await (const file of klaw(srcPath))`), performing `prettier.resolveConfig` per file which may be expensive.
+- Files: `src/build/build-prettier.ts`
+- Cause: Recomputing config and formatting each file sequentially.
+- Improvement path: Resolve config once outside the loop, run formatting in parallel batches, and avoid repeated IO for options.
+
+## Fragile Areas
+
+1. Regex-based token replacement
+
+- Files: `src/utils/file-utils.ts`, `src/utils/template-utils.ts`, `src/create/*` token replacement usage
+- Why fragile: Regexes operate on file contents and can unintentionally match similar substrings; no schema validation after replacement.
+- Safe modification: Add tests for each token replacement case, and perform replacements against structured JSON (for `package.json`) using AST parsing where possible.
+- Test coverage: Token replacement used heavily but tests exercise many flows; add more unit tests for edge cases.
+
+## Scaling Limits
+
+Not applicable: CLI scaffolding and local build tool; not intended for high-concurrency server workloads.
+
+## Dependencies at Risk
+
+1. Prettier plugin `prettier-plugin-multiline-arrays`
+
+- Risk: Incompatibility with Prettier 3.x noted in `src/build/build-prettier.ts` TODO.
+- Impact: Formatting and CI checks could be disrupted.
+- Migration plan: Upgrade plugin or pin Prettier; monitor plugin releases.
+
+## Missing Critical Features
+
+1. No centralized logging or telemetry
+
+- Problem: Uses `console.*` directly; no centralized structured logs for debugging CI or for library consumers.
+- Blocks: Advanced observability and consistent log levels.
+
+## Test Coverage Gaps
+
+1. Lack of mocks for external process execution
+
+- What's not tested: Behavior of `runInstall`/`runBuild` when `npm` present and when the commands fail.
+- Files: `src/utils/template-utils.ts` and tests in `tests/` currently avoid actually running `npm` by relying on environment; but there are no unit tests mocking `exec`.
+- Risk: Breakage during publish/cmd execution might not be caught in unit tests.
+- Priority: Medium — add tests that stub `child_process.exec` and `lookpath` to verify behavior on success and failure.
+
+2. Token replacement edge cases
+
+- What's not tested: Regex collisions and JSON-encoded fields in `package.json` and `package.dist.json` replacements.
+- Files: `src/utils/file-utils.ts`, `src/utils/template-utils.ts`
+- Risk: Incorrect package metadata produced for scaffolds.
+- Priority: High — add unit tests that run replacements on fixture files with edge-case tokens.
+
+---
+
+_Concerns audit: 2026-03-08_

package/.planning/codebase/CONVENTIONS.md

@@ -1,3 +1,96 @@
-Conventions
-- TypeScript + Prettier + ESLint
-- Organize by feature
+# Coding Conventions
+
+**Analysis Date:** 2026-03-08
+
+## Naming Patterns
+
+Files:
+
+- Source files are placed under feature directories (e.g., `src/create/shape/create-shape.ts`). Use descriptive names matching the feature.
+
+Functions:
+
+- Use camelCase for function names (e.g., `createShapeTemplate` in `src/create/shape/create-shape.ts`, `replaceTokensInFile` in `src/utils/file-utils.ts`).
+
+Variables:
+
+- Use camelCase for variables and constants. TypeScript types use PascalCase.
+
+Types:
+
+- Interfaces and types use PascalCase (e.g., `ReplaceTokensOptions`, `ReplaceTokensData` in `src/utils/file-utils.ts`).
+
+## Code Style
+
+Formatting:
+
+- Prettier is the formatting tool; root `package.json` sets `prettier` to `@tsparticles/prettier-config`. Formatting settings are applied in `src/build/build-prettier.ts` (printWidth 120, tabWidth 2, endOfLine lf).
+
+Linting:
+
+- ESLint config in `eslint.config.js` extends `@tsparticles/eslint-config`. Linting is enforced in `package.json` scripts (`lint`, `lint:ci`) and CI runs `pnpm run lint:ci` in `node.js-ci.yml`.
+
+## Import Organization
+
+Order:
+
+1. Node built-ins (e.g., `path`, `fs-extra` import as `fs`)
+2. External dependencies (e.g., `commander`, `prompts`)
+3. Internal modules (relative imports under `src/`)
+
+Examples: `src/cli.ts` imports `buildCommand` and `createCommand` from local modules after Node imports.
+
+Path Aliases:
+
+- None detected. Imports use relative paths and package names. Keep using relative imports within `src/`.
+
+## Error Handling
+
+Patterns:
+
+- Use try/catch around file system operations and external command execution; log errors with `console.error` (see `src/build/*.ts`, `src/utils/*`).
+- Functions that perform operations return boolean success flags (`Promise<boolean>`) where appropriate (e.g., `src/build/build-prettier.ts`, `src/build/build-bundle.ts`).
+
+## Logging
+
+Framework: console
+
+Patterns:
+
+- Use `console.log` for informational messages, `console.warn` for warnings, `console.error` for errors. Follow existing use in `src/build/*` and `src/utils/*`.
+
+## Comments
+
+When to Comment:
+
+- Use JSDoc/TSDoc comments for exported functions and modules. Code contains JSDoc-style function headers (e.g., `src/build/build-prettier.ts`).
+
+JSDoc/TSDoc:
+
+- Use TSDoc/JSDoc annotations for function parameters and return values on public utilities.
+
+## Function Design
+
+Size:
+
+- Functions typically remain under ~200 lines and perform a single responsibility (e.g., `createShapeTemplate` orchestrates template copying and updates but delegates to small helpers).
+
+Parameters:
+
+- Prefer explicit parameters and typed signatures. Existing functions are strongly typed (see `tsconfig.json` with `strict: true`).
+
+Return Values:
+
+- Use typed return values (`Promise<void>`, `Promise<boolean>`) and avoid implicit `any`.
+
+## Module Design
+
+Exports:
+
+- Modules export named functions (e.g., `export async function createShapeTemplate ...` in `src/create/shape/create-shape.ts`). Prefer named exports.
+  Barrel Files:
+- Not used. Add explicit exports per-file instead of index barrel files unless a clear grouping is required.
+
+---
+
+_Convention analysis: 2026-03-08_

package/.planning/codebase/INTEGRATIONS.md

@@ -1,3 +1,73 @@
-External Integrations
-- GitHub Actions for CI
-- npm registry for publishing
+# External Integrations
+
+**Analysis Date:** 2026-03-08
+
+## APIs & External Services
+
+No cloud SDKs (Stripe, AWS, Supabase, etc.) detected in `src/` imports. Searches for common providers returned no matches.
+
+## Data Storage
+
+**Databases:**
+
+- Not detected. No database clients (pg/mysql/mongodb) are imported in `src/`.
+
+**File Storage:**
+
+- Local filesystem via `fs-extra` used throughout (`src/utils/file-utils.ts`, `src/utils/template-utils.ts`, `src/create/*`) to read/write project templates and package files.
+
+**Caching:**
+
+- None detected.
+
+## Authentication & Identity
+
+**Auth Provider:**
+
+- Not applicable. This is a local CLI tool and does not integrate with external auth providers.
+
+## Monitoring & Observability
+
+**Error Tracking:**
+
+- None detected (no Sentry / Datadog / Rollbar SDK imports).
+
+**Logs:**
+
+- Standard console logging (`console.log`, `console.error`, `console.warn`) used throughout build and template utilities (e.g., `src/build/*`, `src/utils/*`).
+
+## CI/CD & Deployment
+
+**Hosting:**
+
+- NPM registry publishes defined in `.github/workflows/npm-publish.yml` (publishes on tags `v*`).
+
+**CI Pipeline:**
+
+- GitHub Actions workflows:
+  - `/.github/workflows/node.js-ci.yml` runs on push and pull_request for `main`, executes `pnpm install`, `pnpm run build:ci`, and `pnpm test`.
+  - `/.github/workflows/npm-publish.yml` publishes package on version tags using OIDC-based authentication.
+
+## Environment Configuration
+
+**Required env vars:**
+
+- No application runtime env vars detected in source. CI workflows rely on GitHub OIDC and standard GitHub Actions environment variables.
+
+**Secrets location:**
+
+- No secrets files in repo. GitHub publishing uses built-in OIDC and repository permissions configured in the workflow (`id-token: write`).
+
+## Webhooks & Callbacks
+
+**Incoming:**
+
+- None detected.
+
+**Outgoing:**
+
+- None detected.
+
+---
+
+_Integration audit: 2026-03-08_

package/.planning/codebase/STACK.md

@@ -1,11 +1,85 @@
-Project Technology Stack
+# Technology Stack
 
-Languages & Runtimes
-- TypeScript (src/)
-- Node.js for CLI
+**Analysis Date:** 2026-03-08
 
-Tools
-- Vitest, tsc, pnpm
+## Languages
 
-Config locations
-- package.json, tsconfig.json
+**Primary:**
+
+- TypeScript (>=5.x) - used across the entire codebase in `src/` (e.g. `src/cli.ts`, `src/create/*`, `src/build/*`)
+
+**Secondary:**
+
+- JavaScript (Node) - runtime JS emitted to `dist/` (package `type` set to `module` in `package.json`)
+
+## Runtime
+
+**Environment:**
+
+- Node.js 24 (CI uses `actions/setup-node` with `node-version: "24"` in `.github/workflows/node.js-ci.yml`)
+
+**Package Manager:**
+
+- pnpm (declared in `package.json` via `packageManager`: `pnpm@10.31.0`)
+- Lockfile present: `pnpm-lock.yaml`
+
+## Frameworks
+
+**Core:**
+
+- None web-framework specific. This is a CLI application built with Node and TypeScript. Entry point: `src/cli.ts`.
+
+**CLI/Command parsing:**
+
+- `commander` (`src/cli.ts`, `src/create/create.ts`, `src/build/*`) - used to declare commands and subcommands.
+
+**Testing:**
+
+- `vitest` (configured in `vitest.config.ts`, tests in `tests/*.test.ts`)
+
+**Build/Dev:**
+
+- `typescript` for compilation (`tsc -p src`, see `package.json` scripts)
+- `webpack` used by some build tasks (see `src/build/build-bundle.ts` importing `webpack`)
+- `swc` (`@swc/core`) is listed as dependency (used by some tooling or downstream tasks)
+
+## Key Dependencies
+
+**Critical:**
+
+- `commander` - command-line parsing (`src/cli.ts`)
+- `fs-extra` - filesystem utilities used widely (`src/utils/*`, `src/create/*`, `src/build/*`)
+- `prettier` - formatting (`src/build/build-prettier.ts`)
+- `typescript` - language (dev dependency and build target)
+
+**Infrastructure / Tooling:**
+
+- `prompts` - interactive prompts for the `create` subcommands (`src/create/*`)
+- `lookpath` - used to detect external commands (`src/utils/template-utils.ts`, `src/utils/file-utils.ts`)
+- `webpack` - bundling (`src/build/build-bundle.ts`)
+- `vitest` - testing runner (`tests/*.test.ts`, `vitest.config.ts`)
+
+## Configuration
+
+**Environment:**
+
+- No `.env` usage detected. CI sets Node version and runs pnpm in GitHub workflows (`.github/workflows/*.yml`).
+
+**Build:**
+
+- TypeScript config: `tsconfig.json` (root) and `src/tsconfig.json` included via `eslint.config.js` (parserOptions.project).
+- Build scripts are defined in `package.json` (e.g. `pnpm run build`, `pnpm run build:ci`, `pnpm run build:ts:cjs`)
+
+## Platform Requirements
+
+**Development:**
+
+- Node.js 24+, pnpm (v10+), git - used by scripts and utilities (`src/utils/file-utils.ts` uses `git` if available)
+
+**Production / Distribution:**
+
+- Packaged as npm package (`publishConfig` in `package.json` and `npm-publish` workflow). Outputs are placed under `dist/` and CLI binary `dist/cli.js` (`bin` in `package.json`).
+
+---
+
+_Stack analysis: 2026-03-08_

package/.planning/codebase/STRUCTURE.md

@@ -1,3 +1,104 @@
-Structure
-- src/, files/, .github/
-- templates in files/
+# Codebase Structure
+
+**Analysis Date:** 2026-03-08
+
+## Directory Layout
+
+```
+[project-root]/
+├── src/                 # TypeScript source for the CLI
+│   ├── build/           # Build command implementations and helpers
+│   ├── create/          # Create command implementations (preset, plugin, shape)
+│   └── utils/           # Shared utilities (file, template, string helpers)
+├── files/               # Template files used by create commands
+├── tests/               # Vitest unit tests for utilities and create flows
+├── dist/                # Build output (generated, should be ignored)
+├── package.json         # NPM package config and scripts
+├── pnpm-lock.yaml       # Lockfile for pnpm
+├── tsconfig.json        # TypeScript compiler options
+└── .github/workflows/   # CI and publish workflows
+```
+
+## Directory Purposes
+
+**`src/`**:
+
+- Purpose: Primary implementation in TypeScript.
+- Contains: `src/cli.ts`, `src/build/*`, `src/create/*`, `src/utils/*`.
+- Key files: `src/cli.ts` (entry), `src/create/create.ts`, `src/build/build.ts`, `src/utils/file-utils.ts`.
+
+**`files/`**:
+
+- Purpose: Scaffolding templates used by the create commands.
+- Contains: `files/create-shape`, `files/create-preset`, `files/create-plugin`, `files/empty-project`.
+
+**`tests/`**:
+
+- Purpose: Unit tests executed by `vitest`.
+- Contains: tests validating template creation and utility behavior (e.g., `tests/create-shape.test.ts`, `tests/file-utils.test.ts`).
+
+**`dist/`**:
+
+- Purpose: Output of compilation/build process. Generated; not committed.
+
+## Key File Locations
+
+**Entry Points:**
+
+- `src/cli.ts`: CLI program creation and command registration.
+
+**Configuration:**
+
+- `package.json`: scripts, dependencies, package metadata.
+- `tsconfig.json`: TypeScript configuration.
+- `vitest.config.ts`: Test runner configuration.
+
+**Core Logic:**
+
+- `src/utils/file-utils.ts`: token replacement, destination directory checks, git repository lookup.
+- `src/utils/template-utils.ts`: template transformers, copy helpers, npm build/install invocations.
+
+**Commands:**
+
+- `src/create/*`: `src/create/create.ts`, `src/create/preset/*`, `src/create/plugin/*`, `src/create/shape/*`.
+- `src/build/*`: `build.ts`, `build-prettier.ts`, `build-bundle.ts`, `build-tsc.ts`, `build-eslint.ts`, `build-distfiles.ts`, `build-diststats.ts`.
+
+## Naming Conventions
+
+Files:
+
+- Kebab-case for templates/files under `files/`.
+- Source files in `src/` use `camelCase` or `kebab-case` depending on purpose; commands grouped into directories named by feature.
+
+Directories:
+
+- Feature directories under `src/` (e.g., `create`, `build`, `utils`).
+
+## Where to Add New Code
+
+New Feature (command):
+New Component/Module:
+
+- Implementation: `src/utils/` for shared helpers, or `src/<feature>/` if feature-specific.
+- Export public helpers from their files; avoid adding global side-effects.
+
+Utilities:
+
+- Shared helpers: `src/utils/`.
+- If utility is generic, add tests in `tests/` and export clearly-typed interfaces.
+
+## Special Directories
+
+`files/`:
+
+- Purpose: Template assets for project scaffolding.
+- Generated: No
+- Committed: Yes
+
+`tests/`:
+
+- Purpose: Contains unit tests. Committed: Yes
+
+---
+
+_Structure analysis: 2026-03-08_