loadout-ai 0.1.0

package/dist/src/core/skills.js

@@ -0,0 +1,208 @@
+import { cp, lstat, readdir, readFile, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ensureDirectory } from "./paths.js";
+import { assertSkillSecurity, scanSkillSecurity } from "./skill-security.js";
+export async function discoverSkillDirectories(root, options = {}) {
+    const result = [];
+    async function visit(directory, depth) {
+        if (depth > 4)
+            return;
+        let entries;
+        try {
+            const directoryStat = await lstat(directory);
+            if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+                if (directoryStat.isSymbolicLink())
+                    throw new Error(`Refusing symlink or non-directory package path: ${directory}`);
+                return;
+            }
+            entries = await readdir(directory);
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.startsWith("Refusing symlink"))
+                throw error;
+            return;
+        }
+        if (entries.includes("SKILL.md")) {
+            const skillPath = join(directory, "SKILL.md");
+            let name;
+            try {
+                const skillStat = await lstat(skillPath);
+                if (skillStat.isFile() && !skillStat.isSymbolicLink()) {
+                    const frontmatter = await readFile(skillPath, "utf8");
+                    name = frontmatter.match(/^name:\s*(\S+)/m)?.[1];
+                }
+            }
+            catch {
+                // Selected invalid skills are rejected by validateSkillDirectory below.
+            }
+            if (options.include &&
+                !options.include({
+                    path: directory,
+                    ...(name ? { name } : {}),
+                    targetName: directory.split(sep).at(-1) ?? "skill",
+                }))
+                return;
+            await validateSkillDirectory(directory);
+            result.push(directory);
+            // A SKILL.md directory is one atomic skill package. Resources beneath it
+            // are validated as content, not recursively treated as additional skills.
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === ".git" || entry === "node_modules")
+                continue;
+            const child = join(directory, entry);
+            const childStat = await lstat(child);
+            // Repositories may contain unrelated symlinked documentation or metadata.
+            // Ignore those while walking, but validate and reject symlinks inside an
+            // actual skill directory before it is copied.
+            if (childStat.isSymbolicLink()) {
+                if (entries.includes("SKILL.md"))
+                    throw new Error(`Refusing symlink in skill package: ${child}`);
+                continue;
+            }
+            // Files such as a root-level SKILL.md are not directories to recurse into.
+            if (childStat.isDirectory())
+                await visit(child, depth + 1);
+        }
+    }
+    await visit(root, 0);
+    return result;
+}
+function safeTarget(root, target) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = resolve(target);
+    if (resolvedTarget !== resolvedRoot &&
+        !resolvedTarget.startsWith(`${resolvedRoot}${sep}`)) {
+        throw new Error(`Refusing path outside target directory: ${target}`);
+    }
+    return resolvedTarget;
+}
+export async function planSkillInstall(sourceRoot, targetDirectories, packageId, options = {}) {
+    const skills = await discoverSkillDirectories(sourceRoot, options);
+    if (skills.length === 0)
+        throw new Error(`No SKILL.md found under ${sourceRoot}`);
+    const files = [];
+    for (const targetRoot of targetDirectories) {
+        try {
+            const targetStat = await lstat(targetRoot);
+            if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+                throw new Error(`Refusing unsafe target directory: ${targetRoot}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.startsWith("Refusing unsafe target"))
+                throw error;
+            // A not-yet-created agent directory is safe; applySkillPlan creates it.
+        }
+        for (const skill of skills) {
+            const name = skill === sourceRoot
+                ? packageId
+                : (skill.split(sep).at(-1) ?? packageId);
+            const target = safeTarget(targetRoot, join(targetRoot, name));
+            const frontmatter = await readFile(join(skill, "SKILL.md"), "utf8");
+            const skillName = frontmatter.match(/^name:\s*(\S+)/m)?.[1];
+            files.push({ source: skill, target, skillName });
+        }
+    }
+    const conflicts = detectInstallConflicts([
+        { packageId, files, targetAgents: [], warnings: [] },
+    ]);
+    return {
+        packageId,
+        files,
+        targetAgents: [],
+        warnings: conflicts
+            .filter((item) => item.severity === "warning")
+            .map((item) => item.message),
+        conflicts,
+    };
+}
+/** Compare one or more plans before any filesystem mutation occurs. */
+export function detectInstallConflicts(plans) {
+    const diagnostics = [];
+    const byTarget = new Map();
+    const byName = new Map();
+    for (const plan of plans) {
+        for (const file of plan.files) {
+            const target = resolve(file.target);
+            const targetItems = byTarget.get(target) ?? [];
+            targetItems.push({ packageId: plan.packageId, target });
+            byTarget.set(target, targetItems);
+            if (file.skillName) {
+                const nameItems = byName.get(file.skillName.toLowerCase()) ?? [];
+                nameItems.push({ packageId: plan.packageId, target });
+                byName.set(file.skillName.toLowerCase(), nameItems);
+            }
+        }
+    }
+    for (const [target, items] of byTarget) {
+        const packages = [...new Set(items.map((item) => item.packageId))];
+        if (items.length > 1)
+            diagnostics.push({
+                severity: "blocking",
+                code: "target-collision",
+                message: `Multiple packages target the same skill directory: ${target}`,
+                packageIds: packages,
+                targets: [target],
+            });
+    }
+    for (const [name, items] of byName) {
+        const packages = [...new Set(items.map((item) => item.packageId))];
+        const targets = [...new Set(items.map((item) => item.target))];
+        if (packages.length > 1 && targets.length > 1)
+            diagnostics.push({
+                severity: "warning",
+                code: "duplicate-skill-name",
+                message: `Skill name '${name}' appears in multiple packages with different targets`,
+                packageIds: packages,
+                targets,
+            });
+    }
+    return diagnostics;
+}
+export async function applySkillPlan(plan) {
+    for (const file of plan.files) {
+        const info = await lstat(file.source);
+        if (info.isSymbolicLink())
+            throw new Error(`Refusing symlinked planned source: ${file.source}`);
+        if (info.isDirectory())
+            await ensureDirectory(file.target);
+        else
+            await ensureDirectory(dirname(file.target));
+        await cp(file.source, file.target, {
+            recursive: info.isDirectory(),
+            errorOnExist: false,
+            force: true,
+        });
+    }
+}
+export async function removeSkillDirectories(plan) {
+    for (const file of plan.files)
+        await rm(file.target, { recursive: true, force: true });
+}
+export async function validateSkillDirectory(path) {
+    const directoryStat = await lstat(path);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+        throw new Error(`Skill path must be a real directory: ${path}`);
+    }
+    const skillPath = join(path, "SKILL.md");
+    const skillStat = await lstat(skillPath);
+    if (!skillStat.isFile() || skillStat.isSymbolicLink()) {
+        throw new Error(`SKILL.md must be a regular file: ${skillPath}`);
+    }
+    const content = await readFile(skillPath, "utf8");
+    // Repositories authored on Windows commonly use CRLF. The parser is
+    // deliberately line-ending agnostic and copying preserves the original bytes.
+    if (!/^---\s*\r?\n/.test(content) ||
+        !/^name:\s*\S+/m.test(content) ||
+        !/^description:\s*\S+/m.test(content)) {
+        throw new Error(`SKILL.md is missing required name/description frontmatter: ${relative(process.cwd(), path)}`);
+    }
+    // Deeper validation stays read-only. Only deterministic critical findings fail
+    // closed here; scripts, domains and dependencies continue through the explicit
+    // risk-approval flow rather than being silently treated as safe.
+    assertSkillSecurity(await scanSkillSecurity(path));
+}

package/dist/src/core/snapshot.js

@@ -0,0 +1,210 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, writeFile, mkdir, readdir, rm, lstat, } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { loadoutHome, ensureDirectory, userHome } from "./paths.js";
+export async function createSnapshot(paths, options = {}) {
+    const normalizedRoots = [...new Set(paths.map((path) => resolve(path)))];
+    const snapshot = {
+        id: `${Date.now()}-${createHash("sha256")
+            .update(`${normalizedRoots.join("\n")}\0${randomUUID()}`)
+            .digest("hex")
+            .slice(0, 12)}`,
+        createdAt: new Date().toISOString(),
+        roots: normalizedRoots,
+        files: [],
+    };
+    async function capture(path) {
+        let info;
+        try {
+            info = await lstat(path);
+        }
+        catch (error) {
+            if (!(error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw error;
+            snapshot.files.push({ path, existed: false });
+            return;
+        }
+        if (info.isSymbolicLink())
+            throw new Error(`Refusing to snapshot symlink: ${path}`);
+        if (info.isFile()) {
+            snapshot.files.push({
+                path,
+                existed: true,
+                content: (await readFile(path)).toString("base64"),
+                encoding: "base64",
+            });
+            return;
+        }
+        if (!info.isDirectory())
+            throw new Error(`Refusing unsupported snapshot target: ${path}`);
+        snapshot.files.push({ path, existed: true, directory: true });
+        const entries = await readdir(path, { withFileTypes: true });
+        for (const entry of entries) {
+            const child = join(path, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`Refusing to snapshot symlink: ${child}`);
+            if (entry.isDirectory())
+                await capture(child);
+            else if (entry.isFile())
+                snapshot.files.push({
+                    path: child,
+                    existed: true,
+                    content: (await readFile(child)).toString("base64"),
+                    encoding: "base64",
+                });
+        }
+    }
+    for (const path of snapshot.roots)
+        await capture(path);
+    validateSnapshot(snapshot);
+    if (options.persist !== false) {
+        const directory = join(loadoutHome(), "snapshots");
+        await ensureDirectory(directory);
+        await writeFile(join(directory, `${snapshot.id}.json`), JSON.stringify(snapshot, null, 2), { mode: 0o600 });
+    }
+    return snapshot;
+}
+export async function restoreSnapshot(snapshot) {
+    validateSnapshot(snapshot);
+    for (const root of snapshot.roots)
+        await rm(root, { recursive: true, force: true });
+    for (const directory of snapshot.files
+        .filter((file) => file.existed && file.directory)
+        .sort((a, b) => a.path.length - b.path.length))
+        await mkdir(directory.path, { recursive: true });
+    for (const file of snapshot.files) {
+        if (!file.existed || file.directory)
+            continue;
+        await mkdir(dirname(file.path), { recursive: true });
+        await writeFile(file.path, file.encoding === "base64"
+            ? Buffer.from(file.content ?? "", "base64")
+            : (file.content ?? ""));
+    }
+}
+export async function readSnapshot(id) {
+    if (!isSnapshotId(id))
+        throw new Error(`Invalid snapshot id: ${id}`);
+    let value;
+    try {
+        value = JSON.parse(await readFile(join(loadoutHome(), "snapshots", `${id}.json`), "utf8"));
+    }
+    catch (error) {
+        if (isFileError(error, "ENOENT"))
+            throw new Error(`Snapshot not found: ${id}`);
+        if (error instanceof SyntaxError)
+            throw new Error(`Snapshot is not valid JSON: ${id}`);
+        throw error;
+    }
+    const snapshot = validateSnapshot(value);
+    if (snapshot.id !== id)
+        throw new Error(`Snapshot id does not match its filename: ${id}`);
+    return snapshot;
+}
+export async function listSnapshotIds() {
+    try {
+        return (await readdir(join(loadoutHome(), "snapshots")))
+            .filter((file) => file.endsWith(".json"))
+            .map((file) => file.slice(0, -5))
+            .filter(isSnapshotId)
+            .sort();
+    }
+    catch (error) {
+        if (isFileError(error, "ENOENT"))
+            return [];
+        throw error;
+    }
+}
+const SNAPSHOT_ID = /^\d{10,}-[a-f0-9]{12}$/;
+function isSnapshotId(value) {
+    return SNAPSHOT_ID.test(value);
+}
+function isFileError(error, code) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isInside(root, path) {
+    const resolvedRoot = resolve(root);
+    const resolvedPath = resolve(path);
+    return (resolvedPath === resolvedRoot ||
+        resolvedPath.startsWith(`${resolvedRoot}${sep}`));
+}
+/**
+ * Reject structurally unsafe or internally inconsistent persisted rollback
+ * data before it can delete or write. This is corruption/tampering hardening,
+ * not an authorization boundary for an attacker who controls the user account.
+ */
+export function validateSnapshot(value) {
+    if (!isRecord(value))
+        throw new Error("Snapshot must be an object");
+    if (typeof value.id !== "string" || !isSnapshotId(value.id))
+        throw new Error("Snapshot id is invalid");
+    if (typeof value.createdAt !== "string" ||
+        !Number.isFinite(Date.parse(value.createdAt)))
+        throw new Error("Snapshot creation time is invalid");
+    if (!Array.isArray(value.roots) ||
+        value.roots.length === 0 ||
+        !value.roots.every((root) => typeof root === "string" && root.length > 0))
+        throw new Error("Snapshot roots are invalid");
+    if (!Array.isArray(value.files))
+        throw new Error("Snapshot files are invalid");
+    const roots = value.roots;
+    const forbiddenRoots = new Set([resolve(userHome()), resolve(loadoutHome())]);
+    for (const [index, root] of roots.entries()) {
+        if (resolve(root) !== root)
+            throw new Error(`Snapshot root ${index} must be an absolute normalized path`);
+        if (dirname(root) === root)
+            throw new Error(`Snapshot root ${index} must not be a filesystem root`);
+        if (forbiddenRoots.has(root))
+            throw new Error(`Snapshot root ${index} is too broad to restore safely`);
+        if (roots.some((candidate, candidateIndex) => candidateIndex !== index && isInside(candidate, root)))
+            throw new Error("Snapshot roots must be unique and non-overlapping");
+    }
+    const paths = new Set();
+    for (const [index, file] of value.files.entries()) {
+        if (!isRecord(file) ||
+            typeof file.path !== "string" ||
+            typeof file.existed !== "boolean" ||
+            (file.directory !== undefined && typeof file.directory !== "boolean") ||
+            (file.content !== undefined && typeof file.content !== "string") ||
+            (file.encoding !== undefined && file.encoding !== "base64"))
+            throw new Error(`Snapshot file ${index} is invalid`);
+        const filePath = file.path;
+        if (resolve(filePath) !== filePath)
+            throw new Error(`Snapshot file ${index} path must be absolute and normalized`);
+        if (paths.has(filePath))
+            throw new Error(`Snapshot file ${index} duplicates another path`);
+        paths.add(filePath);
+        if (!roots.some((root) => isInside(root, filePath)))
+            throw new Error(`Snapshot file ${index} escapes its declared roots`);
+        if (!file.existed) {
+            if (file.directory !== undefined ||
+                file.content !== undefined ||
+                file.encoding !== undefined)
+                throw new Error(`Missing snapshot file ${index} must not contain data`);
+        }
+        else if (file.directory) {
+            if (file.content !== undefined || file.encoding !== undefined)
+                throw new Error(`Snapshot directory ${index} must not contain bytes`);
+        }
+        else if (typeof file.content !== "string" ||
+            file.encoding !== "base64" ||
+            !isCanonicalBase64(file.content))
+            throw new Error(`Snapshot file ${index} bytes are invalid`);
+    }
+    for (const [index, root] of roots.entries())
+        if (!paths.has(root))
+            throw new Error(`Snapshot root ${index} has no matching file record`);
+    return value;
+}
+function isCanonicalBase64(value) {
+    return (value.length % 4 === 0 &&
+        /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value));
+}