opensdd 0.1.0

package/src/commands/update.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createPatch } from 'diff';
+import {
+  findManifestPath,
+  readManifest,
+  getDepsDir,
+} from '../lib/manifest.js';
+import {
+  resolveRegistry,
+  fetchSpecIndex,
+  fetchSpecManifest,
+  fetchSpecFiles,
+} from '../lib/registry.js';
+
+export async function updateCommand(name, options) {
+  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);
+  const deps = manifest.dependencies || {};
+
+  // Determine which specs to update
+  let specsToUpdate;
+  if (name) {
+    if (!deps[name]) {
+      console.error(`Error: ${name} is not installed. Run \`opensdd install ${name}\` first.`);
+      process.exit(1);
+    }
+    specsToUpdate = [name];
+  } else {
+    specsToUpdate = Object.keys(deps);
+    if (specsToUpdate.length === 0) {
+      console.log('No dependencies installed.');
+      return;
+    }
+  }
+
+  const results = [];
+
+  for (const specName of specsToUpdate) {
+    const entry = deps[specName];
+    const specDir = path.join(depsDirPath, specName);
+
+    // Fetch latest from registry
+    let index;
+    try {
+      index = await fetchSpecIndex(registrySource, specName);
+    } catch (err) {
+      console.error(`Error: Could not reach registry for ${specName}: ${err.message}`);
+      process.exit(1);
+    }
+
+    if (!index) {
+      console.warn(
+        `Warning: ${specName} is no longer available in the registry. Local files preserved.`
+      );
+      results.push({ name: specName, status: 'not_found' });
+      continue;
+    }
+
+    const latestVersion = index.latest;
+
+    if (latestVersion === entry.version) {
+      results.push({ name: specName, status: 'up_to_date', version: entry.version });
+      continue;
+    }
+
+    // Fetch new version files
+    const newManifest = await fetchSpecManifest(registrySource, specName, latestVersion);
+    const newFiles = await fetchSpecFiles(registrySource, specName, latestVersion);
+
+    if (!newManifest || !newFiles) {
+      console.error(`Error: Could not fetch ${specName}@${latestVersion} from registry.`);
+      process.exit(1);
+    }
+
+    // Step d: Compute unified diffs of all spec-owned files before overwriting
+    const diffs = {};
+    const changedFiles = [];
+
+    for (const [fileName, newContent] of Object.entries(newFiles)) {
+      // deviations.md is consumer-owned — skip it in diffs and overwrites
+      if (fileName === 'deviations.md') continue;
+
+      const existingPath = path.join(specDir, fileName);
+      const oldContent = fs.existsSync(existingPath)
+        ? fs.readFileSync(existingPath, 'utf-8')
+        : '';
+
+      if (oldContent !== newContent) {
+        diffs[fileName] = createPatch(fileName, oldContent, newContent);
+        changedFiles.push(fileName);
+      }
+    }
+
+    // Step e: Overwrite all spec-owned files
+    fs.mkdirSync(specDir, { recursive: true });
+    for (const [fileName, content] of Object.entries(newFiles)) {
+      // Step f: MUST NOT overwrite deviations.md
+      if (fileName === 'deviations.md') continue;
+      fs.writeFileSync(path.join(specDir, fileName), content);
+    }
+
+    // Step g: Create staging directory
+    const updatesDir = path.join(depsDirPath, '.updates', specName);
+    const wasReplaced = fs.existsSync(updatesDir);
+    fs.mkdirSync(updatesDir, { recursive: true });
+
+    // Write changeset.md
+    const specFormatOld = entry.spec_format || '0.1.0';
+    const specFormatNew = newManifest.spec_format || '0.1.0';
+    const specFormatChange =
+      specFormatOld === specFormatNew
+        ? 'unchanged'
+        : `${specFormatOld} \u2192 ${specFormatNew}`;
+
+    let changeset = `# Changeset: ${specName}\n\n`;
+    changeset += `**Previous version:** ${entry.version}\n`;
+    changeset += `**New version:** ${latestVersion}\n`;
+    changeset += `**Spec-format:** ${specFormatChange}\n`;
+    changeset += `**Date:** ${new Date().toISOString().split('T')[0]}\n\n`;
+    changeset += '## Changed Files\n';
+
+    for (const [fileName, diff] of Object.entries(diffs)) {
+      changeset += `\n### ${fileName}\n\n\`\`\`diff\n${diff}\`\`\`\n`;
+    }
+
+    if (changedFiles.length === 0) {
+      changeset += '\nNo file content changes (metadata only).\n';
+    }
+
+    fs.writeFileSync(path.join(updatesDir, 'changeset.md'), changeset);
+
+    // Write manifest.json for staging
+    const stageManifest = {
+      name: specName,
+      previous_version: entry.version,
+      version: latestVersion,
+      source: registrySource,
+      spec_format: newManifest.spec_format || '0.1.0',
+    };
+
+    fs.writeFileSync(
+      path.join(updatesDir, 'manifest.json'),
+      JSON.stringify(stageManifest, null, 2) + '\n'
+    );
+
+    results.push({
+      name: specName,
+      status: 'updated',
+      oldVersion: entry.version,
+      newVersion: latestVersion,
+      changedFiles,
+      replaced: wasReplaced,
+    });
+  }
+
+  // Print output
+  if (name) {
+    // Single spec output
+    const result = results[0];
+    if (result.status === 'up_to_date') {
+      console.log(`${result.name} v${result.version} is already up to date.`);
+      return;
+    }
+    if (result.status === 'not_found') {
+      return; // Warning already printed
+    }
+
+    console.log(`Updated ${result.name}: v${result.oldVersion} -> v${result.newVersion}`);
+    if (result.replaced) {
+      console.log('  (replaced existing pending update)');
+    }
+
+    if (result.changedFiles.length > 0) {
+      console.log('\nChanged files:');
+      for (const f of result.changedFiles) {
+        console.log(`  ${f.padEnd(16)}updated`);
+      }
+    }
+
+    // Check for deviations.md
+    const deviationsPath = path.join(depsDirPath, result.name, 'deviations.md');
+    if (fs.existsSync(deviationsPath)) {
+      console.log('\nPreserved:');
+      console.log('  deviations.md (consumer-owned, not modified)');
+    }
+
+    console.log('\nStaged update:');
+    console.log(`  ${depsDir}/.updates/${result.name}/changeset.md`);
+    console.log(`  ${depsDir}/.updates/${result.name}/manifest.json`);
+    console.log(`\nRun "process the ${result.name} spec update" in your agent.`);
+    console.log(`After confirming, run: opensdd update apply ${result.name}`);
+  } else {
+    // All specs output
+    const updated = results.filter((r) => r.status === 'updated');
+
+    console.log(`Updated ${updated.length} of ${results.length} installed specs:\n`);
+
+    for (const r of results) {
+      const namePad = r.name.padEnd(16);
+      if (r.status === 'updated') {
+        console.log(`  ${namePad}v${r.oldVersion} -> v${r.newVersion}   staged`);
+      } else if (r.status === 'up_to_date') {
+        console.log(`  ${namePad}v${r.version}             already up to date`);
+      } else if (r.status === 'not_found') {
+        console.log(`  ${namePad}not found in registry`);
+      }
+    }
+
+    if (updated.length > 0) {
+      console.log('\nRun "process spec updates" in your agent.');
+      console.log('After confirming each update, run:');
+      for (const r of updated) {
+        console.log(`  opensdd update apply ${r.name}`);
+      }
+    }
+  }
+}

package/src/commands/updateApply.js

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import {
+  findManifestPath,
+  readManifest,
+  writeManifest,
+  getDepsDir,
+} from '../lib/manifest.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);
+    });
+  });
+}
+
+export async function updateApplyCommand(name) {
+  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 updatesDir = path.join(projectRoot, depsDir, '.updates');
+
+  // Determine which updates to apply
+  let pendingNames;
+  if (name) {
+    const updateDir = path.join(updatesDir, name);
+    if (!fs.existsSync(updateDir)) {
+      console.error(`Error: No pending update for ${name}.`);
+      process.exit(1);
+    }
+    pendingNames = [name];
+  } else {
+    if (!fs.existsSync(updatesDir)) {
+      console.log('No pending updates.');
+      process.exit(0);
+    }
+    const entries = fs.readdirSync(updatesDir, { withFileTypes: true });
+    pendingNames = entries
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name);
+    if (pendingNames.length === 0) {
+      console.log('No pending updates.');
+      process.exit(0);
+    }
+  }
+
+  // Print warning
+  console.log('\u26A0 This will finalize the update in opensdd.json.');
+  console.log('  Only proceed if you have confirmed that all spec changes');
+  console.log('  have been implemented and tests pass.\n');
+
+  // Prompt for confirmation
+  let confirmMsg;
+  if (pendingNames.length === 1) {
+    const updateManifestPath = path.join(updatesDir, pendingNames[0], 'manifest.json');
+    const updateManifest = JSON.parse(fs.readFileSync(updateManifestPath, 'utf-8'));
+    confirmMsg = `Apply update for ${pendingNames[0]} v${updateManifest.previous_version} -> v${updateManifest.version}? (y/n) `;
+  } else {
+    confirmMsg = `Apply ${pendingNames.length} pending updates? (y/n) `;
+  }
+
+  const answer = await prompt(confirmMsg);
+  if (answer.toLowerCase() !== 'y') {
+    process.exit(0);
+  }
+
+  console.log('');
+
+  // Apply each update
+  const applied = [];
+  for (const specName of pendingNames) {
+    const updateDir = path.join(updatesDir, specName);
+    const manifestJsonPath = path.join(updateDir, 'manifest.json');
+
+    if (!fs.existsSync(manifestJsonPath)) {
+      console.error(`Error: Missing manifest.json for ${specName} update.`);
+      process.exit(1);
+    }
+
+    let updateManifest;
+    try {
+      updateManifest = JSON.parse(fs.readFileSync(manifestJsonPath, 'utf-8'));
+    } catch (err) {
+      console.error(`Error: Malformed manifest.json for ${specName}: ${err.message}`);
+      process.exit(1);
+    }
+
+    // Update opensdd.json dependency entry, preserving consumer-managed fields
+    if (!manifest.dependencies) manifest.dependencies = {};
+    const existing = manifest.dependencies[specName] || {};
+
+    manifest.dependencies[specName] = {
+      ...existing,
+      version: updateManifest.version,
+      source: updateManifest.source,
+      spec_format: updateManifest.spec_format,
+      // Preserve consumer-managed fields
+      implementation:
+        existing.implementation !== undefined ? existing.implementation : null,
+      tests: existing.tests !== undefined ? existing.tests : null,
+      has_deviations:
+        existing.has_deviations !== undefined ? existing.has_deviations : false,
+    };
+
+    // Delete staging directory
+    fs.rmSync(updateDir, { recursive: true, force: true });
+
+    applied.push({
+      name: specName,
+      oldVersion: updateManifest.previous_version,
+      newVersion: updateManifest.version,
+    });
+  }
+
+  // Write updated manifest
+  writeManifest(manifestPath, manifest);
+
+  // Clean up .updates/ directory if empty
+  if (fs.existsSync(updatesDir)) {
+    const remaining = fs.readdirSync(updatesDir);
+    if (remaining.length === 0) {
+      fs.rmSync(updatesDir, { recursive: true, force: true });
+    }
+  }
+
+  // Print output
+  if (applied.length === 1) {
+    const a = applied[0];
+    console.log(`Applied update for ${a.name}: v${a.oldVersion} -> v${a.newVersion}\n`);
+    console.log('  opensdd.json    updated');
+    console.log('  staged files    cleaned up');
+  } else {
+    console.log(`Applied ${applied.length} updates:\n`);
+    for (const a of applied) {
+      console.log(`  ${a.name.padEnd(16)}v${a.oldVersion} -> v${a.newVersion}   applied`);
+    }
+    console.log('\nopensdd.json updated.');
+  }
+}

package/src/commands/validate.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateSpec } from '../lib/validation.js';
+
+export async function validateCommand(specPath) {
+  let targetDir;
+
+  if (specPath) {
+    targetDir = path.resolve(specPath);
+  } else {
+    targetDir = path.join(process.cwd(), 'opensdd');
+  }
+
+  if (!fs.existsSync(targetDir)) {
+    if (!specPath) {
+      console.error(
+        'No spec directory found. Provide a path or run from a directory containing `opensdd/`.'
+      );
+    } else {
+      console.error(`Error: Path does not exist: ${specPath}`);
+    }
+    process.exit(1);
+  }
+
+  if (!fs.statSync(targetDir).isDirectory()) {
+    console.error(`Error: ${specPath} is not a directory.`);
+    process.exit(1);
+  }
+
+  const result = validateSpec(targetDir);
+
+  // Determine name and version for display
+  let displayName = path.basename(targetDir);
+  let displayVersion = '';
+
+  if (result.manifest) {
+    displayName = result.manifest.name || displayName;
+    displayVersion = result.manifest.version ? ` v${result.manifest.version}` : '';
+  }
+
+  if (result.errors.length > 0) {
+    console.log(`Validation failed for ${displayName}\n`);
+  } else {
+    console.log(`Validated ${displayName}${displayVersion}\n`);
+  }
+
+  // spec.md structure
+  if (result.specErrors.length > 0) {
+    console.log('  spec.md structure     error');
+    for (const err of result.specErrors) {
+      console.log(`    - ${err}`);
+    }
+  } else if (result.specWarnings.length > 0) {
+    console.log(
+      `  spec.md structure     ${result.specWarnings.length} warning${result.specWarnings.length > 1 ? 's' : ''}`
+    );
+    for (const w of result.specWarnings) {
+      console.log(`    - ${w}`);
+    }
+  } else {
+    console.log('  spec.md structure     ok');
+  }
+
+  // manifest.json
+  if (result.manifestExists) {
+    if (result.manifestErrors.length > 0) {
+      console.log('  manifest.json         error');
+      for (const err of result.manifestErrors) {
+        console.log(`    - ${err}`);
+      }
+    } else {
+      console.log('  manifest.json         ok');
+    }
+  }
+
+  // deviations.md check
+  if (result.hasDeviations) {
+    console.log('  deviations.md         found (should not be in publishable spec)');
+  } else {
+    console.log('  no deviations.md      ok');
+  }
+
+  // Summary
+  console.log('');
+  if (result.errors.length > 0) {
+    console.log(
+      `${result.errors.length} error${result.errors.length > 1 ? 's' : ''}. Fix errors before publishing.`
+    );
+    process.exit(1);
+  } else if (result.warnings.length > 0) {
+    console.log('Valid with warnings. Review warnings before publishing.');
+  } else {
+    console.log('Valid. Ready for publishing to registry.');
+  }
+}

package/src/index.js

@@ -0,0 +1,126 @@
+import { initCommand } from './commands/init.js';
+import { listCommand } from './commands/list.js';
+import { installCommand } from './commands/install.js';
+import { updateCommand } from './commands/update.js';
+import { updateApplyCommand } from './commands/updateApply.js';
+import { publishCommand } from './commands/publish.js';
+import { statusCommand } from './commands/status.js';
+import { validateCommand } from './commands/validate.js';
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[key] = argv[i + 1];
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  return { flags, positional };
+}
+
+function printHelp() {
+  console.log(`opensdd v0.1.0 - Open Spec-Driven Development CLI
+
+Usage: opensdd <command> [options]
+
+Commands:
+  init                    Initialize OpenSDD in the current project
+  list                    List specs available in the registry
+  install <name> [ver]    Install a spec from the registry
+  update [name]           Fetch latest version of dependency specs
+  update apply [name]     Apply a staged update to opensdd.json
+  publish                 Publish an authored spec to the registry
+  status                  Show status of authored and installed specs
+  validate [path]         Validate a spec directory
+
+Options:
+  --registry <url>        Alternative registry source
+  --branch <name>         Branch name for publish PR
+  --version               Show version
+  --help                  Show help`);
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const command = rawArgs[0];
+
+  try {
+    switch (command) {
+      case 'init':
+        await initCommand();
+        break;
+
+      case 'list': {
+        const { flags } = parseArgs(rawArgs.slice(1));
+        await listCommand({ registry: flags.registry });
+        break;
+      }
+
+      case 'install': {
+        const { flags, positional } = parseArgs(rawArgs.slice(1));
+        if (!positional[0]) {
+          console.error('Usage: opensdd install <name> [version]');
+          process.exit(1);
+        }
+        await installCommand(positional[0], positional[1], { registry: flags.registry });
+        break;
+      }
+
+      case 'update': {
+        if (rawArgs[1] === 'apply') {
+          const { positional } = parseArgs(rawArgs.slice(2));
+          await updateApplyCommand(positional[0]);
+        } else {
+          const { flags, positional } = parseArgs(rawArgs.slice(1));
+          await updateCommand(positional[0], { registry: flags.registry });
+        }
+        break;
+      }
+
+      case 'publish': {
+        const { flags } = parseArgs(rawArgs.slice(1));
+        await publishCommand({ branch: flags.branch, registry: flags.registry });
+        break;
+      }
+
+      case 'status':
+        await statusCommand();
+        break;
+
+      case 'validate': {
+        const { positional } = parseArgs(rawArgs.slice(1));
+        await validateCommand(positional[0]);
+        break;
+      }
+
+      case '--version':
+      case '-v':
+        console.log('0.1.0');
+        break;
+
+      case '--help':
+      case '-h':
+      case undefined:
+        printHelp();
+        break;
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/lib/manifest.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Search upward from startDir for opensdd.json, stopping at filesystem root.
+ * Returns the absolute path to opensdd.json, or null if not found.
+ */
+export function findManifestPath(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(dir, 'opensdd.json');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function readManifest(manifestPath) {
+  const content = fs.readFileSync(manifestPath, 'utf-8');
+  try {
+    return JSON.parse(content);
+  } catch (err) {
+    throw new Error(`opensdd.json is malformed JSON: ${err.message}`);
+  }
+}
+
+export function writeManifest(manifestPath, data) {
+  fs.writeFileSync(manifestPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+export function getSpecsDir(manifest) {
+  return manifest.specs_dir || 'opensdd';
+}
+
+export function getDepsDir(manifest) {
+  return manifest.deps_dir || '.opensdd.deps';
+}