@dawitworku/projectcli 0.2.2 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+This project follows Semantic Versioning.
+
+## 3.0.0 (2026-01-07)
+
+- Add `projectcli doctor` with optional `--fix` and `--json` output.
+- Add presets (`projectcli preset list|use`) and preset-aware defaults for common flows.
+- Add safe upgrades (`projectcli upgrade`) with `--preview`, `--dry-run`, and `--only` targeting.
+- Add feature-based add flows (`projectcli add <feature>`) while keeping the interactive library picker.
+- Add a plugin system (`projectcli plugin list|install`) plus plugin contributions (presets, registry additions, doctor checks).
+- Refactor registry internals to support extensions while keeping backwards-compatible imports.
+
+## 0.3.0 (2026-01-06)
+
+- Add per-project config via `.projectclirc` / `projectcli.config.json` (CLI > project config > `~/.projectcli.json`).
+- Improve preflight + missing-command errors with actionable install hints.
+- Add generator stability metadata (defaults to `core`) and show in UI + `--list`.
+- README improvements: demo placeholder, “Why ProjectCLI?”, explicit safety guarantees.
+
+## 0.2.2 (2026-01-06)
+
+- Interactive wizard for selecting language → framework → project name.
+- `--dry-run` prints planned actions without executing.
+- Remote template cloning via `--template` (strips `.git`).
+- Preflight tool checks for generators that declare `check: [...]`.
+- Extras generation: GitHub Actions CI, Dockerfile, Dev Container, LICENSE.
+- Defaults via `projectcli config` (`~/.projectcli.json`).
+- Basic smoke tests via Node’s built-in test runner.

package/README.md

@@ -1,16 +1,36 @@
 # ProjectCLI 🚀
 
+**Demo (2 minutes):**
+
+- Play locally: `asciinema play docs/demo.cast`
+- Convert to plain text (for quick sharing): `asciinema convert --output-format txt docs/demo.cast -`
+
+![ProjectCLI terminal demo](docs/demo.svg)
+
+Asciinema recording file: `docs/demo.cast`
+
 > **The Swiss Army Knife for Project Scaffolding.**  
 > Bootstrapping new projects shouldn't require memorizing 50 different CLI commands.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/@dawitworku%2Fprojectcli.svg)](https://badge.fury.io/js/@dawitworku%2Fprojectcli)
+[![npm downloads](https://img.shields.io/npm/dm/@dawitworku/projectcli)](https://www.npmjs.com/package/@dawitworku/projectcli)
+[![CI](https://github.com/dawitworku/projectcli/actions/workflows/ci.yml/badge.svg)](https://github.com/dawitworku/projectcli/actions/workflows/ci.yml)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
 **ProjectCLI** is an interactive, cross-language project generator. Instead of remembering usage for `create-react-app`, `cargo new`, `poetry new`, `laravel new`, `rails new`, etc., just run `projectcli`.
 
 We handle the complexity of calling the official CLIs for you.
 
+## 🤔 Why ProjectCLI?
+
+| Tool             | Problem                     |
+| ---------------- | --------------------------- |
+| create-react-app | JS-only                     |
+| cargo new        | Rust-only                   |
+| yeoman           | heavy & old                 |
+| projectcli       | **unified + context-aware** |
+
 ## ✨ Features
 
 - **Multi-Language Support**: Rust, Go, Python, JavaScript, TypeScript, PHP, Java, C#, Ruby, Swift, Dart.
@@ -22,6 +42,12 @@ We handle the complexity of calling the official CLIs for you.
 - **Dev Containers**: Generate `.devcontainer/devcontainer.json` for VS Code / Codespaces.
 - **License Generator**: Add a standard `LICENSE` file (configurable default).
 
+## ✅ Safety Guarantees
+
+- ❌ Never writes outside the project folder it creates (guards against path traversal).
+- ❌ Never deletes files without an explicit, targeted operation (template clone only removes the cloned `.git`).
+- ✔ Supports `--dry-run` to preview planned actions without executing them.
+
 ## 🚀 Quick Start
 
 Run instantly with `npx`:
@@ -48,6 +74,16 @@ Just run `projectcli` and follow the prompts:
 
 ## 🛠 Advanced Usage
 
+### V3 Commands
+
+ProjectCLI v3 adds a few focused subcommands:
+
+- `projectcli doctor` check a repo and optionally apply safe fixes
+- `projectcli preset list` / `projectcli preset use <name>` manage presets
+- `projectcli upgrade` upgrade generated configs safely (supports `--preview`)
+- `projectcli add <feature>` add focused features like `ci`, `docker`, `devcontainer`, `license`, `lint`, `test`
+- `projectcli plugin list` / `projectcli plugin install <id>` enable plugins (and their contributions)
+
 ### Context Awareness
 
 Run it inside a project to detect the language and offer relevant tools:
@@ -67,6 +103,12 @@ Clone a starter kit from GitHub and make it your own instantly:
 projectcli --template https://github.com/example/starter-repo --name my-app
 ```
 
+You can also apply extras non-interactively:
+
+```bash
+projectcli --template https://github.com/example/starter-repo --name my-app --yes --ci --docker --devcontainer --license
+```
+
 ### Automation / CI Use
 
 Skip the interactive prompts for scripts or specialized workflows:
@@ -75,6 +117,18 @@ Skip the interactive prompts for scripts or specialized workflows:
 projectcli --language Rust --framework Actix --name my-api --ci --docker --yes
 ```
 
+Preview what would happen (no execution):
+
+```bash
+projectcli --language Rust --framework Actix --name my-api --dry-run
+```
+
+Extras flags:
+
+- `--devcontainer` add a VS Code Dev Container
+- `--license` force-add LICENSE (uses config defaults)
+- `--no-license` never add LICENSE
+
 ### Configuration
 
 Save your preferences (like default package manager):
@@ -89,6 +143,32 @@ You can set defaults like:
 - Author name (for LICENSE)
 - Default license type (MIT/Apache2/ISC)
 
+### Project Config File (teams / automation)
+
+ProjectCLI can also read a config file from the current directory:
+
+- `.projectclirc`
+- `projectcli.config.json`
+
+Example:
+
+```json
+{
+  "packageManager": "pnpm",
+  "author": "The Team",
+  "license": "MIT",
+  "ci": true,
+  "docker": false,
+  "devcontainer": true
+}
+```
+
+Precedence:
+
+1. CLI flags
+2. Project config file
+3. Global config (`projectcli config` → `~/.projectcli.json`)
+
 ## 📦 Supported Generators (Partial List)
 
 | Language                  | Frameworks / Tools                                            |
@@ -101,6 +181,24 @@ You can set defaults like:
 | **Java/Kotlin**           | Spring Boot, Gradle/Maven...                                  |
 | **...and more**           | C#, Ruby, Swift, Dart                                         |
 
+## 🧱 Architecture (for contributors)
+
+ProjectCLI is intentionally simple: most “features” are data-driven.
+
+- **Registry entrypoint**: `src/registry.js` (backwards-compatible import path for callers/tests).
+- **Built-in generators**: `src/registry_legacy.js`.
+- **V3 registry wrapper** (plugins/extensions): `src/registry/index.js`.
+- **Generators produce steps**: each generator returns a list of steps (commands / mkdir / writeFile).
+- **Executor**: steps are executed by `src/run.js` (it also prevents writing outside the project folder).
+- **Preflight**: generators can declare required tools with `check: ["cargo", "go", ...]` and the wizard warns early.
+- **Remote templates**: `--template` clones via `src/remote.js`, strips `.git`, then can apply Extras (CI/Docker/Devcontainer/License).
+
+Adding a framework usually means:
+
+1. Add an entry in `src/registry.js` with `id`, optional `notes`, optional `check`, and a `commands()` function.
+2. Prefer non-interactive CLI args where possible (better for `--yes`/automation).
+3. Run `npm run lint` and `npm test`.
+
 ## 🤝 Contributing
 
 We love contributions! Whether it's adding a new framework to the registry or fixing a bug.

package/ROADMAP.md

@@ -0,0 +1,23 @@
+# Roadmap
+
+This is a lightweight, intention-revealing roadmap (not a promise). PRs welcome.
+
+## v0.3
+
+- Improve `--dry-run` output (include file diffs / more structured output).
+- Add `--no-ci`, `--no-docker`, `--no-devcontainer` to override config defaults.
+- More actionable errors (install hints for more tools; better command failure summaries).
+
+## v0.4
+
+- Generator snapshot tests (golden files) for core templates.
+- More built-in templates for CI/Docker/Dev Container across languages.
+
+## v0.5
+
+- Performance polish: cache tool availability, parallel preflight, reduce prompt startup cost.
+
+## v1.0
+
+- Lock in stability guarantees and backwards-compat for core generators.
+- Document long-term support expectations for generator metadata.