@lonca/baron-recipes 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -7,14 +7,17 @@ import { KnowledgeLoop } from '@lonca/baron-knowledge-loop';
  */
 declare const RECIPE_OPS: {
     readonly issueCreate: "issue.create";
+    readonly issueGet: "issue.get";
     readonly issueTransition: "issue.transition";
     readonly issueComment: "issue.comment";
     readonly issueLink: "issue.link";
+    readonly issueAssign: "issue.assign";
     readonly issueQuery: "issue.query";
     readonly scmBranchCreate: "scm.branch.create";
     readonly scmPrCreate: "scm.pr.create";
     readonly scmPrThread: "scm.pr.thread";
     readonly scmPrStatus: "scm.pr.status";
+    readonly scmPrFind: "scm.pr.find";
     readonly ciRunTrigger: "ci.run.trigger";
     readonly ciRunCancel: "ci.run.cancel";
     readonly deployDeployments: "deploy.deployments";
@@ -42,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;
@@ -71,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.
@@ -124,13 +154,15 @@ 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>;
 
 /** The recipes Baron ships out of the box, runnable by name (no file path). */
-declare const BUILTIN_RECIPE_NAMES: readonly ["task-start", "task-finish", "ship"];
+declare const BUILTIN_RECIPE_NAMES: readonly ["task-new", "task-start", "task-finish", "ship"];
 type BuiltinRecipeName = (typeof BUILTIN_RECIPE_NAMES)[number];
 declare function isBuiltinRecipe(name: string): name is BuiltinRecipeName;
 /** Raw YAML of a built-in recipe (the canonical file — no inlined copy, so it can never drift). */
@@ -153,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

@@ -3,14 +3,17 @@ import { BaronError } from "@lonca/baron-core";
 import { parse as parseYaml } from "yaml";
 var RECIPE_OPS = {
   issueCreate: "issue.create",
+  issueGet: "issue.get",
   issueTransition: "issue.transition",
   issueComment: "issue.comment",
   issueLink: "issue.link",
+  issueAssign: "issue.assign",
   issueQuery: "issue.query",
   scmBranchCreate: "scm.branch.create",
   scmPrCreate: "scm.pr.create",
   scmPrThread: "scm.pr.thread",
   scmPrStatus: "scm.pr.status",
+  scmPrFind: "scm.pr.find",
   ciRunTrigger: "ci.run.trigger",
   ciRunCancel: "ci.run.cancel",
   deployDeployments: "deploy.deployments",
@@ -43,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);
@@ -81,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)) {
@@ -93,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.");
@@ -336,10 +381,14 @@ async function dispatchOp(ports, op, params) {
         ...optStrArray(params, "labels", op) !== void 0 ? { labels: optStrArray(params, "labels", op) } : {},
         ...optStr(params, "initialRole", op) !== void 0 ? { initialRole: reqRole(params, "initialRole", op) } : {}
       });
+    case RECIPE_OPS.issueGet:
+      return issues(ports, op).get(reqStr(params, "id", op));
     case RECIPE_OPS.issueTransition:
       return issues(ports, op).transition(reqStr(params, "id", op), reqRole(params, "role", op));
     case RECIPE_OPS.issueComment:
       return issues(ports, op).comment(reqStr(params, "id", op), reqStr(params, "body", op));
+    case RECIPE_OPS.issueAssign:
+      return issues(ports, op).assign(reqStr(params, "id", op), reqStr(params, "assignee", op));
     case RECIPE_OPS.issueLink:
       return issues(ports, op).link(
         reqStr(params, "fromId", op),
@@ -348,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);
@@ -375,6 +426,10 @@ async function dispatchOp(ports, op, params) {
       );
     case RECIPE_OPS.scmPrStatus:
       return scm(ports, op).prStatus(reqStr(params, "pullRequestId", op));
+    case RECIPE_OPS.scmPrFind: {
+      const found = await scm(ports, op).prForBranch(reqStr(params, "sourceBranch", op));
+      return found ?? null;
+    }
     case RECIPE_OPS.ciRunTrigger: {
       const ref = optStr(params, "ref", op);
       const variables = optStrRecord(params, "variables", op);
@@ -446,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) {
@@ -461,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;
@@ -478,7 +562,7 @@ async function runRecipe(recipe, options) {
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 var RECIPES_DIR = fileURLToPath(new URL("../recipes/", import.meta.url));
-var BUILTIN_RECIPE_NAMES = ["task-start", "task-finish", "ship"];
+var BUILTIN_RECIPE_NAMES = ["task-new", "task-start", "task-finish", "ship"];
 function isBuiltinRecipe(name) {
   return BUILTIN_RECIPE_NAMES.includes(name);
 }
@@ -567,6 +651,7 @@ export {
   isDoStep,
   isMessageStep,
   isRecipeOp,
+  isRequireStep,
   loadBuiltinRecipe,
   loadBuiltinRecipeText,
   loadRecipe,

package/package.json

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

package/recipes/task-finish.yaml

@@ -1,22 +1,39 @@
 name: task-finish
-description: Open a pull request for a branch and move its issue to review.
+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: issue.transition
-    with:
-      id: ${issueId}
-      role: in_review
   - do: scm.pr.thread
+    when:
+      falsy: "${existingPr}"
     with:
       pullRequestId: ${pr.id}
       body: "Opened for issue ${issueId}."
-  - message: "Opened PR ${pr.url}; moved ${issueId} to review."
+  # 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-new.yaml

@@ -0,0 +1,15 @@
+name: task-new
+description: Create a NEW work item (type + optional parent + optional starting role). Starting work on it afterwards is `task-start`.
+steps:
+  - ask: { as: title, type: text, message: "Work item title?" }
+  - ask: { as: typeRole, type: choice, message: "Type role?", choices: [task, bug, story] }
+  - ask: { as: parentId, type: text, message: "Parent id (empty for none)?", optional: true }
+  - do: issue.create
+    as: issue
+    with:
+      title: ${title}
+      typeRole: ${typeRole}
+      # Exactly-one-reference interpolation: an unanswered optional ask stays truly unset,
+      # so hierarchy/gap negotiation only runs when a parent was actually given.
+      parentId: ${parentId}
+  - message: "Created ${issue.key} (${issue.nativeType}): ${issue.title}"

package/recipes/task-start.yaml

@@ -1,18 +1,25 @@
 name: task-start
-description: Create a task, branch for it, and move it into progress.
+description: Start work on an EXISTING work item — load it, cut its canonical branch, move it to in_progress, and note the branch on the item. (Creating a new item is `task-new`.)
 steps:
-  - ask: { as: title, type: text, message: "Task title?" }
-  - do: issue.create
+  - ask: { as: issueId, type: text, message: "Work item id?" }
+  - do: issue.get
     as: issue
     with:
-      title: ${title}
-      typeRole: task
+      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.
   - do: scm.branch.create
     as: branch
     with:
-      # fromBranch omitted on purpose — defaults to the repo's default branch (main/release/master),
-      # so this recipe is portable across repos instead of assuming 'main'.
-      name: feature/${issue.id}
+      # fromBranch omitted on purpose — defaults to the repo's default branch (main/release/master).
+      name: ${issue.branchName}
   - do: issue.transition
     as: issue
     with:
@@ -21,5 +28,5 @@ steps:
   - do: issue.comment
     with:
       id: ${issue.id}
-      body: "Started on branch ${branch.name}."
-  - message: "Task ${issue.key} is in progress on ${branch.name}."
+      body: "Branch created: ${branch.name}."
+  - message: "${issue.key} is in progress on ${branch.name}."