@melius-ai/cli 0.9.1 → 0.10.0

package/README.md

@@ -203,6 +203,31 @@ mel preset apply <canvasId> <presetId>
 mel bulk-run start <canvasId> --wait
 ```
 
+### Templates
+
+Templates are reusable workflows applied server-side as collapsed boxes. Listing includes global templates and templates scoped to the current team. The CLI exposes only template metadata, declared ports, and the applied box IDs; internal workflow nodes and configuration stay private.
+
+| Command                                      | Description                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------ |
+| `mel template list`                          | List available templates and their declared input/output ports           |
+| `mel template apply <canvasId> <templateId>` | Apply a template as one collapsed box and return `instanceId`, `groupId` |
+
+```bash
+# Discover templates and ports
+mel template list
+mel template list --fields id,title,inputPorts,outputPorts
+
+# Apply with automatic placement
+mel template apply <canvasId> <templateId>
+
+# Materialize a text input while applying
+mel template apply <canvasId> <templateId> \
+  --inputs '[{"kind":"text","portId":"<portId>","text":"A red shoe"}]'
+
+# Run only the opaque template box
+mel bulk-run start <canvasId> --node-ids <groupId> --wait
+```
+
 ### Models
 
 | Command                                          | Description                                                   |

package/dist/bin/mel.js

@@ -7,7 +7,7 @@ import {
   printUpgradeNoticeIfNeeded,
   withDefaultHelp,
   writeError
-} from "../chunk-WRLYKNYI.js";
+} from "../chunk-GEI5UAWV.js";
 
 // bin/mel.ts
 var program = createProgram();

package/dist/{chunk-WRLYKNYI.js → chunk-GEI5UAWV.js}

@@ -8647,12 +8647,17 @@ var AgentMessageFeedbackResponseSchema = external_exports.object({
   createdAt: external_exports.string().datetime()
 });
 var AgentSessionStatusSchema = external_exports.enum(["active", "ended", "error"]);
+var AgentSessionSourceSchema = external_exports.enum(["web", "slack"]);
 var AgentSessionResponseSchema = external_exports.object({
   id: external_exports.string().uuid(),
   userId: external_exports.string().uuid(),
   teamId: external_exports.string().uuid(),
   title: external_exports.string(),
   status: AgentSessionStatusSchema,
+  /** Optional so web clients remain compatible with servers that predate session sources. */
+  source: AgentSessionSourceSchema.optional(),
+  /** True when this transcript is view-only on the current surface. */
+  readOnly: external_exports.boolean().optional(),
   /** True when the agent is actively generating a response. */
   isGenerating: external_exports.boolean(),
   /** Present when the session is waiting for the user to approve a tool call. */
@@ -8781,6 +8786,28 @@ var agentContract = c3.router({
     },
     summary: "Get an agent session with recent messages"
   },
+  getInternalDemoCanvasSession: {
+    method: "GET",
+    path: "/agent/internal-demo-canvas-sessions/:sessionId",
+    pathParams: external_exports.object({ sessionId: external_exports.string().uuid() }),
+    query: external_exports.object({
+      messageLimit: external_exports.coerce.number().int().min(0).max(100).default(50)
+    }),
+    responses: {
+      200: AgentSessionResponseSchema
+    },
+    summary: "Get an internal demo canvas Slack transcript"
+  },
+  forkInternalDemoCanvasSession: {
+    method: "POST",
+    path: "/agent/internal-demo-canvas-sessions/:sessionId/fork",
+    pathParams: external_exports.object({ sessionId: external_exports.string().uuid() }),
+    body: null,
+    responses: {
+      201: AgentSessionResponseSchema
+    },
+    summary: "Fork an internal demo canvas Slack transcript into a private agent session"
+  },
   renameSession: {
     method: "PATCH",
     path: "/agent/sessions/:sessionId",
@@ -10221,7 +10248,21 @@ var PreviewAssetSchema = external_exports.object({
   thumbnailUrl: external_exports.string().nullable()
 });
 
+// ../api-contract/src/template-port-summary.ts
+var TemplatePortSummarySchema = external_exports.object({
+  id: external_exports.string(),
+  direction: external_exports.enum(["input", "output"]),
+  label: external_exports.string(),
+  handleType: external_exports.string(),
+  required: external_exports.boolean().optional(),
+  maxConnections: external_exports.number().int().positive().optional(),
+  outputAspectRatio: external_exports.enum(ASPECT_RATIOS).nullable().optional(),
+  exampleAssetUrl: external_exports.string().nullable().optional(),
+  exampleText: external_exports.string().nullable().optional()
+});
+
 // ../api-contract/src/templates-ports.ts
+var TEMPLATE_EXAMPLE_TEXT_MAX_LENGTH = 2e3;
 var TemplatePortBaseFields = {
   /** Stable handle id on the box, e.g. "in_character", "out_angle_1". */
   id: external_exports.string(),
@@ -10238,7 +10279,25 @@ var TemplatePortBaseFields = {
    */
   internalHandle: external_exports.string().nullable(),
   /** Optional vertical position override on the box (e.g. "35%"). */
-  top: external_exports.string().optional()
+  top: external_exports.string().optional(),
+  /**
+   * Example media for a MEDIA port (image/video/audio input source or output
+   * result), shown in the template details panel and the build/edit authoring
+   * UIs. `exampleAssetKey` is the persisted ref: an S3 object key under
+   * `template-examples/`, copied at capture so the example outlives the source
+   * canvas — exactly like `previewImageUrl`. `exampleAssetUrl` is the
+   * freshly-signed display URL, populated on read only and ignored on write.
+   * Both absent when the port has no media example (unset, or a text port).
+   */
+  exampleAssetKey: external_exports.string().nullable().optional(),
+  exampleAssetUrl: external_exports.string().nullable().optional(),
+  /**
+   * Example prompt for a TEXT port — the text parallel of `exampleAssetKey`.
+   * Stored inline (no S3, no signing) since it's just a string; the details
+   * panel shows it truncated, and "use example as input" drops a text node
+   * pre-filled with it. Absent for media ports and text ports with no example.
+   */
+  exampleText: external_exports.string().max(TEMPLATE_EXAMPLE_TEXT_MAX_LENGTH).nullable().optional()
 };
 var TemplatePortTargetSchema = external_exports.object({
   nodeKey: external_exports.string(),
@@ -10336,15 +10395,6 @@ var InstancePortBindingSchema = external_exports.discriminatedUnion("direction",
     ...InstancePortBindingBaseFields
   })
 ]);
-var TemplatePortSummarySchema = external_exports.object({
-  id: external_exports.string(),
-  direction: external_exports.enum(["input", "output"]),
-  label: external_exports.string(),
-  handleType: external_exports.string(),
-  required: external_exports.boolean().optional(),
-  maxConnections: external_exports.number().int().positive().optional(),
-  outputAspectRatio: external_exports.enum(ASPECT_RATIOS).nullable().optional()
-});
 
 // ../api-contract/src/canvas.ts
 var c7 = initContract();
@@ -11286,7 +11336,33 @@ var CanvasSettingsResponseSchema = external_exports.object({
   createdAt: external_exports.string().datetime(),
   updatedAt: external_exports.string().datetime()
 });
+var PlaygroundCanvasReferenceSchema = external_exports.object({
+  projectId: external_exports.string().uuid(),
+  canvasId: external_exports.string().uuid()
+});
+var PlaygroundCanvasPageSchema = external_exports.object({
+  projectId: external_exports.string().uuid().nullable(),
+  data: external_exports.array(external_exports.object({ id: external_exports.string().uuid() })),
+  total: external_exports.number().int().nonnegative()
+});
 var canvasContract = c7.router({
+  createPlaygroundCanvas: {
+    method: "POST",
+    path: "/playground/canvases",
+    body: null,
+    responses: {
+      201: PlaygroundCanvasReferenceSchema,
+      409: MessageResponseSchema
+    }
+  },
+  listPlaygroundCanvases: {
+    method: "GET",
+    path: "/playground/canvases",
+    query: external_exports.object({
+      ...paginationQuery({ maxLimit: 100, defaultLimit: 25 })
+    }),
+    responses: { 200: PlaygroundCanvasPageSchema }
+  },
   createCanvas: {
     method: "POST",
     path: "/projects/:projectId/canvases",
@@ -13816,8 +13892,81 @@ var projectContract = c14.router({
   }
 });
 
+// ../api-contract/src/template-apply-input.ts
+var TemplateApplyInputSchema = external_exports.discriminatedUnion("kind", [
+  external_exports.object({
+    kind: external_exports.literal("asset"),
+    portId: external_exports.string(),
+    assetId: external_exports.string().uuid(),
+    mediaType: external_exports.enum(["image", "video", "audio", "pdf"])
+  }),
+  external_exports.object({
+    kind: external_exports.literal("text"),
+    portId: external_exports.string(),
+    text: external_exports.string().min(1)
+  })
+]);
+
+// ../api-contract/src/template-public-api.ts
+var TemplateResponseSchema = external_exports.object({
+  id: external_exports.string(),
+  title: external_exports.string(),
+  groupLabel: external_exports.string(),
+  icon: external_exports.string(),
+  description: external_exports.string(),
+  previewImageUrl: external_exports.string().nullable(),
+  previewVideoUrl: external_exports.string().nullable().optional(),
+  inputPorts: external_exports.array(TemplatePortSummarySchema),
+  outputPorts: external_exports.array(TemplatePortSummarySchema),
+  canEdit: external_exports.boolean(),
+  isGlobal: external_exports.boolean().optional(),
+  authorName: external_exports.string().nullable().optional(),
+  estimatedCreditCost: external_exports.number().optional(),
+  tags: external_exports.array(external_exports.string()).optional()
+});
+var PublicApplyTemplateResponseSchema = external_exports.object({
+  /** The created template instance id. */
+  instanceId: external_exports.string(),
+  /** The collapsed group id shown on the canvas. */
+  groupId: external_exports.string()
+});
+var ApplyTemplateBodySchema = external_exports.object({
+  canvasId: external_exports.string().uuid(),
+  templateId: external_exports.string().uuid(),
+  /** Box center X. Auto-positioned to avoid existing nodes if omitted. */
+  centerX: external_exports.number().optional(),
+  /** Box center Y. Auto-positioned to avoid existing nodes if omitted. */
+  centerY: external_exports.number().optional(),
+  /** Optional input values materialized with the template instance. */
+  inputs: external_exports.array(TemplateApplyInputSchema).optional()
+});
+var templateListRoute = {
+  method: "GET",
+  path: "/templates",
+  responses: {
+    200: external_exports.object({
+      data: external_exports.array(TemplateResponseSchema)
+    })
+  },
+  summary: "List available templates (active)"
+};
+var templateApplyRouteBase = {
+  method: "POST",
+  path: "/templates/apply",
+  body: ApplyTemplateBodySchema,
+  summary: "Apply a template as a collapsed canvas box"
+};
+var publicTemplateApplyRoute = {
+  ...templateApplyRouteBase,
+  responses: {
+    200: PublicApplyTemplateResponseSchema,
+    404: MessageResponseSchema
+  }
+};
+
 // ../api-contract/src/upload.ts
 var c15 = initContract();
+var PdfExtractionModeSchema = external_exports.enum(["summary", "pages"]);
 var InitUploadBodySchema = external_exports.object({
   nodeId: external_exports.string().uuid().optional(),
   filename: external_exports.string(),
@@ -13877,7 +14026,10 @@ var CompleteUploadBodySchema = external_exports.object({
   // edit/upstream change to keep `src` fresh for downstream nodes; those
   // background refreshes set this so they don't mint a new version each time.
   // Explicit user saves omit it and fork a new version as usual.
-  replaceActiveVersion: external_exports.boolean().optional()
+  replaceActiveVersion: external_exports.boolean().optional(),
+  // PDF-only: how to process the upload once complete. Omitted ⇒ "summary"
+  // (the server default and every non-PDF upload). See PdfExtractionModeSchema.
+  pdfExtractionMode: PdfExtractionModeSchema.optional()
 });
 var CompleteUploadResponseSchema = external_exports.object({
   success: external_exports.boolean(),
@@ -13998,6 +14150,10 @@ var publicContract = c16.router(
     preset: {
       list: presetsContract.listPresets
     },
+    template: {
+      list: templateListRoute,
+      apply: publicTemplateApplyRoute
+    },
     team: {
       list: teamContract.listMyTeams
     },
@@ -14249,7 +14405,7 @@ function isMajorUpgrade(current, latest) {
   return l[0] > c17[0];
 }
 function shouldShowUpgradeNotice(ctx = {}) {
-  const current = ctx.current ?? "0.9.1";
+  const current = ctx.current ?? "0.10.0";
   const latest = ctx.latest ?? serverLatestVersion;
   const env = ctx.env ?? process.env;
   const isTty = ctx.isTty ?? Boolean(process.stderr.isTTY);
@@ -14270,7 +14426,7 @@ Upgrade: npm install -g @melius-ai/cli@latest  (or: brew update && brew upgrade
 function printUpgradeNoticeIfNeeded(ctx = {}) {
   try {
     if (!shouldShowUpgradeNotice(ctx)) return;
-    const current = ctx.current ?? "0.9.1";
+    const current = ctx.current ?? "0.10.0";
     const latest = ctx.latest ?? serverLatestVersion;
     process.stderr.write(formatUpgradeNotice(current, latest));
   } catch {
@@ -15302,14 +15458,27 @@ function shiftToAvoidExisting(result, allNodes, targetIds, allEdges = []) {
   }));
   const existingIds = new Set(otherNodes.map((n) => n.id));
   const nodeById = new Map(allNodes.map((n) => [n.id, n]));
+  function resolveTopLevelNodeId(id) {
+    let resolvedId = id;
+    const seen = /* @__PURE__ */ new Set();
+    while (!seen.has(resolvedId)) {
+      seen.add(resolvedId);
+      const parentId2 = nodeById.get(resolvedId)?.groupId;
+      if (!parentId2) break;
+      resolvedId = parentId2;
+    }
+    return resolvedId;
+  }
   const incomingSourceIds = /* @__PURE__ */ new Set();
   const outgoingTargetIds = /* @__PURE__ */ new Set();
   for (const edge of allEdges) {
-    if (existingIds.has(edge.srcNodeId) && targetIds.has(edge.dstNodeId)) {
-      incomingSourceIds.add(edge.srcNodeId);
+    const srcNodeId = resolveTopLevelNodeId(edge.srcNodeId);
+    const dstNodeId = resolveTopLevelNodeId(edge.dstNodeId);
+    if (existingIds.has(srcNodeId) && targetIds.has(dstNodeId)) {
+      incomingSourceIds.add(srcNodeId);
     }
-    if (targetIds.has(edge.srcNodeId) && existingIds.has(edge.dstNodeId)) {
-      outgoingTargetIds.add(edge.dstNodeId);
+    if (targetIds.has(srcNodeId) && existingIds.has(dstNodeId)) {
+      outgoingTargetIds.add(dstNodeId);
     }
   }
   const SCATTER_THRESHOLD = 3;
@@ -18816,6 +18985,120 @@ Examples:
   );
 }
 
+// src/commands/template.ts
+function parseCoordinate(value, option) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (Number.isFinite(parsed)) return parsed;
+  writeError(
+    formatError("USAGE_ERROR", `${option} must be a finite number`, {
+      suggestion: `Provide ${option} <number> or omit it for automatic placement`
+    }),
+    EXIT_USAGE_ERROR
+  );
+}
+function parseInputs(value) {
+  if (value === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    writeError(
+      formatError("USAGE_ERROR", "Invalid JSON in --inputs", {
+        suggestion: `--inputs must be a JSON array, for example '[{"kind":"text","portId":"prompt","text":"A red shoe"}]'`
+      }),
+      EXIT_USAGE_ERROR
+    );
+  }
+  const result = TemplateApplyInputSchema.array().safeParse(parsed);
+  if (result.success) return result.data;
+  writeError(
+    formatError(
+      "USAGE_ERROR",
+      result.error.issues.map((issue) => issue.message).join("; "),
+      {
+        suggestion: 'Use text inputs {"kind":"text","portId":"<portId>","text":"<text>"} or asset inputs {"kind":"asset","portId":"<portId>","assetId":"<assetId>","mediaType":"image|video|audio|pdf"}'
+      }
+    ),
+    EXIT_USAGE_ERROR
+  );
+}
+function registerTemplateCommands(program2, getOutputOpts) {
+  const template = program2.command("template").description("List and apply opaque canvas workflow templates");
+  template.command("list").description(
+    "List available templates with display metadata and declared input/output ports"
+  ).addHelpText(
+    "after",
+    `
+Returns: Array of templates with id, title, description, previewImageUrl, inputPorts, outputPorts, and estimatedCreditCost.
+Includes global templates and templates scoped to the current team.
+The template's internal workflow stays private. Use a returned id with mel template apply.
+
+Examples:
+  $ mel template list
+  $ mel template list --fields id,title,inputPorts,outputPorts`
+  ).action(async () => {
+    const client = getClient();
+    const result = await client.template.list();
+    if (result.status !== 200) {
+      handleApiError(result.status, result.body);
+    }
+    writeJson(result.body.data, getOutputOpts());
+  });
+  template.command("apply").description(
+    "Apply a template to a canvas as one collapsed box and return its instanceId and groupId"
+  ).argument(
+    "<canvasId>",
+    "Canvas ID (from mel canvas create or mel canvas list output)"
+  ).argument("<templateId>", "Template ID (from mel template list output)").option(
+    "--center-x <number>",
+    "X center for the template box. Omit for automatic non-overlapping placement"
+  ).option(
+    "--center-y <number>",
+    "Y center for the template box. Omit for automatic non-overlapping placement"
+  ).option(
+    "--inputs <json>",
+    "JSON array of text or library-asset inputs targeting port IDs from mel template list"
+  ).addHelpText(
+    "after",
+    `
+Returns: { instanceId, groupId }. Internal workflow node IDs are never returned.
+Input kinds: text {kind,portId,text}; asset {kind,portId,assetId,mediaType} where mediaType is image, video, audio, or pdf.
+Omit --center-x/--center-y to place the box automatically. Use mel canvas content <canvasId> afterward to inspect its public ports.
+Run the applied template with mel bulk-run start <canvasId> --node-ids <groupId> --wait.
+
+Examples:
+  $ mel template apply <canvasId> <templateId>
+  $ mel template apply <canvasId> <templateId> --inputs '[{"kind":"text","portId":"<portId>","text":"A red shoe"}]'
+  $ mel bulk-run start <canvasId> --node-ids <groupId> --wait`
+  ).action(
+    async (canvasId, templateId, opts) => {
+      const client = getClient();
+      const centerX = parseCoordinate(opts.centerX, "--center-x");
+      const centerY = parseCoordinate(opts.centerY, "--center-y");
+      const inputs = parseInputs(opts.inputs);
+      const result = await client.template.apply({
+        body: {
+          canvasId,
+          templateId,
+          ...centerX !== void 0 && { centerX },
+          ...centerY !== void 0 && { centerY },
+          ...inputs !== void 0 && { inputs }
+        }
+      });
+      if (result.status !== 200) {
+        handleApiError(
+          result.status,
+          result.body,
+          "Run: mel template list"
+        );
+      }
+      const { instanceId, groupId } = result.body;
+      writeJson({ instanceId, groupId }, getOutputOpts());
+    }
+  );
+}
+
 // src/lib/upload.ts
 import * as fs3 from "fs";
 import * as path3 from "path";
@@ -19271,7 +19554,7 @@ function withDefaultHelp(args) {
 }
 function createProgram() {
   const program2 = new Command();
-  program2.name("mel").description("Mel \u2014 Melius agent CLI").version("0.9.1").showSuggestionAfterError(true).option("--json", "Force JSON output (default)").option("--text", "Human-readable output").option(
+  program2.name("mel").description("Mel \u2014 Melius agent CLI").version("0.10.0").showSuggestionAfterError(true).option("--json", "Force JSON output (default)").option("--text", "Human-readable output").option(
     "--fields <fields>",
     "Select specific output fields (comma-separated)"
   ).option("--quiet", "Suppress output, exit code only").option("--verbose", "Log request/response metadata to stderr").addHelpText(
@@ -19310,6 +19593,7 @@ Learn more: https://docs.melius.com`
   registerAudioCommands(program2, getOutputOpts);
   registerFontCommands(program2, getOutputOpts);
   registerPresetCommands(program2, getOutputOpts);
+  registerTemplateCommands(program2, getOutputOpts);
   registerConfigCommands(program2, getOutputOpts);
   if (false) {
     registerSkillCommands(program2, getOutputOpts);

package/dist/src/index.js

@@ -2,7 +2,7 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 import {
   createProgram,
   withDefaultHelp
-} from "../chunk-WRLYKNYI.js";
+} from "../chunk-GEI5UAWV.js";
 export {
   createProgram,
   withDefaultHelp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melius-ai/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "The Melius command-line interface — create canvases and run AI image/video generations from your terminal",
   "keywords": [
     "ai",