clyops-jobs 0.8.0 → 0.10.0

package/README.md

@@ -35,7 +35,12 @@ and no `node_modules`. It includes clyops-tools. `require('clyops-jobs')` loads
 - `positionals` (optional) lists the tool's positional arguments explicitly; otherwise they're
   options keyed by argument name.
 - String values may use `${dot.path}` or `{{dot.path}}` templates against a context you build
-  (`job`, `paths`, whatever the trigger knows).
+  (`job`, `paths`, whatever the trigger knows). An unknown path is an error, so a typo fails
+  loudly, except under `params` (the caller's fields): an option or positional that names a
+  missing or null `params` field is left unset, so the tool's default applies. That holds for
+  `${params.x}` alone and inside a longer string (`v-${params.x}`), so a value is never half
+  filled. Elsewhere (`result`, `stdin`, `stdout`, artifact patterns) a missing field renders as
+  `''`. `strict_params: true` on a function makes a missing `params` field an error too.
 - `artifacts`: glob patterns (`*`, `?`, `**`) relative to `paths.work_dir`, copied into
   `paths.artifacts_dir`, with an optional `required: true` or `min: N`.
 - `stdin`: a template naming a file fed to the tool's stdin (`"${media.path}"`; relative to the

package/clyops-jobs.cjs

@@ -32,10 +32,12 @@ __export(index_exports, {
   deepMerge: () => deepMerge,
   ensureDir: () => ensureDir,
   findFilesByArtifactPattern: () => findFilesByArtifactPattern,
+  functionTemplateOptions: () => functionTemplateOptions,
   globToRegex: () => globToRegex,
   isDirectoryPath: () => isDirectoryPath,
   isEnabled: () => isEnabled,
   isFilePath: () => isFilePath,
+  isUnsetTemplate: () => isUnsetTemplate,
   listFilesRecursive: () => listFilesRecursive,
   lookupTemplateValue: () => lookupTemplateValue,
   newJobId: () => newJobId,
@@ -135,40 +137,59 @@ function resolveConfigPath(root, value) {
 var resolveScriptPath = resolveConfigPath;
 
 // packages/jobs/src/template.ts
-function lookupTemplateValue(context, expression) {
+var OPTIONAL_ROOTS = ["params"];
+var TEMPLATE = /\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g;
+var MISSING = /* @__PURE__ */ Symbol("missing");
+function resolvePath(context, expression) {
   let current = context;
   for (const part of String(expression).split(".").filter(Boolean)) {
-    if (!current || typeof current !== "object" || !Object.prototype.hasOwnProperty.call(current, part)) {
-      throw new Error(`unknown template value: ${expression}`);
-    }
+    if (!current || typeof current !== "object" || !Object.prototype.hasOwnProperty.call(current, part)) return MISSING;
     current = current[part];
   }
+  return current;
+}
+function optionalRoot(expression, opts) {
+  return !opts?.strict && OPTIONAL_ROOTS.includes(String(expression).split(".").filter(Boolean)[0] ?? "");
+}
+function lookupTemplateValue(context, expression, opts) {
+  const current = resolvePath(context, expression);
+  if (current === MISSING) {
+    if (optionalRoot(expression, opts)) return "";
+    throw new Error(`unknown template value: ${expression}`);
+  }
   if (current === void 0 || current === null) return "";
   return typeof current === "object" ? JSON.stringify(current) : String(current);
 }
-function renderTemplateString(value, context) {
-  return String(value).replace(
-    /\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g,
-    (_, dollar, brace) => lookupTemplateValue(context, dollar || brace)
-  );
+function isUnsetTemplate(value, context, opts) {
+  if (typeof value !== "string") return false;
+  for (const [, dollar, brace] of value.matchAll(TEMPLATE)) {
+    const expression = dollar || brace;
+    if (!optionalRoot(expression, opts)) continue;
+    const current = resolvePath(context, expression);
+    if (current === MISSING || current === void 0 || current === null) return true;
+  }
+  return false;
+}
+function renderTemplateString(value, context, opts) {
+  return String(value).replace(TEMPLATE, (_, dollar, brace) => lookupTemplateValue(context, dollar || brace, opts));
 }
-function renderConfigValue(value, context) {
+function renderConfigValue(value, context, opts) {
   if (!context) return value;
-  if (typeof value === "string") return renderTemplateString(value, context);
-  if (Array.isArray(value)) return value.map((item) => renderConfigValue(item, context));
+  if (typeof value === "string") return renderTemplateString(value, context, opts);
+  if (Array.isArray(value)) return value.map((item) => renderConfigValue(item, context, opts));
   return value;
 }
-function renderResultValue(value, context) {
-  if (typeof value === "string") return renderTemplateString(value, context);
-  if (Array.isArray(value)) return value.map((item) => renderResultValue(item, context));
+function renderResultValue(value, context, opts) {
+  if (typeof value === "string") return renderTemplateString(value, context, opts);
+  if (Array.isArray(value)) return value.map((item) => renderResultValue(item, context, opts));
   if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context)]));
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context, opts)]));
   }
   return value;
 }
-function renderResultMap(resultMap, context) {
+function renderResultMap(resultMap, context, opts) {
   if (!resultMap || typeof resultMap !== "object" || Array.isArray(resultMap)) return {};
-  return renderResultValue(resultMap, context);
+  return renderResultValue(resultMap, context, opts);
 }
 
 // packages/tools/src/schema.ts
@@ -179,12 +200,13 @@ function stamp(file) {
   return `${s.mtimeMs}:${s.size}`;
 }
 var cache = /* @__PURE__ */ new Map();
+var PROBE_TIMEOUT_MS = 3e4;
 function loadSchema(file, opts = {}) {
   const key = stamp(file);
   const hit = cache.get(file);
   if (hit && hit.stamp === key) return hit.schema;
   const schema = new Promise((resolve5, reject) => {
-    (0, import_node_child_process.execFile)(file, ["--help-json-schema"], { cwd: opts.cwd, timeout: opts.timeoutMs ?? 5e3, maxBuffer: 16 << 20 }, (err, stdout) => {
+    (0, import_node_child_process.execFile)(file, ["--help-json-schema"], { cwd: opts.cwd, timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS, maxBuffer: 16 << 20 }, (err, stdout) => {
       if (err) return reject(new Error(`${file} does not provide --help-json-schema: ${err.message}`));
       const start2 = stdout.indexOf("{");
       const end = stdout.lastIndexOf("}");
@@ -200,7 +222,9 @@ function loadSchema(file, opts = {}) {
       }
     });
   });
-  schema.catch(() => cache.delete(file));
+  schema.catch(() => {
+    if (cache.get(file)?.schema === schema) cache.delete(file);
+  });
   cache.set(file, { stamp: key, schema });
   return schema;
 }
@@ -233,6 +257,9 @@ function isPathValued(validation, type) {
 function isBareProgram(validation, value) {
   return validation === "file:executable" && value !== "" && !value.includes("/") && !(process.platform === "win32" && value.includes("\\"));
 }
+function oneJsonValue(validation, many) {
+  return (validation === "json" || validation.startsWith("json:")) && !many;
+}
 var TRUE = /^(true|1|yes|on)$/i;
 var FALSE = /^(false|0|no|off)$/i;
 function toArgv(schema, input, opts = {}) {
@@ -280,7 +307,7 @@ function toArgv(schema, input, opts = {}) {
       out.env[option.variableName] = text(found.value, isPathValued(option.validation, option.type), `--${option.name}`, option.validation);
       continue;
     }
-    for (const item of Array.isArray(found.value) ? found.value : [found.value]) {
+    for (const item of Array.isArray(found.value) && !oneJsonValue(option.validation, option.isArray) ? found.value : [found.value]) {
       out.argv.push(`--${option.name}`, text(item, isPathValued(option.validation, option.type), `--${option.name}`, option.validation));
     }
   }
@@ -306,7 +333,7 @@ function toArgv(schema, input, opts = {}) {
         positionals.push(text(gap.default, false));
       }
       skipped = [];
-      const values = Array.isArray(found.value) ? found.value : [found.value];
+      const values = Array.isArray(found.value) && !oneJsonValue(argument.validation, argument.isVariadic) ? found.value : [found.value];
       positionals.push(...values.map((v) => text(v, isPathValued(argument.validation), argument.name, argument.validation)));
     }
   }
@@ -597,22 +624,35 @@ function resolveFunctionConfig(scriptRoot, routeConfig, functionName) {
   const config = deepMerge(objectValue(objectValue(routeConfig.defaults)[key]), objectValue(routeConfig[key]));
   return { functionName, key, script: resolveScriptPath(scriptRoot, script), config, definition };
 }
+function functionTemplateOptions(fn) {
+  return { strict: fn.definition.strict_params === true };
+}
+function withoutUnsetParams(config, context, opts) {
+  const out = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (isUnsetTemplate(value, context, opts)) continue;
+    out[key] = Array.isArray(value) ? value.filter((item) => !isUnsetTemplate(item, context, opts)) : value;
+  }
+  return out;
+}
 function explicitPositionals(fn, context) {
   if (!Array.isArray(fn.definition.positionals)) return void 0;
-  return fn.definition.positionals.map((item) => String(renderConfigValue(item, context))).filter(Boolean);
+  const templates = functionTemplateOptions(fn);
+  return fn.definition.positionals.filter((item) => !context || !isUnsetTemplate(item, context, templates)).map((item) => String(renderConfigValue(item, context, templates))).filter(Boolean);
 }
 async function buildFunctionCommand(fn, opts, schema) {
   schema ??= await loadSchema(fn.script);
-  const config = { ...fn.config };
+  const context = opts.context;
+  const templates = functionTemplateOptions(fn);
+  const config = context ? withoutUnsetParams(fn.config, context, templates) : { ...fn.config };
   const first = schema.arguments[0];
   if (opts.defaultPositional && first && !Array.isArray(fn.definition.positionals) && !inputKeys(first).some((k) => k in config)) {
     config[inputKeys(first)[0]] = opts.defaultPositional;
   }
-  const context = opts.context;
   const { argv, unknown, controlled } = toArgv(schema, config, {
     base: opts.configRoot,
     controlled: opts.controlled ?? ["help"],
-    render: context ? (s) => renderTemplateString(s, context) : void 0,
+    render: context ? (s) => renderTemplateString(s, context, templates) : void 0,
     positionals: explicitPositionals(fn, context),
     positionalsOrder: fn.definition.positionals_order
   });
@@ -629,9 +669,9 @@ function parseRoleJson(text) {
     return void 0;
   }
 }
-function streamPath(template, opts, base) {
+function streamPath(template, opts, base, templates) {
   if (!template) return void 0;
-  const rendered = opts.context ? renderTemplateString(template, opts.context) : template;
+  const rendered = opts.context ? renderTemplateString(template, opts.context, templates) : template;
   return (0, import_node_path3.isAbsolute)(rendered) ? rendered : (0, import_node_path3.resolve)(base, rendered);
 }
 async function runScriptFunction(fn, opts) {
@@ -640,8 +680,8 @@ async function runScriptFunction(fn, opts) {
   const command = [file, ...redactArgv(schema, argv)];
   LOGGER.verbose("command: %s", shellQuote(command));
   const workDir = opts.context?.paths?.work_dir;
-  const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot);
-  const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot);
+  const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot, functionTemplateOptions(fn));
+  const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot, functionTemplateOptions(fn));
   let progress;
   const roles = {
     progress: {
@@ -685,7 +725,7 @@ function buildResultRecord(p) {
     artifact_keys: p.artifactKeys,
     completed_at: p.now,
     config: p.fn.config,
-    ...renderResultMap(p.fn.definition.result, p.context)
+    ...renderResultMap(p.fn.definition.result, p.context, functionTemplateOptions(p.fn))
   };
 }
 
@@ -731,8 +771,8 @@ function listFilesRecursive(dir, visited = /* @__PURE__ */ new Set()) {
   }
   return files;
 }
-function findFilesByArtifactPattern(pattern, context) {
-  const rendered = renderTemplateString(pattern, context);
+function findFilesByArtifactPattern(pattern, context, opts) {
+  const rendered = renderTemplateString(pattern, context, opts);
   const absolute = (0, import_node_path4.isAbsolute)(rendered) ? rendered : (0, import_node_path4.resolve)(context.paths.work_dir, rendered);
   if (!/[*?]/.test(absolute)) return isFilePath(absolute) ? [absolute] : [];
   const regex = globToRegex(absolute);
@@ -771,7 +811,7 @@ function copyConfiguredArtifacts(fn, context, opts = {}) {
   const seen = /* @__PURE__ */ new Set();
   const copied = [];
   for (const pattern of patterns) {
-    for (const source of findFilesByArtifactPattern(pattern, context)) {
+    for (const source of findFilesByArtifactPattern(pattern, context, { strict: fn.definition.strict_params === true })) {
       if (seen.has(source)) continue;
       seen.add(source);
       const destination = (0, import_node_path4.join)(dir, (0, import_node_path4.basename)(source));
@@ -921,10 +961,12 @@ var JobQueue = class {
   deepMerge,
   ensureDir,
   findFilesByArtifactPattern,
+  functionTemplateOptions,
   globToRegex,
   isDirectoryPath,
   isEnabled,
   isFilePath,
+  isUnsetTemplate,
   listFilesRecursive,
   lookupTemplateValue,
   newJobId,

package/dist/artifacts.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedFunction } from './functions.js';
-import { type TemplateContext } from './template.js';
+import { type TemplateContext, type TemplateOptions } from './template.js';
 /** Compile an artifact glob into an anchored regular expression. */
 export declare function globToRegex(pattern: string): RegExp;
 /** Every file below `dir`, following symlinks without looping. */
@@ -9,7 +9,7 @@ export declare function findFilesByArtifactPattern(pattern: string, context: Tem
     paths: {
         work_dir: string;
     };
-}): string[];
+}, opts?: TemplateOptions): string[];
 /** A function's `artifacts` as a list of include patterns, plus its `stdout` file. */
 export declare function artifactIncludePatterns(fn: ResolvedFunction): string[];
 /** How many artifacts a function must produce: `min`, or 1 for `required: true`. */

package/dist/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAK3E,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBnD;AAWD,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,cAAoB,GAAG,MAAM,EAAE,CAarF;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,MAAM,EAAE,CAQhI;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAatE;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,CAMhE;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACjF,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,cAAc,EAAE,CAwBlB"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAwB,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAKjG,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBnD;AAWD,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,cAAoB,GAAG,MAAM,EAAE,CAarF;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAQxJ;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAatE;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,CAMhE;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACjF,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,cAAc,EAAE,CAwBlB"}

package/dist/artifacts.js

@@ -59,8 +59,8 @@ export function listFilesRecursive(dir, visited = new Set()) {
     return files;
 }
 /** Files matching a templated glob; relative patterns start at `paths.work_dir`. */
-export function findFilesByArtifactPattern(pattern, context) {
-    const rendered = renderTemplateString(pattern, context);
+export function findFilesByArtifactPattern(pattern, context, opts) {
+    const rendered = renderTemplateString(pattern, context, opts);
     const absolute = isAbsolute(rendered) ? rendered : resolve(context.paths.work_dir, rendered);
     if (!/[*?]/.test(absolute))
         return isFilePath(absolute) ? [absolute] : [];
@@ -118,7 +118,7 @@ export function copyConfiguredArtifacts(fn, context, opts = {}) {
     const seen = new Set();
     const copied = [];
     for (const pattern of patterns) {
-        for (const source of findFilesByArtifactPattern(pattern, context)) {
+        for (const source of findFilesByArtifactPattern(pattern, context, { strict: fn.definition.strict_params === true })) {
             if (seen.has(source))
                 continue;
             seen.add(source);

package/dist/functions.d.ts

@@ -1,5 +1,5 @@
 import { type RunResult, type Schema } from 'clyops-tools';
-import { type TemplateContext } from './template.js';
+import { type TemplateContext, type TemplateOptions } from './template.js';
 import { type Json } from './util.js';
 /**
  * Route diagnostics. `warn` and `verbose` take a printf-style format and
@@ -29,6 +29,8 @@ export interface FunctionDefinition {
     artifacts?: unknown;
     /** Task result or configured result templates, according to the containing interface. */
     result?: unknown;
+    /** A missing `params` field in a template is an error instead of unset (default false). */
+    strict_params?: boolean;
     [key: string]: unknown;
 }
 /** A configured function with resolved executable and merged defaults and overrides. */
@@ -63,6 +65,8 @@ export interface CommandOptions {
      */
     defaultPositional?: string;
 }
+/** The template options a function's definition asks for. */
+export declare function functionTemplateOptions(fn: ResolvedFunction): TemplateOptions;
 /** The full command line for a function: [script, ...argv]. */
 export declare function buildFunctionCommand(fn: ResolvedFunction, opts: CommandOptions, schema?: Schema): Promise<string[]>;
 /** The completed tool execution with a color-stripped stderr tail. */

package/dist/functions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"AASA,OAAO,EAAsG,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAI/J,OAAO,EAA4D,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/G,OAAO,EAAwD,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAS5F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,8EAA8E;IAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAAG,IAAI,CAE5N;AAED,2GAA2G;AAC3G,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,IAAI,CAAC;IACb,+FAA+F;IAC/F,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAQ1H;AAED,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,2GAA2G;IAC3G,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD,+DAA+D;AAC/D,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBzH;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAO/D;AASD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,cAAc,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACtH,uEAAuE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAChG,8EAA8E,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAC5F,gFAAgF,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IACtG,4CAA4C,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChF,wFAAwF,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAChJ,+DAA+D,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChG,GACA,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,EAAE,EAAE,gBAAgB,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wFAAwF;IACxF,OAAO,EAAE,eAAe,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,IAAI,CAYP"}
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"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"}

package/dist/functions.js

@@ -11,7 +11,7 @@ import { declaredRoles, inputKeys, loadSchema, redactArgv, start, shellQuote, ta
 import { createReadStream, createWriteStream } from 'node:fs';
 import { finished } from 'node:stream/promises';
 import { basename, dirname, isAbsolute, resolve } from 'node:path';
-import { renderConfigValue, renderResultMap, renderTemplateString } from './template.js';
+import { isUnsetTemplate, renderConfigValue, renderResultMap, renderTemplateString } from './template.js';
 import { deepMerge, ensureDir, objectValue, resolveScriptPath } from './util.js';
 /** Where engine diagnostics go; a trigger installs its own with configureLogging. */
 const LOGGER = {
@@ -42,6 +42,24 @@ export function resolveFunctionConfig(scriptRoot, routeConfig, functionName) {
     const config = deepMerge(objectValue(objectValue(routeConfig.defaults)[key]), objectValue(routeConfig[key]));
     return { functionName, key, script: resolveScriptPath(scriptRoot, script), config, definition };
 }
+/** The template options a function's definition asks for. */
+export function functionTemplateOptions(fn) {
+    return { strict: fn.definition.strict_params === true };
+}
+/**
+ * The options with `params` templates that name a missing or null field left
+ * out, so the tool's own default applies: such an option is dropped, alone or
+ * inside a longer string, and so is such an item in an array.
+ */
+function withoutUnsetParams(config, context, opts) {
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (isUnsetTemplate(value, context, opts))
+            continue;
+        out[key] = Array.isArray(value) ? value.filter((item) => !isUnsetTemplate(item, context, opts)) : value;
+    }
+    return out;
+}
 /**
  * The positionals for a function: its `positionals` templates when set
  * (authoritative; `[]` for none), else none here and the schema's arguments
@@ -50,21 +68,27 @@ export function resolveFunctionConfig(scriptRoot, routeConfig, functionName) {
 function explicitPositionals(fn, context) {
     if (!Array.isArray(fn.definition.positionals))
         return undefined;
-    return fn.definition.positionals.map((item) => String(renderConfigValue(item, context))).filter(Boolean);
+    const templates = functionTemplateOptions(fn);
+    return fn.definition.positionals
+        .filter((item) => !context || !isUnsetTemplate(item, context, templates))
+        .map((item) => String(renderConfigValue(item, context, templates)))
+        .filter(Boolean);
 }
 /** The full command line for a function: [script, ...argv]. */
 export async function buildFunctionCommand(fn, opts, schema) {
     schema ??= await loadSchema(fn.script);
-    const config = { ...fn.config };
+    const context = opts.context;
+    const templates = functionTemplateOptions(fn);
+    // First, so an argument left unset still takes the default positional.
+    const config = context ? withoutUnsetParams(fn.config, context, templates) : { ...fn.config };
     const first = schema.arguments[0];
     if (opts.defaultPositional && first && !Array.isArray(fn.definition.positionals) && !inputKeys(first).some((k) => k in config)) {
         config[inputKeys(first)[0]] = opts.defaultPositional;
     }
-    const context = opts.context;
     const { argv, unknown, controlled } = toArgv(schema, config, {
         base: opts.configRoot,
         controlled: opts.controlled ?? ['help'],
-        render: context ? (s) => renderTemplateString(s, context) : undefined,
+        render: context ? (s) => renderTemplateString(s, context, templates) : undefined,
         positionals: explicitPositionals(fn, context),
         positionalsOrder: fn.definition.positionals_order,
     });
@@ -87,10 +111,10 @@ export function parseRoleJson(text) {
     }
 }
 /** A function's `stdin` or `stdout` template rendered, a relative one against `base`. */
-function streamPath(template, opts, base) {
+function streamPath(template, opts, base, templates) {
     if (!template)
         return undefined;
-    const rendered = opts.context ? renderTemplateString(template, opts.context) : template;
+    const rendered = opts.context ? renderTemplateString(template, opts.context, templates) : template;
     return isAbsolute(rendered) ? rendered : resolve(base, rendered);
 }
 /**
@@ -105,8 +129,8 @@ export async function runScriptFunction(fn, opts) {
     LOGGER.verbose('command: %s', shellQuote(command));
     // stdin is input, like a path option; stdout is an artifact, found like one.
     const workDir = opts.context?.paths?.work_dir;
-    const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot);
-    const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot);
+    const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot, functionTemplateOptions(fn));
+    const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot, functionTemplateOptions(fn));
     // Wire the well-known roles the tool declares: progress onto the record, meta into the run.
     let progress;
     const roles = {
@@ -148,6 +172,6 @@ export function buildResultRecord(p) {
         artifact_keys: p.artifactKeys,
         completed_at: p.now,
         config: p.fn.config,
-        ...renderResultMap(p.fn.definition.result, p.context),
+        ...renderResultMap(p.fn.definition.result, p.context, functionTemplateOptions(p.fn)),
     };
 }

package/dist/template.d.ts

@@ -2,16 +2,31 @@
 export type TemplateContext = {
     [key: string]: unknown;
 };
-/** A dot-path value from the context; unknown paths are errors, objects become JSON. */
-export declare function lookupTemplateValue(context: TemplateContext, expression: string): string;
+/** How templates treat missing values. */
+export interface TemplateOptions {
+    /** Every unknown path is an error, `params` too (default false: a missing `params` field renders `''`, and an option naming one is unset). */
+    strict?: boolean;
+}
+/**
+ * A dot-path value from the context; objects become JSON and null is `''`.
+ * An unknown path is an error, except a missing `params` field, which is `''`
+ * unless `opts.strict`.
+ */
+export declare function lookupTemplateValue(context: TemplateContext, expression: string, opts?: TemplateOptions): string;
+/**
+ * True when `value` names a `params` field that is missing or null, alone
+ * (`${params.x}`) or inside a longer string (`v-${params.x}`), so an option
+ * or positional set to it is left unset. Always false with `opts.strict`.
+ */
+export declare function isUnsetTemplate(value: unknown, context: TemplateContext, opts?: TemplateOptions): boolean;
 /** Replace dotted-path ${expression} and {{expression}} templates using the context. */
-export declare function renderTemplateString(value: string, context: TemplateContext): string;
+export declare function renderTemplateString(value: string, context: TemplateContext, opts?: TemplateOptions): string;
 /** Render strings and the strings in arrays; other scalars keep their type. */
-export declare function renderConfigValue(value: unknown, context?: TemplateContext | null): unknown;
+export declare function renderConfigValue(value: unknown, context?: TemplateContext | null, opts?: TemplateOptions): unknown;
 /** Deep-render a `result` map value: strings, arrays and nested objects. */
-export declare function renderResultValue(value: unknown, context: TemplateContext): unknown;
+export declare function renderResultValue(value: unknown, context: TemplateContext, opts?: TemplateOptions): unknown;
 /** Render a function's optional `result` map into extra result fields. */
-export declare function renderResultMap(resultMap: unknown, context: TemplateContext): {
+export declare function renderResultMap(resultMap: unknown, context: TemplateContext, opts?: TemplateOptions): {
     [key: string]: unknown;
 };
 //# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AACA,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAEzD,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUxF;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAIpF;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAK3F;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAOnF;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAGxG"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AACA,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAEzD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,8IAA8I;IAC9I,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAqBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAQhH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CASzG;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAE5G;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAKnH;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAO3G;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAGhI"}

package/dist/template.js

@@ -1,44 +1,82 @@
-/** A dot-path value from the context; unknown paths are errors, objects become JSON. */
-export function lookupTemplateValue(context, expression) {
+// Caller-supplied fields: one a request leaves out is unset, not a config error.
+const OPTIONAL_ROOTS = ['params'];
+const TEMPLATE = /\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g;
+// The value at a dot path, or MISSING when the path is not there.
+const MISSING = Symbol('missing');
+function resolvePath(context, expression) {
     let current = context;
     for (const part of String(expression).split('.').filter(Boolean)) {
-        if (!current || typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part)) {
-            throw new Error(`unknown template value: ${expression}`);
-        }
+        if (!current || typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part))
+            return MISSING;
         current = current[part];
     }
+    return current;
+}
+function optionalRoot(expression, opts) {
+    return !opts?.strict && OPTIONAL_ROOTS.includes(String(expression).split('.').filter(Boolean)[0] ?? '');
+}
+/**
+ * A dot-path value from the context; objects become JSON and null is `''`.
+ * An unknown path is an error, except a missing `params` field, which is `''`
+ * unless `opts.strict`.
+ */
+export function lookupTemplateValue(context, expression, opts) {
+    const current = resolvePath(context, expression);
+    if (current === MISSING) {
+        if (optionalRoot(expression, opts))
+            return '';
+        throw new Error(`unknown template value: ${expression}`);
+    }
     if (current === undefined || current === null)
         return '';
     return typeof current === 'object' ? JSON.stringify(current) : String(current);
 }
+/**
+ * True when `value` names a `params` field that is missing or null, alone
+ * (`${params.x}`) or inside a longer string (`v-${params.x}`), so an option
+ * or positional set to it is left unset. Always false with `opts.strict`.
+ */
+export function isUnsetTemplate(value, context, opts) {
+    if (typeof value !== 'string')
+        return false;
+    for (const [, dollar, brace] of value.matchAll(TEMPLATE)) {
+        const expression = dollar || brace;
+        if (!optionalRoot(expression, opts))
+            continue;
+        const current = resolvePath(context, expression);
+        if (current === MISSING || current === undefined || current === null)
+            return true;
+    }
+    return false;
+}
 /** Replace dotted-path ${expression} and {{expression}} templates using the context. */
-export function renderTemplateString(value, context) {
-    return String(value).replace(/\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (_, dollar, brace) => lookupTemplateValue(context, dollar || brace));
+export function renderTemplateString(value, context, opts) {
+    return String(value).replace(TEMPLATE, (_, dollar, brace) => lookupTemplateValue(context, dollar || brace, opts));
 }
 /** Render strings and the strings in arrays; other scalars keep their type. */
-export function renderConfigValue(value, context) {
+export function renderConfigValue(value, context, opts) {
     if (!context)
         return value;
     if (typeof value === 'string')
-        return renderTemplateString(value, context);
+        return renderTemplateString(value, context, opts);
     if (Array.isArray(value))
-        return value.map((item) => renderConfigValue(item, context));
+        return value.map((item) => renderConfigValue(item, context, opts));
     return value;
 }
 /** Deep-render a `result` map value: strings, arrays and nested objects. */
-export function renderResultValue(value, context) {
+export function renderResultValue(value, context, opts) {
     if (typeof value === 'string')
-        return renderTemplateString(value, context);
+        return renderTemplateString(value, context, opts);
     if (Array.isArray(value))
-        return value.map((item) => renderResultValue(item, context));
+        return value.map((item) => renderResultValue(item, context, opts));
     if (value && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context)]));
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context, opts)]));
     }
     return value;
 }
 /** Render a function's optional `result` map into extra result fields. */
-export function renderResultMap(resultMap, context) {
+export function renderResultMap(resultMap, context, opts) {
     if (!resultMap || typeof resultMap !== 'object' || Array.isArray(resultMap))
         return {};
-    return renderResultValue(resultMap, context);
+    return renderResultValue(resultMap, context, opts);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clyops-jobs",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Run clyops tools as jobs: config-bound functions, templated invocation, artifacts, job records and a queue.",
   "license": "MIT",
   "repository": {
@@ -38,12 +38,12 @@
     "typescript": "^5.6.0"
   },
   "dependencies": {
-    "clyops-tools": "0.8.0"
+    "clyops-tools": "0.10.0"
   },
   "homepage": "https://clyops.io/node-tools.html",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --import ../../tools/test-leaks.mjs --test test/*.test.mjs"
   }
 }

package/src/artifacts.ts

@@ -2,7 +2,7 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, normalize, parse, resolve } from 'node:path';
 import type { ResolvedFunction } from './functions.js';
-import { renderTemplateString, type TemplateContext } from './template.js';
+import { renderTemplateString, type TemplateContext, type TemplateOptions } from './template.js';
 import { copyFileEnsuringDir, isDirectoryPath, isFilePath, statFollowingSymlinks, truthy } from './util.js';
 
 // A small glob subset as a regex: `*`, `?`, `**` and `**/` (which also matches no
@@ -53,8 +53,8 @@ export function listFilesRecursive(dir: string, visited = new Set<string>()): st
 }
 
 /** Files matching a templated glob; relative patterns start at `paths.work_dir`. */
-export function findFilesByArtifactPattern(pattern: string, context: TemplateContext & { paths: { work_dir: string } }): string[] {
-  const rendered = renderTemplateString(pattern, context);
+export function findFilesByArtifactPattern(pattern: string, context: TemplateContext & { paths: { work_dir: string } }, opts?: TemplateOptions): string[] {
+  const rendered = renderTemplateString(pattern, context, opts);
   const absolute = isAbsolute(rendered) ? rendered : resolve(context.paths.work_dir, rendered);
   if (!/[*?]/.test(absolute)) return isFilePath(absolute) ? [absolute] : [];
   const regex = globToRegex(absolute);
@@ -118,7 +118,7 @@ export function copyConfiguredArtifacts(
   const seen = new Set<string>();
   const copied: CopiedArtifact[] = [];
   for (const pattern of patterns) {
-    for (const source of findFilesByArtifactPattern(pattern, context)) {
+    for (const source of findFilesByArtifactPattern(pattern, context, { strict: fn.definition.strict_params === true })) {
       if (seen.has(source)) continue;
       seen.add(source);
       const destination = join(dir, basename(source));

package/src/functions.ts

@@ -11,7 +11,7 @@ import { declaredRoles, inputKeys, loadSchema, redactArgv, start, shellQuote, ta
 import { createReadStream, createWriteStream } from 'node:fs';
 import { finished } from 'node:stream/promises';
 import { basename, dirname, isAbsolute, resolve } from 'node:path';
-import { renderConfigValue, renderResultMap, renderTemplateString, type TemplateContext } from './template.js';
+import { isUnsetTemplate, renderConfigValue, renderResultMap, renderTemplateString, type TemplateContext, type TemplateOptions } from './template.js';
 import { deepMerge, ensureDir, objectValue, resolveScriptPath, type Json } from './util.js';
 
 /** Where engine diagnostics go; a trigger installs its own with configureLogging. */
@@ -48,6 +48,8 @@ export interface FunctionDefinition {
   artifacts?: unknown;
   /** Task result or configured result templates, according to the containing interface. */
   result?: unknown;
+  /** A missing `params` field in a template is an error instead of unset (default false). */
+  strict_params?: boolean;
   [key: string]: unknown;
 }
 
@@ -94,6 +96,25 @@ export interface CommandOptions {
   defaultPositional?: string;
 }
 
+/** The template options a function's definition asks for. */
+export function functionTemplateOptions(fn: ResolvedFunction): TemplateOptions {
+  return { strict: fn.definition.strict_params === true };
+}
+
+/**
+ * The options with `params` templates that name a missing or null field left
+ * out, so the tool's own default applies: such an option is dropped, alone or
+ * inside a longer string, and so is such an item in an array.
+ */
+function withoutUnsetParams(config: Json, context: TemplateContext, opts: TemplateOptions): Json {
+  const out: Json = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (isUnsetTemplate(value, context, opts)) continue;
+    out[key] = Array.isArray(value) ? value.filter((item) => !isUnsetTemplate(item, context, opts)) : value;
+  }
+  return out;
+}
+
 /**
  * The positionals for a function: its `positionals` templates when set
  * (authoritative; `[]` for none), else none here and the schema's arguments
@@ -101,22 +122,28 @@ export interface CommandOptions {
  */
 function explicitPositionals(fn: ResolvedFunction, context?: TemplateContext | null): string[] | undefined {
   if (!Array.isArray(fn.definition.positionals)) return undefined;
-  return fn.definition.positionals.map((item) => String(renderConfigValue(item, context))).filter(Boolean);
+  const templates = functionTemplateOptions(fn);
+  return fn.definition.positionals
+    .filter((item) => !context || !isUnsetTemplate(item, context, templates))
+    .map((item) => String(renderConfigValue(item, context, templates)))
+    .filter(Boolean);
 }
 
 /** The full command line for a function: [script, ...argv]. */
 export async function buildFunctionCommand(fn: ResolvedFunction, opts: CommandOptions, schema?: Schema): Promise<string[]> {
   schema ??= await loadSchema(fn.script);
-  const config: Json = { ...fn.config };
+  const context = opts.context;
+  const templates = functionTemplateOptions(fn);
+  // First, so an argument left unset still takes the default positional.
+  const config: Json = context ? withoutUnsetParams(fn.config, context, templates) : { ...fn.config };
   const first = schema.arguments[0];
   if (opts.defaultPositional && first && !Array.isArray(fn.definition.positionals) && !inputKeys(first).some((k) => k in config)) {
     config[inputKeys(first)[0]] = opts.defaultPositional;
   }
-  const context = opts.context;
   const { argv, unknown, controlled } = toArgv(schema, config, {
     base: opts.configRoot,
     controlled: opts.controlled ?? ['help'],
-    render: context ? (s) => renderTemplateString(s, context) : undefined,
+    render: context ? (s) => renderTemplateString(s, context, templates) : undefined,
     positionals: explicitPositionals(fn, context),
     positionalsOrder: fn.definition.positionals_order,
   });
@@ -147,9 +174,9 @@ export function parseRoleJson(text: string | undefined): unknown {
 }
 
 /** A function's `stdin` or `stdout` template rendered, a relative one against `base`. */
-function streamPath(template: string | undefined, opts: CommandOptions, base: string): string | undefined {
+function streamPath(template: string | undefined, opts: CommandOptions, base: string, templates: TemplateOptions): string | undefined {
   if (!template) return undefined;
-  const rendered = opts.context ? renderTemplateString(template, opts.context) : template;
+  const rendered = opts.context ? renderTemplateString(template, opts.context, templates) : template;
   return isAbsolute(rendered) ? rendered : resolve(base, rendered);
 }
 
@@ -177,8 +204,8 @@ export async function runScriptFunction(
   LOGGER.verbose('command: %s', shellQuote(command));
   // stdin is input, like a path option; stdout is an artifact, found like one.
   const workDir = (opts.context?.paths as { work_dir?: string } | undefined)?.work_dir;
-  const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot);
-  const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot);
+  const stdinPath = streamPath(fn.definition.stdin, opts, opts.configRoot, functionTemplateOptions(fn));
+  const stdoutPath = streamPath(fn.definition.stdout, opts, workDir ?? opts.configRoot, functionTemplateOptions(fn));
   // Wire the well-known roles the tool declares: progress onto the record, meta into the run.
   let progress: Record<string, unknown> | undefined;
   const roles: Record<string, RoleOption> = {
@@ -228,6 +255,6 @@ export function buildResultRecord(p: {
     artifact_keys: p.artifactKeys,
     completed_at: p.now,
     config: p.fn.config,
-    ...renderResultMap(p.fn.definition.result, p.context),
+    ...renderResultMap(p.fn.definition.result, p.context, functionTemplateOptions(p.fn)),
   };
 }

package/src/template.ts

@@ -2,46 +2,87 @@
 /** Values available to dotted-path template expressions. */
 export type TemplateContext = { [key: string]: unknown };
 
-/** A dot-path value from the context; unknown paths are errors, objects become JSON. */
-export function lookupTemplateValue(context: TemplateContext, expression: string): string {
+/** How templates treat missing values. */
+export interface TemplateOptions {
+  /** Every unknown path is an error, `params` too (default false: a missing `params` field renders `''`, and an option naming one is unset). */
+  strict?: boolean;
+}
+
+// Caller-supplied fields: one a request leaves out is unset, not a config error.
+const OPTIONAL_ROOTS = ['params'];
+const TEMPLATE = /\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g;
+
+// The value at a dot path, or MISSING when the path is not there.
+const MISSING = Symbol('missing');
+function resolvePath(context: TemplateContext, expression: string): unknown {
   let current: unknown = context;
   for (const part of String(expression).split('.').filter(Boolean)) {
-    if (!current || typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part)) {
-      throw new Error(`unknown template value: ${expression}`);
-    }
+    if (!current || typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part)) return MISSING;
     current = (current as TemplateContext)[part];
   }
+  return current;
+}
+
+function optionalRoot(expression: string, opts?: TemplateOptions): boolean {
+  return !opts?.strict && OPTIONAL_ROOTS.includes(String(expression).split('.').filter(Boolean)[0] ?? '');
+}
+
+/**
+ * A dot-path value from the context; objects become JSON and null is `''`.
+ * An unknown path is an error, except a missing `params` field, which is `''`
+ * unless `opts.strict`.
+ */
+export function lookupTemplateValue(context: TemplateContext, expression: string, opts?: TemplateOptions): string {
+  const current = resolvePath(context, expression);
+  if (current === MISSING) {
+    if (optionalRoot(expression, opts)) return '';
+    throw new Error(`unknown template value: ${expression}`);
+  }
   if (current === undefined || current === null) return '';
   return typeof current === 'object' ? JSON.stringify(current) : String(current);
 }
 
+/**
+ * True when `value` names a `params` field that is missing or null, alone
+ * (`${params.x}`) or inside a longer string (`v-${params.x}`), so an option
+ * or positional set to it is left unset. Always false with `opts.strict`.
+ */
+export function isUnsetTemplate(value: unknown, context: TemplateContext, opts?: TemplateOptions): boolean {
+  if (typeof value !== 'string') return false;
+  for (const [, dollar, brace] of value.matchAll(TEMPLATE)) {
+    const expression = dollar || brace;
+    if (!optionalRoot(expression, opts)) continue;
+    const current = resolvePath(context, expression);
+    if (current === MISSING || current === undefined || current === null) return true;
+  }
+  return false;
+}
+
 /** Replace dotted-path ${expression} and {{expression}} templates using the context. */
-export function renderTemplateString(value: string, context: TemplateContext): string {
-  return String(value).replace(/\$\{\s*([A-Za-z0-9_.-]+)\s*\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (_, dollar, brace) =>
-    lookupTemplateValue(context, dollar || brace),
-  );
+export function renderTemplateString(value: string, context: TemplateContext, opts?: TemplateOptions): string {
+  return String(value).replace(TEMPLATE, (_, dollar, brace) => lookupTemplateValue(context, dollar || brace, opts));
 }
 
 /** Render strings and the strings in arrays; other scalars keep their type. */
-export function renderConfigValue(value: unknown, context?: TemplateContext | null): unknown {
+export function renderConfigValue(value: unknown, context?: TemplateContext | null, opts?: TemplateOptions): unknown {
   if (!context) return value;
-  if (typeof value === 'string') return renderTemplateString(value, context);
-  if (Array.isArray(value)) return value.map((item) => renderConfigValue(item, context));
+  if (typeof value === 'string') return renderTemplateString(value, context, opts);
+  if (Array.isArray(value)) return value.map((item) => renderConfigValue(item, context, opts));
   return value;
 }
 
 /** Deep-render a `result` map value: strings, arrays and nested objects. */
-export function renderResultValue(value: unknown, context: TemplateContext): unknown {
-  if (typeof value === 'string') return renderTemplateString(value, context);
-  if (Array.isArray(value)) return value.map((item) => renderResultValue(item, context));
+export function renderResultValue(value: unknown, context: TemplateContext, opts?: TemplateOptions): unknown {
+  if (typeof value === 'string') return renderTemplateString(value, context, opts);
+  if (Array.isArray(value)) return value.map((item) => renderResultValue(item, context, opts));
   if (value && typeof value === 'object') {
-    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context)]));
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderResultValue(v, context, opts)]));
   }
   return value;
 }
 
 /** Render a function's optional `result` map into extra result fields. */
-export function renderResultMap(resultMap: unknown, context: TemplateContext): { [key: string]: unknown } {
+export function renderResultMap(resultMap: unknown, context: TemplateContext, opts?: TemplateOptions): { [key: string]: unknown } {
   if (!resultMap || typeof resultMap !== 'object' || Array.isArray(resultMap)) return {};
-  return renderResultValue(resultMap, context) as { [key: string]: unknown };
+  return renderResultValue(resultMap, context, opts) as { [key: string]: unknown };
 }