opensddrag 0.1.0

package/bin/opensddrag.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { readFileSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
+
+program
+  .name("opensddrag")
+  .description("Connect any project to the OpenSddRag SDD+Harness MCP server")
+  .version(pkg.version);
+
+const { initCommand } = await import("../src/commands/init.js");
+const { statusCommand } = await import("../src/commands/status.js");
+
+program.addCommand(initCommand);
+program.addCommand(statusCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "opensddrag",
+  "version": "0.1.0",
+  "description": "CLI client to connect any project to the OpenSddRag SDD+Harness MCP server",
+  "keywords": [
+    "sdd",
+    "mcp",
+    "harness",
+    "spec-driven",
+    "ai"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "opensddrag": "./bin/opensddrag.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,50 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const CLIENT_INFO = { name: "opensddrag-cli", version: "0.1.0" };
+
+async function withMcp(serverUrl, fn, apiKey) {
+  const client = new Client(CLIENT_INFO);
+  const transportOpts = apiKey
+    ? { requestInit: { headers: { Authorization: `Bearer ${apiKey}` } } }
+    : {};
+  const transport = new StreamableHTTPClientTransport(
+    new URL(`${serverUrl.replace(/\/+$/, "")}/mcp`),
+    transportOpts,
+  );
+  await client.connect(transport);
+  try {
+    return await fn(client);
+  } finally {
+    await client.close();
+  }
+}
+
+function parseToolResult(result) {
+  const text = result.content?.[0]?.text ?? "";
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(text || "Unexpected response from server");
+  }
+}
+
+export async function checkHealth(serverUrl, apiKey) {
+  await withMcp(serverUrl, async () => {}, apiKey);
+}
+
+export async function createProject(serverUrl, { slug, name, description }, apiKey) {
+  return withMcp(serverUrl, async (client) => {
+    const args = { slug, name };
+    if (description) args.description = description;
+    const result = await client.callTool({ name: "create_project", arguments: args });
+    return parseToolResult(result);
+  }, apiKey);
+}
+
+export async function listProjects(serverUrl, apiKey) {
+  return withMcp(serverUrl, async (client) => {
+    const result = await client.callTool({ name: "list_projects", arguments: {} });
+    return parseToolResult(result);
+  }, apiKey);
+}

package/src/commands/init.js

@@ -0,0 +1,244 @@
+import { Command } from "commander";
+import { input, confirm, checkbox, password } from "@inquirer/prompts";
+import chalk from "chalk";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, basename } from "path";
+
+import { checkHealth, createProject } from "../api.js";
+import { renderClaudeMdBlock, renderClaudeMdStandalone } from "../templates/claude-md.js";
+import { getCommands } from "../templates/commands/index.js";
+import { getOpenCodeCommands } from "../templates/commands/opencode.js";
+import { getSkills } from "../templates/skills/index.js";
+
+// ── Config writers ─────────────────────────────────────────────────────────────
+
+function writeClaudeCode(cwd, serverUrl, apiKey) {
+  const mcpPath = join(cwd, ".mcp.json");
+  let config = {};
+  if (existsSync(mcpPath)) {
+    try { config = JSON.parse(readFileSync(mcpPath, "utf8")); } catch {}
+  }
+  config.mcpServers = config.mcpServers || {};
+  const entry = { type: "http", url: `${serverUrl}/mcp` };
+  if (apiKey) {
+    entry.headers = { Authorization: `Bearer ${apiKey}` };
+  }
+  config.mcpServers.opensddrag = entry;
+  writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+  return ".mcp.json";
+}
+
+function writeOpenCode(cwd, serverUrl, _apiKey) {
+  const configPath = join(cwd, "opencode.json");
+  let config = {};
+  if (existsSync(configPath)) {
+    try { config = JSON.parse(readFileSync(configPath, "utf8")); } catch {}
+  }
+  config.mcp = config.mcp || {};
+  config.mcp.opensddrag = {
+    type: "remote",
+    url: `${serverUrl}/mcp`,
+    enabled: true,
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return "opencode.json";
+}
+
+const TOOL_WRITERS = {
+  "Claude Code": writeClaudeCode,
+  "OpenCode":    writeOpenCode,
+};
+
+// ── Command ────────────────────────────────────────────────────────────────────
+
+export const initCommand = new Command("init")
+  .description("Connect the current project to an OpenSddRag MCP server")
+  .option("--project <slug>", "Project slug (default: current directory name)")
+  .option("--name <name>", "Project display name")
+  .option("--server <url>", "OpenSddRag server URL", "http://localhost:8000")
+  .option("--api-key <key>", "API key for authenticated servers")
+  .option("--tools <list>", "Comma-separated tools to configure: claude,opencode (default: ask)")
+  .option("--yes", "Skip confirmation prompts")
+  .action(async (opts) => {
+    const cwd = process.cwd();
+
+    console.log(chalk.bold("\n  OpenSddRag — Project Init\n"));
+
+    // ── Inputs ────────────────────────────────────────────────────────────────
+    const serverUrl = opts.server ||
+      await input({ message: "OpenSddRag server URL:", default: "http://localhost:8000" });
+
+    // Prompt for API key when connecting to a remote server
+    const isRemote = !serverUrl.includes("localhost") && !serverUrl.includes("127.0.0.1");
+    let apiKey = opts.apiKey || null;
+    if (!apiKey && isRemote && !opts.yes) {
+      apiKey = await password({
+        message: "API key (leave blank to skip — server must have AUTH_ENABLED=false):",
+        mask: "*",
+      }) || null;
+    }
+
+    const slug = opts.project ||
+      await input({
+        message: "Project slug:",
+        default: basename(cwd).toLowerCase().replace(/[^a-z0-9-]/g, "-"),
+      });
+
+    const name = opts.name ||
+      await input({
+        message: "Project display name:",
+        default: slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+      });
+
+    // ── Which tools to configure ──────────────────────────────────────────────
+    let selectedTools;
+    if (opts.tools) {
+      const map = { claude: "Claude Code", opencode: "OpenCode" };
+      selectedTools = opts.tools.split(",").map((t) => map[t.trim().toLowerCase()]).filter(Boolean);
+    } else {
+      selectedTools = await checkbox({
+        message: "Which AI tools to configure?",
+        choices: [
+          { name: "Claude Code  (.claude/settings.json)", value: "Claude Code", checked: true },
+          { name: "OpenCode     (opencode.json)",          value: "OpenCode",    checked: false },
+        ],
+      });
+    }
+
+    if (selectedTools.length === 0) {
+      console.log(chalk.yellow("\n  No tools selected. Exiting.\n"));
+      process.exit(0);
+    }
+
+    // ── Preview ───────────────────────────────────────────────────────────────
+    console.log("\n" + chalk.dim("  Will create/update:"));
+    if (selectedTools.includes("Claude Code")) {
+      console.log(chalk.dim("    .mcp.json                                    — MCP server (type: http)"));
+    }
+    console.log(chalk.dim("    .claude/skills/opensddrag-*/SKILL.md         — individual skill per command"));
+    console.log(chalk.dim("    .agents/skills/opensddrag-*/SKILL.md         — individual skill per command"));
+    if (selectedTools.includes("OpenCode")) {
+      console.log(chalk.dim("    opencode.json               — MCP server"));
+      console.log(chalk.dim("    .opencode/skills/opensddrag-*/SKILL.md     — OpenCode-native skills"));
+      console.log(chalk.dim("    .opencode/commands/opsr/    — slash commands (/opsr:propose, /opsr:apply...)"));
+    }
+    console.log(chalk.dim("    .claude/commands/opsr/        — slash commands (/opsr:propose, /opsr:apply...)"));
+    console.log(chalk.dim("    CLAUDE.md                    — OpenSddRag section"));
+    console.log(chalk.dim(`    Remote: register '${slug}' in central database\n`));
+
+    if (!opts.yes) {
+      const ok = await confirm({ message: "Proceed?", default: true });
+      if (!ok) process.exit(0);
+    }
+
+    // ── 1. Server health ──────────────────────────────────────────────────────
+    process.stdout.write(chalk.bold("  1/4 ") + "Connecting to server... ");
+    try {
+      await checkHealth(serverUrl, apiKey);
+      console.log(chalk.green("✓"));
+    } catch {
+      console.log(chalk.red("✗"));
+      console.error(chalk.red(`\n  Cannot reach ${serverUrl}`));
+      console.error(chalk.dim("  Make sure the OpenSddRag server is running:"));
+      console.error(chalk.dim("    docker compose up -d"));
+      process.exit(1);
+    }
+
+    // ── 2. Register project ───────────────────────────────────────────────────
+    process.stdout.write(chalk.bold("  2/4 ") + "Registering project in database... ");
+    let project;
+    try {
+      project = await createProject(serverUrl, { slug, name }, apiKey);
+      console.log(project.already_existed
+        ? chalk.yellow("✓ (already existed)")
+        : chalk.green(`✓ (id: ${project.id})`));
+    } catch (err) {
+      console.log(chalk.red("✗"));
+      console.error(chalk.red(`\n  ${err.message}`));
+      process.exit(1);
+    }
+
+    // ── 3. Configure AI tools ─────────────────────────────────────────────────
+    process.stdout.write(chalk.bold("  3/4 ") + "Configuring AI tools... ");
+    const configured = [];
+    for (const tool of selectedTools) {
+      const file = TOOL_WRITERS[tool](cwd, serverUrl, apiKey);
+      configured.push(`${tool} → ${file}`);
+    }
+    // Individual skill files per command
+    const skills = getSkills(slug, serverUrl);
+    const skillRoots = [
+      join(cwd, ".claude", "skills"),
+      join(cwd, ".agents", "skills"),
+    ];
+    for (const skill of skills) {
+      for (const root of skillRoots) {
+        const skillDir = join(root, skill.name);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+      }
+      configured.push(`skill → .claude/skills/${skill.name}/SKILL.md`);
+    }
+
+    // Install OpenCode-native skills if OpenCode is selected
+    if (selectedTools.includes("OpenCode")) {
+      const opencodeSkillsRoot = join(cwd, ".opencode", "skills");
+      for (const skill of skills) {
+        const skillDir = join(opencodeSkillsRoot, skill.name);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+        configured.push(`skill → .opencode/skills/${skill.name}/SKILL.md`);
+      }
+    }
+    console.log(chalk.green("✓"));
+    for (const c of configured) console.log(chalk.dim(`    ${c}`));
+
+    // ── 4. Slash commands (.claude/commands/opsr/) ───────────────────────────
+    process.stdout.write(chalk.bold("  4/5 ") + "Writing slash commands... ");
+    const commands = getCommands(slug, serverUrl);
+    for (const cmd of commands) {
+      const cmdDir = join(cwd, ".claude", "commands", cmd.folder);
+      mkdirSync(cmdDir, { recursive: true });
+      writeFileSync(join(cmdDir, `${cmd.name}.md`), cmd.content);
+    }
+    console.log(chalk.green(`✓ (${commands.length} commands)`));
+    for (const cmd of commands) {
+      console.log(chalk.dim(`    /${cmd.folder}:${cmd.name}`));
+    }
+
+    // Install OpenCode-native commands if OpenCode is selected
+    if (selectedTools.includes("OpenCode")) {
+      const opencodeCommands = getOpenCodeCommands(slug, serverUrl);
+      for (const cmd of opencodeCommands) {
+        const cmdDir = join(cwd, ".opencode", "commands", cmd.folder);
+        mkdirSync(cmdDir, { recursive: true });
+        writeFileSync(join(cmdDir, `${cmd.name}.md`), cmd.content);
+        configured.push(`command → .opencode/commands/${cmd.folder}/${cmd.name}.md`);
+      }
+    }
+
+    // ── 5. CLAUDE.md ──────────────────────────────────────────────────────────
+    process.stdout.write(chalk.bold("  5/5 ") + "Updating CLAUDE.md... ");
+    const claudeMdPath = join(cwd, "CLAUDE.md");
+    if (existsSync(claudeMdPath)) {
+      const content = readFileSync(claudeMdPath, "utf8");
+      if (content.includes("OpenSddRag")) {
+        console.log(chalk.yellow("✓ (already has OpenSddRag section)"));
+      } else {
+        writeFileSync(claudeMdPath, content.trimEnd() + "\n" + renderClaudeMdBlock({ slug, serverUrl }) + "\n");
+        console.log(chalk.green("✓ (appended)"));
+      }
+    } else {
+      writeFileSync(claudeMdPath, renderClaudeMdStandalone({ projectName: name, slug, serverUrl }));
+      console.log(chalk.green("✓ (created)"));
+    }
+
+    // opensddrag.yaml (local project marker)
+    if (!existsSync(join(cwd, "opensddrag.yaml"))) {
+      writeFileSync(join(cwd, "opensddrag.yaml"), `project: ${slug}\nserver: ${serverUrl}\n`);
+    }
+
+    // ── Done ──────────────────────────────────────────────────────────────────
+    console.log(chalk.bold.green("\n  ✓ Project connected to OpenSddRag!\n"));
+    console.log("  Open the project in your AI tool — the MCP server is configured.\n");
+  });

package/src/commands/status.js

@@ -0,0 +1,130 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+import { checkHealth, listProjects } from "../api.js";
+
+export const statusCommand = new Command("status")
+  .description("Check OpenSddRag connection status for the current project")
+  .action(async () => {
+    const cwd = process.cwd();
+
+    console.log(chalk.bold("\n  OpenSddRag — Status\n"));
+
+    let serverUrl = "http://localhost:8000";
+    let slug = null;
+
+    // ── Local config ──────────────────────────────────────────────────────────
+    const yamlPath = join(cwd, "opensddrag.yaml");
+    if (existsSync(yamlPath)) {
+      const yaml = readFileSync(yamlPath, "utf8");
+      const slugMatch = yaml.match(/^project:\s*(.+)$/m);
+      const serverMatch = yaml.match(/^server:\s*(.+)$/m);
+      if (slugMatch) slug = slugMatch[1].trim();
+      if (serverMatch) serverUrl = serverMatch[1].trim();
+      console.log(chalk.green("  ✓") + ` opensddrag.yaml  →  project: ${chalk.cyan(slug)}`);
+    } else {
+      console.log(chalk.red("  ✗") + " opensddrag.yaml not found — run: " + chalk.dim("opensddrag init"));
+    }
+
+    // ── Skills ────────────────────────────────────────────────────────────────
+    console.log(chalk.dim("\n  Skills (.claude/skills/ and .agents/skills/):"));
+    const expectedSkills = ["opensddrag-propose","opensddrag-spec","opensddrag-design","opensddrag-tasks","opensddrag-apply","opensddrag-verify","opensddrag-sync","opensddrag-archive","opensddrag-explore","opensddrag-continue","opensddrag-status","opensddrag-flow","opensddrag-search"];
+    const missingSkills = expectedSkills.filter((s) => !existsSync(join(cwd, ".claude", "skills", s, "SKILL.md")));
+    if (missingSkills.length === 0) {
+      console.log(chalk.green("    ✓") + " all " + expectedSkills.length + " skills present");
+    } else {
+      const present = expectedSkills.length - missingSkills.length;
+      console.log(chalk.yellow(`    ! ${present}/${expectedSkills.length} skills present — missing: `) + missingSkills.join(", "));
+    }
+
+    // ── Claude Code ───────────────────────────────────────────────────────────
+    console.log(chalk.dim("\n  Claude Code:"));
+    const mcpJsonPath = join(cwd, ".mcp.json");
+    if (existsSync(mcpJsonPath)) {
+      try {
+        const cfg = JSON.parse(readFileSync(mcpJsonPath, "utf8"));
+        const mcp = cfg?.mcpServers?.opensddrag;
+        if (mcp) {
+          console.log(chalk.green("    ✓") + " .mcp.json  →  type: " + chalk.cyan(mcp.type) + "  url: " + chalk.cyan(mcp.url));
+        } else {
+          console.log(chalk.yellow("    !") + " .mcp.json exists but 'opensddrag' not configured");
+        }
+      } catch {
+        console.log(chalk.red("    ✗") + " .mcp.json — invalid JSON");
+      }
+    } else {
+      console.log(chalk.dim("    –") + " .mcp.json not found");
+    }
+
+
+    // ── Slash commands ────────────────────────────────────────────────────────
+    console.log(chalk.dim("\n  Slash commands (.claude/commands/opsr/):"));
+    const expectedCommands = ["propose", "spec", "design", "tasks", "apply", "verify", "sync", "archive", "explore", "continue", "status", "flow", "search"];
+    const opsrDir = join(cwd, ".claude", "commands", "opsr");
+    const missingCmds = expectedCommands.filter((c) => !existsSync(join(opsrDir, `${c}.md`)));
+    if (missingCmds.length === 0) {
+      console.log(chalk.green("    ✓") + " all commands present: " + chalk.dim(expectedCommands.map((c) => `/opsr:${c}`).join(", ")));
+    } else {
+      const present = expectedCommands.filter((c) => existsSync(join(opsrDir, `${c}.md`)));
+      if (present.length > 0) console.log(chalk.green("    ✓") + " " + present.map((c) => `/opsr:${c}`).join(", "));
+      console.log(chalk.yellow("    !") + " missing: " + missingCmds.map((c) => `/opsr:${c}`).join(", "));
+    }
+
+    // ── OpenCode ──────────────────────────────────────────────────────────────
+    console.log(chalk.dim("\n  OpenCode:"));
+    const opencodePath = join(cwd, "opencode.json");
+    if (existsSync(opencodePath)) {
+      try {
+        const cfg = JSON.parse(readFileSync(opencodePath, "utf8"));
+        const mcp = cfg?.mcp?.opensddrag;
+        if (mcp) {
+          console.log(chalk.green("    ✓") + " opencode.json  →  " + chalk.cyan(mcp.url));
+        } else {
+          console.log(chalk.yellow("    !") + " opencode.json exists but 'opensddrag' not configured");
+        }
+      } catch {
+        console.log(chalk.red("    ✗") + " opencode.json — invalid JSON");
+      }
+    } else {
+      console.log(chalk.dim("    –") + " opencode.json not found");
+    }
+
+    // ── CLAUDE.md ─────────────────────────────────────────────────────────────
+    const claudeMd = join(cwd, "CLAUDE.md");
+    console.log(chalk.dim("\n  CLAUDE.md:"));
+    if (existsSync(claudeMd)) {
+      const content = readFileSync(claudeMd, "utf8");
+      console.log(
+        (content.includes("OpenSddRag") ? chalk.green("    ✓") : chalk.yellow("    !")) +
+        " CLAUDE.md" +
+        (content.includes("OpenSddRag") ? "" : "  (missing OpenSddRag section)")
+      );
+    } else {
+      console.log(chalk.dim("    –") + " CLAUDE.md not found");
+    }
+
+    // ── Server health ─────────────────────────────────────────────────────────
+    console.log(chalk.dim("\n  Server:"));
+    process.stdout.write(`    ${serverUrl} ... `);
+    try {
+      await checkHealth(serverUrl);
+      console.log(chalk.green("online ✓"));
+
+      if (slug) {
+        const projects = await listProjects(serverUrl);
+        const mine = projects.find((p) => p.slug === slug);
+        console.log(
+          (mine ? chalk.green("    ✓") : chalk.yellow("    !")) +
+          ` project '${slug}' ` +
+          (mine ? `registered (id: ${mine.id})` : "NOT registered in database — run: opensddrag init")
+        );
+      }
+    } catch {
+      console.log(chalk.red("offline ✗"));
+      console.log(chalk.dim("    docker compose up -d  or  opensddrag server start --transport sse"));
+    }
+
+    console.log("");
+  });

package/src/templates/claude-md.js

@@ -0,0 +1,69 @@
+export function renderClaudeMdBlock({ slug, serverUrl }) {
+  return `
+---
+
+## OpenSddRag — SDD + Harness
+
+This project uses **OpenSddRag** for Spec-Driven Development with persistent semantic memory.
+
+- **MCP server name:** \`opensddrag\` (${serverUrl}) — configured in \`.mcp.json\`
+- **Project slug:** \`${slug}\`
+- **Skills:** \`.claude/skills/opensddrag-*/SKILL.md\`
+- **Commands:** \`.claude/commands/opsr/\`
+
+### MCP Tools (opensddrag server)
+
+The \`opensddrag\` MCP server exposes these tools — they appear in your tool list under the \`opensddrag\` namespace:
+
+| Tool | Purpose |
+|------|---------|
+| \`create_artifact\` | Create proposals, specs, designs, tasks |
+| \`read_artifact\` | Read an artifact by name |
+| \`list_artifacts\` | List artifacts with type/status filters |
+| \`update_artifact\` | Update content or status |
+| \`validate_artifact\` | Check spec structure |
+| \`link_artifacts\` | Link artifacts (implements / depends_on / relates_to) |
+| \`get_relationships\` | Get linked artifacts |
+| \`search_semantic\` | Semantic search via pgvector |
+| \`recall_episodes\` | Find past agent actions (episodic memory) |
+| \`get_working_context\` | Get active session context |
+| \`update_working_context\` | Update session context |
+| \`record_trace\` | Log an action to episodic memory |
+
+> If these tools are NOT in your active tool list, the server is not connected.
+> Start it with \`docker compose up -d\` and reload the project. Do not attempt to work around a missing server.
+
+### Before implementing any feature
+
+Always search for existing specs first:
+
+\`\`\`
+search_semantic(query="<topic>", project_slug="${slug}")
+\`\`\`
+
+### SDD Commands
+
+| Command | When to use |
+|---------|-------------|
+| \`/opsr:propose\` | Start here — capture intent and scope before any code |
+| \`/opsr:spec\` | Formalize requirements (Purpose / SHALL / Scenarios) |
+| \`/opsr:design\` | Document technical decisions and trade-offs |
+| \`/opsr:tasks\` | Decompose spec into atomic tasks (< 4h each) |
+| \`/opsr:apply\` | Implement the next pending task against spec criteria |
+| \`/opsr:flow\` | Run the full flow end-to-end for a feature |
+| \`/opsr:search\` | Semantic search over specs and past work |
+| \`/opsr:status\` | Show what's in progress and what's done |
+| \`/opsr:archive\` | Mark a completed feature as archived |
+
+### SDD Flow
+
+\`\`\`
+/opsr:propose → /opsr:spec → /opsr:design → /opsr:tasks → /opsr:apply → /opsr:archive
+\`\`\`
+`;
+}
+
+export function renderClaudeMdStandalone({ projectName, slug, serverUrl }) {
+  return `# ${projectName}
+${renderClaudeMdBlock({ slug, serverUrl })}`;
+}