@meistrari/tela-cli 1.2.1 → 1.4.0

package/dist/docs/workflow-code/api-reference.md

@@ -15,6 +15,7 @@ import {
     canvas,
     code,
     crop,
+    docTemplate,
     input,
     llm,
     splitter,
@@ -35,7 +36,9 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
 | [`crop()`](#cropoptions) | Cropping selected PDF pages from compatible files or existing Vault files. |
 | [`vault.asset()`](#vaultassetpath-options) | Declaring a local file that `sync` uploads and locks in Vault. |
+| [`docTemplate()`](#doctemplateoptions) | Rendering a `.docx` Vault template with keyed placeholders. |
 | [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
+| [`vault.asset()`](#vaultassetpath-options) | Declaring a local file dependency uploaded and locked by `sync`. |
 | [`remote()`](#remote) | Generated catalog paths and explicit ID refs for inert remote authoring. |
 | [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
 | [`agent(remoteRef, options)`](#agentremoteref-options) | Published-Agent calls from the remote catalog. |
@@ -491,6 +494,29 @@ function crop(options: CropOptions): CropNodeHandle
 ```
 
 Declares Workflow V3's existing `document-cropper` action. Its exclusive `input.file` supports the same compatible workflow input, prior-node output, `vault.ref()`, `vault.asset()`, and Vault-array forms as `splitter.input.file`.
+### `docTemplate(options)`
+
+```ts
+type DocTemplateOptions = {
+    name: string
+    key?: string
+    input: {
+        template: WorkflowCodeVaultSource
+            | ((context: ExclusiveRefFactoryContext) => WorkflowCodeExclusiveRef<string>)
+        placeholders?: Record<string, string | WorkflowCodeVaultSource>
+            | ((context: PromptFactoryContext) => Record<string, string | WorkflowCodeVaultSource | PromptRefValue>)
+        outputFilename: string
+        mustache?: boolean
+        createPermalink?: boolean
+        templateFilename?: string
+        templateFileSize?: number
+    }
+}
+
+function docTemplate(options: DocTemplateOptions): DocTemplateNodeHandle
+```
+
+Declares the Workflow V3 `document-templater` action. `input.template` may be a `.docx` file declared with `vault.ref()` or `vault.asset()`, or a callback reference to a text workflow input/string-compatible field from an earlier node. Placeholders are authored as a keyed object; literal strings remain literal, and compatible workflow/Vault references lower to the reference strings consumed by the runtime action.
 
 | Option | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
@@ -549,6 +575,44 @@ const selectedPages = crop({
 ```
 
 `path`, `name`, and `mimeType` must be non-empty strings when present. Offline compile without a matching explicit asset snapshot reports `vault.asset.missing_lock`; it never falls back to reading the local file. If the file changes, the next `sync` uploads the new content and updates the lock.
+| `input.template` | `WorkflowCodeVaultSource` | Yes | — | Existing `vault.ref()` or local `vault.asset()` `.docx` template. |
+| `input.template` | `WorkflowCodeVaultSource` or callback | Yes | — | Existing `vault.ref()`, local `vault.asset()`, text input ref, or string-compatible earlier-node ref containing the template Vault URL. |
+| `input.placeholders` | Record or callback | No | `{}` | Literal strings, Vault sources, text inputs, or string-compatible earlier-node fields keyed by template placeholder. |
+| `input.outputFilename` | `string` | Yes | — | Filename for the generated document. |
+| `input.mustache` | `boolean` | No | `false` | Enables the runtime action's Mustache mode. |
+| `input.createPermalink` | `boolean` | No | `false` | Requests a permalink for the rendered document. |
+| `input.templateFilename` | `string` | No | Known Vault name | Explicit `.docx` template name, validated against known metadata. |
+| `input.templateFileSize` | `number` | No | Known Vault size | Explicit byte size, validated against known metadata. |
+
+```ts
+const template = vault.asset('./templates/invoice.docx', {
+    name: 'invoice.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+})
+
+const renderInvoice = docTemplate({
+    name: 'Render invoice',
+    input: {
+        template,
+        outputFilename: 'rendered-invoice.docx',
+        placeholders: ({ ref, paths }) => ({
+            customer: ref(customerName),
+            total: ref(extractInvoice, paths(extractInvoice).total),
+            footer: 'Generated by Tela',
+        }),
+    },
+})
+
+const renderSelectedTemplate = docTemplate({
+    name: 'Render selected template',
+    input: {
+        template: ({ ref, paths }) => ref(selectTemplate, paths(selectTemplate).vaultUrl),
+        outputFilename: 'selected-template.docx',
+    },
+})
+```
+
+The returned handle exposes typed `generatedDocument`, `generatedAt`, and optional permalink fields. Before workflow mutation, `sync` uploads changed local assets, reuses matching locks, validates access to every directly used Vault ref, checks known filename/size metadata, and rejects known non-`.docx` templates. Dynamic template refs are validated for scope and string compatibility, but their runtime Vault value cannot be inspected during sync. File inputs and non-string node fields are incompatible template or placeholder references.
 
 ### `vault.ref(reference)`
 
@@ -575,6 +639,26 @@ const existingPages = splitter({
 
 During compile, a direct Vault ref used by `splitter.input.file` or `crop.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
 
+### `vault.asset(path, options)`
+
+```ts
+const vault: {
+    asset: (
+        path: string,
+        options?: { name?: string, mimeType?: string },
+    ) => WorkflowCodeVaultAsset
+}
+```
+
+Creates an inert local file declaration. Source evaluation does not read, hash, or upload the path. `sync` resolves it inside the Workflow Code project, uploads new or changed content, and persists the returned `vault://...` ref with its content hash and known metadata in the target lockfile. An unchanged asset reuses that lock.
+
+```ts
+const template = vault.asset('./templates/invoice.docx', {
+    name: 'invoice.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+})
+```
+
 ### `agent(remoteRef, options)`
 
 ```ts

package/dist/docs/workflow-code/manifest.json

@@ -14,7 +14,7 @@
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "fc121fd8c0e83e4f39ecef45b50d4fc9b0bc64888bd10d0590b3ca168af0a42d"
+      "sha256": "380cf0c8543400f6fd311936f1b4fb984f12d27b0472213b8a2b431405f0755e"
     },
     {
       "slug": "cli",