@lidtop/loadout 0.1.0

package/dist/cli.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createTwoFilesPatch } from 'diff';
+import { readFileSync, realpathSync } from 'node:fs';
+import os from 'node:os';
+import { discover } from './catalog.js';
+import { initialize } from './init.js';
+import { interactive, confirmApply, selectUpdates, confirmRetry, confirmAdoption, } from './interactive.js';
+import { apply, applyAll, plan } from './storage.js';
+import { renderWithExternal } from './external.js';
+import { DownloadCancelledError } from './retry.js';
+import { loadTarget } from './targets.js';
+import { configure, disableKits, reasons, resolveKits, setAnswers, } from './resolve.js';
+import { kitSource } from './schema.js';
+import { availableUpdates, hasUpdate, updateDescription } from './updates.js';
+const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const program = new Command()
+    .name('loadout')
+    .description('Configure your repository’s agent tools.')
+    .version(version)
+    .option('-g, --global', 'use the Loadout catalog in your home directory')
+    .option('--offline', 'use saved external kits without network requests')
+    .option('-C, --cwd <directory>', 'run in a different directory', process.cwd())
+    .showHelpAfterError();
+function targetRoot() {
+    const opts = program.opts();
+    const home = realpathSync(os.homedir());
+    const root = opts.global ? home : discover(opts.cwd);
+    return { root, global: root === home };
+}
+function context() {
+    const { root, global } = targetRoot();
+    const target = loadTarget(root, global);
+    if (!target.catalog || !target.state)
+        throw new Error(target.error ??
+            `Loadout is not initialized here. Run loadout ${global ? '--global ' : ''}init.`);
+    return { catalog: target.catalog, state: target.state };
+}
+function interactiveTargets() {
+    const { root, global } = targetRoot();
+    const home = realpathSync(os.homedir());
+    let local = root;
+    if (global) {
+        try {
+            local = discover(program.opts().cwd);
+        }
+        catch {
+            local = realpathSync(program.opts().cwd);
+        }
+    }
+    const targets = local === home
+        ? [loadTarget(home, true)]
+        : [loadTarget(local, false), loadTarget(home, true)];
+    const initial = global ? targets.length - 1 : 0;
+    const current = targets[initial];
+    if (!current.catalog)
+        throw new Error(current.error ??
+            `Loadout is not initialized here. Run loadout ${global ? '--global ' : ''}init.`);
+    return { targets, initial };
+}
+function preview(result, diff = false) {
+    const changed = result.changes.filter((c) => c.kind !== 'unchanged' && c.path !== '.gitignore');
+    if (!changed.length) {
+        console.log(result.changes.some((c) => c.kind !== 'unchanged')
+            ? 'Ignore rules will be refreshed.'
+            : 'Generated files are unchanged.');
+        return;
+    }
+    console.log('\nPlanned changes:');
+    for (const change of changed)
+        console.log(`  ${change.kind === 'create' ? '+' : change.kind === 'delete' ? '-' : '~'} ${change.path}`);
+    if (diff) {
+        for (const change of changed) {
+            if (change.path.startsWith('.loadout/') || change.path === '.gitignore')
+                continue;
+            const before = change.before?.content ?? Buffer.alloc(0), after = change.after?.content ?? Buffer.alloc(0);
+            if (before.equals(after))
+                continue;
+            if (before.length + after.length > 200_000 ||
+                before.includes(0) ||
+                after.includes(0)) {
+                console.log(`  ${change.path}: binary or large content; inspect the source for details.`);
+            }
+            else {
+                console.log(createTwoFilesPatch(`a/${change.path}`, `b/${change.path}`, before.toString('utf8'), after.toString('utf8'), undefined, undefined, { context: 3 }));
+            }
+        }
+    }
+}
+function showDependencies(catalog, state) {
+    for (const id of resolveKits(catalog, state.selected))
+        if (!state.selected.includes(id))
+            console.log(`${id} required by ${reasons(catalog, state.selected, id).join(', ')}`);
+}
+function options(command) {
+    return command
+        .option('--answer <kit.question=value>', 'set an answer (repeatable)', (value, previous) => [...previous, value], [])
+        .option('--adopt', 'preserve existing instructions and adopt identical skills')
+        .option('--diff', 'show text changes in generated files')
+        .option('--dry-run', 'preview without writing files or saving selections');
+}
+async function generate(catalog, state, opts) {
+    setAnswers(catalog, state, opts.answer ?? []);
+    const configured = await configure(catalog, state);
+    showDependencies(catalog, configured);
+    const rendered = await renderWithExternal(catalog, configured, {
+        update: opts.update,
+        offline: program.opts().offline,
+        onRetry: (id) => console.log(`Retrying ${id}…`),
+        onFetch: (id, source) => console.log(`Fetching ${id} from ${source.repo}…`),
+    });
+    for (const id of resolveKits(catalog, configured.selected)) {
+        const kit = catalog.kits.get(id);
+        if (kit.external) {
+            const source = opts.update?.includes(id)
+                ? kit.external
+                : (kit.pinned ?? kit.external);
+            console.log(`${id}: ${source.repo}@${source.ref.slice(0, 12)} · license: ${source.license}`);
+        }
+    }
+    const result = plan(catalog, configured, rendered, { adopt: opts.adopt });
+    preview(result, opts.diff || !!opts.update?.length || !!result.adopted?.length);
+    if (opts.dryRun)
+        console.log('Dry run: no files or selections saved.');
+    else {
+        const count = apply(result);
+        if (count)
+            console.log(`\nLoadout applied (${count} files changed).`);
+    }
+}
+async function setup() {
+    const { targets, initial } = interactiveTargets();
+    const configured = await interactive(targets, initial);
+    const offline = program.opts().offline;
+    const plans = [];
+    for (const { target, state } of configured) {
+        const catalog = target.catalog;
+        console.log(`\n${target.label} · ${target.root}`);
+        const update = await selectUpdates(catalog, state, offline);
+        const rendered = await renderWithExternal(catalog, state, {
+            offline,
+            update,
+            retry: confirmRetry,
+            onRetry: (id) => console.log(`Retrying ${id}…`),
+            onFetch: (id, source) => console.log(`Fetching ${id} from ${source.repo}…`),
+        });
+        for (const id of resolveKits(catalog, state.selected)) {
+            const kit = catalog.kits.get(id);
+            if (kit.external) {
+                const source = update.includes(id)
+                    ? kit.external
+                    : (kit.pinned ?? kit.external);
+                console.log(`${id}: ${source.repo}@${source.ref.slice(0, 12)} · license: ${source.license}`);
+            }
+        }
+        const result = plan(catalog, state, rendered, { adopt: true });
+        preview(result, update.length > 0 || !!result.adopted?.length);
+        if (result.adopted?.length && !(await confirmAdoption(result.adopted)))
+            throw new DownloadCancelledError();
+        plans.push(result);
+    }
+    if (!plans.some((result) => result.changes.some((c) => c.kind !== 'unchanged')))
+        return;
+    if (await confirmApply()) {
+        applyAll(plans);
+        console.log('\nYour loadout is ready.');
+    }
+    else
+        console.log('Cancelled. No kit selections or agent outputs saved.');
+}
+program.action(setup);
+program
+    .command('init')
+    .description('create a starter catalog and open setup in a terminal')
+    .action(async () => {
+    const opts = program.opts();
+    const root = opts.global ? os.homedir() : opts.cwd;
+    const global = !!opts.global || realpathSync(root) === realpathSync(os.homedir());
+    initialize(root, global);
+    console.log(`Initialized ${realpathSync(root)}/.loadout${global ? '. Choose kits from Browse.' : ' with an editable starter kit.'}`);
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        await setup();
+    else
+        console.log(`Run loadout${global ? ' --global' : ''} in a terminal to choose your kits.`);
+});
+program
+    .command('list')
+    .description('show available kits and why they are enabled')
+    .action(() => {
+    const { catalog, state } = context();
+    const enabled = resolveKits(catalog, state.selected);
+    for (const kit of catalog.kits.values()) {
+        const status = kit.ready === false
+            ? 'Needs setup'
+            : state.selected.includes(kit.id)
+                ? 'selected'
+                : enabled.includes(kit.id)
+                    ? `required by ${reasons(catalog, state.selected, kit.id).join(', ')}`
+                    : 'disabled';
+        console.log(`${kit.id} [${status}]\n  ${kitSource(kit)} · ${kit.description}`);
+    }
+    if (!catalog.kits.size)
+        console.log('No kits found. Add .loadout/kits/<name>/kit.yaml.');
+});
+program
+    .command('explain <kit>')
+    .description('explain why a kit is enabled')
+    .action((id) => {
+    const { catalog, state } = context();
+    if (!catalog.kits.has(id))
+        throw new Error(`Unknown kit: ${id}`);
+    const kit = catalog.kits.get(id);
+    if (kit.external) {
+        const source = kit.pinned ?? kit.external;
+        console.log(`Source: https://github.com/${source.repo}/tree/${source.ref}`);
+        console.log(`Skills: ${source.skills.map((p) => p.split('/').at(-1)).join(', ')}`);
+        if (hasUpdate(kit))
+            console.log(`A different source revision is offered. Run loadout update ${id} --dry-run to preview it.`);
+    }
+    const enabled = resolveKits(catalog, state.selected);
+    if (!enabled.includes(id)) {
+        console.log(`${id} is disabled.`);
+        return;
+    }
+    if (state.selected.includes(id))
+        console.log(`${id} is explicitly selected.`);
+    for (const dependent of reasons(catalog, state.selected, id))
+        console.log(`${id} is required by ${dependent} (directly or transitively).`);
+});
+options(program
+    .command('enable <kits...>')
+    .description('enable kits and their dependencies')).action(async (ids, opts) => {
+    const { catalog, state } = context();
+    state.selected = [...state.selected, ...ids];
+    await generate(catalog, state, opts);
+});
+options(program
+    .command('disable <kit>')
+    .description('disable a kit; preserve dependencies still in use')
+    .option('--cascade', 'also disable explicit selections that require this kit')).action(async (id, opts) => {
+    const { catalog, state } = context();
+    if (!catalog.kits.has(id) && !state.selected.includes(id))
+        throw new Error(`Unknown kit: ${id}`);
+    state.selected = disableKits(catalog, state.selected, id, opts.cascade ?? false);
+    await generate(catalog, state, opts);
+});
+options(program
+    .command('apply')
+    .description('regenerate using saved selections and answers')).action(async (opts) => {
+    const { catalog, state } = context();
+    await generate(catalog, state, opts);
+});
+program
+    .command('outdated')
+    .description('compare downloaded external kits with the current catalog (no network)')
+    .action(() => {
+    const { catalog, state } = context();
+    const enabled = resolveKits(catalog, state.selected);
+    const updates = availableUpdates(catalog);
+    for (const kit of updates)
+        console.log(`${kit.id}${enabled.includes(kit.id) ? '' : ' [disabled]'}\n  ${updateDescription(kit)}`);
+    console.log(updates.length
+        ? '\nRun loadout to review enabled kit updates, or loadout update --dry-run.'
+        : 'No catalog updates for downloaded external kits.');
+    console.log('Compared with this catalog; upstream branches were not checked.');
+});
+options(program
+    .command('update [kits...]')
+    .description('update enabled external kits to their catalog revisions')).action(async (ids, opts) => {
+    const { catalog, state } = context();
+    const update = ids.length
+        ? ids
+        : availableUpdates(catalog, state.selected).map((kit) => kit.id);
+    if (!update.length) {
+        console.log('No catalog updates for enabled external kits.');
+        return;
+    }
+    await generate(catalog, state, { ...opts, update });
+});
+try {
+    await program.parseAsync();
+}
+catch (error) {
+    if (error instanceof Error &&
+        ['ExitPromptError', 'AbortPromptError', 'DownloadCancelledError'].includes(error.name)) {
+        console.log('\nCancelled. No kit selections or agent outputs saved.');
+        process.exitCode = 130;
+    }
+    else {
+        console.error(`loadout: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/curated.d.ts

@@ -0,0 +1,3 @@
+import { type ExternalKit } from './schema.js';
+export declare const providerDescriptions: Readonly<Record<string, string>>;
+export declare const curatedKits: ExternalKit[];

package/dist/curated.js

@@ -0,0 +1,98 @@
+import { externalKitSchema, parse } from './schema.js';
+export const providerDescriptions = {
+    'mattpocock/skills': 'Test-driven development, debugging, planning, and agent workflows',
+    'anthropics/skills': 'Interface design, browser testing, MCP servers, and generative art',
+};
+// Definitions ship with Loadout; upstream content is fetched only when selected.
+const matt = {
+    repo: 'mattpocock/skills',
+    ref: '3cca18b368ae95cdbdebbff572ccafa662551015',
+    license: 'LICENSE',
+};
+const engineering = [
+    [
+        'tdd',
+        'Build features test-first with behavior checks that survive refactors',
+        ['codebase-design'],
+    ],
+    [
+        'diagnosing-bugs',
+        'Reproduce a failure, isolate its cause, and verify the fix',
+    ],
+    [
+        'domain-modeling',
+        'Define shared project terms and capture architecture decisions',
+    ],
+    [
+        'prototype',
+        'Try an interface or state model before committing to a design',
+    ],
+    [
+        'research',
+        'Investigate a question and save findings with source citations',
+    ],
+    [
+        'resolving-merge-conflicts',
+        'Resolve conflicts, verify the result, and commit the merge',
+    ],
+    ['wizard', 'Create a step-by-step Bash wizard for setup only a human can do'],
+];
+const productivity = [
+    [
+        'grill-me',
+        'Challenge a plan until its assumptions and trade-offs are clear',
+        ['grilling'],
+    ],
+    [
+        'writing-for-agents',
+        'Write concise agent instructions with clear triggers and steps',
+    ],
+    [
+        'handoff',
+        'Save decisions, progress, and next steps for a fresh agent session',
+    ],
+    ['teach', 'Learn a topic through guided lessons, practice, and saved notes'],
+    [
+        'to-questionnaire',
+        'Draft a questionnaire to get missing answers from someone else',
+    ],
+    ['wait-what', 'Re-explain the last answer with context and simpler language'],
+];
+const anthropic = [
+    [
+        'frontend-design',
+        'Build interfaces with a clear visual direction, layout, and typography',
+    ],
+    [
+        'webapp-testing',
+        'Check UI behavior and capture screenshots with Python + Playwright',
+    ],
+    ['mcp-builder', 'Build and evaluate MCP tools that connect agents to APIs'],
+    [
+        'algorithmic-art',
+        'Create p5.js art with repeatable seeds and interactive controls',
+    ],
+];
+export const curatedKits = [
+    ...[
+        ['engineering', engineering],
+        ['productivity', productivity],
+    ].flatMap(([group, kits]) => kits.map(([name, description, supporting = []]) => ({
+        id: `matt-pocock-${name}`,
+        description,
+        source: {
+            ...matt,
+            skills: [name, ...supporting].map((skill) => `skills/${group}/${skill}`),
+        },
+    }))),
+    ...anthropic.map(([name, description]) => ({
+        id: `anthropic-${name}`,
+        description,
+        source: {
+            repo: 'anthropics/skills',
+            ref: '34040c9c568585f6929bedeaad110ad08f079624',
+            skills: [`skills/${name}`],
+            license: `skills/${name}/LICENSE.txt`,
+        },
+    })),
+].map((kit) => parse(externalKitSchema, kit, 'Curated kit'));

package/dist/external.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { type Catalog, type State, type ExternalSource } from './schema.js';
+import { type Rendered } from './render.js';
+declare const snapshotSchema: z.ZodObject<{
+    integrity: z.ZodString;
+    source: z.ZodObject<{
+        repo: z.ZodString;
+        ref: z.ZodString;
+        skills: z.ZodArray<z.ZodString>;
+        license: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        data: z.ZodString;
+        sha: z.ZodString;
+        mode: z.ZodUnion<readonly [z.ZodLiteral<420>, z.ZodLiteral<493>]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const storeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kits: z.ZodRecord<z.ZodString, z.ZodObject<{
+        integrity: z.ZodString;
+        source: z.ZodObject<{
+            repo: z.ZodString;
+            ref: z.ZodString;
+            skills: z.ZodArray<z.ZodString>;
+            license: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+        files: z.ZodRecord<z.ZodString, z.ZodObject<{
+            data: z.ZodString;
+            sha: z.ZodString;
+            mode: z.ZodUnion<readonly [z.ZodLiteral<420>, z.ZodLiteral<493>]>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Snapshot = z.infer<typeof snapshotSchema>;
+export type ExternalStore = z.infer<typeof storeSchema>;
+export type FetchBytes = (url: string, limit: number, signal?: AbortSignal) => Promise<Buffer>;
+export declare function readExternal(root: string): {
+    raw?: Buffer;
+    store: ExternalStore;
+};
+export declare const fetchBytes: FetchBytes;
+export declare function renderWithExternal(catalog: Catalog, state: State, options?: {
+    fetch?: FetchBytes;
+    update?: string[];
+    offline?: boolean;
+    onFetch?: (id: string, source: ExternalSource) => void;
+    onRetry?: (id: string) => void;
+    retry?: (id: string, error: Error) => Promise<boolean>;
+}): Promise<Rendered>;
+export {};