deepline 0.3.311 → 0.3.312

package/dist/cli/chunk-76VKBPOC.mjs

@@ -0,0 +1,406 @@
+// 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/${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 = seen.get(key) ?? {
+      fields: field.fields,
+      count: 0,
+      descriptions: /* @__PURE__ */ new Set(),
+      under: field.name
+    };
+    entry.count += 1;
+    entry.descriptions.add(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 = (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:", described.rowInputs ?? []],
+    ["Outputs:", described.outputs],
+    ["Columns added to each row:", described.rowOutputs ?? []],
+    [
+      "Raw response, as declared (read it from result.toolResponse.rawV2; check one real response for its nesting):",
+      everyField ? 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 = 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)
+  };
+  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: 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;
+}
+
+export {
+  SCHEMA_LINE_LIMIT,
+  schemaField,
+  schemaFields,
+  rateLimitSummary,
+  schemaLines,
+  examples,
+  describedLines,
+  topLevelField,
+  addDescribeOptions
+};