specdrive-cli 0.1.0

package/schemas/spec.schema.json

@@ -0,0 +1,65 @@
+{
+  "": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Specification",
+  "type": "object",
+  "properties": {
+    "feature": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "version": { "type": "integer", "minimum": 1 },
+    "overview": {
+      "type": "object",
+      "properties": {
+        "problemStatement": { "type": "string" },
+        "proposedSolution": { "type": "string" },
+        "targetAudience": { "type": "string" }
+      },
+      "required": ["problemStatement", "proposedSolution", "targetAudience"]
+    },
+    "userStories": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "pattern": "^US-[0-9]{3}$" },
+          "title": { "type": "string" },
+          "acceptanceCriteria": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "pattern": "^AC-[0-9]{3}$" },
+                "text": { "type": "string" }
+              },
+              "required": ["id", "text"]
+            }
+          }
+        },
+        "required": ["id", "title", "acceptanceCriteria"]
+      }
+    },
+    "functionalRequirements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "pattern": "^FR-[0-9]{3}$" },
+          "text": { "type": "string" }
+        },
+        "required": ["id", "text"]
+      }
+    },
+    "nonFunctionalRequirements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "pattern": "^NFR-[0-9]{3}$" },
+          "text": { "type": "string" }
+        },
+        "required": ["id", "text"]
+      }
+    }
+  },
+  "required": ["feature", "version", "overview", "userStories"]
+}

package/schemas/tasks.schema.json

@@ -0,0 +1,44 @@
+{
+  "": "http://json-schema.org/draft-07/schema#",
+  "title": "Execution Tasks",
+  "type": "object",
+  "properties": {
+    "feature": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "version": { "type": "integer", "minimum": 1 },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "phaseId": { "type": "string", "pattern": "^P[0-9]+$" },
+          "name": { "type": "string" },
+          "tasks": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "pattern": "^T[0-9]+\\.[0-9]+$" },
+                "title": { "type": "string" },
+                "description": { "type": "string" },
+                "linkedRequirements": {
+                  "type": "array",
+                  "items": { "type": "string", "pattern": "^(FR|NFR)-[0-9]{3}$" }
+                },
+                "linkedAcceptanceCriteria": {
+                  "type": "array",
+                  "items": { "type": "string", "pattern": "^AC-[0-9]{3}$" }
+                },
+                "completed": { "type": "boolean", "default": false }
+              },
+              "required": ["id", "title", "linkedRequirements"]
+            }
+          }
+        },
+        "required": ["phaseId", "name", "tasks"]
+      }
+    }
+  },
+  "required": ["feature", "version", "phases"]
+}

package/schemas/traceability.schema.json

@@ -0,0 +1,34 @@
+{
+  "": "http://json-schema.org/draft-07/schema#",
+  "title": "Traceability Matrix",
+  "type": "object",
+  "properties": {
+    "feature": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "version": { "type": "integer", "minimum": 1 },
+    "rows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "requirementId": { "type": "string", "pattern": "^(FR|NFR)-[0-9]{3}$" },
+          "acceptanceCriteriaIds": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^AC-[0-9]{3}$" }
+          },
+          "planSection": { "type": "string" },
+          "taskIds": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^T[0-9]+\\.[0-9]+$" }
+          },
+          "testIds": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^TEST-[0-9]{3}$" }
+          },
+          "status": { "enum": ["not_started", "in_progress", "complete"] }
+        },
+        "required": ["requirementId", "status"]
+      }
+    }
+  },
+  "required": ["feature", "version", "rows"]
+}

package/schemas/workflow-state.schema.json

@@ -0,0 +1,41 @@
+{
+  "": "http://json-schema.org/draft-07/schema#",
+  "title": "Workflow State",
+  "type": "object",
+  "properties": {
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "phase": { "enum": ["backlog", "ongoing", "completed", "blocked"] },
+          "currentStep": { "enum": ["specification", "planning", "implementation", "review"] },
+          "gates": {
+            "type": "object",
+            "properties": {
+              "specification": { "enum": ["pending", "approved", "rejected"] },
+              "planning": { "enum": ["pending", "approved", "rejected"] },
+              "implementation": { "enum": ["pending", "in_progress", "approved", "rejected"] },
+              "review": { "enum": ["pending", "approved", "rejected"] }
+            },
+            "required": ["specification", "planning", "implementation", "review"]
+          },
+          "history": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "event": { "type": "string" },
+                "timestamp": { "type": "string", "format": "date-time" }
+              },
+              "required": ["event", "timestamp"]
+            }
+          }
+        },
+        "required": ["name", "phase", "currentStep", "gates"]
+      }
+    }
+  },
+  "required": ["features"]
+}

package/scripts/anti-redundancy.js

@@ -0,0 +1,177 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+
+function readJson(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+  } catch (error) {
+    console.error(`⚠️  Could not parse ${filePath}: ${error.message}`);
+  }
+  return null;
+}
+
+function getInstalledDependencies() {
+  const packageJson = readJson(path.join(projectRoot, "package.json"));
+  if (!packageJson) return [];
+
+  return [
+    ...Object.keys(packageJson.dependencies || {}),
+    ...Object.keys(packageJson.devDependencies || {})
+  ];
+}
+
+function listFiles(dir, extensions = [".ts", ".tsx", ".js", ".jsx"]) {
+  if (!fs.existsSync(dir)) return [];
+
+  let results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results = results.concat(listFiles(fullPath, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+function detectExistingAssets() {
+  const srcDir = path.join(projectRoot, "src");
+  const files = listFiles(srcDir);
+
+  const assets = {
+    components: [],
+    services: [],
+    hooks: [],
+    utils: [],
+    api: [],
+    models: [],
+    constants: []
+  };
+
+  files.forEach((file) => {
+    const relative = path.relative(projectRoot, file).replace(/\\/g, "/");
+
+    if (relative.includes("/components/") || relative.includes("/ui/")) {
+      assets.components.push(relative);
+    }
+
+    if (relative.includes("/services/") || relative.includes("/api/")) {
+      assets.services.push(relative);
+    }
+
+    if (relative.includes("/hooks/") || relative.startsWith("use-")) {
+      assets.hooks.push(relative);
+    }
+
+    if (relative.includes("/utils/") || relative.includes("/helpers/")) {
+      assets.utils.push(relative);
+    }
+
+    if (relative.includes("/models/") || relative.includes("/entities/")) {
+      assets.models.push(relative);
+    }
+
+    if (relative.includes("/constants/") || relative.includes("/config/")) {
+      assets.constants.push(relative);
+    }
+  });
+
+  return assets;
+}
+
+function checkRedundancy(plannedItems) {
+  const existingAssets = detectExistingAssets();
+  const installedDependencies = getInstalledDependencies();
+
+  const report = plannedItems.map((item) => {
+    let exists = false;
+    let location = null;
+
+    switch (item.type) {
+      case "component":
+        exists = existingAssets.components.some((path) => path.includes(item.name));
+        if (exists) {
+          location = existingAssets.components.find((path) => path.includes(item.name));
+        }
+        break;
+      case "service":
+      case "api":
+        exists = existingAssets.services.some((path) => path.includes(item.name));
+        if (exists) {
+          location = existingAssets.services.find((path) => path.includes(item.name));
+        }
+        break;
+      case "hook":
+        exists = existingAssets.hooks.some((path) => path.includes(item.name));
+        if (exists) {
+          location = existingAssets.hooks.find((path) => path.includes(item.name));
+        }
+        break;
+      case "utility":
+        exists = existingAssets.utils.some((path) => path.includes(item.name));
+        if (exists) {
+          location = existingAssets.utils.find((path) => path.includes(item.name));
+        }
+        break;
+      case "model":
+      case "entity":
+        exists = existingAssets.models.some((path) => path.includes(item.name));
+        if (exists) {
+          location = existingAssets.models.find((path) => path.includes(item.name));
+        }
+        break;
+      case "package":
+      case "dependency":
+        exists = installedDependencies.includes(item.name);
+        location = exists ? "package.json" : null;
+        break;
+      default:
+        exists = false;
+        location = null;
+    }
+
+    return {
+      name: item.name,
+      type: item.type,
+      exists,
+      action: exists ? "reuse" : "create",
+      location
+    };
+  });
+
+  return {
+    feature: "current",
+    items: report,
+    existingAssets,
+    installedDependencies
+  };
+}
+
+function main() {
+  const plannedItemsPath = process.argv[2];
+
+  if (!plannedItemsPath) {
+    console.error("❌ Usage: node anti-redundancy.js <planned-items.json>");
+    process.exit(1);
+  }
+
+  const plannedItems = readJson(path.resolve(plannedItemsPath));
+
+  if (!plannedItems || !Array.isArray(plannedItems)) {
+    console.error("❌ planned-items.json must contain an array of items.");
+    process.exit(1);
+  }
+
+  const report = checkRedundancy(plannedItems);
+  console.log(JSON.stringify(report, null, 2));
+}
+
+main();

package/scripts/audit-log.js

@@ -0,0 +1,35 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+const auditLogPath = path.join(projectRoot, ".sdrive", "audit-log.json");
+
+function loadAuditLog() {
+  if (!fs.existsSync(auditLogPath)) {
+    return { events: [] };
+  }
+  return JSON.parse(fs.readFileSync(auditLogPath, "utf8"));
+}
+
+function saveAuditLog(log) {
+  fs.writeFileSync(auditLogPath, JSON.stringify(log, null, 2));
+}
+
+function logEvent(event, details = {}) {
+  const log = loadAuditLog();
+
+  log.events.push({
+    timestamp: new Date().toISOString(),
+    ...details,
+    event
+  });
+
+  saveAuditLog(log);
+  console.log(`📝 Audit: ${event}`);
+}
+
+module.exports = {
+  logEvent,
+  loadAuditLog,
+  saveAuditLog
+};

package/scripts/generate-adapters.js

@@ -0,0 +1,81 @@
+// SAFETY RULE
+// NEVER overwrite existing files in .github/
+// If a file exists, ask the user before modifying it.
+// Only create new files if missing.
+
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+
+function loadTools() {
+  const toolsPath = path.join(projectRoot, ".sdrive", "commands", "tools.json");
+
+  if (!fs.existsSync(toolsPath)) {
+    console.error("❌ tools.json not found.");
+    process.exit(1);
+  }
+
+  return JSON.parse(fs.readFileSync(toolsPath, "utf8")).tools;
+}
+
+function adapterContent(toolName) {
+  return `# SpecDrive Commands
+
+This project uses SpecDrive for spec-driven development.
+
+## How to use
+
+When the user types a /sdrive:* command, follow these steps:
+
+1. Read .sdrive/commands/manifest.json
+2. Find the matching command
+3. Read the agent file listed in agentFile
+4. Follow that agent's instructions exactly
+5. Run validators after writing files
+6. Stop at human approval gates
+
+## Command list
+
+- /sdrive:constitution — Create or update project constitution
+- /sdrive:propose — Create spec, traceability, plan, and tasks
+- /sdrive:design — Build UI/UX prototype
+- /sdrive:apply — Write production code
+- /sdrive:review — Final audit and merge
+- /sdrive:secure — Security audit
+- /sdrive:performance — Performance benchmark
+- /sdrive:docs — Generate documentation
+- /sdrive:sync — Cascade sync
+- /sdrive:skills — Manage AI skills
+
+Always read the manifest first. Never hardcode the command list.
+`;
+}
+
+function generate() {
+  const tools = loadTools();
+
+  tools.forEach((tool) => {
+    const adapterFullPath = path.join(projectRoot, tool.adapterPath);
+    const adapterDir = path.dirname(adapterFullPath);
+
+    if (!fs.existsSync(adapterDir)) {
+      fs.mkdirSync(adapterDir, { recursive: true });
+    }
+
+    // SAFETY GUARD
+    if (fs.existsSync(adapterFullPath)) {
+      console.log(`⚠️  Skipped existing file: ${tool.adapterPath}`);
+      console.log("    SpecDrive never overwrites existing project files.");
+      console.log("    Delete the file or rename it to regenerate.\n");
+      return;
+    }
+
+    fs.writeFileSync(adapterFullPath, adapterContent(tool.name));
+    console.log(`✅ Generated adapter: ${tool.adapterPath}`);
+  });
+
+  console.log("\n🎉 Adapter generation complete.");
+}
+
+generate();

package/scripts/generate-from-template.js

@@ -0,0 +1,70 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+
+function loadTemplate(templateName, fileName) {
+  const templatePath = path.join(projectRoot, ".sdrive", "templates", templateName, fileName);
+  return fs.readFileSync(templatePath, "utf8");
+}
+
+function applyVariables(content, variables) {
+  let result = content;
+  Object.keys(variables).forEach((key) => {
+    result = result.replaceAll(`{{${key}}}`, variables[key]);
+  });
+  return result;
+}
+
+function generate(templateName, featureName, variables) {
+  const templateDir = path.join(projectRoot, ".sdrive", "templates", templateName);
+  const govDir = path.join(projectRoot, ".sdrive", "governance", featureName);
+
+  if (!fs.existsSync(templateDir)) {
+    console.error(`❌ Template "${templateName}" not found.`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(govDir, { recursive: true });
+
+  const files = ["spec.json", "plan.json", "tasks.json"];
+
+  files.forEach((file) => {
+    const templateFile = path.join(templateDir, file);
+    if (!fs.existsSync(templateFile)) {
+      return;
+    }
+
+    let content = loadTemplate(templateName, file);
+    content = applyVariables(content, {
+      featureName,
+      ...variables
+    });
+
+    fs.writeFileSync(path.join(govDir, file), content);
+    console.log(`✅ Generated: ${featureName}/${file}`);
+  });
+
+  console.log(`\n🎉 Feature "${featureName}" generated from "${templateName}" template.`);
+}
+
+const templateName = process.argv[2];
+const featureName = process.argv[3];
+const problemStatement = process.argv[4] || "";
+const proposedSolution = process.argv[5] || "";
+const targetAudience = process.argv[6] || "";
+const approach = process.argv[7] || "";
+const flowDescription = process.argv[8] || "";
+
+if (!templateName || !featureName) {
+  console.error("❌ Usage: node generate-from-template.js <template> <feature> [problem] [solution] [audience] [approach] [flow]");
+  process.exit(1);
+}
+
+generate(templateName, featureName, {
+  problemStatement,
+  proposedSolution,
+  targetAudience,
+  approach,
+  flowDescription
+});

package/scripts/load-plugins.js

@@ -0,0 +1,57 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+const pluginsDir = path.join(projectRoot, ".sdrive", "plugins");
+
+function loadPlugins() {
+  if (!fs.existsSync(pluginsDir)) {
+    return [];
+  }
+
+  const pluginFolders = fs.readdirSync(pluginsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  const plugins = [];
+
+  pluginFolders.forEach((folder) => {
+    const pluginJsonPath = path.join(pluginsDir, folder, "plugin.json");
+
+    if (!fs.existsSync(pluginJsonPath)) {
+      return;
+    }
+
+    const pluginDef = JSON.parse(fs.readFileSync(pluginJsonPath, "utf8"));
+    plugins.push({
+      ...pluginDef,
+      path: path.join(pluginsDir, folder)
+    });
+  });
+
+  return plugins;
+}
+
+function runPlugin(pluginName) {
+  const plugins = loadPlugins();
+  const plugin = plugins.find((p) => p.name === pluginName);
+
+  if (!plugin) {
+    console.error(`❌ Plugin "${pluginName}" not found.`);
+    process.exit(1);
+  }
+
+  const entryPath = path.join(plugin.path, plugin.entry);
+
+  if (!fs.existsSync(entryPath)) {
+    console.error(`❌ Plugin entry not found: ${plugin.entry}`);
+    process.exit(1);
+  }
+
+  require(entryPath);
+}
+
+module.exports = {
+  loadPlugins,
+  runPlugin
+};

package/scripts/pre-commit.js

@@ -0,0 +1,20 @@
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const projectRoot = process.cwd();
+const validatorPath = path.join(projectRoot, ".sdrive", "scripts", "validate-governance.js");
+
+if (!fs.existsSync(validatorPath)) {
+  console.log("⚠️  Validator not found. Skipping pre-commit validation.");
+  process.exit(0);
+}
+
+try {
+  execSync(`node "${validatorPath}"`, { stdio: "inherit" });
+  console.log("✅ Pre-commit validation passed.");
+  process.exit(0);
+} catch (error) {
+  console.error("❌ Pre-commit validation failed. Fix errors before committing.");
+  process.exit(1);
+}

package/scripts/team.js

@@ -0,0 +1,41 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+const teamPath = path.join(projectRoot, ".sdrive", "team.json");
+
+function loadTeam() {
+  if (!fs.existsSync(teamPath)) {
+    console.error("❌ team.json not found.");
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(teamPath, "utf8"));
+}
+
+function getUserRole(username) {
+  const team = loadTeam();
+  const member = team.members.find((m) => m.username === username);
+  return member ? member.role : null;
+}
+
+function canApprove(username) {
+  const role = getUserRole(username);
+  if (!role) return false;
+
+  const team = loadTeam();
+  return team.rules.approval_required.includes(role);
+}
+
+function canImplement(username) {
+  const role = getUserRole(username);
+  if (!role) return false;
+
+  const team = loadTeam();
+  return team.rules.implementation_allowed.includes(role);
+}
+
+module.exports = {
+  getUserRole,
+  canApprove,
+  canImplement
+};