@llman-sdd/core 0.1.0

package/src/context/tree.ts

@@ -0,0 +1,118 @@
+/**
+ * Pageindex tree (context-index capability, r26): specs IR serialized as a
+ * tree — building is LLM-free. Serialization keys are snake_case, matching
+ * v1's tree.json so retrieval IDs stay comparable.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+import type { SpecEntry } from '../validation/validate.ts';
+
+export const TREE_VERSION = 1;
+
+export interface SerializedReqNode {
+  req_id: string;
+  title: string;
+  statement: string;
+}
+
+export interface SerializedScenarioNode {
+  req_id: string;
+  id: string;
+  given: string;
+  when: string;
+  then: string;
+}
+
+export interface SerializedDocNode {
+  spec_id: string;
+  purpose: string;
+  reqs: SerializedReqNode[];
+  scenarios: SerializedScenarioNode[];
+}
+
+export interface SerializedTreeIndex {
+  version: number;
+  spec_hash: string;
+  build_timestamp: string;
+  chat_model: string;
+  docs: SerializedDocNode[];
+}
+
+function joinSteps(
+  steps: { kind: string; text: string }[],
+  kind: 'given' | 'when' | 'then',
+): string {
+  return steps
+    .filter((s) => s.kind === kind)
+    .map((s) => s.text)
+    .join('\n');
+}
+
+export function buildDocs(entries: readonly SpecEntry[]): SerializedDocNode[] {
+  return entries
+    .map((entry) => {
+      const cap = entry.doc.header.capability ?? entry.fileName;
+      const reqs = entry.doc.scenarios
+        .filter((s) => s.classification === 'human')
+        .map((s) => ({
+          req_id: s.reqIds[0] ?? '',
+          title: s.name,
+          statement: s.statement
+            .split('\n')
+            .map((l) => l.replace(/^-\s+/u, ''))
+            .join('\n'),
+        }));
+      const scenarios = entry.doc.scenarios
+        .filter((s) => s.classification === 'executable')
+        .map((s) => ({
+          req_id: s.reqIds[0] ?? '',
+          id: s.name,
+          given: joinSteps(s.steps, 'given'),
+          when: joinSteps(s.steps, 'when'),
+          // `then` is the tree.json contract key, not a thenable
+          // oxlint-disable-next-line unicorn/no-thenable
+          then: joinSteps(s.steps, 'then'),
+        }));
+      return { spec_id: cap, purpose: entry.doc.header.purpose ?? '', reqs, scenarios };
+    })
+    .toSorted((a, b) => a.spec_id.localeCompare(b.spec_id));
+}
+
+export function buildTreeIndex(
+  entries: readonly SpecEntry[],
+  meta: { specHash: string; buildTimestamp: string; chatModel: string },
+): SerializedTreeIndex {
+  return {
+    version: TREE_VERSION,
+    spec_hash: meta.specHash,
+    build_timestamp: meta.buildTimestamp,
+    chat_model: meta.chatModel,
+    docs: buildDocs(entries),
+  };
+}
+
+export interface HashIo {
+  exists(p: string): boolean;
+  isDirectory(p: string): boolean;
+  listDir(p: string): string[];
+  readText(p: string): string;
+}
+
+/** sha256 over all .feature files, sorted by path (r26 freshness anchor). */
+export function computeSpecHash(specsDir: string, io: HashIo): string {
+  const hash = createHash('sha256');
+  const walk = (dir: string): void => {
+    if (!io.exists(dir) || !io.isDirectory(dir)) return;
+    for (const name of io.listDir(dir).toSorted()) {
+      const full = join(dir, name);
+      if (io.isDirectory(full)) walk(full);
+      else if (name.endsWith('.feature')) {
+        hash.update(full);
+        hash.update(io.readText(full));
+      }
+    }
+  };
+  walk(specsDir);
+  return hash.digest('hex');
+}

package/src/git/spawnGit.ts

@@ -0,0 +1,89 @@
+/**
+ * Git subprocess adapter (change-lifecycle capability). Domain logic depends
+ * on the GitLike port; this module is the concrete spawn-based implementation
+ * (node:child_process — dual-runtime compliant per AGENTS.md).
+ */
+import { spawnSync } from 'node:child_process';
+
+export class GitError extends Error {
+  readonly args: string[];
+  readonly stderr: string;
+
+  constructor(args: string[], stderr: string) {
+    super(`git ${args.join(' ')} failed: ${stderr.trim()}`);
+    this.name = 'GitError';
+    this.args = args;
+    this.stderr = stderr;
+  }
+}
+
+export interface GitLike {
+  /** Run git, return stdout; throw GitError on non-zero exit. */
+  run(args: string[]): string;
+  /** Run git, return stdout or null on non-zero exit (probes). */
+  runOpt(args: string[]): string | null;
+}
+
+export function makeSpawnGit(cwd: string): GitLike {
+  const spawn = (args: string[]): { code: number; stdout: string; stderr: string } => {
+    const proc = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    return {
+      code: proc.status ?? 1,
+      stdout: proc.stdout ?? '',
+      stderr: proc.stderr ?? '',
+    };
+  };
+  return {
+    run(args: string[]): string {
+      const r = spawn(args);
+      if (r.code !== 0) throw new GitError(args, r.stderr);
+      return r.stdout.trim();
+    },
+    runOpt(args: string[]): string | null {
+      const r = spawn(args);
+      return r.code === 0 ? r.stdout.trim() : null;
+    },
+  };
+}
+
+export function currentBranch(git: GitLike): string | null {
+  return git.runOpt(['branch', '--show-current']);
+}
+
+export function isCleanTree(git: GitLike): boolean {
+  return git.run(['status', '--porcelain']) === '';
+}
+
+/** Local-first default branch resolution: main → master → origin/HEAD → origin/*. */
+export function defaultBranch(git: GitLike): string {
+  for (const candidate of ['main', 'master']) {
+    if (git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${candidate}`]) !== null) {
+      return candidate;
+    }
+  }
+  const originHead = git.runOpt(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  if (originHead !== null) {
+    const branch = originHead.replace(/^origin\//u, '');
+    if (branch !== originHead && branch !== '') return branch;
+  }
+  for (const ref of git.runOpt(['branch', '--remote', '--format=%(refname:short)'])?.split('\n') ??
+    []) {
+    if (ref.startsWith('origin/')) return ref.slice('origin/'.length);
+  }
+  throw new GitError(
+    ['default-branch-resolution'],
+    'no local main/master or origin/* branch found',
+  );
+}
+
+export function mergeBase(a: string, b: string, git: GitLike): string {
+  return git.run(['merge-base', a, b]);
+}
+
+export function branchExists(branch: string, git: GitLike): boolean {
+  return git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]) !== null;
+}
+
+export function revParseHead(git: GitLike): string {
+  return git.run(['rev-parse', 'HEAD']);
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+export const VERSION = '0.1.0';
+
+export * from './ports.ts';
+
+export {
+  EXTRA_SKILLS,
+  archiveSchema,
+  bddSchema,
+  bindingSchema,
+  changeIdSchema,
+  scenarioAttrsBindingSchema,
+  sddConfigSchema,
+  sddSchema,
+  tagsBindingSchema,
+  type SddConfig,
+  type SddConfigInput,
+} from './config/schema.ts';
+export { ConfigValidationError, MAX_REPORTED_ISSUES, loadConfig } from './config/load.ts';
+
+export type {
+  CapabilityDoc,
+  CapabilityHeader,
+  ScenarioClassification,
+  ScenarioIR,
+  SpecStructuralError,
+} from './spec/ir.ts';
+export {
+  SpecParseError,
+  localeToGherkinLang,
+  parseCapability,
+  parseFeatureSource,
+} from './spec/parser.ts';
+export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export type {
+  SpecEntry,
+  SpecIo,
+  SpecVerdict,
+  ValidationItem,
+  ValidationLevel,
+  ValidationReport,
+} from './validation/validate.ts';
+export { validateAllSpecs, validateCapability } from './validation/validate.ts';
+export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
+export type { ChangeBinding } from './change/frontmatter.ts';
+export { readBinding, writeBinding } from './change/frontmatter.ts';
+export {
+  GitError,
+  defaultBranch,
+  isCleanTree,
+  makeSpawnGit,
+  mergeBase,
+  currentBranch,
+  branchExists,
+  revParseHead,
+  type GitLike,
+} from './git/spawnGit.ts';
+export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId, isLegalChangeId } from './change/id.ts';
+export {
+  CHANGES_DIR,
+  LifecycleError,
+  attachChange,
+  changeDiff,
+  finalizeChange,
+  newChange,
+  startChange,
+  type FinalizeResult,
+  type FsIo,
+} from './change/lifecycle.ts';
+export { normalizeLocale, localeFallbacks } from './templates/locale.ts';
+export {
+  MAX_UNIT_NESTING_DEPTH,
+  MissingUnitError,
+  renderTemplate,
+  renderWithUnits,
+  type UnitRegistry,
+} from './templates/engine.ts';
+export {
+  DEFAULT_SKILL_FILES,
+  ETHICS_KEYS,
+  OPTIONAL_SKILL_FILES,
+  UNIT_FILES,
+  buildTemplateVars,
+  effectiveRunCommand,
+  enforceEthicsGovernance,
+  loadLocaleResource,
+  loadSkillTemplates,
+  loadUnitRegistry,
+  skillCandidates,
+  type SkillTemplate,
+  type TemplateIo,
+} from './templates/skills.ts';
+export { runInit, updateFileWithMarkers, type InitResult } from './init/init.ts';
+export {
+  collectChanges,
+  renderChangesList,
+  renderChangesJson,
+  statusFor,
+  stageFor,
+  relativeTime,
+  statusHuman,
+  type ChangeFsIo,
+  type ChangeStatus,
+  type ChangeSummary,
+} from './report/collect.ts';
+export { graphMermaid, type GraphFsIo } from './report/graph.ts';
+export { showChangeJson, type ShowDeps, type ShowFsIo } from './report/show.ts';
+export {
+  nextReqId,
+  scaffoldSpec,
+  skeletonContent,
+  type SpecHelperIo,
+} from './report/specHelpers.ts';
+export {
+  collectSpecs,
+  renderSpecsJson,
+  renderSpecsList,
+  type SpecMorphology,
+  type SpecSummary,
+} from './report/specs.ts';
+export { SevenZipError, makeWasmSevenZip, type SevenZipPort } from './archive/sevenzip.ts';
+export {
+  ARCHIVE_DIR_REL,
+  FREEZE_ARCHIVE_NAME,
+  freezeCandidates,
+  runFreeze,
+  runList,
+  runThaw,
+  type FreezeIo,
+  type FreezeOpts,
+  type FreezeRunResult,
+  type ThawResult,
+} from './archive/freeze.ts';
+export {
+  buildReview,
+  type ReviewInput,
+  type ReviewKind,
+  type ReviewResult,
+  type ReviewSignal,
+  type TagBinding,
+} from './review/review.ts';
+export {
+  TREE_VERSION,
+  buildDocs,
+  buildTreeIndex,
+  computeSpecHash,
+  type HashIo,
+  type SerializedDocNode,
+  type SerializedScenarioNode,
+  type SerializedReqNode,
+  type SerializedTreeIndex,
+} from './context/tree.ts';
+export {
+  CONTEXT_DIR_REL,
+  PAGEINDEX_DIR_REL,
+  REBUILD_LOCK_REL,
+  TREE_JSON_REL,
+  checkIndexFreshness,
+  loadTree,
+  parseLock,
+  rebuildIndex,
+  type FreshnessResult,
+  type IndexIo,
+  type RebuildOpts,
+  type RebuildResult,
+} from './context/indexStore.ts';
+export {
+  MAX_TOOL_ROUNDS,
+  resolveChatConfig,
+  runContextRetrieval,
+  unavailableResult,
+  type ChatConfig,
+  type ContextResult,
+  type RetrieveDeps,
+  type TierEntry,
+  type TreeToolDeps,
+} from './context/retrieve.ts';

package/src/init/defaultConfig.ts

@@ -0,0 +1,73 @@
+/**
+ * Default llmanspec/config.yaml templates, extracted verbatim from v1
+ * (crates/llman-sdd/src/sdd/project/config.rs DEFAULT_CONFIG_EN/ZH_HANS).
+ */
+export const LLMANSPEC_SCHEMA_URL =
+  'https://raw.githubusercontent.com/StrayDragon/llman/main/artifacts/schema/configs/en/llmanspec-config.schema.json';
+
+export const DEFAULT_CONFIG_EN = `schema: spec-driven
+locale: en
+
+# Optional extra skills (disabled by default, uncomment to enable).
+# On \`llman sdd init --update\`, managed candidates are:
+#   default workflow skills + entries listed here (extra_skills extend).
+# Then \`.agents/skills/llman-sdd-*\` is scanned: anything not in that candidate
+# set is removed first, then candidates are written/updated. Only the
+# \`llman-sdd-\` prefix is touched (custom skills without that prefix are kept).
+# Deprecated shipped skills (e.g. removed from defaults) are cleaned this way.
+# extra_skills:
+#   - llman-sdd-continue
+#   - llman-sdd-ff
+#   - llman-sdd-validate
+#   - llman-sdd-arch-review
+#   - llman-sdd-wayfinder
+#   - llman-sdd-research
+
+# BDD integration (optional, uncomment to enable)
+# bdd:
+#   framework: pytest-bdd
+#   feature_dir: tests/features/
+#   # default_language: en
+#   # Filtered runners: include {feature_*} so validate --all/--specs runs per capability.
+#   # run_command: "pytest {feature_dir} -k {feature_name} -v"
+#   # Project-wide runners (no placeholders): validate --all/--specs runs the suite once (batch-once).
+#   # run_command: "cargo test --features bdd"
+#   # verify_prompt: |
+#   #   Map test failures to requirement IDs.
+`;
+
+export const DEFAULT_CONFIG_ZH_HANS = `schema: spec-driven
+locale: zh-Hans
+
+# 可选额外技能（默认禁用，取消注释以启用）。
+# 运行 \`llman sdd init --update\` 时，管理候选集为：
+#   默认 workflow 技能 + 本列表（extra_skills 扩展）。
+# 然后扫描 \`.agents/skills/llman-sdd-*\`：不在候选集中的先删除，再写入/更新候选。
+# 仅处理 \`llman-sdd-\` 前缀（无此前缀的自定义技能不会被删）。
+# 已废弃的内置技能（从默认集移除后）会因此被正确清理。
+# extra_skills:
+#   - llman-sdd-continue
+#   - llman-sdd-ff
+#   - llman-sdd-validate
+#   - llman-sdd-arch-review
+#   - llman-sdd-wayfinder
+#   - llman-sdd-research
+
+# BDD 集成（可选，取消注释以启用）
+# bdd:
+#   framework: pytest-bdd
+#   feature_dir: tests/features/
+#   # default_language: zh-CN
+#   # 过滤型 runner：写 {feature_*}，validate --all/--specs 按 capability 分别执行。
+#   # run_command: "pytest {feature_dir} -k {feature_name} -v"
+#   # 项目级 runner（无占位符）：validate --all/--specs 整批只跑一次（batch-once）。
+#   # run_command: "cargo test --features bdd"
+#   # verify_prompt: |
+#   #   将测试失败映射到对应的 requirement ID。
+`;
+
+export function prependSchemaHeader(content: string, schemaUrl: string): string {
+  const header = `# yaml-language-server: $schema=${schemaUrl}`;
+  if (content === '') return `${header}\n`;
+  return `${header}\n${content}`;
+}

package/src/init/init.ts

@@ -0,0 +1,145 @@
+/**
+ * init / --update orchestration (init-generators capability, r19).
+ * Scaffold llmanspec/, write managed AGENTS.md blocks, render skills into
+ * the .agents/skills namespace (SKILL.md per skill dir), and clean the
+ * managed namespace.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadConfig } from '../config/load.ts';
+import { renderTemplate } from '../templates/engine.ts';
+import { localeFallbacks } from '../templates/locale.ts';
+import {
+  buildTemplateVars,
+  enforceEthicsGovernance,
+  loadLocaleResource,
+  loadSkillTemplates,
+  skillCandidates,
+} from '../templates/skills.ts';
+import {
+  DEFAULT_CONFIG_EN,
+  DEFAULT_CONFIG_ZH_HANS,
+  LLMANSPEC_SCHEMA_URL,
+  prependSchemaHeader,
+} from './defaultConfig.ts';
+
+export { effectiveRunCommand } from '../templates/skills.ts';
+
+const MARKER_START = '<!-- LLMANSPEC:START -->';
+const MARKER_END = '<!-- LLMANSPEC:END -->';
+
+/** Marker-block update: replace block body if present, else prepend the block. */
+export function updateFileWithMarkers(content: string, body: string): string {
+  if (content === '') {
+    return `${MARKER_START}\n${body}\n${MARKER_END}\n`;
+  }
+  const start = content.indexOf(MARKER_START);
+  const end = content.indexOf(MARKER_END);
+  if (start !== -1 && end !== -1) {
+    if (end < start)
+      throw new Error('Invalid marker state: end marker appears before start marker.');
+    return `${content.slice(0, start)}${MARKER_START}\n${body}\n${MARKER_END}${content.slice(end + MARKER_END.length)}`;
+  }
+  return `${MARKER_START}\n${body}\n${MARKER_END}\n${content}`;
+}
+
+export const TEMPLATES_ROOT = join(import.meta.dirname, '..', '..', 'templates');
+
+function writeDefaultConfig(root: string, locale: string): void {
+  const raw = locale === 'zh-Hans' ? DEFAULT_CONFIG_ZH_HANS : DEFAULT_CONFIG_EN;
+  const dir = join(root, 'llmanspec');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'config.yaml'), prependSchemaHeader(raw, LLMANSPEC_SCHEMA_URL));
+}
+
+export interface InitResult {
+  /** Skill dirs written, in render order. */
+  skills: string[];
+  /** llman-sdd-* directories removed by --update namespace cleanup. */
+  removed: string[];
+  configPath: string;
+}
+
+export function runInit(
+  root: string,
+  opts: { update: boolean; locale?: string; version: string },
+): InitResult {
+  const llmanspecDir = join(root, 'llmanspec');
+  mkdirSync(llmanspecDir, { recursive: true });
+
+  // 1) config: create with defaults if missing, then always load.
+  const configPath = join(llmanspecDir, 'config.yaml');
+  if (!existsSync(configPath)) writeDefaultConfig(root, opts.locale ?? 'en');
+  const config = loadConfig(readFileSync(configPath, 'utf8'));
+
+  // 2) scaffold directories.
+  mkdirSync(join(llmanspecDir, 'specs'), { recursive: true });
+  mkdirSync(join(llmanspecDir, 'changes', 'archive'), { recursive: true });
+  const gitkeepSpecs = join(llmanspecDir, 'specs', '.gitkeep');
+  if (!existsSync(gitkeepSpecs)) writeFileSync(gitkeepSpecs, '');
+  const gitkeepArchive = join(llmanspecDir, 'changes', 'archive', '.gitkeep');
+  if (!existsSync(gitkeepArchive)) writeFileSync(gitkeepArchive, '');
+
+  // 3) AGENTS.md managed blocks (root + llmanspec), preserving content.
+  const vars = buildTemplateVars(config, opts.version);
+  const locales = localeFallbacks(config.locale);
+  // skills render owns the unit registry; stubs reuse the same registry load.
+  const skillTemplates = loadSkillTemplates(
+    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
+    TEMPLATES_ROOT,
+    config,
+    vars,
+  );
+  enforceEthicsGovernance(skillTemplates);
+
+  const rootStubRaw = loadLocaleResource(
+    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
+    TEMPLATES_ROOT,
+    locales,
+    'agents-root-stub.md',
+  );
+  if (rootStubRaw !== null) {
+    const agentsPath = join(root, 'AGENTS.md');
+    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+    const body = renderTemplate(rootStubRaw, new Map(), vars);
+    writeFileSync(agentsPath, updateFileWithMarkers(existing, body));
+  }
+  const llmanspecStubRaw = loadLocaleResource(
+    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
+    TEMPLATES_ROOT,
+    locales,
+    'llmanspec-agents-stub.md',
+  );
+  if (llmanspecStubRaw !== null) {
+    const agentsPath = join(llmanspecDir, 'AGENTS.md');
+    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+    const body = renderTemplate(llmanspecStubRaw, new Map(), vars);
+    writeFileSync(agentsPath, updateFileWithMarkers(existing, body));
+  }
+
+  // 4) skills namespace cleanup (--update only): remove llman-sdd-* dirs
+  // outside the candidate set; un-prefixed custom skills stay untouched.
+  const removed: string[] = [];
+  const skillsBase = join(root, '.agents', 'skills');
+  if (opts.update && existsSync(skillsBase)) {
+    const candidates = new Set(skillCandidates(config).map((f) => f.replace(/\.md$/u, '')));
+    for (const entry of readdirSync(skillsBase)) {
+      if (entry.startsWith('llman-sdd-') && !candidates.has(entry)) {
+        rmSync(join(skillsBase, entry), { recursive: true, force: true });
+        removed.push(entry);
+      }
+    }
+  }
+
+  // 5) write candidates: rendered product trimmed + single trailing newline.
+  const skillsBase2 = join(root, '.agents', 'skills');
+  for (const t of skillTemplates) {
+    const dirName = t.name.replace(/\.md$/u, '');
+    const skillDir = join(skillsBase2, dirName);
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), `${t.content.trimEnd()}\n`);
+  }
+
+  return { skills: skillTemplates.map((t) => t.name.replace(/\.md$/u, '')), removed, configPath };
+}

package/src/ports.ts

@@ -0,0 +1,20 @@
+/**
+ * Ports (spec monorepo-structure r3): domain logic must not touch the
+ * filesystem, git subprocesses, or the terminal directly — side effects are
+ * injected through these interfaces. Nothing under packages/core may import
+ * `node:fs`, `Bun.$`, or prompt libraries; runtimes wire adapters in.
+ */
+
+/** Interaction port. v1 ships an @inquirer/prompts adapter; a future ink TUI
+ * ships its own adapter (the two must never run in the same process). */
+export interface PromptDriver {
+  select<T extends string>(message: string, choices: readonly T[]): Promise<T>;
+  multiselect<T extends string>(message: string, choices: readonly T[]): Promise<T[]>;
+  confirm(message: string): Promise<boolean>;
+}
+
+/** Template rendering port (nunjucks adapter planned: autoescape off,
+ * minijinja-compatible trim semantics, `unit()` registered via addGlobal). */
+export interface TemplateEngine {
+  render(template: string, context: Record<string, unknown>): string;
+}