@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/view/bridge.js

@@ -1,31 +0,0 @@
-// bridge.ts — the server side of the local web transport (Node only).
-//
-// `crtr view serve` runs the portable core CLIENT-SIDE in the browser; its
-// sources resolve over an HTTP Transport that POSTs each SourceRequest here.
-// This helper decodes that POST body and runs it through any Transport (the
-// local exec/file/http one today) — the single endpoint a cloud deploy
-// replaces. Kept transport-agnostic + framework-free so it is trivially
-// testable and tear-out-able.
-function bad(stderr) {
-    const raw = { ok: false, stdout: '', stderr };
-    return { status: 400, body: JSON.stringify(raw) };
-}
-/** Decode a POST body as a SourceRequest and run it through `transport`,
- *  returning the HTTP status + JSON-encoded RawResponse the bridge should send
- *  back. Never throws — a malformed body or a transport failure both come back
- *  as a RawResponse with ok:false. */
-export async function runSourceRequest(transport, rawBody) {
-    let req;
-    try {
-        req = JSON.parse(rawBody);
-    }
-    catch {
-        return bad('bridge: request body is not valid JSON');
-    }
-    const kind = req.kind;
-    if (!req || typeof req !== 'object' || (kind !== 'exec' && kind !== 'file' && kind !== 'http')) {
-        return bad(`bridge: request body is not a SourceRequest (kind must be exec|file|http, got ${JSON.stringify(kind)})`);
-    }
-    const raw = await transport.send(req);
-    return { status: 200, body: JSON.stringify(raw) };
-}

package/dist/core/view/chrome.d.ts

@@ -1,9 +0,0 @@
-import type { ChromeState } from './contract.js';
-export type ChipState = 'working' | 'blocked' | 'attention' | 'ready' | 'idle';
-/** Derive the state chip from host signals: busy→working, error banner→blocked,
- *  action banner→attention, else ready (once loaded) / idle. An info banner does
- *  not block. An explicit interaction mode (setMode) overrides the chip — that
- *  precedence is applied by each target's chrome renderer, not here. */
-export declare function deriveState(c: ChromeState): ChipState;
-/** A fresh chrome record (the shape both hosts start from). */
-export declare function initialChrome(): ChromeState;

package/dist/core/view/chrome.js

@@ -1,22 +0,0 @@
-// chrome.ts — portable chrome-state derivation shared by both targets.
-//
-// The TUI's drawChrome and the web's <ViewChrome> both derive the one state
-// chip from the same host signals via deriveState, so the two targets never
-// drift on what "blocked" / "working" / "ready" mean.
-/** Derive the state chip from host signals: busy→working, error banner→blocked,
- *  action banner→attention, else ready (once loaded) / idle. An info banner does
- *  not block. An explicit interaction mode (setMode) overrides the chip — that
- *  precedence is applied by each target's chrome renderer, not here. */
-export function deriveState(c) {
-    if (c.busy)
-        return 'working';
-    if (c.banner?.level === 'error')
-        return 'blocked';
-    if (c.banner?.level === 'action')
-        return 'attention';
-    return c.loaded ? 'ready' : 'idle';
-}
-/** A fresh chrome record (the shape both hosts start from). */
-export function initialChrome() {
-    return { status: null, banner: null, subtitle: null, mode: null, busy: false, loaded: false, lastRefresh: 0 };
-}

package/dist/core/view/contract.d.ts

@@ -1,205 +0,0 @@
-import type { Draw, Rect } from '../tui/draw.js';
-export interface ViewManifest {
-    id: string;
-    title: string;
-    subtitle?: string;
-    description: string;
-    refreshMs?: number;
-}
-/** Severity of a {@link HostSignals.setBanner} banner — drives glyph + hue and
- *  the derived state chip (error→blocked, action→attention, info→neutral). */
-export type BannerLevel = 'info' | 'action' | 'error';
-export interface Banner {
-    msg: string;
-    level: BannerLevel;
-}
-/** Optional host context passed to the text presenter's dump on the piped path. */
-export interface DumpContext {
-    banner: Banner | null;
-}
-/** Semantic chrome signals the core raises; each target renders them in its own
- *  idiom (TUI footer/banner/title-chip vs web status line/alert bar/pill). */
-export interface HostSignals {
-    setStatus(msg: string | null): void;
-    setBanner(msg: string, level: BannerLevel): void;
-    clearBanner(): void;
-    setSubtitle(s: string | null): void;
-    /** Interaction-mode chip override (compose/react); null returns to derived. */
-    setMode(mode: string | null): void;
-    /** TUI: leave the pane; web: no-op/close tab. */
-    quit(): void;
-}
-/** The host-tracked chrome record both targets render. */
-export interface ChromeState {
-    status: string | null;
-    banner: Banner | null;
-    subtitle: string | null;
-    mode: string | null;
-    busy: boolean;
-    loaded: boolean;
-    lastRefresh: number;
-}
-/** A transport-agnostic request descriptor the host fulfills. The core never
- *  executes anything itself — it describes WHAT to run/read/fetch and the
- *  host's Transport decides HOW (local exec today, a cloud endpoint later). */
-export type SourceRequest = {
-    kind: 'exec';
-    bin: string;
-    args: string[];
-    cwd?: string;
-    stdin?: string;
-} | {
-    kind: 'file';
-    path: string;
-} | {
-    kind: 'http';
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    url: string;
-    headers?: Record<string, string>;
-    body?: string;
-};
-export type StreamRole = 'controller' | 'observer';
-export interface StreamRequest {
-    kind: 'stream';
-    target: string;
-    role?: StreamRole;
-}
-export interface StreamChannel {
-    readonly id: string;
-    send(frame: unknown): void;
-    close(): void;
-}
-export interface StreamSource<A = void> {
-    id: string;
-    request(args: A): StreamRequest;
-    onFrame: string;
-    onOpen?: string;
-    onClose?: string;
-}
-export interface RawResponse {
-    ok: boolean;
-    exitCode?: number;
-    status?: number;
-    stdout: string;
-    stderr: string;
-}
-/** Typed error with a render-ready display. Presenters render `display`
- *  VERBATIM and never branch on `kind` (the view-internal taxonomy). */
-export interface SourceError {
-    kind: string;
-    display: {
-        headline: string;
-        explanation: string;
-        nextStep: string;
-        level: BannerLevel;
-        blocking: boolean;
-    };
-}
-export type Result<T> = {
-    ok: true;
-    data: T;
-} | {
-    ok: false;
-    error: SourceError;
-};
-/** A READ: declarative descriptor + pure parse + optional cadence. Resolved by
- *  the host through its Transport via `ctx.resolve(source, args)`. */
-export interface Source<T, A = void> {
-    id: string;
-    request(args: A): SourceRequest;
-    parse(raw: RawResponse): Result<T>;
-    refreshMs?: number;
-}
-/** A WRITE: same {request, parse} pair, no cadence — invoked by an intent via
- *  `ctx.execute(command, args)`. */
-export interface Command<T, A = void> {
-    id: string;
-    request(args: A): SourceRequest;
-    parse(raw: RawResponse): Result<T>;
-}
-/** A semantic action. State updates are immutable via `ctx.set`; async effects
- *  (transport calls) live in the same handler — a thunk, not a pure reducer.
- *  Sync intents call `ctx.set` once; async intents `await ctx.resolve/execute`
- *  between `set`s. The host serializes async intents in its single-flight lane. */
-export type Intent<S, P = void> = (ctx: IntentCtx<S>, payload: P) => void | Promise<void>;
-export interface IntentCtx<S> {
-    /** Snapshot of state at read time. */
-    readonly state: S;
-    /** Immutable update → triggers a re-render. Value or (prev)=>next fn. */
-    set(next: S | ((prev: S) => S)): void;
-    /** Run a READ source through the host's transport → typed Result. */
-    resolve<T, A>(source: Source<T, A>, args?: A): Promise<Result<T>>;
-    /** Run a WRITE command through the host's transport → typed Result. */
-    execute<T, A>(command: Command<T, A>, args?: A): Promise<Result<T>>;
-    connect<A>(source: StreamSource<A>, args?: A): StreamChannel;
-    /** Semantic chrome signals (status/banner/subtitle/mode/quit). */
-    signal: HostSignals;
-    /** Chain another intent by name. */
-    dispatch(intent: string, payload?: unknown): Promise<void>;
-}
-export interface ViewCore<S = unknown> {
-    manifest: ViewManifest;
-    /** Cheap, synchronous initial state. No fetch, no screen. The host mounts,
-     *  paints a loading frame, then dispatches the first 'refresh'. */
-    init(opts: Readonly<Record<string, string>>): S;
-    /** Declarative READ dependencies the host resolves through the transport. */
-    sources?: Record<string, Source<any, any>>;
-    streams?: Record<string, StreamSource<any>>;
-    /** WRITE descriptors invoked from intents. */
-    commands?: Record<string, Command<any, any>>;
-    /** Semantic actions. Both presenters emit these. */
-    intents: Record<string, Intent<S, any>>;
-}
-export interface KeyHint {
-    keys: string;
-    label: string;
-}
-/** A catalog binding supplies only its semantic hint label: the host derives
- * the rendered key label from the effective user binding snapshot. */
-export interface CatalogKeyHint {
-    label: string;
-}
-export type KeyBinding<S> = {
-    /** Closed crouter catalog action. Shipped presenters use this form. */
-    bindingId: import('../keybindings/index.js').BindingId;
-    intent: string;
-    payload?: (state: S) => unknown;
-    when?: (state: S) => boolean;
-    hint?: CatalogKeyHint;
-} | {
-    /** Literal keys remain owned by custom/plugin views, outside crouter's catalog. */
-    keys: string[];
-    intent: string;
-    payload?: (state: S) => unknown;
-    when?: (state: S) => boolean;
-    hint?: KeyHint;
-} | {
-    /** Text-capture binding: while `when(state)` is true the host runs a
-     *  built-in line-edit buffer over raw printable keys and dispatches
-     *  `capture` with the next draft value on each edit. Deletion is the
-     *  host catalog action `crtr.view.host.editor.backspace`. */
-    capture: string;
-    when: (state: S) => boolean;
-    hint?: KeyHint | CatalogKeyHint;
-};
-export interface TuiPresenter<S = unknown> {
-    /** Pure read of state, paints via draw.*; never ANSI. */
-    render(state: S, draw: Draw, content: Rect): void;
-    /** Pure input→intent mapping. */
-    keymap: KeyBinding<S>[];
-}
-/** Props handed to web.jsx's default-export React component. The component is a
- *  pure function of state; DOM events call `dispatch`. (Typed loosely here so
- *  the core contract carries no React type dependency.) */
-export interface ViewProps<S = unknown> {
-    state: S;
-    dispatch: (intent: string, payload?: unknown) => void;
-    chrome: ChromeState;
-}
-export type WebPresenter<S = unknown> = (props: ViewProps<S>) => unknown;
-export interface TextPresenter<S = unknown> {
-    /** Static text for the non-TTY / piped path. Snapshot of current state. */
-    dump(state: S, ctx?: DumpContext): string;
-}
-export declare function ok<T>(data: T): Result<T>;
-export declare function fail<T = never>(error: SourceError): Result<T>;

package/dist/core/view/contract.js

@@ -1,23 +0,0 @@
-// contract.ts — the dual-target view contract (portable core + thin presenters).
-//
-// One view definition renders to two targets — the tmux TUI (`crtr view run`)
-// and a React+Tailwind web page (`crtr view serve`) — from ONE portable core.
-// On disk a view is a directory of up to four files, each loaded only by the
-// runtime that can execute it:
-//
-//   <view>/
-//     core.mjs   REQUIRED  manifest · init · sources · commands · intents.
-//                          Runs in BOTH Node and the browser. Imports NOTHING —
-//                          no `node:*`, no crtr. Pure JS + the injected ctx.
-//     tui.mjs    optional  render(state, draw, content) + keymap   (Node only)
-//     web.jsx    optional  default React component (Tailwind)      (browser only)
-//     text.mjs   optional  dump(state, ctx) for the piped path     (Node only)
-//
-// The invariant: ALL state + ALL behavior live in the core; presenters are pure
-// reads of state that emit named intents. It is enforced structurally — only
-// `core.mjs` ever sees a mutating `IntentCtx`; presenters receive `state` plus a
-// `dispatch`/`keymap` that names intents, so a presenter has no path to data or
-// logic.
-// ── Result helpers (re-exported for view authors' convenience in tests) ─────
-export function ok(data) { return { ok: true, data }; }
-export function fail(error) { return { ok: false, error }; }

package/dist/core/view/loader.d.ts

@@ -1,31 +0,0 @@
-import type { ViewCore, TuiPresenter, TextPresenter } from './contract.js';
-export interface ResolvedView {
-    id: string;
-    dir: string;
-    scope: 'project' | 'user' | 'builtin';
-    core: string;
-    tui: string | null;
-    web: string | null;
-    text: string | null;
-}
-/** Scope search project→user→builtin; first hit wins. null if no scope holds a
- *  `<name>/core.mjs`. */
-export declare function resolveView(name: string): ResolvedView | null;
-/** Find a directory named `name` across scopes even when it holds no core.mjs —
- *  lets a caller distinguish "no such view" from "a dir that isn't a valid view"
- *  (e.g. a pre-contract `view.mjs`-only dir) and name the contract in the error. */
-export declare function findViewDir(name: string): string | null;
-/** Enumerate every resolvable core-shaped view across scopes (first scope wins
- *  per id). Targets per view are derivable from the tui/web/text fields. */
-export declare function listViews(): ResolvedView[];
-/** Import + validate the portable core. Throws a guided error if malformed. */
-export declare function loadCore(r: ResolvedView): Promise<ViewCore>;
-/** Import + validate the TUI presenter. Call requireTui first. */
-export declare function loadTui(r: ResolvedView): Promise<TuiPresenter>;
-/** Import the text presenter if present; null otherwise (the host synthesizes a
- *  generic one-line dump when a view ships no text.mjs). */
-export declare function loadText(r: ResolvedView): Promise<TextPresenter | null>;
-/** Per-host presenter validation: `view run` requires a TUI presenter. */
-export declare function requireTui(r: ResolvedView): void;
-/** Per-host presenter validation: `view serve` requires a web presenter. */
-export declare function requireWeb(r: ResolvedView): void;

package/dist/core/view/loader.js

@@ -1,188 +0,0 @@
-// loader.ts — resolve + load dual-target (core.mjs) views across scopes.
-//
-// A view = a directory containing `core.mjs` (the portable core). Up to three
-// presenter files sit beside it: `tui.mjs` (Node), `web.jsx`/`web.tsx` (browser,
-// via Vite — NEVER Node-imported), `text.mjs` (Node, piped path). Targets are
-// derived from which presenter files exist — no manifest field.
-//
-// Resolution order: project → user → builtin, first hit wins (scope.ts
-// viewsDir). Node-side loads are plain `import(pathToFileURL())` — no
-// transpile, no bundle. A directory without a `core.mjs` is not a view.
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { viewsDir } from '../scope.js';
-import { InputError } from '../io.js';
-const SCOPE_ORDER = ['project', 'user', 'builtin'];
-function probe(dir, scope, id) {
-    const core = join(dir, 'core.mjs');
-    if (!existsSync(core))
-        return null;
-    const tui = join(dir, 'tui.mjs');
-    const webJsx = join(dir, 'web.jsx');
-    const webTsx = join(dir, 'web.tsx');
-    const text = join(dir, 'text.mjs');
-    return {
-        id, dir, scope, core,
-        tui: existsSync(tui) ? tui : null,
-        web: existsSync(webJsx) ? webJsx : existsSync(webTsx) ? webTsx : null,
-        text: existsSync(text) ? text : null,
-    };
-}
-/** Scope search project→user→builtin; first hit wins. null if no scope holds a
- *  `<name>/core.mjs`. */
-export function resolveView(name) {
-    for (const scope of SCOPE_ORDER) {
-        const root = viewsDir(scope);
-        if (!root)
-            continue;
-        const r = probe(join(root, name), scope, name);
-        if (r)
-            return r;
-    }
-    return null;
-}
-/** Find a directory named `name` across scopes even when it holds no core.mjs —
- *  lets a caller distinguish "no such view" from "a dir that isn't a valid view"
- *  (e.g. a pre-contract `view.mjs`-only dir) and name the contract in the error. */
-export function findViewDir(name) {
-    for (const scope of SCOPE_ORDER) {
-        const root = viewsDir(scope);
-        if (!root)
-            continue;
-        const dir = join(root, name);
-        try {
-            if (statSync(dir).isDirectory())
-                return dir;
-        }
-        catch { /* not here */ }
-    }
-    return null;
-}
-/** Enumerate every resolvable core-shaped view across scopes (first scope wins
- *  per id). Targets per view are derivable from the tui/web/text fields. */
-export function listViews() {
-    const seen = new Set();
-    const out = [];
-    for (const scope of SCOPE_ORDER) {
-        const root = viewsDir(scope);
-        if (!root || !existsSync(root))
-            continue;
-        let names;
-        try {
-            names = readdirSync(root);
-        }
-        catch {
-            continue;
-        }
-        for (const name of names.sort()) {
-            if (seen.has(name))
-                continue; // first scope wins
-            const dir = join(root, name);
-            let isDir = false;
-            try {
-                isDir = statSync(dir).isDirectory();
-            }
-            catch {
-                isDir = false;
-            }
-            if (!isDir)
-                continue;
-            const r = probe(dir, scope, name);
-            if (!r)
-                continue;
-            seen.add(name);
-            out.push(r);
-        }
-    }
-    return out;
-}
-/** Import + validate the portable core. Throws a guided error if malformed. */
-export async function loadCore(r) {
-    let mod;
-    try {
-        mod = (await import(pathToFileURL(r.core).href));
-    }
-    catch (e) {
-        throw guided(r, 'core.mjs', `failed to import: ${errText(e)}`);
-    }
-    const c = mod['default'];
-    if (!c || typeof c !== 'object')
-        throw guided(r, 'core.mjs', 'no default export that is a ViewCore object');
-    const m = c.manifest;
-    if (!m || typeof m.id !== 'string' || typeof m.title !== 'string') {
-        throw guided(r, 'core.mjs', 'manifest.id and manifest.title must be strings');
-    }
-    if (typeof c.init !== 'function')
-        throw guided(r, 'core.mjs', 'init() is required');
-    if (!c.intents || typeof c.intents !== 'object')
-        throw guided(r, 'core.mjs', 'intents must be an object of intent functions');
-    return c;
-}
-/** Import + validate the TUI presenter. Call requireTui first. */
-export async function loadTui(r) {
-    if (!r.tui)
-        throw notTarget(r, 'tui');
-    let mod;
-    try {
-        mod = (await import(pathToFileURL(r.tui).href));
-    }
-    catch (e) {
-        throw guided(r, 'tui.mjs', `failed to import: ${errText(e)}`);
-    }
-    // Accept named exports { render, keymap } or a default-exported object.
-    const candidate = (typeof mod['render'] === 'function' ? mod : mod['default']);
-    if (!candidate || typeof candidate.render !== 'function')
-        throw guided(r, 'tui.mjs', 'render(state, draw, content) is required');
-    if (!Array.isArray(candidate.keymap))
-        throw guided(r, 'tui.mjs', 'keymap must be an array of key bindings');
-    return candidate;
-}
-/** Import the text presenter if present; null otherwise (the host synthesizes a
- *  generic one-line dump when a view ships no text.mjs). */
-export async function loadText(r) {
-    if (!r.text)
-        return null;
-    let mod;
-    try {
-        mod = (await import(pathToFileURL(r.text).href));
-    }
-    catch (e) {
-        throw guided(r, 'text.mjs', `failed to import: ${errText(e)}`);
-    }
-    const candidate = (typeof mod['dump'] === 'function' ? mod : mod['default']);
-    if (!candidate || typeof candidate.dump !== 'function')
-        throw guided(r, 'text.mjs', 'dump(state, ctx) is required');
-    return candidate;
-}
-/** Per-host presenter validation: `view run` requires a TUI presenter. */
-export function requireTui(r) {
-    if (!r.tui) {
-        throw new InputError({
-            error: 'view_web_only',
-            message: `'${r.id}' is web-only — it ships no tui.mjs presenter`,
-            next: 'Open it in the browser through the surface web server.',
-        });
-    }
-}
-/** Per-host presenter validation: `view serve` requires a web presenter. */
-export function requireWeb(r) {
-    if (!r.web) {
-        throw new InputError({
-            error: 'view_tui_only',
-            message: `'${r.id}' is tui-only — it ships no web.jsx presenter`,
-            next: 'Open it in a tmux pane with the surface view run leaf.',
-        });
-    }
-}
-function notTarget(r, target) {
-    return new Error(`view "${r.id}" has no ${target} presenter`);
-}
-function guided(r, file, problem) {
-    return new Error(`invalid view "${r.id}" (${r.scope}) at ${join(r.dir, file)}: ${problem}.\n` +
-        'A dual-target view dir holds core.mjs (default export: { manifest: { id, title }, init(), intents }) ' +
-        'plus optional tui.mjs (render + keymap), web.jsx, text.mjs (dump).');
-}
-function errText(e) {
-    return e instanceof Error ? e.message : String(e);
-}

package/dist/core/view/stream-local.d.ts

@@ -1,3 +0,0 @@
-import type { StreamChannel, StreamRequest } from './contract.js';
-import type { StreamHandlers } from './transport.js';
-export declare function openLocalStream(req: StreamRequest, handlers: StreamHandlers): StreamChannel;