@llman-sdd/core 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@llman-sdd/core",
+  "version": "0.1.0",
+  "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/StrayDragon/llman-sdd.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "lint": "bun run --cwd ../.. lint",
+    "lint:fix": "bun run --cwd ../.. lint:fix",
+    "format:check": "bun run --cwd ../.. format:check",
+    "format:write": "bun run --cwd ../.. format:write",
+    "typecheck": "bun run --cwd ../.. typecheck"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=24.0.0"
+  }
+}

package/src/archive/freeze.ts

@@ -0,0 +1,150 @@
+/**
+ * Archive freeze/thaw orchestration (review-freeze capability, r24/r25).
+ * Port of v1 change/freeze.rs: candidates = dated archive dirs; freeze adds
+ * them into `freezed_changes.7z.archived` (7z a updates existing archives)
+ * then removes the originals; thaw extracts selected dirs back into place.
+ * All filesystem effects flow through the injected FreezeIo.
+ */
+import { join } from 'node:path';
+
+import type { SevenZipPort } from './sevenzip.ts';
+
+export const FREEZE_ARCHIVE_NAME = 'freezed_changes.7z.archived';
+export const ARCHIVE_DIR_REL = 'llmanspec/changes/archive';
+
+export interface FreezeIo {
+  exists(path: string): boolean;
+  listDir(path: string): string[];
+  /** rm -rf */
+  removeDir(path: string): void;
+  mkdirp(path: string): void;
+  /** Move a directory within the repo (same-device; adapter may copy). */
+  moveDir(from: string, to: string): void;
+}
+
+const DATED_RE = /^\d{4}-\d{2}-\d{2}-/u;
+
+export function freezeCandidates(
+  io: FreezeIo,
+  archiveDir: string,
+  opts: { before?: string; keepRecent?: number },
+): string[] {
+  const all = io.exists(archiveDir)
+    ? io
+        .listDir(archiveDir)
+        .filter((n) => DATED_RE.test(n))
+        .toSorted()
+    : [];
+  let candidates = opts.before ? all.filter((n) => n.slice(0, 10) < (opts.before ?? '')) : [...all];
+  const keep = opts.keepRecent ?? 0;
+  if (keep > 0) candidates = candidates.slice(0, Math.max(0, candidates.length - keep));
+  return candidates;
+}
+
+export interface FreezeOpts {
+  before?: string;
+  keepRecent?: number;
+  dryRun?: boolean;
+}
+
+export interface FreezeRunResult {
+  lines: string[];
+  candidates: string[];
+}
+
+export async function runFreeze(
+  io: FreezeIo,
+  sz: SevenZipPort,
+  rootAbs: string,
+  opts: FreezeOpts,
+): Promise<FreezeRunResult> {
+  const candidates = freezeCandidates(io, ARCHIVE_DIR_REL, opts);
+  if (candidates.length === 0) {
+    return { candidates, lines: ['No archived changes selected for freezing.'] };
+  }
+  if (opts.dryRun) {
+    return {
+      candidates,
+      lines: [
+        `Dry run: freeze target ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`,
+        `Would freeze ${candidates.length} archived changes:`,
+        ...candidates.map((c) => `  - ${c}`),
+      ],
+    };
+  }
+  const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
+  await sz.add(archiveAbs, join(rootAbs, ARCHIVE_DIR_REL), candidates);
+  for (const c of candidates) {
+    io.removeDir(`${ARCHIVE_DIR_REL}/${c}`);
+  }
+  return {
+    candidates,
+    lines: [
+      `Froze ${candidates.length} archived changes into ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`,
+    ],
+  };
+}
+
+export async function runList(io: FreezeIo, sz: SevenZipPort, rootAbs: string): Promise<string[]> {
+  const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
+  if (!io.exists(archiveAbs)) {
+    return [`No freeze archive found at ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`];
+  }
+  const entries = (await sz.listEntries(archiveAbs))
+    .map((n) => n.replace(/\/$/u, ''))
+    .filter((n) => DATED_RE.test(n) && n.split('/').length === 1);
+  const unique = [...new Set(entries)].toSorted();
+  if (unique.length === 0) {
+    return [
+      `Freeze archive ${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME} contains no archived changes`,
+    ];
+  }
+  return [
+    `Frozen archived changes in ${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME} (${unique.length}):`,
+    ...unique.map((c) => `  - ${c}`),
+  ];
+}
+
+export interface ThawResult {
+  lines: string[];
+  restored: string[];
+}
+
+export async function runThaw(
+  io: FreezeIo,
+  sz: SevenZipPort,
+  rootAbs: string,
+  names: string[],
+): Promise<ThawResult> {
+  const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
+  if (!io.exists(`${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`)) {
+    throw new Error(`No freeze archive found at ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`);
+  }
+  const tmpRel = 'llmanspec/.thaw-tmp';
+  const tmpAbs = join(rootAbs, tmpRel);
+  io.removeDir(tmpRel);
+  try {
+    await sz.extractAll(archiveAbs, tmpAbs);
+    const available = new Set(io.listDir(tmpRel).filter((n) => DATED_RE.test(n)));
+    const missing = names.filter((n) => !available.has(n));
+    if (missing.length > 0) {
+      throw new Error(
+        `archived change(s) not found in freeze archive: ${missing.join(', ')} — available: ${[...available].toSorted().join(', ')}`,
+      );
+    }
+    const restored: string[] = [];
+    for (const name of names.toSorted()) {
+      if (io.exists(`${ARCHIVE_DIR_REL}/${name}`)) {
+        throw new Error(`target already exists: ${name}`);
+      }
+      io.moveDir(`${tmpRel}/${name}`, `${ARCHIVE_DIR_REL}/${name}`);
+      restored.push(name);
+    }
+    return {
+      restored,
+      lines: [`Thawed ${restored.length} selected archived changes to ${ARCHIVE_DIR_REL}`],
+    };
+  } finally {
+    io.removeDir(tmpRel);
+  }
+}

package/src/archive/sevenzip.ts

@@ -0,0 +1,110 @@
+import { mkdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+/**
+ * 7z adapter (review-freeze capability, r24/r25): 7z-wasm (Emscripten) with
+ * NODEFS mounts — self-contained, no system 7z dependency. One module
+ * instance per operation; extraction target must be a fresh directory
+ * (WASM 7z refuses existing -o dirs). Spike-proven on Bun: compress / list /
+ * extract keep directory structure.
+ */
+import SevenZip from '7z-wasm';
+
+export interface SevenZipPort {
+  /** Add `entries` (paths relative to `baseDir`) into `archivePath`. */
+  add(archivePath: string, baseDir: string, entries: string[]): Promise<void>;
+  /** List entry paths stored in the archive. */
+  listEntries(archivePath: string): Promise<string[]>;
+  /** Extract the whole archive into `destDir` (created fresh, must not exist). */
+  extractAll(archivePath: string, destDir: string): Promise<void>;
+}
+
+export class SevenZipError extends Error {}
+
+interface EmscriptenModule {
+  FS: {
+    mkdir(path: string): void;
+    mount(type: unknown, opts: { root: string }, mountpoint: string): void;
+    chdir(path: string): void;
+  };
+  NODEFS: unknown;
+  callMain(args: string[]): number;
+}
+
+type ModuleFactory = (opts: {
+  noInitialRun: boolean;
+  print?: (text: string) => void;
+  printErr?: (text: string) => void;
+}) => Promise<EmscriptenModule>;
+
+async function initModule(print?: (text: string) => void): Promise<EmscriptenModule> {
+  const sink = (text: string): void => {
+    if (print) print(text);
+  };
+  const factory = SevenZip as unknown as ModuleFactory;
+  return factory({ noInitialRun: true, print: sink, printErr: sink });
+}
+
+function mount(mod: EmscriptenModule, seq: number, hostDir: string): string {
+  const mountpoint = `/mnt${seq}`;
+  mod.FS.mkdir(mountpoint);
+  mod.FS.mount(mod.NODEFS, { root: hostDir }, mountpoint);
+  return mountpoint;
+}
+
+/** 7z `l` listing: header/footer dashed rules around fixed-ish columns; our
+ * entry names are space-free, so the name is column 6+. */
+function parseListNames(lines: string[]): string[] {
+  const names: string[] = [];
+  let inTable = false;
+  let rulesSeen = 0;
+  for (const line of lines) {
+    if (/^-+/u.test(line)) {
+      rulesSeen += 1;
+      inTable = rulesSeen >= 2 && rulesSeen <= 2 ? true : inTable;
+      if (rulesSeen === 3) break;
+      continue;
+    }
+    if (inTable) {
+      const parts = line.trim().split(/\s+/u);
+      if (parts.length >= 6) {
+        const attr = parts[2] ?? '';
+        const name = parts.slice(5).join(' ');
+        if (name !== '' && !attr.includes('D')) names.push(name);
+      }
+    }
+  }
+  return names;
+}
+
+export async function makeWasmSevenZip(): Promise<SevenZipPort> {
+  return {
+    async add(archivePath: string, baseDir: string, entries: string[]): Promise<void> {
+      const mod = await initModule();
+      const archMount = mount(mod, 1, join(archivePath, '..'));
+      const baseMount = mount(mod, 2, baseDir);
+      mod.FS.chdir(baseMount);
+      const rc = mod.callMain(['a', `${archMount}/${basename(archivePath)}`, ...entries]);
+      if (rc !== 0) throw new SevenZipError(`7z add failed (rc=${rc})`);
+    },
+
+    async listEntries(archivePath: string): Promise<string[]> {
+      const lines: string[] = [];
+      const mod = await initModule((text) => lines.push(text));
+      const archMount = mount(mod, 1, join(archivePath, '..'));
+      const rc = mod.callMain(['l', `${archMount}/${basename(archivePath)}`]);
+      if (rc !== 0) throw new SevenZipError(`7z list failed (rc=${rc})`);
+      return parseListNames(lines);
+    },
+
+    async extractAll(archivePath: string, destDir: string): Promise<void> {
+      const mod = await initModule();
+      const archMount = mount(mod, 1, join(archivePath, '..'));
+      mkdirSync(destDir, { recursive: true });
+      const destMount = mount(mod, 2, destDir);
+      mod.FS.chdir(destMount);
+      const rc = mod.callMain(['x', `${archMount}/${basename(archivePath)}`, '-y']);
+      if (rc !== 0) throw new SevenZipError(`7z extract failed (rc=${rc})`);
+    },
+  };
+}

package/src/change/frontmatter.ts

@@ -0,0 +1,49 @@
+/**
+ * proposal.md frontmatter binding (change-lifecycle capability):
+ * comment-preserving read/upsert of the git binding keys via the `yaml`
+ * package's document model. Pure string-in/string-out.
+ */
+import { parseDocument } from 'yaml';
+
+export interface ChangeBinding {
+  branch: string;
+  baseBranch: string;
+  baseSha: string;
+}
+
+function splitFrontmatter(proposal: string): { body: string; frontmatter: string | null } {
+  if (!proposal.startsWith('---\n')) return { body: proposal, frontmatter: null };
+  const end = proposal.indexOf('\n---\n', 4);
+  if (end === -1) return { body: proposal, frontmatter: null };
+  return {
+    frontmatter: proposal.slice(4, end + 1),
+    body: proposal.slice(end + 5),
+  };
+}
+
+export function readBinding(proposal: string): ChangeBinding | null {
+  const { frontmatter } = splitFrontmatter(proposal);
+  if (frontmatter === null) return null;
+  const doc = parseDocument(frontmatter);
+  const branch = doc.get('branch');
+  const baseBranch = doc.get('base_branch');
+  const baseSha = doc.get('base_sha');
+  if (typeof branch !== 'string' || typeof baseBranch !== 'string' || typeof baseSha !== 'string') {
+    return null;
+  }
+  return { branch, baseBranch, baseSha };
+}
+
+/** Upsert the three binding keys, preserving all comments and other keys. */
+export function writeBinding(proposal: string, binding: ChangeBinding): string {
+  const { body, frontmatter } = splitFrontmatter(proposal);
+  if (frontmatter === null) {
+    const fm = `---\nbranch: ${binding.branch}\nbase_branch: ${binding.baseBranch}\nbase_sha: ${binding.baseSha}\n---\n`;
+    return `${fm}${proposal}`;
+  }
+  const doc = parseDocument(frontmatter);
+  doc.set('branch', binding.branch);
+  doc.set('base_branch', binding.baseBranch);
+  doc.set('base_sha', binding.baseSha);
+  return `---\n${String(doc).replace(/\n$/u, '')}\n---\n${body}`;
+}

package/src/change/id.ts

@@ -0,0 +1,50 @@
+/**
+ * Change id derivation (change-lifecycle capability): legal ids are
+ * verb-prefixed kebab-case ASCII, ≤60 chars (CLI-checked convention).
+ */
+const VERBS = [
+  'bootstrap',
+  'port',
+  'add',
+  'update',
+  'remove',
+  'refactor',
+  'fix',
+  'release',
+  'migrate',
+  'init',
+  'draft',
+  'archive',
+] as const;
+
+const ID_CAP = 60;
+
+export function isLegalChangeId(id: string): boolean {
+  return (
+    VERBS.some((v) => id === v || id.startsWith(`${v}-`)) &&
+    /^[a-z0-9-]+$/u.test(id) &&
+    id.length <= ID_CAP
+  );
+}
+
+export function deriveChangeId(description: string): string {
+  let id = description
+    .toLowerCase()
+    .normalize('NFKD')
+    .replaceAll(/[^a-z0-9]+/gu, '-')
+    .replaceAll(/^-+|-+$/gu, '')
+    .slice(0, ID_CAP)
+    .replaceAll(/-+$/gu, '');
+  if (id === '') id = 'change';
+  if (isLegalChangeId(id)) return id;
+  return `add-${id}`.slice(0, ID_CAP).replaceAll(/-+$/gu, '');
+}
+
+export const DRAFT_PROPOSAL_TEMPLATE = `## Why
+
+TODO: Why is this change needed?
+
+## What Changes
+
+TODO: Bullet list of what changes.
+`;

package/src/change/lifecycle.ts

@@ -0,0 +1,141 @@
+import {
+  currentBranch,
+  defaultBranch,
+  isCleanTree,
+  revParseHead,
+  type GitLike,
+} from '../git/spawnGit.ts';
+import { readBinding, writeBinding } from './frontmatter.ts';
+/**
+ * Change lifecycle (change-lifecycle capability): new / start / attach /
+ * finalize with the v1 git-native contract (r14-r16). All effects flow
+ * through the injected GitLike and FsIo ports — this module stays pure.
+ * FsIo paths are ROOT-RELATIVE (e.g. `llmanspec/changes/<id>/proposal.md`);
+ * the git cwd binding lives in the GitLike adapter.
+ */
+import { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId } from './id.ts';
+
+export interface FsIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  /** writeText creates parent directories as needed. */
+  writeText(path: string, content: string): void;
+  rename(from: string, to: string): void;
+  listDir(path: string): string[];
+}
+
+export class LifecycleError extends Error {}
+
+export const CHANGES_DIR = 'llmanspec/changes';
+const proposalPath = (id: string): string => `${CHANGES_DIR}/${id}/proposal.md`;
+
+export function changeExists(io: FsIo, id: string): boolean {
+  return io.exists(proposalPath(id));
+}
+
+/** `change new [id] --from DESC`: derive a legal id and write the draft shell. */
+export function newChange(
+  io: FsIo,
+  opts: { id?: string; from?: string },
+): { id: string; path: string } {
+  const id = opts.id ?? deriveChangeId(opts.from ?? '');
+  const path = proposalPath(id);
+  if (io.exists(path)) throw new LifecycleError(`change \`${id}\` already exists: ${path}`);
+  io.writeText(path, `---\ndepends_on: []\n---\n\n${DRAFT_PROPOSAL_TEMPLATE}`);
+  return { id, path };
+}
+
+/** `change start`: clean-tree + default-branch gates, then branch + binding. */
+export function startChange(
+  git: GitLike,
+  io: FsIo,
+  id: string,
+  opts: { branchPrefix?: string } = {},
+): { branch: string; baseBranch: string; baseSha: string } {
+  const path = proposalPath(id);
+  if (!io.exists(path)) throw new LifecycleError(`proposal not found: ${path}`);
+  if (!isCleanTree(git))
+    throw new LifecycleError('working tree is not clean — commit or stash first');
+  const baseBranch = defaultBranch(git);
+  const here = currentBranch(git);
+  if (here !== baseBranch) {
+    throw new LifecycleError(
+      `must run from the default branch (${baseBranch}), currently on: ${here ?? 'detached'}`,
+    );
+  }
+  const branchPrefix = opts.branchPrefix ?? 'sdd/';
+  const branch = `${branchPrefix}${id}`;
+  git.run(['switch', '-c', branch]);
+  const baseSha = revParseHead(git);
+  io.writeText(path, writeBinding(io.readText(path), { branch, baseBranch, baseSha }));
+  return { branch, baseBranch, baseSha };
+}
+
+/** `change attach`: bind the current branch without gates. */
+export function attachChange(git: GitLike, io: FsIo, id: string): { branch: string } {
+  const path = proposalPath(id);
+  if (!io.exists(path)) throw new LifecycleError(`proposal not found: ${path}`);
+  const branch = currentBranch(git);
+  if (branch === null) throw new LifecycleError('detached HEAD — cannot attach');
+  const baseSha = revParseHead(git);
+  io.writeText(
+    path,
+    writeBinding(io.readText(path), { branch, baseBranch: defaultBranch(git), baseSha }),
+  );
+  return { branch };
+}
+
+export interface FinalizeResult {
+  target: string;
+  archiveDir: string;
+  warnings: string[];
+  commitSubject: string;
+}
+
+/** `change finalize`: merge (squash default) + archive rename + close-out commit. */
+export function finalizeChange(
+  git: GitLike,
+  io: FsIo,
+  id: string,
+  opts: { into?: string; method?: 'squash' | 'ff'; today?: string } = {},
+): FinalizeResult {
+  const path = proposalPath(id);
+  const binding = readBinding(io.readText(path));
+  if (binding === null) {
+    throw new LifecycleError(`change \`${id}\` has no branch binding — run start/attach first`);
+  }
+  const method = opts.method ?? 'squash';
+  const target = opts.into ?? binding.baseBranch ?? defaultBranch(git);
+  const warnings: string[] = [];
+
+  // Read the binding while still on the feature branch (its proposal.md may
+  // carry uncommitted binding edits), then switch and merge.
+  git.run(['switch', target]);
+  const mergeArgs =
+    method === 'ff'
+      ? ['merge', '--ff-only', binding.branch]
+      : ['merge', '--squash', binding.branch];
+  if (git.runOpt(mergeArgs) === null) {
+    git.runOpt(['merge', '--abort']);
+    warnings.push(
+      `merge ${method} failed — resolve manually, e.g. \`git merge ${method === 'ff' ? '--ff-only' : '--squash'} ${binding.branch}\``,
+    );
+  }
+
+  const date = opts.today ?? new Date().toISOString().slice(0, 10);
+  const archiveDir = `${CHANGES_DIR}/archive/${date}-${id}`;
+  io.rename(`${CHANGES_DIR}/${id}`, archiveDir);
+
+  git.run(['add', '-A']);
+  const commitSubject = `archive(sdd): ${id}`;
+  git.run(['commit', '-m', commitSubject]);
+  return { target, archiveDir, warnings, commitSubject };
+}
+
+/** `change diff <id>`: full diff of the bound branch vs base. */
+export function changeDiff(git: GitLike, io: FsIo, id: string): string {
+  const binding = readBinding(io.readText(proposalPath(id)));
+  if (binding === null) throw new LifecycleError(`change \`${id}\` has no branch binding`);
+  const base = binding.baseBranch ?? defaultBranch(git);
+  return git.run(['diff', `${base}...${binding.branch}`]);
+}

package/src/config/load.ts

@@ -0,0 +1,48 @@
+/**
+ * Config loading (config-schema capability): parse YAML text + validate
+ * against the zod contract. Pure — no filesystem access; callers read the
+ * file and hand over the string.
+ *
+ * Validation failures report at most 5 issue lines (r6), each prefixed with
+ * its field path.
+ */
+import { parse } from 'yaml';
+
+import { sddConfigSchema, type SddConfig } from './schema.ts';
+
+export const MAX_REPORTED_ISSUES = 5;
+
+export class ConfigValidationError extends Error {
+  /** All issue lines (untruncated) for programmatic consumers. */
+  readonly issues: string[];
+
+  constructor(issues: string[]) {
+    const shown = issues.slice(0, MAX_REPORTED_ISSUES);
+    super(
+      `invalid llmanspec/config.yaml (${issues.length} issue${issues.length === 1 ? '' : 's'}, showing up to ${MAX_REPORTED_ISSUES}):\n` +
+        shown.map((i) => `- ${i}`).join('\n'),
+    );
+    this.name = 'ConfigValidationError';
+    this.issues = issues;
+  }
+}
+
+export function loadConfig(source: string): SddConfig {
+  let data: unknown;
+  try {
+    data = parse(source);
+  } catch (error) {
+    throw new ConfigValidationError([
+      `YAML parse error: ${error instanceof Error ? error.message : String(error)}`,
+    ]);
+  }
+  const result = sddConfigSchema.safeParse(data);
+  if (!result.success) {
+    const issues = result.error.issues.map((iss) => {
+      const path = iss.path.map(String).join('/');
+      return `${path || '<root>'}: ${iss.message}`;
+    });
+    throw new ConfigValidationError(issues);
+  }
+  return result.data;
+}