deepline 0.2.70 → 0.2.72

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.70",
+  version: "0.2.72",
   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");
@@ -5981,9 +5992,10 @@ var DeeplineClient = class {
    * console.log(`Total runs: ${detail.play.runCount}`);
    * ```
    */
-  async getPlay(name) {
+  async getPlay(name, options) {
     const encodedName = encodeURIComponent(name);
-    return this.http.get(`/api/v2/plays/${encodedName}`);
+    const query = options?.source ? `?include=source&revision=${encodeURIComponent(options.source)}` : "";
+    return this.http.get(`/api/v2/plays/${encodedName}${query}`);
   }
   /**
    * Get a normalized play description suitable for agents and CLIs.
@@ -18580,7 +18592,10 @@ async function assertCanonicalNamedPlayReference(client2, target, options = {})
   const parsed = parseReferencedPlayTarget2(target);
   let detail;
   try {
-    detail = await client2.getPlay(parsed.playName);
+    detail = await client2.getPlay(
+      parsed.playName,
+      options.source ? { source: options.source } : void 0
+    );
   } catch (error) {
     if (isPlayNotFoundError(error)) {
       throw await buildPlayReferenceNotFoundError({
@@ -18633,19 +18648,54 @@ function materializeRemotePlaySource(input2) {
   if (isFileTarget(input2.target)) {
     return null;
   }
-  if (!input2.sourceCode.trim()) {
+  const entrySource = input2.source.files[input2.source.entryFile];
+  if (!entrySource?.trim()) {
     return null;
   }
+  const files = Object.entries(input2.source.files);
+  if (files.length > 1) {
+    if (!input2.outPath) {
+      throw new Error(
+        `Play ${input2.playName} has ${files.length} source files. Use --out <directory> to write the complete bundle.`
+      );
+    }
+    const outputDirectory = (0, import_node_path14.resolve)(input2.outPath);
+    let created = 0;
+    let updated = 0;
+    for (const [logicalPath, sourceCode] of files) {
+      const outputPath2 = (0, import_node_path14.resolve)(outputDirectory, logicalPath);
+      const outputRelativePath = (0, import_node_path14.relative)(outputDirectory, outputPath2);
+      if (!outputRelativePath || outputRelativePath.startsWith("..") || (0, import_node_path14.isAbsolute)(outputRelativePath)) {
+        throw new Error(
+          `Refusing to materialize unsafe Play source path ${JSON.stringify(logicalPath)}.`
+        );
+      }
+      (0, import_node_fs12.mkdirSync)((0, import_node_path14.dirname)(outputPath2), { recursive: true });
+      if (!(0, import_node_fs12.existsSync)(outputPath2)) {
+        (0, import_node_fs12.writeFileSync)(outputPath2, sourceCode, "utf-8");
+        created += 1;
+      } else if ((0, import_node_fs12.readFileSync)(outputPath2, "utf-8") !== sourceCode) {
+        (0, import_node_fs12.writeFileSync)(outputPath2, sourceCode, "utf-8");
+        updated += 1;
+      }
+    }
+    return {
+      path: outputDirectory,
+      status: created > 0 ? "created" : updated > 0 ? "updated" : "unchanged",
+      created: created > 0,
+      fileCount: files.length
+    };
+  }
   const outputPath = input2.outPath ?? defaultMaterializedPlayPath(input2.playName);
   if ((0, import_node_fs12.existsSync)(outputPath)) {
     const existingSource = (0, import_node_fs12.readFileSync)(outputPath, "utf-8");
-    if (existingSource === input2.sourceCode) {
+    if (existingSource === entrySource) {
       return { path: outputPath, status: "unchanged", created: false };
     }
-    (0, import_node_fs12.writeFileSync)(outputPath, input2.sourceCode, "utf-8");
+    (0, import_node_fs12.writeFileSync)(outputPath, entrySource, "utf-8");
     return { path: outputPath, status: "updated", created: false };
   }
-  (0, import_node_fs12.writeFileSync)(outputPath, input2.sourceCode, "utf-8");
+  (0, import_node_fs12.writeFileSync)(outputPath, entrySource, "utf-8");
   return { path: outputPath, status: "created", created: true };
 }
 function formatLoadedPlayMessage(materializedFile) {
@@ -22518,6 +22568,47 @@ ${PLAY_PUBLISH_USAGE}`
     jsonOutput: argsWantJson(args)
   };
 }
+var PLAY_SAVE_USAGE = "Usage: deepline plays save <play-file.ts> [--expected-artifact <hash>] [--dry-run] [--json]";
+function parsePlaySaveOptions(args) {
+  const target = args[0];
+  if (!target) throw new Error(PLAY_SAVE_USAGE);
+  if (target.startsWith("-")) {
+    throw new Error(`${PLAY_SAVE_USAGE}
+The Play file is positional.`);
+  }
+  let expectedArtifactHash;
+  let dryRun = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--expected-artifact") {
+      expectedArtifactHash = args[++index];
+      if (!expectedArtifactHash) {
+        throw new Error("--expected-artifact requires an artifact hash.");
+      }
+      continue;
+    }
+    if (arg.startsWith("--expected-artifact=")) {
+      expectedArtifactHash = arg.slice("--expected-artifact=".length);
+      if (!expectedArtifactHash) {
+        throw new Error("--expected-artifact requires an artifact hash.");
+      }
+      continue;
+    }
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--json") continue;
+    throw new Error(`Unknown option: ${arg}
+${PLAY_SAVE_USAGE}`);
+  }
+  return {
+    target,
+    expectedArtifactHash,
+    dryRun,
+    jsonOutput: argsWantJson(args)
+  };
+}
 function formatByteBudget(usedBytes, limitBytes) {
   return `${usedBytes.toLocaleString()} B / ${limitBytes.toLocaleString()} B`;
 }
@@ -22848,6 +22939,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);
@@ -22887,7 +23001,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 } : {}
@@ -23958,24 +24072,63 @@ async function handlePlayGet(args) {
   const explicitJson = args.includes("--json");
   const sourceOutput = args.includes("--source");
   const jsonOutput = sourceOutput ? explicitJson : argsWantJson(args);
+  const requestedRevisionFlags = [
+    args.includes("--working"),
+    args.includes("--live"),
+    args.includes("--revision")
+  ].filter(Boolean).length;
+  if (requestedRevisionFlags > 1) {
+    console.error("Use only one of --working, --live, or --revision <number>.");
+    return 2;
+  }
+  let sourceSelector = "working";
+  if (args.includes("--live")) {
+    sourceSelector = "live";
+  }
   let outPath = null;
+  let requestedVersion = null;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
       outPath = (0, import_node_path14.resolve)(args[++index]);
     }
+    if (arg === "--revision") {
+      const rawVersion = args[++index];
+      const version = Number(rawVersion);
+      if (!rawVersion || !Number.isInteger(version) || version < 1) {
+        console.error("--revision must be a positive integer.");
+        return 2;
+      }
+      requestedVersion = version;
+    }
+  }
+  if (requestedVersion !== null) {
+    sourceSelector = `version:${requestedVersion}`;
+  }
+  if (requestedRevisionFlags > 0 && !sourceOutput && !outPath) {
+    console.error(
+      "--working, --live, and --revision only apply when reading source with --source or --out."
+    );
+    return 2;
   }
   const playName = isFileTarget(target) ? extractPlayName((0, import_node_fs12.readFileSync)((0, import_node_path14.resolve)(target), "utf-8"), (0, import_node_path14.resolve)(target)) : parseReferencedPlayTarget2(target).playName;
-  const detail = isFileTarget(target) ? await client2.getPlay(playName) : await assertCanonicalNamedPlayReference(client2, target, {
-    command: "get"
-  });
-  const resolvedSource = detail.play.workingRevision?.sourceCode ?? detail.play.liveRevision?.sourceCode ?? detail.play.currentRevision?.sourceCode ?? detail.play.sourceCode ?? "";
-  const materializedFile = outPath ? materializeRemotePlaySource({
-    target,
+  const includeSource = sourceOutput || outPath !== null;
+  const detail = isFileTarget(target) ? await client2.getPlay(
     playName,
-    sourceCode: resolvedSource,
-    outPath
-  }) : null;
+    includeSource ? { source: sourceSelector } : void 0
+  ) : await assertCanonicalNamedPlayReference(client2, target, {
+    command: "get",
+    ...includeSource ? { source: sourceSelector } : {}
+  });
+  const source = detail.source;
+  const resolvedSource = source?.files[source.entryFile] ?? "";
+  let materializedFile = null;
+  try {
+    materializedFile = outPath && source ? materializeRemotePlaySource({ target, playName, source, outPath }) : null;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
   const loadedMessage = materializedFile ? formatLoadedPlayMessage(materializedFile) : null;
   if (jsonOutput) {
     process.stdout.write(
@@ -23996,14 +24149,20 @@ async function handlePlayGet(args) {
     return 0;
   }
   if (sourceOutput) {
-    if (!resolvedSource.trim()) {
+    if (!source || !resolvedSource.trim()) {
       console.error(`No source code available for ${playName}.`);
-      return 1;
+      return 4;
     }
     if (materializedFile) {
       console.log(loadedMessage);
       return 0;
     }
+    if (Object.keys(source.files).length > 1) {
+      console.error(
+        `Play ${playName} has ${Object.keys(source.files).length} source files. Use --out <directory> to write the complete bundle.`
+      );
+      return 2;
+    }
     process.stdout.write(resolvedSource);
     if (!resolvedSource.endsWith("\n")) {
       process.stdout.write("\n");
@@ -24073,7 +24232,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)}
 `);
@@ -24084,6 +24248,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
@@ -24113,6 +24279,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) {
@@ -24147,6 +24343,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(", ")}`);
   }
@@ -24252,6 +24454,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,
@@ -24382,6 +24586,7 @@ async function handlePlayGrep(args) {
         origin: play.origin,
         ownerType: play.ownerType,
         aliases: play.aliases,
+        toolCategories: play.toolCategories,
         inputSchema: play.inputSchema,
         outputSchema: play.outputSchema
       },
@@ -24479,6 +24684,128 @@ async function handlePlayDescribe(args) {
   printPlayDescription(play);
   return 0;
 }
+async function handlePlaySave(args) {
+  let options;
+  try {
+    options = parsePlaySaveOptions(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
+  if (!isFileTarget(options.target)) {
+    console.error(
+      "plays save requires a local .play.ts file. Use plays publish <play-name> to promote an existing saved revision."
+    );
+    return 2;
+  }
+  let graph;
+  try {
+    graph = await traceCliSpan(
+      "cli.play_save_bundle_graph",
+      { targetKind: "file" },
+      () => collectBundledPlayGraph((0, import_node_path14.resolve)(options.target))
+    );
+    assertBundledPlayGraphDescriptions(graph);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 7;
+  }
+  const playName = graph.root.playName ?? extractPlayName(graph.root.sourceCode, graph.root.filePath);
+  const artifactHash = graph.root.artifact.artifactHash;
+  if (options.expectedArtifactHash && options.expectedArtifactHash !== artifactHash) {
+    const result = {
+      ok: false,
+      code: "PLAY_ARTIFACT_HASH_MISMATCH",
+      message: "Refusing to save: the local file no longer produces the artifact checked earlier.",
+      expectedArtifactHash: options.expectedArtifactHash,
+      currentArtifactHash: artifactHash,
+      next: `deepline plays check ${shellQuote2(options.target)}`
+    };
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+    } else {
+      console.error(result.message);
+      console.error(`  checked artifact: ${result.expectedArtifactHash}`);
+      console.error(`  current artifact: ${result.currentArtifactHash}`);
+      console.error(`  run: ${result.next}`);
+    }
+    return 7;
+  }
+  const dryRun = {
+    ok: true,
+    dryRun: true,
+    name: playName,
+    sourcePath: graph.root.filePath,
+    sourceHash: graph.root.artifact.sourceHash,
+    artifactHash,
+    graphHash: graph.root.artifact.graphHash,
+    sourceFileCount: Object.keys(graph.root.sourceFiles).length,
+    plannedMutation: "save or update the mutable working draft; does not change the live revision"
+  };
+  if (options.dryRun) {
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(dryRun)}
+`);
+    } else {
+      console.log(`Dry run: ${playName}`);
+      console.log(`  source: ${dryRun.sourceHash}`);
+      console.log(`  artifact: ${dryRun.artifactHash}`);
+      console.log(`  would: ${dryRun.plannedMutation}`);
+    }
+    return 0;
+  }
+  const client2 = new DeeplineClient();
+  try {
+    await traceCliSpan(
+      "cli.play_save_compile_manifests",
+      { targetKind: "file", nodeCount: graph.nodes.size },
+      () => compileBundledPlayGraphManifests(client2, graph)
+    );
+    const saved = await traceCliSpan(
+      "cli.play_save_register_draft",
+      { targetKind: "file", playName, artifactHash },
+      () => client2.registerPlayArtifact({
+        name: playName,
+        sourceCode: graph.root.sourceCode,
+        sourceFiles: graph.root.sourceFiles,
+        description: graph.root.playDescription ?? void 0,
+        artifact: graph.root.artifact,
+        compilerManifest: requireCompilerManifest(graph.root),
+        publish: false
+      })
+    );
+    const result = {
+      success: true,
+      name: playName,
+      draft: true,
+      revisionId: saved.revisionId ?? null,
+      version: saved.version ?? null,
+      sourceHash: graph.root.artifact.sourceHash,
+      artifactHash,
+      graphHash: graph.root.artifact.graphHash,
+      artifactStorageKey: saved.artifactStorageKey,
+      next: {
+        publish: `deepline plays publish ${shellQuote2(options.target)} --expected-artifact ${artifactHash}`,
+        get: `deepline plays get ${playName} --source --out ./${playName}/ --working`
+      }
+    };
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+    } else {
+      console.log(
+        `\u2713 Saved ${playName} working draft as v${result.version ?? "?"}`
+      );
+      console.log("  Live revision unchanged.");
+      console.log(`  publish: ${result.next.publish}`);
+    }
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 5;
+  }
+}
 async function handlePlayPublish(args) {
   let options;
   try {
@@ -25009,7 +25336,9 @@ Pass-through input flags:
     ]);
   });
   registerPlayBootstrapCommand(play);
-  play.command("get <target>").description("Fetch full play details.").addHelpText(
+  play.command("get <target>").description(
+    "Fetch full play details or materialize a saved source bundle."
+  ).addHelpText(
     "after",
     `
 Notes:
@@ -25021,17 +25350,24 @@ Examples:
   deepline plays get prebuilt/person-linkedin-to-email
   deepline plays get prebuilt/person-linkedin-to-email --json | jq '.play.liveRevision'
   deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source > email-waterfall.play.ts
-  deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source --out ./email-waterfall.play.ts
+  deepline plays get my-play --source --out ./my-play/ --working
+  deepline plays get my-play --source --out ./my-play-v3/ --revision 3
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
     "--source",
-    "Print raw source code; combine with --out to write a file"
-  ).option("--out <path>", "Write source to a specific path").action(async (target, options) => {
+    "Read source; prints single-file Plays or combines with --out to write the full bundle"
+  ).option(
+    "--out <path>",
+    "Write source to a file or, for multi-file Plays, a directory"
+  ).option("--working", "Read the current working draft source (default)").option("--live", "Read the live revision source").option("--revision <number>", "Read a specific revision source").action(async (target, options) => {
     process.exitCode = await handlePlayGet([
       target,
       ...options.json ? ["--json"] : [],
       ...options.source ? ["--source"] : [],
-      ...options.out ? ["--out", options.out] : []
+      ...options.out ? ["--out", options.out] : [],
+      ...options.working ? ["--working"] : [],
+      ...options.live ? ["--live"] : [],
+      ...options.revision ? ["--revision", options.revision] : []
     ]);
   });
   play.command("list").description("List saved and prebuilt plays.").addHelpText(
@@ -25045,11 +25381,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)"
@@ -25142,6 +25502,32 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
+  play.command("save <file>").description(
+    "Save or update a local Play working draft without publishing it."
+  ).addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state, but does not change the live revision or active triggers.
+  Repeated saves update one working draft. Publishing it, or running a named
+  draft revision, freezes it; the next save starts a new revision.
+
+Examples:
+  deepline plays save ./company-research.play.ts
+  deepline plays save ./company-research.play.ts --dry-run --json
+  deepline plays publish ./company-research.play.ts
+`
+  ).option("--expected-artifact <hash>", "Require the checked artifact hash").option(
+    "--dry-run",
+    "Bundle and show the planned draft save without mutation"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (file, options) => {
+    process.exitCode = await handlePlaySave([
+      file,
+      ...options.expectedArtifact ? ["--expected-artifact", options.expectedArtifact] : [],
+      ...options.dryRun ? ["--dry-run"] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
   const addPublishHelp = (command) => command.addHelpText(
     "after",
     `
@@ -26404,10 +26790,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 = [