akm-cli 0.6.0-rc1 → 0.6.0

package/dist/stash-providers/openviking.js

@@ -1,348 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { ConfigError, NotFoundError } from "../errors";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerStashProvider } from "../stash-provider-factory";
-import { isExpired, sanitizeString } from "./provider-utils";
-/** Per-query cache TTL in milliseconds (5 minutes). */
-const QUERY_CACHE_TTL_MS = 5 * 60 * 1000;
-/** Maximum age before query cache is considered stale but still usable (1 hour). */
-const QUERY_CACHE_STALE_MS = 60 * 60 * 1000;
-/**
- * Single source of truth for OpenViking type → akm asset type mapping.
- * Used by both search hit mapping and show response mapping.
- */
-const OV_TYPE_MAP = {
-    skill: "skill",
-    skills: "skill",
-    memory: "memory",
-    memories: "memory",
-    resource: "knowledge",
-    resources: "knowledge",
-    knowledge: "knowledge",
-    agent: "agent",
-    agents: "agent",
-    command: "command",
-    commands: "command",
-    script: "script",
-    scripts: "script",
-};
-class OpenVikingStashProvider {
-    type = "openviking";
-    name;
-    config;
-    constructor(config) {
-        this.config = config;
-        this.name = config.name ?? "openviking";
-        // Validate baseUrl scheme to prevent SSRF via file:// or other non-HTTP schemes
-        const rawUrl = config.url ?? "";
-        if (rawUrl) {
-            try {
-                const parsed = new URL(rawUrl);
-                if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-                    throw new ConfigError(`OpenViking baseUrl must use http:// or https://, got "${parsed.protocol}" in "${rawUrl}"`);
-                }
-            }
-            catch (err) {
-                if (err instanceof ConfigError)
-                    throw err;
-                throw new ConfigError(`OpenViking baseUrl is not a valid URL: "${rawUrl}"`);
-            }
-        }
-    }
-    async search(options) {
-        try {
-            const entries = await this.fetchResults(options.query, options.limit);
-            const limited = entries.slice(0, options.limit);
-            const hits = this.mapToStashHits(limited);
-            return { hits };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return { hits: [], warnings: [`Stash ${this.name}: ${message}`] };
-        }
-    }
-    async show(ref, _view) {
-        const trimmed = ref.trim();
-        // Accept both viking:// URIs (legacy/internal) and type:name refs
-        const uri = trimmed.startsWith("viking://") ? trimmed : refToVikingUri(trimmed);
-        const baseUrl = this.baseUrl;
-        const headers = this.authHeaders;
-        const [statResult, contentResult] = await Promise.all([
-            fetchOVJson(`${baseUrl}/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`, headers),
-            fetchOVJson(`${baseUrl}/api/v1/content/read?uri=${encodeURIComponent(uri)}&offset=0&limit=-1`, headers),
-        ]);
-        if (statResult == null && contentResult == null) {
-            throw new NotFoundError(`Could not fetch remote asset "${trimmed}". The OpenViking server at ${baseUrl} may be unreachable or the resource does not exist.`);
-        }
-        if (contentResult == null) {
-            throw new NotFoundError(`Content not found for remote asset "${trimmed}". The server returned metadata but no content.`);
-        }
-        const stat = (typeof statResult === "object" && statResult !== null ? statResult : {});
-        const uriPath = uri.replace(/^viking:\/\//, "");
-        // Sanitize untrusted fields to strip terminal control characters
-        const name = sanitizeString(stat.name) || uriPath.split("/").pop() || "unknown";
-        const ovType = sanitizeString(stat.type) || inferTypeFromUri(uri);
-        const assetType = OV_TYPE_MAP[ovType] ?? "knowledge";
-        const content = typeof contentResult === "string" ? contentResult : "";
-        const description = sanitizeString(stat.abstract, 1000) || undefined;
-        const assetRef = `${assetType}:${name}`;
-        return {
-            type: assetType,
-            name,
-            path: assetRef,
-            action: `Remote content from OpenViking — ${assetRef}`,
-            content,
-            description,
-            editable: false,
-            origin: "remote",
-        };
-    }
-    canShow(_ref) {
-        return !!(this.config.url ?? "").trim();
-    }
-    get baseUrl() {
-        return (this.config.url ?? "").replace(/\/+$/, "");
-    }
-    get authHeaders() {
-        const headers = {};
-        const apiKey = this.config.options?.apiKey ?? undefined;
-        if (apiKey)
-            headers.Authorization = `Bearer ${apiKey}`;
-        return headers;
-    }
-    async fetchResults(query, limit) {
-        const cachePath = this.queryCachePath(query, limit);
-        const cached = this.readQueryCache(cachePath);
-        if (cached && !isExpired(cached.mtime, QUERY_CACHE_TTL_MS)) {
-            return cached.entries;
-        }
-        const baseUrl = this.baseUrl;
-        const searchType = this.config.options?.searchType ?? "semantic";
-        try {
-            let url;
-            let body;
-            if (searchType === "text") {
-                url = `${baseUrl}/api/v1/search/grep`;
-                body = JSON.stringify({ uri: "viking://", pattern: query, case_insensitive: true });
-            }
-            else {
-                url = `${baseUrl}/api/v1/search/find`;
-                body = JSON.stringify({ query, limit });
-            }
-            const headers = { "Content-Type": "application/json", ...this.authHeaders };
-            const response = await fetchWithRetry(url, { method: "POST", headers, body }, { timeout: 10_000, retries: 1 });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
-            }
-            const data = (await response.json());
-            if (data.status !== "ok") {
-                throw new Error(data.error ?? "OpenViking returned error status");
-            }
-            const entries = parseOVSearchResponse(data.result);
-            this.writeQueryCache(cachePath, entries);
-            return entries;
-        }
-        catch (err) {
-            if (cached && !isExpired(cached.mtime, QUERY_CACHE_STALE_MS)) {
-                return cached.entries;
-            }
-            throw err;
-        }
-    }
-    mapToStashHits(entries) {
-        if (entries.length === 0)
-            return [];
-        const maxScore = entries.reduce((max, e) => Math.max(max, e.score), 0.01);
-        return entries.map((entry) => {
-            const name = sanitizeString(entry.name);
-            const abstract = sanitizeString(entry.abstract, 1000);
-            const type = sanitizeString(entry.type);
-            const assetType = OV_TYPE_MAP[type] ?? "knowledge";
-            const ref = `${assetType}:${name}`;
-            return {
-                type: assetType,
-                name,
-                path: ref,
-                ref,
-                origin: this.type,
-                editable: false,
-                description: abstract || undefined,
-                action: `akm show ${ref}`,
-                score: Math.round((entry.score / maxScore) * 1000) / 1000,
-            };
-        });
-    }
-    queryCachePath(query, limit) {
-        const cacheDir = getRegistryIndexCacheDir();
-        const hasher = createHash("md5");
-        hasher.update(this.config.url ?? "");
-        hasher.update("\0");
-        hasher.update(query.trim().toLowerCase());
-        hasher.update("\0");
-        hasher.update(String(limit));
-        hasher.update("\0");
-        const searchType = this.config.options?.searchType ?? "semantic";
-        hasher.update(searchType);
-        hasher.update("\0");
-        const apiKey = this.config.options?.apiKey ?? "";
-        hasher.update(apiKey);
-        const hash = hasher.digest("hex");
-        return path.join(cacheDir, `openviking-search-${hash}.json`);
-    }
-    readQueryCache(cachePath) {
-        try {
-            const stat = fs.statSync(cachePath);
-            const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
-            if (!Array.isArray(raw))
-                return null;
-            const entries = raw.filter(isValidOVEntry);
-            return { entries, mtime: stat.mtimeMs };
-        }
-        catch {
-            return null;
-        }
-    }
-    writeQueryCache(cachePath, entries) {
-        try {
-            const dir = path.dirname(cachePath);
-            fs.mkdirSync(dir, { recursive: true });
-            const tmpPath = `${cachePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-            // 0o600: owner read/write only — cache may contain search terms tied to API keys
-            fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
-            fs.renameSync(tmpPath, cachePath);
-        }
-        catch {
-            // Best-effort caching
-        }
-    }
-}
-// ── Self-register ───────────────────────────────────────────────────────────
-registerStashProvider("openviking", (config) => new OpenVikingStashProvider(config));
-// ── Helpers ─────────────────────────────────────────────────────────────────
-/**
- * Convert a type:name ref to a viking:// URI for the OpenViking API.
- * Maps the akm asset type back to the OV plural form (e.g. "skill" -> "skills").
- */
-function refToVikingUri(ref) {
-    const colon = ref.indexOf(":");
-    if (colon <= 0)
-        return `viking://${ref}`;
-    const name = ref.slice(colon + 1);
-    const type = ref.slice(0, colon);
-    const ovDir = AKM_TO_OV_DIR[type] ?? type;
-    return `viking://${ovDir}/${name}`;
-}
-/** Reverse map: akm asset type → OpenViking directory name (plural). */
-const AKM_TO_OV_DIR = {
-    skill: "skills",
-    memory: "memories",
-    knowledge: "resources",
-    agent: "agents",
-    command: "commands",
-    script: "scripts",
-};
-function parseOVSearchResponse(result) {
-    if (Array.isArray(result))
-        return result.filter(isValidOVEntry);
-    if (typeof result !== "object" || result === null)
-        return [];
-    const grouped = result;
-    if (Array.isArray(grouped.matches)) {
-        return deduplicateGrepMatches(grouped.matches);
-    }
-    const entries = [];
-    for (const [category, items] of Object.entries(grouped)) {
-        if (category === "total")
-            continue;
-        if (!Array.isArray(items))
-            continue;
-        for (const item of items) {
-            if (!isValidOVSearchItem(item))
-                continue;
-            entries.push({
-                uri: item.uri,
-                name: extractNameFromUri(item.uri),
-                score: item.score,
-                type: item.context_type ?? category,
-                abstract: item.abstract ?? undefined,
-            });
-        }
-    }
-    return entries;
-}
-function isValidGrepMatch(item) {
-    if (typeof item !== "object" || item === null)
-        return false;
-    const obj = item;
-    return typeof obj.uri === "string" && typeof obj.content === "string";
-}
-function deduplicateGrepMatches(matches) {
-    const byUri = new Map();
-    for (const m of matches) {
-        if (!isValidGrepMatch(m))
-            continue;
-        const existing = byUri.get(m.uri);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            const pathSegment = m.uri.replace(/^viking:\/\//, "").split("/")[0] ?? "";
-            byUri.set(m.uri, { content: m.content, count: 1, type: pathSegment });
-        }
-    }
-    const maxCount = Math.max(...[...byUri.values()].map((v) => v.count), 1);
-    const entries = [];
-    for (const [uri, { content, count, type }] of byUri) {
-        entries.push({
-            uri,
-            name: extractNameFromUri(uri),
-            score: count / maxCount,
-            type,
-            abstract: content.slice(0, 200),
-        });
-    }
-    entries.sort((a, b) => b.score - a.score);
-    return entries;
-}
-function isValidOVEntry(entry) {
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
-        return false;
-    const obj = entry;
-    return typeof obj.uri === "string" && typeof obj.name === "string" && typeof obj.score === "number";
-}
-function isValidOVSearchItem(item) {
-    if (typeof item !== "object" || item === null || Array.isArray(item))
-        return false;
-    const obj = item;
-    return typeof obj.uri === "string" && typeof obj.score === "number";
-}
-function extractNameFromUri(uri) {
-    const uriPath = uri.replace(/^viking:\/\//, "");
-    const segments = uriPath.split("/").filter(Boolean);
-    const last = segments[segments.length - 1] ?? "unknown";
-    return last.replace(/\.[^.]+$/, "");
-}
-async function fetchOVJson(url, headers) {
-    try {
-        const response = await fetchWithRetry(url, { headers }, { timeout: 10_000, retries: 1 });
-        if (!response.ok)
-            return null;
-        const data = (await response.json());
-        if (data.status !== "ok")
-            return null;
-        return data.result ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-function inferTypeFromUri(uri) {
-    const uriPath = uri.replace(/^viking:\/\//, "");
-    const firstSegment = uriPath.split("/")[0] ?? "";
-    return OV_TYPE_MAP[firstSegment] ?? "knowledge";
-}
-// ── Exports for testing ─────────────────────────────────────────────────────
-export { OpenVikingStashProvider, parseOVSearchResponse, refToVikingUri };

package/dist/stash-types.js

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

package/dist/workflow-markdown.js

@@ -1,260 +0,0 @@
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
-const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-export class WorkflowValidationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "WorkflowValidationError";
-    }
-}
-export function parseWorkflowMarkdown(markdown) {
-    const parsed = parseFrontmatter(markdown);
-    validateFrontmatter(parsed.data);
-    const title = extractWorkflowTitle(parsed.content);
-    const parameters = extractWorkflowParameters(parsed.data);
-    const tags = extractWorkflowTags(parsed.data, parsed.frontmatter);
-    const steps = extractWorkflowSteps(parsed.content);
-    return {
-        title,
-        description: toStringOrUndefined(parsed.data.description),
-        ...(tags ? { tags } : {}),
-        ...(parameters ? { parameters } : {}),
-        steps,
-    };
-}
-function validateFrontmatter(data) {
-    const unsupported = Object.keys(data).filter((key) => !ALLOWED_FRONTMATTER_KEYS.has(key));
-    if (unsupported.length > 0) {
-        throw new WorkflowValidationError(`Workflow frontmatter only supports description, tags, and params. Unsupported key(s): ${unsupported.join(", ")}`);
-    }
-}
-function extractWorkflowTitle(body) {
-    const matches = Array.from(body.matchAll(/^#\s+Workflow:\s+(.+?)\s*$/gm));
-    if (matches.length === 0) {
-        throw new WorkflowValidationError('Workflow markdown must contain a "# Workflow: <title>" heading.');
-    }
-    if (matches.length > 1) {
-        throw new WorkflowValidationError('Workflow markdown must contain exactly one "# Workflow: <title>" heading.');
-    }
-    const title = matches[0]?.[1]?.trim() ?? "";
-    if (!title) {
-        throw new WorkflowValidationError('Workflow markdown must contain a non-empty "# Workflow: <title>" heading.');
-    }
-    return title;
-}
-function extractWorkflowTags(data, frontmatter) {
-    const tags = data.tags;
-    if (typeof tags === "undefined")
-        return undefined;
-    if (typeof tags === "string") {
-        const trimmed = tags.trim();
-        return trimmed ? [trimmed] : undefined;
-    }
-    if (frontmatter &&
-        typeof tags === "object" &&
-        tags !== null &&
-        !Array.isArray(tags) &&
-        Object.keys(tags).length === 0) {
-        const blockTags = extractTagListFromFrontmatter(frontmatter);
-        if (blockTags)
-            return blockTags;
-    }
-    if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === "string" && tag.trim().length > 0)) {
-        throw new WorkflowValidationError("Workflow frontmatter `tags` must be a string or an array of non-empty strings.");
-    }
-    return tags.map((tag) => tag.trim());
-}
-function extractWorkflowParameters(data) {
-    const params = data.params;
-    if (typeof params === "undefined")
-        return undefined;
-    if (typeof params !== "object" || params === null || Array.isArray(params)) {
-        throw new WorkflowValidationError("Workflow frontmatter `params` must be a mapping of parameter names to descriptions.");
-    }
-    const entries = Object.entries(params);
-    if (entries.length === 0)
-        return undefined;
-    return entries.map(([name, description]) => {
-        if (!name.trim()) {
-            throw new WorkflowValidationError("Workflow parameter names must be non-empty.");
-        }
-        if (typeof description !== "string" || !description.trim()) {
-            throw new WorkflowValidationError(`Workflow parameter "${name}" must have a non-empty string description in frontmatter params.`);
-        }
-        return { name: name.trim(), description: description.trim() };
-    });
-}
-function extractWorkflowSteps(body) {
-    const lines = normalizeLines(body);
-    const titleLineIndex = lines.findIndex((line) => /^#\s+Workflow:\s+/.test(line));
-    if (titleLineIndex === -1) {
-        throw new WorkflowValidationError('Workflow markdown must contain a "# Workflow: <title>" heading.');
-    }
-    const steps = [];
-    let index = titleLineIndex + 1;
-    // Skip optional intro prose before the first ## Step: section.
-    while (index < lines.length && !/^##\s+Step:\s+/.test((lines[index] ?? "").trim())) {
-        const line = lines[index] ?? "";
-        const trimmed = line.trim();
-        if (trimmed.startsWith("# ") && !/^#\s+Workflow:\s+/.test(trimmed)) {
-            throw new WorkflowValidationError(`Unexpected top-level heading after workflow title: "${trimmed}".`);
-        }
-        index++;
-    }
-    while (index < lines.length) {
-        const line = lines[index] ?? "";
-        const trimmed = line.trim();
-        if (!trimmed) {
-            index++;
-            continue;
-        }
-        if (trimmed.startsWith("# ") && !/^#\s+Workflow:\s+/.test(trimmed)) {
-            throw new WorkflowValidationError(`Unexpected top-level heading after workflow title: "${trimmed}".`);
-        }
-        const stepHeader = trimmed.match(/^##\s+Step:\s+(.+?)\s*$/);
-        if (!stepHeader) {
-            throw new WorkflowValidationError(`Expected a "## Step: <title>" section after the workflow title, but found: "${trimmed}".`);
-        }
-        const stepTitle = stepHeader[1].trim();
-        const sequenceIndex = steps.length;
-        index++;
-        let stepId;
-        let instructions;
-        let completionCriteria;
-        while (index < lines.length) {
-            const current = lines[index] ?? "";
-            const currentTrimmed = current.trim();
-            if (/^##\s+Step:\s+/.test(currentTrimmed))
-                break;
-            if (/^#\s+/.test(currentTrimmed)) {
-                throw new WorkflowValidationError(`Unexpected heading "${currentTrimmed}" inside step "${stepTitle}". Only step sections and step subsections are allowed.`);
-            }
-            if (!currentTrimmed) {
-                index++;
-                continue;
-            }
-            const stepIdMatch = currentTrimmed.match(/^Step ID:\s+(.+?)\s*$/);
-            if (stepIdMatch) {
-                if (stepId) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "Step ID: <id>" line.`);
-                }
-                stepId = stepIdMatch[1].trim();
-                if (!STEP_ID_REGEX.test(stepId)) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" has invalid Step ID "${stepId}". Use letters, numbers, ".", "_" or "-".`);
-                }
-                index++;
-                continue;
-            }
-            const subsection = currentTrimmed.match(/^###\s+(.+?)\s*$/);
-            if (!subsection) {
-                throw new WorkflowValidationError(`Unexpected content in step "${stepTitle}". Add "Step ID: <id>" before subsections or move text under "### Instructions".`);
-            }
-            const subsectionName = subsection[1].trim();
-            index++;
-            const block = collectSectionBlock(lines, index);
-            index = block.nextIndex;
-            if (subsectionName === "Instructions") {
-                if (instructions) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "### Instructions" section.`);
-                }
-                instructions = block.text;
-                if (!instructions) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" must include instructions text.`);
-                }
-                continue;
-            }
-            if (subsectionName === "Completion Criteria") {
-                if (completionCriteria) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain at most one "### Completion Criteria" section.`);
-                }
-                completionCriteria = block.items;
-                if (!completionCriteria || completionCriteria.length === 0) {
-                    throw new WorkflowValidationError(`Step "${stepTitle}" has an empty "### Completion Criteria" section.`);
-                }
-                continue;
-            }
-            throw new WorkflowValidationError(`Unknown subsection "### ${subsectionName}" in step "${stepTitle}". Only "### Instructions" and optional "### Completion Criteria" are supported.`);
-        }
-        if (!stepId) {
-            throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "Step ID: <id>" line.`);
-        }
-        if (!instructions) {
-            throw new WorkflowValidationError(`Step "${stepTitle}" must contain a "### Instructions" section.`);
-        }
-        steps.push({
-            id: stepId,
-            title: stepTitle,
-            instructions,
-            ...(completionCriteria ? { completionCriteria } : {}),
-            sequenceIndex,
-        });
-    }
-    if (steps.length === 0) {
-        throw new WorkflowValidationError('Workflow markdown must contain at least one "## Step: <title>" section.');
-    }
-    const seenStepIds = new Set();
-    for (const step of steps) {
-        if (seenStepIds.has(step.id)) {
-            throw new WorkflowValidationError(`Workflow step IDs must be unique. Duplicate Step ID: "${step.id}".`);
-        }
-        seenStepIds.add(step.id);
-    }
-    return steps;
-}
-function normalizeLines(body) {
-    return body.replace(/\r\n|\r/g, "\n").split("\n");
-}
-function collectSectionBlock(lines, startIndex) {
-    const collected = [];
-    let index = startIndex;
-    while (index < lines.length) {
-        const line = lines[index] ?? "";
-        const trimmed = line.trim();
-        if (/^##\s+Step:\s+/.test(trimmed) || /^###\s+/.test(trimmed) || /^#\s+/.test(trimmed))
-            break;
-        collected.push(line);
-        index++;
-    }
-    const text = collected.join("\n").trim();
-    const items = text
-        ? text
-            .split("\n")
-            .map((line) => line.trim())
-            .filter(Boolean)
-            .map((line) => line.replace(/^[-*]\s*/, "").trim())
-            .filter(Boolean)
-        : undefined;
-    return { text, items, nextIndex: index };
-}
-function extractTagListFromFrontmatter(frontmatter) {
-    const lines = frontmatter.split("\n");
-    const tagIndex = lines.findIndex((line) => /^tags:\s*$/.test(line.trim()));
-    if (tagIndex === -1)
-        return undefined;
-    const tags = [];
-    for (let index = tagIndex + 1; index < lines.length; index++) {
-        const line = lines[index] ?? "";
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        if (!line.startsWith("  "))
-            break;
-        const match = trimmed.match(/^-\s+(.+?)\s*$/);
-        if (!match) {
-            throw new WorkflowValidationError("Workflow frontmatter `tags` must contain only dash-prefixed list items when declared as a block list.");
-        }
-        const tag = stripMatchingQuotes(match[1]?.trim() ?? "");
-        if (tag)
-            tags.push(tag);
-    }
-    return tags.length > 0 ? tags : undefined;
-}
-function stripMatchingQuotes(value) {
-    if (value.length >= 2) {
-        const quote = value[0];
-        if ((quote === '"' || quote === "'") && value[value.length - 1] === quote) {
-            return value.slice(1, -1).trim();
-        }
-    }
-    return value;
-}