fitout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Nichols
+
+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,184 @@
+# Fitout
+
+[![CI](https://github.com/technicalpickles/fitout/actions/workflows/ci.yml/badge.svg)](https://github.com/technicalpickles/fitout/actions/workflows/ci.yml)
+
+Context-aware plugin manager for Claude Code.
+
+## The Problem
+
+Managing Claude Code plugins across projects is painful:
+- Config files *look* correct but don't reflect what's actually installed
+- This mismatch leads to broken sessions and missing capabilities
+- Manually syncing plugins across projects is tedious and error-prone
+
+## The Solution
+
+Fitout ensures your actual runtime state matches your declared configuration.
+
+1. Declare desired plugins in `.claude/fitout.toml`
+2. Run `fitout status` to see the diff
+3. Run `fitout apply` to sync
+
+## Installation
+
+```bash
+# Install globally
+npm install -g fitout
+
+# Set up Claude integration
+fitout init
+```
+
+This adds a SessionStart hook to Claude Code that automatically installs missing plugins when you start a session.
+
+### Non-interactive setup
+
+```bash
+fitout init --yes        # Use defaults (creates default profile)
+fitout init --hook-only  # Only add hook, no profile
+```
+
+Requires [Claude Code CLI](https://claude.ai/docs/claude-code) to be installed.
+
+## Quick Start
+
+Create `.claude/fitout.toml` in your project:
+
+```toml
+plugins = [
+  "superpowers@superpowers-marketplace",
+  "ci-cd-tools@pickled-claude-plugins",
+]
+```
+
+Check status:
+
+```bash
+fitout status
+```
+
+Output:
+
+```
+Context: /path/to/project
+
+✗ superpowers@superpowers-marketplace (missing)
+✗ ci-cd-tools@pickled-claude-plugins (missing)
+
+0 present, 2 missing
+```
+
+Install missing plugins:
+
+```bash
+fitout apply
+```
+
+## Commands
+
+### `fitout status`
+
+Shows the diff between desired and installed plugins.
+
+- `✓` - Plugin is installed
+- `✗` - Plugin is missing
+- `?` - Plugin is installed but not in config
+
+Exit code is `1` if any plugins are missing, `0` otherwise.
+
+### `fitout apply`
+
+Installs missing plugins to sync with config.
+
+```bash
+fitout apply           # Install missing plugins
+fitout apply --dry-run # Preview what would be installed
+```
+
+## Profiles
+
+Share plugin sets across projects using profiles.
+
+### User Profiles
+
+Create profiles at `~/.config/fitout/profiles/`:
+
+```toml
+# ~/.config/fitout/profiles/default.toml
+# Auto-included in every project (silent if missing)
+plugins = [
+  "superpowers@superpowers-marketplace",
+]
+```
+
+```toml
+# ~/.config/fitout/profiles/backend.toml
+plugins = [
+  "database-tools@some-registry",
+  "api-helpers@some-registry",
+]
+```
+
+### Using Profiles
+
+Reference profiles in your project config:
+
+```toml
+# .claude/fitout.toml
+profiles = ["backend"]
+plugins = [
+  "project-specific@registry",
+]
+```
+
+Plugins merge additively. The `default` profile auto-includes if present.
+
+### Provenance
+
+Status output shows where each plugin comes from:
+
+```
+Context: /path/to/project
+
+✓ superpowers@superpowers-marketplace (from: default)
+✓ database-tools@some-registry (from: backend)
+✓ project-specific@registry
+
+3 present
+```
+
+## Configuration Reference
+
+### Project Config (`.claude/fitout.toml`)
+
+```toml
+# Optional: explicit profiles to include
+profiles = ["backend", "testing"]
+
+# Required: plugins for this project
+plugins = [
+  "plugin-name@registry",
+]
+```
+
+### Profile Config (`~/.config/fitout/profiles/<name>.toml`)
+
+```toml
+# Plugins provided by this profile
+plugins = [
+  "plugin-name@registry",
+]
+```
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm test             # Run tests
+npm run dev -- status # Run in dev mode
+npm run build        # Build to dist/
+```
+
+## License
+
+MIT

package/dist/claude.d.ts

@@ -0,0 +1,10 @@
+export interface InstalledPlugin {
+    id: string;
+    version: string;
+    scope: 'local' | 'user' | 'global';
+    enabled: boolean;
+    projectPath?: string;
+}
+export declare function parsePluginList(jsonOutput: string): InstalledPlugin[];
+export declare function listPlugins(): InstalledPlugin[];
+export declare function installPlugin(pluginId: string): void;

package/dist/claude.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+export function parsePluginList(jsonOutput) {
+    const parsed = JSON.parse(jsonOutput);
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    return parsed;
+}
+export function listPlugins() {
+    const output = execFileSync('claude', ['plugin', 'list', '--json'], {
+        encoding: 'utf-8',
+    });
+    return parsePluginList(output);
+}
+export function installPlugin(pluginId) {
+    execFileSync('claude', ['plugin', 'install', pluginId, '--scope', 'local'], {
+        encoding: 'utf-8',
+        stdio: 'inherit',
+    });
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { runStatus } from './status.js';
+import { runInstall } from './install.js';
+import { runInit, getProjectConfigPath, readClaudeSettings, getFitoutHookStatus, hasFitoutSkill, hasDefaultProfile, hasProjectConfig, getProjectConfigContent, getDefaultProfilePath, } from './init.js';
+import { getClaudeSettingsPath, getFitoutSkillPath } from './paths.js';
+import { getProfilesDir, resolveProjectRoot } from './context.js';
+import { confirm, input } from './prompt.js';
+import { colors, symbols, formatPath } from './colors.js';
+import { hasGlobalConfig, createGlobalConfig, getGlobalConfigPath, getGlobalConfigContent } from './globalConfig.js';
+import { refreshMarketplaces, listAvailablePlugins } from './marketplace.js';
+import { runUpdate, updatePlugin } from './update.js';
+import { listPlugins } from './claude.js';
+import { handleCompletion, installCompletion, uninstallCompletion } from './completion.js';
+// Handle shell completion requests before command parsing
+if (handleCompletion()) {
+    process.exit(0);
+}
+program
+    .name('fitout')
+    .description('Context-aware plugin manager for Claude Code')
+    .version('0.1.0');
+program
+    .command('status')
+    .description('Show desired vs actual plugin state')
+    .option('--refresh', 'Refresh marketplace data before checking')
+    .action((options) => {
+    const { output, exitCode } = runStatus(process.cwd(), {
+        refresh: options.refresh,
+    });
+    console.log(output);
+    process.exit(exitCode);
+});
+// Helper for install action (used by both `install` command and default)
+function doInstall(options = {}) {
+    const { output, exitCode } = runInstall(process.cwd(), {
+        dryRun: options.dryRun,
+        hook: options.hook,
+    });
+    if (output) {
+        console.log(output);
+    }
+    process.exit(exitCode);
+}
+program
+    .command('install', { isDefault: true })
+    .description('Install missing plugins to sync desired state')
+    .option('--dry-run', 'Show what would change without installing')
+    .option('--hook', 'Hook mode: silent on no-op, minimal output for Claude context')
+    .action((options) => doInstall(options));
+program
+    .command('update [plugins...]')
+    .description('Update outdated plugins (all if no plugins specified)')
+    .option('--offline', 'Skip marketplace refresh, use cached data')
+    .option('--dry-run', 'Show what would be updated without applying')
+    .action((plugins, options) => {
+    const projectRoot = resolveProjectRoot(process.cwd());
+    // Refresh by default, unless --offline
+    if (!options.offline) {
+        console.log('Refreshing marketplaces...');
+        refreshMarketplaces();
+    }
+    const installed = listPlugins();
+    const available = listAvailablePlugins();
+    const result = runUpdate(projectRoot, installed, available, plugins, {
+        dryRun: options.dryRun,
+    });
+    if (result.output) {
+        console.log(result.output);
+    }
+    if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
+    }
+    // Perform actual updates
+    if (result.pluginsToUpdate.length > 0) {
+        for (const plugin of result.pluginsToUpdate) {
+            console.log(`  ${symbols.outdated} ${plugin.id} v${plugin.installedVersion} → v${plugin.availableVersion}`);
+            updatePlugin(plugin.id);
+        }
+        console.log('');
+        console.log(`Updated ${result.pluginsToUpdate.length} plugin${result.pluginsToUpdate.length > 1 ? 's' : ''}. Restart Claude to apply changes.`);
+    }
+    process.exit(0);
+});
+// Marketplace subcommands
+const marketplace = program
+    .command('marketplace')
+    .description('Manage Claude Code marketplaces');
+marketplace
+    .command('refresh')
+    .description('Update marketplace data from sources')
+    .action(() => {
+    console.log('Refreshing marketplaces...');
+    refreshMarketplaces();
+    console.log(`${symbols.present} Marketplaces updated`);
+    process.exit(0);
+});
+program
+    .command('init')
+    .description('Set up Fitout integration with Claude Code')
+    .option('-y, --yes', 'Skip prompts, use defaults')
+    .option('--hook-only', 'Only add the hook, do not create profile or project config')
+    .action(async (options) => {
+    const settingsPath = getClaudeSettingsPath();
+    const profilesDir = getProfilesDir();
+    const projectRoot = resolveProjectRoot(process.cwd());
+    const projectConfigPath = getProjectConfigPath(projectRoot);
+    const skillPath = getFitoutSkillPath();
+    // Check current state
+    const settings = readClaudeSettings(settingsPath);
+    const hookStatus = getFitoutHookStatus(settings);
+    const hookExists = hookStatus !== 'none';
+    const hookOutdated = hookStatus === 'outdated';
+    const skillExists = hasFitoutSkill();
+    const profileExists = hasDefaultProfile(profilesDir);
+    const configExists = hasProjectConfig(projectRoot);
+    // Handle --hook-only mode
+    if (options.hookOnly) {
+        if (hookStatus === 'current') {
+            console.log(`${symbols.present} Hook already installed`);
+            process.exit(0);
+        }
+        const result = runInit({
+            settingsPath,
+            profilesDir,
+            createProfile: false,
+            createSkill: false,
+        });
+        if (result.hookUpgraded) {
+            console.log(`${symbols.present} SessionStart hook upgraded in ${formatPath(settingsPath)}`);
+        }
+        else {
+            console.log(`${symbols.present} SessionStart hook added to ${formatPath(settingsPath)}`);
+        }
+        console.log(colors.dim('  Restart Claude to activate'));
+        process.exit(0);
+    }
+    // Handle --yes mode (non-interactive)
+    if (options.yes) {
+        const result = runInit({
+            settingsPath,
+            profilesDir,
+            createProfile: true,
+            profileName: 'default',
+            projectRoot,
+            createProjectConfig: true,
+            createSkill: true,
+        });
+        const created = [];
+        const upgraded = [];
+        if (result.hookAdded)
+            created.push('hook');
+        if (result.hookUpgraded)
+            upgraded.push('hook');
+        if (result.skillCreated)
+            created.push('skill');
+        if (result.profileCreated)
+            created.push('profile');
+        if (result.projectConfigCreated)
+            created.push('project config');
+        if (created.length === 0 && upgraded.length === 0) {
+            console.log(`${symbols.present} Already initialized`);
+        }
+        else {
+            const parts = [];
+            if (created.length > 0)
+                parts.push(`Created: ${created.join(', ')}`);
+            if (upgraded.length > 0)
+                parts.push(`Upgraded: ${upgraded.join(', ')}`);
+            console.log(`${symbols.present} ${parts.join('. ')}`);
+            console.log(colors.dim('  Restart Claude to activate'));
+        }
+        process.exit(0);
+    }
+    // Interactive phased mode
+    console.log('Checking Fitout setup...\n');
+    // Phase 1: Global setup
+    console.log(colors.header('Global:'));
+    let needsGlobalSetup = false;
+    if (hookStatus === 'current') {
+        console.log(`  ${symbols.present} SessionStart hook`);
+    }
+    else if (hookStatus === 'outdated') {
+        console.log(`  ${symbols.outdated} SessionStart hook ${colors.dim('(outdated)')}`);
+        needsGlobalSetup = true;
+    }
+    else {
+        console.log(`  ${symbols.missing} SessionStart hook ${colors.dim('(missing)')}`);
+        needsGlobalSetup = true;
+    }
+    if (skillExists) {
+        console.log(`  ${symbols.present} Diagnostic skill`);
+    }
+    else {
+        console.log(`  ${symbols.missing} Diagnostic skill ${colors.dim('(missing)')}`);
+        needsGlobalSetup = true;
+    }
+    const globalConfigExists = hasGlobalConfig();
+    if (globalConfigExists) {
+        console.log(`  ${symbols.present} Global config`);
+    }
+    else {
+        console.log(`  ${symbols.missing} Global config ${colors.dim('(optional)')}`);
+    }
+    // Set up global components if needed
+    let hookAdded = false;
+    let hookUpgraded = false;
+    let skillCreated = false;
+    let globalConfigCreated = false;
+    if (needsGlobalSetup) {
+        console.log('');
+        const promptText = hookOutdated
+            ? 'Set up missing/outdated global components?'
+            : 'Set up missing global components?';
+        const setupGlobal = await confirm(promptText);
+        if (setupGlobal) {
+            const result = runInit({
+                settingsPath,
+                profilesDir,
+                createProfile: false,
+                createSkill: !skillExists,
+            });
+            hookAdded = result.hookAdded;
+            hookUpgraded = result.hookUpgraded;
+            skillCreated = result.skillCreated;
+            if (hookAdded)
+                console.log(`  ${symbols.present} Hook installed`);
+            if (hookUpgraded)
+                console.log(`  ${symbols.present} Hook upgraded`);
+            if (skillCreated)
+                console.log(`  ${symbols.present} Skill installed`);
+        }
+    }
+    // Offer to create global config if missing
+    if (!globalConfigExists) {
+        console.log('');
+        const createConfig = await confirm('Create global config for marketplaces?');
+        if (createConfig) {
+            // Show preview
+            const configContent = getGlobalConfigContent();
+            console.log(`\nReady to create ${formatPath(getGlobalConfigPath())}:`);
+            console.log(colors.dim('    ' + configContent.split('\n').join('\n    ')));
+            const confirmCreate = await confirm('Create?');
+            if (confirmCreate) {
+                globalConfigCreated = createGlobalConfig();
+                if (globalConfigCreated) {
+                    console.log(`  ${symbols.present} Created ${formatPath(getGlobalConfigPath())}`);
+                }
+            }
+        }
+    }
+    // Phase 2: Default profile
+    console.log('');
+    console.log(colors.header('Profile:'));
+    let profileCreated = false;
+    let profileName = 'default';
+    if (profileExists) {
+        console.log(`  ${symbols.present} Default profile`);
+    }
+    else {
+        console.log(`  ${symbols.missing} Default profile ${colors.dim('(missing)')}`);
+        console.log('');
+        const createProfile = await confirm('Create a default profile?');
+        if (createProfile) {
+            profileName = await input('Profile name', 'default');
+            const result = runInit({
+                settingsPath,
+                profilesDir,
+                createProfile: true,
+                profileName,
+                createSkill: false,
+            });
+            profileCreated = result.profileCreated;
+            if (profileCreated) {
+                console.log(`  ${symbols.present} Created ${formatPath(getDefaultProfilePath(profilesDir, profileName))}`);
+            }
+        }
+    }
+    // Phase 3: Project config
+    console.log('');
+    console.log(colors.header('Project:'));
+    let projectConfigCreated = false;
+    if (configExists) {
+        console.log(`  ${symbols.present} Project config`);
+    }
+    else {
+        console.log(`  ${symbols.missing} Project config ${colors.dim('(missing)')}`);
+        console.log('');
+        // Show preview
+        const configContent = getProjectConfigContent(profileCreated || profileExists ? profileName : undefined);
+        console.log(`Ready to create ${formatPath(projectConfigPath)}:`);
+        console.log(colors.dim('    ' + configContent.split('\n').join('\n    ')));
+        const createConfig = await confirm('Create project config?');
+        if (createConfig) {
+            const result = runInit({
+                settingsPath,
+                profilesDir,
+                createProfile: false,
+                projectRoot,
+                createProjectConfig: true,
+                createSkill: false,
+            });
+            projectConfigCreated = result.projectConfigCreated;
+            if (projectConfigCreated) {
+                console.log(`  ${symbols.present} Created ${formatPath(projectConfigPath)}`);
+            }
+        }
+    }
+    // Summary
+    console.log('');
+    const anythingCreated = hookAdded || hookUpgraded || skillCreated || globalConfigCreated || profileCreated || projectConfigCreated;
+    if (!anythingCreated && hookExists && skillExists && profileExists && configExists) {
+        console.log(`${symbols.present} ${colors.success('Already initialized')}`);
+    }
+    else if (anythingCreated) {
+        console.log(colors.dim('Restart Claude to activate changes.'));
+    }
+    process.exit(0);
+});
+// Completion subcommands
+const completion = program
+    .command('completion')
+    .description('Manage shell completions');
+completion
+    .command('install')
+    .description('Install shell completions')
+    .argument('[shell]', 'Shell type: bash, zsh, fish, or pwsh (prompts if not specified)')
+    .action(async (shell) => {
+    try {
+        await installCompletion(shell);
+        console.log(`${symbols.present} Shell completions installed`);
+        console.log(colors.dim('  Restart your shell or source your config to activate'));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error(`Failed to install completions: ${err}`);
+        process.exit(1);
+    }
+});
+completion
+    .command('uninstall')
+    .description('Remove shell completions')
+    .action(async () => {
+    try {
+        await uninstallCompletion();
+        console.log(`${symbols.present} Shell completions removed`);
+        process.exit(0);
+    }
+    catch (err) {
+        console.error(`Failed to uninstall completions: ${err}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/colors.d.ts

@@ -0,0 +1,27 @@
+export declare const colors: {
+    success: import("chalk").ChalkInstance;
+    error: import("chalk").ChalkInstance;
+    warning: import("chalk").ChalkInstance;
+    action: import("chalk").ChalkInstance;
+    header: import("chalk").ChalkInstance;
+    dim: import("chalk").ChalkInstance;
+    sourceDefault: import("chalk").ChalkInstance;
+    sourceProject: import("chalk").ChalkInstance;
+    sourceOther: import("chalk").ChalkInstance;
+};
+export declare const symbols: {
+    present: string;
+    missing: string;
+    extra: string;
+    install: string;
+    outdated: string;
+};
+export declare function provenanceColor(source: string): (text: string) => string;
+/**
+ * Format a path for display, replacing $HOME with ~
+ */
+export declare function formatPath(path: string): string;
+/**
+ * Format context line, only showing if different from cwd
+ */
+export declare function formatContextLine(projectRoot: string, cwd: string): string;

package/dist/colors.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { homedir } from 'node:os';
+export const colors = {
+    // Semantic
+    success: chalk.green,
+    error: chalk.red,
+    warning: chalk.yellow,
+    action: chalk.cyan,
+    // Structural
+    header: chalk.bold.white,
+    dim: chalk.dim,
+    // Provenance (dim versions)
+    sourceDefault: chalk.dim.blue,
+    sourceProject: chalk.dim.magenta,
+    sourceOther: chalk.dim.cyan,
+};
+export const symbols = {
+    present: colors.success('✓'),
+    missing: colors.error('✗'),
+    extra: colors.warning('?'),
+    install: colors.action('+'),
+    outdated: colors.warning('↑'),
+};
+export function provenanceColor(source) {
+    switch (source) {
+        case 'default':
+            return colors.sourceDefault;
+        case 'project':
+            return colors.sourceProject;
+        default:
+            return colors.sourceOther;
+    }
+}
+/**
+ * Format a path for display, replacing $HOME with ~
+ */
+export function formatPath(path) {
+    const home = homedir();
+    return path.startsWith(home) ? path.replace(home, '~') : path;
+}
+/**
+ * Format context line, only showing if different from cwd
+ */
+export function formatContextLine(projectRoot, cwd) {
+    if (projectRoot === cwd) {
+        return '';
+    }
+    return `${colors.header('Context:')} ${formatPath(projectRoot)}\n\n`;
+}

package/dist/completion.d.ts

@@ -0,0 +1,14 @@
+import { type SupportedShell } from '@pnpm/tabtab';
+/**
+ * Handle shell completion requests.
+ * Call this early in CLI startup - returns true if we handled a completion request.
+ */
+export declare function handleCompletion(): boolean;
+/**
+ * Install shell completions
+ */
+export declare function installCompletion(shell?: SupportedShell): Promise<void>;
+/**
+ * Uninstall shell completions
+ */
+export declare function uninstallCompletion(): Promise<void>;