deepline 0.3.311 → 0.3.313

package/dist/cli/{play-SOG5Q2GE.mjs → chunk-BS4GAUMH.mjs}

@@ -1,13 +1,17 @@
 import {
-  handleDeploymentGet,
-  handleDeploymentsList
-} from "./chunk-4WFNAWVO.mjs";
+  addDescribeOptions,
+  schemaFields
+} from "./chunk-76VKBPOC.mjs";
 import {
   parseCsvDataInput
 } from "./chunk-EDWJY6T4.mjs";
 import {
   registerDeprecatedSearchCommand
-} from "./chunk-ICZB4GTY.mjs";
+} from "./chunk-RDUS2EDE.mjs";
+import {
+  handleDeploymentGet,
+  handleDeploymentsList
+} from "./chunk-QCXDLOGA.mjs";
 import {
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
   PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER,
@@ -30,7 +34,7 @@ import {
   normalizeRunEventOperationRequest,
   parseLogLevel,
   playInputExampleArgs
-} from "./chunk-5OVNL6LS.mjs";
+} from "./chunk-YZ5PP6TX.mjs";
 import {
   CSV_DATA_INPUT_KEY,
   buildNamedPlayRunRequest,
@@ -62,12 +66,10 @@ import {
   printJson,
   printJsonError,
   renderCommandEnvelopeText
-} from "./chunk-SPUTBCUR.mjs";
+} from "./chunk-CSH4PKPJ.mjs";
 import {
   fetchWithDeploymentProtection
-} from "./chunk-Q3LYQTSO.mjs";
-import "./chunk-DLIRSHV6.mjs";
-import "./chunk-SGTSJCOA.mjs";
+} from "./chunk-DOI3UBGV.mjs";
 import {
   PLAY_DEFAULT_EXPORT,
   extractDefinedPlayName,
@@ -75,14 +77,10 @@ import {
   listPlayFileExports,
   parsePlaySourceForAnalysis,
   resolveEnabledExecutionProfile
-} from "./chunk-4NIQA6S7.mjs";
-import "./chunk-H7HIDGZ7.mjs";
-import "./chunk-WB6Z2Q44.mjs";
-import "./chunk-6IKARAYD.mjs";
+} from "./chunk-US4S3E4Y.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";
-import "./chunk-WZYKRD7T.mjs";
 import {
   __commonJS,
   __toESM
@@ -1917,6 +1915,7 @@ function displayPlayPath(path, ownerName) {
     ...path?.folders ?? []
   ].join(" / ");
 }
+var playDisplayNameSchema = z.string().trim().nullable().transform((value) => value || null);
 var PLAY_SETTING_FIELDS = {
   path: {
     schema: playPathSchema.default(null).describe(
@@ -1937,9 +1936,26 @@ var PLAY_SETTING_FIELDS = {
         "null"
       ],
       parse: (value) => value === "null" ? null : parsePlayPath(value),
-      format: formatPlayPath
+      format: (value) => formatPlayPath(playPathSchema.parse(value))
     },
     ui: { control: "play-location-picker" }
+  },
+  displayName: {
+    schema: playDisplayNameSchema.default(null).describe(
+      "Optional human-readable Play name. Null uses the name derived from the identifier."
+    ),
+    label: "Display name",
+    description: "Optional name shown in the UI. Leave empty to use the name derived from the Play identifier.",
+    get defaultValue() {
+      return this.schema.parse(void 0);
+    },
+    cli: {
+      valueSyntax: "text | null",
+      examples: ["Find verified emails", "null"],
+      parse: (value) => value === "null" ? null : value,
+      format: (value) => playDisplayNameSchema.parse(value) ?? "null"
+    },
+    ui: { control: "text" }
   }
 };
 var playSettingsSchema = z.object(
@@ -2043,6 +2059,7 @@ function resolveField(key, command) {
   return entry[1];
 }
 function printSettings(result, json, name) {
+  result = { ...result, settings: parsePlaySettings(result.settings) };
   const selected = fields.filter(([key]) => !name || key === name);
   printCommandEnvelope(
     {
@@ -4295,7 +4312,7 @@ Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using
       `Unknown plays bootstrap template: ${rawTemplate}
 Supported templates: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}` + (looksLikePlayReference ? `
 
-"${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}'" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
+"${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}'" to run it directly, "deepline describe ${rawTemplate}" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
   }
   return rawTemplate;
@@ -4798,7 +4815,7 @@ function generateSourceProviderInputObject(input) {
   );
   const lines = [
     `${indent}// TODO: fill ${entity} source inputs for ${label}.`,
-    `${indent}// Inspect: deepline tools describe ${label} --json`
+    `${indent}// Inspect: deepline describe ${label}`
   ];
   for (const field of required) {
     lines.push(`${indent}// ${field}: ${exampleValueComment(field)},`);
@@ -4891,7 +4908,7 @@ function safeIdentifier(value) {
   return value.replace(/[^A-Za-z0-9_]+/g, "_");
 }
 function playInspectionComments(playRef, indent) {
-  return [`${indent}// Inspect: deepline plays describe ${playRef} --json`];
+  return [`${indent}// Inspect: deepline describe ${playRef}`];
 }
 function accessorExpression(base, field) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field) ? `${base}.${field}` : `${base}[${jsString(field)}]`;
@@ -5005,7 +5022,7 @@ function validateBootstrapRoutes(input) {
     }
     if (getterNamesFromTool(tool, "list").length === 0) {
       throw new PlayBootstrapValidationError(
-        `Cannot use ${tool.toolId} as a ${config.sourceEntity} source: it exposes no extracted list getters. Run: deepline tools describe ${tool.toolId} --json`
+        `Cannot use ${tool.toolId} as a ${config.sourceEntity} source: it exposes no extracted list getters. Run: deepline describe ${tool.toolId}`
       );
     }
   }
@@ -5034,7 +5051,7 @@ function validateBootstrapRoutes(input) {
       }
       if (getterNamesFromTool(tool, "value").length === 0) {
         throw new PlayBootstrapValidationError(
-          `Cannot use ${tool.toolId} as a ${finder}: it exposes no extracted value getters. Run: deepline tools describe ${tool.toolId} --json`
+          `Cannot use ${tool.toolId} as a ${finder}: it exposes no extracted value getters. Run: deepline describe ${tool.toolId}`
         );
       }
     }
@@ -6956,7 +6973,7 @@ function stringValue2(value) {
 }
 
 // src/cli/play-check-hints.ts
-var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Read tool-specific fields from `toolExecutionResult.toolResponse.rawV2` using the nesting shown in the response example, and use `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline describe <tool>`. Read tool-specific fields from `toolExecutionResult.toolResponse.rawV2` using the nesting shown in the response example, and use `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy, durable, and async-only. Use `.count()`, `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.length`, numeric indexing, spread, synchronous iteration, `.rows`, or `.toArray()`.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and result-cache identity; terminal cache reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
@@ -9359,9 +9376,7 @@ function buildPlayReferenceNotFoundMessage(input) {
           `    deepline plays versions --name ${suggestion.reference} --json`
         );
       } else {
-        lines.push(
-          `    deepline plays describe ${suggestion.reference} --json`
-        );
+        lines.push(`    deepline describe ${suggestion.reference}`);
       }
     }
   }
@@ -9611,7 +9626,7 @@ function parseJsonInput(raw, flag = "--input") {
     parsed = JSON.parse(source);
   } catch {
     throw new DeeplineError(
-      `${flag} expects a valid JSON object or @input.json. A bare file path is not JSON.${flag === "--input" ? " Use the field names and run example from plays check <file> or plays describe <play>. --csv contacts.csv supplies input.csv only when the Play declares that field." : ""}`,
+      `${flag} expects a valid JSON object or @input.json. A bare file path is not JSON.${flag === "--input" ? " Use the field names and run example from plays check <file> or deepline describe <play>. --csv contacts.csv supplies input.csv only when the Play declares that field." : ""}`,
       void 0,
       "INVALID_JSON"
     );
@@ -16738,6 +16753,42 @@ function csvColumnLines(csvInput) {
     CSV_HEADER_MATCHING_NOTE
   ];
 }
+function describedPlay(play) {
+  const reference = formatPlayListReference(play);
+  const starter = play.cloneEditStarter ?? buildCloneEditStarter(play);
+  const csv = play.csvInput ?? {};
+  const headers = isRecord3(csv.defaultColumns) ? csv.defaultColumns : {};
+  const rowInputs = schemaFields(csv.rowInputSchema).map((field) => {
+    const header = [headers[field.name]].flat().filter((name) => name && name !== field.name).join(" or ");
+    return header ? {
+      ...field,
+      description: [field.description, `CSV header: ${header}`].filter(Boolean).join(" - ")
+    } : field;
+  });
+  const rowOutput = play.rowOutputSchema ?? {};
+  const added = isRecord3(rowOutput.addedColumns) ? rowOutput.addedColumns : {};
+  const rowOutputs = schemaFields(
+    Object.keys(added).length ? { properties: added } : rowOutput
+  ).map((field) => ({ ...field, required: true }));
+  return {
+    kind: play.ownerType === "deepline" ? "prebuilt_play" : "custom_play",
+    id: reference,
+    ...play.displayName && play.displayName !== play.name ? { displayName: play.displayName } : {},
+    ...play.description ? { description: play.description } : {},
+    guidance: [],
+    inputs: schemaFields(play.inputSchema),
+    outputs: schemaFields(play.outputSchema),
+    ...rowInputs.length ? { rowInputs } : {},
+    ...rowOutputs.length ? { rowOutputs } : {},
+    runner: {
+      via: "play",
+      reference,
+      // A CSV play's run command is built by the server around its columns.
+      ...play.csvInput ? { cli: play.runCommand } : {}
+    },
+    ...starter ? { source: starter.command } : {}
+  };
+}
 function printPlayDescription(play) {
   const reference = formatPlayListReference(play);
   const labels = [
@@ -16816,7 +16867,7 @@ function printPlayDescription(play) {
     );
   }
   printScheduledPlayCapacity(play.activeScheduledPlays);
-  console.log(`  Describe: deepline plays describe ${reference} --json`);
+  console.log(`  Describe: deepline describe ${reference}`);
   console.log(`  Run: ${play.runCommand}`);
   const cloneEditStarter = play.cloneEditStarter ?? buildCloneEditStarter(play);
   if (cloneEditStarter) {
@@ -16827,10 +16878,11 @@ function printPlayDescription(play) {
 function summarizePlayGrepResult(play) {
   const reference = formatPlayListReference(play);
   return {
-    name: play.displayName?.trim() || play.name,
+    name: play.name,
+    ...play.displayName ? { displayName: play.displayName } : {},
     reference,
     matches: play.matches ?? [],
-    describe: `deepline plays describe ${reference} --json`
+    describe: `deepline describe ${reference}`
   };
 }
 function formatPlayGrepMatches(matches) {
@@ -16861,7 +16913,7 @@ async function handlePlayGrep(args) {
 `
   );
   for (const result of results) {
-    console.log(result.name);
+    console.log(result.displayName?.trim() || result.name);
     const matches = formatPlayGrepMatches(result.matches);
     if (matches) console.log(`  Matched: ${matches}`);
     console.log(`  Describe: ${result.describe}`);
@@ -16902,7 +16954,7 @@ async function handlePlayDescribe(args) {
     })() : null;
     const next = [
       `deepline plays check ${playName}`,
-      ...definedName ? [`deepline plays describe <workspace>/${definedName}`] : []
+      ...definedName ? [`deepline describe <workspace>/${definedName}`] : []
     ];
     if (argsWantJson(args)) {
       printCompactJson({
@@ -17404,7 +17456,7 @@ Concepts:
 
 Run and retrieve results:
   1. Discover a Play: deepline plays search email --json
-     Inspect its input contract: deepline plays describe <play-name> --json
+     Inspect its input contract: deepline describe <play-name>
   2. Start and follow a new run: deepline plays run workflow.play.ts --csv contacts.csv
      This example requires input.csv. Use the selected Play's actual input fields.
      Run waits and shows progress by default; --no-wait returns immediately.
@@ -17439,7 +17491,7 @@ Authoring:
 
 Common commands:
   deepline search --type prebuilts email --json
-  deepline plays describe prebuilt/person-linkedin-to-email --json
+  deepline describe prebuilt/person-linkedin-to-email
   deepline plays check prebuilt/name-and-domain-to-email-waterfall-batch
   deepline plays run prebuilt/person-linkedin-to-email --input '{"linkedin_url":"..."}'
   deepline plays get prebuilt/person-linkedin-to-email --json
@@ -17829,7 +17881,7 @@ Notes:
 
 Examples:
   deepline plays grep email --json
-  deepline plays describe prebuilt/company-to-contact --json
+  deepline describe prebuilt/company-to-contact
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlayGrep([
@@ -17837,7 +17889,7 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("describe [target]").usage("<target> [options]").description("Describe a play contract and how to run it.").addHelpText(
+  const describeCommand = play.command("describe [target]", { hidden: true }).usage("<target> [options]").description("Describe a play contract and how to run it.").addHelpText(
     "after",
     `
 Notes:
@@ -17855,11 +17907,33 @@ Examples:
   ).option("--compact", "Emit compact schemas").option(
     "--json [fields]",
     "JSON output; optionally select comma-separated dotted paths"
-  ).action(async (target, options) => {
-    process.exitCode = await handlePlayDescribe(
-      describeArgs(target, options)
-    );
-  });
+  );
+  addDescribeOptions(describeCommand, { json: false }).action(
+    async (target, options) => {
+      const ownView = () => handlePlayDescribe(describeArgs(target, options));
+      const [flagText] = [options.json].filter(
+        (value) => typeof value === "string"
+      );
+      const name = target || flagText;
+      const selectsFields = Boolean(target && flagText);
+      const own = !name || options.compact || selectsFields || looksLikeRunId(name) || isFileTarget(name) || looksLikeFilePath(name);
+      if (own) {
+        process.exitCode = await ownView();
+        return;
+      }
+      const { describeAnything } = await import("./describe-WCBZTSOF.mjs");
+      process.exitCode = await describeAnything(
+        name,
+        {
+          ...options,
+          kinds: ["prebuilts", "custom"],
+          json: Boolean(options.json)
+        },
+        // An unknown play keeps this command's suggestions.
+        ownView
+      );
+    }
+  );
   play.command("versions").description("List revisions for a named play.").addHelpText(
     "after",
     `
@@ -18794,68 +18868,70 @@ async function handlePlayShareUnpublish(args) {
   console.log(`Unpublished ${name}; the public page has been removed.`);
   return 0;
 }
+
 export {
-  PREBUILT_PLAY_TAG_KEYS,
-  assertDatasetHasExportableRows,
-  buildPlayCompletionTextLines,
-  buildRunActivityTextLines,
-  buildRunLaunch,
-  buildRunLogsText,
-  buildRunPackageTextLines,
-  buildStopAllDryRunTextLines,
-  clampJsonPreviewText,
-  compactPlayStatus,
-  csvColumnLines,
+  resolveDatasetByName,
+  loadPlayBundler,
+  parsePlayRunHeaderFlag,
+  writePlayRunIdFile,
+  preflightLocalFileInputs,
   describeSleepUntil,
-  exportPlayStatusRows,
-  formatPlaySandboxRuntimeWarning,
-  formatStepLabelFromNodeId,
   getFinalStatusFromLiveEvent,
+  formatStepLabelFromNodeId,
+  getStepTransitionLineFromLiveEvent,
   getProgressLinesFromLiveEvent,
+  shouldPrintPlayProgressLine,
   getRunningHeartbeatLine,
-  getStepTransitionLineFromLiveEvent,
+  waitForPlayCompletionByWatch,
+  startAndWaitForPlayCompletionByStream,
+  truncateErrorForDisplay,
+  clampJsonPreviewText,
+  withTerminalPlayIdentity,
+  compactPlayStatus,
+  buildRunActivityTextLines,
+  buildRunPackageTextLines,
+  buildRunLaunch,
+  buildPlayCompletionTextLines,
+  resolvePlayRunOutputStatus,
+  assertDatasetHasExportableRows,
+  exportPlayStatusRows,
+  parsePlayRunOptions,
+  parsePlayPublishOptions,
+  formatPlaySandboxRuntimeWarning,
   handlePlayCheck,
-  handlePlayDelete,
-  handlePlayDescribe,
-  handlePlayGet,
-  handlePlayGrep,
-  handlePlayList,
-  handlePlayPin,
-  handlePlayPublish,
-  handlePlayRestore,
   handlePlayRun,
-  handlePlaySave,
-  handlePlaySharePublish,
-  handlePlayShareRegenerate,
-  handlePlayShareStatus,
-  handlePlayShareUnpublish,
-  handlePlayShareUpdate,
-  handlePlayVersions,
-  handleRunEventSearch,
-  handleRunExport,
+  renderRunOverviewText,
   handleRunGet,
   handleRunLifecycleStatus,
+  handleRunsRerun,
+  handleRunsList,
+  handleRunTail,
   handleRunLogs,
+  selectRunLogTailPage,
+  handleRunEventSearch,
+  buildRunLogsText,
+  resolveRunStopState,
   handleRunStop,
+  buildStopAllDryRunTextLines,
   handleRunStopAll,
-  handleRunTail,
-  handleRunsList,
-  handleRunsRerun,
-  loadPlayBundler,
-  parsePlayPublishOptions,
-  parsePlayRunHeaderFlag,
-  parsePlayRunOptions,
-  preflightLocalFileInputs,
+  handleRunExport,
+  handlePlayGet,
+  handlePlayVersions,
+  PREBUILT_PLAY_TAG_KEYS,
+  handlePlayList,
+  handlePlayPin,
+  csvColumnLines,
+  describedPlay,
+  handlePlayGrep,
+  handlePlayDescribe,
+  handlePlaySave,
+  handlePlayPublish,
+  handlePlayDelete,
+  handlePlayRestore,
   registerPlayCommands,
-  renderRunOverviewText,
-  resolveDatasetByName,
-  resolvePlayRunOutputStatus,
-  resolveRunStopState,
-  selectRunLogTailPage,
-  shouldPrintPlayProgressLine,
-  startAndWaitForPlayCompletionByStream,
-  truncateErrorForDisplay,
-  waitForPlayCompletionByWatch,
-  withTerminalPlayIdentity,
-  writePlayRunIdFile
+  handlePlayShareStatus,
+  handlePlaySharePublish,
+  handlePlayShareUpdate,
+  handlePlayShareRegenerate,
+  handlePlayShareUnpublish
 };

package/dist/cli/{chunk-SPUTBCUR.mjs → chunk-CSH4PKPJ.mjs}

@@ -3,7 +3,7 @@ import {
   detectAgentRuntime,
   resolveCliCommandContext,
   resolveConfig
-} from "./chunk-Q3LYQTSO.mjs";
+} from "./chunk-DOI3UBGV.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";

package/dist/cli/{chunk-Q3LYQTSO.mjs → chunk-DOI3UBGV.mjs}

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