@aperant/framework 0.6.2

package/src/cli/route/skill-discover.mjs

@@ -0,0 +1,328 @@
+/**
+ * route/skill-discover.mjs — filesystem scan of installed skills.
+ *
+ * The router-0.3.0 envelope is built from whatever apt-<slug>/SKILL.md files
+ * live under a trusted root. No hardcoded KNOWN_SKILLS array, no manifest
+ * lookup — the filesystem is the source of truth (D-08).
+ *
+ * Trust boundary (spec §2.5 + subtask 7): only paths contained within at
+ * least one entry of `trustedSkillSources` are accepted. Defaults are:
+ *   - packages/framework/skills (dev checkouts)
+ *   - .aperant/deps/node_modules/@aperant/framework/skills (consumer installs)
+ *   - <host-cli install root>/skills (the runtime the host CLI is in)
+ * `getTrustedSkillSources()` (see config/load.mjs) resolves those for a
+ * given target dir + cli.
+ *
+ * Each discovered record is frontmatter-validated. Failures are dropped
+ * and logged to `.aperant/logs/route-dropped.jsonl` so debugging is not a
+ * needle-in-haystack.
+ */
+
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	statSync,
+} from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { SkillFrontmatterSchema } from '../skill-author/contract.mjs'
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/
+
+/**
+ * @typedef {Object} DiscoveredSkill
+ * @property {string} name
+ * @property {string} description
+ * @property {string} stage
+ * @property {string} intent
+ * @property {string} when_to_use
+ * @property {boolean} user_invocable
+ * @property {boolean} internal
+ * @property {boolean} spawns_agent
+ * @property {string|null} agent_name
+ * @property {string[]} gates
+ * @property {string} default_execution_mode
+ * @property {string[]} execution_modes
+ * @property {string} file_path           absolute path to the SKILL.md
+ */
+
+/**
+ * @typedef {Object} DiscoveredDrop
+ * @property {string} file_path
+ * @property {'outside_allowlist'|'missing_frontmatter'|'malformed_frontmatter'|'read_error'} reason
+ * @property {string[]} [errors]
+ */
+
+/**
+ * @typedef {Object} DiscoverResult
+ * @property {DiscoveredSkill[]} skills
+ * @property {DiscoveredDrop[]} dropped
+ * @property {string[]} scanned_roots
+ */
+
+/**
+ * Return true iff `file` is contained within at least one root. Both the
+ * file path and each root are resolved with `realpathSync` before comparison
+ * so that symlinks pointing outside an allowlisted root are caught.
+ *
+ * SEC-002: using `resolve()` alone (without `realpathSync`) means a symlink
+ * inside a trusted root that points outside it would still pass the
+ * containment check. `realpathSync` resolves every symlink component to its
+ * canonical on-disk path, making the check sound. When a path does not exist
+ * (e.g. a dangling symlink) we fall through to return false.
+ *
+ * @param {string} file
+ * @param {string[]} roots  absolute paths
+ * @returns {boolean}
+ */
+function pathInsideAnyRoot(file, roots) {
+	let realFile
+	try {
+		realFile = realpathSync(resolve(file))
+	} catch {
+		// Dangling symlink or path that doesn't exist — cannot be inside any root.
+		return false
+	}
+	for (const root of roots) {
+		let realRoot
+		try {
+			realRoot = realpathSync(resolve(root))
+		} catch {
+			continue
+		}
+		const rel = relative(realRoot, realFile)
+		if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return true
+	}
+	return false
+}
+
+/**
+ * Read a SKILL.md, extract + parse frontmatter, and validate. Throws on
+ * hard errors (caller catches + logs to dropped).
+ *
+ * @param {string} file  absolute path
+ * @returns {{ ok: true, record: DiscoveredSkill } | { ok: false, reason: DiscoveredDrop['reason'], errors: string[] }}
+ */
+function readSkill(file) {
+	let text
+	try {
+		text = readFileSync(file, 'utf-8')
+	} catch (err) {
+		return {
+			ok: false,
+			reason: 'read_error',
+			errors: [err && /** @type {Error} */ (err).message ? err.message : String(err)],
+		}
+	}
+	const m = text.match(FRONTMATTER_RE)
+	if (!m) {
+		return { ok: false, reason: 'missing_frontmatter', errors: ['no --- frontmatter block'] }
+	}
+	let parsed
+	try {
+		parsed = parseYaml(m[1])
+	} catch (err) {
+		return {
+			ok: false,
+			reason: 'malformed_frontmatter',
+			errors: [err && /** @type {Error} */ (err).message ? err.message : String(err)],
+		}
+	}
+	if (parsed === null || typeof parsed !== 'object') {
+		return {
+			ok: false,
+			reason: 'malformed_frontmatter',
+			errors: ['frontmatter did not parse to an object'],
+		}
+	}
+	const res = SkillFrontmatterSchema.safeParse(parsed)
+	if (!res.success) {
+		return {
+			ok: false,
+			reason: 'malformed_frontmatter',
+			errors: res.error.issues.map(
+				(i) => `${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`,
+			),
+		}
+	}
+	const d = res.data
+	return {
+		ok: true,
+		record: {
+			name: d.name,
+			description: d.description,
+			stage: d.stage,
+			intent: d.intent,
+			when_to_use: d.when_to_use,
+			user_invocable: d.user_invocable,
+			internal: d.internal,
+			spawns_agent: d.spawns_agent,
+			agent_name: d.agent_name ?? null,
+			gates: Array.isArray(d.gates) ? [...d.gates] : [],
+			default_execution_mode: d.default_execution_mode,
+			execution_modes: Array.isArray(d.execution_modes) ? [...d.execution_modes] : [],
+			file_path: file,
+		},
+	}
+}
+
+/**
+ * Walk a single root and return every apt-<slug>/SKILL.md it contains.
+ *
+ * @param {string} root  absolute path; return [] silently if root doesn't exist.
+ */
+function walkSkillRoot(root) {
+	const out = []
+	if (!existsSync(root)) return out
+	let stat
+	try {
+		stat = statSync(root)
+	} catch {
+		return out
+	}
+	if (!stat.isDirectory()) return out
+	let entries
+	try {
+		entries = readdirSync(root, { withFileTypes: true })
+	} catch {
+		return out
+	}
+	for (const entry of entries) {
+		if (!entry.name.startsWith('apt')) continue
+		const sub = join(root, entry.name)
+		if (entry.isDirectory()) {
+			const skillFile = join(sub, 'SKILL.md')
+			if (existsSync(skillFile)) out.push(skillFile)
+		}
+		// Top-level apt-*.md files (e.g. skills/apt-planner.md) are
+		// intentionally ignored by the router — they're agent definitions
+		// consumed by the spawn path, not skills the user picks from a
+		// classification menu.
+	}
+	return out
+}
+
+/**
+ * Append one dropped record to .aperant/logs/route-dropped.jsonl. Best-
+ * effort — if the log dir can't be created we swallow the error (the
+ * router still returns the envelope without the skill).
+ *
+ * @param {string} targetDir
+ * @param {DiscoveredDrop} drop
+ */
+function logDropped(targetDir, drop) {
+	try {
+		const logDir = join(targetDir, '.aperant', 'logs')
+		mkdirSync(logDir, { recursive: true })
+		appendFileSync(
+			join(logDir, 'route-dropped.jsonl'),
+			`${JSON.stringify({ ts: new Date().toISOString(), ...drop })}\n`,
+			'utf-8',
+		)
+	} catch {
+		/* best-effort: never block the hot path on log I/O */
+	}
+}
+
+/**
+ * Process-level cache for discoverSkills results keyed by the sorted,
+ * joined set of resolved trustedSkillSources roots. This memoization
+ * is intentionally cheap and narrow:
+ *
+ *   - Key: sorted joined resolved roots (captures which dirs to scan)
+ *   - TTL: 1 second (covers test-harness multi-call patterns without
+ *     returning stale data in long-running watch processes)
+ *   - Invalidation: the TTL is the only eviction — the cache does NOT
+ *     attempt to detect filesystem changes (inotify/kqueue is out of
+ *     scope for a single-invocation CLI).
+ *
+ * Single CLI invocations (the primary use case) see no observable change;
+ * test harnesses that call discoverSkills 14×+ within one second benefit.
+ *
+ * @type {Map<string, { result: DiscoverResult, expiresAt: number }>}
+ */
+const _discoverCache = new Map()
+const _DISCOVER_CACHE_TTL_MS = 1_000
+
+/**
+ * Scan the trusted skill sources and return discovered skill records.
+ * Skills whose file path is not inside one of the trusted roots are
+ * dropped and logged (trust boundary).
+ *
+ * Results are memoized for up to 1 second per unique set of resolved
+ * trustedSkillSources roots (PRF-001). The memoization wraps the
+ * containment-checked scan so the security boundary is never bypassed.
+ *
+ * @param {Object} opts
+ * @param {string} opts.targetDir              project root (used for log dest)
+ * @param {string[]} opts.trustedSkillSources  absolute paths
+ * @returns {DiscoverResult}
+ */
+export function discoverSkills({ targetDir, trustedSkillSources }) {
+	// Build a stable cache key from the sorted resolved roots.
+	const resolvedRoots = (trustedSkillSources || []).map((r) => resolve(r)).sort()
+	const cacheKey = resolvedRoots.join('\0')
+	const now = Date.now()
+	const cached = _discoverCache.get(cacheKey)
+	if (cached && cached.expiresAt > now) {
+		return cached.result
+	}
+	const result = _discoverSkillsUncached({ targetDir, trustedSkillSources })
+	_discoverCache.set(cacheKey, { result, expiresAt: now + _DISCOVER_CACHE_TTL_MS })
+	return result
+}
+
+/**
+ * Internal uncached implementation — called by discoverSkills after
+ * cache miss. Do not call directly; always go through discoverSkills so
+ * the memoization layer is in effect.
+ *
+ * @param {Object} opts
+ * @param {string} opts.targetDir
+ * @param {string[]} opts.trustedSkillSources
+ * @returns {DiscoverResult}
+ */
+function _discoverSkillsUncached({ targetDir, trustedSkillSources }) {
+	const roots = (trustedSkillSources || []).map((r) => resolve(r)).filter((r) => existsSync(r))
+
+	const skillsByName = new Map()
+	const dropped = []
+
+	for (const root of roots) {
+		for (const file of walkSkillRoot(root)) {
+			if (!pathInsideAnyRoot(file, roots)) {
+				const drop = { file_path: file, reason: 'outside_allowlist' }
+				dropped.push(drop)
+				logDropped(targetDir, drop)
+				continue
+			}
+			const res = readSkill(file)
+			if (!res.ok) {
+				const drop = { file_path: file, reason: res.reason, errors: res.errors }
+				dropped.push(drop)
+				logDropped(targetDir, drop)
+				continue
+			}
+			// First-writer-wins on duplicate names. Since roots are ordered
+			// (dev → consumer → host-cli install root) by getTrustedSkillSources,
+			// the first-resolved copy (typically the dev checkout) ends up in
+			// the envelope. That ordering is load-bearing — it means work on a
+			// local dev branch is always what gets classified, even when a
+			// consumer-install copy also exists in .aperant/deps.
+			if (!skillsByName.has(res.record.name)) {
+				skillsByName.set(res.record.name, res.record)
+			}
+		}
+	}
+
+	const skills = Array.from(skillsByName.values()).sort((a, b) => a.name.localeCompare(b.name))
+	return {
+		skills,
+		dropped,
+		scanned_roots: roots,
+	}
+}

package/src/cli/seeds/io.mjs

@@ -0,0 +1,150 @@
+/**
+ * seeds/io.mjs — seeds.json read/write primitives (C12).
+ *
+ * Seeds are the long-running thematic tier ABOVE milestones. Unlike the
+ * per-scope roadmap (`.aperant/roadmap/{scope}/milestones.json`), seeds are
+ * cross-scope by design — a single "Close parity gaps" initiative can span
+ * `framework` and `project` work. They therefore live in a single top-level
+ * file:
+ *
+ *   .aperant/roadmap/seeds.json
+ *
+ * Spec: docs/frameworks/spec-gaps.md#c12 — section 4a of the task spec.
+ *
+ * Shape:
+ *   {
+ *     version: 1,
+ *     updated_at: ISO-8601,
+ *     seeds: [
+ *       {
+ *         id: string,               // unique, kebab-case recommended
+ *         title: string,
+ *         goal?: string,
+ *         status: 'active' | 'dormant' | 'completed' | 'archived',
+ *         milestones: [             // cross-scope refs
+ *           { scope: string, milestone_id: string },
+ *           ...
+ *         ],
+ *         created_at: ISO-8601,
+ *         closed_at: ISO-8601 | null,
+ *         notes_url?: string,
+ *         history?: Array<{...}>    // optional audit trail (--force --reason)
+ *       },
+ *       ...
+ *     ]
+ *   }
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { atomicWriteJson } from '../util/atomic-write.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+
+/**
+ * Absolute path to seeds.json for a project root.
+ */
+export function seedsJsonPath(targetDir) {
+	return join(targetDir, '.aperant', 'roadmap', 'seeds.json')
+}
+
+/**
+ * Return an empty seeds file with the current schema version.
+ */
+export function emptySeedsFile() {
+	return {
+		version: 1,
+		updated_at: new Date().toISOString(),
+		seeds: [],
+	}
+}
+
+/**
+ * Load `seeds.json`. Returns `null` when the file does not exist so callers can
+ * distinguish "zero seeds declared" (file absent — AC9: no warning, no
+ * migration required) from "seeds declared but empty array".
+ */
+export function loadSeeds(targetDir) {
+	const path = seedsJsonPath(targetDir)
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		// Malformed seeds.json — surface as null so callers can either fail or
+		// treat as absent. The CLI layer gives a clearer error than the parser.
+		return null
+	}
+}
+
+/**
+ * Load seeds, filling in the empty file shape when absent. Used by read paths
+ * that want an always-valid object to iterate over.
+ */
+export function loadSeedsOrEmpty(targetDir) {
+	return loadSeeds(targetDir) || emptySeedsFile()
+}
+
+/**
+ * Atomic save. Stamps `updated_at`, acquires an exclusive lock on seeds.json,
+ * writes via atomicWriteJson (tmp+fsync+rename).
+ *
+ * NOTE: callers that need to coordinate a two-sided write with
+ * milestones.json (e.g. `seed assign` / `seed unassign` / delete-seed) must
+ * take their own outer `withFileLock(seedsJsonPath)` and call
+ * `writeSeedsUnlocked` from inside it so the outer lock spans both sides.
+ * Mirrors `commands/roadmap.mjs:327-368` — seeds.json lock is always the
+ * OUTER lock; `saveRoadmapForScope` takes a milestones.json lock inside.
+ */
+export function saveSeeds(targetDir, seedsFile) {
+	const path = seedsJsonPath(targetDir)
+	const stamped = { ...seedsFile, version: seedsFile.version || 1 }
+	stamped.updated_at = new Date().toISOString()
+	stamped.seeds = stamped.seeds || []
+	mkdirSync(dirname(path), { recursive: true })
+	withFileLock(
+		path,
+		() => {
+			atomicWriteJson(path, stamped)
+		},
+		{ projectRoot: targetDir },
+	)
+	return stamped
+}
+
+/**
+ * Write seeds file WITHOUT taking its lock. Callers MUST already hold the
+ * seeds.json lock (see `saveSeeds` comment). Used by the two-sided atomic
+ * write path in `seed assign` / `seed unassign`.
+ */
+export function writeSeedsUnlocked(targetDir, seedsFile) {
+	const path = seedsJsonPath(targetDir)
+	const stamped = { ...seedsFile, version: seedsFile.version || 1 }
+	stamped.updated_at = new Date().toISOString()
+	stamped.seeds = stamped.seeds || []
+	mkdirSync(dirname(path), { recursive: true })
+	atomicWriteJson(path, stamped)
+	return stamped
+}
+
+/**
+ * Find a seed by id. Returns `undefined` when not found.
+ */
+export function findSeed(seedsFile, seedId) {
+	if (!seedsFile || !Array.isArray(seedsFile.seeds)) return undefined
+	return seedsFile.seeds.find((s) => s.id === seedId)
+}
+
+/**
+ * Find the seed (if any) that owns a given (scope, milestone_id) ref.
+ * Returns the seed record or `undefined`.
+ */
+export function findSeedForMilestone(seedsFile, scope, milestoneId) {
+	if (!seedsFile || !Array.isArray(seedsFile.seeds)) return undefined
+	for (const seed of seedsFile.seeds) {
+		for (const ref of seed.milestones || []) {
+			if (ref && ref.scope === scope && ref.milestone_id === milestoneId) {
+				return seed
+			}
+		}
+	}
+	return undefined
+}

package/src/cli/seeds/render.mjs

@@ -0,0 +1,171 @@
+/**
+ * seeds/render.mjs — seeds.json → SEEDS.md renderer (C12, AC7).
+ *
+ * Mirrors `roadmap/render.mjs` in spirit: pure string-producing function that
+ * takes the already-loaded seeds file + a Map<scope, roadmap> + the raw
+ * state.json for task counting. All I/O happens in the caller (commands/roadmap.mjs).
+ *
+ * Layout:
+ *   # Seeds
+ *   *{n} active · {m} other · Last updated: ISO*
+ *
+ *   ## <Seed title>                         ← H2 per active seed
+ *   **Goal:** …
+ *   **Status:** active · **Tasks:** 12 active / 25 completed
+ *   *Notes: <notes_url>* (when present)
+ *
+ *   | Scope | Milestone | Phases (done / total) | Tasks |
+ *   |…|
+ *
+ *   ## Dormant / completed / archived        ← single H2 footer
+ *   - **seed-a** (dormant) — 3 milestones · 7 tasks
+ *   - …
+ *
+ * The footer groups everything non-active into one bullet list so readers
+ * skimming SEEDS.md don't page through finished initiatives. A seed with
+ * zero milestones still renders — operators need to see empty seeds they've
+ * just created so they can assign milestones.
+ */
+
+/**
+ * Build the task count map (scope, milestone_id) → {active, completed}.
+ * Walks state.json once and hashes per (scope, milestone_id) key so seed
+ * rendering is O(milestones) not O(seeds × milestones × tasks).
+ */
+function buildTaskCountIndex(state) {
+	const index = new Map() // key=`${scope}\0${milestone_id}` → {active,completed}
+	const bump = (scope, milestoneId, bucket) => {
+		if (!milestoneId) return
+		const key = `${scope || 'project'}\u0000${milestoneId}`
+		let rec = index.get(key)
+		if (!rec) {
+			rec = { active: 0, completed: 0 }
+			index.set(key, rec)
+		}
+		rec[bucket] += 1
+	}
+	for (const t of Object.values(state?.active_tasks || {})) {
+		if (!t) continue
+		bump(t.scope, t.milestone_id, 'active')
+	}
+	for (const t of state?.completed_tasks || []) {
+		if (!t) continue
+		bump(t.scope, t.milestone_id, 'completed')
+	}
+	return index
+}
+
+function tasksFor(index, scope, milestoneId) {
+	return index.get(`${scope || 'project'}\u0000${milestoneId}`) || { active: 0, completed: 0 }
+}
+
+/**
+ * Look up a milestone by (scope, milestone_id) across the preloaded roadmap map.
+ * Returns the milestone object or null. Caller handles null (orphan ref).
+ */
+function resolveMilestone(roadmapsByScope, scope, milestoneId) {
+	const rm = roadmapsByScope instanceof Map ? roadmapsByScope.get(scope) : roadmapsByScope?.[scope]
+	if (!rm || !Array.isArray(rm.milestones)) return null
+	return rm.milestones.find((m) => m.id === milestoneId) || null
+}
+
+/**
+ * Count phase done/total for a milestone row. "Done" = status completed or skipped.
+ */
+function milestonePhaseProgress(milestone) {
+	const phases = milestone?.phases || []
+	const done = phases.filter((p) => p.status === 'completed' || p.status === 'skipped').length
+	return { done, total: phases.length }
+}
+
+/**
+ * Escape a pipe so it renders literally in a GFM table cell.
+ */
+function esc(s) {
+	return String(s ?? '').replace(/\|/g, '\\|')
+}
+
+/**
+ * renderSeedsMd(seedsFile, roadmapsByScope, state) → markdown string.
+ *
+ * Renders the canonical SEEDS.md content. Pure — no I/O.
+ *
+ * @param seedsFile loaded seeds.json contents
+ * @param roadmapsByScope Map<scope, roadmap> OR plain object keyed by scope
+ * @param state loaded state.json contents (for task counts); null is fine
+ */
+export function renderSeedsMd(seedsFile, roadmapsByScope, state) {
+	const seeds = (seedsFile?.seeds || []).slice()
+	const active = seeds.filter((s) => (s.status || 'active') === 'active')
+	const dormant = seeds.filter((s) => (s.status || 'active') !== 'active')
+	const updatedAt = seedsFile?.updated_at || new Date().toISOString()
+	const index = buildTaskCountIndex(state || {})
+
+	const lines = []
+	lines.push('# Seeds', '')
+	lines.push(`*${active.length} active · ${dormant.length} other · Last updated: ${updatedAt}*`, '')
+
+	if (active.length === 0 && dormant.length === 0) {
+		lines.push('_No seeds declared. Run `apt-tools seed create --id <id> --title <title>`._', '')
+	}
+
+	// Active seeds — full H2 section each.
+	for (const seed of active) {
+		const refs = seed.milestones || []
+		let seedActive = 0
+		let seedCompleted = 0
+		for (const ref of refs) {
+			const c = tasksFor(index, ref.scope, ref.milestone_id)
+			seedActive += c.active
+			seedCompleted += c.completed
+		}
+
+		lines.push(`## ${seed.title || seed.id}`, '')
+		if (seed.goal) lines.push(`**Goal:** ${seed.goal}`, '')
+		lines.push(`**ID:** \`${seed.id}\` · **Status:** ${seed.status || 'active'}`, '')
+		lines.push(`**Tasks:** ${seedActive} active / ${seedCompleted} completed`, '')
+		if (seed.notes_url) {
+			lines.push(`*Notes: ${seed.notes_url}*`, '')
+		}
+
+		if (refs.length === 0) {
+			lines.push('_No milestones assigned yet. Run `apt-tools seed assign`._', '')
+			continue
+		}
+
+		lines.push('| Scope | Milestone | Phases (done / total) | Tasks |')
+		lines.push('|-------|-----------|-----------------------|-------|')
+		for (const ref of refs) {
+			const ms = resolveMilestone(roadmapsByScope, ref.scope, ref.milestone_id)
+			const title = ms?.title || ref.milestone_id
+			const { done, total } = milestonePhaseProgress(ms)
+			const counts = tasksFor(index, ref.scope, ref.milestone_id)
+			const phaseCell = ms ? `${done} / ${total}` : '_orphan ref_'
+			lines.push(
+				`| ${esc(ref.scope)} | **${esc(title)}** (\`${esc(ref.milestone_id)}\`) | ${phaseCell} | ${counts.active} / ${counts.completed} |`,
+			)
+		}
+		lines.push('')
+	}
+
+	// Dormant / completed / archived — compact footer.
+	if (dormant.length > 0) {
+		lines.push('## Dormant / completed / archived', '')
+		for (const seed of dormant) {
+			const refs = seed.milestones || []
+			let seedTasks = 0
+			for (const ref of refs) {
+				const c = tasksFor(index, ref.scope, ref.milestone_id)
+				seedTasks += c.active + c.completed
+			}
+			const closed = seed.closed_at ? ` · closed ${seed.closed_at}` : ''
+			lines.push(
+				`- **${seed.title || seed.id}** \`${seed.id}\` (${seed.status})${closed} — ${refs.length} milestones · ${seedTasks} tasks`,
+			)
+		}
+		lines.push('')
+	}
+
+	lines.push('---', '', '*Auto-generated from `.aperant/roadmap/seeds.json` by apt-tools*', '')
+	return lines.join('\n')
+}