jdm-plugin-template 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+# jdm-plugin-template
+
+A starter template for building **jdm-cli** plugins. This repo is also self-bootstrapping — the `create` command clones this very repo into a new project, giving contributors a clean slate to start from.
+
+---
+
+## What is this?
+
+`jdm-plugin-template` is the **official base template** for all jdm-cli plugins. It ships with a working plugin structure, a set of standard commands (`create`, `dev`, `build`, `clean`, `install`), shared logging helpers, and a version compatibility system — so you spend time building your plugin, not scaffolding it.
+
+---
+
+## Quick Start
+
+### Use this template to scaffold a new plugin
+
+```bash
+# Install the CLI (if you haven't already)
+npm install -g jdm-cli
+jdm-cli add plugin-template
+
+# Scaffold a new plugin project
+jdm-cli plugin-template create
+
+# Then follow the prompts, or use flags:
+jdm-cli plugin-template create --name my-plugin
+jdm-cli plugin-template create --name my-plugin --install
+```
+
+This will:
+1. Clone this repo into a folder named `my-plugin` (or `.` for current dir)
+2. Strip `.git` so it's a clean project — not a fork
+3. Optionally run `npm install` for you
+
+---
+
+## Project Structure
+
+```
+jdm-plugin-template/
+├── lib/
+│   ├── index.js          # Entry point — namespace, command map, dispatcher
+│   ├── config.js         # Config read/write and compatibility guard
+│   ├── compat.js         # Plugin version + per-command compatibility ranges
+│   ├── logger.js         # Shared logging helpers (ok, fail, warn, info, step, header)
+│   └── commands/
+│       ├── create.js     # Scaffold a new project (clones this repo)
+│       ├── dev.js        # Start development environment
+│       ├── build.js      # Compile / package the project
+│       ├── clean.js      # Remove build artifacts
+│       └── install.js    # Install dependencies
+├── package.json
+└── README.md
+```
+
+---
+
+## Built-in Commands
+
+| Command   | Description                              | Key Flags                              |
+|-----------|------------------------------------------|----------------------------------------|
+| `create`  | Scaffold a new project from this template | `--name <name>`, `--install`          |
+| `dev`     | Start development environment            | _(wire up your own processes)_         |
+| `build`   | Compile / package the project            | `--frontend`, `--backend`, `--full`   |
+| `clean`   | Remove build artifacts                   | `--dry` (preview without deleting)    |
+| `install` | Install dependencies                     | _(none)_                               |
+
+---
+
+## Contributing / Building Your Own Plugin
+
+This repo is the starting point. Here's how to get going:
+
+### 1. Scaffold a copy
+
+```bash
+jdm-cli plugin-template create --name my-plugin --install
+cd my-plugin
+```
+
+Or clone manually:
+
+```bash
+git clone https://github.com/JDM-Github/jdm-plugin-template my-plugin
+cd my-plugin
+rm -rf .git
+npm install
+```
+
+### 2. Set your namespace
+
+In **three places**, replace `"plugin-template"` with your plugin's name:
+
+| File | What to change |
+|---|---|
+| `lib/index.js` | `export const namespace = "plugin-template"` |
+| `lib/config.js` | `const PLUGIN_NAME = "plugin-template"` |
+| `lib/logger.js` | `const ns = "plugin-template"` inside `header()` |
+| `package.json` | `"name"`, `"jdmPlugin.namespace"`, `"jdmPlugin.description"` |
+
+### 3. Add your commands
+
+1. Create `lib/commands/my-command.js` with a default export
+2. Import it in `lib/index.js` and add it to the `commands` map
+3. If it needs interactive prompts (`ask(rl, ...)`), add the name to `INTERACTIVE_COMMANDS`
+4. Add it to `showDesign()` for the help screen
+5. Add it to the `jdmPlugin.commands` array in `package.json`
+
+### 4. Wire up `dev` and `build`
+
+Both files have clearly marked `// TODO` blocks — drop in your actual build commands, server launchers, or watchers there. Cross-platform terminal helpers (Windows Terminal, CMD, gnome-terminal, osascript) are already included in `dev.js`.
+
+### 5. Update compatibility (when needed)
+
+When you make breaking changes to the template structure, bump `COMPAT` in `lib/compat.js` so existing projects get a clear error instead of a silent failure:
+
+```js
+// lib/compat.js
+export const pluginVersion = "1.1.0";
+
+export const COMPAT = {
+    global: ">=1.1.0",  // bump when ALL commands need a newer project
+    commands: {
+        build: ">=1.1.0",  // or target a specific command
+    },
+};
+```
+
+---
+
+## Logger Helpers
+
+All commands share the same logging helpers from `lib/logger.js`:
+
+```js
+import { ok, fail, warn, info, step, header, divider } from "../logger.js";
+
+ok(chalk, "Thing worked");        //  ✔  Thing worked  (green)
+fail(chalk, "Thing broke");       //  ✖  Thing broke   (red)
+warn(chalk, "Watch out");         //  ⚠  Watch out     (yellow)
+info(chalk, "Just so you know");  //  ·  Just so you know (gray)
+
+step(chalk, 1, 3, "Doing X");     // [1/3]  Doing X
+header(chalk, "my-command");      // jdm / plugin-template / my-command
+divider(chalk);                   // ─────────────────────────────────────
+```
+
+---
+
+## Config System
+
+Every scaffolded project gets a `.jdm-config.json` file. This allows commands to verify they're running inside a compatible project:
+
+```json
+{
+  "plugin-template": {
+    "pluginVersion": "1.0.0",
+    "createdAt": "2025-01-01T00:00:00.000Z",
+    "projectName": "my-plugin"
+  }
+}
+```
+
+Use `checkCompat(chalk, "command-name")` at the top of any command that requires a valid project context. It will warn if the config is missing, or error with a helpful message if the version is out of range.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- Git (for the `create` command)
+- jdm-cli installed globally
+
+---
+
+## License
+
+MIT — [JDM-Github](https://github.com/JDM-Github)

package/bin/guard.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import chalk from "chalk";
+import stringWidth from "string-width";
+import stripAnsi from "strip-ansi";
+
+const box = (lines) => {
+    const cleaned = lines.map(l => stripAnsi(l));
+
+    const width = Math.max(...cleaned.map(stringWidth));
+
+    const horizontal = width + 2;
+
+    const top = "┌" + "─".repeat(horizontal) + "┐";
+    const bottom = "└" + "─".repeat(horizontal) + "┘";
+
+    const mid = lines.map((l, i) => {
+        const rawWidth = stringWidth(cleaned[i]);
+        const pad = horizontal - rawWidth - 1;
+        return "│ " + l + " ".repeat(pad) + "│";
+    });
+    return [top, ...mid, bottom].join("\n");
+};
+
+const output = box([
+    chalk.red("⛔ Direct usage is not allowed."),
+    "",
+    "This package is a jdm-cli plugin-template.",
+    "Install jdm-cli first, then register this plugin:",
+    "",
+    "npm install -g jdm-cli",
+    "jdm-cli add plugin-template",
+    "",
+    "Then use it via:",
+    "jdm-cli plugin-template <command>",
+]);
+
+console.log("\n" + output + "\n");

package/lib/commands/build.js

@@ -0,0 +1,109 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/commands/build.js
+//
+//  The "build" command compiles / packages your project.
+//
+//  This template shows:
+//    ✔  Multi-flag build stages (--frontend, --backend, --full)
+//    ✔  How to shell out to build tools (npm run build, etc.)
+//    ✔  How to copy output files to a destination folder
+//    ✔  Graceful error handling per stage
+//
+//  Rename to compile.js / bundle.js / package.js — whatever
+//  makes sense for your plugin.
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { checkCompat } from "../config.js";
+import { ok, fail, info, warn, step, header, divider } from "../logger.js";
+
+// ─────────────────────────────────────────────────────────────
+//  Internal exec helper
+// ─────────────────────────────────────────────────────────────
+function exec(cmd, opts = {}) {
+    try {
+        execSync(cmd, { ...opts, stdio: "pipe" });
+    } catch (err) {
+        const out = [err.stdout?.toString(), err.stderr?.toString()].filter(Boolean).join("\n");
+        throw new Error(out || err.message);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Build stages  (each is its own function — easy to compose)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Example "frontend" stage.
+ * Replace with your actual frontend build command + output path.
+ */
+function buildFrontend(chalk, root) {
+    // const frontendDir = path.join(root, "frontend");
+    // info(chalk, "Building frontend...");
+    // exec("npm run build", { cwd: frontendDir });
+    // ok(chalk, "Frontend built");
+
+    // Placeholder
+    info(chalk, "buildFrontend placeholder — wire up your build command.");
+    ok(chalk, "Frontend stage done (placeholder)");
+}
+
+/**
+ * Example "backend" stage.
+ * Replace with your backend compile/package command.
+ */
+function buildBackend(chalk, root) {
+    // const backendDir = path.join(root, "backend");
+    // info(chalk, "Packaging backend...");
+    // exec("python build.py", { cwd: backendDir });
+    // ok(chalk, "Backend packaged");
+
+    info(chalk, "buildBackend placeholder — wire up your build command.");
+    ok(chalk, "Backend stage done (placeholder)");
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Main export
+//  Signature: build(chalk, args)
+// ─────────────────────────────────────────────────────────────
+export default async function build(chalk, args = []) {
+    header(chalk, "build");
+
+    // ── Guard ─────────────────────────────────────────────────
+    if (!checkCompat(chalk, "build")) return;
+
+    // ── Parse flags ───────────────────────────────────────────
+    //  --frontend   build only the frontend
+    //  --backend    build only the backend
+    //  --full       build everything (same as --frontend --backend)
+    const doFrontend = args.includes("--frontend") || args.includes("--full");
+    const doBackend = args.includes("--backend") || args.includes("--full");
+    const doAll = !doFrontend && !doBackend;   // no flags → build all
+
+    const root = process.cwd();
+    let stageN = 1;
+    const total = (doAll ? 2 : 0) + (doFrontend ? 1 : 0) + (doBackend ? 1 : 0);
+
+    try {
+        if (doFrontend || doAll) {
+            step(chalk, stageN++, total, "Frontend");
+            buildFrontend(chalk, root);
+        }
+
+        if (doBackend || doAll) {
+            step(chalk, stageN++, total, "Backend");
+            buildBackend(chalk, root);
+        }
+    } catch (err) {
+        fail(chalk, `Build failed: ${err.message}`);
+        return;
+    }
+
+    console.log();
+    divider(chalk);
+    console.log(chalk.green("    ✔  Build complete!"));
+    divider(chalk);
+    console.log();
+}

package/lib/commands/clean.js

@@ -0,0 +1,74 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/commands/clean.js
+//
+//  The "clean" command removes build artifacts and temp files.
+//
+//  This template shows:
+//    ✔  How to remove folders/files with existence checks
+//    ✔  How to give the user a dry-run option (--dry)
+//    ✔  Pattern for defining what to clean in one place
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import { checkCompat } from "../config.js";
+import { ok, warn, info, header, divider } from "../logger.js";
+
+// ── Define everything that should be cleaned here ─────────────
+//  Each entry is relative to process.cwd().
+//  Add/remove paths to match your plugin's output structure.
+const CLEAN_TARGETS = [
+    "dist",
+    "build",
+    ".cache",
+    // "some-other-artifact-folder",
+];
+
+// ─────────────────────────────────────────────────────────────
+//  Main export
+//  Signature: clean(chalk, args)
+// ─────────────────────────────────────────────────────────────
+export default async function clean(chalk, args = []) {
+    header(chalk, "clean");
+
+    // ── Guard: must be inside a valid project ─────────────────
+    if (!checkCompat(chalk, "clean")) return;
+
+    // ── Flags ─────────────────────────────────────────────────
+    //  --dry   Print what would be deleted without deleting it
+    const dry = args.includes("--dry");
+    if (dry) info(chalk, chalk.yellow("Dry run — nothing will be deleted"));
+
+    const root = process.cwd();
+    let removed = 0;
+
+    for (const target of CLEAN_TARGETS) {
+        const fullPath = path.join(root, target);
+
+        if (!fs.existsSync(fullPath)) {
+            // Skip silently — already clean
+            continue;
+        }
+
+        if (dry) {
+            warn(chalk, `Would remove: ${chalk.cyan(target)}`);
+        } else {
+            fs.rmSync(fullPath, { recursive: true, force: true });
+            ok(chalk, `Removed ${chalk.cyan(target)}`);
+            removed++;
+        }
+    }
+
+    if (removed === 0 && !dry) {
+        info(chalk, "Nothing to clean.");
+    }
+
+    console.log();
+    divider(chalk);
+    console.log(dry
+        ? chalk.yellow("    ⚠  Dry run complete — no files deleted")
+        : chalk.green("    ✔  Clean complete!")
+    );
+    divider(chalk);
+    console.log();
+}

package/lib/commands/create.js

@@ -0,0 +1,228 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/commands/create.js
+//
+//  The "create" command scaffolds a new project for your plugin.
+//
+//  This template shows:
+//    ✔  How to use the header / step / ok / fail / info helpers
+//    ✔  How to prompt the user interactively with rl (readline)
+//    ✔  How to use the --name flag to skip the prompt
+//    ✔  How to clone a GitHub repo and strip .git
+//    ✔  How to write a local config file (.jdm-config.json)
+//    ✔  How to use an install.log for error output
+//
+//  Remove or replace anything you don't need.
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { writeConfig } from "../config.js";
+import { ok, fail, warn, info, step, header, divider } from "../logger.js";
+
+// ── Replace this with your actual GitHub template repo URL ────
+const TEMPLATE_REPO = "https://github.com/JDM-Github/jdm-plugin-template";
+
+// ── Folders that would conflict in cwd install ────────────────
+const CONFLICT_FOLDERS = ["src", "dist"]; // ← adjust as needed
+
+// ─────────────────────────────────────────────────────────────
+//  Install log  (written to <targetDir>/install.log on error)
+// ─────────────────────────────────────────────────────────────
+let logPath = null;
+
+function initLog(targetDir) {
+    logPath = path.join(targetDir, "install.log");
+    fs.writeFileSync(logPath, `[install log — ${new Date().toISOString()}]\n\n`, "utf8");
+}
+
+function appendLog(line) {
+    if (logPath) fs.appendFileSync(logPath, line + "\n", "utf8");
+}
+
+function cleanLog() {
+    if (logPath && fs.existsSync(logPath)) {
+        fs.unlinkSync(logPath);
+        logPath = null;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Exec wrapper  (captures stdout/stderr into install.log)
+// ─────────────────────────────────────────────────────────────
+function exec(cmd, opts = {}) {
+    try {
+        const result = execSync(cmd, { ...opts, stdio: "pipe" });
+        if (result) appendLog(`[OK] ${cmd}\n${result.toString()}`);
+        return result;
+    } catch (err) {
+        appendLog([
+            `[FAIL] ${cmd}`,
+            err.stdout?.toString() ?? "",
+            err.stderr?.toString() ?? "",
+        ].join("\n"));
+        throw err;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  rl helper  (wraps readline.question as a Promise)
+// ─────────────────────────────────────────────────────────────
+function ask(rl, question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Main export
+//  Signature must match what index.js passes:
+//    create(chalk, rl, args)
+// ─────────────────────────────────────────────────────────────
+export default async function create(chalk, rl, args = []) {
+    header(chalk, "create");
+
+    // ── Parse flags ───────────────────────────────────────────
+    //  --name my-project   → skip the name prompt
+    //  --install           → run npm install / pip install after clone
+    const nameIdx = args.indexOf("--name");
+    const nameArg = nameIdx !== -1 ? args[nameIdx + 1] : null;
+    const shouldInstall = args.includes("--install");
+
+    // ── Step 1: resolve target directory ─────────────────────
+    step(chalk, 1, 3, "Target Directory");
+
+    const answer = nameArg
+        ?? (await ask(rl, chalk.white("\n  Project name (or . for current folder): "))).trim();
+
+    let targetDir;
+
+    if (answer === ".") {
+        // ── Install into current directory ────────────────────
+        targetDir = process.cwd();
+        info(chalk, `Using current directory: ${chalk.cyan(targetDir)}`);
+
+        const entries = fs.readdirSync(targetDir);
+        const conflicts = entries.filter(
+            (e) => CONFLICT_FOLDERS.includes(e) && fs.statSync(path.join(targetDir, e)).isDirectory()
+        );
+
+        if (conflicts.length > 0) {
+            fail(chalk, `Conflicting folders: ${conflicts.map((c) => chalk.red(c)).join(", ")}`);
+            const confirm = (await ask(rl, chalk.white("  Remove them and continue? [y/N]: "))).trim().toLowerCase();
+            if (confirm !== "y") {
+                console.log(chalk.gray("\n  Aborted.\n"));
+                return;
+            }
+            for (const c of conflicts) {
+                fs.rmSync(path.join(targetDir, c), { recursive: true, force: true });
+                ok(chalk, `Removed ${chalk.red(c)}`);
+            }
+        } else if (entries.length > 0) {
+            warn(chalk, "Current folder is not empty.");
+            const confirm = (await ask(rl, chalk.white("  Continue anyway? [y/N]: "))).trim().toLowerCase();
+            if (confirm !== "y") {
+                console.log(chalk.gray("\n  Aborted.\n"));
+                return;
+            }
+        }
+
+    } else {
+        // ── Create a named subfolder ──────────────────────────
+        if (!answer || answer.includes("/") || answer.includes("\\")) {
+            fail(chalk, "Invalid project name.");
+            return;
+        }
+        targetDir = path.join(process.cwd(), answer);
+        if (fs.existsSync(targetDir)) {
+            warn(chalk, `Folder ${chalk.cyan(answer)} already exists.`);
+            const confirm = (await ask(rl, chalk.white("  Continue anyway? [y/N]: "))).trim().toLowerCase();
+            if (confirm !== "y") {
+                console.log(chalk.gray("\n  Aborted.\n"));
+                return;
+            }
+        } else {
+            fs.mkdirSync(targetDir, { recursive: true });
+            ok(chalk, `Created folder: ${chalk.cyan(targetDir)}`);
+        }
+    }
+
+    initLog(targetDir);
+
+    // ── Step 2: clone template ────────────────────────────────
+    step(chalk, 2, 3, "Cloning template");
+
+    try {
+        info(chalk, `Cloning from ${chalk.cyan(TEMPLATE_REPO)}...`);
+
+        // Clone into a temp subfolder first to avoid git's "already exists
+        // and is not an empty directory" error — which always fires when the
+        // template repo is cloning itself into its own working directory.
+        const tmpDir = path.join(targetDir, "__jdm_tmp__");
+        if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+        exec(`git clone ${TEMPLATE_REPO} "${tmpDir}"`);
+
+        // Strip .git so this becomes a clean project, not a fork
+        const gitDir = path.join(tmpDir, ".git");
+        if (fs.existsSync(gitDir)) {
+            fs.rmSync(gitDir, { recursive: true, force: true });
+            info(chalk, "Removed .git (clean slate)");
+        }
+
+        // Move all cloned files from tmpDir into targetDir,
+        // overwriting anything that was already there.
+        for (const entry of fs.readdirSync(tmpDir)) {
+            const src = path.join(tmpDir, entry);
+            const dest = path.join(targetDir, entry);
+            if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+            fs.renameSync(src, dest);
+        }
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+
+        ok(chalk, "Template cloned");
+    } catch (err) {
+        fail(chalk, `Clone failed: ${err.message}`);
+        console.log(chalk.yellow("\n    Full output written to: ") + chalk.white("install.log"));
+        return;
+    }
+
+    // ── Step 3: optional dependency install ──────────────────
+    step(chalk, 3, 3, "Dependencies");
+
+    if (shouldInstall) {
+        try {
+            info(chalk, "Running npm install...");
+            exec("npm install", { cwd: targetDir });
+            ok(chalk, "Dependencies installed");
+        } catch (err) {
+            fail(chalk, `npm install failed: ${err.message}`);
+            console.log(chalk.yellow("\n    Full output written to: ") + chalk.white("install.log"));
+            return;
+        }
+    } else {
+        info(chalk, "Skipped (pass --install to auto-install)");
+    }
+
+    // ── Write local config ────────────────────────────────────
+    writeConfig(targetDir, { projectName: path.basename(targetDir) });
+    info(chalk, `Created ${chalk.cyan(".jdm-config.json")}`);
+
+    cleanLog();
+
+    // ── Done ──────────────────────────────────────────────────
+    console.log();
+    divider(chalk);
+    console.log(chalk.green("    ✔  Project ready!"));
+    console.log(chalk.gray(`    Location: ${targetDir}`));
+    divider(chalk);
+    console.log();
+
+    if (!shouldInstall) {
+        console.log(chalk.white("  Next steps:"));
+        console.log(chalk.gray("    jdm-cli <namespace> install  →  install dependencies"));
+        console.log(chalk.gray("    jdm-cli <namespace> dev      →  start development"));
+    } else {
+        console.log(chalk.white("  Next steps:"));
+        console.log(chalk.gray("    jdm-cli <namespace> dev  →  start development"));
+    }
+    console.log();
+}

package/lib/commands/dev.js

@@ -0,0 +1,147 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/commands/dev.js
+//
+//  The "dev" command starts your development environment.
+//
+//  This template shows:
+//    ✔  How to guard a command with checkCompat
+//    ✔  How to spawn processes in new terminal windows
+//       (Windows Terminal → CMD fallback → Unix terminals)
+//    ✔  How to allocate free ports dynamically
+//    ✔  How to pass env vars to spawned processes
+//
+//  Replace the process launch blocks with whatever your plugin
+//  needs to start (servers, watchers, proxies, etc.)
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import net from "net";
+import { spawn } from "child_process";
+import { checkCompat } from "../config.js";
+import { ok, fail, info, header, divider } from "../logger.js";
+
+// ─────────────────────────────────────────────────────────────
+//  Port allocation
+// ─────────────────────────────────────────────────────────────
+
+/** Returns a free port on 127.0.0.1 by binding to port 0. */
+function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            server.close(() => resolve(port));
+        });
+        server.on("error", reject);
+    });
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Cross-platform terminal launchers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Launch a command in a new Windows Terminal tab.
+ * Falls back to launchInCmdWindow if wt.exe isn't available.
+ */
+function launchInWindowsTerminal(title, cwd, command, args, env = {}) {
+    const envPrefix = Object.entries(env).map(([k, v]) => `set ${k}=${v} &&`).join(" ");
+    const fullCmd = `cd /d "${cwd}" && ${envPrefix} ${command} ${args.join(" ")}`;
+
+    const proc = spawn("wt.exe", [
+        "-w", "0", "new-tab", "--title", title,
+        "--", "cmd.exe", "/k", fullCmd,
+    ], { detached: true, stdio: "ignore", shell: false });
+
+    proc.unref();
+}
+
+/** Launch in a plain new CMD window (fallback when wt.exe is absent). */
+function launchInCmdWindow(cwd, command, args, env = {}) {
+    const envPrefix = Object.entries(env).map(([k, v]) => `set ${k}=${v} &&`).join(" ");
+    const fullCmd = `cd /d "${cwd}" && ${envPrefix} ${command} ${args.join(" ")}`;
+
+    const proc = spawn("cmd.exe", ["/c", "start", "cmd.exe", "/k", fullCmd], {
+        detached: true, stdio: "ignore", shell: false,
+    });
+    proc.unref();
+}
+
+/** Try Windows Terminal; return false if unavailable. */
+function tryWindowsTerminal(title, cwd, command, args, env = {}) {
+    try { launchInWindowsTerminal(title, cwd, command, args, env); return true; }
+    catch { return false; }
+}
+
+/** Try common Unix/macOS terminals in priority order. */
+function launchInUnixTerminal(title, cwd, command, args, env = {}) {
+    const envPrefix = Object.entries(env).map(([k, v]) => `${k}=${v}`).join(" ");
+    const fullCmd = `cd "${cwd}" && ${envPrefix} ${command} ${args.join(" ")}; exec $SHELL`;
+
+    const terminals = [
+        ["gnome-terminal", ["--title", title, "--", "bash", "-c", fullCmd]],
+        ["xterm", ["-title", title, "-e", `bash -c '${fullCmd}'`]],
+        ["osascript", ["-e", `tell application "Terminal" to do script "cd \\"${cwd}\\" && ${envPrefix} ${command} ${args.join(" ")}"`]],
+    ];
+
+    for (const [term, termArgs] of terminals) {
+        try {
+            spawn(term, termArgs, { detached: true, stdio: "ignore" }).unref();
+            return true;
+        } catch { /* try next */ }
+    }
+    return false;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Main export
+//  Signature: dev(chalk, args)
+//  No rl — dev doesn't need interactive prompts.
+// ─────────────────────────────────────────────────────────────
+export default async function dev(chalk, args = []) {
+    header(chalk, "dev");
+
+    // ── Guard: must be inside a valid project ─────────────────
+    if (!checkCompat(chalk, "dev")) return;
+
+    const root = process.cwd();
+
+    // ── TODO: define your service directories here ────────────
+    //  const backendDir  = path.join(root, "backend");
+    //  const frontendDir = path.join(root, "frontend");
+    //
+    //  Example existence check:
+    //  if (!fs.existsSync(backendDir)) {
+    //      fail(chalk, `backend/ not found in ${chalk.cyan(root)}`);
+    //      return;
+    //  }
+
+    // ── Allocate ports (remove if your plugin doesn't use them)
+    // const port = await getFreePort();
+    // info(chalk, `Allocated port ${port}`);
+
+    // ── TODO: launch your dev processes ──────────────────────
+    //
+    //  Windows example:
+    //    const launched = tryWindowsTerminal("My Dev Server", root, "npm", ["run", "dev"], {});
+    //    if (!launched) launchInCmdWindow(root, "npm", ["run", "dev"], {});
+    //
+    //  Unix example:
+    //    const success = launchInUnixTerminal("My Dev Server", root, "npm", ["run", "dev"], {});
+    //    if (!success) {
+    //        fail(chalk, "Could not open terminal. Run manually:");
+    //        console.log(chalk.gray(`      cd "${root}" && npm run dev`));
+    //        return;
+    //    }
+
+    // ── Placeholder output — replace when you wire up processes
+    info(chalk, "Dev command placeholder — wire up your processes above.");
+    ok(chalk, "Nothing launched yet (template mode)");
+
+    console.log();
+    divider(chalk);
+    console.log(chalk.green("    ✔  Dev environment ready!"));
+    divider(chalk);
+    console.log();
+}

package/lib/commands/install.js

@@ -0,0 +1,102 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/commands/install.js
+//
+//  The "install" command installs dependencies for the project.
+//
+//  This template shows:
+//    ✔  Running npm install / pip install per sub-folder
+//    ✔  Checking for package.json / requirements.txt before running
+//    ✔  Reporting success/failure per package manager
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { checkCompat } from "../config.js";
+import { ok, fail, warn, info, step, header, divider } from "../logger.js";
+
+// ── Directories to install deps for ───────────────────────────
+//  Each entry:
+//    dir     → subfolder relative to project root
+//    type    → "npm" | "pip"
+//
+//  Add, remove, or reorder as your plugin needs.
+const INSTALL_TARGETS = [
+    { dir: ".", type: "npm" }
+    // { dir: "frontend", type: "npm" },
+    // { dir: "backend",  type: "pip" },
+];
+
+// ─────────────────────────────────────────────────────────────
+function exec(cmd, opts = {}) {
+    try {
+        execSync(cmd, { ...opts, stdio: "pipe" });
+    } catch (err) {
+        const out = [err.stdout?.toString(), err.stderr?.toString()].filter(Boolean).join("\n");
+        throw new Error(out || err.message);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Main export
+//  Signature: install(chalk, args)
+// ─────────────────────────────────────────────────────────────
+export default async function install(chalk, args = []) {
+    header(chalk, "install");
+
+    // ── Guard ─────────────────────────────────────────────────
+    if (!checkCompat(chalk, "install")) return;
+
+    const root = process.cwd();
+
+    if (INSTALL_TARGETS.length === 0) {
+        info(chalk, "No install targets defined yet.");
+        info(chalk, "Edit INSTALL_TARGETS in lib/commands/install.js to add your dirs.");
+        console.log();
+        return;
+    }
+
+    for (let i = 0; i < INSTALL_TARGETS.length; i++) {
+        const { dir, type } = INSTALL_TARGETS[i];
+        step(chalk, i + 1, INSTALL_TARGETS.length, `Installing ${dir}`);
+
+        const fullDir = path.join(root, dir);
+
+        if (!fs.existsSync(fullDir)) {
+            warn(chalk, `${dir}/ not found — skipping`);
+            continue;
+        }
+
+        try {
+            if (type === "npm") {
+                const pkgJson = path.join(fullDir, "package.json");
+                if (!fs.existsSync(pkgJson)) {
+                    warn(chalk, `No package.json in ${dir}/ — skipping`);
+                    continue;
+                }
+                info(chalk, `Running npm install in ${chalk.cyan(dir)}/...`);
+                exec("npm install", { cwd: fullDir });
+                ok(chalk, "npm dependencies installed");
+
+            } else if (type === "pip") {
+                const req = path.join(fullDir, "requirements.txt");
+                if (!fs.existsSync(req)) {
+                    warn(chalk, `No requirements.txt in ${dir}/ — skipping`);
+                    continue;
+                }
+                info(chalk, `Running pip install in ${chalk.cyan(dir)}/...`);
+                exec("pip install -r requirements.txt", { cwd: fullDir });
+                ok(chalk, "Python dependencies installed");
+            }
+        } catch (err) {
+            fail(chalk, `Failed to install ${dir}: ${err.message}`);
+            return;
+        }
+    }
+
+    console.log();
+    divider(chalk);
+    console.log(chalk.green("    ✔  All dependencies installed!"));
+    divider(chalk);
+    console.log();
+}

package/lib/compat.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/compat.js
+//
+//  Single source of truth for version compatibility.
+//
+//  HOW IT WORKS
+//  ─────────────
+//  • `pluginVersion`  – the version of THIS plugin (bump on releases)
+//  • `COMPAT.global`  – minimum project version required by ALL commands
+//  • `COMPAT.commands`– per-command overrides (takes priority over global)
+//
+//  RANGE SYNTAX (no external deps)
+//  ────────────────────────────────
+//  ">=1.0.0"           project created with plugin 1.0.0 or newer
+//  "<=2.0.0"           project created with plugin 2.0.0 or older
+//  "1.0.0"             exact version only
+//  ">=1.0.0||<=0.9.5"  union (rare — use sparingly)
+//
+//  WHEN TO BUMP
+//  ─────────────
+//  • You change a template repo structure that breaks an existing command
+//    → bump COMPAT.commands[thatCommand] to ">=<new-plugin-version>"
+//  • You change something that affects ALL commands (e.g. config layout)
+//    → bump COMPAT.global
+//  • You add a brand-new command that doesn't touch existing templates
+//    → no bump needed
+// ─────────────────────────────────────────────────────────────
+
+export const pluginVersion = "1.0.0";
+
+export const COMPAT = {
+
+    // Every command: project must have been created with >= this version.
+    // Set to null to disable the global check.
+    global: ">=1.0.0",
+
+    // Per-command overrides.
+    // Only add an entry here when a command needs a tighter requirement
+    // than the global range.
+    commands: {
+        // "build": ">=1.0.0",
+    },
+};

package/lib/config.js

@@ -0,0 +1,150 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/config.js
+// ─────────────────────────────────────────────────────────────
+
+import fs from "fs";
+import path from "path";
+import { COMPAT, pluginVersion } from "./compat.js";
+
+export const CONFIG_FILE = ".jdm-config.json";
+
+// ── CHANGE THIS to match your plugin's namespace ──────────────
+const PLUGIN_NAME = "plugin-template"; // ← CHANGE THIS
+
+// ─────────────────────────────────────────────────────────────
+//  Version helpers
+// ─────────────────────────────────────────────────────────────
+function parseVer(v) {
+    return String(v).split(".").map(Number);
+}
+
+function cmpVer(a, b) {
+    const pa = parseVer(a);
+    const pb = parseVer(b);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0) return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+
+export function satisfies(version, range) {
+    if (!range) return true;
+    const rangeList = range.split("||").map(r => r.trim());
+    return rangeList.some(r => {
+        if (r.startsWith(">=")) return cmpVer(version, r.slice(2)) >= 0;
+        if (r.startsWith("<=")) return cmpVer(version, r.slice(2)) <= 0;
+        if (r.startsWith(">")) return cmpVer(version, r.slice(1)) > 0;
+        if (r.startsWith("<")) return cmpVer(version, r.slice(1)) < 0;
+        return cmpVer(version, r) === 0; // exact match
+    });
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Config read / write
+// ─────────────────────────────────────────────────────────────
+export function configExists(root = process.cwd()) {
+    return fs.existsSync(path.join(root, CONFIG_FILE));
+}
+
+/**
+ * Read the full .jdm-config.json and return only this plugin's slice.
+ * Returns null  → file is missing or unparseable.
+ * Returns {}    → file exists but has no entry for this plugin yet.
+ */
+export function readConfig(root = process.cwd()) {
+    const p = path.join(root, CONFIG_FILE);
+    if (!fs.existsSync(p)) return null;
+    try {
+        const full = JSON.parse(fs.readFileSync(p, "utf8"));
+        return full[PLUGIN_NAME] ?? {};
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Merge this plugin's data into .jdm-config.json under its own key.
+ * Other plugins' keys are left untouched.
+ *
+ * Resulting shape:
+ * {
+ *   "plugin-template": { pluginVersion, createdAt, ...extra },
+ *   "other-plugin":    { ... }   <- untouched
+ * }
+ */
+export function writeConfig(root = process.cwd(), extra = {}) {
+    const p = path.join(root, CONFIG_FILE);
+
+    // Preserve any existing keys from other plugins
+    let full = {};
+    if (fs.existsSync(p)) {
+        try { full = JSON.parse(fs.readFileSync(p, "utf8")); } catch { /* start fresh */ }
+    }
+
+    const pluginData = {
+        pluginVersion,
+        createdAt: new Date().toISOString(),
+        ...extra,
+    };
+
+    full[PLUGIN_NAME] = pluginData;
+    fs.writeFileSync(p, JSON.stringify(full, null, 2) + "\n", "utf8");
+    return pluginData;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  checkCompat()
+//
+//  Call at the top of any command that requires the user to be
+//  inside a project scaffolded by this plugin.
+//
+//  Returns true  → safe to proceed
+//  Returns false → caller should return early
+// ─────────────────────────────────────────────────────────────
+export function checkCompat(chalk, command) {
+    const root = process.cwd();
+    const cfg = readConfig(root);
+
+    // cfg === null → file missing entirely
+    // cfg === {}   → file exists but has no entry for this plugin yet
+    if (cfg === null || !cfg.pluginVersion) {
+        console.log();
+        console.log(chalk.yellow("  ⚠  No .jdm-config.json entry found for this plugin."));
+        console.log(chalk.gray(`     This may not be a jdm-${PLUGIN_NAME} project,`));
+        console.log(chalk.gray("     or it was created before config tracking was introduced."));
+        const globalRange = COMPAT.global ?? null;
+        if (globalRange) {
+            console.log(chalk.gray(`     Expected a project created with plugin ${chalk.white(globalRange)}.`));
+        }
+        console.log(chalk.gray("     Proceeding anyway — things may not work as expected.\n"));
+        return true;
+    }
+
+    // ── Version range check ───────────────────────────────────
+    const projectVer = cfg.pluginVersion;
+    const range = COMPAT.commands?.[command] ?? COMPAT.global ?? null;
+    if (!range) return true;
+
+    if (!satisfies(projectVer, range)) {
+        const cmdLabel = COMPAT.commands?.[command] ? `"${command}"` : "this plugin";
+        console.log();
+        console.log(chalk.red(`  ✖  Compatibility error for command: ${chalk.bold(command)}`));
+        console.log(
+            chalk.gray("     Project was created with plugin version ") +
+            chalk.cyan(projectVer) +
+            chalk.gray(",")
+        );
+        console.log(
+            chalk.gray(`     but ${cmdLabel} requires `) +
+            chalk.white(range) +
+            chalk.gray(".")
+        );
+        console.log();
+        console.log(chalk.yellow("  Tip: ") + chalk.gray("Re-scaffold with ") + chalk.white(`jdm-cli ${PLUGIN_NAME} create`));
+        console.log(chalk.gray("       or update the plugin to a version that supports your project.\n"));
+        return false;
+    }
+
+    return true;
+}

package/lib/index.js

@@ -0,0 +1,107 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/index.js
+//
+//  Main entry point for the plugin.
+//  jdm-cli imports this file and calls run(command, args, chalk, rl).
+//
+//  Required exports:
+//    namespace  (string)  — the CLI prefix:  jdm <namespace> <command>
+//    commands   (object)  — map of command name → handler function
+//    run        (fn)      — dispatcher called by jdm-cli
+//    showDesign (fn)      — prints the help screen
+//
+//  To add a new command:
+//    1. Create lib/commands/my-command.js with a default export
+//    2. Import it here
+//    3. Add it to the `commands` map
+//    4. Add it to showDesign()
+//    5. Add it to the jdmPlugin.commands array in package.json
+// ─────────────────────────────────────────────────────────────
+
+import create from "./commands/create.js";
+import dev from "./commands/dev.js";
+import build from "./commands/build.js";
+import clean from "./commands/clean.js";
+import install from "./commands/install.js";
+
+// ── Namespace ─────────────────────────────────────────────────
+//  This is the prefix used in the CLI:  jdm <namespace> <command>
+//  Change this to match your plugin's jdmPlugin.namespace in package.json
+export const namespace = "plugin-template"; // ← CHANGE THIS
+
+// ── Command map ───────────────────────────────────────────────
+//  Keys are the exact command strings the user types.
+//  Values are the imported handler functions.
+//
+//  Commands that need interactive prompts receive (chalk, rl, args).
+//  Commands that don't need prompts receive (chalk, args).
+//  See the run() dispatcher below for how this is handled.
+export const commands = {
+    create,
+    dev,
+    build,
+    clean,
+    install,
+
+    // ── Add your own commands here ────────────────────────────
+    // "my-command": myCommand,
+};
+
+// ── Commands that need the readline interface (rl) ────────────
+//  List any command names that call ask(rl, ...) for user input.
+const INTERACTIVE_COMMANDS = ["create"];
+
+// ─────────────────────────────────────────────────────────────
+//  run()  —  called by jdm-cli for every invocation
+//
+//  command  (string)   — e.g. "create", "dev", "build"
+//  args     (string[]) — remaining CLI args / flags
+//  chalk    (object)   — chalk instance from jdm-cli
+//  rl       (object)   — readline interface from jdm-cli
+// ─────────────────────────────────────────────────────────────
+export async function run(command, args, chalk, rl) {
+
+    // ── Help shortcut ─────────────────────────────────────────
+    if (command === "help" || command === "--help" || command === "-h" || !command) {
+        return showDesign(chalk);
+    }
+
+    // ── Lookup ────────────────────────────────────────────────
+    const fn = commands[command];
+    if (!fn) {
+        console.log(chalk.red(`\n  ✖  Unknown command: "${command}"`));
+        console.log(chalk.gray(`     Available: ${Object.keys(commands).join(", ")}`));
+        return;
+    }
+
+    // ── Dispatch ──────────────────────────────────────────────
+    if (INTERACTIVE_COMMANDS.includes(command)) {
+        return fn(chalk, rl, args);
+    }
+    return fn(chalk, args);
+}
+
+// ─────────────────────────────────────────────────────────────
+//  showDesign()  —  the help / overview screen
+//
+//  Customize this to describe your plugin's commands.
+// ─────────────────────────────────────────────────────────────
+export async function showDesign(chalk) {
+    console.log(chalk.cyan(`\n  ⚡ ${namespace} Plugin`));
+    // ← Replace the tagline with your plugin's description
+    console.log(chalk.gray("     Your plugin tagline goes here."));
+    console.log(chalk.gray("     Available commands:\n"));
+
+    // ── List your commands here ───────────────────────────────
+    //  Format:  command name (padded)  +  short description
+    console.log(`  ${chalk.green("create")}      ${chalk.dim("Scaffold a new project")}`);
+    console.log(`  ${chalk.green("dev")}         ${chalk.dim("Start development environment")}`);
+    console.log(`  ${chalk.green("build")}       ${chalk.dim("Compile / package the project")}`);
+    console.log(`  ${chalk.green("clean")}       ${chalk.dim("Remove build artifacts")}`);
+    console.log(`  ${chalk.green("install")}     ${chalk.dim("Install dependencies")}`);
+
+    // ── Add your own commands to the list above ───────────────
+    // console.log(`  ${chalk.green("my-command")}  ${chalk.dim("Does something useful")}`);
+
+    console.log();
+}

package/lib/logger.js

@@ -0,0 +1,45 @@
+// ─────────────────────────────────────────────────────────────
+//  jdm-plugin-template  —  lib/logger.js
+//
+//  Shared logging helpers used across all commands.
+//  Import what you need:
+//    import { ok, fail, info, warn, step, header } from "../logger.js";
+//
+//  All functions take (chalk, msg) so chalk stays injectable
+//  and the plugin doesn't need to manage a global chalk ref.
+// ─────────────────────────────────────────────────────────────
+
+// ── Pretty-print helpers ──────────────────────────────────────
+export function ok(chalk, msg) { console.log(chalk.green("    ✔  ") + msg); }
+export function fail(chalk, msg) { console.log(chalk.red("    ✖  ") + msg); }
+export function warn(chalk, msg) { console.log(chalk.yellow("    ⚠  ") + msg); }
+export function info(chalk, msg) { console.log(chalk.gray("    ·  ") + msg); }
+
+// ── Step counter line ─────────────────────────────────────────
+//  step(chalk, 1, 3, "Doing the thing")  →  [1/3]  Doing the thing
+export function step(chalk, n, total, label) {
+    console.log();
+    console.log(chalk.cyan(`  [${n}/${total}]`) + "  " + chalk.bold(label));
+}
+
+// ── Command header ────────────────────────────────────────────
+//  header(chalk, "create")  →  jdm / your-namespace / create
+//
+//  Customize the namespace string to match your plugin.
+export function header(chalk, command = "") {
+    const ns = "plugin-template"; // ← replace with your namespace
+    console.log();
+    console.log(
+        chalk.cyan("  jdm") +
+        chalk.gray(" / ") +
+        chalk.white(ns) +
+        (command ? chalk.gray(" / ") + chalk.bold(command) : "")
+    );
+    console.log(chalk.gray("  ─────────────────────────────────────"));
+    console.log();
+}
+
+// ── Section divider ───────────────────────────────────────────
+export function divider(chalk) {
+    console.log(chalk.gray("  ─────────────────────────────────────"));
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+    "name": "jdm-plugin-template",
+    "type": "module",
+    "version": "1.0.0",
+    "description": "A starter template for building jdm-cli plugins",
+    "main": "./lib/index.js",
+    "scripts": {
+        "test": "echo \"No tests yet\""
+    },
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "ora": "^9.4.0",
+        "string-width": "^8.2.0",
+        "strip-ansi": "^7.2.0"
+    },
+    "keywords": [
+        "jdm",
+        "plugin",
+        "template"
+    ],
+    "author": "JDM-Github",
+    "license": "MIT",
+    "jdmPlugin": {
+        "namespace": "plugin-template",
+        "description": "Your plugin description goes here",
+        "commands": [
+            {
+                "name": "create",
+                "description": "Scaffold a new project",
+                "fields": [
+                    {
+                        "key": "name",
+                        "label": "Project Name",
+                        "flag": "--name",
+                        "type": "text",
+                        "placeholder": "my-project",
+                        "required": true
+                    },
+                    {
+                        "key": "install",
+                        "label": "Install Dependencies",
+                        "flag": "--install",
+                        "type": "boolean",
+                        "default": false
+                    }
+                ]
+            },
+            {
+                "name": "dev",
+                "description": "Start development environment",
+                "fields": []
+            },
+            {
+                "name": "build",
+                "description": "Compile / package the project",
+                "fields": [
+                    {
+                        "key": "frontend",
+                        "label": "Build Frontend",
+                        "flag": "--frontend",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Build only the frontend"
+                    },
+                    {
+                        "key": "backend",
+                        "label": "Build Backend",
+                        "flag": "--backend",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Build only the backend"
+                    },
+                    {
+                        "key": "full",
+                        "label": "Full Build",
+                        "flag": "--full",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Build everything (frontend + backend)"
+                    }
+                ]
+            },
+            {
+                "name": "clean",
+                "description": "Remove build artifacts",
+                "fields": [
+                    {
+                        "key": "dry",
+                        "label": "Dry Run",
+                        "flag": "--dry",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Preview what would be deleted without deleting"
+                    }
+                ]
+            },
+            {
+                "name": "install",
+                "description": "Install dependencies",
+                "fields": []
+            }
+        ]
+    }
+}