workspace-manager-cli 1.0.0

package/README.md

@@ -0,0 +1,339 @@
+# workspace-manager-cli
+
+A cross-platform Node/TypeScript CLI that assembles a project workspace from a shared core boilerplate plus a project's custom folder.
+
+## Features
+
+- **Smart caching**: Clones core repositories to local cache (`.wmc-cache/`)
+- **Update notifications**: Shows when new commits are available with `wmc status`
+- **Overlay system**: Layer your custom code on top of core boilerplate
+- **Cross-platform**: Pure Node.js APIs, no shell dependencies
+- **Automation-friendly**: `--json` flag for machine-readable output
+
+## Quick Start
+
+```bash
+# Initialize cache and build workspace
+wmc init --build
+
+# Skip npm install after build
+wmc init --build --no-install
+# If not installed globally, use: npx workspace-manager-cli init --build
+```
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g workspace-manager-cli
+```
+
+## Configuration
+
+Run `wmc init` (or `wmc init -i` or `wmc init --interactive`) in a folder without a config and the CLI will **generate `workspace.config.json` for you**, prompting for project type plus core/base URLs. It also writes a minimal `.gitignore` covering the generated workspace and cache.
+
+Example of a generated `workspace.config.json` (base-core-custom):
+
+```json
+{
+  "projectType": "base-core-custom",
+  "base": {
+    "name": "base",
+    "url": "https://github.com/example/base.git",
+    "ref": "main"
+  },
+  "core": {
+    "name": "core",
+    "url": "https://github.com/example/core.git",
+    "ref": "main"
+  },
+  "custom": {
+    "path": "custom"
+  },
+  "install": {
+    "command": "npm install"
+  }
+}
+```
+
+### Configuration Options
+
+| Field             | Type     | Default         | Description                                                                                                      |
+| ----------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `projectType`     | enum     | _required_      | One of `core-custom`, `base-core`, `base-core-custom`; determines which repos are required and how they overlay. |
+| `base.name`       | string   | \_required\*    | Base repo name (cache dir). Required when the project type includes base.                                        |
+| `base.url`        | string   | \_required\*    | Git URL of base repo.                                                                                            |
+| `base.ref`        | string   | `"main"`        | Branch/tag/commit for base.                                                                                      |
+| `core.name`       | string   | _required_      | Core repo name (cache dir).                                                                                      |
+| `core.url`        | string   | \_required\*\*  | Git URL of core repo (required for `core-custom` and `base-core-custom`; omit for `base-core`).                  |
+| `core.path`       | string   | `"core"`        | Local path to core folder (only for `base-core` type).                                                           |
+| `core.ref`        | string   | `"main"`        | Branch/tag/commit for core (only used when `core.url` is set).                                                   |
+| (fixed) workspace | string   | `"workspace"`   | The workspace directory is fixed to `./workspace` and is not configurable                                        |
+| `custom.path`     | string   | `"custom"`      | Path to your custom code directory                                                                               |
+| `install.command` | string   | `"npm install"` | Command to run inside `workspace` after copying (skipped with `--no-install`)                                    |
+| `excludes`        | string[] | `[]`            | Additional glob patterns to exclude when copying                                                                 |
+
+\* Required when the selected `projectType` includes a base repository.  
+\*\* Required for `core-custom` and `base-core-custom`; omit for `base-core` (use `core.path` instead).
+
+**Excludes & dry-run visibility** 🛑
+
+- Use `excludes` to skip copying files or directories into the assembled `workspace` folder (`./workspace`).
+- Examples: `excludes: ["**/*.log", "dist/**", "node_modules/**", "**/*.tmp"]` will prevent matching files from being copied.
+- Use `--dry-run` (or `--dry-run` option) to preview actions — the build will add an action `Excludes: <patterns>` and log `Effective excludes: ...` so you can verify which globs will be applied before any copying occurs.
+
+### Project Types
+
+- `core-custom`: Remote core + local custom overlay (no base). Core is cached in `.wmc-cache/<core>` and copied to `workspace`; custom overlays into `workspace/src/core/custom`.
+- `base-core`: Remote base + local core folder. Base comes from cache; core is taken from a local path; custom is optional.
+- `base-core-custom`: Remote base + remote core + local custom. Both base and core are cached; core replaces base's core area; custom overlays on top.
+
+## Commands
+
+### `init`
+
+Initialize repositories (core/base) by cloning to local cache, optionally build.
+
+```bash
+wmc init [options]
+```
+
+**Options:**
+
+- `--ref <ref>`: Override core ref (branch/tag/commit)
+- `--base-ref <ref>`: Override base ref
+- `--core-latest`: Checkout latest commit on core branch
+- `--base-latest`: Checkout latest commit on base branch
+- `--interactive`: Pick refs interactively (non-JSON mode)
+- `--build`: Build workspace after initialization
+- `--no-install`: Skip running `npm install` inside `workspace` (only applies when `--build` is used)
+
+**What it does:**
+
+- Clones configured repos to `.wmc-cache/<name>` (behavior depends on project type):
+  - `core-custom`: Clones core only
+  - `base-core`: Clones base only (core is local)
+  - `base-core-custom`: Clones both base and core
+- Checks out the chosen refs
+- Persists the resolved hashes/refs to `workspace.config.json`
+- (Optional) Builds the workspace when `--build` is provided
+
+### `build` (alias: `sync`)
+
+Build the workspace by assembling repositories and overlaying custom code based on project type.
+
+```bash
+wmc build [options]
+```
+
+**Options:**
+
+- `--no-install`: Skip running `npm install` inside `workspace`
+- `--dry-run`: Preview what will happen **without actually making any changes**. Useful for testing your config before committing to the build.
+
+  **Example:**
+
+  ```bash
+  wmc build --dry-run
+  ```
+
+  **What happens:**
+  - Reads your config and checks what files will be copied/excluded
+  - Logs each action it _would_ perform (copy, overlay, install, etc.)
+  - **Does NOT create or modify any files**
+  - Exits without touching `workspace/` or running `npm install`
+
+  **Real-world scenario:**
+  You just updated your `excludes` list and want to verify the right files will be copied before actually running the build. Run `wmc build --dry-run` first to see the preview, then if it looks good, run `wmc build` to execute it.
+
+**What it does (varies by project type):**
+
+- `core-custom`:
+  1. Copy core from `.wmc-cache/<core>` to `workspace`
+  2. Overlay `custom/` into `workspace/src/core/custom`
+  3. Run `install.command` in `workspace`
+
+- `base-core`:
+  1. Copy base from `.wmc-cache/<base>` to `workspace`
+  2. Copy local core from `config.core.path` to `workspace/src/core`
+  3. Run `install.command` in `workspace`
+
+- `base-core-custom`:
+  1. Copy base from `.wmc-cache/<base>` to `workspace`
+  2. Copy core from `.wmc-cache/<core>` to `workspace/src/core` (replacing base's core)
+  3. Overlay `custom/` into `workspace/src/core/custom`
+  4. Run `install.command` in `workspace`
+
+### `status`
+
+Print current status of repositories and directories based on project type.
+
+```bash
+wmc status
+```
+
+**Shows (varies by project type):**
+
+- `core-custom`:
+  - Core repo cache status (cloned, commit, branch)
+  - Core updates available (if any)
+  - Custom directory uncommitted changes
+
+- `base-core`:
+  - Base repo cache status (cloned, commit, branch)
+  - Base updates available (if any)
+  - Local core directory location
+  - Custom directory uncommitted changes (if applicable)
+
+- `base-core-custom`:
+  - Base repo cache status (cloned, commit, branch)
+  - Base updates available (if any)
+  - Core repo cache status (cloned, commit, branch)
+  - Core updates available (if any)
+  - Custom directory uncommitted changes
+
+## Global Options
+
+| Option      | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `--json`    | Output machine-readable JSON (useful for automation) |
+| `--version` | Show version number                                  |
+| `--help`    | Show help                                            |
+
+## What to Commit
+
+✅ **Commit these:**
+
+- `workspace.config.json`
+- `custom/` directory (your custom code)
+
+❌ **Don't commit:**
+
+- `workspace/` (generated)
+- `.wmc-cache/` (local cache)
+- `workspace/node_modules/` (dependencies)
+
+## How It Works
+
+Core repository is cloned to a local cache directory and reused across builds:
+
+- **Cache location**: `.wmc-cache/<name>` (in project root)
+- **Fast builds**: Reuses cached repositories, only fetches when needed
+- **Update notifications**: `wmc status` shows when new commits are available
+
+**Project Structure:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Your Project                                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  workspace.config.json                                          │
+│  custom/                                                        │
+│  .wmc-cache/                ← Git repos cloned here             │
+│    └── CORE-EKCFastag/                                          │
+│        ├── .git/                                                │
+│        └── src/                                                 │
+│  workspace/ (generated)     ← Files copied here                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Workflow:**
+
+```bash
+# Developer A initializes and builds
+wmc init --build            # Clones to local .wmc-cache and builds workspace
+
+# Developer A commits their work
+git add custom/ workspace.config.json
+git commit -m "Add feature X"
+git push
+
+# Developer B pulls and builds
+git pull
+wmc init --build            # Populates their own .wmc-cache and rebuilds workspace
+                            # Note: .wmc-cache is local per developer, not shared
+
+# Check for updates
+wmc status                  # Shows if new commits are available
+wmc init --core-latest --build   # Fetch latest core, then rebuild
+```
+
+**Note on sharing:**
+
+- Each developer has their own `.wmc-cache/` (not committed to git)
+- Developers share: `workspace.config.json`, `custom/` folder, and `core/` folder (if local)
+- After `git pull`, run `wmc init --build` to populate your local cache and rebuild workspace
+
+## Automation (not tested)
+
+### CI/CD Pipeline Example
+
+```yaml
+# GitHub Actions example
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Initialize core
+        run: wmc init --json
+
+      - name: Build workspace
+        run: wmc build --json
+
+      - name: Build project
+        run: cd workspace && npm run build
+```
+
+### JSON Output
+
+Use `--json` for machine-readable output:
+
+```bash
+wmc status --json   # or: npx workspace-manager-cli status --json
+```
+
+```json
+{
+  "command": "status",
+  "config": { ... },
+  "status": {
+    "coreInitialized": true,
+    "coreCommit": "abc123...",
+    "customHasChanges": false
+  }
+}
+```
+
+## Troubleshooting
+
+### "Could not find workspace.config.json"
+
+Make sure you're running the CLI from a directory that has `workspace.config.json` or one of its parent directories.
+
+### "Core repository not found"
+
+Run `wmc init` (or `npx workspace-manager-cli init` if not installed globally).
+
+### "Failed to checkout ref"
+
+Ensure the ref (branch/tag/commit) exists in the core repository. Try:
+
+```bash
+wmc init --ref main --build   # or: npx workspace-manager-cli init --ref main --build
+```
+
+### Build fails with permission errors
+
+On Windows, ensure no processes are using files in the workspace directory.
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedConfig } from "./config.js";
+import { Logger } from "./logger.js";
+export interface BuildOptions {
+    noInstall?: boolean;
+    dryRun?: boolean;
+}
+export interface BuildResult {
+    success: boolean;
+    baseFilesCopied: number;
+    coreFilesCopied: number;
+    customFilesCopied: number;
+    installRan: boolean;
+    actions: string[];
+}
+/**
+ * Build the workspace by copying layers based on project type
+ */
+export declare function buildWorkspace(config: ResolvedConfig, logger: Logger, options?: BuildOptions): Promise<BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAuGD;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA8ItB"}