@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/dist/src/devcli/skills.js

@@ -0,0 +1,476 @@
+// `vidfarm skills` — install/refresh multi-file agent skills into a project.
+//
+// Layout convention (matches how the vidfarm repo itself is set up):
+//   <root>/.agents/skills/<name>/           canonical install target
+//   <root>/.claude/skills/<name>            RELATIVE symlink → ../../.agents/skills/<name>
+//                                           (falls back to a real copy where
+//                                           symlinks are unavailable, e.g. Windows)
+//   <root>/skills-lock.json                 merged lock file (other tools'
+//                                           entries are preserved verbatim)
+//
+// Root resolution (defuses the cwd trap): --dir wins; else walk UP from cwd to
+// the first directory containing .agents/skills or .git; else cwd.
+//
+// Sources, in order:
+//   (a) LOCAL  — the vidfarm repo's own .agents/skills/<name>, found by walking
+//                up from this module's directory (same walk-up pattern as
+//                locateBundledSkill in src/cli.ts).
+//   (b) REMOTE — the vidfarm skill-pack routes on
+//                `${--host || VIDFARM_SKILLS_HOST || VIDFARM_HOST || https://vidfarm.cc}`:
+//                  GET /skill-pack/index.json           → { skills: [{ name, description }] }
+//                  GET /skill-pack/:name/manifest.json  → { name, files: [{ path, size, sha256 }] }
+//                  GET /skill-pack/:name/files/<relpath> → raw bytes
+//                Every downloaded file's sha256 is verified against the manifest.
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+const DEFAULT_SKILLS_HOST = "https://vidfarm.cc";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+// ── Root + source resolution ────────────────────────────────────────────────
+/** --dir wins; else walk UP from cwd to the first dir with .agents/skills or .git; else cwd. */
+export function resolveSkillsRoot(dirFlag) {
+    if (dirFlag)
+        return path.resolve(process.cwd(), dirFlag);
+    let dir = process.cwd();
+    for (let i = 0; i < 24; i += 1) {
+        if (existsSync(path.join(dir, ".agents", "skills")) || existsSync(path.join(dir, ".git"))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+}
+/** Walk up from this module (mirrors locateBundledSkill in src/cli.ts) to the
+ * vidfarm repo/package root that carries its own .agents/skills. */
+function locateLocalSkillsSource() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, ".agents", "skills");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function resolveSkillsHost(hostFlag) {
+    const raw = hostFlag
+        || process.env.VIDFARM_SKILLS_HOST
+        || process.env.VIDFARM_HOST
+        || DEFAULT_SKILLS_HOST;
+    return raw.replace(/\/+$/, "");
+}
+// ── Hashing ─────────────────────────────────────────────────────────────────
+/**
+ * Lock-file hash algorithm (locally reproducible):
+ * sha256 over the concatenation of, for EACH file sorted by its posix-style
+ * relative path: `${relpath}\0${bytes}\0` — i.e. the UTF-8 relpath, a NUL
+ * byte, the raw file bytes, and a trailing NUL byte, files in sorted order.
+ */
+export function computeSkillHash(files) {
+    const hash = createHash("sha256");
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    for (const file of sorted) {
+        hash.update(Buffer.from(file.path, "utf8"));
+        hash.update(Buffer.from([0]));
+        hash.update(file.bytes);
+        hash.update(Buffer.from([0]));
+    }
+    return hash.digest("hex");
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function readSkillDirFiles(skillDir) {
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(abs, rel);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                try {
+                    files.push({ path: rel, bytes: readFileSync(abs) });
+                }
+                catch {
+                    // unreadable entry — skip rather than abort the whole install
+                }
+            }
+        }
+    };
+    walk(skillDir, "");
+    return files;
+}
+async function fetchSkillPackIndex(host) {
+    const res = await fetch(`${host}/skill-pack/index.json`, { headers: { accept: "application/json" } });
+    if (!res.ok)
+        throw new Error(`GET ${host}/skill-pack/index.json → ${res.status}`);
+    const json = await res.json().catch(() => null);
+    const skills = Array.isArray(json?.skills) ? json.skills : [];
+    return skills
+        .filter((entry) => entry && typeof entry.name === "string")
+        .map((entry) => ({ name: entry.name, description: typeof entry.description === "string" ? entry.description : undefined }));
+}
+/** Manifest path → posix-relative path, refusing traversal segments. */
+function normalizeManifestPath(name, rawPath) {
+    const rel = rawPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (rel.split("/").some((segment) => segment === "..")) {
+        throw new Error(`skill-pack manifest for "${name}" contains an unsafe path: ${rawPath}`);
+    }
+    return rel;
+}
+async function fetchSkillManifestEntries(host, name) {
+    const manifestUrl = `${host}/skill-pack/${encodeURIComponent(name)}/manifest.json`;
+    const manifestRes = await fetch(manifestUrl, { headers: { accept: "application/json" } });
+    if (!manifestRes.ok)
+        throw new Error(`GET ${manifestUrl} → ${manifestRes.status}`);
+    const manifest = await manifestRes.json().catch(() => null);
+    const entries = Array.isArray(manifest?.files)
+        ? manifest.files.filter((f) => f && typeof f.path === "string")
+        : [];
+    if (entries.length === 0)
+        throw new Error(`skill-pack manifest for "${name}" lists no files.`);
+    return entries;
+}
+/** True when the manifest's per-file {path → sha256} set exactly matches the
+ * locally installed pack — every file present, hashes equal, no extras. Any
+ * manifest entry without a sha256 means we cannot verify → false (download). */
+function localPackMatchesManifest(root, name, entries) {
+    const skillDir = path.join(root, ".agents", "skills", name);
+    if (!existsSync(skillDir))
+        return false;
+    let local;
+    try {
+        local = readSkillDirFiles(skillDir);
+    }
+    catch {
+        return false;
+    }
+    if (local.length !== entries.length)
+        return false;
+    const localHashes = new Map(local.map((file) => [file.path, sha256Hex(file.bytes)]));
+    for (const entry of entries) {
+        const expected = entry.sha256?.trim().toLowerCase();
+        if (!expected)
+            return false;
+        const rel = normalizeManifestPath(name, entry.path);
+        if (localHashes.get(rel) !== expected)
+            return false;
+    }
+    return true;
+}
+// Bounded download parallelism — plenty for small skill files without
+// hammering the host or tripping per-origin connection limits.
+const REMOTE_FETCH_BATCH = 8;
+async function fetchRemoteSkillFiles(host, name) {
+    const entries = await fetchSkillManifestEntries(host, name);
+    // Validate every path up front (before any network round-trip)…
+    const rels = entries.map((entry) => normalizeManifestPath(name, entry.path));
+    // …then download in bounded batches, preserving manifest order and applying
+    // the same per-file sha256 verification as the sequential version.
+    const files = new Array(entries.length);
+    for (let start = 0; start < entries.length; start += REMOTE_FETCH_BATCH) {
+        const batch = entries.slice(start, start + REMOTE_FETCH_BATCH);
+        await Promise.all(batch.map(async (entry, offset) => {
+            const index = start + offset;
+            const rel = rels[index];
+            const fileUrl = `${host}/skill-pack/${encodeURIComponent(name)}/files/${rel.split("/").map(encodeURIComponent).join("/")}`;
+            const res = await fetch(fileUrl);
+            if (!res.ok)
+                throw new Error(`GET ${fileUrl} → ${res.status}`);
+            const bytes = Buffer.from(await res.arrayBuffer());
+            if (typeof entry.sha256 === "string" && entry.sha256.trim()) {
+                const actual = sha256Hex(bytes);
+                if (actual !== entry.sha256.trim().toLowerCase()) {
+                    throw new Error(`sha256 mismatch for ${name}/${rel}: manifest ${entry.sha256}, downloaded ${actual}.`);
+                }
+            }
+            files[index] = { path: rel, bytes };
+        }));
+    }
+    return files;
+}
+// ── Lock file ───────────────────────────────────────────────────────────────
+function readLockFile(root) {
+    const lockPath = path.join(root, "skills-lock.json");
+    if (!existsSync(lockPath))
+        return { version: 1, skills: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return { version: 1, skills: {} };
+        if (!parsed.skills || typeof parsed.skills !== "object")
+            parsed.skills = {};
+        if (typeof parsed.version !== "number")
+            parsed.version = 1;
+        return parsed;
+    }
+    catch {
+        throw new Error(`${lockPath} is not valid JSON — fix or remove it before installing skills.`);
+    }
+}
+// MERGE, never clobber: entries owned by other tools (sourceType !== "vidfarm")
+// ride through untouched.
+function writeLockFile(root, lock) {
+    const lockPath = path.join(root, "skills-lock.json");
+    const sortedSkills = {};
+    for (const name of Object.keys(lock.skills).sort())
+        sortedSkills[name] = lock.skills[name];
+    writeFileSync(lockPath, `${JSON.stringify({ ...lock, skills: sortedSkills }, null, 2)}\n`, "utf8");
+    return lockPath;
+}
+// ── Install machinery ───────────────────────────────────────────────────────
+function writeSkillFiles(root, name, files) {
+    const target = path.join(root, ".agents", "skills", name);
+    rmSync(target, { recursive: true, force: true });
+    for (const file of files) {
+        const dest = path.join(target, ...file.path.split("/"));
+        const resolved = path.resolve(dest);
+        if (resolved !== path.resolve(target) && !resolved.startsWith(`${path.resolve(target)}${path.sep}`)) {
+            throw new Error(`Refusing to write outside the skill dir: ${file.path}`);
+        }
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeFileSync(dest, file.bytes);
+    }
+    return target;
+}
+/** RELATIVE symlink <root>/.claude/skills/<name> → ../../.agents/skills/<name>;
+ * a real copy where symlink creation fails (e.g. Windows without dev mode). */
+function linkClaudeSkill(root, name) {
+    const claudeDir = path.join(root, ".claude", "skills");
+    mkdirSync(claudeDir, { recursive: true });
+    const linkPath = path.join(claudeDir, name);
+    const relativeTarget = path.join("..", "..", ".agents", "skills", name);
+    let existing = null;
+    try {
+        existing = lstatSync(linkPath);
+    }
+    catch {
+        // nothing there yet
+    }
+    if (existing) {
+        // unlinkSync handles symlinks (even ones pointing at directories) and
+        // plain files; only a REAL directory (previous copy-mode install) needs
+        // the recursive remove.
+        if (existing.isDirectory())
+            rmSync(linkPath, { recursive: true, force: true });
+        else
+            unlinkSync(linkPath);
+    }
+    try {
+        symlinkSync(relativeTarget, linkPath, "junction");
+        return { mode: "symlink", path: linkPath };
+    }
+    catch {
+        cpSync(path.join(root, ".agents", "skills", name), linkPath, { recursive: true });
+        return { mode: "copy", path: linkPath };
+    }
+}
+async function installSkill(root, name, host) {
+    // (a) LOCAL: the vidfarm repo's own bundled copy wins when reachable.
+    const localSource = locateLocalSkillsSource();
+    let files = null;
+    let source = "vidfarm-repo";
+    if (localSource && existsSync(path.join(localSource, name))) {
+        files = readSkillDirFiles(path.join(localSource, name));
+        if (files.length === 0)
+            files = null;
+    }
+    // (b) REMOTE: the vidfarm skill-pack routes.
+    if (!files) {
+        files = await fetchRemoteSkillFiles(host, name);
+        source = host;
+    }
+    writeSkillFiles(root, name, files);
+    const link = linkClaudeSkill(root, name);
+    const hash = computeSkillHash(files);
+    const lock = readLockFile(root);
+    lock.skills[name] = {
+        ...(lock.skills[name] ?? {}),
+        source,
+        sourceType: "vidfarm",
+        skillPath: `.agents/skills/${name}`,
+        computedHash: hash
+    };
+    writeLockFile(root, lock);
+    return { name, source, files: files.length, hash, linkMode: link.mode };
+}
+// ── Subcommands ─────────────────────────────────────────────────────────────
+async function runList(root, host, json) {
+    const lock = readLockFile(root);
+    const skillsDir = path.join(root, ".agents", "skills");
+    const onDisk = existsSync(skillsDir)
+        ? readdirSync(skillsDir).filter((name) => {
+            try {
+                return statSync(path.join(skillsDir, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+        : [];
+    const installedNames = [...new Set([...Object.keys(lock.skills), ...onDisk])].sort();
+    const installed = installedNames.map((name) => ({
+        name,
+        on_disk: onDisk.includes(name),
+        source: lock.skills[name]?.source ?? null,
+        source_type: lock.skills[name]?.sourceType ?? null
+    }));
+    let available = [];
+    let availableSource = host;
+    try {
+        available = await fetchSkillPackIndex(host);
+    }
+    catch {
+        const localSource = locateLocalSkillsSource();
+        if (localSource) {
+            availableSource = "vidfarm-repo";
+            available = readdirSync(localSource)
+                .filter((name) => existsSync(path.join(localSource, name, "SKILL.md")))
+                .map((name) => ({ name }));
+        }
+    }
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: true, root, installed, available, available_source: availableSource }, null, 2)}\n`);
+        return;
+    }
+    console.log(`${BOLD}Installed${RESET} ${DIM}(${root}/.agents/skills + skills-lock.json)${RESET}`);
+    if (installed.length === 0)
+        console.log(`  ${DIM}(none)${RESET}`);
+    for (const entry of installed) {
+        const flags = [
+            entry.on_disk ? null : "missing on disk",
+            entry.source_type && entry.source_type !== "vidfarm" ? entry.source_type : null
+        ].filter(Boolean).join(", ");
+        console.log(`  ${entry.name}${entry.source ? `  ${DIM}${entry.source}${flags ? ` [${flags}]` : ""}${RESET}` : flags ? `  ${DIM}[${flags}]${RESET}` : ""}`);
+    }
+    console.log("");
+    console.log(`${BOLD}Available${RESET} ${DIM}(${availableSource})${RESET}`);
+    const installedSet = new Set(installedNames);
+    for (const entry of available) {
+        const mark = installedSet.has(entry.name) ? `${GREEN}✓${RESET} ` : "  ";
+        console.log(`${mark}${entry.name}${entry.description ? `  ${DIM}${entry.description}${RESET}` : ""}`);
+    }
+    if (available.length === 0)
+        console.log(`  ${DIM}(index unavailable)${RESET}`);
+    console.log("");
+    console.log(`${DIM}Install with: vidfarm skills add <names…>${RESET}`);
+}
+async function runAdd(root, host, names, json) {
+    if (names.length === 0)
+        throw new Error("skills add requires one or more skill names: `vidfarm skills add hyperframes motion-graphics`.");
+    const installed = [];
+    for (const name of names) {
+        installed.push(await installSkill(root, name, host));
+    }
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: true, root, installed }, null, 2)}\n`);
+        return;
+    }
+    for (const entry of installed) {
+        console.log(`${GREEN}Installed ${entry.name}${RESET} ${DIM}(${entry.files} files from ${entry.source}; .claude/skills/${entry.name} ${entry.linkMode})${RESET}`);
+    }
+    console.log(`${DIM}Lock updated: ${path.join(root, "skills-lock.json")}${RESET}`);
+}
+async function runUpdate(root, host, json) {
+    const lock = readLockFile(root);
+    const vidfarmSkills = Object.entries(lock.skills).filter(([, entry]) => entry.sourceType === "vidfarm");
+    if (vidfarmSkills.length === 0) {
+        if (json)
+            process.stdout.write(`${JSON.stringify({ ok: true, root, updated: [], note: "no vidfarm-sourced skills in the lock file" }, null, 2)}\n`);
+        else
+            console.log(`${DIM}No vidfarm-sourced skills in ${path.join(root, "skills-lock.json")} — nothing to update.${RESET}`);
+        return;
+    }
+    const results = [];
+    // installSkill prefers the local repo copy whenever one is reachable — the
+    // remote short-circuit below only applies when the pack would actually be
+    // downloaded (no bundled copy of that skill next to this module).
+    const localSource = locateLocalSkillsSource();
+    for (const [name, entry] of vidfarmSkills) {
+        const previousHash = entry.computedHash;
+        try {
+            // Re-fetch honoring the entry's original source: repo-sourced entries
+            // refresh from the repo copy; host-sourced entries from their host.
+            const entryHost = entry.source && entry.source !== "vidfarm-repo" ? entry.source.replace(/\/+$/, "") : host;
+            const usesLocalSource = Boolean(localSource && existsSync(path.join(localSource, name)));
+            if (!usesLocalSource) {
+                // Cheap short-circuit: fetch ONLY the manifest and diff its per-file
+                // sha256 set against the installed files — skip every byte download
+                // when nothing changed. (The lock's computedHash covers file BYTES,
+                // so hashing the local files against the manifest is the
+                // lock-compatible comparison.)
+                try {
+                    const manifestEntries = await fetchSkillManifestEntries(entryHost, name);
+                    if (localPackMatchesManifest(root, name, manifestEntries)) {
+                        linkClaudeSkill(root, name); // repair a missing .claude link; no downloads
+                        results.push({ name, status: "unchanged" });
+                        continue;
+                    }
+                }
+                catch {
+                    // manifest probe failed — fall through to the full install, whose
+                    // error reporting is authoritative.
+                }
+            }
+            const result = await installSkill(root, name, entryHost);
+            results.push({ name, status: result.hash === previousHash ? "unchanged" : "changed" });
+        }
+        catch (error) {
+            results.push({ name, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: results.every((r) => r.status !== "failed"), root, updated: results }, null, 2)}\n`);
+    }
+    else {
+        for (const result of results) {
+            const color = result.status === "changed" ? GREEN : result.status === "failed" ? RED : DIM;
+            console.log(`${color}${result.status.padEnd(9)}${RESET} ${result.name}${result.detail ? ` ${DIM}${result.detail}${RESET}` : ""}`);
+        }
+    }
+    if (results.some((r) => r.status === "failed"))
+        process.exitCode = 1;
+}
+export async function runSkillsCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            dir: { type: "string" },
+            host: { type: "string" },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const sub = parsed.positionals[0] ?? "list";
+    const root = resolveSkillsRoot(parsed.values.dir);
+    const host = resolveSkillsHost(parsed.values.host);
+    const json = Boolean(parsed.values.json);
+    switch (sub) {
+        case "list":
+            await runList(root, host, json);
+            return;
+        case "add":
+            await runAdd(root, host, parsed.positionals.slice(1), json);
+            return;
+        case "update":
+            await runUpdate(root, host, json);
+            return;
+        default:
+            throw new Error(`Unknown skills subcommand "${sub}". Use: vidfarm skills <list|add <names…>|update> [--dir <root>] [--host <url>]`);
+    }
+}
+//# sourceMappingURL=skills.js.map