deepline 0.2.69 → 0.2.71

package/dist/cli/index.js

@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.69",
+  version: "0.2.71",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3983,16 +3983,9 @@ function isPrebuiltPlayDescription(play) {
   return play.origin === "prebuilt" || play.ownerType === "deepline";
 }
 function preferPrebuiltPlayDescriptions(plays) {
-  const prebuilt = [];
-  const owned = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays.map((play, index) => ({ play, index })).sort(
+    (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
+  ).map(({ play }) => play);
 }
 function isPlayRunPackage(value) {
   return Boolean(
@@ -4339,6 +4332,8 @@ var DeeplineClient = class {
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -5837,6 +5832,16 @@ var DeeplineClient = class {
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
+    if (options?.categories) {
+      params.set(
+        "categories",
+        Array.isArray(options.categories) ? options.categories.join(",") : options.categories
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set("include_tool_categories", "1");
+    }
+    if (options?.includeArchived) params.set("include_archived", "1");
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
       params.set("grep_mode", options.grepMode ?? "all");
@@ -5848,6 +5853,12 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(playName, pinned) {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned
+    });
+  }
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings() {
     return this.http.get("/api/v2/settings/notifications");
@@ -6050,13 +6061,22 @@ var DeeplineClient = class {
     );
   }
   /**
-   * Delete an org-owned play definition, including its revisions, trigger
-   * bindings, and local run records. Deepline prebuilt plays are read-only.
+   * Move an org-owned play to Trash. This disables its active triggers while
+   * retaining its revisions and run history so it can be restored. Deepline
+   * prebuilt plays are read-only.
    */
   async deletePlay(name) {
     const encodedName = encodeURIComponent(name);
     return this.http.delete(`/api/v2/plays/${encodedName}`);
   }
+  /** Restore an org-owned play that was previously moved to Trash. */
+  async restorePlay(name) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post(
+      `/api/v2/plays/${encodedName}/restore`,
+      {}
+    );
+  }
   // ——————————————————————————————————————————————————————————
   // Plays — public share pages
   // ——————————————————————————————————————————————————————————
@@ -22839,6 +22859,29 @@ function resolvePlayCheckExportNames(sourceCode) {
   if (!exports2 || exports2.length === 0) return [PLAY_DEFAULT_EXPORT];
   return exports2.map((entry) => entry.name);
 }
+function artifactForProductionCompatibilityCheck(artifact) {
+  const rawEdition = process.env.DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION?.trim();
+  if (!rawEdition) return artifact;
+  if (!/^\d+$/.test(rawEdition)) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const edition = Number(rawEdition);
+  if (edition < 1) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const compatibility = isRecord10(artifact.compatibility) ? artifact.compatibility : {};
+  return {
+    ...artifact,
+    compatibility: {
+      ...compatibility,
+      authoringContractEdition: edition
+    }
+  };
+}
 async function checkOneExportedPlay(input2) {
   const { absolutePlayPath, sourceCode, exportName } = input2;
   const fallbackName = extractPlayName(sourceCode, absolutePlayPath);
@@ -22878,7 +22921,7 @@ async function checkOneExportedPlay(input2) {
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
     description: graph.root.playDescription ?? void 0,
-    artifact: graph.root.artifact,
+    artifact: artifactForProductionCompatibilityCheck(graph.root.artifact),
     ...exportName === PLAY_DEFAULT_EXPORT ? {} : { exportName },
     ...importedPlays.length > 0 ? { importedPlays } : {},
     ...integrationMode ? { integrationMode } : {}
@@ -24064,7 +24107,12 @@ async function handlePlayVersions(args) {
 async function handlePlayList(args) {
   const jsonOutput = argsWantJson(args);
   const client2 = new DeeplineClient();
-  const plays = await client2.listPlays();
+  const categoriesIndex = args.indexOf("--categories");
+  const categories = categoriesIndex >= 0 ? args[categoriesIndex + 1]?.trim() : void 0;
+  const plays = await client2.listPlays({
+    categories,
+    includeToolCategories: true
+  });
   if (jsonOutput) {
     process.stdout.write(`${JSON.stringify(plays)}
 `);
@@ -24075,6 +24123,8 @@ async function handlePlayList(args) {
 `);
   for (const play of plays) {
     const flags = [
+      play.pinned ? "pinned" : null,
+      ...(play.toolCategories ?? []).map((category) => `category:${category}`),
       play.origin === "prebuilt" || play.ownerType === "deepline" ? "prebuilt" : "owned",
       play.canEdit ? "editable" : "readonly",
       play.isDraftDirty ? "draft-dirty" : null
@@ -24104,6 +24154,36 @@ async function handlePlayList(args) {
   }
   return 0;
 }
+async function handlePlayPin(args, pinned) {
+  const target = args.find((arg) => !arg.startsWith("-"))?.trim();
+  const jsonOutput = argsWantJson(args);
+  const dryRun = args.includes("--dry-run");
+  if (!target) {
+    console.error(
+      `Usage: deepline plays ${pinned ? "pin" : "unpin"} <play> [--dry-run] [--json]`
+    );
+    return 2;
+  }
+  const parsedTarget = parseReferencedPlayTarget2(target);
+  if (parsedTarget.ownerSlug) {
+    console.error(
+      `deepline plays ${pinned ? "pin" : "unpin"} accepts an org-owned Play identifier without a namespace. Use "${parsedTarget.unqualifiedPlayName}" instead of "${target}".`
+    );
+    return 2;
+  }
+  const name = parsedTarget.playName;
+  const plan = { name, pinned, dryRun };
+  if (dryRun) {
+    process.stdout.write(`${JSON.stringify(plan)}
+`);
+    return 0;
+  }
+  const result = await new DeeplineClient().setPlayPinned(name, pinned);
+  if (jsonOutput) process.stdout.write(`${JSON.stringify(result)}
+`);
+  else console.log(`${result.pinned ? "Pinned" : "Unpinned"} ${result.name}.`);
+  return 0;
+}
 function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
@@ -24138,6 +24218,12 @@ function printPlayDescription(play) {
   if (play.description) {
     console.log(`  Description: ${play.description}`);
   }
+  if (play.pinned) {
+    console.log("  Pinned: yes");
+  }
+  if (play.toolCategories?.length) {
+    console.log(`  Tool categories: ${play.toolCategories.join(", ")}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -24243,6 +24329,8 @@ function summarizePlayListItemForCli(play, options) {
     name: play.name,
     ...play.reference ? { reference: play.reference } : {},
     ...play.displayName ? { displayName: play.displayName } : {},
+    pinned: Boolean(play.pinned),
+    toolCategories: play.toolCategories ?? [],
     origin: play.origin,
     ownerType: play.ownerType,
     canEdit: play.canEdit,
@@ -24373,6 +24461,7 @@ async function handlePlayGrep(args) {
         origin: play.origin,
         ownerType: play.ownerType,
         aliases: play.aliases,
+        toolCategories: play.toolCategories,
         inputSchema: play.inputSchema,
         outputSchema: play.outputSchema
       },
@@ -24673,15 +24762,32 @@ async function handlePlayPublish(args) {
 async function handlePlayDelete(args) {
   const playName = args[0];
   if (!playName) {
-    console.error("Usage: deepline plays delete <play-name> --yes [--json]");
-    return 1;
+    console.error(
+      "Usage: deepline plays delete <play-name> --yes [--dry-run] [--json]"
+    );
+    return 2;
+  }
+  if (looksLikeRunId(playName)) {
+    console.error(
+      formatPlayCommandReceivedRunIdError({
+        command: "delete",
+        runId: playName
+      })
+    );
+    return 2;
+  }
+  if (isFileTarget(playName) || looksLikeFilePath(playName)) {
+    console.error(
+      "Refusing to delete a local file. This command only moves a saved org-owned play to Trash."
+    );
+    return 2;
   }
-  const confirmed = args.includes("--yes") || args.includes("-y") || args.includes("--force");
+  const confirmed = args.includes("--yes") || args.includes("-y");
   if (!confirmed) {
     console.error(
-      "Refusing to delete without --yes. This deletes the org-owned play, its revisions, trigger bindings, and local run records."
+      "Refusing to move the play to Trash without --yes. This stops active triggers; the play can be restored later."
     );
-    return 1;
+    return 2;
   }
   const client2 = new DeeplineClient();
   let detail;
@@ -24689,27 +24795,103 @@ async function handlePlayDelete(args) {
     detail = await client2.getPlay(parseReferencedPlayTarget2(playName).playName);
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
-    return 1;
+    return 5;
   }
   if (detail.play.ownerType === "deepline" || detail.play.origin === "prebuilt") {
     console.error(
-      `Cannot delete prebuilt play: ${formatPlayReference(detail.play)}`
+      `Cannot move prebuilt play to Trash: ${formatPlayReference(detail.play)}`
     );
-    return 1;
+    return 2;
   }
-  const result = await client2.deletePlay(
-    parseReferencedPlayTarget2(formatPlayReference(detail.play)).playName
-  );
+  const resolvedName = parseReferencedPlayTarget2(
+    formatPlayReference(detail.play)
+  ).playName;
+  if (args.includes("--dry-run")) {
+    const result2 = {
+      ok: true,
+      dryRun: true,
+      name: resolvedName,
+      plannedMutation: "move saved org-owned play to Trash and stop triggers"
+    };
+    if (argsWantJson(args)) {
+      process.stdout.write(`${JSON.stringify(result2)}
+`);
+    } else {
+      process.stdout.write(
+        `Dry run: would move ${result2.name} to Trash and stop its active triggers.
+`
+      );
+    }
+    return 0;
+  }
+  const result = await client2.deletePlay(resolvedName);
   if (argsWantJson(args)) {
     process.stdout.write(`${JSON.stringify(result)}
 `);
-    return result.deleted ? 0 : 1;
+    return result.archived || result.alreadyArchived ? 0 : 4;
+  }
+  if (result.alreadyArchived) {
+    process.stdout.write(`Play ${result.name} is already in Trash.
+`);
+    return 0;
+  }
+  if (!result.archived) {
+    console.error(`Play not found: ${result.name}`);
+    return 4;
   }
   process.stdout.write(
-    `Deleted ${result.name}: revisions=${result.deletedRevisionCount}, bindings=${result.deletedBindingCount}, runs=${result.deletedRunCount}
+    `Moved ${result.name} to Trash: stopped bindings=${result.archivedBindingCount}
 `
   );
-  return result.deleted ? 0 : 1;
+  return 0;
+}
+async function handlePlayRestore(args) {
+  const playName = args[0];
+  if (!playName) {
+    console.error("Usage: deepline plays restore <play-name> [--json]");
+    return 2;
+  }
+  if (looksLikeRunId(playName)) {
+    console.error(
+      formatPlayCommandReceivedRunIdError({
+        command: "restore",
+        runId: playName
+      })
+    );
+    return 2;
+  }
+  if (isFileTarget(playName) || looksLikeFilePath(playName)) {
+    console.error(
+      "Refusing to restore a local file. This command only restores a saved org-owned play from Trash."
+    );
+    return 2;
+  }
+  const client2 = new DeeplineClient();
+  try {
+    const result = await client2.restorePlay(
+      parseReferencedPlayTarget2(playName).playName
+    );
+    if (argsWantJson(args)) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+      return result.restored || result.alreadyActive ? 0 : 4;
+    }
+    if (result.alreadyActive) {
+      process.stdout.write(`Play ${result.name} is already active.
+`);
+      return 0;
+    }
+    if (!result.restored) {
+      console.error(`Play not found: ${result.name}`);
+      return 4;
+    }
+    process.stdout.write(`Restored ${result.name} from Trash.
+`);
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 5;
+  }
 }
 function registerPlayCommands(program) {
   const play = program.command("plays").description("Search, validate, run, and manage cloud plays.").addHelpText(
@@ -24943,11 +25125,35 @@ Examples:
   deepline plays list
   deepline plays search email --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+    "--categories <categories>",
+    "Filter by comma-separated canonical tool categories"
+  ).action(async (options) => {
     process.exitCode = await handlePlayList([
+      ...options.categories ? ["--categories", options.categories] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
+  play.command("pin <target>").description("Pin an org-owned play to the top of play listings.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      true
+    );
+  });
+  play.command("unpin <target>").description("Remove an org-owned play from the pinned group.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      false
+    );
+  });
   const addPlaySearchCommand = (command) => command.description("Search Deepline prebuilt plays by task.").option(
     "--prebuilt",
     "Only show Deepline-managed prebuilt plays (default)"
@@ -25094,21 +25300,40 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("delete <target>").description("Delete an org-owned play and its saved revisions/runs.").addHelpText(
+  play.command("delete <target>").description("Move an org-owned play to Trash and stop its triggers.").addHelpText(
     "after",
     `
 Notes:
-  Destructive mutation. Deletes an org-owned play plus saved revisions and run
-  records. Prebuilt/read-only plays are refused. Use --yes for noninteractive runs.
+  Soft delete. Moves an org-owned play to Trash and stops active triggers while
+  retaining revisions and run history. Prebuilt/read-only plays are refused.
+  Use --yes for noninteractive runs. Restore later with \`plays restore\`.
 
 Examples:
-  deepline plays delete my-play
+  deepline plays delete my-play --yes
   deepline plays delete my-play --yes --json
+  deepline plays delete my-play --yes --dry-run --json
 `
-  ).option("-y, --yes", "Confirm deletion").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+  ).option("-y, --yes", "Confirm deletion").option("--dry-run", "Show the planned archive without mutating the play").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayDelete([
       target,
       ...options.yes ? ["--yes"] : [],
+      ...options.dryRun ? ["--dry-run"] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
+  play.command("restore <target>").description("Restore an org-owned play from Trash.").addHelpText(
+    "after",
+    `
+Notes:
+  Restoring re-enables the saved play and recreates its trigger bindings.
+
+Examples:
+  deepline plays restore my-play
+  deepline plays restore my-play --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+    process.exitCode = await handlePlayRestore([
+      target,
       ...options.json ? ["--json"] : []
     ]);
   });
@@ -26283,10 +26508,12 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
   const metadataColumnSource = renderMetadataColumnStep(config);
   const generatedAliases = collectGeneratedAliases(config.commands);
   const runOptionsSource = options.failFast ? `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart), onRowError: 'fail' as const }` : `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart) }`;
+  const describedColumns = config.commands.filter((command) => isWaterfall(command) || !command.disabled).map(
+    (command) => (isWaterfall(command) ? command.with_waterfall : command.alias).replace(/[_-]+/g, " ").trim()
+  ).filter(Boolean).slice(0, 3);
+  const generatedDescription = describedColumns.length ? `Enrich CSV rows with ${describedColumns.join(", ")}.` : "Prepare CSV rows for enrichment.";
   const playOptionsSource = [
-    `description: ${stringLiteral(
-      "Read a CSV file, run the configured Deepline enrich commands, and return enriched rows."
-    )}`,
+    `description: ${stringLiteral(generatedDescription)}`,
     ...options.maxCreditsPerRun === void 0 ? [] : [`billing: { maxCreditsPerRun: ${String(options.maxCreditsPerRun)} }`]
   ].join(", ");
   const body = [