its-magic 0.1.2-9 → 0.1.3-0

package/bin/its-magic.js

@@ -1,9 +1,52 @@
 #!/usr/bin/env node
 const path = require("path");
 const { spawnSync } = require("child_process");
+const packageJson = require("../package.json");
+
+const REPO_URL = "https://github.com/fl0wm0ti0n/its-magic";
+
+function printBanner() {
+  const M = "\x1b[1;35m";
+  const C = "\x1b[1;36m";
+  const Y = "\x1b[1;33m";
+  const R = "\x1b[0m";
+  console.log("");
+  console.log(`${M}  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗${R}`);
+  console.log(`${M}  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝${R}`);
+  console.log(`${M}  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     ${R}`);
+  console.log(`${C}  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     ${R}`);
+  console.log(`${C}  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗${R}`);
+  console.log(`${C}  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝${R}`);
+  console.log("");
+  console.log(`${Y}                         AI dev team${R}`);
+  console.log("");
+}
 
 function parseArgs(argv) {
-  const args = { target: process.cwd(), mode: "missing", backup: false, create: false };
+  const args = {
+    target: process.cwd(),
+    mode: "missing",
+    backup: false,
+    create: false,
+    cleanRepo: false,
+    yes: false,
+    help: false,
+    version: false,
+  };
+
+  if (argv.length === 0) {
+    args.help = true;
+    return args;
+  }
+
+  const first = argv[0];
+  if (first === "help") return { ...args, help: true };
+  if (first === "version") return { ...args, version: true };
+  if (first === "clean") {
+    args.cleanRepo = true;
+    argv = argv.slice(1);
+  }
+
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--target" && argv[i + 1]) {
@@ -24,24 +67,83 @@ function parseArgs(argv) {
       args.create = true;
       continue;
     }
+    if (a === "--clean-repo") {
+      args.cleanRepo = true;
+      continue;
+    }
+    if (a === "--yes") {
+      args.yes = true;
+      continue;
+    }
     if (a === "--help" || a === "-h") {
-      return { help: true };
+      args.help = true;
+      continue;
+    }
+    if (a === "--version" || a === "-v") {
+      args.version = true;
+      continue;
     }
   }
   return args;
 }
 
 function printHelp() {
-  console.log(`its-magic
+  printBanner();
+  console.log(`its-magic v${packageJson.version}
+Repository: ${REPO_URL}
+
+Install AI dev team workflow files into any Cursor repository.
 
 Usage:
-  npx its-magic --target <path> --mode missing [--backup] [--create]
+  its-magic --target <path> [--mode <mode>] [--backup] [--create]
+  its-magic --clean-repo [--target <path>] [--yes]
+  its-magic --help | --version
 
-Options:
-  --target   Target repository path (default: current directory)
-  --mode     missing | overwrite | interactive (default: missing)
-  --backup   Backup files before overwrite
-  --create   Create target directory if missing
+Install options:
+  --target <path>   Path to the repository where workflow files are installed.
+                    If omitted you will be prompted interactively.
+  --mode <mode>     How to handle files that already exist in the target:
+                      missing      Only copy files that do not exist yet (default).
+                                   Safe for repos that already have some workflow files.
+                      overwrite    Replace every file, even if it already exists.
+                                   Combine with --backup to keep a snapshot first.
+                      interactive  Ask per file whether to overwrite or skip.
+                      upgrade      Update framework files (commands, rules, agents,
+                                   hooks, skills, CI, scripts) while preserving user
+                                   data (docs, sprints, handoffs, decisions, runbook).
+                                   Use after updating its-magic to a newer version.
+  --backup          Before overwriting, save existing files to backups/<timestamp>/.
+                    Ignored when mode is "missing" (nothing gets replaced).
+  --create          Create the target directory if it does not exist.
+  Note: installer bootstraps runbook TEST/LINT/TYPECHECK commands from
+        OS+stack detection; unresolved TEST_COMMAND fails fast with
+        [RUNBOOK_BOOTSTRAP_ERROR] diagnostics.
+  Note: scratchpad Model B: .cursor/scratchpad.md is materialized when missing;
+        post-install always refreshes .cursor/scratchpad.local.example.md from the
+        template before baseline handling. PowerShell/bash installers require
+        Python 3 on PATH for merged scratchpad validation. Recovery:
+        python installer.py --scratchpad-postinstall --target <repo> --mode missing
+
+Clean options:
+  --clean-repo      Remove all its-magic workflow artifacts from the target repo
+                    (owned paths from installer manifest, including .cursor,
+                    docs/product, docs/engineering, docs/user-guides, sprints,
+                    handoffs, decisions, workflow scripts, CI files, and
+                    installer metadata under its_magic/ (legacy .its-magic-version
+                    is also removed when present). Your own source code is never touched.
+  --target <path>   Repo to clean (default: current directory).
+  --yes             Skip the confirmation prompt.
+
+Info:
+  --help, -h        Show this help and exit.
+  --version, -v     Print the installed version and exit.
+
+Examples:
+  its-magic --target . --mode missing            Safe first-time setup
+  its-magic --target . --mode upgrade             Update framework, keep user data
+  its-magic --target . --mode upgrade --backup    Upgrade with backup of old files
+  its-magic --target . --mode overwrite --backup  Replace all files, keep backup
+  its-magic --clean-repo --target . --yes         Remove workflow artifacts silently
 `);
 }
 
@@ -50,12 +152,16 @@ if (args.help) {
   printHelp();
   process.exit(0);
 }
+if (args.version) {
+  console.log(`its-magic v${packageJson.version}`);
+  process.exit(0);
+}
 
 const root = path.resolve(__dirname, "..");
 const isWin = process.platform === "win32";
 
 if (isWin) {
-  const installer = path.join(root, "gsd-installer.ps1");
+  const installer = path.join(root, "installer.ps1");
   const psArgs = [
     "-ExecutionPolicy",
     "Bypass",
@@ -68,10 +174,12 @@ if (isWin) {
   ];
   if (args.backup) psArgs.push("-Backup");
   if (args.create) psArgs.push("-Create");
+  if (args.cleanRepo) psArgs.push("-CleanRepo");
+  if (args.yes) psArgs.push("-Yes");
   const res = spawnSync("powershell", psArgs, { stdio: "inherit" });
   process.exit(res.status || 0);
 } else {
-  const installer = path.join(root, "gsd-installer.sh");
+  const installer = path.join(root, "installer.sh");
   const shArgs = [
     installer,
     "--target",
@@ -81,6 +189,8 @@ if (isWin) {
   ];
   if (args.backup) shArgs.push("--backup");
   if (args.create) shArgs.push("--create");
+  if (args.cleanRepo) shArgs.push("--clean-repo");
+  if (args.yes) shArgs.push("--yes");
   const res = spawnSync("sh", shArgs, { stdio: "inherit" });
   process.exit(res.status || 0);
 }

package/bin/postinstall.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const M = "\x1b[1;35m";
+const C = "\x1b[1;36m";
+const Y = "\x1b[1;33m";
+const G = "\x1b[1;32m";
+const W = "\x1b[1;37m";
+const R = "\x1b[0m";
+
+console.log("");
+console.log(`${M}  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗${R}`);
+console.log(`${M}  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝${R}`);
+console.log(`${M}  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     ${R}`);
+console.log(`${C}  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     ${R}`);
+console.log(`${C}  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗${R}`);
+console.log(`${C}  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝${R}`);
+console.log("");
+console.log(`${Y}                         AI dev team${R}`);
+console.log(`${G}                    Installation complete!${R}`);
+console.log("");
+console.log(`${W}  Run: its-magic --help${R}`);
+console.log("");
+
+const pkgRoot = path.resolve(__dirname, "..");
+const templateRoot = path.join(pkgRoot, "template");
+const bootstrapScript = path.join(pkgRoot, "scripts", "dev_environment_lib.py");
+
+function detectConsumerRepoRoot() {
+  let dir = process.cwd();
+  for (let depth = 0; depth <= 6; depth += 1) {
+    const scratchpad = path.join(dir, ".cursor", "scratchpad.md");
+    const versionSentinel = path.join(dir, "its_magic", ".its-magic-version");
+    if (fs.existsSync(scratchpad) || fs.existsSync(versionSentinel)) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+function resolvePythonCommand() {
+  if (process.platform === "win32") {
+    return "python";
+  }
+  return "python3";
+}
+
+function runDevEnvBootstrap() {
+  const repoRoot = detectConsumerRepoRoot();
+  if (!repoRoot) {
+    console.log("[DEV_ENV_BOOTSTRAP_SKIP] no consumer repository detected");
+    return;
+  }
+  if (!fs.existsSync(bootstrapScript)) {
+    console.log(
+      "[DEV_ENV_BOOTSTRAP_ERROR] bootstrap helper missing; copy template/.cursor/dev-environment.json.example manually"
+    );
+    return;
+  }
+  const py = resolvePythonCommand();
+  const res = spawnSync(
+    py,
+    [
+      bootstrapScript,
+      "--bootstrap",
+      "--target",
+      repoRoot,
+      "--source-root",
+      templateRoot,
+    ],
+    { encoding: "utf-8" }
+  );
+  if (res.stdout) {
+    process.stdout.write(res.stdout);
+  }
+  if (res.stderr) {
+    process.stderr.write(res.stderr);
+  }
+  if (res.status === 1) {
+    console.log(
+      "[DEV_ENV_BOOTSTRAP_ERROR] bootstrap failed; copy template/.cursor/dev-environment.json.example to .cursor/dev-environment.json"
+    );
+  }
+}
+
+runDevEnvBootstrap();