/** * Shared skill-write service (P5/D4 binding iii). * * One module, one audit trail, two callers: the agent tool layer * (`skill-tools.ts`) and the HTTP route layer (`routes/skills.ts`) both go * through here so create / update / delete are redacted, provenance-stamped, * and audited exactly once, the same way, regardless of who initiated. * * Per the D4(iii) AMENDED ruling, the agent tool does NOT call HTTP — it calls * this in-process service directly. Caller-specific side effects (skill-hash * store, agentState reload) stay in the caller; this service owns the file I/O, * redaction, provenance, and audit write. */ import * as fs from 'node:fs'; import * as path from 'node:path'; import { redactSkillContent } from './skill-redaction.js'; import type { SkillInitiator } from './skill-frontmatter.js'; import { parseSkillFrontmatter } from './skill-frontmatter.js'; import type { InstallAuditStore } from '@waggle/core'; /** Shared deps for every skill-write op. auditStore/onChange degrade gracefully. */ export interface SkillWriteDeps { /** Directory holding personal-scope SKILL.md files (~/.waggle/skills). */ skillsDir: string; /** Audit store — when present, every op records an install_audit row. */ auditStore?: InstallAuditStore; /** Called after a successful write/delete so the caller can hot-reload skills. */ onChange?: () => void; } export interface WriteSkillInput { name: string; /** Markdown content (raw or pre-generated). Redacted before persisting. */ content: string; /** Who authored this write — stamped into provenance frontmatter + audit. */ initiator: SkillInitiator; /** Where the write originated (e.g. 'chat', 'api', 'skill-creator'). */ source: string; } export interface DeleteSkillInput { name: string; initiator: SkillInitiator; source: string; } export interface SkillWriteResult { ok: boolean; /** Absolute path written/deleted (present on success). */ path?: string; /** True when the target already existed (update vs create). */ existed?: boolean; /** Secrets/paths stripped before persisting (write ops only). */ redactions?: string[]; /** Set when ok=false. */ error?: string; } /** Reject names that could escape skillsDir or collide with shell-hostile chars. */ function invalidName(name: string): boolean { return !name || !/^[a-zA-Z0-9_-]+$/.test(name); } /** Subdir under skillsDir holding pre-overwrite/pre-delete snapshots. */ const BACKUP_DIR = '.backups'; /** Newest N snapshots retained per skill; older are pruned. */ const BACKUP_KEEP = 5; function backupsDirFor(skillsDir: string): string { return path.join(skillsDir, BACKUP_DIR); } /** * Monotonic, filesystem-safe, sortable stamp (e.g. 20260710T123456789Z). It * never repeats within a process — colliding same-millisecond writes are bumped * forward — so backup filenames stay unique and lexical sort == chronological. */ let lastStampMs = 0; function nextBackupStamp(): string { let now = Date.now(); if (now <= lastStampMs) now = lastStampMs + 1; lastStampMs = now; return new Date(now).toISOString().replace(/[-:.]/g, ''); } /** * Skill name a backup filename belongs to. The stamp is the suffix after the * LAST '-' (and contains no '-' itself), so names with hyphens parse correctly. */ function backupSkillName(file: string): string | null { if (!file.endsWith('.md')) return null; const base = file.slice(0, -'.md'.length); const lastDash = base.lastIndexOf('-'); if (lastDash <= 0) return null; return base.slice(0, lastDash); } /** Backup filenames for one skill, newest first (exact-name match, not prefix). */ function backupsForSkill(skillsDir: string, name: string): string[] { const dir = backupsDirFor(skillsDir); if (!fs.existsSync(dir)) return []; return fs .readdirSync(dir) .filter((f) => backupSkillName(f) === name) .sort() .reverse(); } /** * Snapshot the current on-disk skill bytes into .backups before it is * overwritten or deleted, then prune to the newest BACKUP_KEEP. Best-effort: a * backup failure must never block the primary write/delete. */ function stashBackup(skillsDir: string, name: string): void { const filePath = path.join(skillsDir, `${name}.md`); if (!fs.existsSync(filePath)) return; try { const dir = backupsDirFor(skillsDir); if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, `${name}-${nextBackupStamp()}.md`), fs.readFileSync(filePath)); for (const stale of backupsForSkill(skillsDir, name).slice(BACKUP_KEEP)) { try { fs.unlinkSync(path.join(dir, stale)); } catch { /* best-effort prune */ } } } catch { /* backup is best-effort; never block the primary op */ } } /** * Inject/overwrite `initiator` + `source` inside the content's frontmatter * WITHOUT round-tripping through serializeFrontmatter (which is lossy — it drops * unknown keys like custom `permissions:` blocks). Provenance is authoritative: * any initiator/source the author embedded in the body is replaced, so a write * can't spoof false provenance. */ function stampProvenance(content: string, initiator: SkillInitiator, source: string): string { const provLines = [`initiator: ${initiator}`, `source: ${source}`]; if (content.startsWith('---')) { const end = content.indexOf('\n---', 3); if (end !== -1) { const block = content.slice(3, end); const afterDelimiter = end + 4; // '\n---' const rest = content.slice(afterDelimiter); // Strip any existing initiator/source lines, keep everything else. const kept = block .split('\n') .filter((l) => { const key = l.trim().toLowerCase(); return !key.startsWith('initiator:') && !key.startsWith('source:'); }); // Drop leading/trailing blank lines introduced by the filter. while (kept.length && kept[0].trim() === '') kept.shift(); while (kept.length && kept[kept.length - 1].trim() === '') kept.pop(); const newBlock = [...kept, ...provLines].join('\n'); return `---\n${newBlock}\n---${rest}`; } } // No frontmatter → prepend a minimal provenance block. return `---\n${provLines.join('\n')}\n---\n\n${content}`; } /** * Create or update a skill. Redacts secrets/paths, stamps provenance * (sticky — an update preserves the original author rather than relaundering * it), writes to disk, records an audit row, and fires onChange. */ export function writeSkill(deps: SkillWriteDeps, input: WriteSkillInput): SkillWriteResult { const { skillsDir, auditStore, onChange } = deps; const { name, content } = input; if (invalidName(name)) { return { ok: false, error: 'Invalid skill name (letters, numbers, hyphens, underscores only).' }; } const filePath = path.join(skillsDir, `${name}.md`); const existed = fs.existsSync(filePath); // FILE provenance is sticky: if the skill already exists with an author, // preserve it so an edit (by user OR agent) can't reclassify who CREATED it. // The AUDIT row, by contrast, must record who performed THIS write (the actual // actor) — D4(i) requires agent writes to audit initiator:'agent' even when // editing a user-authored skill. The two must NOT share a variable. let fileInitiator = input.initiator; let fileSource = input.source; if (existed) { try { const prior = parseSkillFrontmatter(fs.readFileSync(filePath, 'utf-8')).frontmatter; if (prior.initiator) fileInitiator = prior.initiator; if (prior.source) fileSource = prior.source; } catch { /* unreadable prior — fall back to the input provenance */ } } const { content: safe, redactions } = redactSkillContent(content); const stamped = stampProvenance(safe, fileInitiator, fileSource); if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true }); // Snapshot the outgoing bytes before overwrite so the write is undoable. if (existed) stashBackup(skillsDir, name); fs.writeFileSync(filePath, stamped, 'utf-8'); try { auditStore?.record({ capabilityName: name, capabilityType: 'skill', source: input.source, riskLevel: 'low', trustSource: 'local_user', approvalClass: 'standard', action: 'installed', initiator: input.initiator, detail: `${existed ? 'Updated' : 'Created'} skill via ${input.source}${redactions.length ? ` (redacted ${redactions.length})` : ''}.`, }); } catch { /* audit is best-effort */ } onChange?.(); return { ok: true, path: filePath, existed, redactions }; } /** * Delete a skill. Records an 'uninstalled' audit row (the action added in * P5/D4 DEC-1) and fires onChange. Returns ok=false if the skill is absent. */ export function deleteSkill(deps: SkillWriteDeps, input: DeleteSkillInput): SkillWriteResult { const { skillsDir, auditStore, onChange } = deps; const { name, initiator, source } = input; if (invalidName(name)) { return { ok: false, error: 'Invalid skill name.' }; } const filePath = path.join(skillsDir, `${name}.md`); if (!fs.existsSync(filePath)) { return { ok: false, error: `Skill "${name}" not found.` }; } // Snapshot before unlink so a delete can be undone. stashBackup(skillsDir, name); fs.unlinkSync(filePath); try { auditStore?.record({ capabilityName: name, capabilityType: 'skill', source, riskLevel: 'low', trustSource: 'local_user', approvalClass: 'standard', action: 'uninstalled', initiator, detail: `Skill deleted via ${source}.`, }); } catch { /* audit is best-effort */ } onChange?.(); return { ok: true, path: filePath }; } export interface UndoSkillInput { name: string; /** Who triggered the restore — recorded in the audit row. Defaults to 'agent'. */ initiator?: SkillInitiator; } export interface UndoSkillResult { ok: boolean; /** Absolute path of the restored skill file (present on success). */ path?: string; /** Backup filename that was restored (present on success). */ restoredFrom?: string; /** Set when ok=false. */ error?: string; } /** * Restore a skill's newest backup through the sanctioned writeSkill seam: the * snapshot bytes are re-written (source 'restored-from-backup'), which also * snapshots the current bytes as a fresh backup, records an audit row, and * fires onChange. Returns a clear error when no backup exists. */ export function undoSkillWrite(deps: SkillWriteDeps, input: UndoSkillInput): UndoSkillResult { const { skillsDir } = deps; const { name } = input; if (invalidName(name)) { return { ok: false, error: 'Invalid skill name.' }; } const newest = backupsForSkill(skillsDir, name)[0]; if (!newest) { return { ok: false, error: `No backup found for skill "${name}".` }; } let bytes: string; try { bytes = fs.readFileSync(path.join(backupsDirFor(skillsDir), newest), 'utf-8'); } catch (err) { return { ok: false, error: `Backup unreadable: ${err instanceof Error ? err.message : String(err)}` }; } const res = writeSkill(deps, { name, content: bytes, initiator: input.initiator ?? 'agent', source: 'restored-from-backup', }); if (!res.ok) return { ok: false, error: res.error }; return { ok: true, path: res.path, restoredFrom: newest }; }