@iamsaroj/replicax 0.0.2 → 0.0.4

package/README.md

@@ -10,11 +10,11 @@
   None of your business code. None of your secrets. Just the setup.
 </p>
 
-[![npm](https://img.shields.io/badge/npm-%40iamsaroj%2Freplicax-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@iamsaroj/replicax)
-[![Node](https://img.shields.io/badge/Node-%E2%89%A5%2020-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-![ESM](https://img.shields.io/badge/Module-ESM-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)
-[![License](https://img.shields.io/badge/License-MIT-3FB950?style=for-the-badge)](LICENSE)
+[![npm](https://img.shields.io/badge/npm-%40iamsaroj%2Freplicax-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@iamsaroj/replicax)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A5%2020-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+![ESM](https://img.shields.io/badge/Module-ESM-F7DF1E?style=flat-square&logo=javascript&logoColor=black)
+[![License](https://img.shields.io/badge/License-MIT-3FB950?style=flat-square)](LICENSE)
 
 <sub>
   <a href="#quick-start"><b>Quick start</b></a> &nbsp;•&nbsp;
@@ -219,6 +219,9 @@ No `.env`. No `Button.tsx`. No `UserService.ts`. No `react` runtime dependency.
 | [`replicax validate`](#replicax-validate)                                            | Schema + integrity (SHA‑256) check — CI‑friendly   |
 | [`replicax export`](#replicax-export--import) / [`import`](#replicax-export--import) | Portable `.tar.gz` profile in/out                  |
 | [`replicax init-skill`](#replicax-init-skill)                                        | Author an AI‑assistant skill from your stack       |
+| [`replicax doctor`](#replicax-doctor)                                                | Check which dev tools are installed locally        |
+| [`replicax compare <a> <b>`](#replicax-compare-source-target)                        | Diff two profiles/projects: tooling, config, …     |
+| [`replicax audit`](#replicax-audit)                                                  | Score a setup vs best practices + recommendations  |
 
 > Every write operation accepts `--dry-run` (preview, touch nothing) and `--verbose` (list every file).
 
@@ -347,10 +350,92 @@ replicax init-skill --target claude --force                    # overwrite exist
 `codex` → `.codex/skills/<name>/SKILL.md`, `antigravity` → `.agents/skills/<name>.md`. The **provider** (auto‑detected,
 or forced with `--provider`) is the AI that _authors_ it — the two are independent.
 
+> **Bring your own template.** If the project root has a `SKILL.md`, `init-skill` hands it to the AI as the **base** to
+> refine — the model preserves your headings, structure, and instructions and fills them in from the detected setup,
+> instead of starting from scratch.
+
 > **Privacy:** only the project's _setup_ is sent to the provider — the same safe surface ReplicaX captures (config
 > files, structure, `package.json` scripts/deps). Source code and secrets are never sent. With `--no-ai` (or no provider
 > configured), ReplicaX falls back to a deterministic, fully offline template.
 
+### `replicax doctor`
+
+Report which developer tools are installed locally — runtimes, package managers, Docker, and editors — with versions.
+Cross‑platform and read‑only; a missing tool is a finding, not an error.
+
+```bash
+replicax doctor
+replicax doctor --json     # machine-readable
+```
+
+```console
+$ replicax doctor
+Developer environment
+
+✓ Node.js 22.17.1
+✓ Git 2.45.1
+✓ npm 10.2.0
+✗ Docker not found
+✓ Claude Code 2.1.0
+
+8/11 tools found
+```
+
+### `replicax compare <source> <target>`
+
+Diff two profiles — or two project directories — across tooling, configuration files, `package.json`, structure, and
+metadata. Each argument may be a `.replicax` profile, a directory containing one, or a plain project folder (scanned on
+the fly), so you can compare anything against anything.
+
+```bash
+replicax compare ./examples/react-vite ./examples/nextjs-enterprise
+replicax compare ./my-app ./other-app --json
+```
+
+```text
+Added:
+  + Docker (Tooling)
+  + src/api (Structure)
+Removed:
+  - Jest (Tooling)
+Changed:
+  ~ eslint.config.js (Configuration files)
+  ~ language: javascript → typescript (Metadata)
+```
+
+### `replicax audit`
+
+Score a project's setup against best‑practice rules — linting, formatting, testing, git hooks, CI/CD, containerization —
+and get concrete recommendations for what's missing. Scans the current directory by default, or evaluates a stored
+profile with `--profile`.
+
+```bash
+replicax audit
+replicax audit --path ./some/project
+replicax audit --profile ./examples/nextjs-enterprise/.replicax --json
+```
+
+```text
+Project Score: 60/100
+
+✓ Formatting
+✓ Testing
+✗ Git hooks
+✗ Containerization
+
+Missing:
+  - Git hooks
+  - Containerization
+
+Recommendations:
+  - Add Husky to run checks before each commit.
+  - Add a Dockerfile to containerize the application.
+```
+
+> `compare` and `audit` build on the detection engine: every scan now reports the **detected stack** (React, TypeScript,
+> Docker, GitHub Actions, …) with a confidence score, persisted in the profile and viewable via `inspect --section
+> detections`.
+
 ---
 
 ## What gets captured
@@ -364,6 +449,7 @@ or forced with `--provider`) is the AI that _authors_ it — the two are indepen
 | `.editorconfig`, Husky hooks                        | IDE folders (`.vscode/`, `.idea/`, `.vs/`, `.fleet/`, `.zed/`) |
 | Test configs (Vitest/Jest/Playwright/Cypress)       | Anything matched by `.replicaxignore`                          |
 | Monorepo files, commitlint/lint‑staged/release/knip |                                                                |
+| JVM build (Maven/Gradle) + Spring `application.*`   | Compiled output (`target/`, `*.class`), the gradle wrapper JAR |
 | Folder hierarchy (directories only)                 | Folder _contents_                                              |
 
 **`package.json` is curated, not copied.** Only `scripts`, `devDependencies`, `engines`, `type`, `packageManager`, and
@@ -393,10 +479,10 @@ The same guarantees apply to `extract` — a remote repo's secrets are filtered
 
 ---
 
-## Configuration — `.replicaxignore`
+## Configuration — `.replicaxignore` and `.replicaxinclude`
 
-Control what gets exported with **gitignore syntax**. `init` can scaffold a starter for you. Ignored files are excluded
-from the profile — but their parent directories are still captured for structure.
+**`.replicaxignore`** controls what gets *excluded*, with **gitignore syntax**. `init` can scaffold a starter for you.
+Ignored files are excluded from the profile — but their parent directories are still captured for structure.
 
 ```gitignore
 # Business logic (folders kept, contents dropped)
@@ -408,22 +494,42 @@ src/**/*.ts
 *.log
 ```
 
+**`.replicaxinclude`** is the opposite: a list of **glob patterns** (one per line, `#` comments) for *extra* files to
+capture verbatim, on top of the auto-detected catalogue. Use it for config ReplicaX doesn't recognize by default
+(`*.toml`, a `config/` directory, an IDE file you do want shared, …). A trailing `/` means "the whole directory".
+
+```gitignore
+# Capture these in addition to the auto-detected setup
+app.config.toml
+config/**
+.vscode/extensions.json
+```
+
+**Precedence** (highest first): the **secret guard** always wins (a secret can never be included) →
+**`.replicaxignore`** (your excludes beat your includes) → **`.replicaxinclude`** (overrides the default prune/ignore
+lists, so it can reach normally-skipped locations) → the **built-in catalogue**.
+
 ---
 
 ## Profile format
 
-A profile is five JSON files under `.replicax/`:
+A profile is five required JSON files under `.replicax/`, plus an optional manifest:
 
 ```text
 .replicax/
 ├── profile.json     # identity & metadata (name, version, timestamps)
 ├── tooling.json     # every captured config file (verbatim) + the package.json template
 ├── structure.json   # folder hierarchy (sorted POSIX directory paths)
-├── metadata.json    # node version, package manager, framework, language, platform
-└── checksum.json    # SHA-256 integrity hashes
+├── metadata.json    # node version, package manager, framework, language + detected stack
+├── checksum.json    # SHA-256 integrity hashes
+└── manifest.json    # content-free index of artifacts (path, category, size, hash)
 ```
 
-All five are schema‑validated (zod) on load; `validate` additionally re‑checks checksums and rejects unsafe paths.
+All files are schema‑validated (zod) on load; `validate` additionally re‑checks checksums and rejects unsafe paths.
+
+**Schema version 2.1.0** added the detected stack (`metadata.detections`), an optional `registry` block (for future
+registry support), and `manifest.json` — all backward‑compatible. Profiles written by older ReplicaX (2.0.0) are
+**migrated automatically on load** and the manifest is synthesized when absent, so existing profiles keep working.
 
 ---