loadout-ai 0.1.0

package/dist/src/core/components.js

@@ -0,0 +1,138 @@
+import { lstat, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { buildSkillPlan } from "./install.js";
+import { adapterCapabilities, agentComponentDirectory } from "./adapters.js";
+const RESOURCE_DIRECTORIES = new Map([
+    ["rules", "rule"],
+    ["commands", "command"],
+    ["agents", "agent"],
+]);
+const RESOURCE_FILE = /\.(?:md|json|ya?ml)$/i;
+/** Discover conventional resource directories without following symlinks. */
+export async function discoverResources(root) {
+    const base = resolve(root);
+    const resources = [];
+    async function visit(directory, depth, insideSkill) {
+        if (depth > 5)
+            return;
+        const entries = await readdir(directory, { withFileTypes: true });
+        const skill = insideSkill ||
+            entries.some((entry) => entry.name === "SKILL.md" && entry.isFile());
+        for (const entry of entries) {
+            if (entry.name === ".git" || entry.name === "node_modules")
+                continue;
+            const absolute = join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                if (RESOURCE_DIRECTORIES.has(entry.name))
+                    throw new Error(`Refusing symlinked resource directory: ${absolute}`);
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            const type = !skill ? RESOURCE_DIRECTORIES.get(entry.name) : undefined;
+            if (type) {
+                for (const child of await readdir(absolute, { withFileTypes: true })) {
+                    if (child.isSymbolicLink())
+                        throw new Error(`Refusing symlinked package resource: ${join(absolute, child.name)}`);
+                    // Conventional agent resources are files. Treating arbitrary child
+                    // directories as agents creates dangerous false positives such as
+                    // `skills/agents/references`, which is supporting material for a
+                    // runtime tool rather than an installable agent declaration.
+                    if (!child.isFile() || !RESOURCE_FILE.test(child.name))
+                        continue;
+                    resources.push({
+                        type,
+                        name: child.name.replace(/\.(md|json|ya?ml)$/i, ""),
+                        path: relative(base, join(absolute, child.name))
+                            .split(sep)
+                            .join("/"),
+                    });
+                }
+                continue;
+            }
+            await visit(absolute, depth + 1, skill);
+        }
+    }
+    await visit(base, 0, false);
+    return resources.sort((a, b) => a.type.localeCompare(b.type) || a.path.localeCompare(b.path));
+}
+function safeSource(root, path) {
+    const base = resolve(root);
+    const source = resolve(base, path);
+    if (source !== base && !source.startsWith(`${base}${sep}`))
+        throw new Error(`Resource escapes package root: ${path}`);
+    return source;
+}
+export async function buildUniversalPackagePlan(root, packageId, agents) {
+    const files = [];
+    const warnings = [];
+    try {
+        const skills = await buildSkillPlan(root, packageId, agents);
+        files.push(...skills.files.map((file) => ({
+            ...file,
+            componentType: "skill",
+            compatibility: "native",
+        })));
+        warnings.push(...skills.warnings);
+    }
+    catch (error) {
+        if (!(error instanceof Error) ||
+            !error.message.startsWith("No SKILL.md found"))
+            throw error;
+    }
+    const resources = await discoverResources(root);
+    for (const resource of resources) {
+        for (const agent of agents) {
+            const directory = agentComponentDirectory(agent, resource.type);
+            const compatibility = adapterCapabilities(agent.id).components[resource.type];
+            if (!directory) {
+                warnings.push(`${agent.displayName}: ${resource.type} '${resource.name}' is unsupported and will not be installed.`);
+                continue;
+            }
+            files.push({
+                source: safeSource(root, resource.path),
+                target: join(directory, packageId, resource.path.split("/").at(-1)),
+                targetAgent: agent.id,
+                componentType: resource.type,
+                compatibility,
+            });
+            if (compatibility === "adapted")
+                warnings.push(`${agent.displayName}: ${resource.type} '${resource.name}' will be installed using an adapted layout.`);
+        }
+    }
+    if (!files.length)
+        throw new Error(`No supported skills, rules, commands, or agents found under ${root}`);
+    return {
+        packageId,
+        files,
+        targetAgents: agents.map((agent) => agent.id),
+        warnings: [...new Set(warnings)],
+    };
+}
+export async function addRootFileExports(plan, packageRoot, targetRoot, exports) {
+    const sourceRoot = resolve(packageRoot);
+    const destinationRoot = resolve(targetRoot);
+    for (const item of exports) {
+        if (!item.source ||
+            !item.target ||
+            isAbsolute(item.source) ||
+            isAbsolute(item.target))
+            throw new Error(`Root-file exports must use non-empty relative paths: ${item.source} -> ${item.target}`);
+        const source = resolve(sourceRoot, item.source);
+        const target = resolve(destinationRoot, item.target);
+        if (source !== sourceRoot && !source.startsWith(`${sourceRoot}${sep}`))
+            throw new Error(`Root-file source escapes package: ${item.source}`);
+        if (target !== destinationRoot &&
+            !target.startsWith(`${destinationRoot}${sep}`))
+            throw new Error(`Root-file target escapes allowed scope: ${item.target}`);
+        const info = await lstat(source);
+        if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory()))
+            throw new Error(`Root-file source must be a real file or directory: ${item.source}`);
+        plan.files.push({
+            source,
+            target,
+            componentType: "root",
+            compatibility: "native",
+        });
+    }
+}

package/dist/src/core/conversion.js

@@ -0,0 +1,56 @@
+import { basename } from "node:path";
+function safeName(name) {
+    const value = basename(name).replace(/[^A-Za-z0-9._-]+/g, "-");
+    if (!value)
+        throw new Error("Conversion name must contain a safe identifier");
+    return value.toLowerCase();
+}
+/**
+ * Compile only static instruction semantics. Hooks never become executable
+ * hooks; their trigger and command are preserved in a review artifact.
+ */
+export function compileConversion(input, target) {
+    const name = safeName(input.name);
+    if (!input.body.trim())
+        throw new Error("Conversion source body is empty");
+    if (input.kind === "hook" && target !== "static-review")
+        throw new Error("Hooks may only convert to static-review; executable behavior is never synthesized");
+    if (input.kind === "subagent" && target === "static-review")
+        throw new Error("Subagents require a skill target for static conversion");
+    if (target === "static-review") {
+        return {
+            source: input.kind,
+            target,
+            relativePath: `conversion-reports/${name}.md`,
+            content: `# Hook conversion review: ${name}\n\nThe original hook was not executed or converted into an executable hook.\n\n## Source instructions\n\n${input.body.trim()}\n`,
+            preserved: ["instruction text", "source name"],
+            dropped: [
+                {
+                    field: "trigger and command execution",
+                    reason: "hooks are not portable and must be reviewed manually",
+                },
+            ],
+            requiresApproval: true,
+        };
+    }
+    const dropped = [
+        {
+            field: "agent runtime metadata",
+            reason: "target agent may not support the source model/tools contract",
+        },
+    ];
+    for (const field of Object.keys(input.metadata ?? {}))
+        dropped.push({
+            field,
+            reason: "metadata is not part of the portable instruction body",
+        });
+    return {
+        source: input.kind,
+        target,
+        relativePath: `skills/${name}/SKILL.md`,
+        content: `---\nname: ${name}\ndescription: Converted static instructions; review before use\n---\n\n${input.body.trim()}\n`,
+        preserved: ["instruction text", "source name"],
+        dropped,
+        requiresApproval: true,
+    };
+}

package/dist/src/core/credentials.js

@@ -0,0 +1,377 @@
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_ACCOUNT = "default";
+const WINDOWS_MAX_SECRET_BYTES = 2_560;
+/**
+ * Uses the Win32 Credential Manager API rather than cmdkey because cmdkey
+ * cannot retrieve generic credentials and would require a password argument.
+ * The secret is read exclusively from stdin by the set operation.
+ */
+const WINDOWS_CREDENTIAL_SCRIPT = String.raw `
+$source = @'
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+public static class LoadoutCredentialManager {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct Credential {
+    public UInt32 Flags;
+    public UInt32 Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public UInt32 CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public UInt32 Persist;
+    public UInt32 AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+
+  [DllImport("advapi32.dll", EntryPoint = "CredWriteW", CharSet = CharSet.Unicode, SetLastError = true)]
+  private static extern bool CredWrite(ref Credential credential, UInt32 flags);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredReadW", CharSet = CharSet.Unicode, SetLastError = true)]
+  private static extern bool CredRead(string target, UInt32 type, UInt32 flags, out IntPtr credential);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredDeleteW", CharSet = CharSet.Unicode, SetLastError = true)]
+  private static extern bool CredDelete(string target, UInt32 type, UInt32 flags);
+
+  [DllImport("advapi32.dll")]
+  private static extern void CredFree(IntPtr credential);
+
+  public static void Set(string target, string account, string secret) {
+    IntPtr blob = Marshal.StringToCoTaskMemUni(secret);
+    try {
+      Credential credential = new Credential {
+        Type = 1,
+        TargetName = target,
+        CredentialBlobSize = (UInt32)(secret.Length * 2),
+        CredentialBlob = blob,
+        Persist = 2,
+        UserName = account
+      };
+      if (!CredWrite(ref credential, 0)) throw new Win32Exception(Marshal.GetLastWin32Error());
+    } finally {
+      Marshal.ZeroFreeCoTaskMemUnicode(blob);
+    }
+  }
+
+  public static string Get(string target) {
+    IntPtr pointer;
+    if (!CredRead(target, 1, 0, out pointer)) {
+      int error = Marshal.GetLastWin32Error();
+      if (error == 1168) return null;
+      throw new Win32Exception(error);
+    }
+    try {
+      Credential credential = (Credential)Marshal.PtrToStructure(pointer, typeof(Credential));
+      return Marshal.PtrToStringUni(credential.CredentialBlob, (int)credential.CredentialBlobSize / 2);
+    } finally {
+      CredFree(pointer);
+    }
+  }
+
+  public static bool Delete(string target) {
+    if (CredDelete(target, 1, 0)) return true;
+    int error = Marshal.GetLastWin32Error();
+    if (error == 1168) return false;
+    throw new Win32Exception(error);
+  }
+}
+'@
+Add-Type -TypeDefinition $source
+$operation = $args[0]
+$target = $args[1]
+$account = $args[2]
+if ($operation -eq 'get') {
+  $value = [LoadoutCredentialManager]::Get($target)
+  if ($null -eq $value) { exit 3 }
+  [Console]::Out.Write($value)
+} elseif ($operation -eq 'set') {
+  $value = [Console]::In.ReadToEnd()
+  [LoadoutCredentialManager]::Set($target, $account, $value)
+} elseif ($operation -eq 'delete') {
+  if (-not [LoadoutCredentialManager]::Delete($target)) { exit 3 }
+} else {
+  throw 'Unsupported credential operation'
+}
+`;
+function validateTimeout(timeoutMs) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 30_000)
+        throw new Error("Credential timeout must be between 100ms and 30000ms");
+    return timeoutMs;
+}
+function validateOutputLimit(maxOutputBytes) {
+    if (!Number.isInteger(maxOutputBytes) ||
+        maxOutputBytes < 1_024 ||
+        maxOutputBytes > 1024 * 1024)
+        throw new Error("Credential output limit must be between 1024 and 1048576 bytes");
+    return maxOutputBytes;
+}
+function validateIdentifier(value, field) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:@/+ -]{0,127}$/.test(value) ||
+        value !== value.trim())
+        throw new Error(`Credential ${field} must be 1-128 safe identifier characters`);
+    return value;
+}
+function normalizeReference(reference) {
+    if (reference.kind !== "os-keychain")
+        throw new Error("A keychain credential reference is required");
+    return {
+        service: validateIdentifier(reference.service, "service"),
+        account: validateIdentifier(reference.account ?? DEFAULT_ACCOUNT, "account"),
+    };
+}
+function validateEnvironmentName(name) {
+    if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(name))
+        throw new Error("Credential environment name is invalid");
+    return name;
+}
+function validateSecret(secret, platform) {
+    const maximum = platform === "win32" ? WINDOWS_MAX_SECRET_BYTES : DEFAULT_MAX_OUTPUT_BYTES;
+    const bytes = Buffer.byteLength(secret, platform === "win32" ? "utf16le" : "utf8");
+    if (!secret || secret.includes("\0") || bytes > maximum)
+        throw new Error("Credential value is empty or exceeds the backend limit");
+}
+function windowsTarget(reference) {
+    return `loadout:${reference.service}:${reference.account}`;
+}
+function backendFor(platform) {
+    if (platform === "darwin")
+        return {
+            statusName: "macos-keychain",
+            status: { command: "security", args: ["help"] },
+            get: ({ service, account }) => ({
+                command: "security",
+                args: ["find-generic-password", "-s", service, "-a", account, "-w"],
+            }),
+            set: ({ service, account }, secret) => ({
+                command: "security",
+                args: [
+                    "add-generic-password",
+                    "-U",
+                    "-s",
+                    service,
+                    "-a",
+                    account,
+                    "-w",
+                ],
+                stdin: secret,
+            }),
+            delete: ({ service, account }) => ({
+                command: "security",
+                args: ["delete-generic-password", "-s", service, "-a", account],
+            }),
+            notFoundExitCodes: new Set([44]),
+        };
+    if (platform === "linux")
+        return {
+            statusName: "linux-secret-service",
+            status: { command: "secret-tool", args: ["--help"] },
+            get: ({ service, account }) => ({
+                command: "secret-tool",
+                args: ["lookup", "service", service, "account", account],
+            }),
+            set: ({ service, account }, secret) => ({
+                command: "secret-tool",
+                args: [
+                    "store",
+                    "--label=Loadout credential",
+                    "service",
+                    service,
+                    "account",
+                    account,
+                ],
+                stdin: secret,
+            }),
+            delete: ({ service, account }) => ({
+                command: "secret-tool",
+                args: ["clear", "service", service, "account", account],
+            }),
+            notFoundExitCodes: new Set([1]),
+        };
+    const powershellArgs = (operation, reference) => [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        `& { ${WINDOWS_CREDENTIAL_SCRIPT} } '${operation}' '${windowsTarget(reference)}' '${reference.account}'`,
+    ];
+    return {
+        statusName: "windows-credential-manager",
+        status: {
+            command: "powershell.exe",
+            args: [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                "if (Get-Command powershell.exe -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }",
+            ],
+        },
+        get: (reference) => ({
+            command: "powershell.exe",
+            args: powershellArgs("get", reference),
+        }),
+        set: (reference, secret) => ({
+            command: "powershell.exe",
+            args: powershellArgs("set", reference),
+            stdin: secret,
+        }),
+        delete: (reference) => ({
+            command: "powershell.exe",
+            args: powershellArgs("delete", reference),
+        }),
+        notFoundExitCodes: new Set([3]),
+    };
+}
+export const defaultCredentialCommandRunner = async (request) => new Promise((resolve, reject) => {
+    const child = spawn(request.command, request.args, {
+        shell: false,
+        windowsHide: true,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let failure;
+    let settled = false;
+    const finishWithError = () => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(`Credential command failed (${failure ?? "process"})`));
+    };
+    const collect = (target, chunk, isStdout) => {
+        if (failure)
+            return;
+        if (isStdout)
+            stdoutBytes += chunk.length;
+        else
+            stderrBytes += chunk.length;
+        if (stdoutBytes + stderrBytes > request.maxOutputBytes) {
+            failure = "output";
+            child.kill();
+            return;
+        }
+        target.push(chunk);
+    };
+    child.stdout.on("data", (chunk) => collect(stdout, chunk, true));
+    child.stderr.on("data", (chunk) => collect(stderr, chunk, false));
+    child.on("error", () => {
+        failure = "spawn";
+        finishWithError();
+    });
+    child.on("close", (code) => {
+        if (failure) {
+            finishWithError();
+            return;
+        }
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({
+            stdout: Buffer.concat(stdout).toString("utf8"),
+            stderr: Buffer.concat(stderr).toString("utf8"),
+            exitCode: code ?? 1,
+        });
+    });
+    child.stdin.on("error", () => {
+        // A command that exits early may close stdin. Its exit code is enough.
+    });
+    child.stdin.end(request.stdin ?? "");
+    const timer = setTimeout(() => {
+        failure = "timeout";
+        child.kill();
+    }, request.timeoutMs);
+    timer.unref();
+});
+function supportedPlatform(platform) {
+    if (platform === "darwin" || platform === "linux" || platform === "win32")
+        return platform;
+    throw new Error(`OS credential storage is unsupported on '${platform}'`);
+}
+function withoutCommandNewline(value) {
+    return value.replace(/\r?\n$/, "");
+}
+export function createOsCredentialStore(options = {}) {
+    const platform = supportedPlatform(options.platform ?? process.platform);
+    const backend = backendFor(platform);
+    const runner = options.runner ?? defaultCredentialCommandRunner;
+    const timeoutMs = validateTimeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const maxOutputBytes = validateOutputLimit(options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES);
+    const run = async (operation, command) => {
+        try {
+            return await runner({
+                ...command,
+                timeoutMs,
+                maxOutputBytes,
+            });
+        }
+        catch {
+            // A custom runner could include its input in an exception. Never forward it.
+            throw new Error(`Credential ${operation} could not execute safely`);
+        }
+    };
+    return {
+        async get(reference) {
+            const result = await run("get", backend.get(normalizeReference(reference)));
+            if (backend.notFoundExitCodes.has(result.exitCode))
+                return undefined;
+            if (result.exitCode !== 0)
+                throw new Error("Credential get failed in the operating-system store");
+            const secret = withoutCommandNewline(result.stdout);
+            return secret || undefined;
+        },
+        async set(reference, secret) {
+            validateSecret(secret, platform);
+            const result = await run("set", backend.set(normalizeReference(reference), secret));
+            if (result.exitCode !== 0)
+                throw new Error("Credential set failed in the operating-system store");
+        },
+        async delete(reference) {
+            const result = await run("delete", backend.delete(normalizeReference(reference)));
+            if (backend.notFoundExitCodes.has(result.exitCode))
+                return false;
+            if (result.exitCode !== 0)
+                throw new Error("Credential delete failed in the operating-system store");
+            return true;
+        },
+        async status() {
+            try {
+                const result = await run("status", backend.status);
+                return {
+                    platform,
+                    backend: backend.statusName,
+                    available: result.exitCode === 0,
+                };
+            }
+            catch {
+                return { platform, backend: backend.statusName, available: false };
+            }
+        },
+    };
+}
+/** Resolve secret-free configuration references only at the point of use. */
+export function createCredentialResolver(options = {}) {
+    const environment = options.environment ?? process.env;
+    let store = options.store;
+    return async (reference) => {
+        if (reference.kind === "environment")
+            return environment[validateEnvironmentName(reference.name)] || undefined;
+        store ??= createOsCredentialStore(options);
+        return store.get(reference);
+    };
+}
+export async function resolveCredentialReference(reference, options = {}) {
+    return createCredentialResolver(options)(reference);
+}