sdd-jc-methodology 0.2.0

package/bin/sdd-jc.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const SOURCE_CLAUDE = path.join(PACKAGE_ROOT, ".claude");
+const SOURCE_COMMANDS = path.join(SOURCE_CLAUDE, "commands");
+const SOURCE_SKILLS = path.join(SOURCE_CLAUDE, "skills");
+const SOURCE_SCRIPTS = path.join(PACKAGE_ROOT, "scripts");
+const SOURCE_MCP_EXAMPLE = path.join(PACKAGE_ROOT, ".mcp.json.example");
+
+const TOOL_DEFAULTS = {
+  claude: path.join(os.homedir(), ".claude"),
+  opencode: path.join(os.homedir(), ".config", "opencode"),
+};
+
+function printHelp() {
+  console.log(`SDD JC Methodology CLI
+
+Usage:
+  sdd-jc <command> [options]
+
+Commands:
+  install   Install commands, skills, and helper resources
+  update    Reinstall commands, skills, and helper resources
+  doctor    Check whether expected files are installed
+  list      List packaged commands, skills, and helper resources
+  help      Show this help
+
+Options:
+  --tool <name>        Install target: claude, opencode, or both. Default: claude
+  --target <path>      Target config directory for selected single tool
+  --claude-target      Claude config directory. Default: ~/.claude
+  --opencode-target    OpenCode config directory. Default: ~/.config/opencode
+  --force              Overwrite existing files
+  --dry-run            Show what would happen without writing files
+  --commands-only      Install or check only commands
+  --skills-only        Install or check only skills
+
+Examples:
+  sdd-jc install
+  sdd-jc install --tool opencode
+  sdd-jc install --tool both --dry-run
+  sdd-jc install --tool claude --target ./.claude
+  sdd-jc update --tool both --force
+  sdd-jc doctor --tool opencode
+  sdd-jc list
+`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    command: argv[2] || "help",
+    tool: "claude",
+    target: undefined,
+    claudeTarget: TOOL_DEFAULTS.claude,
+    opencodeTarget: TOOL_DEFAULTS.opencode,
+    force: false,
+    dryRun: false,
+    commandsOnly: false,
+    skillsOnly: false,
+  };
+
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "--tool") {
+      const value = argv[i + 1];
+      if (!value) fail("Missing value for --tool");
+      if (!["claude", "opencode", "both"].includes(value)) {
+        fail("--tool must be one of: claude, opencode, both");
+      }
+      args.tool = value;
+      i += 1;
+    } else if (arg === "--target") {
+      const value = argv[i + 1];
+      if (!value) fail("Missing value for --target");
+      args.target = resolveUserPath(value);
+      i += 1;
+    } else if (arg === "--claude-target") {
+      const value = argv[i + 1];
+      if (!value) fail("Missing value for --claude-target");
+      args.claudeTarget = resolveUserPath(value);
+      i += 1;
+    } else if (arg === "--opencode-target") {
+      const value = argv[i + 1];
+      if (!value) fail("Missing value for --opencode-target");
+      args.opencodeTarget = resolveUserPath(value);
+      i += 1;
+    } else if (arg === "--force") {
+      args.force = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--commands-only") {
+      args.commandsOnly = true;
+    } else if (arg === "--skills-only") {
+      args.skillsOnly = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.command = "help";
+    } else {
+      fail(`Unknown option: ${arg}`);
+    }
+  }
+
+  if (args.commandsOnly && args.skillsOnly) {
+    fail("Use only one of --commands-only or --skills-only");
+  }
+
+  if (args.target && args.tool === "both") {
+    fail("--target can only be used with --tool claude or --tool opencode. Use --claude-target and --opencode-target with --tool both.");
+  }
+
+  if (args.target && args.tool === "claude") args.claudeTarget = args.target;
+  if (args.target && args.tool === "opencode") args.opencodeTarget = args.target;
+
+  return args;
+}
+
+function resolveUserPath(input) {
+  return path.resolve(input.replace(/^~(?=$|\/|\\)/, os.homedir()));
+}
+
+function fail(message) {
+  console.error(`ERROR: ${message}`);
+  process.exit(1);
+}
+
+function ensureDirectory(dir, dryRun) {
+  if (fs.existsSync(dir)) return;
+  if (dryRun) {
+    console.log(`create directory ${dir}`);
+    return;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function listEntries(dir, filter) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(filter)
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function listCommands() {
+  return listEntries(SOURCE_COMMANDS, (entry) => entry.isFile() && entry.name.endsWith(".md"));
+}
+
+function listSkills() {
+  return listEntries(SOURCE_SKILLS, (entry) => entry.isDirectory());
+}
+
+function selectedTools(args) {
+  if (args.tool === "both") return ["claude", "opencode"];
+  return [args.tool];
+}
+
+function shouldInclude(type, args) {
+  if (args.commandsOnly) return type === "commands";
+  if (args.skillsOnly) return type === "skills";
+  return true;
+}
+
+function copySingleFile(sourcePath, targetPath, args) {
+  ensureDirectory(path.dirname(targetPath), args.dryRun);
+
+  if (fs.existsSync(targetPath) && !args.force) {
+    console.log(`skip existing ${targetPath}`);
+    return { installed: 0, skipped: 1 };
+  }
+
+  const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+  console.log(`${args.dryRun ? "would " : ""}${action} ${targetPath}`);
+
+  if (!args.dryRun) {
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  return { installed: 1, skipped: 0 };
+}
+
+function copyDirectoryContents(sourceDir, targetDir, args) {
+  ensureDirectory(targetDir, args.dryRun);
+
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  let installed = 0;
+  let skipped = 0;
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (fs.existsSync(targetPath) && !args.force) {
+      console.log(`skip existing ${targetPath}`);
+      skipped += 1;
+      continue;
+    }
+
+    const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+    console.log(`${args.dryRun ? "would " : ""}${action} ${targetPath}`);
+
+    if (!args.dryRun) {
+      fs.cpSync(sourcePath, targetPath, {
+        recursive: true,
+        force: true,
+        errorOnExist: false,
+      });
+    }
+    installed += 1;
+  }
+
+  return { installed, skipped };
+}
+
+function installTool(tool, args) {
+  const targetRoot = tool === "claude" ? args.claudeTarget : args.opencodeTarget;
+  const targetCommands = path.join(targetRoot, "commands");
+  const targetSkills = path.join(targetRoot, "skills");
+  const targetResources = path.join(targetRoot, "sdd-jc");
+  let installed = 0;
+  let skipped = 0;
+
+  console.log(`\n${tool} target: ${targetRoot}`);
+
+  if (shouldInclude("commands", args)) {
+    const result = copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args);
+    installed += result.installed;
+    skipped += result.skipped;
+  }
+
+  if (shouldInclude("skills", args)) {
+    const result = copyDirectoryContents(SOURCE_SKILLS, targetSkills, args);
+    installed += result.installed;
+    skipped += result.skipped;
+  }
+
+  if (shouldInclude("resources", args)) {
+    const scriptsResult = copyDirectoryContents(
+      SOURCE_SCRIPTS,
+      path.join(targetResources, "scripts"),
+      args
+    );
+    installed += scriptsResult.installed;
+    skipped += scriptsResult.skipped;
+
+    const mcpResult = copySingleFile(
+      SOURCE_MCP_EXAMPLE,
+      path.join(targetResources, ".mcp.json.example"),
+      args
+    );
+    installed += mcpResult.installed;
+    skipped += mcpResult.skipped;
+  }
+
+  return { installed, skipped };
+}
+
+function runInstall(args) {
+  let installed = 0;
+  let skipped = 0;
+
+  for (const tool of selectedTools(args)) {
+    const result = installTool(tool, args);
+    installed += result.installed;
+    skipped += result.skipped;
+  }
+
+  console.log(`\nDone. Installed: ${installed} | Skipped: ${skipped}`);
+  if (skipped > 0 && !args.force) {
+    console.log("Use --force to overwrite existing files.");
+  }
+
+  if (selectedTools(args).includes("opencode") && !args.dryRun) {
+    console.log("Restart OpenCode for installed commands and skills to be loaded.");
+  }
+}
+
+function runList() {
+  const commands = listCommands();
+  const skills = listSkills();
+  const scripts = listEntries(SOURCE_SCRIPTS, (entry) => entry.isFile());
+
+  console.log("Commands:");
+  commands.forEach((name) => console.log(`  ${name.replace(/\.md$/, "")}`));
+
+  console.log("\nSkills:");
+  skills.forEach((name) => console.log(`  ${name}`));
+
+  console.log("\nResources:");
+  scripts.forEach((name) => console.log(`  scripts/${name}`));
+  console.log("  .mcp.json.example");
+}
+
+function hasInstalledCommand(targetRoot, name) {
+  return fs.existsSync(path.join(targetRoot, "commands", name));
+}
+
+function hasInstalledSkill(targetRoot, name) {
+  return fs.existsSync(path.join(targetRoot, "skills", name, "SKILL.md"));
+}
+
+function doctorTool(tool, args) {
+  const targetRoot = tool === "claude" ? args.claudeTarget : args.opencodeTarget;
+  const targetResources = path.join(targetRoot, "sdd-jc");
+  let missing = 0;
+
+  console.log(`\nChecking ${tool}: ${targetRoot}`);
+
+  if (shouldInclude("commands", args)) {
+    console.log("\nCommands:");
+    for (const command of listCommands()) {
+      const ok = hasInstalledCommand(targetRoot, command);
+      console.log(`  ${ok ? "OK" : "MISSING"} ${command}`);
+      if (!ok) missing += 1;
+    }
+  }
+
+  if (shouldInclude("skills", args)) {
+    console.log("\nSkills:");
+    for (const skill of listSkills()) {
+      const ok = hasInstalledSkill(targetRoot, skill);
+      console.log(`  ${ok ? "OK" : "MISSING"} ${skill}`);
+      if (!ok) missing += 1;
+    }
+  }
+
+  if (shouldInclude("resources", args)) {
+    console.log("\nResources:");
+    const resourceChecks = [
+      path.join(targetResources, "scripts", "gsc_verify.py"),
+      path.join(targetResources, ".mcp.json.example"),
+    ];
+
+    for (const resourcePath of resourceChecks) {
+      const ok = fs.existsSync(resourcePath);
+      console.log(`  ${ok ? "OK" : "MISSING"} ${resourcePath}`);
+      if (!ok) missing += 1;
+    }
+  }
+
+  return missing;
+}
+
+function runDoctor(args) {
+  let missing = 0;
+  for (const tool of selectedTools(args)) {
+    missing += doctorTool(tool, args);
+  }
+
+  console.log(`\nDone. Missing: ${missing}`);
+  if (missing > 0) process.exitCode = 1;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  switch (args.command) {
+    case "install":
+    case "update":
+      runInstall(args);
+      break;
+    case "doctor":
+      runDoctor(args);
+      break;
+    case "list":
+      runList();
+      break;
+    case "help":
+      printHelp();
+      break;
+    default:
+      fail(`Unknown command: ${args.command}`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "sdd-jc-methodology",
+  "version": "0.2.0",
+  "description": "Portable SDD JC methodology commands and skills for AI-assisted development.",
+  "homepage": "https://github.com/JuankCadavid/sdd-jc-methodology#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JuankCadavid/sdd-jc-methodology.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JuankCadavid/sdd-jc-methodology/issues"
+  },
+  "bin": {
+    "sdd-jc": "./bin/sdd-jc.js"
+  },
+  "files": [
+    ".claude/commands",
+    ".claude/skills",
+    ".mcp.json.example",
+    "assets",
+    "bin",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "scripts"
+  ],
+  "scripts": {
+    "pack:dry-run": "npm pack --dry-run",
+    "verify:cli": "node bin/sdd-jc.js list"
+  },
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "claude",
+    "opencode",
+    "ai-coding",
+    "methodology"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}

package/scripts/gsc_verify.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Verify a Google service account as an owner on Google Search Console
+Domain properties via DNS TXT records.
+
+The `gsc` MCP (@mikusnuz/gsc-mcp) does NOT expose Site Verification
+endpoints — only Search Console. This helper covers the verification
+half: token generation + verify call.
+
+After verification succeeds, use the `gsc` MCP `sites_add` tool to add
+the property to Search Console for the service account.
+
+Setup:
+  pip install google-auth google-api-python-client
+
+Usage:
+  GSC_KEY_PATH=/abs/path/to/service-account.json \
+    python3 gsc_verify.py get <domain> [<domain> ...]
+
+  GSC_KEY_PATH=/abs/path/to/service-account.json \
+    python3 gsc_verify.py verify <domain> [<domain> ...]
+
+Or pass the key path explicitly:
+  python3 gsc_verify.py --key /abs/path/to/key.json get example.com
+
+Workflow:
+  1. Run with `get` to obtain a DNS TXT verification token per domain.
+  2. Add the TXT record to each domain's DNS (host: @, value: the token).
+  3. Wait for DNS propagation (a few minutes to an hour).
+  4. Run with `verify` to trigger the verification on Google's side.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from google.oauth2 import service_account
+    from googleapiclient.discovery import build
+    from googleapiclient.errors import HttpError
+except ImportError:
+    print("ERROR: missing dependencies. Install with:", file=sys.stderr)
+    print("  pip install google-auth google-api-python-client", file=sys.stderr)
+    sys.exit(1)
+
+
+SCOPES = ["https://www.googleapis.com/auth/siteverification"]
+
+
+def make_client(key_path: str):
+    if not Path(key_path).exists():
+        print(f"ERROR: key file not found at: {key_path}", file=sys.stderr)
+        sys.exit(1)
+    creds = service_account.Credentials.from_service_account_file(
+        key_path, scopes=SCOPES
+    )
+    return build("siteVerification", "v1", credentials=creds, cache_discovery=False)
+
+
+def get_token(sv, domain: str) -> str:
+    body = {
+        "site": {"type": "INET_DOMAIN", "identifier": domain},
+        "verificationMethod": "DNS_TXT",
+    }
+    return sv.webResource().getToken(body=body).execute()["token"]
+
+
+def check_dns(domain: str, token: str):
+    """Best-effort check that the TXT record is visible via dig."""
+    try:
+        out = subprocess.check_output(
+            ["dig", "+short", "TXT", domain], stderr=subprocess.DEVNULL, text=True
+        )
+        return token in out
+    except Exception:
+        return None
+
+
+def verify_domain(sv, domain: str):
+    body = {"site": {"type": "INET_DOMAIN", "identifier": domain}}
+    return sv.webResource().insert(verificationMethod="DNS_TXT", body=body).execute()
+
+
+def cmd_get(sv, domains):
+    print("\n=== DNS TXT records to add ===\n")
+    print("For each domain, log into your DNS provider and add a TXT record")
+    print("at the root (host = '@' or blank) with the value shown.\n")
+    for d in domains:
+        try:
+            token = get_token(sv, d)
+            print(f"--- {d} ---")
+            print(f"  Type:  TXT")
+            print(f"  Host:  @  (root of {d})")
+            print(f"  Value: {token}\n")
+        except HttpError as e:
+            print(f"--- {d} ---")
+            print(f"  ERROR getting token: {e}\n")
+
+
+def cmd_verify(sv, domains):
+    print("\n=== Verifying domains ===\n")
+    successes, failures = [], []
+    for d in domains:
+        try:
+            token = get_token(sv, d)
+        except HttpError as e:
+            print(f"[{d}] ERROR fetching token: {e}")
+            failures.append(d)
+            continue
+
+        dns_ok = check_dns(d, token)
+        if dns_ok is False:
+            print(f"[{d}] WARNING: TXT record not visible yet via dig. Trying anyway...")
+        elif dns_ok is True:
+            print(f"[{d}] TXT record visible in DNS")
+
+        try:
+            verify_domain(sv, d)
+            print(f"[{d}] VERIFIED — service account is now an owner.")
+            successes.append(d)
+        except HttpError as e:
+            print(f"[{d}] FAILED to verify: {e}")
+            failures.append(d)
+        print()
+
+    print(f"\nDone. Success: {len(successes)} | Failed: {len(failures)}")
+    if failures:
+        print("Failed domains:", ", ".join(failures))
+        print("Tip: DNS can take a few minutes to propagate. Try again later.")
+    return 0 if not failures else 1
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Verify a service account as owner on GSC domain properties."
+    )
+    parser.add_argument(
+        "--key",
+        default=os.environ.get("GSC_KEY_PATH"),
+        help="Path to the Google service account JSON key. "
+        "Defaults to $GSC_KEY_PATH.",
+    )
+    parser.add_argument("action", choices=["get", "verify"])
+    parser.add_argument("domains", nargs="+", help="One or more apex domains.")
+    args = parser.parse_args()
+
+    if not args.key:
+        parser.error(
+            "missing service account key: pass --key /abs/path.json or set $GSC_KEY_PATH"
+        )
+
+    sv = make_client(args.key)
+    if args.action == "get":
+        cmd_get(sv, args.domains)
+        return 0
+    return cmd_verify(sv, args.domains)
+
+
+if __name__ == "__main__":
+    sys.exit(main())