omkit 0.4.0 → 0.4.2

package/dist/actions/chrome-page.js

@@ -65,6 +65,14 @@ export const chromePage = action("chromePage")
         await page.goto(url);
         console.log(`navigated ${url}`);
     }
+    // Oms run under tsx, which forces esbuild `keepNames`: every function serialized into
+    // page.evaluate() carries a bare `__name(...)` wrapper that is undefined in the page and
+    // throws `ReferenceError: __name is not defined`. Define a no-op __name so those bodies
+    // run — seed the current document, and register it for any later navigation. Passed as a
+    // string so tsx doesn't rewrite (and re-break) the shim itself.
+    const nameShim = "globalThis.__name = globalThis.__name || function (f) { return f; };";
+    await page.evaluate(nameShim);
+    await page.addInitScript(nameShim);
     attach(page); // resolves instance.ref for every downstream action
     console.log(`attached ${from}`);
     // Daemon: hold the page open until teardown, then drop the CDP session if ours.

package/dist/cli/client/discovery.d.ts

@@ -1,7 +1,8 @@
 import type { Registry } from "./registry.ts";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
- * actions. Never throws for user-code problems — type errors become `warnings`, and whatever
- * parsed is still returned (so an editor-in-progress project stays useful).
+ * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
+ * project stays useful), but a **fatal config problem** — a missing, unparseable, or invalid
+ * tsconfig — throws, so the CLI crashes visibly instead of silently returning an empty project.
  */
 export declare function discover(tsconfigPath: string): Registry;

package/dist/cli/client/discovery.js

@@ -2,22 +2,16 @@ import ts from "typescript";
 import path from "node:path";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
- * actions. Never throws for user-code problems — type errors become `warnings`, and whatever
- * parsed is still returned (so an editor-in-progress project stays useful).
+ * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
+ * project stays useful), but a **fatal config problem** — a missing, unparseable, or invalid
+ * tsconfig — throws, so the CLI crashes visibly instead of silently returning an empty project.
  */
 export function discover(tsconfigPath) {
     const oms = [];
     const actions = [];
     const warnings = [];
-    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
-    if (configFile.error) {
-        warnings.push(ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n"));
-        return { oms, actions, warnings };
-    }
-    // Resolve to an absolute base so `parsed.fileNames` are absolute. Otherwise root files stay
-    // relative while imported files (e.g. an action pulled in by an om) resolve to absolute paths,
-    // and the two never match in `fileSet`.
-    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.resolve(path.dirname(tsconfigPath)));
+    const { parsed, warnings: configWarnings } = loadProject(tsconfigPath);
+    warnings.push(...configWarnings);
     const program = ts.createProgram({
         rootNames: parsed.fileNames,
         options: { ...parsed.options, noEmit: true },
@@ -62,6 +56,28 @@ export function discover(tsconfigPath) {
     }
     return { oms, actions, warnings };
 }
+/**
+ * Load and validate the tsconfig, throwing on a fatal config problem — a missing/unparseable file,
+ * or a config-level error (bad compilerOptions, an unresolvable `extends`). The benign "no inputs
+ * found" (TS18003) is not fatal: an empty-but-valid project comes back as a warning instead.
+ *
+ * Parses against an absolute base dir so `parsed.fileNames` are absolute — otherwise root files
+ * stay relative while imported files (an action pulled in by an om) resolve absolute, and the two
+ * never match in the caller's `fileSet`.
+ */
+function loadProject(tsconfigPath) {
+    const flatten = (d) => ts.flattenDiagnosticMessageText(d.messageText, "\n");
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error)
+        throw new Error(`could not read ${tsconfigPath}: ${flatten(configFile.error)}`);
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.resolve(path.dirname(tsconfigPath)));
+    const fatal = parsed.errors.filter((e) => e.category === ts.DiagnosticCategory.Error && e.code !== 18003);
+    if (fatal.length) {
+        throw new Error(`invalid ${tsconfigPath}:\n${fatal.map((e) => `  ${flatten(e)}`).join("\n")}`);
+    }
+    const warnings = parsed.errors.filter((e) => e.code === 18003).map(flatten);
+    return { parsed, warnings };
+}
 /** Collect the local names bound to om/step/action from `import … from "omkit"`. */
 function omkitImports(sf) {
     const names = {};

package/dist/cli/commands/check.d.ts

@@ -1,6 +1,11 @@
 import type { Diagnostic } from "../client/types.ts";
-/** Format typecheck diagnostics into terminal text plus a process exit code. */
-export declare function formatDiagnostics(diagnostics: Diagnostic[]): {
-    text: string;
+import type { ReportItem } from "../ui/Report.tsx";
+/**
+ * Turn typecheck diagnostics into a report: a headline, one item per diagnostic (location + message),
+ * and the process exit code — **1 when there are any errors**, 0 when the project is clean.
+ */
+export declare function checkReport(diagnostics: Diagnostic[]): {
+    title: string;
+    items: ReportItem[];
     code: number;
 };

package/dist/cli/commands/check.js

@@ -1,11 +1,14 @@
 import path from "node:path";
-/** Format typecheck diagnostics into terminal text plus a process exit code. */
-export function formatDiagnostics(diagnostics) {
-    if (diagnostics.length === 0) {
-        return { text: "no type errors", code: 0 };
-    }
-    const lines = diagnostics.map((d) => `${path.basename(d.file)}:${d.line}  ${d.message}`);
-    lines.push("");
-    lines.push(`${diagnostics.length} error${diagnostics.length === 1 ? "" : "s"}`);
-    return { text: lines.join("\n"), code: 1 };
+/**
+ * Turn typecheck diagnostics into a report: a headline, one item per diagnostic (location + message),
+ * and the process exit code — **1 when there are any errors**, 0 when the project is clean.
+ */
+export function checkReport(diagnostics) {
+    const n = diagnostics.length;
+    const items = diagnostics.map((d) => ({
+        head: `${path.basename(d.file)}:${d.line}`,
+        detail: d.message,
+    }));
+    const title = n === 0 ? "no type errors" : `${n} type error${n === 1 ? "" : "s"}`;
+    return { title, items, code: n === 0 ? 0 : 1 };
 }

package/dist/cli/commands/run.d.ts

@@ -1,3 +1,11 @@
+import type { Registry } from "../client/registry.ts";
+/**
+ * Report an actionable "nothing to run" panel when discovery finds no oms. Names the config file
+ * omkit actually read (absolute, so the tsconfig.omkit.json-vs-tsconfig.json confusion goes away),
+ * lists any config warnings (e.g. TypeScript's "no inputs found" with the offending globs), and
+ * points at the usual cause: an `include` that doesn't reach the om files.
+ */
+export declare function reportNoOms(tsconfig: string, registry: Registry): Promise<void>;
 /**
  * Resolve a `run` argument to an absolute om file: an existing file path (relative to `cwd`)
  * wins; otherwise match a discovered om by name. Returns undefined when nothing matches.

package/dist/cli/commands/run.js

@@ -1,5 +1,22 @@
 import fs from "node:fs";
 import path from "node:path";
+import { renderDiagnostics } from "../ui/Report.js";
+/**
+ * Report an actionable "nothing to run" panel when discovery finds no oms. Names the config file
+ * omkit actually read (absolute, so the tsconfig.omkit.json-vs-tsconfig.json confusion goes away),
+ * lists any config warnings (e.g. TypeScript's "no inputs found" with the offending globs), and
+ * points at the usual cause: an `include` that doesn't reach the om files.
+ */
+export function reportNoOms(tsconfig, registry) {
+    return renderDiagnostics({
+        kind: "warning",
+        title: "no oms found",
+        subtitle: `config: ${path.resolve(tsconfig)}`,
+        items: registry.warnings.map((w) => ({ head: "", detail: w })),
+        hint: "Check the config's `include` — it must reach your om files, and a glob only recurses " +
+            'with `**` (e.g. "src/**/*.ts", not "src/*.ts").',
+    });
+}
 /**
  * Resolve a `run` argument to an absolute om file: an existing file path (relative to `cwd`)
  * wins; otherwise match a discovered om by name. Returns undefined when nothing matches.

package/dist/cli/commands/ui.d.ts

@@ -3,5 +3,10 @@ import type { OmkitClient } from "../client/index.ts";
  * Render the interactive Ink app. Ink's own Ctrl+C handling is disabled so the app can tear the
  * run down gracefully first; the final verdict + run-folder path are printed here, after Ink
  * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ *
+ * Discovery runs first, before Ink takes the terminal: a fatal config problem throws here and the
+ * bin's error boundary turns it into a clean crash rather than an empty list. With no oms to show,
+ * it reports why (config + warnings) instead of dropping into a blank picker. Non-fatal warnings
+ * are printed so they aren't lost behind the UI.
  */
-export declare function launchUi(client: OmkitClient): void;
+export declare function launchUi(client: OmkitClient, tsconfig: string): Promise<void>;

package/dist/cli/commands/ui.js

@@ -1,14 +1,33 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
 import { App } from "../ui/app.js";
+import { renderDiagnostics, withSpinner } from "../ui/Report.js";
+import { reportNoOms } from "./run.js";
 /**
  * Render the interactive Ink app. Ink's own Ctrl+C handling is disabled so the app can tear the
  * run down gracefully first; the final verdict + run-folder path are printed here, after Ink
  * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ *
+ * Discovery runs first, before Ink takes the terminal: a fatal config problem throws here and the
+ * bin's error boundary turns it into a clean crash rather than an empty list. With no oms to show,
+ * it reports why (config + warnings) instead of dropping into a blank picker. Non-fatal warnings
+ * are printed so they aren't lost behind the UI.
  */
-export function launchUi(client) {
+export async function launchUi(client, tsconfig) {
+    const registry = await withSpinner("discovering…", () => client.discover());
+    if (registry.oms.length === 0) {
+        await reportNoOms(tsconfig, registry);
+        return;
+    }
+    if (registry.warnings.length > 0) {
+        await renderDiagnostics({
+            kind: "warning",
+            title: `${registry.warnings.length} warning${registry.warnings.length === 1 ? "" : "s"}`,
+            items: registry.warnings.map((w) => ({ head: "", detail: w })),
+        });
+    }
     let finalVerdict;
-    const app = render(_jsx(App, { client: client, onExit: (v) => (finalVerdict = v) }), {
+    const app = render(_jsx(App, { client: client, oms: registry.oms, onExit: (v) => (finalVerdict = v) }), {
         exitOnCtrlC: false,
     });
     void app.waitUntilExit().then(() => {

package/dist/cli/index.js

@@ -36,13 +36,18 @@ async function main() {
     }
     if (cli.command === "ls") {
         const { formatRegistry } = await import("./commands/ls.js");
-        console.log(formatRegistry(await client.discover(), { json: cli.json }));
+        const { withSpinner } = await import("./ui/Report.js");
+        const registry = await withSpinner("discovering…", () => client.discover());
+        console.log(formatRegistry(registry, { json: cli.json }));
         return;
     }
     if (cli.command === "check") {
-        const { formatDiagnostics } = await import("./commands/check.js");
-        const { text, code } = formatDiagnostics(await client.check());
-        console.log(text);
+        const { checkReport } = await import("./commands/check.js");
+        const { renderDiagnostics, withSpinner } = await import("./ui/Report.js");
+        const diagnostics = await withSpinner("type-checking…", () => client.check());
+        const { title, items, code } = checkReport(diagnostics);
+        // Type errors fail the command (exit 1); a clean project reports ok and exits 0.
+        await renderDiagnostics({ kind: code === 0 ? "ok" : "error", title, items }, code === 0 ? process.stdout : process.stderr);
         process.exitCode = code;
         return;
     }
@@ -51,12 +56,18 @@ async function main() {
         // A bare `omkit` lands here too, since `run` is the default command.
         if (!cli.target) {
             const { launchUi } = await import("./commands/ui.js");
-            launchUi(client);
+            await launchUi(client, cli.tsconfig);
             return;
         }
-        const { resolveOm } = await import("./commands/run.js");
+        const { resolveOm, reportNoOms } = await import("./commands/run.js");
         const { spawnBare } = await import("./client/runner.js");
-        const registry = await client.discover();
+        const { withSpinner } = await import("./ui/Report.js");
+        const registry = await withSpinner("discovering…", () => client.discover());
+        if (registry.oms.length === 0) {
+            await reportNoOms(cli.tsconfig, registry);
+            process.exitCode = 1;
+            return;
+        }
         const omFile = resolveOm(cli.target, registry, process.cwd());
         if (!omFile) {
             const known = registry.oms.map((o) => o.name).join(", ");
@@ -87,5 +98,33 @@ function isEntryPoint() {
         return false;
     }
 }
-if (isEntryPoint())
-    void main();
+/** Print a fatal error to stderr in one consistent shape, just before the process exits non-zero. */
+function reportFatal(err) {
+    const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    process.stderr.write(`\nomkit: ${detail}\n`);
+}
+if (isEntryPoint()) {
+    // Nothing should fail silently. A fatal anywhere — a bad config, an uncaught throw, or a rejected
+    // promise in the interactive app — prints and crashes the CLI with a non-zero exit code.
+    //
+    // The controlled path (a rejection from `main`, e.g. a bad tsconfig) gets the pretty Ink panel;
+    // the last-resort sync handlers stay plain, since the process may be mid-crash and can't await.
+    process.on("uncaughtException", (err) => {
+        reportFatal(err);
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (err) => {
+        reportFatal(err);
+        process.exit(1);
+    });
+    main().catch(async (err) => {
+        const { renderDiagnostics } = await import("./ui/Report.js");
+        const message = err instanceof Error ? err.message : String(err);
+        // Keep the panel clean by default (a bad tsconfig needs no stack); set OMKIT_DEBUG for the trace.
+        const stack = process.env.OMKIT_DEBUG && err instanceof Error && err.stack
+            ? err.stack.split("\n").slice(1).join("\n")
+            : undefined;
+        await renderDiagnostics({ kind: "error", title: message, hint: stack });
+        process.exit(1);
+    });
+}

package/dist/cli/ui/Report.d.ts

@@ -0,0 +1,40 @@
+import { type ReactElement } from "react";
+export type ReportKind = "error" | "warning" | "ok" | "info";
+/** One row of a report: a colored `head` (e.g. a file:line location) and a dim `detail`. */
+export interface ReportItem {
+    head: string;
+    detail?: string;
+}
+export interface ReportProps {
+    kind: ReportKind;
+    /** The bold, colored headline (e.g. "3 type errors"). */
+    title: string;
+    /** A dim line under the title — e.g. the config file a diagnostic came from. */
+    subtitle?: string;
+    /** The list of findings, shown under a separator. */
+    items?: ReportItem[];
+    /** A dim footer with next-step guidance. */
+    hint?: string;
+}
+/**
+ * A colorful, bordered diagnostics panel: an icon + title header, an optional subtitle, a separator,
+ * a list of items (colored location + dim detail), and an optional dim hint footer. Kind picks the
+ * accent color (error red / warning yellow / ok green / info cyan).
+ */
+export declare function Report({ kind, title, subtitle, items, hint }: ReportProps): ReactElement;
+/**
+ * Render a one-shot Ink element to `stream` (stderr by default) and resolve once it's painted.
+ * Paints a single frame then unmounts, leaving it in the scrollback — the right shape for
+ * non-interactive diagnostic output, unlike the live app.
+ */
+export declare function renderReport(element: ReactElement, stream?: NodeJS.WriteStream): Promise<void>;
+/** Build a {@link Report} from plain data and render it — so non-JSX call sites (the bin, run.ts)
+ *  stay free of JSX while still using the Ink component. */
+export declare function renderDiagnostics(props: ReportProps, stream?: NodeJS.WriteStream): Promise<void>;
+/**
+ * Show a spinner labelled `label` while `work` runs, then clear it and resolve `work`'s result.
+ * Good for the noticeable-but-quiet waits (discovery, typecheck). Note: a CPU-bound synchronous
+ * `work` blocks the event loop, so the spinner shows its label but can't animate until `work`
+ * yields — it still tells the user something is happening instead of a silent hang.
+ */
+export declare function withSpinner<T>(label: string, work: () => T | Promise<T>, stream?: NodeJS.WriteStream): Promise<T>;

package/dist/cli/ui/Report.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import {} from "react";
+import { Box, Text, render, useStdout } from "ink";
+import { Spinner } from "./Spinner.js";
+const THEME = {
+    error: { color: "red", icon: "✗" },
+    warning: { color: "yellow", icon: "⚠" },
+    ok: { color: "green", icon: "✓" },
+    info: { color: "cyan", icon: "ℹ" },
+};
+/** A horizontal rule sized to the terminal (bounded), used to separate the header from the list. */
+function Divider({ color }) {
+    const { stdout } = useStdout();
+    const width = Math.max(Math.min((stdout?.columns ?? 80) - 6, 56), 12);
+    return (_jsx(Text, { color: color, dimColor: true, children: "─".repeat(width) }));
+}
+/**
+ * A colorful, bordered diagnostics panel: an icon + title header, an optional subtitle, a separator,
+ * a list of items (colored location + dim detail), and an optional dim hint footer. Kind picks the
+ * accent color (error red / warning yellow / ok green / info cyan).
+ */
+export function Report({ kind, title, subtitle, items = [], hint }) {
+    const { color, icon } = THEME[kind];
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: color, paddingX: 1, children: [_jsxs(Text, { color: color, bold: true, children: [icon, " ", title] }), subtitle ? _jsx(Text, { dimColor: true, children: subtitle }) : null, items.length > 0 ? (_jsxs(_Fragment, { children: [_jsx(Divider, { color: color }), items.map((it, i) => (_jsxs(Text, { children: [it.head ? _jsx(Text, { color: color, children: it.head }) : null, it.detail ? _jsx(Text, { dimColor: true, children: (it.head ? "  " : "") + it.detail }) : null] }, i)))] })) : null, hint ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: hint }) })) : null] }));
+}
+/**
+ * Render a one-shot Ink element to `stream` (stderr by default) and resolve once it's painted.
+ * Paints a single frame then unmounts, leaving it in the scrollback — the right shape for
+ * non-interactive diagnostic output, unlike the live app.
+ */
+export async function renderReport(element, stream = process.stderr) {
+    const app = render(element, { stdout: stream, patchConsole: false });
+    await new Promise((resolve) => setImmediate(resolve)); // let the frame paint once
+    app.unmount();
+    await app.waitUntilExit();
+}
+/** Build a {@link Report} from plain data and render it — so non-JSX call sites (the bin, run.ts)
+ *  stay free of JSX while still using the Ink component. */
+export function renderDiagnostics(props, stream = process.stderr) {
+    return renderReport(_jsx(Report, { ...props }), stream);
+}
+/**
+ * Show a spinner labelled `label` while `work` runs, then clear it and resolve `work`'s result.
+ * Good for the noticeable-but-quiet waits (discovery, typecheck). Note: a CPU-bound synchronous
+ * `work` blocks the event loop, so the spinner shows its label but can't animate until `work`
+ * yields — it still tells the user something is happening instead of a silent hang.
+ */
+export async function withSpinner(label, work, stream = process.stderr) {
+    // No TTY (piped/CI) → a spinner can't animate or erase itself; skip it and just do the work,
+    // so the output stays clean rather than leaving a stray "…" line above the result.
+    if (!stream.isTTY)
+        return work();
+    const app = render(_jsx(Spinner, { label: label }), { stdout: stream, patchConsole: false });
+    try {
+        await new Promise((resolve) => setImmediate(resolve)); // let the first frame paint
+        return await work();
+    }
+    finally {
+        app.clear(); // erase the spinner frame (unmount alone leaves the last frame on screen)
+        app.unmount();
+        await app.waitUntilExit();
+    }
+}

package/dist/cli/ui/app.d.ts

@@ -1,9 +1,12 @@
 import { type ReactElement } from "react";
 import type { OmkitClient, Verdict } from "../client/types.ts";
+import type { DiscoveredOm } from "../client/registry.ts";
 /** The interactive app: discover → list/search → run → live milestones + prompts. */
-export declare function App({ client, onExit, }: {
+export declare function App({ client, onExit, oms: initialOms, }: {
     client: OmkitClient;
     /** Called with the run's verdict (if any) just before Ink unmounts, so the caller can print
      *  a durable summary — Ink erases its own frame on exit. */
     onExit?: (verdict: Verdict | undefined) => void;
+    /** Oms discovered by the caller (pre-flight). When given, the app skips its own discovery. */
+    oms?: DiscoveredOm[];
 }): ReactElement;

package/dist/cli/ui/app.js

@@ -6,9 +6,9 @@ import { OmList } from "./views/OmList.js";
 import { RunView } from "./views/RunView.js";
 import { Spinner } from "./Spinner.js";
 /** The interactive app: discover → list/search → run → live milestones + prompts. */
-export function App({ client, onExit, }) {
+export function App({ client, onExit, oms: initialOms, }) {
     const { exit } = useApp();
-    const [oms, setOms] = useState([]);
+    const [oms, setOms] = useState(initialOms ?? []);
     const [session, setSession] = useState(null);
     const [lines, setLines] = useState([]);
     const [prompt, setPrompt] = useState();
@@ -19,6 +19,8 @@ export function App({ client, onExit, }) {
     const verdictRef = useRef(undefined);
     const tearingRef = useRef(false);
     useEffect(() => {
+        if (initialOms)
+            return; // provided by the caller's pre-flight discovery
         let live = true;
         void client.discover().then((r) => {
             if (live)
@@ -27,7 +29,7 @@ export function App({ client, onExit, }) {
         return () => {
             live = false;
         };
-    }, [client]);
+    }, [client, initialOms]);
     const run = (om) => {
         const s = client.run(om.file);
         sessionRef.current = s;

package/dist/core/ActionRun.js

@@ -131,8 +131,13 @@ export class ActionRun {
                 if (win())
                     resolve(undefined);
             }, (error) => {
-                if (win())
-                    key === "error" ? resolve(error) : reject(error);
+                if (!win())
+                    return;
+                // Awaiting the `error` event hands back the error; any other gate rejects on failure.
+                if (key === "error")
+                    resolve(error);
+                else
+                    reject(error);
             });
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",