vgxness 0.1.0

package/dist/skills/repositories/skills.js

@@ -0,0 +1,430 @@
+import { randomUUID } from 'node:crypto';
+export class SkillRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    register(input) {
+        const validation = validateSkill(input);
+        if (!validation.ok)
+            return validation;
+        const result = this.db.transaction(() => {
+            const existing = this.findByNaturalKey(input.project, input.scope, input.name);
+            const id = existing?.id ?? randomUUID();
+            const now = new Date().toISOString();
+            this.db.connection.prepare(`
+        INSERT INTO skills(id, project, scope, name, description, created_at, updated_at)
+        VALUES (@id, @project, @scope, @name, @description, @createdAt, @updatedAt)
+        ON CONFLICT(project, scope, name) DO UPDATE SET
+          description=excluded.description,
+          updated_at=excluded.updated_at
+      `).run({
+                id,
+                project: input.project,
+                scope: input.scope,
+                name: input.name,
+                description: input.description,
+                createdAt: existing?.created_at ?? now,
+                updatedAt: now,
+            });
+            const read = this.getById(id);
+            if (!read.ok)
+                throw new Error(read.error.message);
+            return read.value;
+        });
+        return result;
+    }
+    addVersion(input) {
+        const validation = validateVersion(input);
+        if (!validation.ok)
+            return validation;
+        const result = this.db.transaction(() => {
+            const skill = this.getById(input.skillId);
+            if (!skill.ok)
+                throw new SkillRegistryValidationError(skill.error.message);
+            const existing = this.findVersion(input.skillId, input.version);
+            const id = existing?.id ?? randomUUID();
+            const now = new Date().toISOString();
+            const status = input.activate === true ? 'active' : input.status ?? existing?.status ?? 'draft';
+            this.db.connection.prepare(`
+        INSERT INTO skill_versions(id, skill_id, version, source_kind, source_path, source_url, source_inline_metadata_json, compatibility_json, status, created_at)
+        VALUES (@id, @skillId, @version, @sourceKind, @sourcePath, @sourceUrl, @sourceInlineMetadataJson, @compatibilityJson, @status, @createdAt)
+        ON CONFLICT(skill_id, version) DO UPDATE SET
+          source_kind=excluded.source_kind,
+          source_path=excluded.source_path,
+          source_url=excluded.source_url,
+          source_inline_metadata_json=excluded.source_inline_metadata_json,
+          compatibility_json=excluded.compatibility_json,
+          status=excluded.status
+      `).run({
+                id,
+                skillId: input.skillId,
+                version: input.version,
+                sourceKind: input.source.kind,
+                sourcePath: input.source.path ?? null,
+                sourceUrl: input.source.url ?? null,
+                sourceInlineMetadataJson: JSON.stringify(input.source.inlineMetadata ?? {}),
+                compatibilityJson: JSON.stringify(input.compatibility ?? {}),
+                status,
+                createdAt: existing?.created_at ?? now,
+            });
+            if (input.activate === true) {
+                this.db.connection.prepare('UPDATE skills SET current_version_id=?, updated_at=? WHERE id=?').run(id, now, input.skillId);
+            }
+            const read = this.getVersion(id);
+            if (!read.ok)
+                throw new Error(read.error.message);
+            return read.value;
+        });
+        if (!result.ok && result.error.cause instanceof SkillRegistryValidationError) {
+            return validationFailure(result.error.cause.message);
+        }
+        return result;
+    }
+    attach(input) {
+        const validation = validateAttachment(input);
+        if (!validation.ok)
+            return validation;
+        const result = this.db.transaction(() => {
+            const skill = this.getById(input.skillId);
+            if (!skill.ok)
+                throw new SkillRegistryValidationError(skill.error.message);
+            if (input.versionId !== undefined)
+                assertVersionBelongsToSkill(this.db, input.versionId, input.skillId);
+            const existing = this.db.connection.prepare('SELECT * FROM skill_attachments WHERE skill_id=? AND target_type=? AND target_key=?').get(input.skillId, input.targetType, input.targetKey);
+            const id = existing?.id ?? randomUUID();
+            const now = new Date().toISOString();
+            this.db.connection.prepare(`
+        INSERT INTO skill_attachments(id, skill_id, version_id, target_type, target_key, metadata_json, created_at)
+        VALUES (@id, @skillId, @versionId, @targetType, @targetKey, @metadataJson, @createdAt)
+        ON CONFLICT(skill_id, target_type, target_key) DO UPDATE SET
+          version_id=excluded.version_id,
+          metadata_json=excluded.metadata_json
+      `).run({
+                id,
+                skillId: input.skillId,
+                versionId: input.versionId ?? null,
+                targetType: input.targetType,
+                targetKey: input.targetKey,
+                metadataJson: JSON.stringify(input.metadata ?? {}),
+                createdAt: existing?.created_at ?? now,
+            });
+            const read = this.getAttachment(id);
+            if (!read.ok)
+                throw new Error(read.error.message);
+            return read.value;
+        });
+        if (!result.ok && result.error.cause instanceof SkillRegistryValidationError) {
+            return validationFailure(result.error.cause.message);
+        }
+        return result;
+    }
+    detach(skillId, targetType, targetKey) {
+        try {
+            const result = this.db.connection.prepare('DELETE FROM skill_attachments WHERE skill_id=? AND target_type=? AND target_key=?').run(skillId, targetType, targetKey);
+            return ok({ detached: result.changes > 0 });
+        }
+        catch (cause) {
+            return fail('Failed to detach skill', cause);
+        }
+    }
+    recordUsage(input) {
+        const validation = validateUsage(input);
+        if (!validation.ok)
+            return validation;
+        const result = this.db.transaction(() => {
+            const skill = this.getById(input.skillId);
+            if (!skill.ok)
+                throw new SkillRegistryValidationError(skill.error.message);
+            if (input.versionId !== undefined)
+                assertVersionBelongsToSkill(this.db, input.versionId, input.skillId);
+            const id = randomUUID();
+            const now = new Date().toISOString();
+            this.db.connection.prepare(`
+        INSERT INTO skill_usage_records(id, skill_id, version_id, run_id, target_type, target_key, outcome, notes, created_at)
+        VALUES (@id, @skillId, @versionId, @runId, @targetType, @targetKey, @outcome, @notes, @createdAt)
+      `).run({
+                id,
+                skillId: input.skillId,
+                versionId: input.versionId ?? null,
+                runId: input.runId ?? null,
+                targetType: input.targetType ?? null,
+                targetKey: input.targetKey ?? null,
+                outcome: input.outcome,
+                notes: input.notes ?? null,
+                createdAt: now,
+            });
+            const read = this.getUsage(id);
+            if (!read.ok)
+                throw new Error(read.error.message);
+            return read.value;
+        });
+        if (!result.ok && result.error.cause instanceof SkillRegistryValidationError) {
+            return validationFailure(result.error.cause.message);
+        }
+        return result;
+    }
+    getById(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM skills WHERE id=?').get(id);
+            return row ? ok(mapSkill(row)) : missing(`Skill not found: ${id}`);
+        }
+        catch (cause) {
+            return fail('Failed to read skill', cause);
+        }
+    }
+    getByName(project, scope, name) {
+        try {
+            const row = this.findByNaturalKey(project, scope, name);
+            return row ? ok(mapSkill(row)) : missing(`Skill not found: ${project}/${scope}/${name}`);
+        }
+        catch (cause) {
+            return fail('Failed to read skill by name', cause);
+        }
+    }
+    getDetails(id) {
+        const skill = this.getById(id);
+        if (!skill.ok)
+            return skill;
+        const versions = this.listVersions(id);
+        if (!versions.ok)
+            return versions;
+        const attachments = this.listAttachments(id);
+        if (!attachments.ok)
+            return attachments;
+        const usage = this.listUsage(id);
+        if (!usage.ok)
+            return usage;
+        const details = { ...skill.value, versions: versions.value, attachments: attachments.value, usage: usage.value };
+        const currentVersion = versions.value.find((version) => version.id === skill.value.currentVersionId);
+        if (currentVersion !== undefined)
+            details.currentVersion = currentVersion;
+        return ok(details);
+    }
+    list(filters = {}) {
+        try {
+            const where = [];
+            const parameters = {};
+            if (filters.project !== undefined) {
+                where.push('project=@project');
+                parameters.project = filters.project;
+            }
+            if (filters.scope !== undefined) {
+                where.push('scope=@scope');
+                parameters.scope = filters.scope;
+            }
+            const rows = this.db.connection.prepare(`
+        SELECT * FROM skills
+        ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+        ORDER BY name ASC
+      `).all(parameters);
+            return ok(rows.map((row) => {
+                const summary = mapSkill(row);
+                if (summary.currentVersionId !== undefined) {
+                    const version = this.getVersion(summary.currentVersionId);
+                    if (version.ok)
+                        summary.currentVersion = version.value;
+                }
+                return summary;
+            }));
+        }
+        catch (cause) {
+            return fail('Failed to list skills', cause);
+        }
+    }
+    listVersions(skillId) {
+        try {
+            const rows = this.db.connection.prepare('SELECT * FROM skill_versions WHERE skill_id=? ORDER BY created_at DESC, version DESC').all(skillId);
+            return ok(rows.map(mapVersion));
+        }
+        catch (cause) {
+            return fail('Failed to list skill versions', cause);
+        }
+    }
+    listAttachments(skillId) {
+        try {
+            const rows = this.db.connection.prepare('SELECT * FROM skill_attachments WHERE skill_id=? ORDER BY target_type ASC, target_key ASC').all(skillId);
+            return ok(rows.map(mapAttachment));
+        }
+        catch (cause) {
+            return fail('Failed to list skill attachments', cause);
+        }
+    }
+    listAttachmentsForTargets(targets) {
+        try {
+            if (targets.length === 0)
+                return ok([]);
+            const rows = [];
+            const read = this.db.connection.prepare('SELECT * FROM skill_attachments WHERE target_type=? AND target_key=? ORDER BY created_at ASC, id ASC');
+            for (const target of targets)
+                rows.push(...read.all(target.targetType, target.targetKey));
+            return ok(rows.map(mapAttachment));
+        }
+        catch (cause) {
+            return fail('Failed to list skill attachments for targets', cause);
+        }
+    }
+    listUsage(skillId) {
+        try {
+            const rows = this.db.connection.prepare('SELECT * FROM skill_usage_records WHERE skill_id=? ORDER BY created_at DESC').all(skillId);
+            return ok(rows.map(mapUsage));
+        }
+        catch (cause) {
+            return fail('Failed to list skill usage', cause);
+        }
+    }
+    getVersion(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM skill_versions WHERE id=?').get(id);
+            return row ? ok(mapVersion(row)) : missing(`Skill version not found: ${id}`);
+        }
+        catch (cause) {
+            return fail('Failed to read skill version', cause);
+        }
+    }
+    getAttachment(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM skill_attachments WHERE id=?').get(id);
+            return row ? ok(mapAttachment(row)) : missing(`Skill attachment not found: ${id}`);
+        }
+        catch (cause) {
+            return fail('Failed to read skill attachment', cause);
+        }
+    }
+    getUsage(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM skill_usage_records WHERE id=?').get(id);
+            return row ? ok(mapUsage(row)) : missing(`Skill usage record not found: ${id}`);
+        }
+        catch (cause) {
+            return fail('Failed to read skill usage record', cause);
+        }
+    }
+    findByNaturalKey(project, scope, name) {
+        return this.db.connection.prepare('SELECT * FROM skills WHERE project=? AND scope=? AND name=?').get(project, scope, name);
+    }
+    findVersion(skillId, version) {
+        return this.db.connection.prepare('SELECT * FROM skill_versions WHERE skill_id=? AND version=?').get(skillId, version);
+    }
+}
+function validateSkill(input) {
+    if (!input.project.trim())
+        return validationFailure('Skill project is required');
+    if (!input.name.trim())
+        return validationFailure('Skill name is required');
+    if (!input.description.trim())
+        return validationFailure('Skill description is required');
+    return ok(undefined);
+}
+function validateVersion(input) {
+    if (!input.skillId.trim())
+        return validationFailure('Skill id is required');
+    if (!input.version.trim())
+        return validationFailure('Skill version is required');
+    if (input.source.kind === 'path' && !input.source.path?.trim())
+        return validationFailure('Path skill sources require source.path');
+    if (input.source.kind === 'url' && !input.source.url?.trim())
+        return validationFailure('URL skill sources require source.url');
+    if (input.source.kind === 'inline' && (input.source.path !== undefined || input.source.url !== undefined))
+        return validationFailure('Inline skill sources cannot include source.path or source.url');
+    return ok(undefined);
+}
+function validateAttachment(input) {
+    if (!input.skillId.trim())
+        return validationFailure('Skill id is required');
+    if (!input.targetKey.trim())
+        return validationFailure('Skill attachment target key is required');
+    return ok(undefined);
+}
+function validateUsage(input) {
+    if (!input.skillId.trim())
+        return validationFailure('Skill id is required');
+    if (input.targetType !== undefined && !input.targetKey?.trim())
+        return validationFailure('Skill usage target key is required when target type is set');
+    if (input.targetType === undefined && input.targetKey !== undefined)
+        return validationFailure('Skill usage target type is required when target key is set');
+    return ok(undefined);
+}
+function assertVersionBelongsToSkill(db, versionId, skillId) {
+    const row = db.connection.prepare('SELECT skill_id FROM skill_versions WHERE id=?').get(versionId);
+    if (row === undefined)
+        throw new SkillRegistryValidationError(`Skill version not found: ${versionId}`);
+    if (row.skill_id !== skillId)
+        throw new SkillRegistryValidationError('Skill version must belong to the attached skill');
+}
+function mapSkill(row) {
+    const skill = {
+        id: row.id,
+        project: row.project,
+        scope: row.scope,
+        name: row.name,
+        description: row.description,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+    if (row.current_version_id !== null)
+        skill.currentVersionId = row.current_version_id;
+    return skill;
+}
+function mapVersion(row) {
+    const source = { kind: row.source_kind };
+    if (row.source_path !== null)
+        source.path = row.source_path;
+    if (row.source_url !== null)
+        source.url = row.source_url;
+    const inlineMetadata = JSON.parse(row.source_inline_metadata_json ?? '{}');
+    if (Object.keys(inlineMetadata).length > 0)
+        source.inlineMetadata = inlineMetadata;
+    return {
+        id: row.id,
+        skillId: row.skill_id,
+        version: row.version,
+        source,
+        compatibility: JSON.parse(row.compatibility_json),
+        status: row.status,
+        createdAt: row.created_at,
+    };
+}
+function mapAttachment(row) {
+    const attachment = {
+        id: row.id,
+        skillId: row.skill_id,
+        targetType: row.target_type,
+        targetKey: row.target_key,
+        metadata: JSON.parse(row.metadata_json),
+        createdAt: row.created_at,
+    };
+    if (row.version_id !== null)
+        attachment.versionId = row.version_id;
+    return attachment;
+}
+function mapUsage(row) {
+    const usage = {
+        id: row.id,
+        skillId: row.skill_id,
+        outcome: row.outcome,
+        createdAt: row.created_at,
+    };
+    if (row.version_id !== null)
+        usage.versionId = row.version_id;
+    if (row.run_id !== null)
+        usage.runId = row.run_id;
+    if (row.target_type !== null)
+        usage.targetType = row.target_type;
+    if (row.target_key !== null)
+        usage.targetKey = row.target_key;
+    if (row.notes !== null)
+        usage.notes = row.notes;
+    return usage;
+}
+function ok(value) { return { ok: true, value }; }
+function missing(message) { return { ok: false, error: { code: 'not_found', message } }; }
+function validationFailure(message) { return { ok: false, error: { code: 'validation_failed', message } }; }
+function fail(message, cause) {
+    const error = { code: 'validation_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}
+class SkillRegistryValidationError extends Error {
+}

package/dist/skills/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/skills/skill-payload.js

@@ -0,0 +1,94 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+const defaultMaxSourceBytes = 64 * 1024;
+export function buildSkillInjectionPayload(resolution, options = {}) {
+    const workspaceRoot = options.workspaceRoot !== undefined ? safeRealpath(options.workspaceRoot) : undefined;
+    if (options.workspaceRoot !== undefined && workspaceRoot === undefined)
+        return validationFailure(`Workspace root is unavailable: ${options.workspaceRoot}`);
+    const maxSourceBytes = options.maxSourceBytes ?? defaultMaxSourceBytes;
+    const items = resolution.skills.map((skill, index) => toPayloadItem(skill, index, workspaceRoot, maxSourceBytes));
+    return {
+        ok: true,
+        value: {
+            version: 1,
+            providerAgnostic: true,
+            context: resolution.context,
+            items,
+            skipped: resolution.skipped,
+            warnings: ['Skill payload v1 is injection-ready data only; it does not mutate provider configuration or fetch URL sources.'],
+        },
+    };
+}
+function toPayloadItem(skill, index, workspaceRoot, maxSourceBytes) {
+    const loaded = loadContent(skill, workspaceRoot, maxSourceBytes);
+    return {
+        identity: {
+            skillId: skill.skillId,
+            name: skill.name,
+            description: skill.description,
+            versionId: skill.versionId,
+            version: skill.version,
+        },
+        source: {
+            kind: skill.source.kind,
+            ...(skill.source.path !== undefined ? { path: skill.source.path } : {}),
+            ...(skill.source.url !== undefined ? { url: skill.source.url } : {}),
+        },
+        content: loaded,
+        attachmentReasons: skill.attachmentSources,
+        ordering: {
+            index,
+            dedupeKey: skill.skillId,
+            attachmentSourceCount: skill.attachmentSources.length,
+        },
+    };
+}
+function loadContent(skill, workspaceRoot, maxSourceBytes) {
+    if (skill.source.kind === 'inline') {
+        if (skill.content !== undefined)
+            return { status: 'available', value: skill.content };
+        if (skill.summary !== undefined)
+            return { status: 'available', value: skill.summary };
+        return { status: 'unavailable', unavailableReason: 'inline_content_missing' };
+    }
+    if (skill.source.kind === 'url')
+        return { status: 'unavailable', unavailableReason: 'url_fetch_disabled' };
+    if (workspaceRoot === undefined)
+        return { status: 'unavailable', unavailableReason: 'workspace_root_required' };
+    if (skill.source.path === undefined || !skill.source.path.trim())
+        return { status: 'unavailable', unavailableReason: 'path_missing' };
+    const requested = isAbsolute(skill.source.path) ? skill.source.path : resolve(workspaceRoot, skill.source.path);
+    if (!isWithinRoot(requested, workspaceRoot))
+        return { status: 'unavailable', unavailableReason: 'path_outside_workspace' };
+    const real = safeRealpath(requested);
+    if (real === undefined)
+        return { status: 'unavailable', unavailableReason: 'path_not_found' };
+    if (!isWithinRoot(real, workspaceRoot))
+        return { status: 'unavailable', unavailableReason: 'path_outside_workspace' };
+    try {
+        const stats = statSync(real);
+        if (!stats.isFile())
+            return { status: 'unavailable', unavailableReason: 'path_not_file' };
+        if (stats.size > maxSourceBytes)
+            return { status: 'unavailable', unavailableReason: 'path_too_large' };
+        return { status: 'available', value: readFileSync(real, 'utf8') };
+    }
+    catch {
+        return { status: 'unavailable', unavailableReason: 'path_read_failed' };
+    }
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isWithinRoot(path, root) {
+    const relation = relative(root, path);
+    return relation === '' || (!relation.startsWith('..') && !isAbsolute(relation));
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/skills/skill-registry-service.js

@@ -0,0 +1,92 @@
+import { AgentRepository } from '../agents/repositories/agents.js';
+import { SkillEvaluationScenarioRepository } from './repositories/skill-evaluation-scenarios.js';
+import { SkillImprovementProposalRepository } from './repositories/skill-improvement-proposals.js';
+import { SkillRepository } from './repositories/skills.js';
+import { buildSkillInjectionPayload } from './skill-payload.js';
+import { SkillResolver } from './skill-resolver.js';
+export class SkillRegistryService {
+    database;
+    skills;
+    proposals;
+    evaluationScenarios;
+    constructor(database) {
+        this.database = database;
+        this.skills = new SkillRepository(database);
+        this.proposals = new SkillImprovementProposalRepository(database);
+        this.evaluationScenarios = new SkillEvaluationScenarioRepository(database);
+    }
+    registerSkill(input) {
+        return this.skills.register(input);
+    }
+    addSkillVersion(input) {
+        return this.skills.addVersion(input);
+    }
+    attachSkill(input) {
+        return this.skills.attach(input);
+    }
+    detachSkill(skillId, targetType, targetKey) {
+        return this.skills.detach(skillId, targetType, targetKey);
+    }
+    recordSkillUsage(input) {
+        return this.skills.recordUsage(input);
+    }
+    getSkill(id) {
+        return this.skills.getById(id);
+    }
+    getSkillByName(project, scope, name) {
+        return this.skills.getByName(project, scope, name);
+    }
+    getSkillDetails(id) {
+        return this.skills.getDetails(id);
+    }
+    listSkills(filters = {}) {
+        return this.skills.list(filters);
+    }
+    listSkillVersions(skillId) {
+        return this.skills.listVersions(skillId);
+    }
+    resolveSkills(input) {
+        return new SkillResolver(this.skills, new AgentRepository(this.database)).resolve(input);
+    }
+    createSkillImprovementProposal(input) {
+        return this.proposals.create(input);
+    }
+    listSkillImprovementProposals(filters = {}) {
+        return this.proposals.list(filters);
+    }
+    getSkillImprovementProposal(id) {
+        return this.proposals.getById(id);
+    }
+    submitSkillImprovementProposal(input) {
+        return this.proposals.submitForApproval(input);
+    }
+    approveSkillImprovementProposal(input) {
+        return this.proposals.approve(input);
+    }
+    rejectSkillImprovementProposal(input) {
+        return this.proposals.reject(input);
+    }
+    cancelSkillImprovementProposal(input) {
+        return this.proposals.cancel(input);
+    }
+    applySkillImprovementProposal(input) {
+        return this.proposals.apply(input);
+    }
+    createSkillEvaluationScenario(input) {
+        return this.evaluationScenarios.createScenario(input);
+    }
+    listSkillEvaluationScenarios(filters) {
+        return this.evaluationScenarios.listScenarios(filters);
+    }
+    recordSkillEvaluationResult(input) {
+        return this.evaluationScenarios.recordResult(input);
+    }
+    listSkillEvaluationResults(filters = {}) {
+        return this.evaluationScenarios.listResults(filters);
+    }
+    buildSkillPayload(input, options = {}) {
+        const resolution = this.resolveSkills(input);
+        return resolution.ok ? buildSkillInjectionPayload(resolution.value, options) : resolution;
+    }
+    close() { this.database.close(); }
+}