@lidtop/loadout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loadout contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# Loadout
+
+Share a collection of agent skills and instructions with your team. Everyone in the repository picks the kits they want, keeping the full collection available without adding it all to their agent's context.
+
+Kit definitions live in the repository. Each developer's selections and generated files stay local and ignored by Git. Loadout configures both Codex and Claude Code.
+
+## Use it
+
+Requires Node.js **22.13+**. In a repository using Loadout:
+
+```sh
+npm install -g @lidtop/loadout
+loadout
+```
+
+Pick your kits, select **Continue**, and confirm. Run `loadout` again to change your selection.
+
+## Add it to your repository
+
+```sh
+loadout init
+```
+
+Add kits under `.loadout/kits/` and commit the collection for your team. Enable **Browse → loadout → write-kit** for a short guide your agent can use to create kits.
+
+`loadout --help` lists the commands.
+
+[MIT](LICENSE) · External kits retain their upstream licenses.

package/dist/adoption.d.ts

@@ -0,0 +1,13 @@
+import type { FileContent, Rendered } from './render.js';
+import type { Change } from './storage.js';
+export declare function prepareAdoption(root: string, rendered: Rendered, owned: Record<string, {
+    hash: string;
+    mode: number;
+}>, global: boolean, allow: boolean): {
+    files: Map<string, FileContent>;
+    originals: Map<string, FileContent>;
+    released: Set<string>;
+    adopted: string[];
+    beforeOutputs: Change[];
+    afterOutputs: Change[];
+};

package/dist/adoption.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { exists, json, readOptional, safePath, walk, portableMode, } from './fs.js';
+import { isOutput } from './output-path.js';
+import { parse } from './schema.js';
+const manifestPath = '.loadout/adopted.json';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const manifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    files: z.record(z.string(), z
+        .object({
+        hash: z.string().regex(/^[a-f0-9]{64}$/),
+        mode: z.number().int().min(0).max(0o777),
+    })
+        .strict()),
+})
+    .strict();
+function read(root, file) {
+    const content = readOptional(root, file);
+    return content === undefined
+        ? undefined
+        : {
+            content,
+            mode: portableMode(fs.statSync(safePath(root, file)).mode),
+        };
+}
+function compose(original, generated, file) {
+    const base = original.toString('utf8');
+    if (!Buffer.from(base).equals(original) || original.includes(0))
+        throw new Error(`Cannot preserve ${file}: expected UTF-8 instructions.`);
+    if (path.posix.basename(file) === 'CLAUDE.md') {
+        const normalize = (line) => line.trim().replace(/^@\.\//, '@');
+        if (base
+            .split(/\r?\n/)
+            .some((line) => normalize(line) === normalize(generated.toString())))
+            return original;
+    }
+    const crlf = (base.match(/\r\n/g) ?? []).length;
+    const newline = crlf > (base.match(/(?<!\r)\n/g) ?? []).length ? '\r\n' : '\n';
+    return Buffer.concat([
+        original,
+        Buffer.from(base ? (base.endsWith('\n') ? newline : newline + newline) : ''),
+        Buffer.from(generated.toString('utf8').replace(/\r?\n/g, newline)),
+    ]);
+}
+// This only prepares bytes. Baselines, outputs, and ownership are committed by
+// the same preview/recheck/rollback transaction as every other Loadout file.
+export function prepareAdoption(root, rendered, owned, global, allow) {
+    const beforeManifest = read(root, manifestPath);
+    const manifest = beforeManifest
+        ? parse(manifestSchema, JSON.parse(beforeManifest.content.toString()), manifestPath)
+        : {
+            schemaVersion: 1,
+            files: {},
+        };
+    const originals = new Map();
+    const blobs = new Map();
+    for (const [file, entry] of Object.entries(manifest.files)) {
+        if (!isOutput(file, global) || !Object.hasOwn(owned, file))
+            throw new Error(`Unexpected adopted output: ${file}`);
+        const blobPath = `.loadout/adopted/${entry.hash}`;
+        const blob = read(root, blobPath);
+        if (!blob || digest(blob.content) !== entry.hash)
+            throw new Error(`Original content is missing or changed for ${file}. Restore its .loadout/adopted backup before applying.`);
+        blobs.set(blobPath, blob);
+        originals.set(file, { content: blob.content, mode: entry.mode });
+    }
+    const adopted = [];
+    if (allow) {
+        for (const skill of rendered.skillRoots) {
+            if (!exists(safePath(root, skill)) ||
+                Object.keys(owned).some((file) => file.startsWith(`${skill}/`)))
+                continue;
+            const actual = walk(safePath(root, skill))
+                .map((file) => `${skill}/${file}`)
+                .sort();
+            const expected = [...rendered.files.keys()]
+                .filter((file) => file.startsWith(`${skill}/`))
+                .sort();
+            if (JSON.stringify(actual) !== JSON.stringify(expected) ||
+                actual.some((file) => {
+                    const current = read(root, file);
+                    const next = rendered.files.get(file);
+                    return (!current.content.equals(next.content) || current.mode !== next.mode);
+                }))
+                throw new Error(`Existing skill differs: ${skill}. Rename or move that folder, or deselect the kit, before continuing.`);
+        }
+        for (const file of rendered.files.keys()) {
+            if (Object.hasOwn(owned, file))
+                continue;
+            const original = read(root, file);
+            if (original) {
+                const expected = rendered.files.get(file);
+                if ([...rendered.skillRoots].some((skill) => file.startsWith(`${skill}/`)) &&
+                    (!original.content.equals(expected.content) ||
+                        original.mode !== expected.mode))
+                    throw new Error(`Existing skill differs: ${file}. Rename or move its folder, or deselect the kit, before continuing.`);
+                originals.set(file, original);
+                adopted.push(file);
+            }
+        }
+    }
+    const files = new Map(rendered.files);
+    const released = new Set();
+    const nextManifest = {
+        schemaVersion: 1,
+        files: {},
+    };
+    const nextBlobs = new Map();
+    for (const [file, original] of originals) {
+        const next = files.get(file);
+        if (!next) {
+            files.set(file, original);
+            released.add(file);
+            continue;
+        }
+        if (['AGENTS.md', 'CLAUDE.md'].includes(path.posix.basename(file)) &&
+            !/^\.(agents|claude)\/skills\//.test(file))
+            files.set(file, {
+                ...next,
+                content: compose(original.content, next.content, file),
+            });
+        const hash = digest(original.content);
+        nextManifest.files[file] = { hash, mode: original.mode };
+        const blobPath = `.loadout/adopted/${hash}`;
+        const existing = blobs.get(blobPath) ?? read(root, blobPath);
+        if (existing && !existing.content.equals(original.content))
+            throw new Error(`Original backup changed: ${blobPath}`);
+        nextBlobs.set(blobPath, existing ?? { content: original.content, mode: portableMode(0o600) });
+    }
+    const beforeOutputs = [];
+    const afterOutputs = [];
+    for (const [file, after] of nextBlobs) {
+        const before = blobs.get(file) ?? read(root, file);
+        beforeOutputs.push({
+            path: file,
+            before,
+            after,
+            kind: before ? 'unchanged' : 'create',
+        });
+    }
+    for (const [file, before] of blobs)
+        if (!nextBlobs.has(file))
+            afterOutputs.push({ path: file, before, kind: 'delete' });
+    if (beforeManifest || Object.keys(nextManifest.files).length) {
+        const after = Object.keys(nextManifest.files).length
+            ? {
+                content: json(nextManifest),
+                mode: beforeManifest?.mode ?? portableMode(0o600),
+            }
+            : undefined;
+        afterOutputs.push({
+            path: manifestPath,
+            before: beforeManifest,
+            after,
+            kind: !after
+                ? 'delete'
+                : !beforeManifest
+                    ? 'create'
+                    : after.content.equals(beforeManifest.content)
+                        ? 'unchanged'
+                        : 'update',
+        });
+    }
+    return { files, originals, released, adopted, beforeOutputs, afterOutputs };
+}

package/dist/bundled.d.ts

@@ -0,0 +1 @@
+export declare const bundledRoot: string;

package/dist/bundled.js

@@ -0,0 +1,3 @@
+import { fileURLToPath } from 'node:url';
+// Shared by source runs and the published dist/ entry point.
+export const bundledRoot = fileURLToPath(new URL('../kits/', import.meta.url));

package/dist/catalog.d.ts

@@ -0,0 +1,3 @@
+import { type Catalog } from './schema.js';
+export declare function discover(cwd: string): string;
+export declare function loadCatalog(root: string, global?: boolean): Catalog;

package/dist/catalog.js

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { parse as yaml } from 'yaml';
+import { configSchema, kitSchema, parse, validAnswer, idSchema, } from './schema.js';
+import { exists, safePath, walk } from './fs.js';
+import { curatedKits } from './curated.js';
+import { resolveKits } from './resolve.js';
+import { bundledRoot } from './bundled.js';
+export function discover(cwd) {
+    let root = fs.realpathSync(cwd);
+    const initial = root;
+    const home = fs.realpathSync(os.homedir());
+    while (true) {
+        // A home catalog is global, never an implicit catalog for child projects.
+        if (root === home && root !== initial)
+            break;
+        if (exists(path.join(root, '.loadout/config.yaml')))
+            return root;
+        if (exists(path.join(root, '.git')) || path.dirname(root) === root)
+            break;
+        root = path.dirname(root);
+    }
+    throw new Error('No .loadout/config.yaml found in this repository. Run loadout init at the repository root.');
+}
+function readYaml(root, relative) {
+    try {
+        return yaml(fs.readFileSync(safePath(root, relative), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${relative}: ${error.message}`);
+    }
+}
+function validateKit(kit, root, global) {
+    if (kit.ready === false)
+        return;
+    const dir = kit.directory;
+    for (const [key, q] of Object.entries(kit.questions)) {
+        if (q.default !== undefined && !validAnswer(q, q.default))
+            throw new Error(`${kit.id}.${key}: invalid default`);
+        if (q.type === 'choice' && new Set(q.choices).size !== q.choices.length)
+            throw new Error(`${kit.id}.${key}: duplicate choices`);
+    }
+    for (const output of kit.outputs) {
+        const source = safePath(dir, output.source);
+        if (!exists(source))
+            throw new Error(`${kit.id}: missing source ${output.source}`);
+        if (output.when) {
+            const q = kit.questions[output.when.answer];
+            if (!q || !validAnswer(q, output.when.equals))
+                throw new Error(`${kit.id}: invalid condition on ${output.when.answer}`);
+        }
+        if (output.type === 'instructions') {
+            if (global && output.scope !== '.')
+                throw new Error(`${kit.id}: global instructions must use scope: .`);
+            if (!fs.statSync(source).isFile())
+                throw new Error(`${kit.id}: instructions source must be a file`);
+            if (output.scope !== '.') {
+                const scope = safePath(root, output.scope);
+                if (!exists(scope) || !fs.statSync(scope).isDirectory())
+                    throw new Error(`${kit.id}: scope directory does not exist: ${output.scope}`);
+            }
+        }
+        else {
+            if (!fs.statSync(source).isDirectory())
+                throw new Error(`${kit.id}: skill source must be a directory`);
+            const name = path.basename(source);
+            parse(idSchema, name, `${kit.id}: skill directory name`);
+            const files = walk(source);
+            if (!files.includes('SKILL.md'))
+                throw new Error(`${kit.id}: skill requires SKILL.md`);
+            const skill = fs.readFileSync(path.join(source, 'SKILL.md'), 'utf8');
+            const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(skill);
+            if (!frontmatter)
+                throw new Error(`${kit.id}: SKILL.md needs YAML frontmatter`);
+            const meta = yaml(frontmatter[1]);
+            if (!meta ||
+                meta.name !== name ||
+                typeof meta.description !== 'string' ||
+                !meta.description.trim())
+                throw new Error(`${kit.id}: SKILL.md needs name: ${name} and a description`);
+        }
+    }
+}
+export function loadCatalog(root, global = path.resolve(root) === fs.realpathSync(os.homedir())) {
+    const config = parse(configSchema, readYaml(root, '.loadout/config.yaml'), '.loadout/config.yaml');
+    const directory = safePath(root, '.loadout/kits');
+    const kits = new Map();
+    for (const folder of exists(directory)
+        ? fs.readdirSync(directory).sort()
+        : []) {
+        const dir = safePath(directory, folder);
+        if (!fs.statSync(dir).isDirectory())
+            continue;
+        const manifest = `.loadout/kits/${folder}/kit.yaml`;
+        const kit = {
+            ...parse(kitSchema, readYaml(root, manifest), manifest),
+            directory: dir,
+        };
+        if (kits.has(kit.id))
+            throw new Error(`Duplicate kit ID: ${kit.id}`);
+        validateKit(kit, root, global);
+        kits.set(kit.id, kit);
+    }
+    for (const [definitions, origin] of [
+        [config.curated ? curatedKits : [], 'curated'],
+        [config.externalKits, 'external'],
+    ]) {
+        for (const definition of definitions) {
+            if (origin === 'curated' &&
+                config.externalKits.some((kit) => kit.id === definition.id))
+                continue;
+            if (kits.has(definition.id))
+                throw new Error(`Duplicate kit ID: ${definition.id}. Local and external kits must have distinct IDs.`);
+            kits.set(definition.id, {
+                schemaVersion: 1,
+                id: definition.id,
+                description: definition.description,
+                requires: [],
+                questions: {},
+                outputs: [],
+                directory: root,
+                external: definition.source,
+                origin,
+            });
+        }
+    }
+    if (config.curated) {
+        for (const folder of fs.readdirSync(bundledRoot).sort()) {
+            const definition = parse(kitSchema, readYaml(bundledRoot, `${folder}/kit.yaml`), `loadout/${folder}`);
+            const kit = {
+                ...definition,
+                id: `loadout-${definition.id}`,
+                requires: definition.requires.map((id) => `loadout-${id}`),
+                directory: safePath(bundledRoot, folder),
+                origin: 'bundled',
+            };
+            if (kits.has(kit.id))
+                throw new Error(`Duplicate kit ID: ${kit.id}`);
+            validateKit(kit, root, global);
+            kits.set(kit.id, kit);
+        }
+    }
+    const catalog = { root, kits, global };
+    resolveKits(catalog, [...kits.values()]
+        .filter((kit) => kit.ready !== false)
+        .map((kit) => kit.id));
+    return catalog;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};