@lidtop/loadout 0.1.0

package/dist/external.js

@@ -0,0 +1,285 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { parse as yaml } from 'yaml';
+import { z } from 'zod';
+import { agents, externalSourceSchema, idSchema, relativePath, parse, sameSource, } from './schema.js';
+import { json, readOptional, portableMode } from './fs.js';
+import { resolveKits } from './resolve.js';
+import { render } from './render.js';
+import { retryDownload } from './retry.js';
+const MAX_FILE = 2 * 1024 * 1024;
+const MAX_KIT = 8 * 1024 * 1024;
+const MAX_FILES = 200;
+const snapshotFile = z
+    .object({
+    data: z.string().max(Math.ceil(MAX_FILE / 3) * 4),
+    sha: z.string().regex(/^[a-f0-9]{40}$/),
+    mode: z.union([z.literal(420), z.literal(493)]),
+})
+    .strict();
+const snapshotSchema = z
+    .object({
+    integrity: z.string().regex(/^[a-f0-9]{64}$/),
+    source: externalSourceSchema,
+    files: z.record(relativePath, snapshotFile),
+})
+    .strict();
+const storeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kits: z.record(idSchema, snapshotSchema),
+})
+    .strict();
+export function readExternal(root) {
+    const raw = readOptional(root, '.loadout/external.json');
+    return {
+        raw,
+        store: raw
+            ? parse(storeSchema, JSON.parse(raw.toString()), '.loadout/external.json')
+            : { schemaVersion: 1, kits: {} },
+    };
+}
+function blobHash(content) {
+    return createHash('sha1')
+        .update(`blob ${content.length}\0`)
+        .update(content)
+        .digest('hex');
+}
+export const fetchBytes = async (url, limit, signal) => {
+    const response = await fetch(url, {
+        headers: { 'User-Agent': 'loadout', Accept: 'application/vnd.github+json' },
+        redirect: 'error',
+        signal: signal
+            ? AbortSignal.any([signal, AbortSignal.timeout(30_000)])
+            : AbortSignal.timeout(30_000),
+    });
+    if (!response.ok)
+        throw new Error(`GitHub request failed (${response.status}): ${url}${response.status === 403 || response.status === 429 ? '. The public API may be rate-limited; try again later.' : ''}`);
+    if (!response.body)
+        throw new Error(`Empty response: ${url}`);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > limit)
+                throw new Error(`Download exceeds ${limit} bytes: ${url}`);
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(chunks);
+};
+const treeSchema = z.object({
+    truncated: z.boolean(),
+    tree: z.array(z.object({
+        path: z.string(),
+        type: z.string(),
+        mode: z.string(),
+        sha: z.string().regex(/^[a-f0-9]{40}$/),
+        size: z.number().optional(),
+    })),
+});
+function skillNames(source) {
+    const names = source.skills.map((p) => path.posix.basename(p));
+    if (new Set(names).size !== names.length)
+        throw new Error(`External kit has duplicate skill names: ${names.join(', ')}`);
+    return names;
+}
+function snapshotIntegrity(snapshot) {
+    const source = snapshot.source;
+    const files = Object.entries(snapshot.files)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, file]) => [name, file.sha, file.mode]);
+    return createHash('sha256')
+        .update(JSON.stringify([
+        source.repo,
+        source.ref,
+        source.skills,
+        source.license,
+        files,
+    ]))
+        .digest('hex');
+}
+function validateSnapshot(snapshot, label) {
+    if (snapshot.integrity !== snapshotIntegrity(snapshot))
+        throw new Error(`${label}: external snapshot manifest checksum mismatch`);
+    const names = skillNames(snapshot.source);
+    let size = 0;
+    if (Object.keys(snapshot.files).length > MAX_FILES)
+        throw new Error(`${label}: too many external files`);
+    for (const [file, stored] of Object.entries(snapshot.files)) {
+        if (!names.some((name) => file.startsWith(`${name}/`)))
+            throw new Error(`${label}: invalid external output ${file}`);
+        const data = Buffer.from(stored.data, 'base64');
+        size += data.length;
+        if (data.toString('base64') !== stored.data ||
+            blobHash(data) !== stored.sha)
+            throw new Error(`${label}: external snapshot checksum mismatch: ${file}`);
+        if (data.length > MAX_FILE || size > MAX_KIT)
+            throw new Error(`${label}: external snapshot exceeds size limit`);
+    }
+    for (const name of names) {
+        const file = snapshot.files[`${name}/SKILL.md`];
+        if (!file)
+            throw new Error(`${label}: missing ${name}/SKILL.md`);
+        const text = Buffer.from(file.data, 'base64').toString('utf8');
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+        const meta = frontmatter ? yaml(frontmatter[1]) : undefined;
+        if (!meta ||
+            meta.name !== name ||
+            typeof meta.description !== 'string' ||
+            !meta.description.trim())
+            throw new Error(`${label}: ${name}/SKILL.md needs matching name and description`);
+        if (!snapshot.files[`${name}/LICENSE.upstream`])
+            throw new Error(`${label}: missing upstream license for ${name}`);
+    }
+}
+async function download(source, get) {
+    skillNames(source);
+    const tree = parse(treeSchema, JSON.parse((await get(`https://api.github.com/repos/${source.repo}/git/trees/${source.ref}?recursive=1`, MAX_KIT)).toString()), 'GitHub tree');
+    if (tree.truncated)
+        throw new Error('GitHub returned a truncated tree; this repository is too large for the external kit loader.');
+    const chosen = [];
+    const license = tree.tree.find((f) => f.path === source.license);
+    if (!license ||
+        license.type !== 'blob' ||
+        !['100644', '100755'].includes(license.mode))
+        throw new Error(`Missing regular license file: ${source.license}`);
+    for (const skill of source.skills) {
+        const name = path.posix.basename(skill);
+        for (const entry of tree.tree.filter((f) => f.path.startsWith(`${skill}/`))) {
+            if (entry.type === 'tree')
+                continue;
+            if (entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode))
+                throw new Error(`Unsupported external symlink or submodule: ${entry.path}`);
+            const relative = entry.path.slice(skill.length + 1);
+            parse(relativePath, relative, `External path ${entry.path}`);
+            chosen.push({
+                remote: entry.path,
+                target: `${name}/${relative}`,
+                sha: entry.sha,
+                mode: entry.mode === '100755' ? 0o755 : 0o644,
+                size: entry.size ?? MAX_FILE + 1,
+            });
+        }
+        chosen.push({
+            remote: source.license,
+            target: `${name}/LICENSE.upstream`,
+            sha: license.sha,
+            mode: 0o644,
+            size: license.size ?? MAX_FILE + 1,
+        });
+    }
+    if (chosen.length > MAX_FILES ||
+        chosen.some((f) => f.size > MAX_FILE) ||
+        chosen.reduce((sum, f) => sum + f.size, 0) > MAX_KIT)
+        throw new Error('External kit exceeds file count or size limits.');
+    const files = {};
+    for (let start = 0; start < chosen.length; start += 6) {
+        const entries = await Promise.all(chosen.slice(start, start + 6).map(async (file) => {
+            const encoded = file.remote
+                .split('/')
+                .map(encodeURIComponent)
+                .join('/');
+            const content = await get(`https://raw.githubusercontent.com/${source.repo}/${source.ref}/${encoded}`, MAX_FILE);
+            if (content.length !== file.size || blobHash(content) !== file.sha)
+                throw new Error(`GitHub content checksum mismatch: ${file.remote}`);
+            return {
+                file,
+                stored: {
+                    data: content.toString('base64'),
+                    sha: file.sha,
+                    mode: file.mode,
+                },
+            };
+        }));
+        for (const { file, stored } of entries) {
+            if (Object.hasOwn(files, file.target))
+                throw new Error(`External output collision: ${file.target}`);
+            files[file.target] = stored;
+        }
+    }
+    const snapshot = {
+        source,
+        files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b))),
+    };
+    const complete = { ...snapshot, integrity: snapshotIntegrity(snapshot) };
+    validateSnapshot(complete, source.repo);
+    return complete;
+}
+export async function renderWithExternal(catalog, state, options = {}) {
+    const result = render(catalog, state);
+    const enabled = resolveKits(catalog, state.selected);
+    const { raw, store } = readExternal(catalog.root);
+    for (const id of options.update ?? [])
+        if (!enabled.includes(id) || !catalog.kits.get(id)?.external)
+            throw new Error(`Cannot update ${id}: choose an enabled external kit.`);
+    for (const id of enabled) {
+        const kit = catalog.kits.get(id);
+        const source = kit.external;
+        if (!source)
+            continue;
+        let snapshot = Object.hasOwn(store.kits, id) ? store.kits[id] : undefined;
+        const unchanged = snapshot && sameSource(snapshot.source, source);
+        if (!snapshot ||
+            (options.update?.includes(id) && !(options.offline && unchanged))) {
+            if (options.offline)
+                throw new Error(`${id} is not available at the requested revision offline. Run without --offline once to fetch it.`);
+            options.onFetch?.(id, source);
+            snapshot = await retryDownload(async () => {
+                const controller = new AbortController();
+                const requests = new Map();
+                const get = (url, limit) => {
+                    if (!requests.has(url))
+                        requests.set(url, (options.fetch ?? fetchBytes)(url, limit, controller.signal));
+                    return requests.get(url);
+                };
+                try {
+                    return await download(source, get);
+                }
+                finally {
+                    controller.abort();
+                    await Promise.allSettled(requests.values());
+                    requests.clear();
+                }
+            }, options.retry ? (error) => options.retry(id, error) : undefined, () => options.onRetry?.(id));
+            store.kits[id] = snapshot;
+        }
+        validateSnapshot(snapshot, id);
+        for (const agent of agents) {
+            const prefix = `${agent === 'codex' ? '.agents' : '.claude'}/skills`;
+            for (const name of skillNames(snapshot.source)) {
+                const destination = `${prefix}/${name}`;
+                if (result.skillRoots.has(destination))
+                    throw new Error(`Output collision: multiple kits target ${destination}`);
+                result.skillRoots.add(destination);
+            }
+            for (const [relative, file] of Object.entries(snapshot.files)) {
+                const destination = `${prefix}/${relative}`;
+                if (result.files.has(destination))
+                    throw new Error(`Output collision: ${destination}`);
+                result.files.set(destination, {
+                    content: Buffer.from(file.data, 'base64'),
+                    mode: portableMode(file.mode),
+                });
+            }
+        }
+    }
+    if (raw || Object.keys(store.kits).length)
+        result.external = {
+            before: raw,
+            content: json(parse(storeSchema, {
+                ...store,
+                kits: Object.fromEntries(Object.entries(store.kits).sort(([a], [b]) => a.localeCompare(b))),
+            }, 'External snapshots')),
+        };
+    result.files = new Map([...result.files].sort(([a], [b]) => a.localeCompare(b)));
+    return result;
+}

package/dist/fs.d.ts

@@ -0,0 +1,6 @@
+export declare function exists(file: string): boolean;
+export declare function safePath(root: string, relative: string): string;
+export declare function readOptional(root: string, relative: string): Buffer | undefined;
+export declare function walk(root: string): string[];
+export declare function json(value: unknown): Buffer;
+export declare function portableMode(mode: number): number;

package/dist/fs.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function exists(file) {
+    try {
+        fs.lstatSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+// Reject symlinks on every existing component, including dangling links.
+export function safePath(root, relative) {
+    const absolute = path.resolve(root, relative);
+    const local = path.relative(root, absolute);
+    if (!local ||
+        local === '..' ||
+        local.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(local))
+        throw new Error(`Path escapes its permitted root: ${relative}`);
+    let current = root;
+    for (const component of local.split(path.sep)) {
+        current = path.join(current, component);
+        if (exists(current) && fs.lstatSync(current).isSymbolicLink())
+            throw new Error(`Symlinks are not supported: ${current}`);
+    }
+    return absolute;
+}
+export function readOptional(root, relative) {
+    const file = safePath(root, relative);
+    if (!exists(file))
+        return undefined;
+    if (!fs.statSync(file).isFile())
+        throw new Error(`Expected a regular file: ${relative}`);
+    return fs.readFileSync(file);
+}
+export function walk(root) {
+    const files = [];
+    for (const entry of fs.readdirSync(root).sort()) {
+        const file = safePath(root, entry);
+        const stat = fs.statSync(file);
+        if (stat.isDirectory())
+            files.push(...walk(file).map((p) => `${entry}/${p}`));
+        else if (stat.isFile())
+            files.push(entry);
+        else
+            throw new Error(`Unsupported file type: ${file}`);
+    }
+    return files;
+}
+export function json(value) {
+    return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+}
+// Windows does not preserve POSIX executable/permission bits. Compare its
+// generated files by content and use one stable mode in ownership metadata.
+export function portableMode(mode) {
+    return process.platform === 'win32' ? 0o644 : mode & 0o777;
+}

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function initialize(cwd: string, global?: boolean): void;

package/dist/init.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { exists, safePath } from './fs.js';
+import { ignoredText } from './storage.js';
+export function initialize(cwd, global = fs.realpathSync(cwd) === fs.realpathSync(os.homedir())) {
+    const root = fs.realpathSync(cwd);
+    const target = safePath(root, '.loadout');
+    if (exists(target))
+        throw new Error('.loadout already exists. Refusing to replace an existing catalog.');
+    const ignore = safePath(root, '.gitignore');
+    const original = exists(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
+    const updated = ignoredText(original, []); // Validate before creating anything.
+    try {
+        const starterFiles = {
+            'config.yaml': 'schemaVersion: 1\n',
+        };
+        if (!global) {
+            starterFiles['kits/starter/kit.yaml'] = `schemaVersion: 1
+id: starter
+description: Add your repository guidance
+ready: false
+outputs:
+  - type: skill
+    source: skills/starter
+`;
+            starterFiles['kits/starter/skills/starter/SKILL.md'] = `---
+name: starter
+description: Replace this with when to use your repository skill.
+---
+
+# Starter
+
+This is an unfinished template. It supplies no agent instructions.
+
+Replace this text with your repository workflow, update the description,
+and set ready: true in the kit's kit.yaml when it is ready to use.
+`;
+        }
+        for (const [relative, content] of Object.entries(starterFiles)) {
+            const file = path.join(target, relative);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, content, { flag: 'wx' });
+        }
+        fs.writeFileSync(ignore, updated);
+    }
+    catch (error) {
+        fs.rmSync(target, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/interactive.d.ts

@@ -0,0 +1,10 @@
+import { checkbox, confirm, select } from '@inquirer/prompts';
+import { type Catalog, type State } from './schema.js';
+import { type TargetSelection } from './picker.js';
+import { type Target } from './targets.js';
+export declare function interactive(targets: Target[], initial?: number): Promise<TargetSelection[]>;
+export declare function configureSelection(target: Target, state: State, context?: Parameters<typeof confirm>[1]): Promise<State>;
+export declare function confirmApply(): Promise<boolean>;
+export declare function selectUpdates(catalog: Catalog, state: State, offline?: boolean, context?: Parameters<typeof checkbox>[1]): Promise<string[]>;
+export declare function confirmRetry(id: string, error: Error, context?: Parameters<typeof select>[1]): Promise<boolean>;
+export declare function confirmAdoption(paths: string[], context?: Parameters<typeof confirm>[1]): Promise<boolean>;

package/dist/interactive.js

@@ -0,0 +1,82 @@
+import { checkbox, confirm, select } from '@inquirer/prompts';
+import { configure } from './resolve.js';
+import { validAnswer } from './schema.js';
+import { targetPicker } from './picker.js';
+import { initializeTarget } from './targets.js';
+import { availableUpdates, updateDescription } from './updates.js';
+export async function interactive(targets, initial = 0) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error('Interactive setup needs a terminal. Use loadout enable <kit>, then loadout apply.');
+    const chosen = await targetPicker({
+        targets,
+        initial,
+        initialize: initializeTarget,
+    });
+    const configured = [];
+    for (const { target, state } of chosen) {
+        const value = await configureSelection(target, state);
+        configured.push({ target, state: value });
+    }
+    return configured;
+}
+export async function configureSelection(target, state, context) {
+    const change = new Map();
+    return configure(target.catalog, state, async (kit, key, question, value) => {
+        if (!change.has(kit)) {
+            const hasSaved = Object.entries(target.catalog.kits.get(kit).questions).some(([name, q]) => validAnswer(q, state.answers[kit]?.[name]));
+            change.set(kit, hasSaved
+                ? await confirm({
+                    message: `${target.label} · ${kit} · Change selection?`,
+                    default: false,
+                }, context)
+                : true);
+        }
+        const saved = state.answers[kit]?.[key];
+        if (!change.get(kit) && validAnswer(question, saved))
+            return saved;
+        const message = `${target.label} · ${kit} · ${question.message}`;
+        if (question.type === 'boolean')
+            return confirm({ message, default: typeof value === 'boolean' ? value : false }, context);
+        return select({
+            message,
+            choices: question.choices.map((v) => ({ name: v, value: v })),
+            default: typeof value === 'string' ? value : undefined,
+        }, context);
+    });
+}
+export async function confirmApply() {
+    return confirm({ message: 'Apply changes?', default: true });
+}
+export async function selectUpdates(catalog, state, offline = false, context) {
+    const updates = availableUpdates(catalog, state.selected);
+    if (!updates.length)
+        return [];
+    if (offline) {
+        console.log(`${updates.length} catalog update(s) available. Run loadout online to review them; keeping saved versions.`);
+        return [];
+    }
+    return checkbox({
+        message: 'Catalog updates available · choose kits to update (Enter skips)',
+        choices: updates.map((kit) => ({
+            name: kit.id,
+            value: kit.id,
+            description: updateDescription(kit),
+        })),
+        required: false,
+    }, context);
+}
+export async function confirmRetry(id, error, context) {
+    return select({
+        message: `${id}: ${error.message}`,
+        choices: [
+            { name: 'Retry download', value: true },
+            { name: 'Cancel', value: false },
+        ],
+    }, context);
+}
+export async function confirmAdoption(paths, context) {
+    return confirm({
+        message: `Keep existing content and let Loadout manage ${paths.join(', ')}? Originals will be restored when disabled.`,
+        default: true,
+    }, context);
+}

package/dist/output-path.d.ts

@@ -0,0 +1 @@
+export declare function isOutput(relative: string, global?: boolean): boolean;

package/dist/output-path.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import { scopeSchema } from './schema.js';
+export function isOutput(relative, global = false) {
+    if (global && ['.codex/AGENTS.md', '.claude/CLAUDE.md'].includes(relative))
+        return true;
+    if (relative.includes('\\') ||
+        relative.split('/').some((p) => !p || p === '.' || p === '..') ||
+        /[\x00-\x1f]/.test(relative))
+        return false;
+    if (/^\.(agents|claude)\/skills\/[a-z0-9]+(?:-[a-z0-9]+)*\/.+/.test(relative))
+        return true;
+    const directory = path.posix.dirname(relative);
+    return (['AGENTS.md', 'CLAUDE.md'].includes(path.posix.basename(relative)) &&
+        scopeSchema.safeParse(directory).success);
+}

package/dist/picker.d.ts

@@ -0,0 +1,29 @@
+import { type Catalog, type State } from './schema.js';
+import { type Target } from './targets.js';
+export type PickerConfig = {
+    catalog: Catalog;
+    selected: string[];
+    columns?: number;
+    rows?: number;
+};
+export type TargetPickerConfig = {
+    targets: Target[];
+    initial?: number;
+    columns?: number;
+    rows?: number;
+    initialize?: (target: Target) => Target;
+};
+export type TargetSelection = {
+    target: Target;
+    state: State;
+};
+declare const renderPicker: import("@inquirer/type").Prompt<TargetSelection[], {
+    targets: Target[];
+    initial?: number;
+    columns?: number;
+    rows?: number;
+    initialize?: (target: Target) => Target;
+} & TargetPickerConfig>;
+export declare function targetPicker(config: TargetPickerConfig, context?: Parameters<typeof renderPicker>[1]): Promise<TargetSelection[]>;
+export declare function kitPicker(config: PickerConfig, context?: Parameters<typeof targetPicker>[1]): Promise<string[]>;
+export {};