@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/commands/surface.js

@@ -0,0 +1,43 @@
+// `crtr surface` — the screen-facing entrypoints.
+//
+// Groups the four surface families under one canonical noun: standalone tmux
+// views, live broker attachment, the split editor workspace, and the browser
+// shell.
+import { defineBranch } from '../core/command.js';
+import { registerView } from './view.js';
+import { registerWorkspace } from './workspace.js';
+import { registerWeb } from '../clients/web/web-cmd.js';
+import { registerAttach } from '../clients/attach/attach-cmd.js';
+function namespaceForSurface(node) {
+    node.help.name = `surface ${node.help.name}`;
+    if (node.kind === 'branch') {
+        node.description = node.rootEntry?.concept ?? node.description ?? '';
+        node.whenToUse = node.rootEntry?.useWhen ?? node.whenToUse ?? '';
+        for (const child of node.children)
+            namespaceForSurface(child);
+    }
+}
+export function registerSurface() {
+    const view = registerView();
+    const attach = registerAttach();
+    const workspace = registerWorkspace();
+    const web = registerWeb();
+    for (const child of [view, attach, workspace, web]) {
+        child.tier = 'important';
+        namespaceForSurface(child);
+    }
+    return defineBranch({
+        name: 'surface',
+        rootEntry: {
+            concept: 'screen-facing surfaces — tmux views, live broker attachment, the editor workspace, and the browser shell',
+            desc: 'open and manage screen-facing surfaces',
+            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — standalone tmux views, live broker attachment, the split workspace layout, or the browser-hosted shell',
+        },
+        help: {
+            name: 'surface',
+            summary: 'open and manage screen-facing surfaces',
+            model: 'Four entrypoints share the screen-facing space. `view` hosts a standalone raw-ANSI surface in tmux; `attach` connects this pane to a node broker; `workspace` lays out the left rail plus chat pane in one tmux window; `web` serves the browser shell and broker relay. Pick the family by host and layout, then choose the leaf that matches the action.',
+        },
+        children: [view, attach, workspace, web],
+    });
+}

package/dist/commands/sys/promptstudio.js

@@ -36,7 +36,7 @@ export const sysPromptStudioLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Binds the same long-running local web server as `crtr web serve`, opens `/views/prompt-review` in the default browser, and keeps serving until ctrl+c/SIGTERM.',
+            'Binds the same long-running local web server as the surface web serve leaf, opens `/views/prompt-review` in the default browser, and keeps serving until ctrl+c/SIGTERM.',
             'The Prompt Studio view uses the existing source bridge to call `crtr sys prompt-review` for composed prompts and review export.',
         ],
     },

package/dist/commands/sys/settings.js

@@ -3,14 +3,14 @@ import { viewRunLeaf } from '../view-run.js';
 export const sysSettingsLeaf = defineLeaf({
     name: 'settings',
     description: 'open the model ladders settings view',
-    whenToUse: 'you want to open the built-in model ladders settings view in tmux — the same interactive surface as `crtr view run settings`. Use this from `crtr sys` when you want the settings opener beside the rest of system config.',
+    whenToUse: 'you want to open the built-in model ladders settings view in tmux — the same interactive surface as the settings view host. Use this from sys when you want the settings opener beside the rest of system config.',
     help: {
         name: 'sys settings',
         summary: 'open the built-in model ladders settings view',
         inputNote: 'No input parameters.',
         output: [],
         outputKind: 'object',
-        effects: ['Hosts the built-in `settings` view via `crtr view run settings`, preserving the same tmux and non-TTY behavior.'],
+        effects: ['Hosts the built-in settings view, preserving the same tmux and non-TTY behavior.'],
     },
     run: async () => viewRunLeaf.run({ name: 'settings' }),
 });

package/dist/commands/sys/setup-core.d.ts

@@ -0,0 +1,88 @@
+export type SetupPackageId = 'crtr-extensions' | 'mode-switch' | 'oauth-adapter';
+export type SetupTool = 'tmux' | 'nvim';
+export type SetupPackageSourceKind = 'local-path' | 'npm';
+export type SetupPackageIdentity = string;
+export type PackageManager = 'brew' | 'apt-get' | 'dnf' | 'pacman' | 'manual';
+export interface SetupPackageManifestEntry {
+    id: SetupPackageId;
+    name: string;
+    sourceKind: SetupPackageSourceKind;
+    installSource: string;
+    shortDescription: string;
+    longDescription: string;
+}
+export interface SetupSystemInstallPlan {
+    tool: SetupTool;
+    label: string;
+    installed: boolean;
+    checked: boolean;
+    packageManager: PackageManager;
+    command: string | null;
+    hint: string;
+    autoInstall: boolean;
+}
+export interface SetupSystemToolState {
+    tool: SetupTool;
+    installed: boolean;
+    plan: SetupSystemInstallPlan;
+}
+export interface SetupStaticInstructions {
+    headline: string;
+    packageLines: string[];
+    systemLines: string[];
+    exaLine: string;
+    footer: string;
+}
+export interface SetupSubmission {
+    packages: SetupPackageManifestEntry[];
+    installedPackageIds: Set<SetupPackageId>;
+    systemDeps: SetupSystemInstallPlan[];
+    exaKey: string;
+    exaKeyPath: string;
+}
+export interface SetupExecutionSummary {
+    installed: string[];
+    skipped: string[];
+    exaKeyWritten: boolean;
+    exaKeyPath: string;
+}
+export interface SetupInitialState {
+    manifest: SetupPackageManifestEntry[];
+    installedPackageIds: Set<SetupPackageId>;
+    systemTools: SetupSystemToolState[];
+    exaKeyPath: string;
+}
+export declare function buildSetupManifest(resolveBuiltinPackageDir?: (name: string) => string): SetupPackageManifestEntry[];
+export declare function normalizePackageIdentity(source: string, settingsDir: string, homeDir: string): SetupPackageIdentity;
+export declare function detectInstalledSetupPackageIds(settingsJson: unknown, manifest?: SetupPackageManifestEntry[], settingsPath?: string, homeDir?: string): Set<SetupPackageId>;
+export declare function detectCommandOnPath(command: string): boolean;
+export declare function detectPackageManager(platform?: NodeJS.Platform, commandExists?: (command: string) => boolean): PackageManager;
+export declare function buildSystemInstallPlan(tool: SetupTool, packageManager: PackageManager, installed: boolean): SetupSystemInstallPlan;
+export declare function buildSystemToolState(tool: SetupTool, packageManager: PackageManager, commandExists?: (command: string) => boolean): SetupSystemToolState;
+export declare function resolveSettingsPath(homeDir?: string): string;
+export declare function resolveExaKeyPath(homeDir?: string): string;
+export declare function buildSetupInitialState(opts?: {
+    manifest?: SetupPackageManifestEntry[];
+    settingsPath?: string;
+    homeDir?: string;
+    packageManager?: PackageManager;
+    commandExists?: (command: string) => boolean;
+}): SetupInitialState;
+export declare function buildSetupStaticInstructions(opts: {
+    manifest: SetupPackageManifestEntry[];
+    installedPackageIds: Set<SetupPackageId>;
+    systemPlans: SetupSystemInstallPlan[];
+    exaKeyPath: string;
+}): SetupStaticInstructions;
+export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath'>): string;
+export declare function writeExaKey(exaKeyPath: string, exaKey: string): Promise<void>;
+export declare function summarizeSetupExecution(result: {
+    installedPackages: string[];
+    skippedPackages: string[];
+    installedSystemDeps: string[];
+    skippedSystemDeps: string[];
+    exaKeyWritten: boolean;
+    exaKeyPath: string;
+}): SetupExecutionSummary;
+export declare function formatSetupExecutionSummary(summary: SetupExecutionSummary): string;
+export declare function executeSetupSubmission(submission: SetupSubmission): Promise<SetupExecutionSummary>;

package/dist/commands/sys/setup-core.js

@@ -0,0 +1,352 @@
+import { spawnSync } from 'node:child_process';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { builtinPiPackageDir } from '../../core/scope.js';
+import { readJsonIfExists } from '../../core/fs-utils.js';
+const PACKAGE_COPY = {
+    'crtr-extensions': {
+        name: 'pi-crtr-extensions',
+        shortDescription: 'crtr companion extensions — command palette, help gating, statusline, subscription/OAuth rotation, nested context.',
+        longDescription: 'Bundles the extensions built for crtr: a crtr slash-command palette, crtr/crouter help gating, surfacing of Claude Code marketplace plugin commands, nested AGENTS.md/CLAUDE.md loading, a model/subscription/token statusline badge, OAuth login + rotation across multiple Claude subscriptions (provider-rotation), and system-prompt trimming. The OAuth/rotation piece is what lets crtr authenticate your Claude account.',
+    },
+    'mode-switch': {
+        name: 'pi-mode-switch',
+        shortDescription: 'Alt+M cycles spec / plan / normal modes; injects mode-specific guidance on change.',
+        longDescription: 'Press Alt+M to rotate between three operating modes — spec (requirements gathering), plan (design before code), and normal (execution). Each switch appends mode-tailored guidance to keep the agent in the right gear.',
+    },
+    'oauth-adapter': {
+        name: 'pi-claude-oauth-adapter',
+        shortDescription: 'Anthropic OAuth / Claude Code credential compatibility for pi.',
+        longDescription: 'Third-party adapter (minzique/dotfiles-agents) letting pi authenticate with Claude using Claude Code OAuth credentials. Installed from npm, pinned to 0.1.2.',
+    },
+};
+const PACKAGE_SOURCES = {
+    'crtr-extensions': { kind: 'local-path', source: builtinPiPackageDir('pi-crtr-extensions') },
+    'mode-switch': { kind: 'local-path', source: builtinPiPackageDir('pi-mode-switch') },
+    'oauth-adapter': { kind: 'npm', source: 'npm:pi-claude-oauth-adapter@0.1.2' },
+};
+const LOCAL_PACKAGE_NAME_ALIASES = {
+    'crtr-extensions': ['pi-crtr-extensions'],
+    'mode-switch': ['pi-mode-switch'],
+    'oauth-adapter': [],
+};
+export function buildSetupManifest(resolveBuiltinPackageDir = builtinPiPackageDir) {
+    return [
+        'crtr-extensions',
+        'mode-switch',
+        'oauth-adapter',
+    ].map((id) => {
+        const copy = PACKAGE_COPY[id];
+        const source = id === 'oauth-adapter'
+            ? PACKAGE_SOURCES[id].source
+            : resolveBuiltinPackageDir(copy.name);
+        return {
+            id,
+            name: copy.name,
+            sourceKind: PACKAGE_SOURCES[id].kind,
+            installSource: source,
+            shortDescription: copy.shortDescription,
+            longDescription: copy.longDescription,
+        };
+    });
+}
+function expandTilde(pathValue, homeDir) {
+    if (pathValue === '~')
+        return homeDir;
+    if (pathValue.startsWith('~/'))
+        return join(homeDir, pathValue.slice(2));
+    return pathValue;
+}
+function npmPackageName(source) {
+    if (!source.startsWith('npm:'))
+        return null;
+    const spec = source.slice(4);
+    const versionIndex = spec.startsWith('@') ? spec.indexOf('@', 1) : spec.lastIndexOf('@');
+    return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+}
+export function normalizePackageIdentity(source, settingsDir, homeDir) {
+    const npmName = npmPackageName(source);
+    if (npmName !== null)
+        return `npm:${npmName}`;
+    const expanded = expandTilde(source, homeDir);
+    return resolve(settingsDir, expanded);
+}
+function packageNameIdentity(name) {
+    return `package:${name}`;
+}
+function localPackageNameIdentities(source) {
+    if (source.startsWith('npm:'))
+        return [];
+    return [packageNameIdentity(basename(source))];
+}
+function manifestIdentities(entry, settingsDir, homeDir) {
+    const identities = [normalizePackageIdentity(entry.installSource, settingsDir, homeDir)];
+    if (entry.sourceKind === 'local-path') {
+        identities.push(packageNameIdentity(entry.name));
+        for (const alias of LOCAL_PACKAGE_NAME_ALIASES[entry.id])
+            identities.push(packageNameIdentity(alias));
+    }
+    return identities;
+}
+export function detectInstalledSetupPackageIds(settingsJson, manifest = buildSetupManifest(), settingsPath = join(homedir(), '.pi', 'agent', 'settings.json'), homeDir = homedir()) {
+    const settingsDir = dirname(settingsPath);
+    const installed = new Set();
+    const manifestByIdentity = new Map();
+    for (const entry of manifest) {
+        for (const identity of manifestIdentities(entry, settingsDir, homeDir)) {
+            manifestByIdentity.set(identity, entry.id);
+        }
+    }
+    const rawPackages = settingsJson && typeof settingsJson === 'object'
+        ? settingsJson.packages
+        : undefined;
+    if (!Array.isArray(rawPackages))
+        return installed;
+    for (const raw of rawPackages) {
+        const source = typeof raw === 'string'
+            ? raw
+            : raw && typeof raw === 'object' && typeof raw.source === 'string'
+                ? raw.source
+                : null;
+        if (source === null)
+            continue;
+        const identities = [
+            normalizePackageIdentity(source, settingsDir, homeDir),
+            ...localPackageNameIdentities(source),
+        ];
+        for (const identity of identities) {
+            const id = manifestByIdentity.get(identity);
+            if (id !== undefined)
+                installed.add(id);
+        }
+    }
+    return installed;
+}
+export function detectCommandOnPath(command) {
+    const res = spawnSync('sh', ['-lc', `command -v ${command} >/dev/null 2>&1`], { stdio: 'ignore' });
+    return res.status === 0;
+}
+export function detectPackageManager(platform = process.platform, commandExists = detectCommandOnPath) {
+    switch (platform) {
+        case 'darwin':
+            return commandExists('brew') ? 'brew' : 'manual';
+        case 'linux':
+            if (commandExists('apt-get'))
+                return 'apt-get';
+            if (commandExists('dnf'))
+                return 'dnf';
+            if (commandExists('pacman'))
+                return 'pacman';
+            return 'manual';
+        default:
+            return 'manual';
+    }
+}
+export function buildSystemInstallPlan(tool, packageManager, installed) {
+    const label = `Install ${tool}`;
+    if (installed) {
+        return {
+            tool,
+            label,
+            installed: true,
+            checked: false,
+            packageManager,
+            command: null,
+            hint: 'already installed',
+            autoInstall: false,
+        };
+    }
+    const packageName = tool === 'nvim' ? 'neovim' : 'tmux';
+    switch (packageManager) {
+        case 'brew':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `brew install ${packageName}`,
+                hint: 'Homebrew install',
+                autoInstall: true,
+            };
+        case 'apt-get':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo apt-get update && sudo apt-get install -y ${packageName}`,
+                hint: 'apt-get install',
+                autoInstall: true,
+            };
+        case 'dnf':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo dnf install -y ${packageName}`,
+                hint: 'dnf install',
+                autoInstall: true,
+            };
+        case 'pacman':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo pacman -S --noconfirm ${packageName}`,
+                hint: 'pacman install',
+                autoInstall: true,
+            };
+        default:
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: false,
+                packageManager: 'manual',
+                command: null,
+                hint: `manual install required for ${tool}`,
+                autoInstall: false,
+            };
+    }
+}
+export function buildSystemToolState(tool, packageManager, commandExists = detectCommandOnPath) {
+    const installed = commandExists(tool);
+    return {
+        tool,
+        installed,
+        plan: buildSystemInstallPlan(tool, packageManager, installed),
+    };
+}
+export function resolveSettingsPath(homeDir = homedir()) {
+    return join(homeDir, '.pi', 'agent', 'settings.json');
+}
+export function resolveExaKeyPath(homeDir = homedir()) {
+    return join(homeDir, '.crouter', 'exa.key');
+}
+export function buildSetupInitialState(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const settingsPath = opts.settingsPath ?? resolveSettingsPath(homeDir);
+    const manifest = opts.manifest ?? buildSetupManifest(builtinPiPackageDir);
+    const settingsJson = readJsonIfExists(settingsPath);
+    const installedPackageIds = detectInstalledSetupPackageIds(settingsJson, manifest, settingsPath, homeDir);
+    const commandExists = opts.commandExists ?? detectCommandOnPath;
+    const packageManager = opts.packageManager ?? detectPackageManager(process.platform, commandExists);
+    const systemTools = ['tmux', 'nvim'].map((tool) => buildSystemToolState(tool, packageManager, commandExists));
+    return { manifest, installedPackageIds, systemTools, exaKeyPath: resolveExaKeyPath(homeDir) };
+}
+export function buildSetupStaticInstructions(opts) {
+    return {
+        headline: 'crtr sys setup (non-interactive)',
+        packageLines: opts.manifest.map((entry) => {
+            const installed = opts.installedPackageIds.has(entry.id) ? 'installed' : 'not installed';
+            return `- ${entry.name} — ${entry.shortDescription} (${installed})`;
+        }),
+        systemLines: opts.systemPlans.map((plan) => {
+            if (plan.installed)
+                return `- ${plan.tool}: ✓ installed`;
+            if (plan.command)
+                return `- ${plan.tool}: ${plan.command}`;
+            return `- ${plan.tool}: ${plan.hint}`;
+        }),
+        exaLine: `- Exa key: write to ${opts.exaKeyPath} or set EXA_API_KEY`,
+        footer: 'Run `crtr sys setup` in a TTY to open the wizard.',
+    };
+}
+export function renderSetupStaticInstructions(state) {
+    const instructions = buildSetupStaticInstructions({
+        manifest: state.manifest,
+        installedPackageIds: state.installedPackageIds,
+        systemPlans: state.systemTools.map((tool) => tool.plan),
+        exaKeyPath: state.exaKeyPath,
+    });
+    return [
+        instructions.headline,
+        '',
+        'Packages:',
+        ...instructions.packageLines,
+        '',
+        'System deps:',
+        ...instructions.systemLines,
+        '',
+        instructions.exaLine,
+        instructions.footer,
+    ].join('\n') + '\n';
+}
+function runShellCommand(command) {
+    const result = spawnSync('sh', ['-lc', command], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        throw new Error(`command failed: ${command}`);
+    }
+}
+function installPiPackage(source) {
+    const result = spawnSync('pi', ['install', source], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        throw new Error(`pi install failed: ${source}`);
+    }
+}
+export async function writeExaKey(exaKeyPath, exaKey) {
+    await mkdir(dirname(exaKeyPath), { recursive: true });
+    await writeFile(exaKeyPath, `${exaKey}\n`, 'utf8');
+    await chmod(exaKeyPath, 0o600).catch(() => undefined);
+}
+export function summarizeSetupExecution(result) {
+    return {
+        installed: [...result.installedPackages, ...result.installedSystemDeps],
+        skipped: [...result.skippedPackages, ...result.skippedSystemDeps],
+        exaKeyWritten: result.exaKeyWritten,
+        exaKeyPath: result.exaKeyPath,
+    };
+}
+export function formatSetupExecutionSummary(summary) {
+    return [
+        'crtr sys setup complete',
+        summary.installed.length > 0 ? `installed: ${summary.installed.join(', ')}` : 'installed: none',
+        summary.skipped.length > 0 ? `skipped: ${summary.skipped.join(', ')}` : 'skipped: none',
+        summary.exaKeyWritten ? `exa key written: ${summary.exaKeyPath}` : 'exa key written: no',
+    ].join('\n') + '\n';
+}
+export async function executeSetupSubmission(submission) {
+    const installedPackages = [];
+    const skippedPackages = [];
+    const installedSystemDeps = [];
+    const skippedSystemDeps = [];
+    for (const entry of submission.packages) {
+        if (submission.installedPackageIds.has(entry.id)) {
+            skippedPackages.push(`${entry.name} (already installed)`);
+            continue;
+        }
+        installPiPackage(entry.installSource);
+        installedPackages.push(entry.name);
+    }
+    for (const plan of submission.systemDeps) {
+        if (!plan.checked || plan.installed) {
+            skippedSystemDeps.push(`${plan.tool} (already installed)`);
+            continue;
+        }
+        if (!plan.autoInstall || !plan.command) {
+            skippedSystemDeps.push(`${plan.tool} (${plan.hint})`);
+            continue;
+        }
+        runShellCommand(plan.command);
+        installedSystemDeps.push(plan.tool);
+    }
+    const exaKeyWritten = submission.exaKey.trim() !== '';
+    if (exaKeyWritten) {
+        await writeExaKey(submission.exaKeyPath, submission.exaKey);
+    }
+    return summarizeSetupExecution({
+        installedPackages,
+        skippedPackages,
+        installedSystemDeps,
+        skippedSystemDeps,
+        exaKeyWritten,
+        exaKeyPath: submission.exaKeyPath,
+    });
+}

package/dist/commands/sys/setup.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const sysSetupLeaf: LeafDef;