310 lines
11 KiB
TypeScript
310 lines
11 KiB
TypeScript
/**
|
|
* 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 };
|
|
}
|