opensdd 0.1.0

package/src/lib/registry.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_REGISTRY = 'https://github.com/deepagents-ai/opensdd';
+
+export function resolveRegistry(options, manifest) {
+  if (options?.registry) return options.registry;
+  if (manifest?.registry) return manifest.registry;
+  return DEFAULT_REGISTRY;
+}
+
+export function isLocalPath(source) {
+  return !source.startsWith('http://') && !source.startsWith('https://');
+}
+
+export function isGitHubUrl(source) {
+  return /github\.com/.test(source);
+}
+
+export function parseGitHubUrl(url) {
+  const match = url.match(/github\.com\/([^/]+)\/([^/.]+)/);
+  if (!match) throw new Error(`Invalid GitHub URL: ${url}`);
+  return { owner: match[1], repo: match[2] };
+}
+
+async function githubApiFetch(urlPath, owner, repo) {
+  const url = `https://api.github.com/repos/${owner}/${repo}/contents/${urlPath}`;
+  const headers = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'opensdd-cli',
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    if (response.status === 404) return null;
+    throw new Error(`GitHub API error: ${response.status} ${response.statusText} for ${url}`);
+  }
+  return response.json();
+}
+
+async function githubRawFetch(filePath, owner, repo) {
+  const data = await githubApiFetch(filePath, owner, repo);
+  if (!data) return null;
+  if (data.content) {
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  }
+  // For larger files, use download_url
+  if (data.download_url) {
+    const response = await fetch(data.download_url, {
+      headers: { 'User-Agent': 'opensdd-cli' },
+    });
+    if (!response.ok) throw new Error(`Failed to download ${filePath}`);
+    return response.text();
+  }
+  throw new Error(`Could not fetch content for ${filePath}`);
+}
+
+/**
+ * List all specs available in the registry.
+ * Returns an array of index.json objects.
+ */
+export async function listRegistrySpecs(registrySource) {
+  if (isLocalPath(registrySource)) {
+    const registryDir = path.join(registrySource, 'registry');
+    if (!fs.existsSync(registryDir)) return [];
+    const entries = fs.readdirSync(registryDir, { withFileTypes: true });
+    const specs = [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const indexPath = path.join(registryDir, entry.name, 'index.json');
+        if (fs.existsSync(indexPath)) {
+          try {
+            const index = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+            specs.push(index);
+          } catch {
+            console.warn(`Warning: Malformed index.json for ${entry.name}, skipping.`);
+          }
+        }
+      }
+    }
+    return specs;
+  }
+
+  // GitHub registry
+  const { owner, repo } = parseGitHubUrl(registrySource);
+  const contents = await githubApiFetch('registry', owner, repo);
+  if (!contents || !Array.isArray(contents)) return [];
+
+  const specs = [];
+  for (const item of contents) {
+    if (item.type === 'dir') {
+      try {
+        const indexContent = await githubRawFetch(`registry/${item.name}/index.json`, owner, repo);
+        if (indexContent) {
+          specs.push(JSON.parse(indexContent));
+        }
+      } catch {
+        console.warn(`Warning: Could not read index.json for ${item.name}, skipping.`);
+      }
+    }
+  }
+  return specs;
+}
+
+/**
+ * Fetch index.json for a specific spec from the registry.
+ */
+export async function fetchSpecIndex(registrySource, specName) {
+  if (isLocalPath(registrySource)) {
+    const indexPath = path.join(registrySource, 'registry', specName, 'index.json');
+    if (!fs.existsSync(indexPath)) return null;
+    return JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+  }
+
+  const { owner, repo } = parseGitHubUrl(registrySource);
+  const content = await githubRawFetch(`registry/${specName}/index.json`, owner, repo);
+  if (!content) return null;
+  return JSON.parse(content);
+}
+
+/**
+ * Fetch manifest.json for a specific spec version from the registry.
+ */
+export async function fetchSpecManifest(registrySource, specName, version) {
+  if (isLocalPath(registrySource)) {
+    const manifestPath = path.join(registrySource, 'registry', specName, version, 'manifest.json');
+    if (!fs.existsSync(manifestPath)) return null;
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  }
+
+  const { owner, repo } = parseGitHubUrl(registrySource);
+  const content = await githubRawFetch(`registry/${specName}/${version}/manifest.json`, owner, repo);
+  if (!content) return null;
+  return JSON.parse(content);
+}
+
+/**
+ * Fetch all files for a specific spec version from the registry.
+ * Returns an object mapping filename -> content string.
+ */
+export async function fetchSpecFiles(registrySource, specName, version) {
+  const files = {};
+
+  if (isLocalPath(registrySource)) {
+    const versionDir = path.join(registrySource, 'registry', specName, version);
+    if (!fs.existsSync(versionDir)) return null;
+    const entries = fs.readdirSync(versionDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        files[entry.name] = fs.readFileSync(path.join(versionDir, entry.name), 'utf-8');
+      }
+    }
+    return files;
+  }
+
+  // GitHub registry
+  const { owner, repo } = parseGitHubUrl(registrySource);
+  const contents = await githubApiFetch(`registry/${specName}/${version}`, owner, repo);
+  if (!contents || !Array.isArray(contents)) return null;
+
+  for (const item of contents) {
+    if (item.type === 'file') {
+      const content = await githubRawFetch(
+        `registry/${specName}/${version}/${item.name}`,
+        owner,
+        repo
+      );
+      if (content !== null) {
+        files[item.name] = content;
+      }
+    }
+  }
+  return files;
+}

package/src/lib/skills.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const OPENSDD_SECTION_START = '<!-- OpenSDD Skills (managed by opensdd init \u2014 do not edit this section) -->';
+const OPENSDD_SECTION_END = '<!-- /OpenSDD Skills -->';
+
+function getSkillContent() {
+  const opensddDir = path.resolve(__dirname, '../../opensdd');
+  return {
+    sddManager: fs.readFileSync(path.join(opensddDir, 'sdd-manager.md'), 'utf-8'),
+    sddGenerate: fs.readFileSync(path.join(opensddDir, 'sdd-generate.md'), 'utf-8'),
+    specFormat: fs.readFileSync(path.join(opensddDir, 'spec-format.md'), 'utf-8'),
+  };
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFileSync(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content);
+}
+
+/**
+ * Update a managed section in a file (GEMINI.md or AGENTS.md).
+ * Creates the file if it doesn't exist.
+ * Only modifies the clearly delimited OpenSDD section.
+ */
+function updateManagedSection(filePath, sectionBody) {
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf-8');
+  }
+
+  const sectionContent = `${OPENSDD_SECTION_START}\n${sectionBody}\n${OPENSDD_SECTION_END}`;
+
+  const startIdx = content.indexOf(OPENSDD_SECTION_START);
+  const endIdx = content.indexOf(OPENSDD_SECTION_END);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing section
+    content =
+      content.substring(0, startIdx) +
+      sectionContent +
+      content.substring(endIdx + OPENSDD_SECTION_END.length);
+  } else if (startIdx !== -1) {
+    // Start marker exists but no end marker — replace from start to end
+    content = content.substring(0, startIdx) + sectionContent;
+  } else {
+    // No existing section — append
+    if (content.length > 0 && !content.endsWith('\n')) {
+      content += '\n';
+    }
+    if (content.length > 0) {
+      content += '\n';
+    }
+    content += sectionContent + '\n';
+  }
+
+  fs.writeFileSync(filePath, content);
+}
+
+/**
+ * Install both skills (sdd-manager and sdd-generate) into all 6 supported agent formats.
+ * Returns an array of warnings for non-critical failures.
+ * Throws on critical failures (e.g., Claude Code installation fails).
+ */
+export function installSkills(projectRoot) {
+  const skills = getSkillContent();
+  const warnings = [];
+
+  // 1. Claude Code (critical — Gemini and Amp depend on this)
+  const claudeBase = path.join(projectRoot, '.claude', 'skills');
+  writeFileSync(
+    path.join(claudeBase, 'sdd-manager', 'SKILL.md'),
+    skills.sddManager
+  );
+  writeFileSync(
+    path.join(claudeBase, 'sdd-manager', 'references', 'spec-format.md'),
+    skills.specFormat
+  );
+  writeFileSync(
+    path.join(claudeBase, 'sdd-generate', 'SKILL.md'),
+    skills.sddGenerate
+  );
+  writeFileSync(
+    path.join(claudeBase, 'sdd-generate', 'references', 'spec-format.md'),
+    skills.specFormat
+  );
+
+  // 2. Codex CLI
+  try {
+    const codexBase = path.join(projectRoot, '.agents', 'skills');
+    writeFileSync(
+      path.join(codexBase, 'sdd-manager', 'SKILL.md'),
+      skills.sddManager
+    );
+    writeFileSync(
+      path.join(codexBase, 'sdd-manager', 'references', 'spec-format.md'),
+      skills.specFormat
+    );
+    writeFileSync(
+      path.join(codexBase, 'sdd-generate', 'SKILL.md'),
+      skills.sddGenerate
+    );
+    writeFileSync(
+      path.join(codexBase, 'sdd-generate', 'references', 'spec-format.md'),
+      skills.specFormat
+    );
+  } catch (err) {
+    warnings.push(`Could not install Codex CLI skills: ${err.message}`);
+  }
+
+  // 3. Cursor
+  try {
+    const cursorBase = path.join(projectRoot, '.cursor', 'rules');
+    ensureDir(cursorBase);
+
+    const sddManagerCursor = `---
+description: "Implement, update, and verify installed OpenSDD dependency specs. Use when the user asks to implement a spec, process a spec update, check conformance, or create a deviation."
+alwaysApply: false
+---
+
+${skills.sddManager}`;
+
+    const sddGenerateCursor = `---
+description: "Generate an OpenSDD behavioral spec from existing code. Use when the user asks to generate, create, or extract a spec from a repository or codebase."
+alwaysApply: false
+---
+
+${skills.sddGenerate}`;
+
+    const specFormatCursor = `---
+description: "OpenSDD spec format reference. Defines the structure and rules for behavioral specifications. Referenced by sdd-manager and sdd-generate skills."
+alwaysApply: false
+---
+
+${skills.specFormat}`;
+
+    writeFileSync(path.join(cursorBase, 'sdd-manager.md'), sddManagerCursor);
+    writeFileSync(path.join(cursorBase, 'sdd-generate.md'), sddGenerateCursor);
+    writeFileSync(path.join(cursorBase, 'opensdd-spec-format.md'), specFormatCursor);
+  } catch (err) {
+    warnings.push(`Could not install Cursor skills: ${err.message}`);
+  }
+
+  // 4. GitHub Copilot
+  try {
+    const copilotBase = path.join(projectRoot, '.github', 'instructions');
+    ensureDir(copilotBase);
+
+    const copilotFrontmatter = `---
+applyTo: "**"
+---
+
+`;
+
+    writeFileSync(
+      path.join(copilotBase, 'sdd-manager.instructions.md'),
+      copilotFrontmatter + skills.sddManager
+    );
+    writeFileSync(
+      path.join(copilotBase, 'sdd-generate.instructions.md'),
+      copilotFrontmatter + skills.sddGenerate
+    );
+    writeFileSync(
+      path.join(copilotBase, 'opensdd-spec-format.instructions.md'),
+      copilotFrontmatter + skills.specFormat
+    );
+  } catch (err) {
+    warnings.push(`Could not install GitHub Copilot skills: ${err.message}`);
+  }
+
+  // 5. Gemini CLI
+  try {
+    const geminiPath = path.join(projectRoot, 'GEMINI.md');
+    const geminiBody = `@.claude/skills/sdd-manager/SKILL.md
+@.claude/skills/sdd-manager/references/spec-format.md
+@.claude/skills/sdd-generate/SKILL.md
+@.claude/skills/sdd-generate/references/spec-format.md`;
+    updateManagedSection(geminiPath, geminiBody);
+  } catch (err) {
+    warnings.push(`Could not install Gemini CLI skills: ${err.message}`);
+  }
+
+  // 6. Amp
+  try {
+    const ampPath = path.join(projectRoot, 'AGENTS.md');
+    const ampBody = `@.claude/skills/sdd-manager/SKILL.md
+@.claude/skills/sdd-manager/references/spec-format.md
+@.claude/skills/sdd-generate/SKILL.md
+@.claude/skills/sdd-generate/references/spec-format.md`;
+    updateManagedSection(ampPath, ampBody);
+  } catch (err) {
+    warnings.push(`Could not install Amp skills: ${err.message}`);
+  }
+
+  return warnings;
+}

package/src/lib/validation.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Validate a spec directory for conformance to the OpenSDD spec-format.
+ * Returns an object with errors, warnings, and detailed results per file.
+ */
+export function validateSpec(specDir) {
+  const result = {
+    errors: [],
+    warnings: [],
+    specErrors: [],
+    specWarnings: [],
+    manifestErrors: [],
+    manifestExists: false,
+    hasDeviations: false,
+    manifest: null,
+  };
+
+  // Check for spec.md
+  const specMdPath = path.join(specDir, 'spec.md');
+  if (!fs.existsSync(specMdPath)) {
+    result.specErrors.push('Missing required file: spec.md');
+    result.errors.push('Missing required file: spec.md');
+  } else {
+    const content = fs.readFileSync(specMdPath, 'utf-8');
+    validateSpecMd(content, result);
+  }
+
+  // Check for manifest.json (optional, but validate if present)
+  const manifestPath = path.join(specDir, 'manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    result.manifestExists = true;
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      result.manifest = manifest;
+      validateManifest(manifest, result);
+    } catch (err) {
+      result.manifestErrors.push(`Malformed JSON: ${err.message}`);
+      result.errors.push('manifest.json: Malformed JSON');
+    }
+  }
+
+  // Check for deviations.md (specs for registry MUST NOT contain deviations)
+  if (fs.existsSync(path.join(specDir, 'deviations.md'))) {
+    result.hasDeviations = true;
+    result.errors.push('deviations.md found (specs for the registry must not contain deviations)');
+  }
+
+  return result;
+}
+
+function validateSpecMd(content, result) {
+  const lines = content.split('\n');
+
+  // Check for H1 header — spec says "MUST start with an H1 header"
+  // Find the first non-empty line
+  const firstContentIndex = lines.findIndex((l) => l.trim().length > 0);
+  const firstContentLine = firstContentIndex !== -1 ? lines[firstContentIndex] : '';
+
+  if (!/^# .+/.test(firstContentLine)) {
+    result.specErrors.push('Missing required: H1 header with blockquote summary');
+    result.errors.push('spec.md: Missing H1 header with blockquote summary');
+  } else {
+    // Check for blockquote summary after H1
+    let foundBlockquote = false;
+    for (let i = firstContentIndex + 1; i < Math.min(firstContentIndex + 5, lines.length); i++) {
+      if (lines[i].startsWith('> ')) {
+        foundBlockquote = true;
+        break;
+      }
+    }
+    if (!foundBlockquote) {
+      result.specErrors.push('Missing required: blockquote summary after H1 header');
+      result.errors.push('spec.md: Missing blockquote summary after H1');
+    }
+  }
+
+  // Check for Behavioral Contract section
+  if (!content.includes('## Behavioral Contract')) {
+    result.specErrors.push('Missing required: ## Behavioral Contract section');
+    result.errors.push('spec.md: Missing Behavioral Contract section');
+  }
+
+  // SHOULD warnings for recommended sections
+  if (!content.includes('## NOT Specified')) {
+    result.specWarnings.push('Missing ## NOT Specified section (recommended)');
+    result.warnings.push('spec.md: Missing NOT Specified section');
+  }
+
+  if (!content.includes('## Invariants')) {
+    result.specWarnings.push('Missing ## Invariants section (recommended)');
+    result.warnings.push('spec.md: Missing Invariants section');
+  }
+
+  if (!content.includes('## Edge Cases')) {
+    result.specWarnings.push('Missing ## Edge Cases section (recommended)');
+    result.warnings.push('spec.md: Missing Edge Cases section');
+  }
+}
+
+function validateManifest(manifest, result) {
+  if (!manifest.name) {
+    result.manifestErrors.push('Missing required field: name');
+    result.errors.push('manifest.json: Missing name');
+  }
+
+  if (!manifest.spec_format) {
+    result.manifestErrors.push('Missing required field: spec_format');
+    result.errors.push('manifest.json: Missing spec_format');
+  }
+
+  if (!manifest.version) {
+    result.manifestErrors.push('Missing required field: version');
+    result.errors.push('manifest.json: Missing version');
+  } else if (!/^\d+\.\d+\.\d+/.test(manifest.version)) {
+    result.manifestErrors.push(
+      `Invalid version format: ${manifest.version} (must be valid semver)`
+    );
+    result.errors.push('manifest.json: Invalid version format');
+  }
+}