kld-sdd 2.6.7 → 2.6.9

package/skywalk-sdd/ontology/sdd-config.cjs

@@ -0,0 +1,335 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const CODES = {
+  MISSING: 'SDD_YAML_MISSING',
+  FORMAT_INVALID: 'SDD_YAML_FORMAT_INVALID',
+  SPEC_PATH_MISSING: 'SDD_SPEC_PATH_MISSING',
+  SPEC_PATH_INVALID: 'SDD_SPEC_PATH_INVALID',
+  REMOTE_MISMATCH: 'SDD_SPEC_REMOTE_MISMATCH',
+};
+
+const LAYOUTS = {
+  MULTI: 'multi',
+  MONO: 'mono',
+};
+
+function stripYamlQuotes(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (
+    (text.startsWith('"') && text.endsWith('"')) ||
+    (text.startsWith("'") && text.endsWith("'"))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+/**
+ * Minimal parser for .sdd.yaml，两种布局：
+ *
+ * 多仓（默认）：spec 是另一个 clone
+ *   version: 1
+ *   spec_repository: git@host:group/repo.git
+ *
+ * 单仓：openspec 与代码同仓，无外部 spec 可指
+ *   version: 1
+ *   layout: mono
+ */
+function parseSddYaml(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  let version = null;
+  let specRepository = null;
+  let layout = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+
+    const versionMatch = /^version:\s*(\d+)\s*$/.exec(line);
+    if (versionMatch) {
+      version = Number(versionMatch[1]);
+      continue;
+    }
+
+    const layoutMatch = /^layout:\s*(.+?)\s*$/.exec(line);
+    if (layoutMatch) {
+      const value = stripYamlQuotes(layoutMatch[1]).toLowerCase();
+      if (value !== LAYOUTS.MONO && value !== LAYOUTS.MULTI) {
+        return {
+          ok: false,
+          code: CODES.FORMAT_INVALID,
+          message: `.sdd.yaml layout 只能是 mono 或 multi，实际: ${value}`,
+        };
+      }
+      layout = value;
+      continue;
+    }
+
+    const repoMatch = /^spec_repository:\s*(.+?)\s*$/.exec(line);
+    if (repoMatch) {
+      specRepository = stripYamlQuotes(repoMatch[1]);
+      continue;
+    }
+
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `.sdd.yaml 第 ${index + 1} 行无法解析: ${raw}`,
+    };
+  }
+
+  if (version == null) {
+    return { ok: false, code: CODES.FORMAT_INVALID, message: '.sdd.yaml 缺少 version' };
+  }
+  if (version !== 1) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `不支持的 .sdd.yaml version: ${version}`,
+    };
+  }
+  const resolvedLayout = layout || LAYOUTS.MULTI;
+  // 单仓没有外部 spec 仓库可指，spec_repository 可省略
+  if (resolvedLayout === LAYOUTS.MULTI && !specRepository) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: '.sdd.yaml 缺少 spec_repository（单仓请写 layout: mono）',
+    };
+  }
+
+  return {
+    ok: true,
+    version,
+    layout: resolvedLayout,
+    spec_repository: specRepository || '',
+  };
+}
+
+function loadSddYaml(codeRepoRoot) {
+  const filePath = path.join(codeRepoRoot, '.sdd.yaml');
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      code: CODES.MISSING,
+      message: `.sdd.yaml 不存在: ${filePath}`,
+      path: filePath,
+    };
+  }
+  const parsed = parseSddYaml(fs.readFileSync(filePath, 'utf8'));
+  if (!parsed.ok) return { ...parsed, path: filePath };
+  return { ...parsed, path: filePath };
+}
+
+/** 单仓声明：.sdd.yaml 显式写了 layout: mono */
+function isMonoLayout(repoRoot) {
+  const loaded = loadSddYaml(repoRoot);
+  return loaded.ok && loaded.layout === LAYOUTS.MONO;
+}
+
+function gitConfig(cwd, key) {
+  try {
+    return execFileSync('git', ['config', '--local', '--get', key], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitRemoteUrl(cwd, remote = 'origin') {
+  try {
+    return execFileSync('git', ['remote', 'get-url', remote], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function normalizeRemoteUrl(url) {
+  if (!url) return '';
+  let value = String(url).trim().replace(/\\/g, '/');
+  value = value.replace(/\.git$/i, '');
+  const sshMatch = /^git@([^:]+):(.+)$/.exec(value);
+  if (sshMatch) {
+    return `${sshMatch[1].toLowerCase()}/${sshMatch[2].replace(/^\/+/, '').toLowerCase()}`;
+  }
+  const schemeMatch = /^https?:\/\/([^/]+)\/(.+)$/i.exec(value);
+  if (schemeMatch) {
+    return `${schemeMatch[1].toLowerCase()}/${schemeMatch[2].replace(/^\/+/, '').toLowerCase()}`;
+  }
+  return value.toLowerCase();
+}
+
+function remotesMatch(left, right) {
+  const a = normalizeRemoteUrl(left);
+  const b = normalizeRemoteUrl(right);
+  return Boolean(a && b && a === b);
+}
+
+function resolveSpecPath(codeRepoRoot, env = process.env) {
+  const fromEnv = env.KLD_SDD_SPEC_PATH && String(env.KLD_SDD_SPEC_PATH).trim();
+  if (fromEnv) {
+    return {
+      ok: true,
+      source: 'env',
+      path: path.resolve(fromEnv),
+    };
+  }
+
+  const fromGit = gitConfig(codeRepoRoot, 'sdd.specPath');
+  if (fromGit) {
+    return {
+      ok: true,
+      source: 'git-config',
+      path: path.resolve(fromGit),
+    };
+  }
+
+  return {
+    ok: false,
+    code: CODES.SPEC_PATH_MISSING,
+    message: '未找到 spec clone 路径。请设置 KLD_SDD_SPEC_PATH 或 git config --local sdd.specPath <path>',
+  };
+}
+
+function validateSpecPath(specPath) {
+  if (!specPath || !fs.existsSync(specPath)) {
+    return {
+      ok: false,
+      code: CODES.SPEC_PATH_INVALID,
+      message: `spec 路径不存在: ${specPath}`,
+    };
+  }
+  if (!fs.existsSync(path.join(specPath, '.git'))) {
+    return {
+      ok: false,
+      code: CODES.SPEC_PATH_INVALID,
+      message: `spec 路径不是 Git 仓库: ${specPath}`,
+    };
+  }
+  return { ok: true, path: specPath };
+}
+
+function setSpecPath(codeRepoRoot, specPath) {
+  const absolute = path.resolve(specPath);
+  const valid = validateSpecPath(absolute);
+  if (!valid.ok) return valid;
+  execFileSync('git', ['config', '--local', 'sdd.specPath', absolute], {
+    cwd: codeRepoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return { ok: true, path: absolute };
+}
+
+function resolveCodeRepoContext(codeRepoRoot, env = process.env) {
+  const sddYaml = loadSddYaml(codeRepoRoot);
+  const specPathResult = resolveSpecPath(codeRepoRoot, env);
+  if (!specPathResult.ok) {
+    return {
+      ok: false,
+      code: specPathResult.code,
+      message: specPathResult.message,
+      sddYaml,
+      specPath: null,
+    };
+  }
+
+  const pathValid = validateSpecPath(specPathResult.path);
+  if (!pathValid.ok) {
+    return {
+      ok: false,
+      code: pathValid.code,
+      message: pathValid.message,
+      sddYaml,
+      specPath: specPathResult.path,
+      specPathSource: specPathResult.source,
+    };
+  }
+
+  const result = {
+    ok: true,
+    sddYaml,
+    specPath: pathValid.path,
+    specPathSource: specPathResult.source,
+    specRemote: gitRemoteUrl(pathValid.path),
+  };
+
+  if (sddYaml.ok && result.specRemote) {
+    result.remoteMatches = remotesMatch(sddYaml.spec_repository, result.specRemote);
+    if (!result.remoteMatches) {
+      result.ok = false;
+      result.code = CODES.REMOTE_MISMATCH;
+      result.message = `.sdd.yaml spec_repository 与本地 spec remote 不一致: ${sddYaml.spec_repository} vs ${result.specRemote}`;
+    }
+  }
+
+  return result;
+}
+
+function gitHeadSha(repoRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitWorkingTreeClean(repoRoot) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return status === '';
+  } catch {
+    return false;
+  }
+}
+
+function objectExists(repoRoot, sha) {
+  if (!sha) return false;
+  try {
+    execFileSync('git', ['cat-file', '-e', `${sha}^{commit}`], {
+      cwd: repoRoot,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  CODES,
+  LAYOUTS,
+  parseSddYaml,
+  isMonoLayout,
+  loadSddYaml,
+  gitConfig,
+  gitRemoteUrl,
+  normalizeRemoteUrl,
+  remotesMatch,
+  resolveSpecPath,
+  validateSpecPath,
+  setSpecPath,
+  resolveCodeRepoContext,
+  gitHeadSha,
+  gitWorkingTreeClean,
+  objectExists,
+};

package/skywalk-sdd/ontology/workspace-layout.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const WORKSPACE_FILE = '.sdd-workspace.yaml';
+const IGNORE_DIR_NAMES = new Set([
+  'node_modules',
+  '.git',
+  '.claude',
+  '.codebuddy',
+  '.kunlunzhima',
+  '.cursor',
+  '.opencode',
+  'skywalk-sdd',
+  'openspec',
+  'openspec-templates',
+  'dist',
+  'build',
+  'coverage',
+]);
+
+function isGitRepo(dir) {
+  return fs.existsSync(path.join(dir, '.git'));
+}
+
+function looksLikeSpecRepo(dir) {
+  const name = path.basename(dir).toLowerCase();
+  if (/-sdd-specs$/.test(name) || name.endsWith('sdd-specs')) return true;
+  if (fs.existsSync(path.join(dir, 'modules.yaml'))) return true;
+  if (fs.existsSync(path.join(dir, 'openspec', 'changes'))) return true;
+  if (fs.existsSync(path.join(dir, 'openspec', 'specs', 'overview.md'))) return true;
+  return false;
+}
+
+function listChildGitRepos(workspaceRoot) {
+  if (!fs.existsSync(workspaceRoot)) return [];
+  return fs.readdirSync(workspaceRoot)
+    .filter((name) => !name.startsWith('.') && !IGNORE_DIR_NAMES.has(name))
+    .map((name) => ({ name, abs: path.join(workspaceRoot, name) }))
+    .filter((entry) => {
+      try {
+        return fs.statSync(entry.abs).isDirectory() && isGitRepo(entry.abs);
+      } catch {
+        return false;
+      }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Detect personal workspace layout: cwd hosts multiple/sibling git repos,
+ * and skills should live once at workspace root (not in every code repo).
+ */
+function detectWorkspaceLayout(workspaceRoot = process.cwd()) {
+  const root = path.resolve(workspaceRoot);
+  const children = listChildGitRepos(root);
+  const rootIsGit = isGitRepo(root);
+  const rootLooksSpec = looksLikeSpecRepo(root);
+
+  const specCandidates = children.filter((c) => looksLikeSpecRepo(c.abs));
+  let spec = null;
+  if (specCandidates.length === 1) {
+    spec = specCandidates[0];
+  } else if (specCandidates.length > 1) {
+    spec = specCandidates.find((c) => fs.existsSync(path.join(c.abs, 'modules.yaml')))
+      || specCandidates.find((c) => /-sdd-specs$/i.test(c.name))
+      || specCandidates[0];
+  } else if (rootLooksSpec && rootIsGit) {
+    spec = { name: path.basename(root), abs: root };
+  }
+
+  const codeRepos = children.filter((c) => !spec || c.abs !== spec.abs);
+
+  const isWorkspace = (!rootIsGit && children.length >= 1)
+    || (children.length >= 2)
+    || (Boolean(spec) && codeRepos.length >= 1 && !rootLooksSpec);
+
+  return {
+    root,
+    isWorkspace: Boolean(isWorkspace),
+    rootIsGit,
+    specRepo: spec,
+    codeRepos,
+    allChildGitRepos: children,
+  };
+}
+
+function parseWorkspaceYaml(text) {
+  const result = {
+    version: 1,
+    spec_path: '',
+    code_repos: [],
+  };
+  const lines = String(text || '').split(/\r?\n/);
+  let inCode = false;
+  for (const raw of lines) {
+    const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+    if (!line.trim()) continue;
+    const version = /^version:\s*(\d+)\s*$/.exec(line);
+    if (version) {
+      result.version = Number(version[1]);
+      inCode = false;
+      continue;
+    }
+    const spec = /^spec_path:\s*(.+?)\s*$/.exec(line);
+    if (spec) {
+      let value = spec[1].trim();
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      result.spec_path = value;
+      inCode = false;
+      continue;
+    }
+    if (/^code_repos:\s*$/.test(line)) {
+      inCode = true;
+      continue;
+    }
+    if (inCode) {
+      const item = /^\s*-\s+(.+?)\s*$/.exec(line);
+      if (item) {
+        result.code_repos.push(item[1].trim());
+        continue;
+      }
+      if (/^\S/.test(line)) inCode = false;
+    }
+  }
+  return result;
+}
+
+function loadWorkspaceFile(workspaceRoot) {
+  const filePath = path.join(workspaceRoot, WORKSPACE_FILE);
+  if (!fs.existsSync(filePath)) {
+    return { ok: false, path: filePath, data: null };
+  }
+  const data = parseWorkspaceYaml(fs.readFileSync(filePath, 'utf8'));
+  return { ok: true, path: filePath, data };
+}
+
+function writeWorkspaceFile(workspaceRoot, layout) {
+  const specRel = layout.specRepo
+    ? path.relative(workspaceRoot, layout.specRepo.abs) || '.'
+    : '';
+  const codeRels = (layout.codeRepos || []).map((c) =>
+    path.relative(workspaceRoot, c.abs) || c.name,
+  );
+  const lines = [
+    '# 个人工作目录编排清单（不替代各仓 .sdd.yaml）',
+    '# skills 只部署在本工作目录；代码仓仅挂 Hook / 关联 spec。',
+    'version: 1',
+    `spec_path: ${specRel}`,
+    'code_repos:',
+    ...codeRels.map((name) => `  - ${name}`),
+    '',
+  ];
+  const filePath = path.join(workspaceRoot, WORKSPACE_FILE);
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  return filePath;
+}
+
+/**
+ * Compare discovery with saved workspace file; return newly found code repos.
+ */
+function findNewCodeRepos(workspaceRoot) {
+  const layout = detectWorkspaceLayout(workspaceRoot);
+  const saved = loadWorkspaceFile(workspaceRoot);
+  const known = new Set(
+    saved.ok && saved.data
+      ? saved.data.code_repos.map((item) => path.resolve(workspaceRoot, item))
+      : [],
+  );
+  const newcomers = layout.codeRepos.filter((c) => !known.has(path.resolve(c.abs)));
+  return {
+    layout,
+    saved,
+    newcomers,
+  };
+}
+
+module.exports = {
+  WORKSPACE_FILE,
+  isGitRepo,
+  looksLikeSpecRepo,
+  listChildGitRepos,
+  detectWorkspaceLayout,
+  parseWorkspaceYaml,
+  loadWorkspaceFile,
+  writeWorkspaceFile,
+  findNewCodeRepos,
+};

package/templates/dot-sdd.yaml

@@ -0,0 +1,8 @@
+# 代码仓库根目录配置：关联团队 spec Git 仓库
+# 个人绝对路径请写入 git config --local sdd.specPath，不要写进本文件。
+#
+# 单仓（openspec 文档与代码在同一仓库）改为下面两行即可，无需 spec_repository：
+#   version: 1
+#   layout: mono
+version: 1
+spec_repository: git@gitlab.example.com:biz/xxx-sdd-specs.git