@lovelybunch/api 1.0.75-alpha.0 → 1.0.75-alpha.10

package/dist/routes/api/v1/skills/route.js

@@ -0,0 +1,329 @@
+import { Hono } from 'hono';
+import { promises as fs } from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import AdmZip from 'adm-zip';
+const app = new Hono();
+const ALLOWED_ARCHIVE_HOSTS = [
+    'registry.coconut.dev',
+];
+const MAX_ARCHIVE_SIZE = 50 * 1024 * 1024; // 50 MB
+/** Paths to skip entirely when extracting zip archives (macOS resource forks, etc.) */
+const IGNORED_ZIP_PREFIXES = ['__MACOSX/', '.DS_Store'];
+function isIgnoredZipEntry(entryName) {
+    return IGNORED_ZIP_PREFIXES.some(prefix => entryName.startsWith(prefix) || entryName === prefix);
+}
+/**
+ * Detect if all zip entries share a single wrapping directory (e.g., `pptx/...`).
+ * Returns the prefix (with trailing slash) to strip, or null if no wrapper.
+ * Ignores macOS resource fork entries (__MACOSX/) when detecting the prefix.
+ */
+function detectWrapperPrefix(entries) {
+    const paths = entries
+        .map(e => e.entryName)
+        .filter(name => name !== '/' && name !== '' && !isIgnoredZipEntry(name));
+    if (paths.length === 0)
+        return null;
+    const prefixes = new Set(paths.map(p => {
+        const firstSlash = p.indexOf('/');
+        return firstSlash >= 0 ? p.substring(0, firstSlash + 1) : null;
+    }));
+    // If all entries share exactly one prefix directory, strip it
+    if (prefixes.size === 1) {
+        const prefix = [...prefixes][0];
+        if (prefix !== null)
+            return prefix;
+    }
+    return null;
+}
+/**
+ * Download a zip archive from a trusted URL and extract it into destDir.
+ * Returns true if extraction succeeded and SKILL.md exists in the output.
+ */
+async function downloadAndExtractArchive(archiveUrl, destDir) {
+    // Validate URL against allow-list
+    let parsed;
+    try {
+        parsed = new URL(archiveUrl);
+    }
+    catch {
+        throw new Error('Invalid archive URL');
+    }
+    if (!ALLOWED_ARCHIVE_HOSTS.includes(parsed.hostname)) {
+        throw new Error(`Archive host '${parsed.hostname}' is not trusted`);
+    }
+    // Download the zip
+    const response = await fetch(archiveUrl, {
+        headers: { 'User-Agent': 'coconut-api' },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to download archive: ${response.status} ${response.statusText}`);
+    }
+    const contentLength = Number(response.headers.get('content-length') || '0');
+    if (contentLength > MAX_ARCHIVE_SIZE) {
+        throw new Error(`Archive too large (${contentLength} bytes, max ${MAX_ARCHIVE_SIZE})`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > MAX_ARCHIVE_SIZE) {
+        throw new Error(`Archive too large (${buffer.length} bytes, max ${MAX_ARCHIVE_SIZE})`);
+    }
+    // Extract with path-traversal protection
+    const zip = new AdmZip(buffer);
+    const entries = zip.getEntries();
+    const wrapperPrefix = detectWrapperPrefix(entries);
+    await fs.mkdir(destDir, { recursive: true });
+    for (const entry of entries) {
+        let entryName = entry.entryName;
+        // Skip macOS resource fork junk and other ignored entries
+        if (isIgnoredZipEntry(entryName))
+            continue;
+        // Strip single wrapping directory if detected (e.g., pptx/SKILL.md -> SKILL.md)
+        if (wrapperPrefix && entryName.startsWith(wrapperPrefix)) {
+            entryName = entryName.substring(wrapperPrefix.length);
+        }
+        if (!entryName || entryName === '/')
+            continue;
+        // Reject paths that attempt directory traversal
+        const resolved = path.resolve(destDir, entryName);
+        if (!resolved.startsWith(path.resolve(destDir) + path.sep) && resolved !== path.resolve(destDir)) {
+            console.warn(`Skipping zip entry with path traversal: ${entryName}`);
+            continue;
+        }
+        if (entry.isDirectory) {
+            await fs.mkdir(resolved, { recursive: true });
+        }
+        else {
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
+            await fs.writeFile(resolved, entry.getData());
+        }
+    }
+    // Check if SKILL.md was extracted
+    try {
+        await fs.access(path.join(destDir, 'SKILL.md'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate skill name per Agent Skills spec:
+ * - 1-64 characters
+ * - Lowercase letters, numbers, hyphens only
+ * - No leading/trailing hyphens
+ * - No consecutive hyphens
+ */
+function validateSkillName(name) {
+    if (!name || name.length === 0)
+        return 'Name is required';
+    if (name.length > 64)
+        return 'Name must be 64 characters or fewer';
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(name)) {
+        return 'Name must contain only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen';
+    }
+    if (/--/.test(name))
+        return 'Name must not contain consecutive hyphens';
+    return null;
+}
+function generateSkillId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/--+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function getSkillsPath() {
+    let basePath;
+    if (process.env.NODE_ENV === 'development' && process.env.GAIT_DEV_ROOT) {
+        basePath = process.env.GAIT_DEV_ROOT;
+    }
+    else if (process.env.GAIT_DATA_PATH) {
+        basePath = path.resolve(process.env.GAIT_DATA_PATH, '.nut');
+    }
+    else {
+        basePath = path.resolve(process.cwd(), '.nut');
+    }
+    return path.join(basePath, 'skills');
+}
+/**
+ * GET /api/v1/skills
+ * Load all skill documents
+ */
+app.get('/', async (c) => {
+    try {
+        const skillsPath = getSkillsPath();
+        await fs.mkdir(skillsPath, { recursive: true });
+        const entries = await fs.readdir(skillsPath, { withFileTypes: true });
+        const skills = await Promise.all(entries
+            .filter(entry => entry.isDirectory())
+            .map(async (entry) => {
+            const skillFile = path.join(skillsPath, entry.name, 'SKILL.md');
+            try {
+                const fileContent = await fs.readFile(skillFile, 'utf-8');
+                const { data, content } = matter(fileContent);
+                const nestedMeta = typeof data.metadata === 'object' ? data.metadata : undefined;
+                const doc = {
+                    id: entry.name,
+                    name: data.name || entry.name,
+                    description: data.description || '',
+                    ...(data.license ? { license: data.license } : {}),
+                    ...(data.compatibility ? { compatibility: data.compatibility } : {}),
+                    ...(data['allowed-tools'] || data.allowedTools ? { allowedTools: data['allowed-tools'] || data.allowedTools } : {}),
+                    metadata: {
+                        name: data.name || entry.name,
+                        description: data.description || '',
+                        ...(nestedMeta || {}),
+                    },
+                    content,
+                };
+                return doc;
+            }
+            catch {
+                // Skip directories without valid SKILL.md
+                return null;
+            }
+        }));
+        const validSkills = skills.filter((s) => s !== null);
+        return c.json({
+            success: true,
+            documents: validSkills.sort((a, b) => a.id.localeCompare(b.id))
+        });
+    }
+    catch (error) {
+        console.error('Error loading skill documents:', error);
+        return c.json({
+            success: false,
+            error: 'Failed to load skill documents',
+            documents: []
+        }, 500);
+    }
+});
+/**
+ * POST /api/v1/skills
+ * Create a new skill document
+ */
+app.post('/', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (!body.name || !body.description) {
+            return c.json({ success: false, error: 'Name and description are required' }, 400);
+        }
+        const skillId = generateSkillId(body.name);
+        const nameError = validateSkillName(skillId);
+        if (nameError) {
+            return c.json({ success: false, error: nameError }, 400);
+        }
+        const skillsPath = getSkillsPath();
+        const skillDir = path.join(skillsPath, skillId);
+        // Check if skill directory already exists
+        try {
+            await fs.access(path.join(skillDir, 'SKILL.md'));
+            return c.json({ success: false, error: 'A skill with this name already exists' }, 409);
+        }
+        catch {
+            // Doesn't exist, proceed
+        }
+        // Create skill directory
+        await fs.mkdir(skillDir, { recursive: true });
+        let finalContent = body.content || '';
+        if (body.archiveUrl) {
+            // Download and extract archive — SKILL.md comes from the zip
+            try {
+                const hasSkillMd = await downloadAndExtractArchive(body.archiveUrl, skillDir);
+                if (!hasSkillMd) {
+                    // Fallback: generate SKILL.md from JSON fields if the archive didn't include one
+                    const frontmatter = {
+                        name: skillId,
+                        description: body.description,
+                    };
+                    if (body.license)
+                        frontmatter.license = body.license;
+                    if (body.compatibility)
+                        frontmatter.compatibility = body.compatibility;
+                    if (body.allowedTools)
+                        frontmatter['allowed-tools'] = body.allowedTools;
+                    if (body.metadata && Object.keys(body.metadata).length > 0) {
+                        const meta = {};
+                        for (const [key, value] of Object.entries(body.metadata)) {
+                            if (value !== undefined && value !== null) {
+                                meta[key] = value;
+                            }
+                        }
+                        if (Object.keys(meta).length > 0) {
+                            frontmatter.metadata = meta;
+                        }
+                    }
+                    const fileContent = matter.stringify(finalContent, frontmatter);
+                    await fs.writeFile(path.join(skillDir, 'SKILL.md'), fileContent, 'utf-8');
+                }
+                // Read back SKILL.md content for the response
+                try {
+                    const written = await fs.readFile(path.join(skillDir, 'SKILL.md'), 'utf-8');
+                    const { data: extractedFrontmatter, content: mdContent } = matter(written);
+                    finalContent = mdContent;
+                    // If the extracted SKILL.md body is empty but we have registry content,
+                    // append it as a fallback and rewrite the file
+                    if (!mdContent.trim() && body.content?.trim()) {
+                        const rewritten = matter.stringify(body.content, extractedFrontmatter);
+                        await fs.writeFile(path.join(skillDir, 'SKILL.md'), rewritten, 'utf-8');
+                        finalContent = body.content;
+                    }
+                }
+                catch {
+                    // best effort
+                }
+            }
+            catch (archiveError) {
+                // Clean up the directory on failure
+                await fs.rm(skillDir, { recursive: true, force: true }).catch(() => { });
+                return c.json({ success: false, error: `Archive extraction failed: ${archiveError.message}` }, 400);
+            }
+        }
+        else {
+            // No archive — build SKILL.md from JSON fields (existing behavior)
+            const frontmatter = {
+                name: skillId,
+                description: body.description,
+            };
+            if (body.license)
+                frontmatter.license = body.license;
+            if (body.compatibility)
+                frontmatter.compatibility = body.compatibility;
+            if (body.allowedTools)
+                frontmatter['allowed-tools'] = body.allowedTools;
+            if (body.metadata && Object.keys(body.metadata).length > 0) {
+                const meta = {};
+                for (const [key, value] of Object.entries(body.metadata)) {
+                    if (value !== undefined && value !== null) {
+                        meta[key] = value;
+                    }
+                }
+                if (Object.keys(meta).length > 0) {
+                    frontmatter.metadata = meta;
+                }
+            }
+            const fileContent = matter.stringify(finalContent, frontmatter);
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), fileContent, 'utf-8');
+        }
+        return c.json({
+            success: true,
+            document: {
+                id: skillId,
+                name: skillId,
+                description: body.description,
+                metadata: {
+                    name: skillId,
+                    description: body.description,
+                    ...(body.metadata || {}),
+                },
+                content: finalContent
+            }
+        }, 201);
+    }
+    catch (error) {
+        console.error('Error creating skill document:', error);
+        return c.json({ success: false, error: 'Failed to create skill document' }, 500);
+    }
+});
+export default app;

package/dist/routes/api/v1/tasks/[id]/route.d.ts

@@ -0,0 +1,351 @@
+import { Context } from 'hono';
+export declare function GET(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+    data: {
+        id: string;
+        title: string;
+        intent?: string;
+        content?: string;
+        author: {
+            type: import("@lovelybunch/core").AuthorType;
+            id: string;
+            name: string;
+            email?: string;
+        };
+        productSpecRef?: string;
+        planSteps: {
+            id: string;
+            description: string;
+            command?: string;
+            expectedOutcome?: string;
+            status: "pending" | "in-progress" | "completed" | "failed";
+            output?: string;
+            error?: string;
+            executedAt?: string;
+        }[];
+        evidence: {
+            type: "test" | "benchmark" | "screenshot" | "log" | "other";
+            description: string;
+            data: any;
+            timestamp: string;
+        }[];
+        policies: {
+            id: string;
+            name: string;
+            description: string;
+            status: "pending" | "passed" | "failed" | "skipped";
+            message?: string;
+            checkedAt?: string;
+        }[];
+        featureFlags: {
+            id: string;
+            version: string;
+            name: string;
+            description: string;
+            type: import("@lovelybunch/core").FeatureFlagType;
+            defaultValue: any;
+            scopes: string[];
+            targets: {
+                audience: string;
+                value: any;
+                percentage?: number;
+            }[];
+            killSwitch: boolean;
+            dependencies: string[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        experiments: {
+            id: string;
+            name: string;
+            hypothesis: string;
+            variants: {
+                id: string;
+                name: string;
+                description: string;
+                allocation: number;
+                config: {
+                    [x: string]: any;
+                };
+            }[];
+            allocation: {
+                method: "random" | "deterministic" | "weighted";
+                seed?: string;
+                totalAllocation: number;
+            };
+            successMetrics: string[];
+            guardrailMetrics: {
+                name: string;
+                threshold: number;
+                comparison: "greater" | "less" | "equal";
+                action: "alert" | "pause" | "stop";
+            }[];
+            stopRules: {
+                metric: string;
+                condition: string;
+                action: "stop" | "pause";
+            }[];
+            analysisConfig: {
+                confidenceLevel: number;
+                minimumSampleSize: number;
+                testType: "two-tailed" | "one-tailed";
+            };
+            status: import("@lovelybunch/core").ExperimentStatus;
+            startedAt?: string;
+            endedAt?: string;
+        }[];
+        telemetryContracts: {
+            eventName: string;
+            version: string;
+            schema: {
+                [x: string]: any;
+            };
+            piiFields: {
+                field: string;
+                classification: "none" | "quasi" | "sensitive" | "highly-sensitive";
+                handling: "clear" | "hash" | "encrypt" | "remove";
+            }[];
+            samplingRate: number;
+            retentionPolicy: {
+                duration: number;
+                archiveAfter?: number;
+                deleteAfter: number;
+            };
+            approvals: {
+                approver: string;
+                approvedAt: string;
+                comment?: string;
+            }[];
+        }[];
+        releasePlan: {
+            strategy: "immediate" | "gradual" | "scheduled" | "gated";
+            stages?: {
+                name: string;
+                percentage: number;
+                duration?: number;
+                criteria?: string[];
+            }[];
+            schedule?: string;
+            rollbackPlan?: string;
+        };
+        status: import("@lovelybunch/core").TaskStatus;
+        comments?: {
+            id: string;
+            author: string;
+            content: string;
+            createdAt: string;
+        }[];
+        metadata: {
+            createdAt: string;
+            updatedAt: string;
+            reviewers: string[];
+            aiInteractions: {
+                id: string;
+                timestamp: string;
+                model: string;
+                prompt: string;
+                response: string;
+                tokens: {
+                    prompt: number;
+                    completion: number;
+                    total: number;
+                };
+                cost?: number;
+            }[];
+            tags?: string[];
+            priority?: "low" | "medium" | "high" | "critical";
+        };
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: {
+        code: string;
+        message: any;
+    };
+}, 500, "json">)>;
+export declare function PATCH(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    success: true;
+    data: {
+        id: string;
+        title: string;
+        intent?: string;
+        content?: string;
+        author: {
+            type: import("@lovelybunch/core").AuthorType;
+            id: string;
+            name: string;
+            email?: string;
+        };
+        productSpecRef?: string;
+        planSteps: {
+            id: string;
+            description: string;
+            command?: string;
+            expectedOutcome?: string;
+            status: "pending" | "in-progress" | "completed" | "failed";
+            output?: string;
+            error?: string;
+            executedAt?: string;
+        }[];
+        evidence: {
+            type: "test" | "benchmark" | "screenshot" | "log" | "other";
+            description: string;
+            data: any;
+            timestamp: string;
+        }[];
+        policies: {
+            id: string;
+            name: string;
+            description: string;
+            status: "pending" | "passed" | "failed" | "skipped";
+            message?: string;
+            checkedAt?: string;
+        }[];
+        featureFlags: {
+            id: string;
+            version: string;
+            name: string;
+            description: string;
+            type: import("@lovelybunch/core").FeatureFlagType;
+            defaultValue: any;
+            scopes: string[];
+            targets: {
+                audience: string;
+                value: any;
+                percentage?: number;
+            }[];
+            killSwitch: boolean;
+            dependencies: string[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        experiments: {
+            id: string;
+            name: string;
+            hypothesis: string;
+            variants: {
+                id: string;
+                name: string;
+                description: string;
+                allocation: number;
+                config: {
+                    [x: string]: any;
+                };
+            }[];
+            allocation: {
+                method: "random" | "deterministic" | "weighted";
+                seed?: string;
+                totalAllocation: number;
+            };
+            successMetrics: string[];
+            guardrailMetrics: {
+                name: string;
+                threshold: number;
+                comparison: "greater" | "less" | "equal";
+                action: "alert" | "pause" | "stop";
+            }[];
+            stopRules: {
+                metric: string;
+                condition: string;
+                action: "stop" | "pause";
+            }[];
+            analysisConfig: {
+                confidenceLevel: number;
+                minimumSampleSize: number;
+                testType: "two-tailed" | "one-tailed";
+            };
+            status: import("@lovelybunch/core").ExperimentStatus;
+            startedAt?: string;
+            endedAt?: string;
+        }[];
+        telemetryContracts: {
+            eventName: string;
+            version: string;
+            schema: {
+                [x: string]: any;
+            };
+            piiFields: {
+                field: string;
+                classification: "none" | "quasi" | "sensitive" | "highly-sensitive";
+                handling: "clear" | "hash" | "encrypt" | "remove";
+            }[];
+            samplingRate: number;
+            retentionPolicy: {
+                duration: number;
+                archiveAfter?: number;
+                deleteAfter: number;
+            };
+            approvals: {
+                approver: string;
+                approvedAt: string;
+                comment?: string;
+            }[];
+        }[];
+        releasePlan: {
+            strategy: "immediate" | "gradual" | "scheduled" | "gated";
+            stages?: {
+                name: string;
+                percentage: number;
+                duration?: number;
+                criteria?: string[];
+            }[];
+            schedule?: string;
+            rollbackPlan?: string;
+        };
+        status: import("@lovelybunch/core").TaskStatus;
+        comments?: {
+            id: string;
+            author: string;
+            content: string;
+            createdAt: string;
+        }[];
+        metadata: {
+            createdAt: string;
+            updatedAt: string;
+            reviewers: string[];
+            aiInteractions: {
+                id: string;
+                timestamp: string;
+                model: string;
+                prompt: string;
+                response: string;
+                tokens: {
+                    prompt: number;
+                    completion: number;
+                    total: number;
+                };
+                cost?: number;
+            }[];
+            tags?: string[];
+            priority?: "low" | "medium" | "high" | "critical";
+        };
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: {
+        code: string;
+        message: any;
+    };
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: {
+        code: string;
+        message: any;
+    };
+}, 500, "json">)>;
+export declare function DELETE(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    success: true;
+    message: string;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: {
+        code: string;
+        message: any;
+    };
+}, 500, "json">)>;