omkit 0.8.3 → 0.8.5

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

@@ -1,6 +1,11 @@
 import type { RegistrationSet, Registry } from "../../client/registry.ts";
 export interface FormatOptions {
     readonly json?: boolean;
+    /**
+     * Where om depth is measured from for the listing order. Defaults to the working directory —
+     * the same root the interactive picker measures from, so `ls` and the picker agree.
+     */
+    readonly root?: string;
     /**
      * What the oms and actions declare, from the discovery fork. Present only under
      * `--describe`: reading it costs an import of every candidate file, which is why plain
@@ -8,5 +13,11 @@ export interface FormatOptions {
      */
     readonly registrations?: RegistrationSet;
 }
-/** Render a {@link Registry} for the terminal (plain text) or as JSON. */
+/**
+ * Render a {@link Registry} for the terminal (plain text) or as JSON.
+ *
+ * Oms are listed with {@link byNesting} — the core workflows near the root first — in both
+ * modes, and in the registrations too, since under `--describe` the JSON `oms` key is theirs.
+ * Actions keep discovery order: they are looked up by name, not browsed.
+ */
 export declare function formatRegistry(registry: Registry, opts?: FormatOptions): string;

package/dist/cli/commands/ls.js

@@ -1,12 +1,25 @@
 import path from "node:path";
-/** Render a {@link Registry} for the terminal (plain text) or as JSON. */
+import { byNesting } from "../../client/order.js";
+/**
+ * Render a {@link Registry} for the terminal (plain text) or as JSON.
+ *
+ * Oms are listed with {@link byNesting} — the core workflows near the root first — in both
+ * modes, and in the registrations too, since under `--describe` the JSON `oms` key is theirs.
+ * Actions keep discovery order: they are looked up by name, not browsed.
+ */
 export function formatRegistry(registry, opts = {}) {
+    const order = byNesting(opts.root ?? process.cwd());
+    const oms = [...registry.oms].sort(order);
+    const registrations = opts.registrations && {
+        ...opts.registrations,
+        oms: [...opts.registrations.oms].sort(order),
+    };
     if (opts.json)
-        return renderJson(registry, opts.registrations);
-    const declared = index(opts.registrations);
+        return renderJson({ ...registry, oms }, registrations);
+    const declared = index(registrations);
     const lines = [
-        `oms (${registry.oms.length})`,
-        ...registry.oms.flatMap((om) => row(`${om.name}  ${path.basename(om.file)}:${om.line}`, [], declared?.get(key(om.name, om.file)))),
+        `oms (${oms.length})`,
+        ...oms.flatMap((om) => row(`${om.name}  ${path.basename(om.file)}:${om.line}`, [], declared?.get(key(om.name, om.file)))),
         "",
         `actions (${registry.actions.length})`,
         ...registry.actions.flatMap((a) => row(`${a.name}  ${path.basename(a.file)}`, [a.publishesCapability ? "ref" : "", a.events ? "events" : ""], declared?.get(key(a.name, a.file)))),

package/dist/cli/ui/app.js

@@ -5,6 +5,17 @@ import { RunModel } from "../../output/RunModel.js";
 import { OmList } from "./views/OmList.js";
 import { RunView } from "./views/RunView.js";
 import { Spinner } from "./Spinner.js";
+/**
+ * How often the run screen redraws while the log streams in.
+ *
+ * An Ink frame costs ~25ms at minimum and grows with the milestone tail, so redrawing per log
+ * entry caps the app at roughly 40 entries/second — far under what a build, a test suite, or a
+ * dev server emits. The app then falls permanently behind: `settled` is the *last* message on
+ * the channel, so it only arrives once every backlogged entry has been drawn, and the run looks
+ * hung long after the child has finished. Folding into the model is cheap; drawing is not, so
+ * the two run at different rates.
+ */
+const REDRAW_MS = 80;
 /** The interactive app: discover → list/search → run → live milestones + prompts. */
 export function App({ client, onExit, oms: initialOms, }) {
     const { exit } = useApp();
@@ -21,6 +32,16 @@ export function App({ client, onExit, oms: initialOms, }) {
     const sessionRef = useRef(null);
     const verdictRef = useRef(undefined);
     const tearingRef = useRef(false);
+    const redrawTimer = useRef(undefined);
+    const stopRedraw = () => {
+        if (redrawTimer.current === undefined)
+            return;
+        clearInterval(redrawTimer.current);
+        redrawTimer.current = undefined;
+    };
+    // The redraw timer holds the event loop open, so it must not outlive the app — an unmount
+    // for any reason other than the run settling would otherwise keep the CLI from exiting.
+    useEffect(() => stopRedraw, []);
     useEffect(() => {
         if (initialOms)
             return; // provided by the caller's pre-flight discovery
@@ -37,17 +58,34 @@ export function App({ client, onExit, oms: initialOms, }) {
         const model = new RunModel();
         const s = client.run(om.file);
         sessionRef.current = s;
-        s.on("log", (entry) => {
-            model.apply(entry);
+        // Every entry lands in the model immediately; the screen catches up on its own cadence.
+        // `dirty` keeps an idle run from redrawing over nothing — see REDRAW_MS for why the two
+        // are separated at all.
+        let dirty = false;
+        const redraw = () => {
+            if (!dirty)
+                return;
+            dirty = false;
             setLines(model.milestones());
             setStatus(model.summary());
+        };
+        redrawTimer.current = setInterval(redraw, REDRAW_MS);
+        s.on("log", (entry) => {
+            model.apply(entry);
+            dirty = true;
+        });
+        // A prompt blocks the child until it's answered, so it must not wait for the next tick —
+        // and the milestones that led to it are the context the question is read in.
+        s.on("prompt", (req) => {
+            redraw();
+            setPrompt(req);
         });
-        s.on("prompt", (req) => setPrompt(req));
         // The child gave up on the prompt (timed out or torn down). Withdraw its box so a stale,
         // unanswerable prompt doesn't linger — but only if it's still the one on screen, so a late
         // withdrawal can't clobber a fresh prompt.
         s.on("promptDone", (id) => setPrompt((p) => (p?.id === id ? undefined : p)));
         s.on("settled", (v) => {
+            redraw(); // the run's closing milestones, before its verdict
             setVerdict(v);
             setPrompt(undefined);
         });
@@ -57,6 +95,8 @@ export function App({ client, onExit, oms: initialOms, }) {
         // so it can print the durable summary block, and unmount. Without this a self-completing run
         // would show its verdict line but never exit or render the summary.
         void s.result.then((v) => {
+            stopRedraw();
+            redraw(); // last pass: whatever arrived since the final tick
             verdictRef.current = v;
             setVerdict(v);
             onExit?.(v);

package/dist/cli/ui/views/OmList.d.ts

@@ -1,6 +1,12 @@
 import { type ReactElement } from "react";
 import type { DiscoveredOm } from "../../../client/registry.ts";
-/** A searchable, arrow-navigable list of oms; Enter selects the highlighted one. */
+/**
+ * A searchable, arrow-navigable list of oms; Enter selects the highlighted one.
+ *
+ * Rows are ordered by {@link byNesting} from the working directory — the same root the path
+ * column is rendered from, so the order matches what the column shows: the oms nearest the
+ * top of the project first, deeper ones after, and any shown as an absolute path last.
+ */
 export declare function OmList({ oms, onSelect, }: {
     oms: DiscoveredOm[];
     onSelect: (om: DiscoveredOm) => void;

package/dist/cli/ui/views/OmList.js

@@ -1,16 +1,25 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import path from "node:path";
-import {} from "react";
+import { useMemo } from "react";
 import { Text } from "ink";
 import { SearchableList } from "./SearchableList.js";
-/** Show the om's path relative to cwd when it's inside the project; else the absolute path. */
-function displayPath(file) {
-    const rel = path.relative(process.cwd(), file);
+import { byNesting } from "../../../client/order.js";
+/** Show the om's path relative to `root` when it's inside it; else the absolute path. */
+function displayPath(file, root) {
+    const rel = path.relative(root, file);
     return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : file;
 }
-/** A searchable, arrow-navigable list of oms; Enter selects the highlighted one. */
+/**
+ * A searchable, arrow-navigable list of oms; Enter selects the highlighted one.
+ *
+ * Rows are ordered by {@link byNesting} from the working directory — the same root the path
+ * column is rendered from, so the order matches what the column shows: the oms nearest the
+ * top of the project first, deeper ones after, and any shown as an absolute path last.
+ */
 export function OmList({ oms, onSelect, }) {
+    const root = process.cwd();
+    const sorted = useMemo(() => [...oms].sort(byNesting(root)), [oms, root]);
     // Column width so paths line up; capped so one long name can't push paths off-screen.
     const nameWidth = Math.min(30, oms.reduce((w, o) => Math.max(w, o.name.length), 0));
-    return (_jsx(SearchableList, { items: oms, getKey: (o) => o.name, getSearchText: (o) => o.name, onSelect: onSelect, renderRow: (o, selected) => (_jsxs(Text, { children: [_jsx(Text, { color: selected ? "cyan" : undefined, children: selected ? "❯ " : "  " }), _jsx(Text, { bold: selected, children: o.name.padEnd(nameWidth) }), "  ", _jsx(Text, { dimColor: true, children: displayPath(o.file) })] })) }));
+    return (_jsx(SearchableList, { items: sorted, getKey: (o) => o.name, getSearchText: (o) => o.name, onSelect: onSelect, renderRow: (o, selected) => (_jsxs(Text, { children: [_jsx(Text, { color: selected ? "cyan" : undefined, children: selected ? "❯ " : "  " }), _jsx(Text, { bold: selected, children: o.name.padEnd(nameWidth) }), "  ", _jsx(Text, { dimColor: true, children: displayPath(o.file, root) })] })) }));
 }

package/dist/client/channel.d.ts

@@ -5,6 +5,11 @@ export interface Transport {
     send(message: SupervisorMessage): void;
     onMessage(handler: (message: ChildMessage) => void): void;
     onClose(handler: (code: number | null) => void): void;
+    /**
+     * Whatever the child printed outside the channel, for a close that never reached `settled`.
+     * Read only on that path — a run that reports for itself needs no second account.
+     */
+    diagnostics?(): string[];
 }
 /**
  * Turn a child transport into a {@link RunSession}: fan `log`/`prompt`/`prompt-done` child

package/dist/client/channel.js

@@ -35,8 +35,15 @@ export function createChannel(transport) {
         }
     });
     transport.onClose(() => {
-        if (!settled)
-            resolveResult({ ok: false, folder: "", summary: [] });
+        if (settled)
+            return;
+        // The child died before it could report: there is no run folder and no summary of its own.
+        // What it printed on its way out — a module that failed to load, a crash during import — is
+        // the only account of why, so it stands in as the summary. Without it the frontend shows a
+        // bare "✗ failed" and the reason is lost with the process.
+        const output = transport.diagnostics?.() ?? [];
+        const summary = output.length ? ["the run ended before it could report:", ...output] : [];
+        resolveResult({ ok: false, folder: "", summary });
     });
     return {
         on(event, handler) {

package/dist/client/order.d.ts

@@ -0,0 +1,21 @@
+/** What the listing order needs from an entry: its name, and where it is defined. */
+export interface Located {
+    readonly name: string;
+    readonly file: string;
+}
+/**
+ * How many directories lie between `root` and `file`: `oms/build.ts` is 1, `build.ts` is 0.
+ * A file outside the root is `Infinity`, so it lists after everything the root contains rather
+ * than at a depth invented from its `..` segments.
+ */
+export declare function nestingDepth(file: string, root: string): number;
+/**
+ * The order a project's oms are presented in: shallowest first, then by name, then by file.
+ *
+ * Where an om sits says what it is for. The workflows at the top of a project are the ones
+ * people reach for every day; one three folders down is a specialised variant or a helper
+ * behind them. Listing by depth puts the core oms first without asking authors to rank them.
+ * Depth is measured from the root the listing renders its paths from, so the order matches
+ * the column it sits beside. The file tie-break keeps two same-named oms in a fixed order.
+ */
+export declare function byNesting(root: string): (a: Located, b: Located) => number;

package/dist/client/order.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+/**
+ * How many directories lie between `root` and `file`: `oms/build.ts` is 1, `build.ts` is 0.
+ * A file outside the root is `Infinity`, so it lists after everything the root contains rather
+ * than at a depth invented from its `..` segments.
+ */
+export function nestingDepth(file, root) {
+    const rel = path.relative(root, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return Infinity;
+    return rel.split(path.sep).length - 1;
+}
+/**
+ * The order a project's oms are presented in: shallowest first, then by name, then by file.
+ *
+ * Where an om sits says what it is for. The workflows at the top of a project are the ones
+ * people reach for every day; one three folders down is a specialised variant or a helper
+ * behind them. Listing by depth puts the core oms first without asking authors to rank them.
+ * Depth is measured from the root the listing renders its paths from, so the order matches
+ * the column it sits beside. The file tie-break keeps two same-named oms in a fixed order.
+ */
+export function byNesting(root) {
+    return (a, b) => nestingDepth(a.file, root) - nestingDepth(b.file, root) ||
+        a.name.localeCompare(b.name) ||
+        a.file.localeCompare(b.file);
+}

package/dist/client/runner.js

@@ -18,6 +18,30 @@ export function inspectArgs(inspect) {
         return [];
     return [`--inspect=${inspect.port}`];
 }
+/**
+ * How much of a child's raw output to keep. Enough for a module-resolution failure or a stack
+ * trace, small enough that a run which prints megabytes still costs nothing to supervise.
+ */
+const TAIL_BYTES = 8 * 1024;
+/**
+ * Drain a child's raw streams while keeping the last {@link TAIL_BYTES} of them. Attaching a
+ * `data` handler is what puts each stream in flowing mode — that, not the tail, is what stops
+ * the child wedging on a full pipe. Returns a reader for the kept lines, oldest first; stdout
+ * and stderr share one buffer so a message split across them stays in order.
+ */
+function keepTail(...streams) {
+    let text = "";
+    for (const stream of streams) {
+        stream?.setEncoding("utf8");
+        stream?.on("data", (chunk) => {
+            text = (text + chunk).slice(-TAIL_BYTES);
+        });
+    }
+    return () => text
+        .split("\n")
+        .map((line) => line.replace(/\r$/, "").trimEnd())
+        .filter((line) => line !== "");
+}
 /**
  * Fork `omFile` as a supervised child: the `tsx` loader runs the TypeScript directly,
  * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
@@ -38,10 +62,19 @@ export function runOm(omFile, opts = {}) {
         env: { ...process.env, OMKIT_SUPERVISED: "1", ...opts.env },
         stdio: ["ignore", "pipe", "pipe", "ipc"],
     });
+    // Piped, not read: nothing in the supervisor consumes these streams, so once the OS pipe
+    // buffer fills (~64 KB) the child blocks on its next write — permanently, since the only
+    // thing the supervisor ever reads is the IPC channel. `patch-console` swaps the console
+    // methods but not `process.stdout.write`, so any direct write in an om (or in a library it
+    // uses) lands here and wedges the run before it can settle. Draining is what keeps the child
+    // moving; the tail is kept because a child that dies before the channel opens has nowhere
+    // else to say why (see the Transport's `diagnostics`).
+    const tail = keepTail(child.stdout, child.stderr);
     const transport = {
         send: (message) => void child.send(message),
         onMessage: (handler) => void child.on("message", (m) => handler(m)),
         onClose: (handler) => void child.on("close", (code) => handler(code)),
+        diagnostics: tail,
     };
     const session = createChannel(transport);
     // When the run settles, the child has already written its logs and reaped its process tree —

package/dist/skill/model.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { shapeHint } from "../core/schema-hint.js";
 import { DEFAULT_TSCONFIG } from "../client/types.js";
+import { byNesting } from "../client/order.js";
 /**
  * Fold a project's registrations and its AST scan into the model the skill renders from.
  *
@@ -16,10 +17,12 @@ export function buildSkillModel(registrations, registry, project) {
     const { root } = project;
     const outlines = new Map(registry.oms.map((o) => [key(o.name, o.file), o.calls]));
     const capabilities = new Map(registry.actions.map((a) => [key(a.name, a.file), a.publishesCapability]));
+    // Oms are what a reader picks from, so the core ones — those nearest the root — lead.
+    // Actions are looked up by name from an om's outline, so alphabetical is their lookup order.
     const oms = registrations.oms
         .filter(isExposed)
-        .map((om) => omEntry(om, outlines.get(key(om.name, om.file)), root))
-        .sort(byName);
+        .sort(byNesting(root))
+        .map((om) => omEntry(om, outlines.get(key(om.name, om.file)), root));
     const actions = registrations.actions
         .filter(isExposed)
         .map((a) => actionEntry(a, capabilities.get(key(a.name, a.file)), root))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "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",