@jarkkojs/readseek-api 0.11.0 → 0.11.1

package/README.md

@@ -43,6 +43,12 @@ separate extraction step or destination argument. Cache population is an interna
 write; reading never invokes inference. Syntax checks return diagnostics even
 when the native process exits 1 (findings); exit 2 is a failure.
 
+`presentShowResult()` and `formatShowResult()` provide shared readable output for
+`show_content`, `show_structure`, `show_metadata`, and `show_assets`. Summaries
+identify selections and counts; bodies contain anchored lines, document sections,
+structure trees, fields, or asset paths. Notices identify omitted source ranges
+and how to continue. Formatting never mutates the decoded result.
+
 This is a breaking contract: legacy `inspect`/`extract` methods, selectable facets,
 and old command names are removed, not aliased.
 

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./argv.ts";
 export * from "./client.ts";
 export { serializeEditPlan } from "./edit-plan.ts";
 export * from "./hashline.ts";
+export * from "./show-presentation.ts";
 export { READSEEK_BINARY_ENV, READSEEK_PLATFORM_PACKAGES, readSeekBinaryName, readSeekPlatformKey, resolveReadSeekBinaryFromPackages, resolveReadSeekBinaryOverride, resolveReadSeekCacheDir, type ModuleResolver, type ReadSeekCacheOptions, } from "./platform.ts";
 export { canonicalPathKey, expandUserPath, isSubPath, resolveScopedPath, resolveToCwd, } from "./path.ts";
 export { cleanReadSeekErrorText } from "./error.ts";

package/dist/index.js

@@ -1347,6 +1347,221 @@ function createReadSeekClient(runner) {
     }
   };
 }
+// src/show-presentation.ts
+function isShowTool(name) {
+  return name === "show_content" || name === "show_structure" || name === "show_metadata" || name === "show_assets";
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function records(value) {
+  return Array.isArray(value) ? value.map(record) : [];
+}
+function text(value) {
+  return typeof value === "string" ? value : "";
+}
+function count(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function safe(value) {
+  return value.replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, (char) => {
+    if (char === "\t")
+      return "\\t";
+    if (char === "\r")
+      return "\\r";
+    return `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+function inline(value) {
+  return safe(text(value)).replaceAll(`
+`, "\\n");
+}
+function plural(n, unit) {
+  return `${n} ${unit}${n === 1 ? "" : "s"}`;
+}
+function fields(value, omit = []) {
+  return Object.entries(value).flatMap(([key, item]) => {
+    if (omit.includes(key) || item === undefined || item === null || typeof item === "object")
+      return [];
+    const label = key.replaceAll("_", " ");
+    return [`${label[0]?.toUpperCase() ?? ""}${label.slice(1)}: ${safe(String(item))}`];
+  }).join(`
+`);
+}
+function location(value) {
+  const start = text(value.start_anchor) || (count(value.start_line) !== undefined ? `${value.start_line}${text(value.start_hash) ? `:${value.start_hash}` : ""}` : "");
+  const end = text(value.end_anchor) || (count(value.end_line) !== undefined ? `${value.end_line}${text(value.end_hash) ? `:${value.end_hash}` : ""}` : "");
+  return start ? `  ${inline(start)}${end && end !== start ? ` - ${inline(end)}` : ""}` : "";
+}
+function sourceStructure(structure) {
+  const sections = [];
+  if (structure.root) {
+    const lines = [];
+    const stack = [{ node: record(structure.root), depth: 0 }];
+    while (stack.length > 0) {
+      const { node, depth } = stack.pop();
+      lines.push(`${"  ".repeat(Math.min(depth, 12))}${inline(node.kind) || "node"}${text(node.name) ? ` ${inline(node.name)}` : ""}${location(node)}`);
+      const children = records(node.children);
+      for (let i = children.length - 1;i >= 0; i--)
+        stack.push({ node: children[i], depth: depth + 1 });
+    }
+    sections.push(`Tree
+${lines.join(`
+`)}`);
+  }
+  const symbols = records(structure.symbols);
+  if (symbols.length > 0) {
+    sections.push(`Symbols
+${symbols.map((symbol) => `${inline(symbol.kind) || "symbol"} ${inline(symbol.qualified_name || symbol.name)}${location(symbol)}`).join(`
+`)}`);
+  }
+  return sections.join(`
+
+`) || "No structure found in this selection.";
+}
+function documentNodes(nodes, content) {
+  const depths = new Map;
+  return nodes.map((node) => {
+    const depth = Math.min((depths.get(text(node.parent_id)) ?? -1) + 1, 12);
+    depths.set(text(node.id), depth);
+    const indent = "  ".repeat(depth);
+    const label = inline(node.title) || inline(node.kind) || "node";
+    const page = count(node.page);
+    const selector = text(node.id) ? `node:${inline(node.id)}` : "";
+    const position = [selector, page !== undefined ? `page:${page}` : ""].filter(Boolean).join(" · ");
+    const heading = `${indent}${label}${position ? `  [${position}]` : ""}`;
+    const body = text(node.text);
+    return content && body ? `${heading}
+${safe(body).split(`
+`).map((line) => indent + line).join(`
+`)}` : heading;
+  }).join(content ? `
+
+` : `
+`);
+}
+function assetList(assets) {
+  return assets.map((asset) => {
+    const id = text(asset.id);
+    const page = count(asset.page);
+    const heading = [id ? `asset:${inline(id)}` : inline(asset.kind) || "image", inline(asset.mime), page !== undefined ? `page:${page}` : ""].filter(Boolean).join(" · ");
+    const details = fields(asset, ["id", "kind", "mime", "page", "bbox", "content_identity"]);
+    return `${heading}${details ? `
+${details.split(`
+`).map((line) => `  ${line}`).join(`
+`)}` : ""}`;
+  }).join(`
+
+`);
+}
+function presentShowResult(tool, value, options = {}) {
+  const output = record(value);
+  const metadata = record(output.metadata);
+  const content = record(output.content);
+  const cursor = record(output.cursor);
+  const structure = record(output.structure);
+  const document = typeof output.format === "string" && (Array.isArray(output.nodes) || typeof output.source === "string");
+  const path = inline(options.path || output.source || output.file || content.file || structure.file || metadata.file || cursor.file) || "(unknown path)";
+  const summary = [];
+  const result = { summary: "", body: "", notices: [], metadata: {} };
+  if (tool === "show_metadata") {
+    const data = Object.keys(metadata).length > 0 ? metadata : output;
+    if (text(data.format || data.language || data.type))
+      summary.push(inline(data.format || data.language || data.type));
+    if (count(data.pages) !== undefined) {
+      result.metadata.pages = data.pages;
+      summary.push(plural(result.metadata.pages, "page"));
+    }
+    result.body = fields(data) || "No metadata available.";
+  } else if (tool === "show_assets") {
+    const assets = records(output.assets);
+    result.metadata.assets = assets.length;
+    summary.push(plural(assets.length, "asset"));
+    result.body = assetList(assets) || "No assets in this selection.";
+  } else if (document) {
+    const nodes = records(output.nodes);
+    const assets = records(output.assets);
+    result.metadata.nodes = nodes.length;
+    if (count(output.pages) !== undefined)
+      result.metadata.pages = output.pages;
+    summary.push(plural(nodes.length, "node"));
+    if (result.metadata.pages !== undefined)
+      summary.push(plural(result.metadata.pages, "page"));
+    const sections = [text(output.title) ? safe(text(output.title)) : "", documentNodes(nodes, tool === "show_content")];
+    if (assets.length > 0) {
+      result.metadata.assets = assets.length;
+      sections.push(`Assets
+${assetList(assets)}`);
+    }
+    result.body = sections.filter(Boolean).join(`
+
+`) || "No content in this selection.";
+  } else if (tool === "show_structure") {
+    const symbols = records(structure.symbols);
+    result.metadata.symbols = symbols.length;
+    summary.push(plural(symbols.length, "symbol"));
+    result.body = sourceStructure(structure);
+  } else if (content.kind === "image" || count(content.width) !== undefined && count(content.height) !== undefined || count(metadata.width) !== undefined && count(metadata.height) !== undefined || text(content.mime).startsWith("image/") || text(metadata.mime).startsWith("image/") || text(metadata.type).startsWith("image/")) {
+    const description = Object.keys(content).length > 0 ? content : Object.keys(metadata).length > 0 ? metadata : output;
+    if (count(description.width) !== undefined && count(description.height) !== undefined) {
+      summary.push(`${description.width} × ${description.height}`);
+    } else if (count(metadata.width) !== undefined && count(metadata.height) !== undefined) {
+      summary.push(`${metadata.width} × ${metadata.height}`);
+    }
+    const mime = text(description.mime || metadata.mime || metadata.type);
+    if (mime)
+      summary.push(inline(mime));
+    result.body = fields(description, ["hashlines"]) || fields(metadata) || "No content in this selection.";
+  } else if (Array.isArray(content.hashlines) || Array.isArray(cursor.hashlines)) {
+    const lines = records(content.hashlines ?? cursor.hashlines);
+    const start = count(content.start_line) ?? count(lines[0]?.line);
+    const end = count(content.end_line) ?? count(lines.at(-1)?.line);
+    const total = count(content.line_count) ?? count(cursor.line_count);
+    if (start !== undefined && end !== undefined && start <= end) {
+      result.metadata.start_line = start;
+      result.metadata.end_line = end;
+      summary.push(`lines ${start}-${end}${total !== undefined ? ` of ${total}` : ""}`);
+    } else
+      summary.push(plural(lines.length, "line"));
+    const lang = text(metadata.language || content.language);
+    if (lang)
+      summary.push(inline(lang));
+    const rows = lines.map((line) => `${line.line}${options.noAnchors ? "" : `:${text(line.hash)}`} | ${safe(text(line.text)).replaceAll("\\n", "\\\\n")}`);
+    const identifier = record(cursor.identifier);
+    if (count(cursor.line) !== undefined)
+      result.metadata.line = cursor.line;
+    if (count(cursor.column) !== undefined)
+      result.metadata.column = cursor.column;
+    if (Object.keys(cursor).length > 0) {
+      const symbol = record(cursor.symbol);
+      const description = [text(identifier.text), text(symbol.qualified_name || symbol.name), text(symbol.kind)].filter(Boolean);
+      rows.unshift(`Cursor: ${cursor.line ?? "?"}:${cursor.column ?? "?"}${description.length > 0 ? ` · ${[...new Set(description)].map(inline).join(" · ")}` : ""}`, "");
+    }
+    result.body = rows.join(`
+`) || "Empty source selection.";
+    if (start !== undefined && start > 1)
+      result.notices.push(`Earlier lines omitted. Read preceding content with at: line:1 and limit: ${start - 1}.`);
+    if (end !== undefined && total !== undefined && end < total) {
+      result.notices.push(`More lines available. Continue with at: line:${end + 1}.`);
+    } else if (content.truncated === true && (end === undefined || total === undefined)) {
+      result.notices.push(`Content is truncated.${end !== undefined ? ` Continue with at: line:${end + 1}.` : " Select a smaller range with at and limit."}`);
+    }
+  } else {
+    const description = Object.keys(content).length > 0 ? content : output;
+    result.body = fields(description) || "No content in this selection.";
+  }
+  if (tool === "show_structure")
+    result.notices.push("Structure is limited to the requested depth, kind, and outline. Use a deeper depth or focus with at to inspect further.");
+  if (text(output.warning))
+    result.notices.push(safe(text(output.warning)));
+  result.summary = summary.join(" · ") || "complete";
+  return result;
+}
+function formatShowResult(presentation) {
+  return [presentation.summary, presentation.body, ...presentation.notices.map((notice) => `Note: ${notice}`)].filter(Boolean).join(`
+
+`);
+}
 // src/platform.ts
 import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -2113,13 +2328,16 @@ export {
   expandUserPath,
   failureFromProcessResult,
   fallbackToolDescriptionMap,
+  formatShowResult,
   getToolContract,
+  isShowTool,
   isSubPath,
   parseLineAnchor,
   parseReadSeekKdl,
   parseSelector,
   parseSuccessfulKdl,
   preferredToolDescriptionMap,
+  presentShowResult,
   readSeekBinaryName,
   readSeekPlatformKey,
   readSeekProcessEnvironment,

package/dist/show-presentation.d.ts

@@ -0,0 +1,15 @@
+export type ShowTool = "show_content" | "show_structure" | "show_metadata" | "show_assets";
+export interface ShowPresentation {
+    summary: string;
+    body: string;
+    notices: string[];
+    metadata: Record<string, number>;
+}
+export interface ShowPresentationOptions {
+    path?: string;
+    at?: string;
+    noAnchors?: boolean;
+}
+export declare function isShowTool(name: string): name is ShowTool;
+export declare function presentShowResult(tool: ShowTool, value: unknown, options?: ShowPresentationOptions): ShowPresentation;
+export declare function formatShowResult(presentation: ShowPresentation): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.11.0",
+    "@jarkkojs/readseek": "^0.11.1",
     "@bgotink/kdl": "0.4.0",
     "@sinclair/typebox": "0.34.52"
   }