cyber-sdd 0.6.1 → 0.7.1

package/skills/manage-scenario-bridge/scripts/manage-scenario-bridge.mts

@@ -1,159 +0,0 @@
-#!/usr/bin/env node
-// manage-scenario-bridge — the concrete curation engine for `<project-path>/.agents/sdd/scenario-bridge.toml`,
-// the one-time per-project wiring the verify-scenarios bridge and the impl-judge step-0 consumption
-// both read. It reads/writes ONLY that one project's scenario-bridge.toml — never a spec.md, status,
-// approval, or a freeze; it never runs the bridge or a test.
-//
-// Operations:
-//   --list                                        print every configured [[source]] block in order
-//   --scaffold --adapter <a> [--command <c>] --report-path <p>
-//                                                  create the config with one source block; refused
-//                                                  when the file already exists
-//   --add --adapter <a> [--command <c>] --report-path <p>
-//                                                  append a source block to an existing config;
-//                                                  refused when the file does not exist
-//
-// Every read/write is resolved beneath --project-path (a colocated project's project-path is its own
-// repo root, so the config lands at the familiar .agents/sdd/scenario-bridge.toml there).
-//
-// Reuses the verify-scenarios bridge's own SourceConfig/parseSourcesToml shape — never diverge the
-// format the reader (verify-scenarios) and the writer (this engine) agree on.
-//
-// Pure functions are exported for node:test; running the file directly drives the CLI. No deps (the
-// repo's node-≥23.6 convention).
-
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { parseSourcesToml, type SourceConfig } from '../../verify-scenarios/scripts/verify-scenarios.mts'
-
-export type { SourceConfig }
-
-const CONFIG_REL_PATH = '.agents/sdd/scenario-bridge.toml'
-
-export function configPath(projectPath: string): string {
-	return join(projectPath, CONFIG_REL_PATH)
-}
-
-// ── list ──
-
-// Every configured source in file order; a missing config lists nothing without error.
-export function listSources(projectPath: string): SourceConfig[] {
-	const file = configPath(projectPath)
-	if (!existsSync(file)) return []
-	try {
-		return parseSourcesToml(readFileSync(file, 'utf8'))
-	} catch {
-		return []
-	}
-}
-
-// ── render one [[source]] block ──
-
-function renderBlock(source: { adapter: string; command?: string; reportPath: string }): string {
-	const lines = [
-		'[[source]]',
-		`adapter    = "${source.adapter}"`,
-		...(source.command !== undefined ? [`command    = "${source.command}"`] : []),
-		`reportPath = "${source.reportPath}"`,
-	]
-	return lines.join('\n')
-}
-
-// ── scaffold / add ──
-
-export interface NewSourceInput {
-	adapter?: string
-	command?: string
-	reportPath?: string
-}
-
-export type MutateResult = { ok: true; message: string; sources: SourceConfig[] } | { ok: false; reason: string }
-
-function validateInput(
-	input: NewSourceInput,
-): { ok: true; adapter: string; command?: string; reportPath: string } | { ok: false; reason: string } {
-	if (!input.adapter || !input.reportPath) {
-		return { ok: false, reason: 'a source needs both adapter and reportPath' }
-	}
-	return { ok: true, adapter: input.adapter, command: input.command, reportPath: input.reportPath }
-}
-
-// Creates <project-path>/.agents/sdd/scenario-bridge.toml with one [[source]] block. Refuses when the
-// file already exists (use `add` instead) or when adapter/reportPath is missing — no source block is
-// written in the refused case.
-export function scaffoldSource(projectPath: string, input: NewSourceInput): MutateResult {
-	const valid = validateInput(input)
-	if (!valid.ok) return valid
-	const file = configPath(projectPath)
-	if (existsSync(file)) {
-		return { ok: false, reason: 'scenario-bridge.toml already exists; use add to append a source' }
-	}
-	mkdirSync(dirname(file), { recursive: true })
-	writeFileSync(file, `${renderBlock(valid)}\n`)
-	const sources = listSources(projectPath)
-	return { ok: true, message: `scaffolded ${file}`, sources }
-}
-
-// Appends a [[source]] block to an existing config, leaving the existing sources untouched. Refuses
-// when the config does not exist yet (names scaffold as the entry point) or when adapter/reportPath
-// is missing.
-export function addSource(projectPath: string, input: NewSourceInput): MutateResult {
-	const valid = validateInput(input)
-	if (!valid.ok) return valid
-	const file = configPath(projectPath)
-	if (!existsSync(file)) {
-		return { ok: false, reason: 'scenario-bridge.toml does not exist yet; use scaffold to create it first' }
-	}
-	const existing = readFileSync(file, 'utf8')
-	const sep = existing.endsWith('\n') ? '' : '\n'
-	writeFileSync(file, `${existing}${sep}\n${renderBlock(valid)}\n`)
-	const sources = listSources(projectPath)
-	return { ok: true, message: `added a source to ${file}`, sources }
-}
-
-// ── CLI ──
-
-function flag(argv: string[], name: string): string | undefined {
-	const i = argv.indexOf(name)
-	return i === -1 ? undefined : argv[i + 1]
-}
-
-function inputFromArgv(argv: string[]): NewSourceInput {
-	return {
-		adapter: flag(argv, '--adapter'),
-		command: flag(argv, '--command'),
-		reportPath: flag(argv, '--report-path'),
-	}
-}
-
-export function main(argv: string[]): number {
-	const projectPath = flag(argv, '--project-path') ?? '.'
-	const w = (s: string) => process.stdout.write(`${s}\n`)
-
-	if (argv.includes('--list')) {
-		for (const s of listSources(projectPath)) {
-			w(`${s.adapter}${s.command ? ` (${s.command})` : ''} -> ${s.reportPath}`)
-		}
-		return 0
-	}
-	if (argv.includes('--scaffold')) {
-		const r = scaffoldSource(projectPath, inputFromArgv(argv))
-		w(r.ok ? r.message : `refused: ${r.reason}`)
-		return r.ok ? 0 : 1
-	}
-	if (argv.includes('--add')) {
-		const r = addSource(projectPath, inputFromArgv(argv))
-		w(r.ok ? r.message : `refused: ${r.reason}`)
-		return r.ok ? 0 : 1
-	}
-
-	w(
-		'usage: manage-scenario-bridge --project-path <dir> --list | --scaffold --adapter <a> [--command <c>] --report-path <p> | --add --adapter <a> [--command <c>] --report-path <p>',
-	)
-	return 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}

package/skills/manage-spec-anchors/scripts/manage-spec-anchors.mts

@@ -1,331 +0,0 @@
-#!/usr/bin/env node
-// manage-spec-anchors — corpus/spec-anchors' concrete curation engine. Declares and curates the
-// OPT-IN extra spec anchors that discover-specs scans on top of the three fixed conventions
-// (ADR-0019). It reads/writes ONLY `.agents/sdd/spec-anchors.toml` — never a spec.md, status,
-// approval, or freeze.
-//
-// Operations:
-//   --list                  list the three fixed anchors (each explained) + every custom anchor
-//   --add <pattern>         validate + append a custom anchor (creates the config if absent)
-//   --remove <pattern>      drop a custom anchor (no-op + unchanged when absent)
-//   --edit <old> <new>      replace one custom anchor (rejects a malformed <new>)
-//   --induce <path>         candidate patterns for a sample spec dir (literal + <project> capture)
-//   --preview <pattern>     the project(s) a candidate pattern would discover, without persisting
-//
-// A pattern is a repo-relative directory pattern; `*` globs one segment, `**` globs zero or more
-// segments (any depth), `<project>` globs AND captures a segment as the spec name. Fixed conventions
-// are implicit and cannot be curated here.
-// Pure functions are exported for node:test; running the file directly drives the CLI. No deps.
-
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const ANCHORS_CONFIG = '.agents/sdd/spec-anchors.toml'
-const LIFECYCLE_STATUSES = new Set(['draft', 'approved', 'implemented', 'deprecated'])
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
-
-export interface AnchorEntry {
-	pattern: string
-	kind: 'fixed' | 'custom'
-	explanation: string
-}
-
-// The three fixed conventions, always scanned by discovery and never curated here.
-export const FIXED_ANCHORS: AnchorEntry[] = [
-	{ pattern: '.agents/spec/', kind: 'fixed', explanation: 'the repo-root single-project spec' },
-	{
-		pattern: '.agents/specs/<project>/',
-		kind: 'fixed',
-		explanation: 'each repo-root multi-project spec (the folder names the project)',
-	},
-	{
-		pattern: '<project-path>/.agents/spec/',
-		kind: 'fixed',
-		explanation: "a nested project's hoisted spec, at any depth",
-	},
-]
-
-// ── Config read/write (a minimal TOML: the `anchors = [ … ]` string array) ──
-
-export function parseAnchorsToml(text: string): string[] {
-	const m = /(^|\n)\s*anchors\s*=\s*\[([\s\S]*?)\]/.exec(text)
-	if (!m) return []
-	const out: string[] = []
-	for (const q of m[2].matchAll(/"([^"]*)"|'([^']*)'/g)) out.push((q[1] ?? q[2]).trim())
-	return out.filter((s) => s !== '')
-}
-
-export function readCustomAnchors(root: string): string[] {
-	const file = join(root, ANCHORS_CONFIG)
-	if (!existsSync(file)) return []
-	try {
-		return parseAnchorsToml(readFileSync(file, 'utf8'))
-	} catch {
-		return []
-	}
-}
-
-export function serializeAnchors(patterns: string[]): string {
-	if (patterns.length === 0) return 'anchors = []\n'
-	return `anchors = [\n${patterns.map((p) => `  "${p}",`).join('\n')}\n]\n`
-}
-
-function writeCustomAnchors(root: string, patterns: string[]): void {
-	const file = join(root, ANCHORS_CONFIG)
-	mkdirSync(dirname(file), { recursive: true })
-	writeFileSync(file, serializeAnchors(patterns))
-}
-
-// ── Validation ──
-
-// A pattern is well-formed iff it is repo-relative (no leading slash, no `..`) and every segment is
-// a literal, `*`, `**`, or the `<project>` capture token (no other `<…>` token, no empty segment).
-export function isValidPattern(pattern: string): boolean {
-	const p = pattern.trim().replace(/\\/g, '/')
-	if (p === '' || p.startsWith('/') || /(^|\/)\.\.(\/|$)/.test(p)) return false
-	const segs = p.replace(/^\/+|\/+$/g, '').split('/')
-	if (segs.some((s) => s === '')) return false
-	return segs.every((s) => s === '*' || s === '**' || s === '<project>' || !/[<>]/.test(s))
-}
-
-// True when a pattern names one of the three fixed conventions (which are implicit, not curated).
-export function isFixedConvention(pattern: string): boolean {
-	const p = pattern
-		.trim()
-		.replace(/\\/g, '/')
-		.replace(/^\/+|\/+$/g, '')
-	return (
-		p === '.agents/spec' ||
-		p === '.agents/specs/<project>' ||
-		p === '.agents/specs/*' ||
-		p.endsWith('/.agents/spec') ||
-		p.endsWith('/.agents/specs/<project>')
-	)
-}
-
-// ── list ──
-
-export function listAnchors(root: string): AnchorEntry[] {
-	const custom = readCustomAnchors(root).map(
-		(pattern): AnchorEntry => ({ pattern, kind: 'custom', explanation: 'a declared extra anchor' }),
-	)
-	return [...FIXED_ANCHORS, ...custom]
-}
-
-// ── add / remove / edit ──
-
-export type CrudResult =
-	| { ok: true; changed: boolean; anchors: string[]; message: string }
-	| { ok: false; reason: string }
-
-export function addAnchor(root: string, pattern: string): CrudResult {
-	const p = pattern.trim()
-	if (isFixedConvention(p)) return { ok: false, reason: 'that is a fixed convention — always scanned, never curated' }
-	if (!isValidPattern(p)) return { ok: false, reason: 'malformed anchor pattern' }
-	const current = readCustomAnchors(root)
-	if (current.includes(p)) return { ok: true, changed: false, anchors: current, message: 'already present' }
-	const next = [...current, p]
-	writeCustomAnchors(root, next)
-	return { ok: true, changed: true, anchors: next, message: `added ${p}` }
-}
-
-export function removeAnchor(root: string, pattern: string): CrudResult {
-	const p = pattern.trim()
-	const current = readCustomAnchors(root)
-	if (!current.includes(p)) return { ok: true, changed: false, anchors: current, message: 'nothing was removed' }
-	const next = current.filter((a) => a !== p)
-	writeCustomAnchors(root, next)
-	return { ok: true, changed: true, anchors: next, message: `removed ${p}` }
-}
-
-export function editAnchor(root: string, oldPattern: string, newPattern: string): CrudResult {
-	const oldP = oldPattern.trim()
-	const newP = newPattern.trim()
-	if (isFixedConvention(oldP)) return { ok: false, reason: 'cannot edit a fixed convention' }
-	if (!isValidPattern(newP)) return { ok: false, reason: 'malformed replacement pattern' }
-	if (isFixedConvention(newP)) return { ok: false, reason: 'replacement is a fixed convention' }
-	const current = readCustomAnchors(root)
-	if (!current.includes(oldP)) return { ok: false, reason: `no such custom anchor: ${oldP}` }
-	const next = current.map((a) => (a === oldP ? newP : a))
-	writeCustomAnchors(root, next)
-	return { ok: true, changed: true, anchors: next, message: `edited ${oldP} -> ${newP}` }
-}
-
-// ── induce ──
-
-export type InduceResult = { ok: true; candidates: string[] } | { ok: false; reason: string }
-
-// From a sample path to a spec's directory, offer a literal-directory candidate and a <project>-token
-// generalization (deepest segment replaced with the capture). Rejects a path that is not a directory
-// under the repo root.
-export function inducePatterns(root: string, samplePath: string): InduceResult {
-	const rel = samplePath
-		.trim()
-		.replace(/\\/g, '/')
-		.replace(/^\/+|\/+$/g, '')
-	if (rel === '' || /(^|\/)\.\.(\/|$)/.test(rel)) return { ok: false, reason: 'path is not repo-relative' }
-	let ok = false
-	try {
-		ok = statSync(join(root, rel)).isDirectory()
-	} catch {
-		ok = false
-	}
-	if (!ok) return { ok: false, reason: `sample path does not resolve to a directory under the repo: ${rel}` }
-	const segs = rel.split('/')
-	const generalized = [...segs.slice(0, -1), '<project>'].join('/')
-	const candidates = generalized === rel ? [rel] : [rel, generalized]
-	return { ok: true, candidates }
-}
-
-// ── preview ──
-
-interface PreviewMatch {
-	path: string
-	name: string
-}
-
-export type PreviewResult = { ok: true; matches: PreviewMatch[] } | { ok: false; reason: string }
-
-// Every dir reachable from `startDir` by descending zero or more levels (startDir itself included),
-// skipping SKIP_DIRS. Backs the `**` segment (any-depth glob) below.
-function collectDescendants(root: string, startDir: string): string[] {
-	const out = [startDir]
-	let entries: import('node:fs').Dirent[]
-	try {
-		entries = readdirSync(join(root, startDir), { withFileTypes: true })
-	} catch {
-		return out
-	}
-	for (const e of entries) {
-		if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue
-		out.push(...collectDescendants(root, startDir ? `${startDir}/${e.name}` : e.name))
-	}
-	return out
-}
-
-// Expand a pattern against the filesystem (mirrors discover-specs' expandAnchor), then keep only the
-// dirs holding a spec.md whose frontmatter status is in the lifecycle enum — the specs discovery
-// would actually surface. Does NOT read or persist anything to the config.
-export function previewPattern(root: string, pattern: string): PreviewResult {
-	const p = pattern.trim()
-	if (!isValidPattern(p)) return { ok: false, reason: 'malformed candidate pattern' }
-	const segs = p
-		.replace(/\\/g, '/')
-		.replace(/^\/+|\/+$/g, '')
-		.split('/')
-		.filter(Boolean)
-	let frontier: { dir: string; capturedName?: string }[] = [{ dir: '' }]
-	for (const seg of segs) {
-		const next: { dir: string; capturedName?: string }[] = []
-		if (seg === '**') {
-			for (const node of frontier) {
-				for (const dir of collectDescendants(root, node.dir)) next.push({ dir, capturedName: node.capturedName })
-			}
-			frontier = next
-			continue
-		}
-		const isGlob = seg === '*' || seg === '<project>'
-		for (const node of frontier) {
-			if (isGlob) {
-				let entries: import('node:fs').Dirent[]
-				try {
-					entries = readdirSync(join(root, node.dir), { withFileTypes: true })
-				} catch {
-					continue
-				}
-				for (const e of entries) {
-					if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue
-					next.push({
-						dir: node.dir ? `${node.dir}/${e.name}` : e.name,
-						capturedName: seg === '<project>' ? e.name : node.capturedName,
-					})
-				}
-			} else {
-				next.push({ dir: node.dir ? `${node.dir}/${seg}` : seg, capturedName: node.capturedName })
-			}
-		}
-		frontier = next
-	}
-	const matches: PreviewMatch[] = []
-	for (const node of frontier) {
-		const rel = node.dir ? `${node.dir}/spec.md` : 'spec.md'
-		let status: string | undefined
-		try {
-			status = /(^|\n)status:\s*["']?([a-z]+)/.exec(readFileSync(join(root, rel), 'utf8'))?.[2]
-		} catch {
-			continue
-		}
-		if (!status || !LIFECYCLE_STATUSES.has(status)) continue
-		matches.push({ path: node.dir, name: node.capturedName ?? node.dir.split('/').pop() ?? node.dir })
-	}
-	matches.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
-	return { ok: true, matches }
-}
-
-// ── CLI ──
-
-function flag(argv: string[], name: string): string | undefined {
-	const i = argv.indexOf(name)
-	return i === -1 ? undefined : argv[i + 1]
-}
-
-export function main(argv: string[]): number {
-	const root = flag(argv, '--root') ?? '.'
-	const w = (s: string) => process.stdout.write(`${s}\n`)
-
-	if (argv.includes('--list')) {
-		w('Spec anchors discovery scans (fixed conventions are always scanned):')
-		for (const a of listAnchors(root)) w(`  [${a.kind}] ${a.pattern} — ${a.explanation}`)
-		return 0
-	}
-	if (argv.includes('--add')) {
-		const r = addAnchor(root, flag(argv, '--add') ?? '')
-		w(r.ok ? r.message : `refused: ${r.reason}`)
-		return r.ok ? 0 : 1
-	}
-	if (argv.includes('--remove')) {
-		const r = removeAnchor(root, flag(argv, '--remove') ?? '')
-		w(r.ok ? r.message : `refused: ${r.reason}`)
-		return r.ok ? 0 : 1
-	}
-	if (argv.includes('--edit')) {
-		const i = argv.indexOf('--edit')
-		const r = editAnchor(root, argv[i + 1] ?? '', argv[i + 2] ?? '')
-		w(r.ok ? r.message : `refused: ${r.reason}`)
-		return r.ok ? 0 : 1
-	}
-	if (argv.includes('--induce')) {
-		const r = inducePatterns(root, flag(argv, '--induce') ?? '')
-		if (!r.ok) {
-			w(`unusable: ${r.reason}`)
-			return 1
-		}
-		w('Candidate anchor patterns:')
-		for (const c of r.candidates) w(`  ${c}`)
-		return 0
-	}
-	if (argv.includes('--preview')) {
-		const r = previewPattern(root, flag(argv, '--preview') ?? '')
-		if (!r.ok) {
-			w(`invalid: ${r.reason}`)
-			return 1
-		}
-		if (r.matches.length === 0) {
-			w('This pattern matches no project.')
-			return 0
-		}
-		w('This pattern would discover:')
-		for (const m of r.matches) w(`  ${m.path} (${m.name})`)
-		return 0
-	}
-
-	w(
-		'usage: manage-spec-anchors --list | --add <p> | --remove <p> | --edit <old> <new> | --induce <path> | --preview <p>',
-	)
-	return 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}