@meistrari/tela-cli 1.4.0 → 1.5.0

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

@@ -16,11 +16,13 @@ import {
     code,
     crop,
     docTemplate,
+    condition,
     input,
     llm,
     splitter,
     vault,
     remote,
+    stop,
     workflow,
 } from '@meistrari/workflow-code'
 import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
@@ -43,6 +45,8 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
 | [`agent(remoteRef, options)`](#agentremoteref-options) | Published-Agent calls from the remote catalog. |
 | [`code()`](#codeoptions) | Sandboxed runtime JavaScript/TypeScript execution. |
+| [`condition()`](#conditionoptions) | Synchronous predicate branches with compiler-owned V3 branch ports. |
+| [`stop()`](#stop) | Terminal leaf allowed only as the final direct node of a condition branch. |
 | [`ref()` / `paths()` / `formats()`](#references-ref-paths-and-formats) | References to workflow inputs or prior node output in prompt callbacks and code handlers. |
 
 A workflow file normally creates inputs, creates nodes, then default-exports `build(workflow(...), { inputs, nodes })`.
@@ -177,6 +181,7 @@ const normalizeInvoice = code({
 Reference rules:
 
 - References in node inputs may target workflow inputs or earlier nodes.
+- `condition()` and `stop()` are compiler-owned topology nodes and do not produce output references.
 - `paths()` only accepts node declarations, not inputs.
 - Path tokens are branded; do not replace them with strings or arrays.
 - A path token must come from the same node used in `ref()`, or authoring throws `ref path source must match ref target`.
@@ -743,6 +748,38 @@ Avoid these patterns:
 - Forward references to later nodes.
 - Declaring generated-reserved names such as `execute` or `TelaInput` in extracted handler/helper/type code.
 
+### `condition(options)`
+
+```ts
+const route = condition({
+    cases: {
+        approved: {
+            when: ({ ref, paths }) =>
+                ref(classify, paths(classify).status) === 'approved',
+            nodes: [approveInvoice],
+        },
+    },
+    default: { nodes: [manualReview] },
+})
+```
+
+Declares a Workflow V3 condition. `cases` are evaluated in authored object insertion order; array-index names like `"0"` are rejected. Each named case has a synchronous boolean `when` predicate and ordered branch `nodes`. The optional `default` has only `nodes`.
+
+The compiler extracts predicate source without executing it, copies supported source-visible helpers and local imports, rewrites `ref()` reads to runtime inputs, and emits guarded JavaScript for the V3 condition action. V3 `steps`, branch `portId`s, node IDs, and graph edges are always compiler-owned.
+
+### `stop()`
+
+```ts
+const route = condition({
+    cases: {
+        duplicate: { when: () => true, nodes: [stop()] },
+    },
+    default: { nodes: [continueProcessing] },
+})
+```
+
+Declares a terminal Workflow V3 stop node. It is valid only as the final direct node in a `condition()` case or default branch. A stopped branch does not converge to the next node; normal and empty sibling branches still converge. `stop()` at the workflow root, inside a map body, or before another direct branch node reports `compiler.stop.invalid_placement`.
+
 ### Config and shared types
 
 These types are exported for config files and integrations. See [Config](/docs/config) for full examples.

package/dist/docs/workflow-code/cli.md

@@ -72,6 +72,8 @@ tela workflow init --workflow invoice-processing --yes --json
 
 **Description.** `tela workflow compile` loads config, loads dotenv files, evaluates the TypeScript entrypoint, validates declarations, and returns deterministic Workflow V3 graph, payload, hashes, and diagnostics. It does not require or validate remote `projectId`/`promptId`, write lockfiles, sync remote content, or publish.
 
+`compile` stays offline. For a workflow that declares `vault.asset()`, it can lower the asset only when the active-context lockfile already contains the matching uploaded `vault://...` ref. Otherwise it reports `vault.asset.missing_lock`. Compile never reads the asset file, uploads it, refreshes the lock, or contacts Vault; run `sync` first to create or refresh that lock.
+
 | Prop | Type | Required | Description |
 |---|---|---:|---|
 | `target` | Positional | No | Config `workflows` key to compile. Required when more than one workflow is configured. |
@@ -132,6 +134,8 @@ tela workflow codegen --json
 
 **Description.** `tela workflow sync` compiles local source, resolves the active Tela Local context, selects the matching `projectId` and `promptId`, verifies remote content, and writes per-context lockfile state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`.
 
+For `vault.asset()` declarations, sync validates that each local path is a regular file within the project directory, hashes its content, and reuses a matching active-context asset lock when possible. New or changed assets are uploaded and recorded as `vault://...` refs before sync performs its final resolved compilation or any workflow lifecycle mutation. This makes later offline `compile` runs deterministic; a changed asset is uploaded again on the next sync.
+
 Sync uses a consolidated version strategy. The compiled workflow becomes the complete source of truth for the next remote version: source files, hashes, lifecycle payload, package metadata, and binding metadata are consolidated into one prompt version snapshot. When compiled content changed, sync creates a new non-draft version. The only exception is a verified no-op: if local hashes already match the active-context lockfile and fresh remote content confirms the same version, sync returns without creating a version.
 
 Consolidated versions make sync safe to repeat. A sync never edits an existing version in place, never mutates a draft, and never changes the previous consolidated version. If the workflow is currently pointing at a draft version, sync leaves that draft untouched and creates a new consolidated non-draft version for the compiled workflow instead.

package/dist/docs/workflow-code/guides.md

@@ -26,6 +26,17 @@ src/workflows/shared.ts
 | `src/workflows/prompts.ts` | Prompt strings and small prompt helpers. |
 | `src/workflows/shared.ts` | Pure utilities reused by declarations or code handlers. |
 
+### Generate remote authoring metadata
+
+Run `codegen` before typechecking workflow source that uses named `remote()` catalog paths. It refreshes the active Tela Local context's catalog and writes the TypeScript augmentation used for remote authoring. `codegen` is workspace-scoped: it does not take a workflow target, load `workflow-code.config.ts`, compile a workflow, or mutate Tela resources.
+
+```bash
+pnpm exec tela workflow codegen --json > .tela/codegen-result.json
+node -e "const r=require('./.tela/codegen-result.json'); if (!r.success || r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
+```
+
+With credentials, codegen refreshes the catalog. When that refresh is unavailable, it can use only a complete cached snapshot for the same active context and workspace; inspect its warning diagnostics and `fetchedAt` before relying on the generated names.
+
 ### CI compile check
 
 Use `compile --json` in CI to validate source and fail on error diagnostics before any remote lifecycle command runs.
@@ -37,7 +48,9 @@ pnpm exec tela workflow compile demo --env .env.ci --json > .tela/compile-result
 node -e "const r=require('./.tela/compile-result.json'); if (r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
 ```
 
-For trusted release jobs with Tela credentials, run sync after compile:
+`compile` does not upload local `vault.asset()` files. An asset workflow needs an uploaded ref in the active-context lockfile or compile reports `vault.asset.missing_lock`. Do not use a compile-only job to bootstrap those locks.
+
+For trusted release jobs with Tela credentials, run sync. It reuses unchanged asset hashes, uploads new or changed assets, records their Vault refs in the context lockfile, then performs final resolved compilation before the workflow lifecycle mutation:
 
 ```bash
 pnpm exec tela workflow sync --env .env.ci --yes --json > .tela/sync-result.json
@@ -48,9 +61,11 @@ Commit stable context lockfiles such as `.tela/workflows/*/contexts/*/lock.json`
 
 ### Troubleshooting diagnostics
 
-When `compile` or `sync` fails, read diagnostic `code` and `hint` first. Most failures point to config shape, missing env files, unresolved entry paths, invalid references, `workflowKey` mismatches, unsupported `code()` extraction patterns, missing `promptId`, active-context binding mismatches, or remote divergence.
+When `codegen`, `compile`, or `sync` fails, read diagnostic `code` and `hint` first. Most failures point to config shape, missing env files, unresolved entry paths, invalid references, `workflowKey` mismatches, unsupported `code()` extraction patterns, missing `promptId`, active-context binding mismatches, Vault asset locks/uploads, or remote divergence.
 
+- Use `tela workflow codegen --json` to refresh remote authoring metadata or inspect matching-context cached-fallback diagnostics.
 - Use `tela workflow compile --json` for declaration and graph diagnostics.
 - Use `tela context current --json` when `sync` selects an unexpected context binding.
+- Run `tela workflow sync` when `compile` reports `vault.asset.missing_lock`; sync uploads and locks the local asset before its final resolved compile.
 - Pass `--yes` only in trusted non-interactive jobs where consolidating a newer remote version is expected.
 - Keep code handlers source-visible and avoid dynamic imports, runtime-created closure values, and reserved generated names.

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

@@ -14,13 +14,13 @@
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "380cf0c8543400f6fd311936f1b4fb984f12d27b0472213b8a2b431405f0755e"
+      "sha256": "f601e98f0c63812dc0979473c5476b35709f6c8ff70e6de131674503d9cfbe59"
     },
     {
       "slug": "cli",
       "title": "CLI",
       "file": "cli.md",
-      "sha256": "759db330fd7b06859e55404f01feb0625a43bb579324fe011bc34cd92d517239"
+      "sha256": "ef7975ab0a915f6a57aa869713e0134478751e9814ac0b2f40d137c85f8ad581"
     },
     {
       "slug": "config",
@@ -32,7 +32,7 @@
       "slug": "guides",
       "title": "Guides",
       "file": "guides.md",
-      "sha256": "b3f2ff1ac03f3829b6c5614ecc61229e181179dd2506684fae073075748359cb"
+      "sha256": "4109cef4376315b99cbee2d763c927c3148ed889b8602f958fb785faebaf8e03"
     },
     {
       "slug": "installation",