@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/sys/prompt-review.js

@@ -0,0 +1,178 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { InputError, readStdinRaw } from '../../core/io.js';
+import { workspaceRoot } from '../../core/artifact.js';
+import { availableKinds, kindWhenToUse, subPersonasFor } from '../../core/personas/index.js';
+import { resolvePromptReview } from '../../core/personas/resolve.js';
+function resolveLifecycle(mode, lifecycle) {
+    if (lifecycle !== undefined)
+        return lifecycle;
+    return mode === 'orchestrator' ? 'resident' : 'terminal';
+}
+function readJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'invalid_json',
+            message: `stdin is not valid JSON: ${String(err)}`,
+            field: 'stdin',
+            next: 'Pass the comments deck JSON on stdin.',
+        });
+    }
+}
+function parseBool(value, field, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (value === true || value === false)
+        return value;
+    if (typeof value !== 'string') {
+        throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+function normaliseKindList() {
+    return availableKinds().map((kind) => ({ kind, whenToUse: kindWhenToUse(kind) }));
+}
+function normaliseSubPersonaList(kind) {
+    return subPersonasFor(kind).map((sub) => ({ kind: sub.kind, whenToUse: sub.whenToUse }));
+}
+function reviewList() {
+    const kinds = normaliseKindList();
+    const subPersonas = {};
+    for (const { kind } of kinds)
+        subPersonas[kind] = normaliseSubPersonaList(kind);
+    return {
+        kinds,
+        modes: ['base', 'orchestrator'],
+        lifecycles: ['terminal', 'resident'],
+        subPersonas,
+    };
+}
+function promptReviewPath() {
+    const dir = workspaceRoot();
+    const reviewsDir = join(dir, 'prompt-reviews');
+    mkdirSync(reviewsDir, { recursive: true });
+    return join(reviewsDir, `${new Date().toISOString()}.md`);
+}
+function renderExportDeck(deck) {
+    const lines = [];
+    lines.push(`# Prompt review — ${deck.config.kind}/${deck.config.mode}`);
+    lines.push('');
+    lines.push('## Config');
+    lines.push(`- timestamp: ${new Date().toISOString()}`);
+    lines.push(`- kind: ${deck.config.kind}`);
+    lines.push(`- mode: ${deck.config.mode}`);
+    lines.push(`- lifecycle: ${deck.config.lifecycle}`);
+    lines.push(`- hasManager: ${String(deck.config.hasManager)}`);
+    lines.push(`- node: ${deck.config.node ?? '(none)'}`);
+    lines.push('');
+    lines.push('## Comments');
+    if (deck.comments.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const comment of deck.comments) {
+            lines.push(`### ${comment.label} (${comment.layerId})`);
+            lines.push(`- source: \`${comment.sourcePath ?? '(generated)'}\` (${comment.scope})`);
+            if (comment.anchor !== null) {
+                lines.push('> ' + comment.anchor.split('\n').join('\n> '));
+            }
+            lines.push(comment.body);
+            lines.push('');
+        }
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+    }
+    lines.push('');
+    lines.push('## Prompt sources (edit these)');
+    const seen = new Set();
+    for (const source of deck.sources) {
+        const key = `${source.scope}:${source.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        lines.push(`- ${source.label} — \`${source.path}\` (${source.scope})`);
+    }
+    lines.push('');
+    lines.push('These are review comments on an assembled system prompt; edit the listed source files to address them.');
+    return lines.join('\n') + '\n';
+}
+function exportReview(deck) {
+    const path = promptReviewPath();
+    writeFileSync(path, renderExportDeck(deck), 'utf8');
+    return { path };
+}
+function resolveDeck(input) {
+    const kind = input['kind'];
+    const mode = input['mode'] ?? 'base';
+    const lifecycle = resolveLifecycle(mode, input['lifecycle']);
+    const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+    const node = optionalString(input['node']);
+    if (kind === undefined || kind.trim() === '') {
+        throw new InputError({ error: 'missing_parameter', message: 'kind is required', field: 'kind', next: 'Pass --kind <kind> or use --list.' });
+    }
+    return resolvePromptReview(kind, mode, {
+        lifecycle,
+        hasManager,
+    }, node ?? undefined);
+}
+export const promptReviewLeaf = defineLeaf({
+    name: 'prompt-review',
+    description: 'inspect an assembled prompt and export review notes',
+    whenToUse: 'you want to inspect a composed persona prompt for a kind/mode combo, compare the space around it, or export review notes back to source files',
+    help: {
+        name: 'sys prompt-review',
+        summary: 'inspect an assembled prompt and export review notes',
+        params: [
+            { kind: 'positional', name: 'action', type: 'string', required: false, constraint: 'Optional subcommand: export. Omit for the assembled prompt contract.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind to inspect. Required unless --list or export.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. Default: base.' },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Lifecycle axis. Default: base -> terminal, orchestrator -> resident.' },
+            { kind: 'flag', name: 'has-manager', type: 'string', required: false, default: 'true', constraint: 'Whether the node reports to a manager. Use true or false. Default: true.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Optional node id. When the node exists, runtime substrate layers are appended.' },
+            { kind: 'flag', name: 'list', type: 'bool', required: false, constraint: 'List the available kinds, modes, lifecycles, and sub-personas.' },
+        ],
+        output: [
+            { name: 'config', type: 'object', required: false, constraint: 'Resolved config: {kind, mode, lifecycle, hasManager, node}.' },
+            { name: 'layers', type: 'object[]', required: false, constraint: 'Ordered prompt layers, including excluded alternatives and provenance.' },
+            { name: 'assembled', type: 'string', required: false, constraint: 'The assembled prompt string.' },
+            { name: 'total', type: 'object', required: false, constraint: 'Approximate token/char totals for included layers.' },
+            { name: 'sources', type: 'object[]', required: false, constraint: 'De-duplicated source files referenced by the prompt.' },
+            { name: 'kinds', type: 'object[]', required: false, constraint: 'Available kinds for --list.' },
+            { name: 'modes', type: 'string[]', required: false, constraint: 'Mode choices for --list.' },
+            { name: 'lifecycles', type: 'string[]', required: false, constraint: 'Lifecycle choices for --list.' },
+            { name: 'subPersonas', type: 'object', required: false, constraint: 'Available sub-personas keyed by kind for --list.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Written markdown path for export.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only inspection, or writes a review markdown file under the per-cwd crouter root.'],
+    },
+    run: async (input) => {
+        const action = input['action'];
+        const isList = input['list'] === true;
+        const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+        if (action !== undefined && action !== 'export') {
+            throw new InputError({ error: 'unknown_action', message: `unknown action: ${action}`, field: 'action', next: 'Use `export` or omit the positional action.' });
+        }
+        if (action === 'export') {
+            const raw = await readStdinRaw();
+            const deck = readJson(raw);
+            return exportReview(deck);
+        }
+        if (isList)
+            return reviewList();
+        const deck = resolveDeck({ ...input, hasManager });
+        return deck;
+    },
+});

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

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

package/dist/commands/sys/promptstudio.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { defineLeaf } from '../../core/command.js';
+import { startWebServer } from '../../clients/web/server.js';
+const DEFAULT_PORT = 7878;
+const PROMPT_STUDIO_PATH = '/views/prompt-review';
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            /* the printed URL is enough when no browser opener is available */
+        });
+        child.unref();
+    }
+    catch {
+        /* the printed URL is enough when no browser opener is available */
+    }
+}
+export const sysPromptStudioLeaf = defineLeaf({
+    name: 'promptstudio',
+    description: 'open Prompt Studio in the browser',
+    whenToUse: 'you want the Prompt Studio browser UI — a prompt review surface for toggling crouter persona/mode/lifecycle configs, inspecting the assembled system prompt, comparing configurations, and exporting review comments with source-file pointers.',
+    help: {
+        name: 'sys promptstudio',
+        summary: 'start the crouter web server and open Prompt Studio directly',
+        params: [
+            { kind: 'flag', name: 'port', type: 'int', required: false, default: DEFAULT_PORT, constraint: `TCP port to bind on 127.0.0.1. Default ${DEFAULT_PORT}.` },
+            { kind: 'flag', name: 'dev', type: 'bool', required: false, default: false, constraint: 'Serve the web shell through Vite middleware/HMR while iterating on Prompt Studio or the web client.' },
+        ],
+        output: [
+            { name: 'url', type: 'string', required: true, constraint: 'Prompt Studio URL opened in the browser.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            '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.',
+        ],
+    },
+    run: async (input) => {
+        const port = input['port'] ?? DEFAULT_PORT;
+        const dev = input['dev'] ?? false;
+        const server = await startWebServer({ port, dev });
+        const url = `${server.url}${PROMPT_STUDIO_PATH}`;
+        process.stdout.write(`Prompt Studio serving at ${url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
+            `  bridge:       POST ${server.url}/__crtr/source\n` +
+            `  events (SSE): GET  ${server.url}/__crtr/events\n` +
+            `  shell assets: ${dev ? 'Vite middleware (HMR)' : server.clientDir}\n` +
+            `  (ctrl+c to stop)\n`);
+        openBrowser(url);
+        await new Promise((resolveShutdown) => {
+            const shutdown = () => {
+                void server.close().then(() => resolveShutdown());
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+            process.once('SIGHUP', shutdown);
+        });
+        return { url };
+    },
+    render: () => '',
+});

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

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

package/dist/commands/sys/settings.js

@@ -0,0 +1,16 @@
+import { defineLeaf } from '../../core/command.js';
+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 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, 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>;