@opengeni/ogtool 0.3.26 → 0.3.31-canary.0

package/dist/catalog-discovery.d.ts

@@ -0,0 +1,12 @@
+import type { AttemptToolCatalog, AttemptToolCatalogEntry } from "@opengeni/codemode";
+export declare function shortDescription(entry: AttemptToolCatalogEntry): string;
+export type ListOptions = {
+    full: boolean;
+    json: boolean;
+    query: string;
+    limit: number;
+    offset: number;
+};
+export declare function parseListOptions(args: string[]): ListOptions;
+/** Render first, then emit: the bound includes metadata, escaping, hints, and newline. */
+export declare function compactOutput(catalog: AttemptToolCatalog, options: ListOptions): string;

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 import { type AttemptToolCatalog, type AttemptToolCatalogEntry } from "@opengeni/codemode";
 export declare function resolveTool(catalog: AttemptToolCatalog, name: string): AttemptToolCatalogEntry;
 export declare function listProjection(catalog: AttemptToolCatalog): Record<string, unknown>;
+export declare function showOutput(catalog: AttemptToolCatalog, name: string): string;
 export declare function parseToolArguments(raw: string | undefined): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/ogtool",
-  "version": "0.3.26",
+  "version": "0.3.31-canary.0",
   "description": "Codemode CLI and typed client entrypoint for an OpenGeni execution attempt.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,7 +37,7 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "^0.4.22"
+    "@opengeni/codemode": "^0.4.27-canary.0"
   },
   "engines": {
     "node": ">=18"

package/src/catalog-discovery.ts

@@ -0,0 +1,111 @@
+import type { AttemptToolCatalog, AttemptToolCatalogEntry } from "@opengeni/codemode";
+
+const DESCRIPTION_MAX_CHARS = 160;
+const LIST_MAX_BYTES = 16 * 1024;
+
+function normalizedDescription(entry: AttemptToolCatalogEntry): string {
+  return (entry.description || entry.title || "")
+    .split(/\p{White_Space}+/u)
+    .filter(Boolean)
+    .join(" ");
+}
+
+export function shortDescription(entry: AttemptToolCatalogEntry): string {
+  const text = normalizedDescription(entry);
+  const characters = Array.from(text);
+  return characters.length <= DESCRIPTION_MAX_CHARS
+    ? text
+    : `${characters.slice(0, DESCRIPTION_MAX_CHARS - 1).join("")}…`;
+}
+
+/** Terminal-only presentation: never mutate catalog, query, or JSON content. */
+function terminalDescription(text: string): string {
+  return text.replace(
+    /[\u0000-\u001f\u007f-\u009f]/gu,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+export type ListOptions = {
+  full: boolean;
+  json: boolean;
+  query: string;
+  limit: number;
+  offset: number;
+};
+
+export function parseListOptions(args: string[]): ListOptions {
+  const options: ListOptions = { full: false, json: false, query: "", limit: 50, offset: 0 };
+  const seen = new Set<string>();
+  const invalid = () =>
+    new Error(
+      "usage: ogtool list [--full | --json] [--query <substring>] [--limit <1..100>] [--offset <nonnegative integer>]",
+    );
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]!;
+    const equals = argument.indexOf("=");
+    const flag = equals < 0 ? argument : argument.slice(0, equals);
+    if (seen.has(flag)) throw invalid();
+    seen.add(flag);
+    if (flag === "--full" || flag === "--json") {
+      if (equals >= 0) throw invalid();
+      options[flag === "--full" ? "full" : "json"] = true;
+    } else if (flag === "--query" || flag === "--limit" || flag === "--offset") {
+      const value = equals < 0 ? args[++index] : argument.slice(equals + 1);
+      if (value === undefined || (equals < 0 && value.startsWith("-"))) throw invalid();
+      if (flag === "--query") options.query = value;
+      else {
+        if (!/^[0-9]+$/u.test(value) || !Number.isSafeInteger(Number(value))) throw invalid();
+        const number = Number(value);
+        if (flag === "--limit" && (number < 1 || number > 100)) throw invalid();
+        options[flag === "--limit" ? "limit" : "offset"] = number;
+      }
+    } else throw invalid();
+  }
+  if (options.full && seen.size !== 1) throw invalid();
+  return options;
+}
+
+/** Render first, then emit: the bound includes metadata, escaping, hints, and newline. */
+export function compactOutput(catalog: AttemptToolCatalog, options: ListOptions): string {
+  const matches = catalog.entries.filter(
+    (entry) =>
+      entry.codemodePath.join(".").includes(options.query) ||
+      normalizedDescription(entry).includes(options.query),
+  );
+  const tools = matches.slice(options.offset, options.offset + options.limit).map((entry) => ({
+    path: entry.codemodePath.join("."),
+    description: shortDescription(entry),
+  }));
+  const textLines = options.json
+    ? []
+    : tools.map(
+        (tool) =>
+          `${tool.path}${tool.description ? ` — ${terminalDescription(tool.description)}` : ""}\n`,
+      );
+  for (;;) {
+    const nextOffset =
+      options.offset + tools.length < matches.length ? options.offset + tools.length : null;
+    const page = {
+      catalogDigest: catalog.digest,
+      total: matches.length,
+      offset: options.offset,
+      nextOffset,
+      tools,
+    };
+    const output = options.json
+      ? `${JSON.stringify(page)}\n`
+      : textLines.slice(0, tools.length).join("") +
+        `# total: ${page.total}; offset: ${page.offset}; nextOffset: ${nextOffset ?? "none"}\n` +
+        (nextOffset === null
+          ? ""
+          : `# Continue with --offset ${nextOffset} (keep the same --query and --limit).\n`);
+    if (Buffer.byteLength(output, "utf8") <= LIST_MAX_BYTES) return output;
+    if (tools.length <= 1) {
+      throw new Error(
+        "One tool exceeds the 16384-byte compact page limit; use list --full redirected to a file",
+      );
+    }
+    tools.pop();
+  }
+}

package/src/cli.ts

@@ -7,6 +7,7 @@ import {
   type AttemptToolCatalogEntry,
 } from "@opengeni/codemode";
 import packageManifest from "../package.json" with { type: "json" };
+import { compactOutput, parseListOptions } from "./catalog-discovery";
 
 const PACKAGE_NAME = "@opengeni/ogtool";
 const VERSION = packageManifest.version;
@@ -14,7 +15,9 @@ const VERSION = packageManifest.version;
 function usage(exitCode = 1): void {
   const output = [
     "usage:",
-    "  ogtool list",
+    "  ogtool list [--full | --json]",
+    "              [--query <substring>] [--limit <1..100>] [--offset <nonnegative integer>]",
+    "  ogtool show <tool-path-or-model-name>",
     "  ogtool call <tool-path-or-model-name> [json-object]",
     "  ogtool declarations [output-file]",
     "  ogtool doctor",
@@ -148,6 +151,20 @@ export function listProjection(catalog: AttemptToolCatalog): Record<string, unkn
   };
 }
 
+const SHOW_MAX_BYTES = 64 * 1024;
+
+export function showOutput(catalog: AttemptToolCatalog, name: string): string {
+  const entry = resolveTool(catalog, name);
+  const projection = listProjection({ ...catalog, entries: [entry] });
+  const output = JSON.stringify((projection.tools as unknown[])[0], null, 2);
+  if (Buffer.byteLength(output, "utf8") + 1 > SHOW_MAX_BYTES) {
+    throw new Error(
+      "Tool details exceed 65536 bytes; use list --full or declarations <output-file>",
+    );
+  }
+  return `${output}\n`;
+}
+
 export function parseToolArguments(raw: string | undefined): Record<string, unknown> {
   if (raw === undefined) return {};
   let value: unknown;
@@ -172,9 +189,30 @@ async function main(): Promise<void> {
   if (command === "doctor") return doctor();
   if (!command) return usage();
 
+  const args = process.argv.slice(3);
+  if (
+    (command === "list" || command === "show") &&
+    args.length === 1 &&
+    (args[0] === "--help" || args[0] === "-h")
+  )
+    return usage(0);
+  const listOptions = command === "list" ? parseListOptions(args) : null;
+  if (command === "show" && (args.length !== 1 || !args[0] || args[0].startsWith("-"))) {
+    throw new Error("usage: ogtool show <tool-path-or-model-name>");
+  }
+
   const client = configuredClient();
   if (command === "list") {
-    process.stdout.write(`${JSON.stringify(listProjection(await client.catalog()), null, 2)}\n`);
+    const catalog = await client.catalog();
+    if (listOptions!.full) {
+      process.stdout.write(`${JSON.stringify(listProjection(catalog), null, 2)}\n`);
+    } else {
+      process.stdout.write(compactOutput(catalog, listOptions!));
+    }
+    return;
+  }
+  if (command === "show") {
+    process.stdout.write(showOutput(await client.catalog(), args[0]!));
     return;
   }
   if (command === "call") {