@lonca/baron-recipes 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -45,17 +45,43 @@ interface AskSpec {
 interface AskStep {
     readonly ask: AskSpec;
 }
+/**
+ * A declarative condition over the run context. Exactly ONE key; operands are interpolated before
+ * evaluation. Deliberately not an expression language: four primitive tests cover the reference
+ * guards (refuse-if-closed, refuse-containers, skip-when-PR-exists) without opening a parser
+ * attack/maintenance surface.
+ */
+interface StepCondition {
+    /** True when the interpolated value is present and not ''/false/null. */
+    readonly truthy?: string;
+    /** True when the interpolated value is absent, '', false, or null. */
+    readonly falsy?: string;
+    /** True when both interpolated operands are equal (string comparison). */
+    readonly equals?: readonly [string, string];
+    /** True when the interpolated operands differ (string comparison). */
+    readonly notEquals?: readonly [string, string];
+}
+/** A guard: when the condition is false the run STOPS with the (interpolated) message. */
+interface RequireStep {
+    readonly require: StepCondition & {
+        readonly message: string;
+    };
+}
 interface DoStep {
     readonly do: RecipeOp;
     /** Step parameters; string values may contain `${path}` references into the run context. */
     readonly with?: Record<string, unknown>;
     /** Context variable the step result is bound to. */
     readonly as?: string;
+    /** Run the step only when the condition holds; otherwise it is skipped (its `as` stays unset). */
+    readonly when?: StepCondition;
 }
 interface MessageStep {
     readonly message: string;
+    /** Emit the message only when the condition holds. */
+    readonly when?: StepCondition;
 }
-type Step = AskStep | DoStep | MessageStep;
+type Step = AskStep | DoStep | MessageStep | RequireStep;
 interface Recipe {
     readonly name: string;
     readonly description?: string;
@@ -74,6 +100,7 @@ declare function recipeInputs(recipe: Recipe): RecipeInput[];
 declare function isAskStep(step: Step): step is AskStep;
 declare function isDoStep(step: Step): step is DoStep;
 declare function isMessageStep(step: Step): step is MessageStep;
+declare function isRequireStep(step: Step): step is RequireStep;
 /**
  * Validate an untrusted object (typically `YAML.parse` of a recipe file) into a typed {@link Recipe}.
  * Throws {@link BaronError} (`RECIPE_PARSE`) with an actionable, pathed message on any violation.
@@ -127,8 +154,10 @@ interface RunRecipeResult {
 /**
  * Execute a recipe step by step against the injected ports, threading a context: `ask` steps gather
  * typed human input (skipped when pre-seeded), `do` steps call a primitive and bind its result,
- * `message` steps surface a line. All workflow opinion lives in the recipe; this engine is pure
- * mechanism (invariant #3) and does no role/native translation (that stays in the ports, #4).
+ * `message` steps surface a line, `require` steps are engine-enforced guards (decision #19: the
+ * rules live in the engine, not in agent judgement), and a `when:` condition skips a do/message
+ * step. All workflow opinion lives in the recipe; this engine is pure mechanism (invariant #3) and
+ * does no role/native translation (that stays in the ports, #4).
  */
 declare function runRecipe(recipe: Recipe, options: RunRecipeOptions): Promise<RunRecipeResult>;
 
@@ -156,4 +185,4 @@ interface RecipeService {
 }
 declare function createRecipeService(ports: RecipePorts, root: string): RecipeService;
 
-export { ASK_TYPES, type AskSpec, type AskStep, type AskType, BUILTIN_RECIPE_NAMES, type BuiltinRecipeName, type DoStep, type MessageStep, RECIPE_OPS, type Recipe, type RecipeAsker, type RecipeContext, type RecipeInput, type RecipeOp, type RecipePorts, type RecipeService, type RecipeSummary, type RunRecipeOptions, type RunRecipeResult, type Step, createRecipeService, interpolate, isAskStep, isBuiltinRecipe, isDoStep, isMessageStep, isRecipeOp, loadBuiltinRecipe, loadBuiltinRecipeText, loadRecipe, parseRecipe, recipeInputs, runRecipe };
+export { ASK_TYPES, type AskSpec, type AskStep, type AskType, BUILTIN_RECIPE_NAMES, type BuiltinRecipeName, type DoStep, type MessageStep, RECIPE_OPS, type Recipe, type RecipeAsker, type RecipeContext, type RecipeInput, type RecipeOp, type RecipePorts, type RecipeService, type RecipeSummary, type RequireStep, type RunRecipeOptions, type RunRecipeResult, type Step, type StepCondition, createRecipeService, interpolate, isAskStep, isBuiltinRecipe, isDoStep, isMessageStep, isRecipeOp, isRequireStep, loadBuiltinRecipe, loadBuiltinRecipeText, loadRecipe, parseRecipe, recipeInputs, runRecipe };

package/dist/index.js

@@ -46,6 +46,9 @@ function isDoStep(step) {
 function isMessageStep(step) {
   return "message" in step;
 }
+function isRequireStep(step) {
+  return "require" in step;
+}
 var PARSE_CODE = "RECIPE_PARSE";
 function fail(message) {
   throw new BaronError(message, PARSE_CODE);
@@ -84,6 +87,41 @@ function parseAsk(raw, where) {
     }
   };
 }
+var CONDITION_KEYS = ["truthy", "falsy", "equals", "notEquals"];
+function parseCondition(raw, where) {
+  if (!isRecord(raw)) fail(`${where} must be an object.`);
+  const present = CONDITION_KEYS.filter((key2) => raw[key2] !== void 0);
+  if (present.length !== 1) {
+    fail(
+      `${where} must have exactly one of ${CONDITION_KEYS.join(", ")} (found: ${present.join(", ") || "none"}).`
+    );
+  }
+  const key = present[0];
+  const value = raw[key];
+  if (key === "truthy" || key === "falsy") {
+    if (typeof value !== "string" || value.length === 0) {
+      fail(`${where}.${key} must be a non-empty string.`);
+    }
+    return key === "truthy" ? { truthy: value } : { falsy: value };
+  }
+  if (!Array.isArray(value) || value.length !== 2 || value.some((v) => typeof v !== "string")) {
+    fail(`${where}.${key} must be an array of exactly two strings.`);
+  }
+  const pair = value;
+  return key === "equals" ? { equals: pair } : { notEquals: pair };
+}
+function parseRequire(raw, where) {
+  const req = raw.require;
+  if (!isRecord(req)) fail(`${where}: 'require' must be an object.`);
+  if (typeof req.message !== "string" || req.message.length === 0) {
+    fail(`${where}: require.message must be a non-empty string (it is what the user sees).`);
+  }
+  const { message, ...condition } = req;
+  return { require: { ...parseCondition(condition, `${where}.require`), message } };
+}
+function parseWhen(raw, where) {
+  return raw.when === void 0 ? void 0 : parseCondition(raw.when, `${where}.when`);
+}
 function parseDo(raw, where) {
   const op = raw.do;
   if (typeof op !== "string" || !isRecipeOp(op)) {
@@ -96,25 +134,29 @@ function parseDo(raw, where) {
   if (as !== void 0 && (typeof as !== "string" || as.length === 0)) {
     fail(`${where}: 'as' must be a non-empty string.`);
   }
+  const when = parseWhen(raw, where);
   return {
     do: op,
     ...withParams !== void 0 ? { with: withParams } : {},
-    ...as !== void 0 ? { as } : {}
+    ...as !== void 0 ? { as } : {},
+    ...when !== void 0 ? { when } : {}
   };
 }
 function parseStep(raw, index) {
   const where = `steps[${index}]`;
   if (!isRecord(raw)) fail(`${where} must be an object.`);
-  const kinds = ["ask", "do", "message"].filter((kind) => kind in raw);
+  const kinds = ["ask", "do", "message", "require"].filter((kind) => kind in raw);
   if (kinds.length !== 1) {
     fail(
-      `${where} must have exactly one of 'ask', 'do', or 'message' (found: ${kinds.join(", ") || "none"}).`
+      `${where} must have exactly one of 'ask', 'do', 'message', or 'require' (found: ${kinds.join(", ") || "none"}).`
     );
   }
   if ("ask" in raw) return parseAsk(raw, where);
   if ("do" in raw) return parseDo(raw, where);
+  if ("require" in raw) return parseRequire(raw, where);
   if (typeof raw.message !== "string") fail(`${where}: 'message' must be a string.`);
-  return { message: raw.message };
+  const when = parseWhen(raw, where);
+  return { message: raw.message, ...when !== void 0 ? { when } : {} };
 }
 function parseRecipe(raw) {
   if (!isRecord(raw)) fail("recipe must be an object.");
@@ -355,9 +397,11 @@ async function dispatchOp(ports, op, params) {
       );
     case RECIPE_OPS.issueQuery: {
       const limit = optNum(params, "limit", op);
+      const assignee = optStr(params, "assignee", op);
       const query = {
         ...optStr(params, "role", op) !== void 0 ? { role: reqRole(params, "role", op) } : {},
         ...optStr(params, "typeRole", op) !== void 0 ? { typeRole: reqTypeRole(params, "typeRole", op) } : {},
+        ...assignee !== void 0 ? { assignee } : {},
         ...limit !== void 0 ? { limit } : {}
       };
       return issues(ports, op).query(query);
@@ -457,6 +501,26 @@ async function dispatchOp(ports, op, params) {
     }
   }
 }
+var REQUIRE = "RECIPE_REQUIRE";
+function isTruthy(value) {
+  return value !== void 0 && value !== null && value !== "" && value !== false;
+}
+function asComparable(value) {
+  return value === void 0 || value === null ? "" : String(value);
+}
+function evalCondition(condition, context) {
+  if (condition.truthy !== void 0) return isTruthy(interpolate(condition.truthy, context));
+  if (condition.falsy !== void 0) return !isTruthy(interpolate(condition.falsy, context));
+  if (condition.equals !== void 0) {
+    const [a, b] = condition.equals;
+    return asComparable(interpolate(a, context)) === asComparable(interpolate(b, context));
+  }
+  if (condition.notEquals !== void 0) {
+    const [a, b] = condition.notEquals;
+    return asComparable(interpolate(a, context)) !== asComparable(interpolate(b, context));
+  }
+  throw new BaronError2("Empty step condition.", REQUIRE);
+}
 async function runRecipe(recipe, options) {
   const context = { ...options.inputs };
   for (const step of recipe.steps) {
@@ -472,11 +536,20 @@ async function runRecipe(recipe, options) {
       }
       continue;
     }
+    if (isRequireStep(step)) {
+      const { message, ...condition } = step.require;
+      if (!evalCondition(condition, context)) {
+        throw new BaronError2(String(interpolate(message, context)), REQUIRE);
+      }
+      continue;
+    }
     if (isMessageStep(step)) {
+      if (step.when !== void 0 && !evalCondition(step.when, context)) continue;
       options.asker.note(String(interpolate(step.message, context)));
       continue;
     }
     if (isDoStep(step)) {
+      if (step.when !== void 0 && !evalCondition(step.when, context)) continue;
       const params = interpolate(step.with ?? {}, context) ?? {};
       const result = await dispatchOp(options.ports, step.do, params);
       if (step.as !== void 0) context[step.as] = result;
@@ -578,6 +651,7 @@ export {
   isDoStep,
   isMessageStep,
   isRecipeOp,
+  isRequireStep,
   loadBuiltinRecipe,
   loadBuiltinRecipeText,
   loadRecipe,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lonca/baron-recipes",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -17,13 +17,13 @@
   ],
   "dependencies": {
     "yaml": "^2.6.0",
-    "@lonca/baron-core": "0.2.0",
-    "@lonca/baron-knowledge-loop": "0.2.0"
+    "@lonca/baron-core": "0.4.0",
+    "@lonca/baron-knowledge-loop": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@lonca/baron-adapter-github": "0.2.0",
-    "@lonca/baron-conformance": "0.2.0"
+    "@lonca/baron-adapter-github": "0.4.0",
+    "@lonca/baron-conformance": "0.4.0"
   },
   "description": "Baron recipe engine: run declarative YAML workflows over Baron primitives, deterministically.",
   "keywords": [

package/recipes/task-finish.yaml

@@ -1,23 +1,39 @@
 name: task-finish
-description: Open a draft pull request for a work-item branch and post the PR link back on the item. Deliberately does NOT move the item's role — review/testing state changes when the PR actually merges, not when it opens.
+description: Open a draft pull request for a work-item branch and post the PR link back on the item. Idempotent — an existing open PR is reported, never duplicated. Deliberately does NOT move the item's role; review state changes when the PR merges.
 steps:
   - ask: { as: issueId, type: text, message: "Issue id?" }
   - ask: { as: branch, type: text, message: "Source branch?" }
   - ask: { as: title, type: text, message: "Pull request title?" }
+  # Idempotency probe: the engine (not the agent) decides create-vs-report (decision #19).
+  - do: scm.pr.find
+    as: existingPr
+    with:
+      sourceBranch: ${branch}
+  - message: "PR already open for ${branch}: ${existingPr.url} — not duplicating."
+    when:
+      truthy: "${existingPr}"
   - do: scm.pr.create
     as: pr
+    when:
+      falsy: "${existingPr}"
     with:
       # targetBranch omitted — defaults to the repo's default branch, keeping the recipe portable.
       title: ${title}
       sourceBranch: ${branch}
       draft: true
   - do: scm.pr.thread
+    when:
+      falsy: "${existingPr}"
     with:
       pullRequestId: ${pr.id}
       body: "Opened for issue ${issueId}."
   # Give the card full context: reviewers/QA opening the work item see the PR without digging.
   - do: issue.comment
+    when:
+      falsy: "${existingPr}"
     with:
       id: ${issueId}
       body: "PR opened: ${pr.url} (from ${branch}). Role unchanged — moves to in_review on merge."
   - message: "Opened PR ${pr.url} for ${issueId}. Role unchanged; transition on merge (task-move)."
+    when:
+      falsy: "${existingPr}"

package/recipes/task-start.yaml

@@ -6,9 +6,15 @@ steps:
     as: issue
     with:
       id: ${issueId}
+  # Engine-enforced guards (decision #19): a failed require STOPS the run before any mutation.
+  - require:
+      notEquals: ["${issue.role}", "done"]
+      message: "${issue.key} is already done — reopen it (task-move) or pick an active item."
+  - require:
+      truthy: "${issue.branchName}"
+      message: "${issue.key} (${issue.nativeType}) has no canonical branch — containers (epic/initiative) and unmapped types are never branched. Pick a child story/task/bug."
   # ${issue.branchName} is the core-derived canonical name (<prefix>/<id>-<slug>) — every agent and
-  # recipe derives the SAME name for the same item. It is unset for container types (epic/initiative),
-  # which makes this step fail loudly rather than branch on an epic.
+  # recipe derives the SAME name for the same item.
   - do: scm.branch.create
     as: branch
     with: