@iamsaroj/replicax 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReplicaX contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,394 @@
+<div align="center">
+
+# ReplicaX
+
+### _Copy the setup, not the code._
+
+Extract a project's development environment — tooling config, folder structure, and
+conventions — into a reusable profile, then recreate it in seconds anywhere.
+
+![Node](https://img.shields.io/badge/node-%3E%3D20-43853d)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6)
+![Module](https://img.shields.io/badge/module-ESM-f7df1e)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+</div>
+
+---
+
+ReplicaX captures the **setup** of a project — the parts you copy-paste between every
+new repo — and leaves the **implementation** behind. New projects start with your
+exact tooling and folder layout, and **zero** of your business code, secrets, or
+build artifacts.
+
+It is **not** a code generator, a project cloner, or a backup tool.
+
+## Why
+
+Every new project repeats the same ritual: copy `tsconfig.json`, port the ESLint and
+Prettier setup, recreate the Docker files, re-add the CI workflow, rebuild `src/`'s
+folder layout. It's slow, error-prone, and drifts out of sync across a team.
+
+ReplicaX captures that ritual once and replays it on demand.
+
+## Features
+
+- **One-command capture** — `init` scans the current project into a profile.
+- **One-command scaffold** — `create` reproduces it in a new directory.
+- **`.ts` _and_ `.js` configs** — copied byte-for-byte, never compiled or executed.
+- **Secret-safe by design** — `.env`, keys, and certs can never enter a profile; `.npmrc` auth tokens are stripped
+  automatically.
+- **No business code** — folders are recreated empty; source files are never copied.
+- **Stays in sync** — `sync --diff` shows what drifted; `validate` checks integrity via SHA-256.
+- **Portable & shareable** — `export`/`import` a profile as a single `.tar.gz`.
+- **`.replicaxignore`** — gitignore-style control over what gets exported.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Worked example](#worked-example)
+- [Commands](#commands)
+- [What gets captured](#what-gets-captured)
+- [Security](#security)
+- [replicaxignore](#replicaxignore)
+- [Profile format](#profile-format)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [FAQ](#faq)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install -g @iamsaroj/replicax
+# or
+pnpm add -g @iamsaroj/replicax
+```
+
+Requires **Node.js 20+**. ReplicaX is a standalone CLI with no external services.
+
+## Quick start
+
+```bash
+# 1. In an existing, well-configured project:
+cd my-project
+replicax init                  # → writes a profile to .replicax/
+
+# 2. Anywhere the profile lives, scaffold a fresh project:
+replicax create my-new-app     # → same setup, none of the code
+```
+
+> Tip: try `replicax init --dry-run` first to preview exactly what would be captured.
+
+## Worked example
+
+Starting from a typical Vite + React + TypeScript project:
+
+```text
+my-project/
+├── vite.config.ts
+├── tsconfig.json
+├── tsconfig.node.json
+├── .prettierrc
+├── eslint.config.js
+├── Dockerfile
+├── docker-compose.yml
+├── .github/workflows/ci.yml
+├── .husky/pre-commit
+├── .env                       # ← secret
+├── package.json               # ← incl. runtime deps
+└── src/
+    ├── components/Button.tsx   # ← business code
+    ├── hooks/
+    ├── services/UserService.ts # ← business code
+    └── pages/
+```
+
+```bash
+replicax init
+replicax create my-new-app --skip-install
+```
+
+ReplicaX produces:
+
+```text
+my-new-app/
+├── vite.config.ts             # copied verbatim
+├── tsconfig.json
+├── tsconfig.node.json
+├── .prettierrc
+├── eslint.config.js
+├── Dockerfile
+├── docker-compose.yml
+├── .github/workflows/ci.yml
+├── .husky/pre-commit
+├── package.json               # name renamed; scripts/devDeps kept, runtime deps dropped
+└── src/
+    ├── components/             # recreated, but EMPTY
+    ├── hooks/
+    ├── services/               # recreated, but EMPTY
+    └── pages/
+```
+
+No `.env`, no `Button.tsx`, no `UserService.ts`, no `react` runtime dependency — only
+the setup.
+
+## Commands
+
+### `replicax init`
+
+Scan the current project and write a profile to `.replicax/`.
+
+```bash
+replicax init --name "react-enterprise"   # name the profile
+replicax init --dry-run                    # preview, write nothing
+replicax init --verbose                    # list every detected file
+```
+
+### `replicax create <project-name>`
+
+Create a new project from a profile. Existing files trigger an interactive
+overwrite/skip prompt (auto-skips when non-interactive).
+
+```bash
+replicax create my-app
+replicax create my-app --profile ./shared/.replicax   # use a profile elsewhere
+replicax create my-app --skip-install                  # don't run the package manager
+replicax create my-app --force                         # overwrite conflicts, no prompt
+replicax create my-app --dry-run                        # preview the file plan
+```
+
+### `replicax sync`
+
+Re-scan and update the profile to match the current project.
+
+```bash
+replicax sync           # update, print a change summary
+replicax sync --diff    # detailed per-file added/changed/removed list
+replicax sync --force   # rewrite even if nothing changed
+```
+
+### `replicax inspect`
+
+Display the captured configuration and structure.
+
+```bash
+replicax inspect
+replicax inspect --json                  # machine-readable (stdout only)
+replicax inspect --section tooling       # profile | tooling | structure | metadata
+```
+
+```text
+Tooling (14 file(s))
+┌────────────────────────────────┬──────────────────────────┬─────────┬──────────┐
+│ Category                       │ File                     │ Variant │ Size     │
+├────────────────────────────────┼──────────────────────────┼─────────┼──────────┤
+│ Language & Type Checking       │ tsconfig.json            │ json    │ 226 B    │
+│ Build Tools                    │ vite.config.ts           │ ts      │ 98 B     │
+│ Formatting                     │ .prettierrc              │ other   │ 63 B     │
+│ …                              │ …                        │ …       │ …        │
+└────────────────────────────────┴──────────────────────────┴─────────┴──────────┘
+```
+
+### `replicax validate`
+
+Check the profile's schema and integrity (SHA-256 checksums + path safety). Exits
+non-zero on failure — handy in CI.
+
+```bash
+replicax validate
+```
+
+### `replicax export` / `import`
+
+Package a profile into a portable archive and adopt it elsewhere.
+
+```bash
+replicax export --out ./react-enterprise.tar.gz
+replicax import ./react-enterprise.tar.gz          # validates before adopting
+replicax import ./react-enterprise.tar.gz --force  # overwrite an existing profile
+```
+
+> `--dry-run` is available on every write operation and never touches disk.
+
+## What gets captured
+
+| Captured ✅                                          | Left behind ❌                                                  |
+|-----------------------------------------------------|----------------------------------------------------------------|
+| TS/JS configs, ESLint, Prettier                     | Application source (components, services, controllers)         |
+| Vite / Webpack / Rollup / esbuild                   | Runtime `dependencies` in `package.json`                       |
+| Tailwind / PostCSS                                  | `.env*`, `*.pem`, `*.key`, certificates                        |
+| Docker, CI/CD (Actions, GitLab, CircleCI, Jenkins)  | `node_modules/`, `dist/`, `build/`, `coverage/`, `.next/`, …   |
+| `.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 |                                                                |
+| Folder hierarchy (directories only)                 | Folder _contents_                                              |
+
+**`package.json`** is curated, not copied: only `scripts`, `devDependencies`,
+`engines`, `type`, `packageManager`, and config blocks like `lint-staged` are kept.
+Runtime `dependencies` are deliberately dropped, and the new project's name is
+stamped in on `create`.
+
+Both `.ts` and `.js` config variants are supported because ReplicaX copies them
+**verbatim** — it never needs to compile or execute a config to capture it.
+
+## Security
+
+ReplicaX treats secret exclusion as a hard guarantee, not a best effort:
+
+- **Secrets are never captured.** `.env`, `.env.*`, `*.pem`, `*.key`, `*.crt`,
+  SSH keys, and friends are blocked unconditionally — this cannot be overridden by
+  configuration.
+- **`.npmrc` is sanitized.** It's a legitimate setup file, but auth tokens
+  (`_authToken`, `_password`, …) are stripped out before it enters a profile.
+- **No path escapes.** Every path read from a profile is validated against traversal
+  (`..`) and absolute paths before anything is written, so a malicious profile can't
+  write outside its target directory.
+
+## `.replicaxignore`
+
+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.
+
+```gitignore
+# Business logic (folders kept, contents dropped)
+src/services/**
+src/**/*.ts
+
+# Extra secrets / noise
+.env
+*.log
+```
+
+## Profile format
+
+A profile is five JSON files under `.replicax/`:
+
+```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
+```
+
+All five are schema-validated (zod) on load; `validate` additionally re-checks
+checksums and rejects unsafe paths.
+
+## How it works
+
+```text
+              ┌─────────┐      ┌──────────────────┐      ┌──────────────┐
+  init/sync   │ Scanner │ ───▶ │ Profile Generator│ ───▶ │ .replicax/   │
+              └─────────┘      └──────────────────┘      └──────────────┘
+                  │                                            │
+       ignore engine + secret guard                   load + zod validate
+                                                             │
+              ┌──────────────────┐                           ▼
+  create      │ Project Generator│ ◀───────────────────  ProfileBundle
+              └──────────────────┘
+                  │
+       conflict resolver (overwrite/skip)
+```
+
+- **Scanner** detects config files (via a glob catalogue), the folder hierarchy, and
+  project metadata (package manager, framework, language).
+- **Ignore engine** layers default ignores + `.replicaxignore`, with a separate,
+  non-overridable **secret guard**.
+- **Profile generator** assembles the bundle and computes checksums.
+- **Project generator** reproduces the setup, adapting names/paths, with a
+  **conflict resolver** for existing files.
+
+## Development
+
+```bash
+npm install
+npm run build         # tsup → dist/index.js (single ESM file, with shebang)
+npm run typecheck     # tsc --noEmit
+npm test              # vitest (32 tests, real temp-dir fixtures)
+npm run format        # prettier --write .
+npm run dev           # tsup --watch
+```
+
+> **Lockfile:** `package-lock.json` is maintained with **npm 10** (the version CI's
+> Node 20/22 ship with). If you're on npm 11+, regenerate it with `npx npm@10 install`
+> when changing dependencies — npm 11 resolves a different tree and will desync `npm ci`.
+
+Imports use a `@/*` → `src/*` alias resolved by tsc, tsup/esbuild, and the
+`vite-tsconfig-paths` vitest plugin. The build bundles to one file, so the alias
+never reaches the published output.
+
+**Stack:** TypeScript 5 · Node 20+ · ESM · commander · fast-glob · fs-extra ·
+ignore · zod · tar · picocolors · ora · @inquirer/prompts · cli-table3 · vitest ·
+tsup · prettier.
+
+> **Audit note:** `npm audit` flags `esbuild` (a build-time transitive of `tsup`).
+> The advisory concerns esbuild's dev server, which ReplicaX never runs, and
+> esbuild is not part of the published runtime (`dist/`). Fixing it requires a
+> breaking tsup downgrade, so the toolchain is left intact.
+
+## Releasing
+
+Publishing is **fully automated** by [`.github/workflows/release.yml`](.github/workflows/release.yml):
+bump the version, push to `main`, and the workflow tags the commit, runs the full
+CI gate (format, types, tests, build, CLI smoke test), publishes to npm with
+[provenance](https://docs.npmjs.com/generating-provenance-statements), and opens a
+GitHub Release with generated notes. You never create the tag by hand.
+
+**One-time setup:**
+
+1. Create a **classic Automation token** on npm (Access Tokens → Generate New
+   Token → Classic Token → **Automation**). If your account has 2FA enabled for
+   writes, this is the token type that can publish from CI — it bypasses the
+   interactive 2FA prompt. (A granular or classic _Publish_ token still requires
+   an OTP and will fail in CI with a `403`.)
+2. Add it to the repo as a secret named `NPM_TOKEN`
+   (Settings → Secrets and variables → Actions). Scoping it to a `npm`
+   environment is optional but recommended for required-reviewer protection.
+
+**Cut a release** — bump and push, that's it:
+
+```bash
+npm version patch --no-git-tag-version   # minor / major too; bumps package.json + lock
+git commit -am "Release v0.1.0"
+git push                                 # → workflow tags v0.1.0 and publishes
+```
+
+The release gate is "is this version already on npm?", so:
+
+- A normal push with no version change is a **no-op**.
+- Re-running never double-publishes (npm already has the version → skipped).
+- The git tag (`vX.Y.Z`) is created **after** a successful publish, so a failed
+  publish stays retryable.
+- Prerelease versions (e.g. `0.2.0-beta.1`) publish under a matching dist-tag
+  (`beta`) instead of `latest`.
+
+> Don't push tags manually — let the workflow own tagging. Every push and PR is
+> also checked by [`.github/workflows/ci.yml`](.github/workflows/ci.yml) across Node 20 and 22.
+
+## FAQ
+
+**Does it copy my source code?** No. Only configuration files and the empty folder
+hierarchy. Application code is never read into a profile.
+
+**What about `.ts` config files like `vite.config.ts`?** Fully supported — they're
+copied as text, so both `.ts` and `.js` variants work without any compile step.
+
+**Can a profile leak a secret?** No. Secret exclusion is unconditional and `.npmrc`
+tokens are stripped; `validate` will fail if a secret ever appears in a profile.
+
+**Why are runtime `dependencies` dropped from `package.json`?** They're part of your
+application, not your setup. `devDependencies`, `scripts`, and `engines` are kept.
+
+**Is it cross-platform?** Yes — Windows (native + WSL), macOS, and Linux.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<div align="center"><sub><i>ReplicaX — copy the setup, not the code.</i></sub></div>