superpower_setup 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# superpower_setup
+
+CLI tool để cài đặt [obra/superpowers](https://github.com/obra/superpowers) vào project Google Antigravity.
+
+## Cài đặt & Sử dụng
+
+### Cài đặt superpowers vào project
+
+```bash
+npx superpower_setup init
+```
+
+### Cập nhật superpowers lên phiên bản mới nhất
+
+```bash
+npx superpower_setup update
+```
+
+### Options
+
+| Option | Mô tả | Mặc định |
+|--------|--------|----------|
+| `--target <path>` | Thư mục đích | Thư mục hiện tại |
+| `--branch <name>` | Branch của repo superpowers | `main` |
+| `--force` | Ghi đè files đã tồn tại | `false` |
+
+### Ví dụ
+
+```bash
+# Cài đặt vào project hiện tại
+npx superpower_setup init
+
+# Cài đặt vào thư mục khác
+npx superpower_setup init --target /path/to/project
+
+# Ghi đè files đã có
+npx superpower_setup init --force
+
+# Cài đặt từ branch khác
+npx superpower_setup init --branch develop
+```
+
+## Cấu trúc sau khi cài đặt
+
+```
+project-root/
+├── .agents/
+│   ├── skills/superpowers/       # 14 skills
+│   ├── agents/superpowers/       # Agent definitions
+│   ├── commands/superpowers/     # Custom commands
+│   └── hooks/superpowers/        # Session hooks
+├── GEMINI.md                     # Context file (tham chiếu skills)
+└── gemini-extension.json         # Extension config
+```
+
+## Skills đi kèm
+
+| Skill | Mô tả |
+|-------|--------|
+| **brainstorming** | Socratic design refinement |
+| **test-driven-development** | RED-GREEN-REFACTOR cycle |
+| **systematic-debugging** | 4-phase root cause process |
+| **writing-plans** | Detailed implementation plans |
+| **executing-plans** | Batch execution with checkpoints |
+| **subagent-driven-development** | Fast iteration with two-stage review |
+| **using-git-worktrees** | Parallel development branches |
+| **requesting-code-review** | Pre-review checklist |
+| **receiving-code-review** | Responding to feedback |
+| **finishing-a-development-branch** | Merge/PR decision workflow |
+| **verification-before-completion** | Ensure it's actually fixed |
+| **dispatching-parallel-agents** | Concurrent subagent workflows |
+| **writing-skills** | Create new skills |
+| **using-superpowers** | Introduction to the skills system |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { runInit } from "../src/index.js";
+import { logInfo, logError, LOG_COLORS } from "../src/utils.js";
+
+const PACKAGE_VERSION = "1.0.0";
+
+const HELP_TEXT = `
+${LOG_COLORS.cyan}superpower_setup${LOG_COLORS.reset} - Cài đặt obra/superpowers vào Google Antigravity project
+
+${LOG_COLORS.yellow}Usage:${LOG_COLORS.reset}
+  npx superpower_setup init [options]    Tải và cài đặt superpowers skills
+  npx superpower_setup update [options]  Cập nhật superpowers lên phiên bản mới nhất
+  npx superpower_setup --help            Hiển thị help
+  npx superpower_setup --version         Hiển thị version
+
+${LOG_COLORS.yellow}Options:${LOG_COLORS.reset}
+  --target <path>    Thư mục đích (mặc định: thư mục hiện tại)
+  --branch <name>    Branch của repo superpowers (mặc định: main)
+  --force            Ghi đè files đã tồn tại
+  --help, -h         Hiển thị help
+  --version, -v      Hiển thị version
+`;
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log(`superpower_setup v${PACKAGE_VERSION}`);
+    process.exit(0);
+  }
+
+  const command_args = args.slice(1);
+
+  let parsed_options;
+  try {
+    const { values } = parseArgs({
+      args: command_args,
+      options: {
+        target: { type: "string", default: process.cwd() },
+        branch: { type: "string", default: "main" },
+        force: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+      allowPositionals: true,
+    });
+    parsed_options = values;
+  } catch (err) {
+    logError(`Lỗi parse arguments: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (parsed_options.help) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+
+  switch (command) {
+    case "init":
+      runInit({
+        target_dir: parsed_options.target,
+        branch: parsed_options.branch,
+        is_force: parsed_options.force,
+        is_update: false,
+      });
+      break;
+
+    case "update":
+      runInit({
+        target_dir: parsed_options.target,
+        branch: parsed_options.branch,
+        is_force: true,
+        is_update: true,
+      });
+      break;
+
+    default:
+      logError(`Lệnh không hợp lệ: "${command}"`);
+      logInfo('Chạy "npx superpower_setup --help" để xem hướng dẫn.');
+      process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "superpower_setup",
+  "version": "1.0.0",
+  "description": "CLI tool to install obra/superpowers skills into Google Antigravity projects",
+  "type": "module",
+  "bin": {
+    "superpower_setup": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "superpowers",
+    "gemini",
+    "antigravity",
+    "ai",
+    "skills",
+    "coding-agent"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import {
+  logInfo,
+  logSuccess,
+  logWarning,
+  logError,
+  logStep,
+  ensureDir,
+  copyDirRecursive,
+  cleanUp,
+  checkGitInstalled,
+  cloneRepo,
+  LOG_COLORS,
+} from "./utils.js";
+
+const REPO_URL = "https://github.com/obra/superpowers.git";
+const TOTAL_STEPS = 5;
+
+// Các thư mục/files cần copy từ repo superpowers
+// Theo docs Antigravity: skills đặt trong .agents/skills/<skill-folder>/ (workspace-specific)
+// Ref: https://antigravity.google/docs/skills
+const COPY_MAP = [
+  { source: "skills", dest_sub: join(".agents", "skills", "superpowers"), type: "dir" },
+  { source: "agents", dest_sub: join(".agents", "agents", "superpowers"), type: "dir" },
+  { source: "commands", dest_sub: join(".agents", "commands", "superpowers"), type: "dir" },
+  { source: "hooks", dest_sub: join(".agents", "hooks", "superpowers"), type: "dir" },
+];
+
+/**
+ * Tạo nội dung GEMINI.md cho project đích
+ * References đến tất cả skills đã cài đặt
+ */
+function buildGeminiMdContent(skills_dir) {
+  const lines = [
+    "# Superpowers Skills",
+    "",
+    "<!-- Auto-generated by superpower_setup. Do not edit this section manually. -->",
+    "",
+  ];
+
+  // Tham chiếu đến skills theo cấu trúc Antigravity (.agents/skills/)
+  lines.push("@./.agents/skills/superpowers/using-superpowers/SKILL.md");
+  lines.push("@./.agents/skills/superpowers/using-superpowers/references/gemini-tools.md");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Cập nhật hoặc tạo GEMINI.md ở root project
+ */
+function setupGeminiMd(target_dir, is_force) {
+  const gemini_md_path = join(target_dir, "GEMINI.md");
+  const superpowers_content = buildGeminiMdContent(target_dir);
+  const MARKER_START = "<!-- SUPERPOWERS_START -->";
+  const MARKER_END = "<!-- SUPERPOWERS_END -->";
+  const wrapped_content = `${MARKER_START}\n${superpowers_content}\n${MARKER_END}`;
+
+  if (existsSync(gemini_md_path)) {
+    const existing_content = readFileSync(gemini_md_path, "utf-8");
+
+    // Kiểm tra xem đã có section superpowers chưa
+    if (existing_content.includes(MARKER_START)) {
+      if (!is_force) {
+        logWarning("GEMINI.md đã chứa cấu hình superpowers. Dùng --force để ghi đè.");
+        return false;
+      }
+      // Replace section cũ
+      const regex = new RegExp(
+        `${escapeRegex(MARKER_START)}[\\s\\S]*?${escapeRegex(MARKER_END)}`,
+        "g"
+      );
+      const updated_content = existing_content.replace(regex, wrapped_content);
+      writeFileSync(gemini_md_path, updated_content, "utf-8");
+      logSuccess("Đã cập nhật section superpowers trong GEMINI.md");
+    } else {
+      // Append vào cuối file
+      const updated_content = `${existing_content}\n\n${wrapped_content}\n`;
+      writeFileSync(gemini_md_path, updated_content, "utf-8");
+      logSuccess("Đã thêm cấu hình superpowers vào GEMINI.md");
+    }
+  } else {
+    writeFileSync(gemini_md_path, `${wrapped_content}\n`, "utf-8");
+    logSuccess("Đã tạo GEMINI.md với cấu hình superpowers");
+  }
+
+  return true;
+}
+
+/**
+ * Copy gemini-extension.json vào root project
+ */
+function setupGeminiExtension(repo_dir, target_dir, is_force) {
+  const source_path = join(repo_dir, "gemini-extension.json");
+  const dest_path = join(target_dir, "gemini-extension.json");
+
+  if (!existsSync(source_path)) {
+    logWarning("Không tìm thấy gemini-extension.json trong repo.");
+    return;
+  }
+
+  if (existsSync(dest_path) && !is_force) {
+    logWarning("gemini-extension.json đã tồn tại. Dùng --force để ghi đè.");
+    return;
+  }
+
+  // Đọc và chỉnh sửa contextFileName path
+  const extension_content = JSON.parse(readFileSync(source_path, "utf-8"));
+  extension_content.contextFileName = "GEMINI.md";
+
+  writeFileSync(dest_path, JSON.stringify(extension_content, null, 2) + "\n", "utf-8");
+  logSuccess("Đã copy gemini-extension.json");
+}
+
+/**
+ * Thêm .agents vào .gitignore nếu chưa có
+ */
+function setupGitignore(target_dir) {
+  const gitignore_path = join(target_dir, ".gitignore");
+  const entry = ".agents";
+
+  if (existsSync(gitignore_path)) {
+    const content = readFileSync(gitignore_path, "utf-8");
+    const lines = content.split(/\r?\n/).map((l) => l.trim());
+
+    if (lines.includes(entry) || lines.includes(entry + "/")) {
+      logInfo(".agents đã có trong .gitignore");
+      return;
+    }
+
+    // Append vào cuối file
+    const separator = content.endsWith("\n") ? "" : "\n";
+    writeFileSync(gitignore_path, `${content}${separator}\n# Superpowers skills\n${entry}\n`, "utf-8");
+    logSuccess("Đã thêm .agents vào .gitignore");
+  } else {
+    writeFileSync(gitignore_path, `# Superpowers skills\n${entry}\n`, "utf-8");
+    logSuccess("Đã tạo .gitignore với .agents");
+  }
+}
+
+/**
+ * Escape regex special characters
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Main init function
+ */
+export function runInit({ target_dir, branch, is_force, is_update }) {
+  const resolved_target = resolve(target_dir);
+  const action_name = is_update ? "Cập nhật" : "Cài đặt";
+  const temp_dir = join(tmpdir(), `superpower_setup_${randomBytes(6).toString("hex")}`);
+
+  console.log("");
+  console.log(
+    `${LOG_COLORS.bold}${LOG_COLORS.magenta}⚡ Superpower Setup${LOG_COLORS.reset} - ${action_name} superpowers skills`
+  );
+  console.log(`${LOG_COLORS.dim}   Target: ${resolved_target}${LOG_COLORS.reset}`);
+  console.log(`${LOG_COLORS.dim}   Branch: ${branch}${LOG_COLORS.reset}`);
+  console.log("");
+
+  // ── Step 1: Kiểm tra git ──────────────────────────────────────────
+  logStep(1, TOTAL_STEPS, "Kiểm tra prerequisites...");
+
+  if (!checkGitInstalled()) {
+    logError("Git chưa được cài đặt. Vui lòng cài đặt git trước.");
+    logInfo("Tải git tại: https://git-scm.com/downloads");
+    process.exit(1);
+  }
+
+  logSuccess("Git đã sẵn sàng");
+
+  // ── Step 2: Clone repo ────────────────────────────────────────────
+  logStep(2, TOTAL_STEPS, "Tải superpowers từ GitHub...");
+
+  try {
+    logInfo(`Cloning ${REPO_URL} (branch: ${branch})...`);
+    cloneRepo({ repo_url: REPO_URL, target_dir: temp_dir, branch });
+    logSuccess("Đã tải xong repo superpowers");
+  } catch (err) {
+    logError(`Không thể clone repo: ${err.message}`);
+    cleanUp(temp_dir);
+    process.exit(1);
+  }
+
+  // ── Step 3: Copy files ────────────────────────────────────────────
+  logStep(3, TOTAL_STEPS, "Copy skills, agents, commands, hooks...");
+
+  let total_files = 0;
+
+  for (const item of COPY_MAP) {
+    const source_path = join(temp_dir, item.source);
+    const dest_path = join(resolved_target, item.dest_sub);
+
+    if (!existsSync(source_path)) {
+      logWarning(`Không tìm thấy thư mục: ${item.source}`);
+      continue;
+    }
+
+    if (existsSync(dest_path) && !is_force && !is_update) {
+      logWarning(`${item.dest_sub} đã tồn tại. Dùng --force để ghi đè.`);
+      continue;
+    }
+
+    // Xóa thư mục cũ nếu update/force
+    if (existsSync(dest_path) && (is_force || is_update)) {
+      cleanUp(dest_path);
+    }
+
+    const count = copyDirRecursive(source_path, dest_path);
+    total_files += count;
+    logSuccess(`${item.source}/ → ${item.dest_sub} (${count} files)`);
+  }
+
+  logInfo(`Tổng cộng: ${total_files} files đã được copy`);
+
+  // ── Step 4: Setup GEMINI.md, gemini-extension.json, .gitignore ────
+  logStep(4, TOTAL_STEPS, "Cấu hình GEMINI.md, gemini-extension.json, .gitignore...");
+
+  setupGeminiMd(resolved_target, is_force || is_update);
+  setupGeminiExtension(temp_dir, resolved_target, is_force || is_update);
+  setupGitignore(resolved_target);
+
+  // ── Step 5: Cleanup ───────────────────────────────────────────────
+  logStep(5, TOTAL_STEPS, "Dọn dẹp...");
+
+  cleanUp(temp_dir);
+  logSuccess("Đã xóa temp files");
+
+  // ── Done ──────────────────────────────────────────────────────────
+  console.log("");
+  console.log(
+    `${LOG_COLORS.green}${LOG_COLORS.bold}🎉 ${action_name} superpowers thành công!${LOG_COLORS.reset}`
+  );
+  console.log("");
+  console.log(`${LOG_COLORS.cyan}Các skills đã được cài đặt:${LOG_COLORS.reset}`);
+  console.log("  • brainstorming           - Socratic design refinement");
+  console.log("  • dispatching-parallel-agents - Concurrent subagent workflows");
+  console.log("  • executing-plans         - Batch execution with checkpoints");
+  console.log("  • finishing-a-development-branch - Merge/PR decision workflow");
+  console.log("  • receiving-code-review   - Responding to feedback");
+  console.log("  • requesting-code-review  - Pre-review checklist");
+  console.log("  • subagent-driven-development - Fast iteration with two-stage review");
+  console.log("  • systematic-debugging    - 4-phase root cause process");
+  console.log("  • test-driven-development - RED-GREEN-REFACTOR cycle");
+  console.log("  • using-git-worktrees     - Parallel development branches");
+  console.log("  • using-superpowers       - Introduction to the skills system");
+  console.log("  • verification-before-completion - Ensure it's actually fixed");
+  console.log("  • writing-plans           - Detailed implementation plans");
+  console.log("  • writing-skills          - Create new skills");
+  console.log("");
+  console.log(
+    `${LOG_COLORS.dim}Chạy "npx superpower_setup update" để cập nhật lên phiên bản mới nhất.${LOG_COLORS.reset}`
+  );
+  console.log("");
+}

package/src/utils.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+// ─── Console colors ─────────────────────────────────────────────────
+export const LOG_COLORS = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+};
+
+// ─── Logging helpers ────────────────────────────────────────────────
+export function logInfo(message) {
+  console.log(`${LOG_COLORS.blue}ℹ${LOG_COLORS.reset} ${message}`);
+}
+
+export function logSuccess(message) {
+  console.log(`${LOG_COLORS.green}✔${LOG_COLORS.reset} ${message}`);
+}
+
+export function logWarning(message) {
+  console.log(`${LOG_COLORS.yellow}⚠${LOG_COLORS.reset} ${message}`);
+}
+
+export function logError(message) {
+  console.error(`${LOG_COLORS.red}✖${LOG_COLORS.reset} ${message}`);
+}
+
+export function logStep(step_number, total, message) {
+  console.log(
+    `\n${LOG_COLORS.cyan}[${step_number}/${total}]${LOG_COLORS.reset} ${LOG_COLORS.bold}${message}${LOG_COLORS.reset}`
+  );
+}
+
+// ─── File system helpers ────────────────────────────────────────────
+export function ensureDir(dir_path) {
+  if (!existsSync(dir_path)) {
+    mkdirSync(dir_path, { recursive: true });
+  }
+}
+
+export function copyDirRecursive(source, destination) {
+  ensureDir(destination);
+
+  const entries = readdirSync(source);
+  let copied_count = 0;
+
+  for (const entry of entries) {
+    const source_path = join(source, entry);
+    const dest_path = join(destination, entry);
+    const stat = statSync(source_path);
+
+    if (stat.isDirectory()) {
+      copied_count += copyDirRecursive(source_path, dest_path);
+    } else {
+      copyFileSync(source_path, dest_path);
+      copied_count++;
+    }
+  }
+
+  return copied_count;
+}
+
+export function cleanUp(temp_dir) {
+  if (existsSync(temp_dir)) {
+    rmSync(temp_dir, { recursive: true, force: true });
+  }
+}
+
+// ─── Git helpers ────────────────────────────────────────────────────
+export function checkGitInstalled() {
+  try {
+    execSync("git --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function cloneRepo({ repo_url, target_dir, branch }) {
+  execSync(
+    `git clone --depth 1 --branch ${branch} --single-branch "${repo_url}" "${target_dir}"`,
+    { stdio: "pipe" }
+  );
+}