@tsparticles/cli 3.3.1 → 3.3.3

package/.planning/codebase/INTEGRATIONS.md

@@ -1,73 +1,82 @@
 # External Integrations
 
-**Analysis Date:** 2026-03-08
+**Analysis Date:** 2026-03-10
 
 ## APIs & External Services
 
-No cloud SDKs (Stripe, AWS, Supabase, etc.) detected in `src/` imports. Searches for common providers returned no matches.
+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. No database clients (pg/mysql/mongodb) are imported in `src/`.
+- 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` used throughout (`src/utils/file-utils.ts`, `src/utils/template-utils.ts`, `src/create/*`) to read/write project templates and package files.
+- 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:**
 
-- None detected.
+- Not detected. No Redis or in-process caching libraries observed.
 
 ## Authentication & Identity
 
 **Auth Provider:**
 
-- Not applicable. This is a local CLI tool and does not integrate with external auth providers.
+- 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:**
 
-- None detected (no Sentry / Datadog / Rollbar SDK imports).
+- Not detected. No Sentry, Datadog, or similar SDKs in dependencies.
 
 **Logs:**
 
-- Standard console logging (`console.log`, `console.error`, `console.warn`) used throughout build and template utilities (e.g., `src/build/*`, `src/utils/*`).
+- 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 publishes defined in `.github/workflows/npm-publish.yml` (publishes on tags `v*`).
+- NPM registry for package distribution. Source is maintained in GitHub and CI runs on GitHub Actions (`.github/workflows/*`).
 
 **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.
+- 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:**
 
-- No application runtime env vars detected in source. CI workflows rely on GitHub OIDC and standard GitHub Actions environment variables.
+- 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:**
 
-- No secrets files in repo. GitHub publishing uses built-in OIDC and repository permissions configured in the workflow (`id-token: write`).
+- Not present in repo. CI uses OIDC in the publish workflow. No local secrets files detected (no `.env`).
 
 ## Webhooks & Callbacks
 
 **Incoming:**
 
-- None detected.
+- Not detected. This is a CLI tool; it does not expose HTTP endpoints.
 
 **Outgoing:**
 
-- None detected.
+- 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-08_
+_Integration audit: 2026-03-10_

package/.planning/codebase/STACK.md

@@ -1,85 +1,91 @@
 # Technology Stack
 
-**Analysis Date:** 2026-03-08
+**Analysis Date:** 2026-03-10
 
 ## Languages
 
 **Primary:**
 
-- TypeScript (>=5.x) - used across the entire codebase in `src/` (e.g. `src/cli.ts`, `src/create/*`, `src/build/*`)
+- 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) - runtime JS emitted to `dist/` (package `type` set to `module` in `package.json`)
+- 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 24 (CI uses `actions/setup-node` with `node-version: "24"` in `.github/workflows/node.js-ci.yml`)
+- 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 (declared in `package.json` via `packageManager`: `pnpm@10.31.0`)
-- Lockfile present: `pnpm-lock.yaml`
+- 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. Entry point: `src/cli.ts`.
-
-**CLI/Command parsing:**
-
-- `commander` (`src/cli.ts`, `src/create/create.ts`, `src/build/*`) - used to declare commands and subcommands.
+- 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` (configured in `vitest.config.ts`, tests in `tests/*.test.ts`)
+- Vitest (`vitest` ^4.x) - config file: `vitest.config.ts`, tests located 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)
+- 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:**
 
-- `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)
+- `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`).
 
-**Infrastructure / Tooling:**
+**Utilities:**
 
-- `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`)
+- `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 `.env` usage detected. CI sets Node version and runs pnpm in GitHub workflows (`.github/workflows/*.yml`).
+- 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` 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`)
+- 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+, pnpm (v10+), git - used by scripts and utilities (`src/utils/file-utils.ts` uses `git` if available)
+- 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 / Distribution:**
+**Production / Publishing:**
 
-- 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`).
+- 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-08_
+_Stack analysis: 2026-03-10_

package/.planning/codebase/STRUCTURE.md

@@ -1,104 +1,138 @@
 # Codebase Structure
 
-**Analysis Date:** 2026-03-08
+**Analysis Date:** 2026-03-10
 
 ## 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
+├── 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/`**:
+**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`.
+- 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`.
 
-**`files/`**:
+**src/create/**:
 
-- Purpose: Scaffolding templates used by the create commands.
-- Contains: `files/create-shape`, `files/create-preset`, `files/create-plugin`, `files/empty-project`.
+- 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`.
 
-**`tests/`**:
+**src/build/**:
 
-- 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`).
+- 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`.
 
-**`dist/`**:
+**src/utils/**:
 
-- Purpose: Output of compilation/build process. Generated; not committed.
+- 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:**
+Entry Points:
 
-- `src/cli.ts`: CLI program creation and command registration.
+- `src/cli.ts`: boots the program, reads package version from `package.json`, registers `build` and `create` commands.
 
-**Configuration:**
+Create commands:
 
-- `package.json`: scripts, dependencies, package metadata.
-- `tsconfig.json`: TypeScript configuration.
-- `vitest.config.ts`: Test runner configuration.
+- `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.
 
-**Core Logic:**
+Utilities:
 
-- `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.
+- `src/utils/file-utils.ts`: token replacement helpers and repository detection.
+- `src/utils/template-utils.ts`: file copying, package updates and running `npm` commands.
 
-**Commands:**
+Build tasks:
 
-- `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`.
+- `src/build/build.ts`: orchestration of build steps called both in CI and local `pnpm run build`.
 
 ## 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.
+- 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:
 
-- Feature directories under `src/` (e.g., `create`, `build`, `utils`).
+- Pattern: singular, descriptive names (`create`, `build`, `utils`, `files`).
 
 ## Where to Add New Code
 
-New Feature (command):
-New Component/Module:
+New Feature (CLI command):
 
-- Implementation: `src/utils/` for shared helpers, or `src/<feature>/` if feature-specific.
-- Export public helpers from their files; avoid adding global side-effects.
+- 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`).
 
-Utilities:
+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:
 
-- Shared helpers: `src/utils/`.
-- If utility is generic, add tests in `tests/` and export clearly-typed interfaces.
+- Add new templates under `files/` and reference them from create implementations using `path.join(__dirname, "..", "..", "files", "<template>")`.
 
 ## Special Directories
 
-`files/`:
+dist/:
 
-- Purpose: Template assets for project scaffolding.
-- Generated: No
-- Committed: Yes
+- Purpose: Compiled ESM output for packaging and the `bin` entry (`dist/cli.js`).
+- Generated: Yes
+- Committed: No (should be generated during build)
 
-`tests/`:
+tests/tmp-files/:
 
-- Purpose: Contains unit tests. Committed: Yes
+- Purpose: Tests write temporary projects into `tests/tmp-files/*` during execution and remove them afterwards (see `tests/*.test.ts`).
 
 ---
 
-_Structure analysis: 2026-03-08_
+_Structure analysis: 2026-03-10_