@meistrari/tela-cli 0.7.55 → 0.7.56

package/dist/index.js

@@ -7749,7 +7749,7 @@ var require_env = __commonJS({
         if (!await fileExists(path)) {
           return {
             ok: false,
-            diagnostics: [(0, diagnostics_1.diagnostic)("config.env_file.missing", "error", `Workflow Code env file not found at ${path}`, "Pass an existing dotenv file with --env <path>, or omit --env to use default .env loading.")]
+            diagnostics: [(0, diagnostics_1.diagnostic)("config.env_file.missing", "error", `Workflow Code env file not found at ${path}`, "Create the dotenv file, fix the --env path, or omit --env to use default `.env` / `.env.local` loading. Example: `tela workflow compile --env .env.staging`.")]
           };
         }
         Object.assign(loaded, parseDotenv(await (0, promises_1.readFile)(path, "utf8")));
@@ -219681,7 +219681,8 @@ var require_evaluate_typescript_config = __commonJS({
     var node_vm_1 = require("node:vm");
     var typescript_1 = __importDefault(require_typescript());
     var diagnostics_1 = require_diagnostics();
-    function evaluateTypeScriptConfig(content, path) {
+    function evaluateTypeScriptConfig(content, path, options = {}) {
+      const compileCommand = options.compileCommand ?? "tela workflow compile";
       let outputText;
       try {
         outputText = typescript_1.default.transpileModule(content, {
@@ -219693,10 +219694,10 @@ var require_evaluate_typescript_config = __commonJS({
             target: typescript_1.default.ScriptTarget.ES2022
           }
         }).outputText;
-      } catch (error) {
+      } catch {
         return {
           ok: false,
-          diagnostics: [(0, diagnostics_1.diagnostic)("config.parse_failed", "error", `Unable to transpile Workflow Code config at ${path}`, error instanceof Error ? error.message : void 0)]
+          diagnostics: [(0, diagnostics_1.diagnostic)("config.parse_failed", "error", `Unable to transpile Workflow Code config at ${path}`, `Fix TypeScript syntax in \`${path}\`, then rerun \`${compileCommand}\`. If you need a fresh template, run \`tela workflow init\` in an empty directory.`)]
         };
       }
       const module3 = { exports: {} };
@@ -219717,16 +219718,16 @@ var require_evaluate_typescript_config = __commonJS({
           setInterval,
           setTimeout
         });
-      } catch (error) {
+      } catch {
         return {
           ok: false,
-          diagnostics: [(0, diagnostics_1.diagnostic)("config.evaluate_failed", "error", `Unable to evaluate Workflow Code config at ${path}`, error instanceof Error ? error.message : void 0)]
+          diagnostics: [(0, diagnostics_1.diagnostic)("config.evaluate_failed", "error", `Unable to evaluate Workflow Code config at ${path}`, `Fix \`${path}\` so it can be imported without throwing. If it reads env vars, define them in \`.env\` / \`.env.local\` or pass the matching file with \`${compileCommand} --env <path>\`.`)]
         };
       }
       if (!("default" in module3.exports)) {
         return {
           ok: false,
-          diagnostics: [(0, diagnostics_1.diagnostic)("config.export.invalid", "error", `Workflow Code TypeScript config at ${path} must export a default config object`)]
+          diagnostics: [(0, diagnostics_1.diagnostic)("config.export.invalid", "error", `Workflow Code TypeScript config at ${path} must export a default config object`, `Add \`export default { version: 1, workflows: { ... } }\` to \`${path}\`, or run \`tela workflow init\` in an empty directory to generate a template.`)]
         };
       }
       return { ok: true, value: module3.exports.default };
@@ -219734,6 +219735,29 @@ var require_evaluate_typescript_config = __commonJS({
   }
 });
 
+// ../../packages/workflow-code/dist/cli/config/format-config-path.js
+var require_format_config_path = __commonJS({
+  "../../packages/workflow-code/dist/cli/config/format-config-path.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.formatConfigPath = formatConfigPath;
+    exports2.formatObjectKey = formatObjectKey;
+    var IDENTIFIER_PATTERN = /^[A-Z_$][\w$]*$/i;
+    function formatConfigPath(...segments) {
+      return segments.map((segment, index) => index === 0 ? segment : formatConfigPathSegment(segment)).join("");
+    }
+    function formatObjectKey(key) {
+      return IDENTIFIER_PATTERN.test(key) ? key : `'${escapeSingleQuotedString(key)}'`;
+    }
+    function formatConfigPathSegment(segment) {
+      return IDENTIFIER_PATTERN.test(segment) ? `.${segment}` : `['${escapeSingleQuotedString(segment)}']`;
+    }
+    function escapeSingleQuotedString(value) {
+      return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    }
+  }
+});
+
 // ../../packages/workflow-code/dist/cli/config/load-config.js
 var require_load_config = __commonJS({
   "../../packages/workflow-code/dist/cli/config/load-config.js"(exports2) {
@@ -219745,8 +219769,10 @@ var require_load_config = __commonJS({
     var diagnostics_1 = require_diagnostics();
     var env_1 = require_env();
     var evaluate_typescript_config_1 = require_evaluate_typescript_config();
+    var format_config_path_1 = require_format_config_path();
     async function loadWorkflowCodeConfig(cwd, configPath, options = {}) {
       const path = (0, node_path_1.resolve)(cwd, configPath ?? "workflow-code.config.ts");
+      const compileCommand = workflowCompileCommand(configPath);
       const extensionDiagnostic = validateConfigExtension(path);
       if (extensionDiagnostic)
         return { ok: false, diagnostics: [extensionDiagnostic] };
@@ -219759,13 +219785,15 @@ var require_load_config = __commonJS({
       } catch (error) {
         return {
           ok: false,
-          diagnostics: [(0, diagnostics_1.diagnostic)("config.read_failed", "error", `Unable to read Workflow Code config at ${path}`, error instanceof Error ? error.message : void 0)]
+          diagnostics: [(0, diagnostics_1.diagnostic)("config.read_failed", "error", `Unable to read Workflow Code config at ${path}`, readConfigHint(error, path, compileCommand))]
         };
       }
-      const parsedResult = await (0, env_1.withWorkflowEnv)(envResult.env, () => (0, evaluate_typescript_config_1.evaluateTypeScriptConfig)(content, path));
+      const parsedResult = await (0, env_1.withWorkflowEnv)(envResult.env, () => (0, evaluate_typescript_config_1.evaluateTypeScriptConfig)(content, path, {
+        compileCommand
+      }));
       if (!parsedResult.ok)
         return parsedResult;
-      const diagnostics = validateWorkflowCodeConfig(parsedResult.value);
+      const diagnostics = validateWorkflowCodeConfig(parsedResult.value, compileCommand);
       if (diagnostics.length > 0)
         return { ok: false, diagnostics };
       return { ok: true, value: { path, config: parsedResult.value } };
@@ -219773,82 +219801,113 @@ var require_load_config = __commonJS({
     function validateConfigExtension(path) {
       if ((0, node_path_1.extname)(path) === ".ts")
         return void 0;
-      return (0, diagnostics_1.diagnostic)("config.extension.unsupported", "error", `Unsupported Workflow Code config extension for ${path}`, "Workflow Code config files must be TypeScript files ending in .ts.");
+      return (0, diagnostics_1.diagnostic)("config.extension.unsupported", "error", `Unsupported Workflow Code config extension for ${path}`, "Rename the config to `workflow-code.config.ts`, pass a TypeScript config with `--config <path>.ts`, or create one with `tela workflow init`.");
     }
-    function validateWorkflowCodeConfig(value) {
+    function validateWorkflowCodeConfig(value, compileCommand) {
       const diagnostics = [];
       if (!isRecord2(value)) {
-        return [(0, diagnostics_1.diagnostic)("config.invalid", "error", "Workflow Code config must be an object")];
+        return [(0, diagnostics_1.diagnostic)("config.invalid", "error", "Workflow Code config must be an object", configHint("Export a default object with `version: 1` and a non-empty `workflows` map. To recreate the template in an empty directory, run `tela workflow init`.", compileCommand))];
       }
       if (value.version !== 1) {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.version.invalid", "error", "Workflow Code config version must be 1"));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.version.invalid", "error", "Workflow Code config version must be 1", configHint("Set the top-level field to `version: 1`; this is the only supported Workflow Code config schema version.", compileCommand)));
       }
       if (value.tsconfig !== void 0 && typeof value.tsconfig !== "string") {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.tsconfig.invalid", "error", "Config field tsconfig must be a string when provided"));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.tsconfig.invalid", "error", "Config field tsconfig must be a string when provided", configHint("Set `tsconfig` to a string path such as `./tsconfig.json`, or remove the field to use default TypeScript resolution.", compileCommand)));
       }
       if (value.outDir !== void 0 && typeof value.outDir !== "string") {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.out_dir.invalid", "error", "Config field outDir must be a string when provided"));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.out_dir.invalid", "error", "Config field outDir must be a string when provided", configHint("Set `outDir` to a string path such as `.tela/workflows`, or remove the field to use the default output directory.", compileCommand)));
       }
       if (!isRecord2(value.workflows) || Object.keys(value.workflows).length === 0) {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflows.invalid", "error", "Config field workflows must contain at least one workflow target"));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflows.invalid", "error", "Config field workflows must contain at least one workflow target", configHint("Add at least one target, for example `workflows: { demo: { entry: './src/workflows/demo.workflow.ts', projectId: 'proj_...' } }`, or run `tela workflow init` in an empty directory for a template.", compileCommand)));
         return diagnostics;
       }
       for (const [targetName, target] of Object.entries(value.workflows)) {
-        diagnostics.push(...validateWorkflowTarget(targetName, target));
+        diagnostics.push(...validateWorkflowTarget(targetName, target, compileCommand));
       }
       return diagnostics;
     }
-    function validateWorkflowTarget(targetName, value) {
+    function validateWorkflowTarget(targetName, value, compileCommand) {
       const diagnostics = [];
       if (!isRecord2(value)) {
-        return [(0, diagnostics_1.diagnostic)("config.workflow.invalid", "error", `Workflow target ${targetName} must be an object`)];
+        return [(0, diagnostics_1.diagnostic)("config.workflow.invalid", "error", `Workflow target ${targetName} must be an object`, targetHint(targetName, "Change this target to an object with `entry` and either top-level `projectId` or a `contexts` map.", compileCommand))];
       }
       const target = value;
       if (!target.entry || typeof target.entry !== "string") {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.entry.invalid", "error", `Workflow target ${targetName} must define string field entry`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.entry.invalid", "error", `Workflow target ${targetName} must define string field entry`, targetFieldHint(targetName, "entry", "to the workflow source file path, for example `./src/workflows/demo.workflow.ts`", compileCommand)));
       }
       if (target.projectId !== void 0 && (typeof target.projectId !== "string" || target.projectId.length === 0)) {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.project_id.invalid", "error", `Workflow target ${targetName} field projectId must be a non-empty string when provided`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.project_id.invalid", "error", `Workflow target ${targetName} field projectId must be a non-empty string when provided`, targetFieldHint(targetName, "projectId", "to a non-empty Tela project id from the Tela UI, or move environment-specific project ids under `contexts`", compileCommand)));
       }
       if (target.export !== void 0 && target.export !== "default") {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.export.invalid", "error", `Workflow target ${targetName} only supports export: "default"`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.export.invalid", "error", `Workflow target ${targetName} only supports export: "default"`, targetFieldHint(targetName, "export", "to `default`, or remove the field; named workflow exports are not supported yet", compileCommand)));
       }
       for (const field of ["workflowKey", "title"]) {
         if (target[field] !== void 0 && typeof target[field] !== "string") {
-          diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.optional_field.invalid", "error", `Workflow target ${targetName} field ${field} must be a string when provided`));
+          diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.optional_field.invalid", "error", `Workflow target ${targetName} field ${field} must be a string when provided`, targetFieldHint(targetName, field, "to a string value, or remove the field if you do not need it", compileCommand)));
         }
       }
       if (target.promptId !== void 0 && (typeof target.promptId !== "string" || target.promptId.length === 0)) {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.prompt_id.invalid", "error", `Workflow target ${targetName} field promptId must be a non-empty string when provided`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.prompt_id.invalid", "error", `Workflow target ${targetName} field promptId must be a non-empty string when provided`, targetFieldHint(targetName, "promptId", "to a non-empty Tela prompt id from the Tela UI, or remove it to create/sync without an existing prompt binding", compileCommand)));
       }
       if (target.contexts !== void 0)
-        diagnostics.push(...validateWorkflowContexts(targetName, target.contexts));
+        diagnostics.push(...validateWorkflowContexts(targetName, target.contexts, compileCommand));
       return diagnostics;
     }
-    function validateWorkflowContexts(targetName, value) {
+    function validateWorkflowContexts(targetName, value, compileCommand) {
       const diagnostics = [];
       if (!isRecord2(value) || Object.keys(value).length === 0) {
-        return [(0, diagnostics_1.diagnostic)("config.workflow.contexts.invalid", "error", `Workflow target ${targetName} field contexts must contain at least one context binding when provided`)];
+        return [(0, diagnostics_1.diagnostic)("config.workflow.contexts.invalid", "error", `Workflow target ${targetName} field contexts must contain at least one context binding when provided`, targetFieldHint(targetName, "contexts", "to an object keyed by Tela context ids or environment aliases such as `dev`, `staging`, or `prod`; each binding needs `projectId`", compileCommand))];
       }
       for (const [contextName, binding] of Object.entries(value)) {
-        diagnostics.push(...validateWorkflowContextBinding(targetName, contextName, binding));
+        diagnostics.push(...validateWorkflowContextBinding(targetName, contextName, binding, compileCommand));
       }
       return diagnostics;
     }
-    function validateWorkflowContextBinding(targetName, contextName, value) {
+    function validateWorkflowContextBinding(targetName, contextName, value, compileCommand) {
       const diagnostics = [];
       if (!isRecord2(value)) {
-        return [(0, diagnostics_1.diagnostic)("config.workflow.context.invalid", "error", `Workflow target ${targetName} context ${contextName} must be an object`)];
+        return [(0, diagnostics_1.diagnostic)("config.workflow.context.invalid", "error", `Workflow target ${targetName} context ${contextName} must be an object`, contextHint(targetName, contextName, "Change this binding to an object like `{ projectId: 'proj_...' }`.", compileCommand))];
       }
       const binding = value;
       if (!binding.projectId || typeof binding.projectId !== "string") {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.project_id.missing", "error", `Workflow target ${targetName} context ${contextName} must define string field projectId`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.project_id.missing", "error", `Workflow target ${targetName} context ${contextName} must define string field projectId`, contextFieldHint(targetName, contextName, "projectId", "to a non-empty Tela project id from the Tela UI or a required env var such as `process.env.TELA_PROJECT_ID!`", compileCommand)));
       }
       if (binding.promptId !== void 0 && (typeof binding.promptId !== "string" || binding.promptId.length === 0)) {
-        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.prompt_id.invalid", "error", `Workflow target ${targetName} context ${contextName} field promptId must be a non-empty string when provided`));
+        diagnostics.push((0, diagnostics_1.diagnostic)("config.workflow.prompt_id.invalid", "error", `Workflow target ${targetName} context ${contextName} field promptId must be a non-empty string when provided`, contextFieldHint(targetName, contextName, "promptId", "to a non-empty Tela prompt id from the Tela UI, or remove it if this context has no existing prompt binding", compileCommand)));
       }
       return diagnostics;
     }
+    function configHint(action, compileCommand) {
+      return `${action} Then rerun \`${compileCommand}\`.`;
+    }
+    function targetHint(targetName, action, compileCommand) {
+      return configHint(`${action} Location: \`${(0, format_config_path_1.formatConfigPath)("workflows", targetName)}\`.`, compileCommand);
+    }
+    function targetFieldHint(targetName, field, action, compileCommand) {
+      return configHint(`Set \`${(0, format_config_path_1.formatConfigPath)("workflows", targetName, field)}\` ${action}.`, compileCommand);
+    }
+    function contextHint(targetName, contextName, action, compileCommand) {
+      return configHint(`${action} Location: \`${(0, format_config_path_1.formatConfigPath)("workflows", targetName, "contexts", contextName)}\`.`, compileCommand);
+    }
+    function contextFieldHint(targetName, contextName, field, action, compileCommand) {
+      return configHint(`Set \`${(0, format_config_path_1.formatConfigPath)("workflows", targetName, "contexts", contextName, field)}\` ${action}.`, compileCommand);
+    }
+    function workflowCompileCommand(configPath) {
+      return configPath === void 0 ? "tela workflow compile" : `tela workflow compile --config ${shellArg(configPath)}`;
+    }
+    function shellArg(value) {
+      return /^[\w./:-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+    }
+    function readConfigHint(error, path, compileCommand) {
+      if (isNodeErrorCode(error, "ENOENT")) {
+        return `Create \`${path}\` with \`tela workflow init --config ${shellArg(path)}\`, or pass an existing TypeScript config path. Then rerun \`${compileCommand}\`.`;
+      }
+      const detail = error instanceof Error && error.message.trim() ? ` Detail: ${error.message}` : "";
+      return `${configHint("Check that the config path exists and is readable, or pass another path with `--config <path>.ts`.", compileCommand)}${detail}`;
+    }
+    function isNodeErrorCode(error, code) {
+      return typeof error === "object" && error !== null && "code" in error && error.code === code;
+    }
     function isRecord2(value) {
       return typeof value === "object" && value !== null && !Array.isArray(value);
     }
@@ -220054,12 +220113,12 @@ export default {
         if (isFileExistsError(error)) {
           return {
             exitCode: 1,
-            diagnostics: [(0, diagnostics_1.diagnostic)("init.config_exists", "error", `Workflow Code config already exists at ${path}`, "Move the existing file or pass --config with a different path.")]
+            diagnostics: [(0, diagnostics_1.diagnostic)("init.config_exists", "error", `Workflow Code config already exists at ${path}`, "Run `tela workflow compile` to validate the existing config, edit it in place, or pass `--config <new-path>.ts` to create a separate config.")]
           };
         }
         return {
           exitCode: 1,
-          diagnostics: [(0, diagnostics_1.diagnostic)("init.write_failed", "error", `Unable to write Workflow Code config at ${path}`, error instanceof Error ? error.message : void 0)]
+          diagnostics: [(0, diagnostics_1.diagnostic)("init.write_failed", "error", `Unable to write Workflow Code config at ${path}`, initWriteFailedHint(error))]
         };
       }
       return {
@@ -220077,6 +220136,10 @@ export default {
         ])
       };
     }
+    function initWriteFailedHint(error) {
+      const detail = error instanceof Error && error.message.trim() ? ` Detail: ${error.message}` : "";
+      return `Check that the destination directory exists and is writable, then rerun \`tela workflow init\`, or pass \`--config <writable-path>.ts\`.${detail}`;
+    }
     function isFileExistsError(error) {
       return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
     }
@@ -220093,7 +220156,7 @@ var require_not_implemented = __commonJS({
     function notImplementedCommand(command) {
       return {
         exitCode: 1,
-        diagnostics: [(0, diagnostics_1.diagnostic)("cli.command.not_implemented", "error", `tela workflow ${command} is not yet available.`, "This command is planned for a future release.")]
+        diagnostics: [(0, diagnostics_1.diagnostic)("cli.command.not_implemented", "error", `tela workflow ${command} is not yet available.`, "This command is planned for a future release. Today, use `tela workflow init` to create config and `tela workflow compile` to validate it.")]
       };
     }
   }
@@ -220159,11 +220222,7 @@ var require_cli2 = __commonJS({
       } else {
         result = {
           exitCode: 1,
-          diagnostics: [{
-            code: "cli.command.unknown",
-            severity: "error",
-            message: `Unknown tela workflow command: ${command}`
-          }]
+          diagnostics: [(0, diagnostics_1.diagnostic)("cli.command.unknown", "error", `Unknown tela workflow command: ${command}`, "Run `tela workflow help` to list supported commands. Common commands: `tela workflow init` and `tela workflow compile`.")]
         };
       }
       if (globalOptions.json === true) {
@@ -220194,7 +220253,7 @@ var require_cli2 = __commonJS({
         return void 0;
       return {
         exitCode: 1,
-        diagnostics: [(0, diagnostics_1.diagnostic)("cli.flag.missing_value", "error", `Flag --${missingFlag} requires a value.`, missingFlag === "config" ? `Use --config <path>, for example: tela workflow ${command} --config workflow-code.config.ts` : `Use --env <path>, for example: tela workflow ${command} --env .env.staging`)]
+        diagnostics: [(0, diagnostics_1.diagnostic)("cli.flag.missing_value", "error", `Flag --${missingFlag} requires a value.`, missingFlag === "config" ? `Use --config <path>.ts, for example: tela workflow ${command} --config workflow-code.config.ts. To create the default config, run tela workflow init.` : `Use --env <path>, for example: tela workflow ${command} --env .env.staging. Omit --env to load .env and .env.local automatically.`)]
       };
     }
     function unexpectedPassthroughResult(command, passthrough) {
@@ -220202,7 +220261,7 @@ var require_cli2 = __commonJS({
         return void 0;
       return {
         exitCode: 1,
-        diagnostics: [(0, diagnostics_1.diagnostic)("cli.command.unexpected_args", "error", `Unexpected positional arguments for tela workflow ${command}: ${passthrough.join(" ")}`, `Run tela workflow ${command} --help to see supported arguments.`)]
+        diagnostics: [(0, diagnostics_1.diagnostic)("cli.command.unexpected_args", "error", `Unexpected positional arguments for tela workflow ${command}: ${passthrough.join(" ")}`, "Remove the positional arguments. Run `tela workflow help` to see supported workflow commands and flags.")]
       };
     }
     function writeHelp2(io) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "0.7.55",
+  "version": "0.7.56",
   "description": "Tela command line tools for local state and agent workflows.",
   "license": "UNLICENSED",
   "repository": {