deepline 0.3.461 → 0.3.463

package/dist/cli/{chunk-HDFRJ4IT.mjs → chunk-JVHOS3K3.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-OVDNJAJN.mjs";
 import {
   cloneEditStarter
-} from "./chunk-EIMG75BT.mjs";
+} from "./chunk-S3A4IXBQ.mjs";
 
 // src/cli/described.ts
 var SHAPE = "{}";
@@ -48,6 +48,14 @@ var NAMED_EXAMPLES = {
 };
 function schemaType(schema) {
   const brackets = (type) => type.includes(" | ") ? `(${type})` : type;
+  if (typeof schema.$ref === "string") {
+    const { $ref, ...siblings } = schema;
+    const sibling = schemaType(siblings);
+    return {
+      ...sibling,
+      type: sibling.type === "unknown" ? $ref : `${$ref} & ${brackets(sibling.type)}`
+    };
+  }
   if (Array.isArray(schema.enum) && schema.enum.length) {
     return {
       type: schema.enum.map((value) => JSON.stringify(value)).join(" | ")
@@ -55,9 +63,7 @@ function schemaType(schema) {
   }
   const alternatives = [schema.anyOf, schema.oneOf].find(Array.isArray);
   if (alternatives) {
-    const parts = alternatives.map(
-      (option) => schemaType(isRecord(option) ? option : {})
-    );
+    const parts = alternatives.map((option) => schemaType(isRecord(option) ? option : {})).sort((a, b) => Number(a.type === "null") - Number(b.type === "null"));
     const shaped = parts.find((part) => part.fields);
     return {
       type: parts.map(
@@ -86,8 +92,9 @@ function schemaType(schema) {
       ...value.fields ? { fields: value.fields } : {}
     };
   }
+  const nonNull = types.filter((type) => type !== "null").join(" | ");
   return {
-    type: types.filter((type) => type !== "null").join(" | ") + nullable || "unknown"
+    type: nonNull ? nonNull + nullable : nullable ? "null" : "unknown"
   };
 }
 function schemaField(name, node, required) {
@@ -109,29 +116,57 @@ function schemaField(name, node, required) {
     ...typeof schema.means === "string" ? { means: schema.means } : {}
   };
 }
-function withoutRefs(node, root, depth = 0) {
+function resolveSchemaReference(root, ref) {
+  const definitions = isRecord(root) ? [root.$defs, root.definitions].filter(isRecord) : [];
+  const target = ref.startsWith("#/") ? ref.slice(2).split("/").reduce(
+    (at, key) => isRecord(at) ? at[key] : void 0,
+    root
+  ) : definitions.flatMap((group) => Object.values(group)).find((definition) => isRecord(definition) && definition.$id === ref);
+  return isRecord(target) ? target : void 0;
+}
+function withoutRefs(node, root, expandedRefs = /* @__PURE__ */ new Set(), fieldRoots = false) {
   if (Array.isArray(node)) {
-    return node.map((item) => withoutRefs(item, root, depth));
+    return node.map((item) => withoutRefs(item, root, expandedRefs));
   }
   if (!isRecord(node)) return node;
   const { $ref: ref, ...rest } = node;
   if (typeof ref === "string") {
-    const definitions = isRecord(root) ? [root.$defs, root.definitions].filter(isRecord) : [];
-    const target = ref.startsWith("#/") ? ref.slice(2).split("/").reduce(
-      (at, key) => isRecord(at) ? at[key] : void 0,
-      root
-    ) : definitions.flatMap((group) => Object.values(group)).find((definition) => isRecord(definition) && definition.$id === ref);
-    return isRecord(target) && depth < 12 ? withoutRefs({ ...target, ...rest }, root, depth + 1) : rest;
+    if (expandedRefs.has(ref)) return node;
+    const target = resolveSchemaReference(root, ref);
+    if (!isRecord(target)) return rest;
+    expandedRefs.add(ref);
+    return withoutRefs({ ...target, ...rest }, root, expandedRefs, fieldRoots);
   }
   return Object.fromEntries(
-    Object.entries(rest).map(([key, value]) => [
-      key,
-      key === "$defs" || key === "definitions" ? value : withoutRefs(value, root, depth)
-    ])
+    Object.entries(rest).map(([key, value]) => {
+      if (key === "fields" && Array.isArray(value)) {
+        return [
+          key,
+          value.map(
+            (field) => withoutRefs(field, root, fieldRoots ? /* @__PURE__ */ new Set() : expandedRefs)
+          )
+        ];
+      }
+      if (key === "properties" && isRecord(value)) {
+        return [
+          key,
+          Object.fromEntries(
+            Object.entries(value).map(([name, child]) => [
+              name,
+              withoutRefs(child, root, fieldRoots ? /* @__PURE__ */ new Set() : expandedRefs)
+            ])
+          )
+        ];
+      }
+      if (["items", "additionalProperties", "anyOf", "oneOf"].includes(key)) {
+        return [key, withoutRefs(value, root, expandedRefs)];
+      }
+      return [key, value];
+    })
   );
 }
 function schemaFields(schema) {
-  return fieldsOf(withoutRefs(schema, schema));
+  return fieldsOf(withoutRefs(schema, schema, /* @__PURE__ */ new Set(), true));
 }
 function fieldsOf(schema) {
   if (!isRecord(schema)) return [];
@@ -178,14 +213,39 @@ function rateLimitQualifier(limit) {
   ].filter(Boolean);
   return notes.length ? ` ${notes.join(", ")}` : "";
 }
-function exampleValue(field, schema) {
+var InputFileExampleRequired = class extends Error {
+};
+function exampleValue(field, schema, rootSchema = schema, activeRefs = /* @__PURE__ */ new Set(), expandedObjectRefs = /* @__PURE__ */ new Set()) {
   if (field.example !== void 0) return field.example;
+  if (isRecord(schema) && typeof schema.$ref === "string" && !activeRefs.has(schema.$ref)) {
+    const { $ref, ...siblings } = schema;
+    const target = resolveSchemaReference(rootSchema, $ref);
+    if (target) {
+      const resolved = { ...target, ...siblings };
+      const resolvedField = schemaField(field.name, resolved, field.required);
+      const expanded = activeRefs.size ? expandedObjectRefs : /* @__PURE__ */ new Set();
+      if (resolvedField.fields?.some((child) => child.required) && !resolvedField.type.includes("[]")) {
+        if (expanded.has($ref)) throw new InputFileExampleRequired();
+        expanded.add($ref);
+      }
+      return exampleValue(
+        resolvedField,
+        resolved,
+        rootSchema,
+        /* @__PURE__ */ new Set([...activeRefs, $ref]),
+        expanded
+      );
+    }
+  }
   if (field.type.startsWith(RECORD)) {
     const value = field.type.slice(RECORD.length).replace(/>( \| null)?$/, "");
     return {
       key: exampleValue(
         { ...field, type: value },
-        isRecord(schema) ? schema.additionalProperties : void 0
+        isRecord(schema) ? schema.additionalProperties : void 0,
+        rootSchema,
+        activeRefs,
+        expandedObjectRefs
       )
     };
   }
@@ -197,7 +257,13 @@ function exampleValue(field, schema) {
     return Object.fromEntries(
       (field.fields ?? []).filter((child) => child.required).map((child) => [
         child.name,
-        exampleValue(child, propertySchema(schema, child.name))
+        exampleValue(
+          child,
+          propertySchema(schema, child.name, rootSchema),
+          rootSchema,
+          activeRefs,
+          expandedObjectRefs
+        )
       ])
     );
   }
@@ -208,8 +274,35 @@ function exampleValue(field, schema) {
   if (type.startsWith("boolean")) return true;
   return "...";
 }
-function propertySchema(schema, name) {
-  return isRecord(schema) && isRecord(schema.properties) ? schema.properties[name] : void 0;
+function propertySchema(schema, name, rootSchema = schema, activeRefs = /* @__PURE__ */ new Set()) {
+  if (!isRecord(schema)) return void 0;
+  if (typeof schema.$ref === "string" && !activeRefs.has(schema.$ref)) {
+    const { $ref, ...siblings } = schema;
+    const target = resolveSchemaReference(rootSchema, $ref);
+    if (target)
+      return propertySchema(
+        { ...target, ...siblings },
+        name,
+        rootSchema,
+        /* @__PURE__ */ new Set([...activeRefs, $ref])
+      );
+  }
+  if (isRecord(schema.properties) && name in schema.properties)
+    return schema.properties[name];
+  if (Array.isArray(schema.fields)) {
+    const field = schema.fields.find(
+      (value) => isRecord(value) && value.name === name
+    );
+    if (field) return field;
+  }
+  for (const keyword of ["anyOf", "oneOf"]) {
+    if (!Array.isArray(schema[keyword])) continue;
+    for (const branch of schema[keyword]) {
+      const property = propertySchema(branch, name, rootSchema, activeRefs);
+      if (property !== void 0) return property;
+    }
+  }
+  return void 0;
 }
 function lowestNumber(schema) {
   const bounds = isRecord(schema) ? schema : {};
@@ -220,14 +313,13 @@ function lowestNumber(schema) {
   return lowest >= 0 ? lowest : 1;
 }
 function shapeKey(fields) {
-  return JSON.stringify(
-    fields.map((field) => [
-      field.name,
-      field.required,
-      field.type,
-      field.fields ? shapeKey(field.fields) : null
-    ])
-  );
+  const structure = (children) => children.map((field) => [
+    field.name,
+    field.required,
+    field.type,
+    field.fields ? structure(field.fields) : null
+  ]);
+  return JSON.stringify(structure(fields));
 }
 function pascalCase(text) {
   return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/).filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join("");
@@ -318,8 +410,8 @@ function withRowOutputs(described) {
     (field) => field.name === "rows" ? typed(field) : field
   ) : [...described.outputs, typed({ name: "rows", type: "", required: true })];
 }
-function schemaBlocks(described, maxDepth, everyField = false) {
-  const sections = [
+function describedSections(described, everyField) {
+  return [
     ["Inputs:", withRowInputs(described)],
     ["Outputs:", withRowOutputs(described)],
     [
@@ -327,6 +419,8 @@ function schemaBlocks(described, maxDepth, everyField = false) {
       everyField ? described.rawResponse ?? [] : []
     ]
   ];
+}
+function schemaBlocks(sections, maxDepth, everyField = false) {
   const shapes = namedShapes(sections.flatMap(([, fields]) => fields));
   const used = [];
   const comment = (notes) => {
@@ -450,40 +544,63 @@ function schemaLines(described, view) {
       ] : []
     ];
   }
-  if (view.full) return schemaBlocks(described, Infinity, true);
+  if (view.full) {
+    return schemaBlocks(describedSections(described, true), Infinity, true);
+  }
   const raw = described.rawResponse?.length ? [
     "",
     `Other response fields (${described.rawResponse.map((field) => field.name).join(", ")}) are in result.toolResponse.rawV2. --full-schema lists them.`
   ] : [];
-  const full = schemaBlocks(described, Infinity);
-  if (full.length <= SCHEMA_LINE_LIMIT) return [...full, ...raw];
-  const folded = [3, 2].map((depth) => ({ depth, lines: schemaBlocks(described, depth) })).find(({ lines }) => lines.length <= SCHEMA_LINE_LIMIT) ?? {
-    depth: 1,
-    lines: schemaBlocks(described, 1)
-  };
+  const { lines, fullLength } = fitted(describedSections(described, false));
   return [
-    ...folded.lines,
+    ...lines,
     ...raw,
-    "",
-    `This schema is long (${full.length} lines), so deeper objects show only their field names. --full-schema prints every field.`
+    ...fullLength > lines.length ? [
+      "",
+      `This schema is long (${fullLength} lines), so deeper objects show only their field names. --full-schema prints every field.`
+    ] : []
   ];
 }
+function fitted(sections) {
+  const full = schemaBlocks(sections, Infinity);
+  if (full.length <= SCHEMA_LINE_LIMIT) {
+    return { lines: full, fullLength: full.length };
+  }
+  const lines = [3, 2].map((depth) => schemaBlocks(sections, depth)).find((folded) => folded.length <= SCHEMA_LINE_LIMIT) ?? schemaBlocks(sections, 1);
+  return { lines, fullLength: full.length };
+}
+function fieldBlockLines(title, fields) {
+  const { lines, fullLength } = fitted([[title, fields]]);
+  return { lines: lines.slice(1), folded: fullLength > lines.length };
+}
 function safeIdentifier(name) {
   return name.replace(/[^a-zA-Z0-9_$]+/g, "_").replace(/^[^a-zA-Z_$]+/, "") || "value";
 }
 function examples(described, options) {
   const { runner } = described;
+  if (runner.via === "monitor") return { cli: runner.deploy, play: null };
   const required = described.inputs.filter((field) => field.required);
   const shown = options.verbose ? described.inputs : required.length ? required : described.inputs.slice(0, 1);
-  const inputSchema = runner.via === "tool" && runner.inputSchema !== void 0 ? withoutRefs(runner.inputSchema, runner.inputSchema) : void 0;
-  const input = JSON.stringify(
-    Object.fromEntries(
-      shown.map((field) => [
-        field.name,
-        exampleValue(field, propertySchema(inputSchema, field.name))
-      ])
-    )
-  );
+  const inputSchema = runner.inputSchema;
+  let input;
+  try {
+    input = JSON.stringify(
+      Object.fromEntries(
+        shown.map((field) => [
+          field.name,
+          exampleValue(
+            field,
+            propertySchema(inputSchema, field.name),
+            inputSchema
+          )
+        ])
+      )
+    );
+  } catch (error) {
+    if (!(error instanceof InputFileExampleRequired)) throw error;
+  }
+  const inputArgument = input === void 0 ? "--input-file input.json" : `--input ${shellQuote(input)}`;
+  const inputExpression = input ?? "input";
   const read = options.verbose ? described.outputs : described.outputs.filter((field) => !field.secondary).slice(0, 1);
   const reads = (expression) => read.flatMap((field) => {
     const source = expression(field);
@@ -491,7 +608,7 @@ function examples(described, options) {
   });
   const playFunction = (body, returned) => [
     "import deepline from 'deepline';",
-    "export default async function () {",
+    input === void 0 ? "export default async function (input: Record<string, unknown>) {" : "export default async function () {",
     ...[...body, `return { ${returned.join(", ")} };`].map(
       (line) => `  ${line}`
     ),
@@ -500,18 +617,17 @@ function examples(described, options) {
   const returnedNames = (expression) => read.flatMap(
     (field) => expression(field) ? [safeIdentifier(field.name)] : []
   );
-  if (runner.via === "monitor") return { cli: runner.deploy, play: null };
   if (runner.via === "tool") {
     const readNames = returnedNames((field) => field.read);
     return {
-      cli: `deepline tools execute ${runner.toolId} --input ${shellQuote(input)}`,
+      cli: `deepline run ${runner.toolId} ${inputArgument}`,
       play: playFunction(
         [
           "const result = await deepline.tools.execute({",
           "  staleAfterSeconds: 0,",
           `  id: '${safeIdentifier(runner.toolId)}',`,
           `  tool: '${runner.toolId}',`,
-          `  input: ${input},`,
+          `  input: ${inputExpression},`,
           `  description: ${JSON.stringify(described.displayName ?? runner.toolId)},`,
           "});",
           ...reads((field) => field.read)
@@ -521,10 +637,10 @@ function examples(described, options) {
     };
   }
   return {
-    cli: runner.cli ?? `deepline plays run ${runner.reference} --input ${shellQuote(input)}`,
+    cli: `deepline run ${runner.reference} ${inputArgument}`,
     play: playFunction(
       [
-        `const output = await deepline.runPlay('${safeIdentifier(runner.reference.replace(/^.*\//, ""))}', '${runner.reference}', ${input});`,
+        `const output = await deepline.runPlay('${safeIdentifier(runner.reference.replace(/^.*\//, ""))}', '${runner.reference}', ${inputExpression});`,
         ...reads((field) => `output.${field.name}`)
       ],
       read.length ? returnedNames((field) => field.name) : ["output"]
@@ -714,7 +830,7 @@ function describedPlay(play) {
     ...play.displayName && play.displayName !== play.name ? { displayName: play.displayName } : {},
     ...play.description ? { description: play.description } : {},
     ...play.observedCost ? { cost: play.observedCost.displayText } : {},
-    guidance: [],
+    guidance: play.guidance ? [play.guidance] : [],
     inputs: schemaFields(play.inputSchema),
     outputs: schemaFields(play.outputSchema),
     ...rowInputs.length ? { rowInputs } : {},
@@ -723,12 +839,7 @@ function describedPlay(play) {
       rowOutputs,
       rowOutputsAddToSource: Object.keys(added).length > 0 || rowOutput.preservesSourceColumns === true
     } : {},
-    runner: {
-      via: "play",
-      reference,
-      // A CSV play's run command is built by the server around its columns.
-      ...play.csvInput ? { cli: play.runCommand } : {}
-    },
+    runner: { via: "play", reference, inputSchema: play.inputSchema },
     ...starter ? { source: starter.command } : {},
     ...exclusive ? { exclusive } : {},
     // A prebuilt's cost is what its recent runs were charged; there is no rate.
@@ -744,6 +855,7 @@ export {
   rateLimitSummary,
   rateLimitQualifier,
   schemaLines,
+  fieldBlockLines,
   examples,
   describedLines,
   topLevelField,