@meistrari/tela-cli 0.7.58 → 0.8.0

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

@@ -0,0 +1,69 @@
+## Config
+
+`workflow-code.config.ts` selects workflow targets, TypeScript entrypoints used by `compile`, and remote prompt bindings used by `sync`. The config is evaluated after dotenv loading, so `process.env` is available.
+
+### Basic shape
+
+```ts
+import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
+
+export default {
+    version: 1,
+    workflows: {
+        demo: {
+            entry: './src/workflows/demo.workflow.ts',
+            projectId: process.env.TELA_PROJECT_ID,
+            promptId: process.env.TELA_WORKFLOW_PROMPT_ID,
+            workflowKey: 'first-workflow',
+            contexts: {
+                development: {
+                    projectId: process.env.TELA_DEV_PROJECT_ID ?? process.env.TELA_PROJECT_ID!,
+                    promptId: process.env.TELA_DEV_PROMPT_ID,
+                },
+            },
+        },
+    },
+} satisfies WorkflowCodeConfig
+```
+
+### Config properties
+
+| Property | Required | Purpose |
+| --- | --- | --- |
+| `version` | Yes | Must be `1`. |
+| `workflows` | Yes | Map from CLI target name to workflow target. |
+| `tsconfig` | No | Optional TypeScript config path for source evaluation. |
+| `outDir` | No | Output directory for generated workflow artifacts. |
+
+### Workflow target properties
+
+| Property | Required | Purpose |
+| --- | --- | --- |
+| `entry` | Yes | Path to the workflow TypeScript entrypoint. |
+| `projectId` | No | Default Tela project id for remote lifecycle commands; not required by compile. |
+| `promptId` | No | Existing Tela prompt or workflow id for remote lifecycle commands; not required by compile. |
+| `workflowKey` | No | Expected source workflow key; compile reports an error if it disagrees with `workflow(...)`. |
+| `title` | No | Human title used by compiler metadata. |
+| `contexts` | No | Map of context name to `projectId` and `promptId` overrides for remote lifecycle commands. |
+
+### Environment variables
+
+Use `.env` files for ids that differ by workspace or deployment.
+
+```bash
+TELA_PROJECT_ID=proj_default
+TELA_WORKFLOW_PROMPT_ID=prompt_default
+TELA_DEV_PROJECT_ID=proj_development
+TELA_DEV_PROMPT_ID=prompt_development
+```
+
+Use `tela workflow compile --env .env.staging --json` to validate local workflow source. `compile` does not require or validate `projectId`/`promptId`; use `tela workflow sync demo --env .env.staging --json` when remote bindings are available. Do not print secrets or store credentials in workflow source.
+
+### Contexts
+
+Contexts can mirror Tela Dock contexts for environment-specific ids. `compile` remains local validation. `sync` resolves the active Tela Local context, chooses the matching `contexts[...]` binding, requires both `projectId` and `promptId`, and writes state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`.
+
+```bash
+tela context current --json
+tela context list --json
+```

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

@@ -0,0 +1,56 @@
+## Guides
+
+These guides collect practical conventions for source layout, CI validation, and diagnostic workflows.
+
+### Suggested scaffold
+
+Start with a small source tree that separates workflow declarations, prompt text, and shared utilities.
+
+
+
+```bash
+workflow-code.config.ts
+.env.example
+src/workflows/demo.workflow.ts
+src/workflows/prompts.ts
+src/workflows/shared.ts
+```
+
+
+
+| Path | Purpose |
+| --- | --- |
+| `workflow-code.config.ts` | Typed workflow targets and context bindings. |
+| `.env.example` | Document required project and prompt ids. |
+| `src/workflows/demo.workflow.ts` | Default-exported `build(workflow(...))` declaration. |
+| `src/workflows/prompts.ts` | Prompt strings and small prompt helpers. |
+| `src/workflows/shared.ts` | Pure utilities reused by declarations or code handlers. |
+
+### CI compile check
+
+Use `compile --json` in CI to validate source and fail on error diagnostics before any remote lifecycle command runs.
+
+```bash
+set -euo pipefail
+pnpm install --frozen-lockfile
+pnpm exec tela workflow compile demo --env .env.ci --json > .tela/compile-result.json
+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:
+
+```bash
+pnpm exec tela workflow sync --env .env.ci --yes --json > .tela/sync-result.json
+node -e "const r=require('./.tela/sync-result.json'); if (r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
+```
+
+Commit stable context lockfiles such as `.tela/workflows/*/contexts/*/lock.json` when they represent reviewed remote sync state.
+
+### 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.
+
+- Use `tela workflow compile --json` for declaration and graph diagnostics.
+- Use `tela context current --json` when `sync` selects an unexpected context binding.
+- 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/installation.md

@@ -0,0 +1,33 @@
+## Installation
+
+Workflow Code uses the `tela workflow` command group from `@meistrari/tela-cli` and the authoring/compiler package `@meistrari/workflow-code` in the repository that owns workflow source.
+
+### CLI through Tela Dock
+
+Tela Dock is the recommended source for CLI setup. It manages account login, workspace or environment context, updates, and shared local configuration used by workflow commands.
+
+```bash
+tela whoami --pretty
+tela workflow help
+```
+
+Use Dock for login and context switching instead of workflow-specific token files. Dock and CLI share local context metadata through `@meistrari/tela-local-config`; credential material remains in the OS keychain (macOS Keychain, or the Linux freedesktop Secret Service via `secret-tool`) or environment credential adapters.
+
+### Repository package
+
+Install the authoring and compiler package where workflow source lives.
+
+```bash
+pnpm add -D @meistrari/workflow-code @meistrari/tela-cli
+```
+
+Use package scripts or `pnpm exec` to invoke `tela workflow` from CI. The public workflow source imports only `@meistrari/workflow-code`.
+
+### Verification
+
+Run these checks before writing workflow source:
+
+- `tela whoami --pretty` confirms the authenticated account.
+- `tela context current --json` confirms the active local context.
+- `tela workflow help` confirms the workflow command group is routed.
+- `pnpm list @meistrari/workflow-code` confirms the authoring package is installed in the repository.

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

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@meistrari/workflow-code",
+  "packageVersion": "0.0.0",
+  "sourcePackage": "@meistrari/workflow-code-page",
+  "pages": [
+    {
+      "slug": "overview",
+      "title": "Documentation overview",
+      "file": "overview.md",
+      "sha256": "864146c6f6ef204590c4f444edb5109be08075343bd3115f1ba5bc29d70be177"
+    },
+    {
+      "slug": "api-reference",
+      "title": "API Reference",
+      "file": "api-reference.md",
+      "sha256": "bc52ff31a4fcf5b8c21cf0ddf2fc3f2ba2dcbc69b6b55302f26768fb5348b7bb"
+    },
+    {
+      "slug": "cli",
+      "title": "CLI",
+      "file": "cli.md",
+      "sha256": "321454c8359c0449261e625120e2af6960cc71460dcf9a0f929ffad58e8ab4bf"
+    },
+    {
+      "slug": "config",
+      "title": "Config",
+      "file": "config.md",
+      "sha256": "b07b91f46b4ab9a3850df58a0dec388c670771be6de0a5cf3bafd989135fe306"
+    },
+    {
+      "slug": "guides",
+      "title": "Guides",
+      "file": "guides.md",
+      "sha256": "b3f2ff1ac03f3829b6c5614ecc61229e181179dd2506684fae073075748359cb"
+    },
+    {
+      "slug": "installation",
+      "title": "Installation",
+      "file": "installation.md",
+      "sha256": "e20f15e52c519580a8260748195a3ec8f149ac15d8beb79d06bb401a5f639500"
+    },
+    {
+      "slug": "quick-start",
+      "title": "Quick start",
+      "file": "quick-start.md",
+      "sha256": "78212b3f1fa52c116e6fd9f5331edefecf1079e1073aa32673f719b44d019ce8"
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+## Documentation overview
+
+Workflow Code documentation is organized as a set of focused pages. Read the pages in order when adopting the package for the first time, or use the sidebar when you need a specific reference.
+
+### Recommended path
+
+| Page | Use it when |
+| --- | --- |
+| [Quick start](/docs/quick-start) | You want the shortest path from `tela workflow init` to local compile and explicit sync. |
+| [Installation](/docs/installation) | You need to verify Tela Dock, the `tela` CLI, or the `@meistrari/workflow-code` package. |
+| [Config](/docs/config) | You are defining `workflow-code.config.ts`, dotenv files, target ids, or context-specific bindings. |
+| [CLI](/docs/cli) | You need implemented init/compile/sync/publish behavior, target selection rules, or JSON diagnostics. |
+| [API Reference](/docs/api-reference) | You are authoring `workflow()`, `build()`, `input`, `llm`, `agent`, `code`, and references. |
+| [Guides](/docs/guides) | You want repository layout, CI compile checks, and troubleshooting patterns. |

package/dist/docs/workflow-code/quick-start.md

@@ -0,0 +1,122 @@
+## Quick start
+
+This page assumes Tela Dock already installed and authenticated the `tela` CLI. Use [Installation](/docs/installation) only when the command is unavailable or the account context is not configured.
+
+### Verify the CLI
+
+```bash
+tela whoami --pretty
+tela workflow help
+```
+
+`compile` is a local validation step. It does not create, sync, publish, or run remote workflows. `sync` writes compiled versions to configured Tela prompts, while `publish` releases a local-matching version to a workflow publication environment.
+
+### Initialize local scaffold
+
+```bash
+tela workflow init
+```
+
+`init` creates safe starter files and package scripts, reports skipped existing files, and does not call Tela APIs.
+
+### Add a minimal config
+
+```ts
+import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
+
+export default {
+    version: 1,
+    workflows: {
+        demo: {
+            entry: './src/workflows/demo.workflow.ts',
+            projectId: process.env.TELA_PROJECT_ID,
+            promptId: process.env.TELA_WORKFLOW_PROMPT_ID,
+            contexts: {
+                development: {
+                    projectId: process.env.TELA_DEV_PROJECT_ID ?? process.env.TELA_PROJECT_ID!,
+                    promptId: process.env.TELA_DEV_PROMPT_ID,
+                },
+            },
+        },
+    },
+} satisfies WorkflowCodeConfig
+```
+
+Keep the first config small: one target, one entrypoint, and environment-backed ids. Context-specific ids can override defaults when Tela Dock switches contexts.
+
+### Author a workflow
+
+```ts
+import { agent, build, code, input, llm, workflow } from '@meistrari/workflow-code'
+
+const topic = input.text({
+    name: 'topic',
+    required: true,
+    description: 'Topic the workflow should explain.',
+})
+
+const outline = llm({
+    name: 'Draft outline',
+    input: {
+        temperature: 0.2,
+        prompt: ({ ref }) => `Create a concise outline about ${ref(topic).formats().raw}.`,
+    },
+    schema: {
+        bullets: { type: 'array', items: { type: 'string' } },
+    },
+})
+
+const countBullets = code({
+    name: 'Count bullets',
+    handler: ({ ref, paths }) => {
+        const bullets = ref(outline, paths(outline).bullets) as string[]
+        return {
+            count: bullets.length,
+            firstBullet: bullets[0] ?? null,
+        }
+    },
+})
+
+const review = agent({
+    name: 'Review outline',
+    input: {
+        maxRounds: 8,
+        prompt: ({ ref, paths }) => [
+            'Review this outline for a new Tela user.',
+            `Bullets: ${ref(outline, paths(outline).bullets).formats().json}`,
+            `Bullet count: ${ref(countBullets, paths(countBullets).count).formats().json}`,
+        ].join('\n'),
+    },
+})
+
+export default build(workflow('first-workflow'), {
+    inputs: [topic],
+    nodes: [outline, countBullets, review],
+})
+```
+
+Workflow source is an inert TypeScript declaration. `build(workflow(...), { inputs, nodes })` is the default export read by `compile`. The `code()` handler is not run during compile; compile extracts supported source and lowers it into sandbox code for Workflow runtime execution.
+
+### Compile
+
+```bash
+tela workflow compile demo --json
+```
+
+Use `compile` to validate source and inspect deterministic graph, compiler payload, hashes, and diagnostics.
+
+### Sync
+
+```bash
+tela workflow sync demo --json
+```
+
+Use `sync` after review to write the compiled workflow to the configured Tela prompt for the active Tela context. Omit `demo` to sync every configured workflow. If remote content changed since the last successful sync, the CLI asks before consolidating a new version; pass `--yes` for non-interactive CI.
+
+### Publish
+
+```bash
+tela workflow publish demo --environment production --json
+```
+
+Use `publish` to release the exact version proven to match local compiled source. `production` is the default. When a selected custom environment does not exist, interactive publish asks whether to create it and defaults to no; non-interactive commands must add `--create-environment-if-missing`. The `--environment` flag selects the workflow publication environment; Tela authentication, workspace, and context still come from shared Tela Local state. Publish can perform its own sync when required, but keeping sync explicit in this quick-start flow preserves a clear review boundary before release.