omkit 0.8.4 → 0.8.6

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/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/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/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.4",
+  "version": "0.8.6",
   "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",