deepline 0.3.395 → 0.3.397

package/dist/cli/{db-7AP4P52N.js → db-JPUYC5RB.js}

@@ -4,10 +4,10 @@ var _chunkAID3OYVJjs = require('./chunk-AID3OYVJ.js');
 
 
 
-var _chunk36ML3YKAjs = require('./chunk-36ML3YKA.js');
+var _chunkUVXBVUZQjs = require('./chunk-UVXBVUZQ.js');
 require('./chunk-S6R3OX7B.js');
 require('./chunk-UHNDVD3P.js');
-require('./chunk-DRM3CMHL.js');
+require('./chunk-KXMNM4AQ.js');
 require('./chunk-XDVT3GOM.js');
 
 
@@ -18,15 +18,16 @@ require('./chunk-XDVT3GOM.js');
 
 
 
-var _chunkHRWUQJ4Kjs = require('./chunk-HRWUQJ4K.js');
+var _chunkDQ65ZVHNjs = require('./chunk-DQ65ZVHN.js');
+require('./chunk-RYW4HPSM.js');
 
 
-var _chunk56IFFVIBjs = require('./chunk-56IFFVIB.js');
+var _chunkQ2E4E4FJjs = require('./chunk-Q2E4E4FJ.js');
 require('./chunk-XNYIZMNQ.js');
 
 
 var _chunk7P5AA3SNjs = require('./chunk-7P5AA3SN.js');
-require('./chunk-TO2MWPGR.js');
+require('./chunk-IZ74ABSX.js');
 require('./chunk-OG64RBAC.js');
 require('./chunk-COGTRVWW.js');
 
@@ -49,8 +50,8 @@ function formatCell(value) {
   return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
 function tableLines(result) {
-  const rows = _chunkHRWUQJ4Kjs.dataExportRows.call(void 0, customerDbRows(result));
-  const responseColumns = _chunkHRWUQJ4Kjs.dataExportColumns.call(void 0, 
+  const rows = _chunkDQ65ZVHNjs.dataExportRows.call(void 0, customerDbRows(result));
+  const responseColumns = _chunkDQ65ZVHNjs.dataExportColumns.call(void 0, 
     rows,
     customerDbColumnNames(result)
   );
@@ -96,7 +97,7 @@ function tableLines(result) {
   return lines;
 }
 function customerDbRows(result) {
-  return _chunkHRWUQJ4Kjs.recordRows.call(void 0, result.rows);
+  return _chunkDQ65ZVHNjs.recordRows.call(void 0, result.rows);
 }
 function customerDbColumnNames(result) {
   return result.columns.map((column) => column.name).filter(Boolean);
@@ -118,15 +119,15 @@ function collectErrorText(value) {
   ].filter(Boolean).join("\n");
 }
 function formatDbQueryError(sql, error) {
-  const text = error instanceof _chunk56IFFVIBjs.CustomerDbQueryOutcomeUnknownError ? collectErrorText(error.cause) : collectErrorText(error);
+  const text = error instanceof _chunkQ2E4E4FJjs.CustomerDbQueryOutcomeUnknownError ? collectErrorText(error.cause) : collectErrorText(error);
   const lower = text.toLowerCase();
   const referencesStorage = /"storage"\.|storage\./i.test(sql);
   const runIdColumnMissing = /column\s+"?run_id"?\s+does not exist/i.test(text) || /run_id.*does not exist/i.test(lower);
   const relationMissing = /relation\s+["']?[^"']*storage[^"']*["']?\s+does not exist/i.test(text) || /42p01/i.test(text);
   if (referencesStorage && relationMissing) {
     return [
-      ...error instanceof _chunk56IFFVIBjs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
-      error instanceof _chunk56IFFVIBjs.CustomerDbQueryOutcomeUnknownError ? "The server reported that the referenced storage table does not exist." : "Customer DB query failed: the referenced storage table does not exist.",
+      ...error instanceof _chunkQ2E4E4FJjs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
+      error instanceof _chunkQ2E4E4FJjs.CustomerDbQueryOutcomeUnknownError ? "The server reported that the referenced storage table does not exist." : "Customer DB query failed: the referenced storage table does not exist.",
       "Play dataset tables are created only when the corresponding ctx.dataset(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the dataset do not create that table.",
       "Use `deepline runs get <run-id> --full` to inspect returned dataset handles, then export them with `deepline runs export <run-id> --dataset result.rows --out rows.csv`.",
       `Original error: ${errorMessage(error)}`
@@ -134,7 +135,7 @@ function formatDbQueryError(sql, error) {
   }
   if (referencesStorage && runIdColumnMissing) {
     return [
-      ...error instanceof _chunk56IFFVIBjs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
+      ...error instanceof _chunkQ2E4E4FJjs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
       "Customer DB query failed: storage dataset tables use `_run_id`, not `run_id`.",
       "Prefer `deepline runs export <run-id> --dataset result.rows --out rows.csv` unless you are doing deep table debugging.",
       `Original error: ${errorMessage(error)}`
@@ -149,7 +150,7 @@ function writeCustomerDbCsv(result, outPath) {
   const resolved = _path.resolve.call(void 0, outPath);
   _fs.writeFileSync.call(void 0, 
     resolved,
-    _chunkHRWUQJ4Kjs.dataExportCsvString.call(void 0, customerDbRows(result), customerDbColumnNames(result)),
+    _chunkDQ65ZVHNjs.dataExportCsvString.call(void 0, customerDbRows(result), customerDbColumnNames(result)),
     "utf-8"
   );
   return resolved;
@@ -190,7 +191,7 @@ function dbQueryExportEnvelope(input) {
 function renderDbQueryResult(result, query, options) {
   const { sql, maxRows, operationKey } = query;
   const { format, out: outPath, json: explicitJsonOutput = false } = options;
-  const jsonOutput = explicitJsonOutput || _chunkHRWUQJ4Kjs.shouldEmitJson.call(void 0, );
+  const jsonOutput = explicitJsonOutput || _chunkDQ65ZVHNjs.shouldEmitJson.call(void 0, );
   const toolPayload = JSON.stringify({
     sql,
     result_mode: "rows",
@@ -201,7 +202,7 @@ function renderDbQueryResult(result, query, options) {
   if (format === "csv") {
     if (outPath) {
       const exportedPath = writeCustomerDbCsv(result, outPath);
-      _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+      _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
         dbQueryExportEnvelope({
           result,
           format,
@@ -217,7 +218,7 @@ function renderDbQueryResult(result, query, options) {
       );
       return;
     }
-    _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+    _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
       dbQueryExportEnvelope({
         result,
         format,
@@ -227,7 +228,7 @@ function renderDbQueryResult(result, query, options) {
       }),
       {
         json: explicitJsonOutput,
-        text: _chunkHRWUQJ4Kjs.dataExportCsvString.call(void 0, 
+        text: _chunkDQ65ZVHNjs.dataExportCsvString.call(void 0, 
           customerDbRows(result),
           customerDbColumnNames(result)
         )
@@ -236,14 +237,14 @@ function renderDbQueryResult(result, query, options) {
     return;
   }
   if (format === "markdown") {
-    const content = _chunkHRWUQJ4Kjs.markdownTableFromRows.call(void 0, 
+    const content = _chunkDQ65ZVHNjs.markdownTableFromRows.call(void 0, 
       customerDbRows(result),
       customerDbColumnNames(result)
     );
     if (outPath) {
       const exportedPath = _path.resolve.call(void 0, outPath);
       _fs.writeFileSync.call(void 0, exportedPath, content, "utf-8");
-      _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+      _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
         dbQueryExportEnvelope({
           result,
           format,
@@ -259,7 +260,7 @@ function renderDbQueryResult(result, query, options) {
       );
       return;
     }
-    _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+    _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
       dbQueryExportEnvelope({
         result,
         format,
@@ -274,7 +275,7 @@ function renderDbQueryResult(result, query, options) {
     );
     return;
   }
-  _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+  _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
     {
       ...result,
       next: {
@@ -348,9 +349,9 @@ async function runDbQueryCommand(options) {
       ...maxRows === void 0 ? {} : { maxRows },
       ...operationKey === void 0 ? {} : { operationKey }
     };
-    const plan = _chunk36ML3YKAjs.planCustomerDbQuery.call(void 0, query);
+    const plan = _chunkUVXBVUZQjs.planCustomerDbQuery.call(void 0, query);
     if (options.dryRun) {
-      _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+      _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
         {
           dryRun: true,
           ...plan,
@@ -363,11 +364,11 @@ async function runDbQueryCommand(options) {
             ...out === void 0 ? {} : { file: _path.resolve.call(void 0, out) }
           }
         },
-        { json: options.json || _chunkHRWUQJ4Kjs.shouldEmitJson.call(void 0, ) }
+        { json: options.json || _chunkDQ65ZVHNjs.shouldEmitJson.call(void 0, ) }
       );
       return 0;
     }
-    const client = new (0, _chunk36ML3YKAjs.DeeplineClient)();
+    const client = new (0, _chunkUVXBVUZQjs.DeeplineClient)();
     const result = await client.db.query(query);
     renderDbQueryResult(result, query, {
       format,
@@ -376,8 +377,8 @@ async function runDbQueryCommand(options) {
     });
     return 0;
   } catch (error) {
-    if (error instanceof _chunk56IFFVIBjs.CustomerDbQueryOutcomeUnknownError && (options.json || _chunkHRWUQJ4Kjs.shouldEmitJson.call(void 0, ))) {
-      _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+    if (error instanceof _chunkQ2E4E4FJjs.CustomerDbQueryOutcomeUnknownError && (options.json || _chunkDQ65ZVHNjs.shouldEmitJson.call(void 0, ))) {
+      _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
         {
           ok: false,
           error: {
@@ -425,8 +426,8 @@ function dbRepairPlainText(result) {
 async function handleDbRepair(args) {
   const providerIndex = args.indexOf("--provider");
   const provider = providerIndex >= 0 ? _optionalChain([args, 'access', _9 => _9[providerIndex + 1], 'optionalAccess', _10 => _10.trim, 'call', _11 => _11()]) : void 0;
-  const jsonOutput = _chunkHRWUQJ4Kjs.argsWantJson.call(void 0, args);
-  const client = new (0, _chunk36ML3YKAjs.DeeplineClient)();
+  const jsonOutput = _chunkDQ65ZVHNjs.argsWantJson.call(void 0, args);
+  const client = new (0, _chunkUVXBVUZQjs.DeeplineClient)();
   let result;
   try {
     result = await client.repairIngestionStorage(
@@ -442,7 +443,7 @@ async function handleDbRepair(args) {
     console.error(errorMessage2(error));
     return 1;
   }
-  _chunkHRWUQJ4Kjs.printCommandEnvelope.call(void 0, 
+  _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
     {
       command: "db repair",
       status: result.status,

package/dist/cli/{db-7QLNI3Q4.mjs → db-L5IEI2AU.mjs}

@@ -4,10 +4,10 @@ import {
 import {
   DeeplineClient,
   planCustomerDbQuery
-} from "./chunk-G4IWGRMK.mjs";
+} from "./chunk-J7ABTQQ7.mjs";
 import "./chunk-6IKARAYD.mjs";
 import "./chunk-JI2B4RZP.mjs";
-import "./chunk-5VCZ3WRH.mjs";
+import "./chunk-EIMG75BT.mjs";
 import "./chunk-UBKA33KY.mjs";
 import {
   argsWantJson,
@@ -18,15 +18,16 @@ import {
   printCommandEnvelope,
   recordRows,
   shouldEmitJson
-} from "./chunk-47M6HPGP.mjs";
+} from "./chunk-RNSWDKBM.mjs";
+import "./chunk-2LDADJNO.mjs";
 import {
   CustomerDbQueryOutcomeUnknownError
-} from "./chunk-6D7A2FSL.mjs";
+} from "./chunk-YHPYUZZX.mjs";
 import "./chunk-DLIRSHV6.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";
-import "./chunk-BON3DRC6.mjs";
+import "./chunk-MRXMMERY.mjs";
 import "./chunk-WZYKRD7T.mjs";
 import "./chunk-KRD6H754.mjs";
 

package/dist/cli/describe-6WT74AOR.js

@@ -0,0 +1,164 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+var _chunkK33MXVXQjs = require('./chunk-K33MXVXQ.js');
+
+
+var _chunkZAAKSJASjs = require('./chunk-ZAAKSJAS.js');
+require('./chunk-PSGEDGLT.js');
+
+
+
+var _chunkRFG3MRACjs = require('./chunk-RFG3MRAC.js');
+require('./chunk-7DRPTGCK.js');
+
+
+var _chunkBQR6UN3Cjs = require('./chunk-BQR6UN3C.js');
+require('./chunk-AID3OYVJ.js');
+require('./chunk-ZM2YPJQJ.js');
+require('./chunk-HGFFYVXN.js');
+require('./chunk-NA4T3B62.js');
+require('./chunk-KB4SDX5S.js');
+
+
+var _chunkUVXBVUZQjs = require('./chunk-UVXBVUZQ.js');
+require('./chunk-S6R3OX7B.js');
+require('./chunk-UHNDVD3P.js');
+require('./chunk-KXMNM4AQ.js');
+require('./chunk-XDVT3GOM.js');
+require('./chunk-QJBJZVG6.js');
+
+
+var _chunkDQ65ZVHNjs = require('./chunk-DQ65ZVHN.js');
+require('./chunk-RYW4HPSM.js');
+require('./chunk-Q2E4E4FJ.js');
+require('./chunk-XNYIZMNQ.js');
+require('./chunk-7P5AA3SN.js');
+require('./chunk-IZ74ABSX.js');
+require('./chunk-OG64RBAC.js');
+require('./chunk-COGTRVWW.js');
+
+// src/cli/commands/describe.ts
+var _fs = require('fs');
+var _path = require('path');
+async function describeAnything(name, options, onMissing) {
+  const client = new (0, _chunkUVXBVUZQjs.DeeplineClient)();
+  const lookups = _chunkRFG3MRACjs.describeLookupsFor.call(void 0, client);
+  const outcome = await _chunkRFG3MRACjs.describeName.call(void 0, name, options, {
+    ...lookups,
+    // `tools describe` has already fetched the tool for its compatibility check.
+    tool: async (toolName) => _nullishCoalesce(options.fetchedTool, () => ( lookups.tool(toolName))),
+    seedStarterScript: _chunkK33MXVXQjs.seedToolListScript
+  });
+  if (outcome.status === "missing") {
+    if (onMissing) return onMissing();
+    console.error(
+      `Nothing named "${name}". Search for it: deepline search ${JSON.stringify(name.replace(/[-_./]+/g, " "))}`
+    );
+    return 2;
+  }
+  if (outcome.status === "refused") {
+    console.error(outcome.message);
+    return outcome.exitCode;
+  }
+  return deliver(outcome.envelope, outcome.lines, {
+    json: options.json === true,
+    out: options.out
+  });
+}
+function deliver(envelope, lines, { json, out }) {
+  const text = `${lines.join("\n")}
+`;
+  if (out) {
+    const path = _path.resolve.call(void 0, out);
+    const content = json ? `${JSON.stringify(envelope, null, 2)}
+` : text;
+    _fs.writeFileSync.call(void 0, path, content);
+    const bytes = Buffer.byteLength(content);
+    _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, 
+      { path, bytes },
+      { json, text: `Wrote ${path} (${bytes} bytes)
+` }
+    );
+    return 0;
+  }
+  _chunkDQ65ZVHNjs.printCommandEnvelope.call(void 0, envelope, { json, text });
+  return 0;
+}
+function registerDescribeCommand(program) {
+  _chunkZAAKSJASjs.addDescribeOptions.call(void 0, program.command("describe <name>")).option("--web-url", "Print only a play's play page URL").description(
+    "Describe anything search returns: a tool, monitor type, or play."
+  ).addHelpText(
+    "after",
+    `
+What you can describe:
+  Any id deepline search returns: a tool id, a monitor type id, or a play name
+  or reference. You do not say which kind it is; tool ids, monitor type ids
+  and prebuilt play names never overlap.
+
+When a name is taken twice:
+  A play your workspace created is shown instead of a Deepline tool, monitor
+  type or prebuilt play with the same name, and the output says so.
+  Pass --prebuilt (or --tool) to see the Deepline one.
+
+What it prints:
+  The same sections for every kind: what it is, cost, inputs, outputs, then
+  an example of running it from the CLI and from inside a play.
+
+Examples in the output:
+  (default)        required inputs filled in, first output read
+  --verbose        every input filled in, every output read; also shows
+                   secondary fields
+  --cli-example    only the CLI example, with how inputs and outputs work
+  --play-example   only the in-play example, with how inputs and outputs work
+  --no-example     no examples
+
+Features:
+  A tool lists its features: parts with their own description, such as the
+  model an AI tool runs. --feature <name> describes one at its default value,
+  --feature <name>=<value> at another, e.g. --feature model=openai/gpt-5.6-luna.
+
+Schema size and format:
+  Secondary fields (diagnostics, attempt logs, echoes of input) are left out
+  by default; the output names them, and --verbose shows them.
+  --fields email,miss_reason shows only the fields you name, plus every
+  required input, and names the rest. Use it when you know what you need.
+  A schema over ${_chunkBQR6UN3Cjs.SCHEMA_LINE_LIMIT} lines is folded: deeper objects show only their field
+  names. A shape used more than once is printed once under Types.
+  --full-schema    the normal output, with the schema not folded
+  --schema-only    only the schema, not folded, and nothing else
+  --json           the same facts as JSON: fields keyed by name, with what
+                   each means and, for a tool, where it is in the result;
+                   secondary fields are named in "hidden"
+  --json --full-schema  the whole catalog record, as tools describe and
+                   plays describe print it
+  --schema-only --json
+                   only the input and output JSON Schemas; use this for a
+                   program, or for a schema too large to read
+  --out <path>     save any of the above to a file instead of printing it
+
+Play page:
+  For a play, the output ends with its play page URL (JSON: dashboardUrl).
+  --web-url        print only that URL; with --json, {"dashboardUrl": ...}.
+                   Fails for a tool or monitor type, which have no play page.
+
+Older commands:
+  deepline tools describe and deepline plays describe are this command limited
+  to one kind. Their own flags still work: --pricing-only, --examples-only,
+  --model and --estimate-payload on tools; --json <fields> on plays.
+
+Examples:
+  deepline describe hunter_email_verifier
+  deepline describe person-linkedin-to-email
+  deepline describe my-play --prebuilt
+  deepline describe ai_ark_people_search --full-schema
+  deepline describe prebuilt/person-to-email-batch --web-url
+  deepline describe ai_ark_people_search --schema-only --out schema.json
+`
+  ).action(async (name, options) => {
+    process.exitCode = await describeAnything(name, options);
+  });
+}
+
+
+
+exports.describeAnything = describeAnything; exports.registerDescribeCommand = registerDescribeCommand;

package/dist/cli/describe-S6BFANVI.mjs

@@ -0,0 +1,164 @@
+import {
+  seedToolListScript
+} from "./chunk-F3BUFYKE.mjs";
+import {
+  addDescribeOptions
+} from "./chunk-OSDXE27V.mjs";
+import "./chunk-4D745XZO.mjs";
+import {
+  describeLookupsFor,
+  describeName
+} from "./chunk-HFYQBC2D.mjs";
+import "./chunk-YHZUZO3U.mjs";
+import {
+  SCHEMA_LINE_LIMIT
+} from "./chunk-IHG7UAHD.mjs";
+import "./chunk-OVDNJAJN.mjs";
+import "./chunk-LJ5747UC.mjs";
+import "./chunk-FIVKWNMT.mjs";
+import "./chunk-TXZVVBQZ.mjs";
+import "./chunk-3HU47EGZ.mjs";
+import {
+  DeeplineClient
+} from "./chunk-J7ABTQQ7.mjs";
+import "./chunk-6IKARAYD.mjs";
+import "./chunk-JI2B4RZP.mjs";
+import "./chunk-EIMG75BT.mjs";
+import "./chunk-UBKA33KY.mjs";
+import "./chunk-WXLOW623.mjs";
+import {
+  printCommandEnvelope
+} from "./chunk-RNSWDKBM.mjs";
+import "./chunk-2LDADJNO.mjs";
+import "./chunk-YHPYUZZX.mjs";
+import "./chunk-DLIRSHV6.mjs";
+import "./chunk-NXGCO4JB.mjs";
+import "./chunk-MRXMMERY.mjs";
+import "./chunk-WZYKRD7T.mjs";
+import "./chunk-KRD6H754.mjs";
+
+// src/cli/commands/describe.ts
+import { writeFileSync } from "fs";
+import { resolve } from "path";
+async function describeAnything(name, options, onMissing) {
+  const client = new DeeplineClient();
+  const lookups = describeLookupsFor(client);
+  const outcome = await describeName(name, options, {
+    ...lookups,
+    // `tools describe` has already fetched the tool for its compatibility check.
+    tool: async (toolName) => options.fetchedTool ?? lookups.tool(toolName),
+    seedStarterScript: seedToolListScript
+  });
+  if (outcome.status === "missing") {
+    if (onMissing) return onMissing();
+    console.error(
+      `Nothing named "${name}". Search for it: deepline search ${JSON.stringify(name.replace(/[-_./]+/g, " "))}`
+    );
+    return 2;
+  }
+  if (outcome.status === "refused") {
+    console.error(outcome.message);
+    return outcome.exitCode;
+  }
+  return deliver(outcome.envelope, outcome.lines, {
+    json: options.json === true,
+    out: options.out
+  });
+}
+function deliver(envelope, lines, { json, out }) {
+  const text = `${lines.join("\n")}
+`;
+  if (out) {
+    const path = resolve(out);
+    const content = json ? `${JSON.stringify(envelope, null, 2)}
+` : text;
+    writeFileSync(path, content);
+    const bytes = Buffer.byteLength(content);
+    printCommandEnvelope(
+      { path, bytes },
+      { json, text: `Wrote ${path} (${bytes} bytes)
+` }
+    );
+    return 0;
+  }
+  printCommandEnvelope(envelope, { json, text });
+  return 0;
+}
+function registerDescribeCommand(program) {
+  addDescribeOptions(program.command("describe <name>")).option("--web-url", "Print only a play's play page URL").description(
+    "Describe anything search returns: a tool, monitor type, or play."
+  ).addHelpText(
+    "after",
+    `
+What you can describe:
+  Any id deepline search returns: a tool id, a monitor type id, or a play name
+  or reference. You do not say which kind it is; tool ids, monitor type ids
+  and prebuilt play names never overlap.
+
+When a name is taken twice:
+  A play your workspace created is shown instead of a Deepline tool, monitor
+  type or prebuilt play with the same name, and the output says so.
+  Pass --prebuilt (or --tool) to see the Deepline one.
+
+What it prints:
+  The same sections for every kind: what it is, cost, inputs, outputs, then
+  an example of running it from the CLI and from inside a play.
+
+Examples in the output:
+  (default)        required inputs filled in, first output read
+  --verbose        every input filled in, every output read; also shows
+                   secondary fields
+  --cli-example    only the CLI example, with how inputs and outputs work
+  --play-example   only the in-play example, with how inputs and outputs work
+  --no-example     no examples
+
+Features:
+  A tool lists its features: parts with their own description, such as the
+  model an AI tool runs. --feature <name> describes one at its default value,
+  --feature <name>=<value> at another, e.g. --feature model=openai/gpt-5.6-luna.
+
+Schema size and format:
+  Secondary fields (diagnostics, attempt logs, echoes of input) are left out
+  by default; the output names them, and --verbose shows them.
+  --fields email,miss_reason shows only the fields you name, plus every
+  required input, and names the rest. Use it when you know what you need.
+  A schema over ${SCHEMA_LINE_LIMIT} lines is folded: deeper objects show only their field
+  names. A shape used more than once is printed once under Types.
+  --full-schema    the normal output, with the schema not folded
+  --schema-only    only the schema, not folded, and nothing else
+  --json           the same facts as JSON: fields keyed by name, with what
+                   each means and, for a tool, where it is in the result;
+                   secondary fields are named in "hidden"
+  --json --full-schema  the whole catalog record, as tools describe and
+                   plays describe print it
+  --schema-only --json
+                   only the input and output JSON Schemas; use this for a
+                   program, or for a schema too large to read
+  --out <path>     save any of the above to a file instead of printing it
+
+Play page:
+  For a play, the output ends with its play page URL (JSON: dashboardUrl).
+  --web-url        print only that URL; with --json, {"dashboardUrl": ...}.
+                   Fails for a tool or monitor type, which have no play page.
+
+Older commands:
+  deepline tools describe and deepline plays describe are this command limited
+  to one kind. Their own flags still work: --pricing-only, --examples-only,
+  --model and --estimate-payload on tools; --json <fields> on plays.
+
+Examples:
+  deepline describe hunter_email_verifier
+  deepline describe person-linkedin-to-email
+  deepline describe my-play --prebuilt
+  deepline describe ai_ark_people_search --full-schema
+  deepline describe prebuilt/person-to-email-batch --web-url
+  deepline describe ai_ark_people_search --schema-only --out schema.json
+`
+  ).action(async (name, options) => {
+    process.exitCode = await describeAnything(name, options);
+  });
+}
+export {
+  describeAnything,
+  registerDescribeCommand
+};

package/dist/cli/describe-core.d.mts

@@ -0,0 +1,100 @@
+/// <reference path="./text-imports.d.ts" />
+import { T as ToolDefinition, D as DeeplineAgentModelDescription, P as PlayDescription, S as SearchType, a as DeeplineClient } from '../client-D0j-_aaa.mjs';
+import '../compiler-manifest-DLxUY5kI.mjs';
+import '@sinclair/typebox';
+import 'zod';
+import '../monitor-fleet-contract.mjs';
+
+/**
+ * How `deepline describe` presents a tool: its contract, the JSON record,
+ * and the shared `Described` form. Pure, so the CLI and MCP describe a tool
+ * the same way; writing a starter Play to a local file is the caller's
+ * choice, passed in as `seedStarterScript`. Relative imports carry no `.js`
+ * suffix because the app compiles this module from source.
+ */
+/** Writes a starter Play for a tool that returns a list; needs a local file. */
+type SeedStarterScript = (input: {
+    toolId: string;
+    payload: Record<string, unknown>;
+    rows: Array<Record<string, unknown>>;
+}) => SeededScript;
+type CliToolMetadata = ToolDefinition & Record<string, unknown>;
+type SeededScript = {
+    path: string;
+    sourceCode: string;
+    projectDir: string;
+    macCopyCommand: string;
+    windowsCopyCommand: string;
+};
+
+type FeatureDependencies = {
+    describeModel(model: string): Promise<DeeplineAgentModelDescription>;
+};
+
+/**
+ * `deepline describe` without a terminal: resolve a name to a tool, monitor
+ * type or play and build what describe shows for it. The CLI prints the
+ * result; MCP `deepline_describe` returns it. The lookups are the caller's,
+ * so each surface reads Deepline through its own authenticated client.
+ * Relative imports carry no `.js` suffix because the app compiles this
+ * module from source.
+ */
+/** The `--type` name that selects each kind; `plays` is `prebuilts` plus `custom`. */
+type KindFilter = Exclude<SearchType, 'plays'>;
+type DescribeOptions = {
+    /** Set by `tools describe` and `plays describe` to limit what a name may be. */
+    kinds?: readonly KindFilter[];
+    /** The whole catalog record as JSON, as the older describe commands print it. */
+    fullRecord?: boolean;
+    prebuilt?: boolean;
+    tool?: boolean;
+    verbose?: boolean;
+    cliExample?: boolean;
+    playExample?: boolean;
+    /** False under `--no-example`. */
+    example?: boolean;
+    fullSchema?: boolean;
+    fields?: string;
+    schemaOnly?: boolean;
+    /** `name` or `name=value`: describe that one feature instead. */
+    feature?: string;
+    /** Only the play page URL; a tool or monitor type has none. */
+    webUrl?: boolean;
+};
+/** How describe reads Deepline. A lookup answers null when nothing has the name. */
+type DescribeLookups = FeatureDependencies & {
+    play(reference: string): Promise<PlayDescription | null>;
+    tool(name: string): Promise<CliToolMetadata | null>;
+    /** The app origin play pages are served from. */
+    baseUrl: string;
+    /** Where a list tool's starter Play is written; only a local CLI has one. */
+    seedStarterScript?: SeedStarterScript;
+};
+/** Describe's lookups over an SDK client, as the CLI and MCP both read. */
+declare function describeLookupsFor(client: Pick<DeeplineClient, 'describePlay' | 'getTool' | 'describeModel' | 'baseUrl'>): DescribeLookups;
+/**
+ * What describe shows for a name: its JSON record and readable lines; that
+ * nothing has the name; or why the request cannot be answered, with the
+ * CLI's exit code.
+ */
+type DescribeOutcome = {
+    status: 'described';
+    envelope: Record<string, unknown>;
+    lines: string[];
+} | {
+    status: 'missing';
+} | {
+    status: 'refused';
+    message: string;
+    exitCode: number;
+};
+/**
+ * Describe whatever `name` is: anything `deepline search` returns. Tool ids,
+ * monitor type ids and prebuilt play names never collide (the catalog build
+ * rejects a release where they do), so a bare name has at most one
+ * Deepline-maintained meaning. A play the workspace created under the same
+ * name wins unless `custom` is excluded, and the output says so.
+ */
+declare function describeName(name: string, options: DescribeOptions, lookups: DescribeLookups): Promise<DescribeOutcome>;
+
+export { type CliToolMetadata, type DescribeLookups, type DescribeOptions, type DescribeOutcome, type KindFilter, PlayDescription, describeLookupsFor, describeName };