deepline 0.3.310 → 0.3.312

package/dist/cli/{chunk-5VVRQY4Y.js → chunk-VJDKV5RU.js}

@@ -1,20 +1,20 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkPNNFR4L5js = require('./chunk-PNNFR4L5.js');
+var _chunkULI6UVV6js = require('./chunk-ULI6UVV6.js');
 
 
-var _chunkRYO6353Ojs = require('./chunk-RYO6353O.js');
+var _chunk6LLJWMYHjs = require('./chunk-6LLJWMYH.js');
 
 
 
-var _chunkQARMMLYEjs = require('./chunk-QARMMLYE.js');
+var _chunkTID5XLTZjs = require('./chunk-TID5XLTZ.js');
 
 // src/cli/search-ref.ts
 var _fs = require('fs');
 var _path = require('path');
 var SEARCH_REF_TTL_MS = 15 * 6e4;
 function lastSearchPath() {
-  return _path.join.call(void 0, _chunkQARMMLYEjs.sdkCliStateDirPath.call(void 0, _chunkQARMMLYEjs.resolveConfig.call(void 0, ).baseUrl), "last-search.json");
+  return _path.join.call(void 0, _chunkTID5XLTZjs.sdkCliStateDirPath.call(void 0, _chunkTID5XLTZjs.resolveConfig.call(void 0, ).baseUrl), "last-search.json");
 }
 function rememberSearchRef(searchRef) {
   try {
@@ -75,14 +75,29 @@ function addSearchOptions(command) {
     "What you are trying to accomplish: input you have -> result you need"
   ).option("--limit <count>", "Maximum ranked results to return (1-50)").option("--offset <count>", "Zero-based ranked result offset").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output instead of the readable default");
 }
+function pointAtDescribe(result) {
+  const old = /`deepline (tools|plays) describe [^`]*`/;
+  const render = result.render;
+  for (const section of _nullishCoalesce(_optionalChain([render, 'optionalAccess', _ => _.sections]), () => ( []))) {
+    if (!_optionalChain([section, 'access', _2 => _2.lines, 'optionalAccess', _3 => _3.some, 'call', _4 => _4((line) => old.test(line))])) continue;
+    section.lines = [
+      "Run `deepline describe <id>` before executing a tool or running a play.",
+      ...section.lines.filter((line) => !old.test(line))
+    ];
+  }
+  const templates = result.commandTemplates;
+  for (const template of Object.values(_nullishCoalesce(templates, () => ( {})))) {
+    if (template.describe) template.describe = "deepline describe <id>";
+  }
+}
 async function runSearch(queryInput, options, types, exclude = []) {
-  const query = _nullishCoalesce(_optionalChain([queryInput, 'optionalAccess', _ => _.trim, 'call', _2 => _2()]), () => ( ""));
+  const query = _nullishCoalesce(_optionalChain([queryInput, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]), () => ( ""));
   const searchTerms = _nullishCoalesce(options.searchTerms, () => ( options.search_terms));
-  if (!query && !_optionalChain([options, 'access', _3 => _3.categories, 'optionalAccess', _4 => _4.trim, 'call', _5 => _5()]) && !_optionalChain([searchTerms, 'optionalAccess', _6 => _6.trim, 'call', _7 => _7()])) {
+  if (!query && !_optionalChain([options, 'access', _7 => _7.categories, 'optionalAccess', _8 => _8.trim, 'call', _9 => _9()]) && !_optionalChain([searchTerms, 'optionalAccess', _10 => _10.trim, 'call', _11 => _11()])) {
     console.error(USAGE);
     return 1;
   }
-  const { search_ref: searchRef, ...result } = await new (0, _chunkPNNFR4L5js.DeeplineClient)().search({
+  const { search_ref: searchRef, ...result } = await new (0, _chunkULI6UVV6js.DeeplineClient)().search({
     query,
     types,
     exclude,
@@ -95,7 +110,8 @@ async function runSearch(queryInput, options, types, exclude = []) {
     includeSearchDebug: Boolean(options.includeSearchDebug)
   });
   if (searchRef) rememberSearchRef(searchRef);
-  _chunkRYO6353Ojs.printCommandEnvelope.call(void 0, result, {
+  pointAtDescribe(result);
+  _chunk6LLJWMYHjs.printCommandEnvelope.call(void 0, result, {
     json: options.json === true
   });
   return 0;
@@ -187,4 +203,8 @@ Examples:
 
 
 
-exports.recentSearchRef = recentSearchRef; exports.registerDeprecatedSearchCommand = registerDeprecatedSearchCommand; exports.registerSearchCommand = registerSearchCommand;
+
+
+
+
+exports.recentSearchRef = recentSearchRef; exports.SEARCH_TYPES = SEARCH_TYPES; exports.parseTypes = parseTypes; exports.appendCsv = appendCsv; exports.pointAtDescribe = pointAtDescribe; exports.registerDeprecatedSearchCommand = registerDeprecatedSearchCommand; exports.registerSearchCommand = registerSearchCommand;

package/dist/cli/{chunk-M4KGWEN2.mjs → chunk-WPTUKXIF.mjs}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-DLIRSHV6.mjs";
 import {
   SDK_RELEASE
-} from "./chunk-VN7Y4LVH.mjs";
+} from "./chunk-AA66YTS7.mjs";
 import {
   DeeplineError,
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,

package/dist/cli/chunk-XNL3SEMC.js

@@ -0,0 +1,406 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/cli/described.ts
+var SHAPE = "{}";
+var SCHEMA_LINE_LIMIT = 100;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var NAMED_EXAMPLES = {
+  email: "ada@example.com",
+  domain: "example.com",
+  website: "example.com",
+  linkedin_url: "https://www.linkedin.com/in/ada-lovelace",
+  first_name: "Ada",
+  last_name: "Lovelace",
+  full_name: "Ada Lovelace"
+};
+function schemaType(schema) {
+  const brackets = (type) => type.includes(" | ") ? `(${type})` : type;
+  if (Array.isArray(schema.enum) && schema.enum.length) {
+    return {
+      type: schema.enum.map((value) => JSON.stringify(value)).join(" | ")
+    };
+  }
+  const alternatives = [schema.anyOf, schema.oneOf].find(Array.isArray);
+  if (alternatives) {
+    const parts = alternatives.map(
+      (option) => schemaType(isRecord(option) ? option : {})
+    );
+    const shaped = parts.find((part) => part.fields);
+    return {
+      type: parts.map(
+        (part) => part === shaped ? part.type : part.type.replace(SHAPE, "object")
+      ).join(" | "),
+      ...shaped ? { fields: shaped.fields } : {}
+    };
+  }
+  const types = [schema.type].flat().filter((type) => typeof type === "string");
+  const nullable = types.includes("null") ? " | null" : "";
+  const fields = fieldsOf(schema);
+  if (fields.length && !types.includes("array")) {
+    return { type: `${SHAPE}${nullable}`, fields };
+  }
+  if (types.includes("array")) {
+    const item = schemaType(isRecord(schema.items) ? schema.items : {});
+    return {
+      type: `${brackets(item.type)}[]${nullable}`,
+      ...item.fields ? { fields: item.fields } : {}
+    };
+  }
+  return {
+    type: types.filter((type) => type !== "null").join(" | ") + nullable || "unknown"
+  };
+}
+function schemaField(name, node, required) {
+  const schema = isRecord(node) ? node : {};
+  const { type, fields } = schemaType(schema);
+  const example = [
+    schema.example,
+    schema.default,
+    Array.isArray(schema.enum) ? schema.enum[0] : void 0,
+    type === "string" ? NAMED_EXAMPLES[name.toLowerCase()] : void 0
+  ].find((value) => value !== void 0);
+  return {
+    name,
+    type,
+    required,
+    ...example !== void 0 ? { example } : {},
+    ...typeof schema.description === "string" && schema.description ? { description: schema.description } : {},
+    ...fields ? { fields } : {}
+  };
+}
+function withoutRefs(node, root, depth = 0) {
+  if (Array.isArray(node)) {
+    return node.map((item) => withoutRefs(item, root, depth));
+  }
+  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;
+  }
+  return Object.fromEntries(
+    Object.entries(rest).map(([key, value]) => [
+      key,
+      key === "$defs" || key === "definitions" ? value : withoutRefs(value, root, depth)
+    ])
+  );
+}
+function schemaFields(schema) {
+  return fieldsOf(withoutRefs(schema, schema));
+}
+function fieldsOf(schema) {
+  if (!isRecord(schema)) return [];
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.map(String) : []
+  );
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const entries = Object.keys(properties).length ? Object.entries(properties) : (Array.isArray(schema.fields) ? schema.fields : []).map((field) => [
+    isRecord(field) ? field.name : "",
+    field
+  ]);
+  return entries.flatMap(
+    ([name, node]) => typeof name === "string" && name ? [
+      schemaField(
+        name,
+        node,
+        isRecord(node) && node.required === true || required.has(name)
+      )
+    ] : []
+  );
+}
+function rateLimitSummary(limits) {
+  const windows = {
+    1e3: "second",
+    6e4: "minute",
+    36e5: "hour",
+    864e5: "day"
+  };
+  const parts = (Array.isArray(limits) ? limits : []).flatMap((limit) => {
+    if (!isRecord(limit)) return [];
+    const { requestsPerWindow: requests, windowMs } = limit;
+    if (typeof requests !== "number" || typeof windowMs !== "number") return [];
+    return [
+      `${requests} requests/${_nullishCoalesce(windows[windowMs], () => ( `${windowMs / 1e3}s`))}`
+    ];
+  });
+  return parts.length ? parts.join(", ") : void 0;
+}
+function exampleValue(field) {
+  if (field.example !== void 0) return field.example;
+  const type = field.type.toLowerCase();
+  if (type.includes("[]")) return [];
+  if (type.startsWith(SHAPE) || type.startsWith("object")) return {};
+  if (type.startsWith("integer") || type.startsWith("number")) return 1;
+  if (type.startsWith("boolean")) return true;
+  return "...";
+}
+function shapeKey(fields) {
+  return JSON.stringify(
+    fields.map((field) => [
+      field.name,
+      field.required,
+      field.type,
+      field.fields ? shapeKey(field.fields) : null
+    ])
+  );
+}
+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("");
+}
+function namedShapes(roots) {
+  const seen = /* @__PURE__ */ new Map();
+  const visit = (field) => {
+    if (!field.fields) return;
+    const key = shapeKey(field.fields);
+    const entry = _nullishCoalesce(seen.get(key), () => ( {
+      fields: field.fields,
+      count: 0,
+      descriptions: /* @__PURE__ */ new Set(),
+      under: field.name
+    }));
+    entry.count += 1;
+    entry.descriptions.add(_nullishCoalesce(field.description, () => ( "")));
+    seen.set(key, entry);
+    field.fields.forEach(visit);
+  };
+  roots.forEach(visit);
+  const taken = /* @__PURE__ */ new Set();
+  const named = /* @__PURE__ */ new Map();
+  for (const [key, entry] of seen) {
+    if (entry.count < 2) continue;
+    const [description] = entry.descriptions.size === 1 ? [...entry.descriptions] : [""];
+    const title = (_nullishCoalesce(description, () => ( ""))).split(/[.:]/)[0].trim();
+    const base = pascalCase(
+      title && title.split(/\s+/).length <= 3 ? title : entry.fields.length <= 3 ? entry.fields.map((field) => field.name).join(" ") : entry.under
+    ) || "Shape";
+    let name = base;
+    for (let n = 2; taken.has(name); n += 1) name = `${base}${n}`;
+    taken.add(name);
+    named.set(key, {
+      name,
+      fields: entry.fields,
+      ...description ? { description } : {}
+    });
+  }
+  return named;
+}
+function schemaBlocks(described, maxDepth, everyField = false) {
+  const sections = [
+    ["Inputs:", described.inputs],
+    ["CSV columns read from each row:", _nullishCoalesce(described.rowInputs, () => ( []))],
+    ["Outputs:", described.outputs],
+    ["Columns added to each row:", _nullishCoalesce(described.rowOutputs, () => ( []))],
+    [
+      "Raw response, as declared (read it from result.toolResponse.rawV2; check one real response for its nesting):",
+      everyField ? _nullishCoalesce(described.rawResponse, () => ( [])) : []
+    ]
+  ];
+  const shapes = namedShapes(sections.flatMap(([, fields]) => fields));
+  const used = [];
+  const comment = (notes) => {
+    const shown = notes.filter(Boolean);
+    return shown.length ? `  // ${shown.join(" - ")}` : "";
+  };
+  const fieldLines = (field, indent, depth) => {
+    const example = field.example === void 0 ? void 0 : JSON.stringify(field.example);
+    const start = `${indent}${JSON.stringify(field.name)}${field.required ? "" : "?"}: `;
+    if (!field.fields) {
+      return [`${start}${field.type},${comment([example, field.description])}`];
+    }
+    const [before, after] = field.type.split(SHAPE);
+    const shape = shapes.get(shapeKey(field.fields));
+    if (shape) {
+      if (!used.includes(shape)) used.push(shape);
+      const own = field.description === shape.description ? void 0 : field.description;
+      return [`${start}${before}${shape.name}${after},${comment([own])}`];
+    }
+    if (depth >= maxDepth || field.summarized && !everyField) {
+      const names = field.fields.map((child) => child.name).join(", ");
+      return [
+        `${start}${before}{ ${names} }${after},${comment([field.description])}`
+      ];
+    }
+    return [
+      `${start}${before}{${comment([field.description])}`,
+      ...field.fields.flatMap(
+        (child) => fieldLines(child, `${indent}  `, depth + 1)
+      ),
+      `${indent}}${after},`
+    ];
+  };
+  const block = (title, fields) => fields.length ? [
+    "",
+    title,
+    "{",
+    ...fields.flatMap((field) => fieldLines(field, "  ", 1)),
+    "}"
+  ] : [];
+  const lines = sections.flatMap(([title, fields]) => block(title, fields));
+  const types = [];
+  for (let index = 0; index < used.length; index += 1) {
+    const shape = used[index];
+    types.push(
+      `  ${shape.name} = {${comment([shape.description])}`,
+      ...shape.fields.flatMap((field) => fieldLines(field, "    ", 1)),
+      "  }"
+    );
+  }
+  return [...lines, ...types.length ? ["", "Types:", ...types] : []];
+}
+function schemaLines(described, options) {
+  if (options.full) return schemaBlocks(described, Infinity, true);
+  const raw = _optionalChain([described, 'access', _ => _.rawResponse, 'optionalAccess', _2 => _2.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)
+  }));
+  return [
+    ...folded.lines,
+    ...raw,
+    "",
+    `This schema is long (${full.length} lines), so deeper objects show only their field names. --full-schema prints every field.`
+  ];
+}
+function safeIdentifier(name) {
+  return name.replace(/[^a-zA-Z0-9_$]+/g, "_").replace(/^[^a-zA-Z_$]+/, "") || "value";
+}
+function examples(described, options) {
+  const { runner } = described;
+  const required = described.inputs.filter((field) => field.required);
+  const shown = options.verbose ? described.inputs : required.length ? required : described.inputs.slice(0, 1);
+  const input = JSON.stringify(
+    Object.fromEntries(shown.map((field) => [field.name, exampleValue(field)]))
+  );
+  const read = options.verbose ? described.outputs : described.outputs.slice(0, 1);
+  const reads = (expression) => read.flatMap((field) => {
+    const source = expression(field);
+    return source ? [`const ${safeIdentifier(field.name)} = ${source};`] : [];
+  });
+  if (runner.via === "monitor") return { cli: runner.deploy, play: null };
+  if (runner.via === "tool") {
+    return {
+      cli: `deepline tools execute ${runner.toolId} --input '${input}'`,
+      play: [
+        "const result = await ctx.tools.execute({",
+        `  id: '${safeIdentifier(runner.toolId)}',`,
+        `  tool: '${runner.toolId}',`,
+        `  input: ${input},`,
+        "});",
+        ...reads((field) => field.read)
+      ].join("\n")
+    };
+  }
+  return {
+    cli: _nullishCoalesce(runner.cli, () => ( `deepline plays run ${runner.reference} --input '${input}'`)),
+    play: [
+      `const output = await ctx.runPlay('${safeIdentifier(runner.reference.replace(/^.*\//, ""))}', '${runner.reference}', ${input});`,
+      ...reads((field) => `output.${field.name}`)
+    ].join("\n")
+  };
+}
+var EXPLANATIONS = {
+  tool: {
+    cli: "--input takes a JSON object or @file.json. The result prints when the call finishes; add --json for the full result payload.",
+    play: "id names the step and must stay stable. Read a declared output with its getter; every other provider field is in result.toolResponse.rawV2."
+  },
+  play: {
+    cli: "--input takes a JSON object or @file.json. The run waits and prints its output; add --json for the full result, or read it later with deepline runs get <run-id> --json.",
+    play: "The first argument is a stable key for the child run. The call waits and returns the output object."
+  },
+  monitor: {
+    cli: "A monitor type is deployed, not executed. Its inputs are the filters in the payload, and its events stream into your warehouse.",
+    play: ""
+  }
+};
+function describedLines(described, view) {
+  const { cli, play } = examples(described, view);
+  const explanation = EXPLANATIONS[described.runner.via];
+  const indented = (text) => text.split("\n").map((line) => `  ${line}`);
+  const section = (lines) => lines.length ? ["", ...lines] : [];
+  return [
+    `${described.id} [${described.kind.replace("_", " ")}]`,
+    ...described.displayName ? [described.displayName] : [],
+    ...described.description ? [described.description] : [],
+    ...described.cost ? [`Cost: ${described.cost}`] : [],
+    ...described.guidance.map((line) => `Guidance: ${line}`),
+    ...described.rateLimit ? [`Rate limit: ${described.rateLimit}`] : [],
+    ...schemaLines(described, { full: view.fullSchema }),
+    ...section(
+      view.cli ? [
+        "Run from the CLI:",
+        ...indented(cli),
+        ...view.explain ? indented(explanation.cli) : []
+      ] : []
+    ),
+    ...section(
+      view.play && play ? [
+        "Run in a play:",
+        ...indented(play),
+        ...view.explain ? indented(explanation.play) : []
+      ] : []
+    ),
+    ...section(described.source ? [`Source: ${described.source}`] : []),
+    "",
+    "For more detail or examples, see deepline describe --help."
+  ];
+}
+function topLevelField({ fields: _fields, ...field }) {
+  return { ...field, type: field.type.replace(SHAPE, "object") };
+}
+
+// src/cli/describe-options.ts
+function addDescribeOptions(command, options = {}) {
+  command.option(
+    "--prebuilt",
+    "Show the Deepline tool or play, not a play your workspace created under the same name"
+  ).option("--tool", "Same as --prebuilt").option(
+    "--verbose",
+    "Examples fill in every input and read every output, not only required ones"
+  ).option(
+    "--cli-example",
+    "Show only the CLI example, and explain how it takes inputs and returns outputs"
+  ).option(
+    "--play-example",
+    "Show only the in-play example, and explain how it takes inputs and returns outputs"
+  ).option("--no-example", "Hide the run examples").option(
+    "--full-schema",
+    `Print every field: a long schema unfolded (over ${SCHEMA_LINE_LIMIT} lines), list rows, and a tool's raw response`
+  ).option(
+    "-o, --out <path>",
+    "Save the output to this file instead of printing it"
+  );
+  if (options.schemaOnly !== false) {
+    command.option(
+      "--schema-only",
+      "Print only the schema, with every field, and nothing else"
+    );
+  }
+  if (options.json !== false) {
+    command.option(
+      "--json",
+      "Print JSON instead of text; with --schema-only, only the input and output JSON Schemas"
+    );
+  }
+  return command;
+}
+
+
+
+
+
+
+
+
+
+
+
+exports.SCHEMA_LINE_LIMIT = SCHEMA_LINE_LIMIT; exports.schemaField = schemaField; exports.schemaFields = schemaFields; exports.rateLimitSummary = rateLimitSummary; exports.schemaLines = schemaLines; exports.examples = examples; exports.describedLines = describedLines; exports.topLevelField = topLevelField; exports.addDescribeOptions = addDescribeOptions;