openspec-sdd-e2e-kit 0.1.0

package/src/check.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  collectAssetFiles,
+  getPackageScriptDiff,
+  loadManifest,
+  parseCommonArgs,
+  summarizeByStatus,
+} from './lib.mjs';
+
+function printHelp() {
+  console.log(`Usage: node tools/sdd-e2e-kit/check.mjs [target] [--source <path>] [--json]
+
+Checks whether a target project has the SDD-E2E kit assets and package scripts.
+
+Arguments:
+  target    Project root to check. Defaults to current working directory.
+
+Options:
+  --source <path>  Source project root for kit assets. Defaults to this repository root.
+  --json    Print machine-readable JSON.
+  -h, --help
+`);
+}
+
+const options = parseCommonArgs(process.argv.slice(2));
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const manifest = loadManifest();
+const expectedFiles = collectAssetFiles(options.source, manifest);
+
+const assetResults = expectedFiles.map((relativePath) => {
+  const absolutePath = path.join(options.target, relativePath);
+  const exists = fs.existsSync(absolutePath);
+
+  return {
+    relativePath,
+    status: exists ? 'present' : 'missing',
+  };
+});
+
+const scriptResults = getPackageScriptDiff(options.target, manifest);
+const hasMissingAssets = assetResults.some((item) => item.status !== 'present');
+const hasScriptDrift = scriptResults.some((item) => item.status !== 'same');
+
+if (options.json) {
+  console.log(
+    JSON.stringify(
+      {
+        target: options.target,
+        assets: assetResults,
+        packageScripts: scriptResults,
+        ok: !hasMissingAssets && !hasScriptDrift,
+      },
+      null,
+      2,
+    ),
+  );
+} else {
+  console.log(`SDD-E2E kit check: ${options.target}`);
+  console.log(`Assets: ${JSON.stringify(summarizeByStatus(assetResults))}`);
+  console.log(`Package scripts: ${JSON.stringify(summarizeByStatus(scriptResults))}`);
+
+  const missingAssets = assetResults.filter((item) => item.status !== 'present');
+  if (missingAssets.length > 0) {
+    console.log('\nMissing assets:');
+    for (const item of missingAssets) {
+      console.log(`  - ${item.relativePath}`);
+    }
+  }
+
+  const scriptIssues = scriptResults.filter((item) => item.status !== 'same');
+  if (scriptIssues.length > 0) {
+    console.log('\nPackage script issues:');
+    for (const item of scriptIssues) {
+      console.log(`  - ${item.name}: ${item.status}`);
+    }
+  }
+}
+
+process.exit(hasMissingAssets || hasScriptDrift ? 1 : 0);

package/src/diff.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import {
+  collectAssetFiles,
+  collectTargetAssetFiles,
+  compareFile,
+  getPackageScriptDiff,
+  loadManifest,
+  parseCommonArgs,
+  summarizeByStatus,
+} from './lib.mjs';
+
+function printHelp() {
+  console.log(`Usage: node tools/sdd-e2e-kit/diff.mjs [target] [source] [--json]
+
+Compares target project assets with the kit source assets.
+
+Arguments:
+  target    Project root to compare. Defaults to current working directory.
+  source    Source project root for kit assets. Defaults to this repository root.
+
+Options:
+  --source <path>  Alternative source project root.
+  --json           Print machine-readable JSON.
+  -h, --help
+`);
+}
+
+const options = parseCommonArgs(process.argv.slice(2));
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const manifest = loadManifest();
+const sourceFiles = collectAssetFiles(options.source, manifest);
+const targetFiles = collectTargetAssetFiles(options.target, manifest);
+const sourceSet = new Set(sourceFiles);
+const targetSet = new Set(targetFiles);
+
+const fileResults = sourceFiles.map((relativePath) =>
+  compareFile(options.source, options.target, relativePath),
+);
+
+for (const relativePath of targetFiles) {
+  if (!sourceSet.has(relativePath)) {
+    fileResults.push({ status: 'extra', relativePath });
+  }
+}
+
+for (const relativePath of sourceFiles) {
+  if (!targetSet.has(relativePath)) {
+    const existing = fileResults.find((item) => item.relativePath === relativePath);
+    if (!existing) {
+      fileResults.push({ status: 'missing', relativePath });
+    }
+  }
+}
+
+const scriptResults = getPackageScriptDiff(options.target, manifest);
+const driftFiles = fileResults.filter((item) => item.status !== 'same');
+const driftScripts = scriptResults.filter((item) => item.status !== 'same');
+const ok = driftFiles.length === 0 && driftScripts.length === 0;
+
+if (options.json) {
+  console.log(
+    JSON.stringify(
+      {
+        source: options.source,
+        target: options.target,
+        files: fileResults,
+        packageScripts: scriptResults,
+        ok,
+      },
+      null,
+      2,
+    ),
+  );
+} else {
+  console.log(`SDD-E2E kit diff`);
+  console.log(`Source: ${options.source}`);
+  console.log(`Target: ${options.target}`);
+  console.log(`Files: ${JSON.stringify(summarizeByStatus(fileResults))}`);
+  console.log(`Package scripts: ${JSON.stringify(summarizeByStatus(scriptResults))}`);
+
+  if (driftFiles.length > 0) {
+    console.log('\nFile drift:');
+    for (const item of driftFiles.sort((a, b) => a.relativePath.localeCompare(b.relativePath))) {
+      console.log(`  - ${item.status}: ${item.relativePath}`);
+    }
+  }
+
+  if (driftScripts.length > 0) {
+    console.log('\nPackage script drift:');
+    for (const item of driftScripts) {
+      console.log(`  - ${item.status}: ${item.name}`);
+    }
+  }
+}
+
+process.exit(ok ? 0 : 1);

package/src/install.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  collectAssetFiles,
+  compareFile,
+  loadManifest,
+  parseCommonArgs,
+  readPackageJson,
+  summarizeByStatus,
+} from './lib.mjs';
+
+function printHelp() {
+  console.log(`Usage: node tools/sdd-e2e-kit/install.mjs [target] [--source <path>] [--dry-run] [--force]
+
+Installs the SDD-E2E kit assets into a target project.
+
+Arguments:
+  target    Project root to install into. Defaults to current working directory.
+
+Options:
+  --source <path>  Source project root for kit assets. Defaults to this repository root.
+  --dry-run        Print planned writes without changing files.
+  --force          Overwrite changed target files and conflicting package scripts.
+  -h, --help
+`);
+}
+
+function copyFile(sourcePath, targetPath, dryRun) {
+  if (dryRun) {
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+}
+
+function installPackageScripts(targetRoot, manifest, options) {
+  const { packagePath, data } = readPackageJson(targetRoot);
+
+  if (!data) {
+    return {
+      changed: false,
+      conflicts: Object.keys(manifest.packageScripts),
+      results: Object.keys(manifest.packageScripts).map((name) => ({
+        name,
+        status: 'package-missing',
+      })),
+    };
+  }
+
+  const next = { ...data, scripts: { ...(data.scripts ?? {}) } };
+  const results = [];
+  let changed = false;
+  const conflicts = [];
+
+  for (const [name, expected] of Object.entries(manifest.packageScripts)) {
+    const actual = next.scripts[name];
+
+    if (actual === expected) {
+      results.push({ name, status: 'same' });
+      continue;
+    }
+
+    if (actual && actual !== expected && !options.force) {
+      conflicts.push(name);
+      results.push({ name, status: 'conflict' });
+      continue;
+    }
+
+    next.scripts[name] = expected;
+    changed = true;
+    results.push({ name, status: actual ? 'overwritten' : 'created' });
+  }
+
+  if (changed && !options.dryRun) {
+    fs.writeFileSync(packagePath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+
+  return { changed, conflicts, results };
+}
+
+const options = parseCommonArgs(process.argv.slice(2));
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const manifest = loadManifest();
+const files = collectAssetFiles(options.source, manifest);
+const fileResults = [];
+const conflicts = [];
+const sourceMissing = [];
+
+for (const relativePath of files) {
+  const sourcePath = path.join(options.source, relativePath);
+  const targetPath = path.join(options.target, relativePath);
+  const comparison = compareFile(options.source, options.target, relativePath);
+
+  if (comparison.status === 'source-missing') {
+    sourceMissing.push(relativePath);
+    fileResults.push(comparison);
+    continue;
+  }
+
+  if (comparison.status === 'same') {
+    fileResults.push(comparison);
+    continue;
+  }
+
+  if (comparison.status === 'changed' && !options.force) {
+    conflicts.push(relativePath);
+    fileResults.push({ status: 'conflict', relativePath });
+    continue;
+  }
+
+  copyFile(sourcePath, targetPath, options.dryRun);
+  fileResults.push({
+    status: comparison.status === 'missing' ? 'created' : 'overwritten',
+    relativePath,
+  });
+}
+
+const packageResult = installPackageScripts(options.target, manifest, options);
+const hasProblems = sourceMissing.length > 0 || conflicts.length > 0 || packageResult.conflicts.length > 0;
+
+console.log(`SDD-E2E kit install${options.dryRun ? ' (dry run)' : ''}`);
+console.log(`Source: ${options.source}`);
+console.log(`Target: ${options.target}`);
+console.log(`Files: ${JSON.stringify(summarizeByStatus(fileResults))}`);
+console.log(`Package scripts: ${JSON.stringify(summarizeByStatus(packageResult.results))}`);
+
+if (sourceMissing.length > 0) {
+  console.log('\nSource assets missing:');
+  for (const item of sourceMissing) {
+    console.log(`  - ${item}`);
+  }
+}
+
+if (conflicts.length > 0) {
+  console.log('\nFile conflicts, not overwritten:');
+  for (const item of conflicts) {
+    console.log(`  - ${item}`);
+  }
+}
+
+if (packageResult.conflicts.length > 0) {
+  console.log('\nPackage script conflicts, not overwritten:');
+  for (const item of packageResult.conflicts) {
+    console.log(`  - ${item}`);
+  }
+}
+
+if (hasProblems) {
+  console.log('\nUse --force only after reviewing conflicts.');
+}
+
+process.exit(hasProblems ? 1 : 0);

package/src/lib.mjs

@@ -0,0 +1,221 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const kitDir = path.dirname(fileURLToPath(import.meta.url));
+export const repoRoot = path.resolve(kitDir, '..');
+export const defaultSourceRoot = path.join(repoRoot, 'kit');
+
+const ignoredFileNames = new Set(['.DS_Store']);
+
+export function loadManifest(sourceRoot = defaultSourceRoot) {
+  const manifestPath = path.join(sourceRoot, 'manifest.json');
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+export function toPosix(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+export function resolveRoot(input = process.cwd()) {
+  return path.resolve(input);
+}
+
+export function walkFiles(root) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (ignoredFileNames.has(entry.name)) {
+      continue;
+    }
+
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files.sort();
+}
+
+export function collectAssetFiles(root, manifest) {
+  const files = [];
+
+  for (const asset of manifest.assets) {
+    const assetPath = path.join(root, asset.path);
+
+    if (asset.type === 'file') {
+      files.push(asset.path);
+      continue;
+    }
+
+    if (asset.type === 'directory') {
+      for (const file of walkFiles(assetPath)) {
+        files.push(toPosix(path.relative(root, file)));
+      }
+      continue;
+    }
+
+    throw new Error(`Unsupported asset type: ${asset.type}`);
+  }
+
+  return [...new Set(files)].sort();
+}
+
+export function collectTargetAssetFiles(root, manifest) {
+  return collectAssetFiles(root, manifest);
+}
+
+export function hashFile(filePath) {
+  const hash = createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+export function compareFile(sourceRoot, targetRoot, relativePath) {
+  const sourcePath = path.join(sourceRoot, relativePath);
+  const targetPath = path.join(targetRoot, relativePath);
+
+  if (!fs.existsSync(sourcePath)) {
+    return { status: 'source-missing', relativePath };
+  }
+
+  if (!fs.existsSync(targetPath)) {
+    return { status: 'missing', relativePath };
+  }
+
+  const sourceHash = hashFile(sourcePath);
+  const targetHash = hashFile(targetPath);
+
+  if (sourceHash === targetHash) {
+    return { status: 'same', relativePath };
+  }
+
+  return { status: 'changed', relativePath };
+}
+
+export function readPackageJson(root) {
+  const packagePath = path.join(root, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return { packagePath, data: null };
+  }
+
+  return {
+    packagePath,
+    data: JSON.parse(fs.readFileSync(packagePath, 'utf8')),
+  };
+}
+
+export function getPackageScriptDiff(root, manifest) {
+  const { data } = readPackageJson(root);
+
+  if (!data) {
+    return Object.entries(manifest.packageScripts).map(([name, expected]) => ({
+      name,
+      expected,
+      actual: null,
+      status: 'package-missing',
+    }));
+  }
+
+  const scripts = data.scripts ?? {};
+  return Object.entries(manifest.packageScripts).map(([name, expected]) => {
+    const actual = scripts[name] ?? null;
+
+    if (actual === null) {
+      return { name, expected, actual, status: 'missing' };
+    }
+
+    if (actual !== expected) {
+      return { name, expected, actual, status: 'changed' };
+    }
+
+    return { name, expected, actual, status: 'same' };
+  });
+}
+
+export function printRows(rows, emptyMessage) {
+  if (rows.length === 0) {
+    console.log(emptyMessage);
+    return;
+  }
+
+  for (const row of rows) {
+    console.log(row);
+  }
+}
+
+export function parseCommonArgs(argv) {
+  const options = {
+    dryRun: false,
+    force: false,
+    json: false,
+    source: defaultSourceRoot,
+    target: process.cwd(),
+  };
+
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (arg === '--source') {
+      index += 1;
+      if (!argv[index]) {
+        throw new Error('--source requires a path');
+      }
+      options.source = argv[index];
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional[0]) {
+    options.target = positional[0];
+  }
+
+  if (positional[1]) {
+    options.source = positional[1];
+  }
+
+  options.target = resolveRoot(options.target);
+  options.source = resolveRoot(options.source);
+
+  return options;
+}
+
+export function summarizeByStatus(results) {
+  return results.reduce((summary, item) => {
+    summary[item.status] = (summary[item.status] ?? 0) + 1;
+    return summary;
+  }, {});
+}