deepline 0.3.461 → 0.3.463

package/dist/cli/{chunk-Z2XUZC34.js → chunk-IAYSWZDJ.js}

@@ -3,7 +3,7 @@
 var _chunkAID3OYVJjs = require('./chunk-AID3OYVJ.js');
 
 
-var _chunkKXMNM4AQjs = require('./chunk-KXMNM4AQ.js');
+var _chunkNMU3VR5Ujs = require('./chunk-NMU3VR5U.js');
 
 // 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 (_optionalChain([resolvedField, 'access', _2 => _2.fields, 'optionalAccess', _3 => _3.some, 'call', _4 => _4((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(
       (_nullishCoalesce(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("");
@@ -272,7 +364,7 @@ function namedShapes(roots) {
 }
 function withRowInputs(described) {
   const columns = described.rowInputs;
-  if (!_optionalChain([columns, 'optionalAccess', _2 => _2.length])) return described.inputs;
+  if (!_optionalChain([columns, 'optionalAccess', _5 => _5.length])) return described.inputs;
   const join = (...notes) => notes.filter(Boolean).join(" - ");
   const first = columns[0].name;
   return described.inputs.map((field) => {
@@ -307,7 +399,7 @@ function withRowInputs(described) {
 }
 function withRowOutputs(described) {
   const columns = described.rowOutputs;
-  if (!_optionalChain([columns, 'optionalAccess', _3 => _3.length])) return described.outputs;
+  if (!_optionalChain([columns, 'optionalAccess', _6 => _6.length])) return described.outputs;
   const typed = (field) => ({
     ...field,
     type: `PlayDataset<${SHAPE}>`,
@@ -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 ? _nullishCoalesce(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);
-  const raw = _optionalChain([described, 'access', _4 => _4.rawResponse, 'optionalAccess', _5 => _5.length]) ? [
+  if (view.full) {
+    return schemaBlocks(describedSections(described, true), Infinity, true);
+  }
+  const raw = _optionalChain([described, 'access', _7 => _7.rawResponse, 'optionalAccess', _8 => _8.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 = _nullishCoalesce([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 = _nullishCoalesce([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 ${_chunkAID3OYVJjs.shellQuote.call(void 0, input)}`;
+  const inputExpression = _nullishCoalesce(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 ${_chunkAID3OYVJjs.shellQuote.call(void 0, 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(_nullishCoalesce(described.displayName, () => ( runner.toolId)))},`,
           "});",
           ...reads((field) => field.read)
@@ -521,10 +637,10 @@ function examples(described, options) {
     };
   }
   return {
-    cli: _nullishCoalesce(runner.cli, () => ( `deepline plays run ${runner.reference} --input ${_chunkAID3OYVJjs.shellQuote.call(void 0, 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"]
@@ -601,15 +717,15 @@ function jsonFields(fields, options) {
       return [
         field.name,
         {
-          type: field.type.replace(SHAPE, _nullishCoalesce(_optionalChain([shape, 'optionalAccess', _6 => _6.name]), () => ( "object"))),
+          type: field.type.replace(SHAPE, _nullishCoalesce(_optionalChain([shape, 'optionalAccess', _9 => _9.name]), () => ( "object"))),
           ...options.input ? { required: field.required } : {},
           ...field.means ? { means: field.means } : {},
           ...field.example !== void 0 ? { example: field.example } : {},
-          ...field.description && field.description !== _optionalChain([shape, 'optionalAccess', _7 => _7.description]) ? { description: field.description } : {},
+          ...field.description && field.description !== _optionalChain([shape, 'optionalAccess', _10 => _10.description]) ? { description: field.description } : {},
           ...field.secondary ? { secondary: true } : {},
           ...field.read ? { read: field.read } : {},
           ...field.in ? { in: field.in } : {},
-          ..._optionalChain([field, 'access', _8 => _8.paths, 'optionalAccess', _9 => _9.length]) ? { paths: field.paths } : {},
+          ..._optionalChain([field, 'access', _11 => _11.paths, 'optionalAccess', _12 => _12.length]) ? { paths: field.paths } : {},
           ...field.fields && !shape ? { fields: jsonFields(field.fields, options) } : {}
         }
       ];
@@ -630,7 +746,7 @@ function describedJson(described, view) {
   const used = /* @__PURE__ */ new Set();
   const blocks = Object.fromEntries(
     sections.flatMap(
-      ([key, fields, input]) => _optionalChain([fields, 'optionalAccess', _10 => _10.length]) ? [
+      ([key, fields, input]) => _optionalChain([fields, 'optionalAccess', _13 => _13.length]) ? [
         [
           key,
           jsonFields(fields, {
@@ -664,7 +780,7 @@ function describedJson(described, view) {
     ...described.cost ? { cost: described.cost } : {},
     ...described.rateLimit ? { rateLimit: described.rateLimit } : {},
     ...described.byok ? { byok: described.byok } : {},
-    ..._optionalChain([described, 'access', _11 => _11.features, 'optionalAccess', _12 => _12.length]) ? { features: described.features } : {},
+    ..._optionalChain([described, 'access', _14 => _14.features, 'optionalAccess', _15 => _15.length]) ? { features: described.features } : {},
     ...described.guidance.length ? { guidance: described.guidance } : {},
     ...blocks,
     ...used.size ? { types } : {},
@@ -681,7 +797,7 @@ function buildPlayDashboardUrl(baseUrl, playName) {
 }
 function describedPlay(play) {
   const reference = play.reference || play.name;
-  const starter = _nullishCoalesce(play.cloneEditStarter, () => ( _chunkKXMNM4AQjs.cloneEditStarter.call(void 0, play)));
+  const starter = _nullishCoalesce(play.cloneEditStarter, () => ( _chunkNMU3VR5Ujs.cloneEditStarter.call(void 0, play)));
   const csv = _nullishCoalesce(play.csvInput, () => ( {}));
   const csvField = typeof csv.inputField === "string" ? csv.inputField : "csv";
   const alongside = /* @__PURE__ */ new Set([
@@ -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,16 +839,11 @@ 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.
-    ..._optionalChain([play, 'access', _13 => _13.observedCost, 'optionalAccess', _14 => _14.displayText]) ? { cost: play.observedCost.displayText } : {}
+    ..._optionalChain([play, 'access', _16 => _16.observedCost, 'optionalAccess', _17 => _17.displayText]) ? { cost: play.observedCost.displayText } : {}
   };
 }
 
@@ -750,4 +861,5 @@ function describedPlay(play) {
 
 
 
-exports.byokLines = byokLines; exports.SCHEMA_LINE_LIMIT = SCHEMA_LINE_LIMIT; exports.schemaField = schemaField; exports.schemaFields = schemaFields; exports.rateLimitSummary = rateLimitSummary; exports.rateLimitQualifier = rateLimitQualifier; exports.schemaLines = schemaLines; exports.examples = examples; exports.describedLines = describedLines; exports.topLevelField = topLevelField; exports.describedJson = describedJson; exports.buildPlayDashboardUrl = buildPlayDashboardUrl; exports.describedPlay = describedPlay;
+
+exports.byokLines = byokLines; exports.SCHEMA_LINE_LIMIT = SCHEMA_LINE_LIMIT; exports.schemaField = schemaField; exports.schemaFields = schemaFields; exports.rateLimitSummary = rateLimitSummary; exports.rateLimitQualifier = rateLimitQualifier; exports.schemaLines = schemaLines; exports.fieldBlockLines = fieldBlockLines; exports.examples = examples; exports.describedLines = describedLines; exports.topLevelField = topLevelField; exports.describedJson = describedJson; exports.buildPlayDashboardUrl = buildPlayDashboardUrl; exports.describedPlay = describedPlay;

package/dist/cli/{chunk-FGLKOWSC.mjs → chunk-IKWRUNAP.mjs}

@@ -1,6 +1,6 @@
 import {
   resolveShellSpawn
-} from "./chunk-3BMLICF7.mjs";
+} from "./chunk-UIURR26V.mjs";
 
 // src/cli/npm-script-policy.ts
 import { spawnSync } from "child_process";