opensdd 0.1.0

package/src/commands/init.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { installSkills } from '../lib/skills.js';
+
+const PROJECT_MARKERS = [
+  'package.json',
+  'pyproject.toml',
+  'Cargo.toml',
+  'go.mod',
+  '.git',
+  'opensdd.json',
+  'pom.xml',
+  'build.gradle',
+  'build.gradle.kts',
+  'Makefile',
+  'CMakeLists.txt',
+  'composer.json',
+  'Gemfile',
+  'setup.py',
+  'setup.cfg',
+  'mix.exs',
+  'deno.json',
+  'bun.lockb',
+];
+
+function hasProjectMarker(dir) {
+  return PROJECT_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)));
+}
+
+function getProjectName(dir) {
+  // Try package.json
+  const pkgPath = path.join(dir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.name) return pkg.name;
+    } catch {
+      // ignore
+    }
+  }
+  // Try pyproject.toml
+  const pyprojectPath = path.join(dir, 'pyproject.toml');
+  if (fs.existsSync(pyprojectPath)) {
+    try {
+      const content = fs.readFileSync(pyprojectPath, 'utf-8');
+      const match = content.match(/name\s*=\s*"([^"]+)"/);
+      if (match) return match[1];
+    } catch {
+      // ignore
+    }
+  }
+  // Try Cargo.toml
+  const cargoPath = path.join(dir, 'Cargo.toml');
+  if (fs.existsSync(cargoPath)) {
+    try {
+      const content = fs.readFileSync(cargoPath, 'utf-8');
+      const match = content.match(/name\s*=\s*"([^"]+)"/);
+      if (match) return match[1];
+    } catch {
+      // ignore
+    }
+  }
+  // Default to directory name
+  return path.basename(dir);
+}
+
+function promptYN(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+export async function initCommand() {
+  const cwd = process.cwd();
+
+  // Step 1: Check for project markers
+  if (!hasProjectMarker(cwd)) {
+    const proceed = await promptYN(
+      'Warning: No project markers found in the current directory. Continue? (y/n) '
+    );
+    if (!proceed) {
+      process.exit(0);
+    }
+  }
+
+  // Step 2: Install skills to all agent formats
+  let warnings;
+  try {
+    warnings = installSkills(cwd);
+  } catch (err) {
+    console.error(`Error: Could not install skills: ${err.message}`);
+    process.exit(1);
+  }
+
+  for (const w of warnings) {
+    console.warn(`Warning: ${w}`);
+  }
+
+  // Step 3: Read or create opensdd.json
+  const manifestPath = path.join(cwd, 'opensdd.json');
+  let manifest = null;
+  let manifestCreated = false;
+
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch (err) {
+      console.error(`Error: opensdd.json is malformed JSON: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (!manifest) {
+    manifest = {
+      opensdd: '0.1.0',
+      specs_dir: 'opensdd',
+      deps_dir: '.opensdd.deps',
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    manifestCreated = true;
+  }
+
+  const specsDir = manifest.specs_dir || 'opensdd';
+  const depsDir = manifest.deps_dir || '.opensdd.deps';
+  const specsDirPath = path.join(cwd, specsDir);
+  const depsDirPath = path.join(cwd, depsDir);
+
+  // Step 4: Create specs directory
+  const specsDirCreated = !fs.existsSync(specsDirPath);
+  fs.mkdirSync(specsDirPath, { recursive: true });
+
+  // Step 5: Create skeleton spec.md
+  const specMdPath = path.join(specsDirPath, 'spec.md');
+  let specMdCreated = false;
+  if (!fs.existsSync(specMdPath)) {
+    const projectName = getProjectName(cwd);
+    const skeleton = `# ${projectName}
+
+> TODO: One-line description of what this software does.
+
+## Behavioral Contract
+
+<!-- Define behaviors here. -->
+
+## NOT Specified (Implementation Freedom)
+
+<!-- List aspects left to the implementer's discretion. -->
+
+## Invariants
+
+<!-- List properties that must hold true across all inputs and states. -->
+`;
+    fs.writeFileSync(specMdPath, skeleton);
+    specMdCreated = true;
+  }
+
+  // Step 6: Create deps directory
+  const depsDirCreated = !fs.existsSync(depsDirPath);
+  fs.mkdirSync(depsDirPath, { recursive: true });
+
+  // Step 7: Print output
+  const isReInit = !manifestCreated;
+  const skillVerb = isReInit ? 'updated' : 'installed';
+
+  console.log('Initialized OpenSDD:');
+  console.log(
+    '  Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp'
+  );
+  console.log(`    sdd-manager              ${skillVerb} (6 agent formats)`);
+  console.log(`    sdd-generate             ${skillVerb} (6 agent formats)`);
+  console.log(
+    `  opensdd.json               ${manifestCreated ? 'created' : 'already exists (preserved)'}`
+  );
+  console.log(`  ${specsDir}/                   ${specsDirCreated ? 'created' : 'already exists'}`);
+  console.log(
+    `  ${specsDir}/spec.md            ${specMdCreated ? 'created (skeleton)' : 'already exists (preserved)'}`
+  );
+  console.log(`  ${depsDir}/             ${depsDirCreated ? 'created' : 'already exists'}`);
+}

package/src/commands/install.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  findManifestPath,
+  readManifest,
+  writeManifest,
+  getDepsDir,
+} from '../lib/manifest.js';
+import {
+  resolveRegistry,
+  fetchSpecIndex,
+  fetchSpecManifest,
+  fetchSpecFiles,
+  listRegistrySpecs,
+} from '../lib/registry.js';
+
+function isValidSpecName(name) {
+  return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name);
+}
+
+export async function installCommand(name, version, options) {
+  // Step 1: Verify opensdd.json exists
+  const manifestPath = findManifestPath(process.cwd());
+  if (!manifestPath) {
+    console.error('Error: OpenSDD not initialized. Run `opensdd init` to get started.');
+    process.exit(1);
+  }
+
+  const manifest = readManifest(manifestPath);
+  const projectRoot = path.dirname(manifestPath);
+  const depsDir = getDepsDir(manifest);
+  const depsDirPath = path.join(projectRoot, depsDir);
+  const registrySource = resolveRegistry(options, manifest);
+
+  // Step 2: Check if already installed
+  const deps = manifest.dependencies || {};
+  const specDirPath = path.join(depsDirPath, name);
+
+  let useVersion = version;
+
+  if (deps[name] && fs.existsSync(specDirPath)) {
+    console.error(`Error: ${name} is already installed (v${deps[name].version}).`);
+    console.error(`Use \`opensdd update ${name}\` to update to the latest version.`);
+    process.exit(1);
+  }
+
+  // Handle stale entry (entry exists but directory missing)
+  if (deps[name] && !fs.existsSync(specDirPath)) {
+    console.log(
+      `Note: Found stale entry for ${name} in opensdd.json (directory missing). Re-installing.`
+    );
+    if (!useVersion) {
+      useVersion = deps[name].version;
+    }
+  }
+
+  // Step 3: Validate spec name
+  if (!isValidSpecName(name)) {
+    console.error(
+      `Error: Invalid spec name "${name}". Allowed characters: lowercase alphanumeric and hyphens only.`
+    );
+    process.exit(1);
+  }
+
+  // Step 4: Fetch index.json
+  let index;
+  try {
+    index = await fetchSpecIndex(registrySource, name);
+  } catch (err) {
+    console.error(`Error: Could not reach registry at ${registrySource}`);
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (!index) {
+    console.error(`Error: Spec "${name}" not found in registry.`);
+    try {
+      const available = await listRegistrySpecs(registrySource);
+      if (available.length > 0) {
+        console.error('\nAvailable specs:');
+        for (const s of available) {
+          console.error(`  ${s.name}`);
+        }
+      }
+    } catch {
+      // ignore listing errors
+    }
+    process.exit(1);
+  }
+
+  // Resolve version
+  const resolvedVersion = useVersion || index.latest;
+
+  // Check version exists
+  if (!index.versions || !index.versions[resolvedVersion]) {
+    console.error(`Error: Version ${resolvedVersion} not found for ${name}.`);
+    const availableVersions = Object.keys(index.versions || {});
+    if (availableVersions.length > 0) {
+      console.error(`Available versions: ${availableVersions.join(', ')}`);
+    }
+    process.exit(1);
+  }
+
+  // Step 5: Fetch manifest for the version
+  const specManifest = await fetchSpecManifest(registrySource, name, resolvedVersion);
+  if (!specManifest) {
+    console.error(`Error: Could not fetch manifest for ${name}@${resolvedVersion}`);
+    process.exit(1);
+  }
+
+  // Step 6: Fetch all spec files and write to deps dir
+  const files = await fetchSpecFiles(registrySource, name, resolvedVersion);
+  if (!files) {
+    console.error(`Error: Could not fetch spec files for ${name}@${resolvedVersion}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(specDirPath, { recursive: true });
+  for (const [fileName, content] of Object.entries(files)) {
+    // Invariant: opensdd install MUST NOT create a deviations.md file
+    if (fileName === 'deviations.md') continue;
+    fs.writeFileSync(path.join(specDirPath, fileName), content);
+  }
+
+  // Step 7: Add entry to opensdd.json
+  if (!manifest.dependencies) {
+    manifest.dependencies = {};
+  }
+
+  // Preserve consumer-managed fields from stale entry if re-installing
+  const existingEntry = deps[name];
+  manifest.dependencies[name] = {
+    version: resolvedVersion,
+    source: registrySource,
+    spec_format: specManifest.spec_format || '0.1.0',
+    implementation: existingEntry?.implementation ?? null,
+    tests: existingEntry?.tests ?? null,
+    has_deviations: existingEntry?.has_deviations ?? false,
+  };
+
+  writeManifest(manifestPath, manifest);
+
+  // Step 8: Check for missing dependencies
+  if (specManifest.dependencies && specManifest.dependencies.length > 0) {
+    const missing = specManifest.dependencies.filter(
+      (dep) => !manifest.dependencies[dep]
+    );
+    if (missing.length > 0) {
+      console.log('\nWarning: This spec has uninstalled dependencies:');
+      for (const dep of missing) {
+        console.log(`  Run \`opensdd install ${dep}\` to install ${dep}.`);
+      }
+    }
+  }
+
+  // Step 9: Print success
+  console.log(`Installed ${name} v${resolvedVersion} to ${depsDir}/${name}/`);
+  console.log(
+    `\nRun "implement the ${name} spec" in your agent to generate an implementation.`
+  );
+}

package/src/commands/list.js

@@ -0,0 +1,40 @@
+import { findManifestPath, readManifest } from '../lib/manifest.js';
+import { resolveRegistry, listRegistrySpecs } from '../lib/registry.js';
+
+export async function listCommand(options) {
+  // list doesn't require opensdd.json, but uses it for registry resolution if available
+  let manifest = null;
+  const manifestPath = findManifestPath(process.cwd());
+  if (manifestPath) {
+    try {
+      manifest = readManifest(manifestPath);
+    } catch {
+      // ignore — list works without opensdd.json
+    }
+  }
+
+  const registrySource = resolveRegistry(options, manifest);
+
+  let specs;
+  try {
+    specs = await listRegistrySpecs(registrySource);
+  } catch (err) {
+    console.error(`Error: Could not reach registry at ${registrySource}`);
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (specs.length === 0) {
+    console.log('No specs available in the registry.');
+    return;
+  }
+
+  console.log('Available specs:\n');
+
+  for (const spec of specs) {
+    const name = (spec.name || 'unknown').padEnd(17);
+    const version = `v${spec.latest || '0.0.0'}`.padEnd(8);
+    const desc = spec.description || '';
+    console.log(`  ${name}${version}${desc}`);
+  }
+}

package/src/commands/publish.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import readline from 'node:readline';
+import {
+  findManifestPath,
+  readManifest,
+  getSpecsDir,
+} from '../lib/manifest.js';
+import {
+  resolveRegistry,
+  isGitHubUrl,
+  parseGitHubUrl,
+  fetchSpecIndex,
+} from '../lib/registry.js';
+import { validateSpec } from '../lib/validation.js';
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export async function publishCommand(options) {
+  // Step 1: Verify opensdd.json
+  const manifestPath = findManifestPath(process.cwd());
+  if (!manifestPath) {
+    console.error('Error: OpenSDD not initialized. Run `opensdd init` to get started.');
+    process.exit(1);
+  }
+
+  const manifest = readManifest(manifestPath);
+  const projectRoot = path.dirname(manifestPath);
+  const registrySource = resolveRegistry(options, manifest);
+
+  // Step 2: Verify publish section
+  if (!manifest.publish) {
+    console.error('Error: No `publish` section in opensdd.json.');
+    console.error(
+      'Add a `publish` object with name, version, description, and spec_format to publish your spec.'
+    );
+    process.exit(1);
+  }
+
+  const { name, version, description, spec_format, dependencies } = manifest.publish;
+
+  if (!name || !version || !description || !spec_format) {
+    console.error(
+      'Error: `publish` section must include name, version, description, and spec_format.'
+    );
+    process.exit(1);
+  }
+
+  // Step 4: Verify spec.md exists
+  const specsDir = getSpecsDir(manifest);
+  const specsDirPath = path.join(projectRoot, specsDir);
+
+  if (!fs.existsSync(path.join(specsDirPath, 'spec.md'))) {
+    console.error(`Error: ${specsDir}/spec.md not found. Create your spec before publishing.`);
+    process.exit(1);
+  }
+
+  // Step 5: Validate spec
+  console.log(`Publishing ${name} v${version} to registry...\n`);
+
+  const validation = validateSpec(specsDirPath);
+  if (validation.errors.length > 0) {
+    console.error('  Validated spec            FAILED\n');
+    for (const err of validation.errors) {
+      console.error(`    - ${err}`);
+    }
+    process.exit(1);
+  }
+  console.log('  Validated spec            ok');
+
+  // Step 6: Verify registry is GitHub
+  if (!isGitHubUrl(registrySource)) {
+    console.error('Error: Publishing requires a GitHub registry URL.');
+    console.error(`Current registry: ${registrySource}`);
+    process.exit(1);
+  }
+
+  // Check git and gh CLI
+  if (!commandExists('git')) {
+    console.error('Error: git is not installed. Install git to publish specs.');
+    process.exit(1);
+  }
+  if (!commandExists('gh')) {
+    console.error('Error: GitHub CLI (gh) is not installed.');
+    console.error(
+      'Install it from https://cli.github.com/ and authenticate with `gh auth login`.'
+    );
+    process.exit(1);
+  }
+
+  // Step 7: Check if version already exists
+  try {
+    const index = await fetchSpecIndex(registrySource, name);
+    if (index && index.versions && index.versions[version]) {
+      console.error(
+        `\nError: Version ${version} already exists in the registry for ${name}.`
+      );
+      console.error('Bump the version in opensdd.json before publishing.');
+      process.exit(1);
+    }
+  } catch {
+    // Spec doesn't exist in registry yet — that's fine
+  }
+
+  // Step 9: Determine branch name
+  let branchName = options.branch;
+  if (!branchName) {
+    const answer = await prompt(
+      `Enter branch name for the registry PR (default: opensdd/${name}-v${version}): `
+    );
+    branchName = answer.trim() || `opensdd/${name}-v${version}`;
+  }
+
+  const { owner, repo } = parseGitHubUrl(registrySource);
+  const repoUrl = `https://github.com/${owner}/${repo}.git`;
+
+  // Step 10: Clone, create branch, add files, push, create PR
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opensdd-publish-'));
+
+  try {
+    // Clone
+    execSync(`git clone --depth 1 "${repoUrl}" "${tmpDir}"`, { stdio: 'pipe' });
+
+    // Create branch
+    execSync(`git checkout -b "${branchName}"`, { cwd: tmpDir, stdio: 'pipe' });
+    console.log(`  Created branch            ${branchName}`);
+
+    // Create registry entry directory
+    const registryDir = path.join(tmpDir, 'registry', name, version);
+    fs.mkdirSync(registryDir, { recursive: true });
+
+    // Copy all spec files first
+    copyDirRecursive(specsDirPath, registryDir);
+
+    // Build manifest.json from publish fields (written after copy so it takes precedence
+    // over any manifest.json that might exist in the specs directory)
+    const publishManifest = {
+      name,
+      version,
+      spec_format,
+      description,
+      dependencies: dependencies || [],
+    };
+    fs.writeFileSync(
+      path.join(registryDir, 'manifest.json'),
+      JSON.stringify(publishManifest, null, 2) + '\n'
+    );
+
+    console.log(`  Created registry entry    registry/${name}/${version}/`);
+
+    // Update (or create) index.json
+    const indexDir = path.join(tmpDir, 'registry', name);
+    fs.mkdirSync(indexDir, { recursive: true });
+    const indexPath = path.join(indexDir, 'index.json');
+
+    let indexData;
+    if (fs.existsSync(indexPath)) {
+      indexData = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+    } else {
+      indexData = { name, description, latest: version, versions: {} };
+    }
+    indexData.latest = version;
+    indexData.versions[version] = { spec_format };
+    fs.writeFileSync(indexPath, JSON.stringify(indexData, null, 2) + '\n');
+    console.log(`  Updated index.json        latest: ${version}`);
+
+    // Commit and push
+    execSync('git add -A', { cwd: tmpDir, stdio: 'pipe' });
+    execSync(`git commit -m "Add ${name} v${version}"`, { cwd: tmpDir, stdio: 'pipe' });
+    execSync(`git push -u origin "${branchName}"`, { cwd: tmpDir, stdio: 'pipe' });
+
+    // Create PR
+    const prTitle = `Add ${name} v${version}`;
+    const prBody = `Adds ${name} v${version} to the OpenSDD registry.\n\n${description}`;
+    const prOutput = execSync(
+      `gh pr create --repo "${owner}/${repo}" --title "${prTitle}" --body "${prBody}" --head "${branchName}"`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    ).trim();
+
+    console.log(`  Opened pull request       ${prOutput}`);
+  } catch (err) {
+    if (err.message.includes('Authentication') || err.message.includes('auth')) {
+      console.error('\nError: Git authentication failed.');
+      console.error('Run `gh auth login` to authenticate with GitHub.');
+    } else {
+      console.error(`\nError during publish: ${err.message}`);
+      if (err.stderr) {
+        console.error(err.stderr.toString());
+      }
+    }
+    process.exit(1);
+  } finally {
+    // Clean up temp directory
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+
+  console.log('\nPublished. Spec will be available after PR is merged.');
+}

package/src/commands/status.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  findManifestPath,
+  readManifest,
+  getSpecsDir,
+  getDepsDir,
+} from '../lib/manifest.js';
+
+export async function statusCommand() {
+  const manifestPath = findManifestPath(process.cwd());
+  if (!manifestPath) {
+    console.log('OpenSDD not initialized. Run `opensdd init` to get started.');
+    return;
+  }
+
+  const manifest = readManifest(manifestPath);
+  const projectRoot = path.dirname(manifestPath);
+  const specsDir = getSpecsDir(manifest);
+  const depsDir = getDepsDir(manifest);
+
+  let hasContent = false;
+
+  // Authored spec
+  if (manifest.publish) {
+    hasContent = true;
+    const pub = manifest.publish;
+    console.log('Authored spec:\n');
+    console.log(`  ${pub.name}  v${pub.version}  ${specsDir}/`);
+    console.log('');
+  }
+
+  // Dependencies
+  const deps = manifest.dependencies || {};
+  const depKeys = Object.keys(deps);
+
+  if (depKeys.length > 0) {
+    hasContent = true;
+    console.log('Installed dependencies:\n');
+
+    for (const depName of depKeys) {
+      const entry = deps[depName];
+      const namePad = depName.padEnd(16);
+      const version = `v${entry.version}`.padEnd(8);
+
+      let status;
+      if (entry.implementation) {
+        status = `implemented       ${entry.implementation}`;
+      } else {
+        status = 'not implemented';
+      }
+
+      // Check for deviations
+      let deviationInfo = '';
+      const deviationsPath = path.join(projectRoot, depsDir, depName, 'deviations.md');
+      if (entry.has_deviations || fs.existsSync(deviationsPath)) {
+        if (fs.existsSync(deviationsPath)) {
+          const content = fs.readFileSync(deviationsPath, 'utf-8');
+          const deviationCount = (content.match(/^## /gm) || []).length;
+          if (deviationCount > 0) {
+            deviationInfo = `    ${deviationCount} deviation${deviationCount > 1 ? 's' : ''}`;
+          }
+        }
+      }
+
+      console.log(`  ${namePad}${version}${status}${deviationInfo}`);
+    }
+  }
+
+  // Check for untracked spec directories
+  const depsDirPath = path.join(projectRoot, depsDir);
+  if (fs.existsSync(depsDirPath)) {
+    const dirEntries = fs.readdirSync(depsDirPath, { withFileTypes: true });
+    const untracked = dirEntries
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !deps[e.name])
+      .map((e) => e.name);
+
+    if (untracked.length > 0) {
+      console.log('\nWarning: Untracked spec directories:');
+      for (const u of untracked) {
+        console.log(`  ${depsDir}/${u}/`);
+      }
+    }
+  }
+
+  if (!hasContent) {
+    console.log(
+      'No specs found. Run `opensdd install <name>` to install a dependency or add a `publish` entry to opensdd.json.'
+    );
+  }
+}