@jiggai/recipes 0.2.23 → 0.2.25

package/src/handlers/tickets.ts

@@ -0,0 +1,304 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { ensureDir, fileExists, writeFileSafely } from "../lib/fs-utils";
+import { findTicketFile, handoffTicket, takeTicket } from "../lib/ticket-workflow";
+import { ticketStageDir } from "../lib/lanes";
+import { computeNextTicketNumber, TICKET_FILENAME_REGEX } from "../lib/ticket-finder";
+import { resolveTeamContext } from "../lib/workspace";
+import { DEFAULT_TICKET_NUMBER, VALID_ROLES, VALID_STAGES } from "../lib/constants";
+
+export function patchTicketField(md: string, key: string, value: string): string {
+  const lineRe = new RegExp(`^${key}:\\s.*$`, "m");
+  if (md.match(lineRe)) return md.replace(lineRe, `${key}: ${value}`);
+  return md.replace(/^(# .+\n)/, `$1\n${key}: ${value}\n`);
+}
+
+export function patchTicketOwner(md: string, owner: string): string {
+  return patchTicketField(md, "Owner", owner);
+}
+
+export function patchTicketStatus(md: string, status: string): string {
+  return patchTicketField(md, "Status", status);
+}
+
+type TicketRow = { stage: "backlog" | "in-progress" | "testing" | "done"; number: number | null; id: string; file: string };
+
+/**
+ * List tickets for a team (backlog, in-progress, testing, done).
+ * @param api - OpenClaw plugin API
+ * @param options - teamId
+ * @returns Grouped tickets by stage
+ */
+export async function handleTickets(api: OpenClawPluginApi, options: { teamId: string }) {
+  const teamId = String(options.teamId);
+  const { teamDir } = await resolveTeamContext(api, teamId);
+  const dirs = {
+    backlog: ticketStageDir(teamDir, "backlog"),
+    inProgress: ticketStageDir(teamDir, "in-progress"),
+    testing: ticketStageDir(teamDir, "testing"),
+    done: ticketStageDir(teamDir, "done"),
+  } as const;
+  const readTickets = async (dir: string, stage: "backlog" | "in-progress" | "testing" | "done") => {
+    if (!(await fileExists(dir))) return [] as TicketRow[];
+    const files = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+    return files.map((f) => {
+      const m = f.match(TICKET_FILENAME_REGEX);
+      return {
+        stage,
+        number: m ? Number(m[1]) : null,
+        id: m ? `${m[1]}-${m[2]}` : f.replace(/\.md$/, ""),
+        file: path.join(dir, f),
+      };
+    });
+  };
+  const backlog = await readTickets(dirs.backlog, "backlog");
+  const inProgress = await readTickets(dirs.inProgress, "in-progress");
+  const testing = await readTickets(dirs.testing, "testing");
+  const done = await readTickets(dirs.done, "done");
+  return {
+    teamId,
+    tickets: [...backlog, ...inProgress, ...testing, ...done],
+    backlog,
+    inProgress,
+    testing,
+    done,
+  };
+}
+
+/**
+ * Move a ticket between backlog/in-progress/testing/done.
+ * @param api - OpenClaw plugin API
+ * @param options - teamId, ticket, to stage, optional completed, dryRun
+ * @returns Plan (dryRun) or result with from/to paths
+ */
+export async function handleMoveTicket(
+  api: OpenClawPluginApi,
+  options: { teamId: string; ticket: string; to: string; completed?: boolean; dryRun?: boolean },
+) {
+  const teamId = String(options.teamId);
+  const { teamDir } = await resolveTeamContext(api, teamId);
+  const dest = String(options.to);
+  if (!(VALID_STAGES as readonly string[]).includes(dest)) {
+    throw new Error("--to must be one of: backlog, in-progress, testing, done");
+  }
+  const srcPath = await findTicketFile(teamDir, options.ticket);
+  if (!srcPath) throw new Error(`Ticket not found: ${options.ticket}`);
+  const destDir = ticketStageDir(teamDir, dest as "backlog" | "in-progress" | "testing" | "done");
+  await ensureDir(destDir);
+  const filename = path.basename(srcPath);
+  const destPath = path.join(destDir, filename);
+  const plan = { from: srcPath, to: destPath };
+  if (options.dryRun) return { ok: true as const, plan };
+  const patchStatus = (md: string) => {
+    const nextStatus =
+      dest === "backlog" ? "queued" : dest === "in-progress" ? "in-progress" : dest === "testing" ? "testing" : "done";
+    let out = md;
+    if (out.match(/^Status:\s.*$/m)) out = out.replace(/^Status:\s.*$/m, `Status: ${nextStatus}`);
+    else out = out.replace(/^(# .+\n)/, `$1\nStatus: ${nextStatus}\n`);
+    if (dest === "done" && options.completed) {
+      const completed = new Date().toISOString();
+      if (out.match(/^Completed:\s.*$/m)) out = out.replace(/^Completed:\s.*$/m, `Completed: ${completed}`);
+      else out = out.replace(/^Status:.*$/m, (m) => `${m}\nCompleted: ${completed}`);
+    }
+    return out;
+  };
+  const md = await fs.readFile(srcPath, "utf8");
+  const patched = patchStatus(md);
+  await fs.writeFile(srcPath, patched, "utf8");
+  if (srcPath !== destPath) await fs.rename(srcPath, destPath);
+  return { ok: true, from: srcPath, to: destPath };
+}
+
+/**
+ * Assign a ticket to an owner (writes assignment stub + updates Owner:).
+ * @param api - OpenClaw plugin API
+ * @param options - teamId, ticket, owner, optional overwrite, dryRun
+ * @returns Plan (dryRun) or ok with plan
+ */
+export async function handleAssign(
+  api: OpenClawPluginApi,
+  options: { teamId: string; ticket: string; owner: string; overwrite?: boolean; dryRun?: boolean },
+) {
+  const teamId = String(options.teamId);
+  const { teamDir } = await resolveTeamContext(api, teamId);
+  const owner = String(options.owner);
+  if (!(VALID_ROLES as readonly string[]).includes(owner)) {
+    throw new Error("--owner must be one of: dev, devops, lead, test");
+  }
+  const ticketPath = await findTicketFile(teamDir, options.ticket);
+  if (!ticketPath) throw new Error(`Ticket not found: ${options.ticket}`);
+  const filename = path.basename(ticketPath);
+  const m = filename.match(TICKET_FILENAME_REGEX);
+  const ticketNumStr = m?.[1] ?? DEFAULT_TICKET_NUMBER;
+  const slug = m?.[2] ?? (options.ticket.replace(/^\d{4}-?/, "") || "ticket");
+  const assignmentsDir = ticketStageDir(teamDir, "assignments");
+  await ensureDir(assignmentsDir);
+  const assignmentPath = path.join(assignmentsDir, `${ticketNumStr}-assigned-${owner}.md`);
+  const plan = { ticketPath, assignmentPath, owner };
+  if (options.dryRun) return { ok: true, plan };
+  const patchOwner = (md: string) => {
+    if (md.match(/^Owner:\s.*$/m)) return md.replace(/^Owner:\s.*$/m, `Owner: ${owner}`);
+    return md.replace(/^(# .+\n)/, `$1\nOwner: ${owner}\n`);
+  };
+  const md = await fs.readFile(ticketPath, "utf8");
+  const nextMd = patchOwner(md);
+  await fs.writeFile(ticketPath, nextMd, "utf8");
+  const assignmentMd = `# Assignment — ${ticketNumStr}-${slug}\n\nAssigned: ${owner}\n\n## Ticket\n${path.relative(teamDir, ticketPath)}\n\n## Notes\n- Created by: openclaw recipes assign\n`;
+  await writeFileSafely(assignmentPath, assignmentMd, options.overwrite ? "overwrite" : "createOnly");
+  return { ok: true, plan };
+}
+
+async function dryRunTicketMove(
+  teamDir: string,
+  ticket: string,
+  lane: "in-progress" | "testing"
+): Promise<{ from: string; to: string }> {
+  const srcPath = await findTicketFile(teamDir, ticket);
+  if (!srcPath) throw new Error(`Ticket not found: ${ticket}`);
+  const filename = path.basename(srcPath);
+  const destPath = path.join(ticketStageDir(teamDir, lane), filename);
+  return { from: srcPath, to: destPath };
+}
+
+async function resolveTeamAndValidateRole(
+  api: OpenClawPluginApi,
+  teamId: string,
+  role: string,
+  optionName: string
+): Promise<{ teamDir: string }> {
+  const { teamDir } = await resolveTeamContext(api, teamId);
+  if (!(VALID_ROLES as readonly string[]).includes(role)) {
+    throw new Error(`--${optionName} must be one of: dev, devops, lead, test`);
+  }
+  return { teamDir };
+}
+
+/**
+ * Assign ticket to owner and move to in-progress.
+ * @param api - OpenClaw plugin API
+ * @param options - teamId, ticket, optional owner, overwrite, dryRun
+ * @returns Plan (dryRun) or result with paths and assignment
+ */
+export async function handleTake(
+  api: OpenClawPluginApi,
+  options: { teamId: string; ticket: string; owner?: string; overwrite?: boolean; dryRun?: boolean },
+) {
+  const teamId = String(options.teamId);
+  const owner = String(options.owner ?? "dev");
+  const { teamDir } = await resolveTeamAndValidateRole(api, teamId, owner, "owner");
+  if (options.dryRun) {
+    const plan = await dryRunTicketMove(teamDir, options.ticket, "in-progress");
+    return { plan: { ...plan, owner } };
+  }
+  return takeTicket({
+    teamDir,
+    ticket: options.ticket,
+    owner,
+    overwriteAssignment: !!options.overwrite,
+  });
+}
+
+/**
+ * Move ticket to testing and assign to tester (QA handoff).
+ * @param api - OpenClaw plugin API
+ * @param options - teamId, ticket, optional tester, overwrite, dryRun
+ * @returns Plan (dryRun) or result with paths and assignment
+ */
+export async function handleHandoff(
+  api: OpenClawPluginApi,
+  options: { teamId: string; ticket: string; tester?: string; overwrite?: boolean; dryRun?: boolean },
+) {
+  const teamId = String(options.teamId);
+  const tester = String(options.tester ?? "test");
+  const { teamDir } = await resolveTeamAndValidateRole(api, teamId, tester, "tester");
+  if (options.dryRun) {
+    const plan = await dryRunTicketMove(teamDir, options.ticket, "testing");
+    return {
+      plan: { ...plan, tester, note: plan.from.includes("testing") ? "already-in-testing" : "move-to-testing" },
+    };
+  }
+  return handoffTicket({
+    teamDir,
+    ticket: options.ticket,
+    tester,
+    overwriteAssignment: !!options.overwrite,
+  });
+}
+
+/**
+ * Turn a request into inbox + backlog ticket(s) + assignment stubs.
+ * @param api - OpenClaw plugin API
+ * @param options - teamId, requestText, optional owner, dryRun
+ * @returns Plan (dryRun) or result with wrote paths and nudgeQueued
+ */
+export async function handleDispatch(
+  api: OpenClawPluginApi,
+  options: { teamId: string; requestText: string; owner?: string; dryRun?: boolean },
+) {
+  const teamId = String(options.teamId);
+  const { teamDir } = await resolveTeamContext(api, teamId);
+  const owner = String(options.owner ?? "dev");
+  if (!(VALID_ROLES as readonly string[]).includes(owner)) {
+    throw new Error("--owner must be one of: dev, devops, lead, test");
+  }
+  const requestText = options.requestText.trim();
+  if (!requestText) throw new Error("Request cannot be empty");
+  const inboxDir = path.join(teamDir, "inbox");
+  const backlogDir = ticketStageDir(teamDir, "backlog");
+  const assignmentsDir = ticketStageDir(teamDir, "assignments");
+  const slugify = (s: string) =>
+    s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 60) || "request";
+  const nowKey = () => {
+    const d = new Date();
+    const pad = (n: number) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+  };
+  const ticketNum = await computeNextTicketNumber(teamDir);
+  const ticketNumStr = String(ticketNum).padStart(4, "0");
+  const title = requestText.length > 80 ? requestText.slice(0, 77) + "…" : requestText;
+  const baseSlug = slugify(title);
+  const inboxPath = path.join(inboxDir, `${nowKey()}-${baseSlug}.md`);
+  const ticketPath = path.join(backlogDir, `${ticketNumStr}-${baseSlug}.md`);
+  const assignmentPath = path.join(assignmentsDir, `${ticketNumStr}-assigned-${owner}.md`);
+  const receivedIso = new Date().toISOString();
+  const inboxMd = `# Inbox — ${teamId}\n\nReceived: ${receivedIso}\n\n## Request\n${requestText}\n\n## Proposed work\n- Ticket: ${ticketNumStr}-${baseSlug}\n- Owner: ${owner}\n\n## Links\n- Ticket: ${path.relative(teamDir, ticketPath)}\n- Assignment: ${path.relative(teamDir, assignmentPath)}\n`;
+  const ticketMd = `# ${ticketNumStr}-${baseSlug}\n\nCreated: ${receivedIso}\nOwner: ${owner}\nStatus: queued\nInbox: ${path.relative(teamDir, inboxPath)}\nAssignment: ${path.relative(teamDir, assignmentPath)}\n\n## Context\n${requestText}\n\n## Requirements\n- (fill in)\n\n## Acceptance criteria\n- (fill in)\n\n## Tasks\n- [ ] (fill in)\n\n## Comments\n- (use this section for @mentions, questions, decisions, and dated replies)\n`;
+  const assignmentMd = `# Assignment — ${ticketNumStr}-${baseSlug}\n\nCreated: ${receivedIso}\nAssigned: ${owner}\n\n## Goal\n${title}\n\n## Ticket\n${path.relative(teamDir, ticketPath)}\n\n## Notes\n- Created by: openclaw recipes dispatch\n`;
+  const plan = {
+    teamId,
+    request: requestText,
+    files: [
+      { path: inboxPath, kind: "inbox", summary: title },
+      { path: ticketPath, kind: "backlog-ticket", summary: title },
+      { path: assignmentPath, kind: "assignment", summary: owner },
+    ],
+  };
+  if (options.dryRun) return { ok: true as const, plan };
+  await ensureDir(inboxDir);
+  await ensureDir(backlogDir);
+  await ensureDir(assignmentsDir);
+  await writeFileSafely(inboxPath, inboxMd, "createOnly");
+  await writeFileSafely(ticketPath, ticketMd, "createOnly");
+  await writeFileSafely(assignmentPath, assignmentMd, "createOnly");
+  let nudgeQueued = false;
+  try {
+    const leadAgentId = `${teamId}-lead`;
+    api.runtime.system.enqueueSystemEvent(
+      [
+        `Dispatch created new intake for team: ${teamId}`,
+        `- Inbox: ${path.relative(teamDir, inboxPath)}`,
+        `- Backlog: ${path.relative(teamDir, ticketPath)}`,
+        `- Assignment: ${path.relative(teamDir, assignmentPath)}`,
+        `Action: please triage/normalize the ticket (fill Requirements/AC/tasks) and move it through the workflow.`,
+      ].join("\n"),
+      { sessionKey: `agent:${leadAgentId}:main` },
+    );
+    nudgeQueued = true;
+  } catch {
+    // Non-critical: enqueueSystemEvent may be unavailable or fail (e.g. in tests, headless).
+    // Dispatch still succeeds; nudgeQueued stays false so caller knows the nudge was skipped.
+    nudgeQueued = false;
+  }
+  return { ok: true as const, wrote: plan.files.map((f) => f.path), nudgeQueued };
+}

package/src/lib/agent-config.ts

@@ -0,0 +1,48 @@
+export type AgentConfigSnippet = {
+  id: string;
+  workspace: string;
+  identity?: { name?: string };
+  tools?: { profile?: string; allow?: string[]; deny?: string[] };
+};
+
+type AgentsConfigMutable = Record<string, unknown> & {
+  agents?: { list?: Array<{ id?: string; workspace?: string; identity?: Record<string, unknown>; tools?: unknown }> };
+};
+
+export function upsertAgentInConfig(cfgObj: AgentsConfigMutable, snippet: AgentConfigSnippet) {
+  if (!cfgObj.agents) cfgObj.agents = {};
+  if (!Array.isArray(cfgObj.agents.list)) cfgObj.agents.list = [];
+
+  const list = cfgObj.agents.list;
+  const idx = list.findIndex((a) => a?.id === snippet.id);
+  const prev = idx >= 0 ? list[idx] : {};
+  const prevTools = (prev as any)?.tools as undefined | { profile?: string; allow?: string[]; deny?: string[] };
+  const nextTools =
+    snippet.tools === undefined
+      ? prevTools
+      : {
+          ...(prevTools ?? {}),
+          ...(snippet.tools ?? {}),
+          ...(Object.prototype.hasOwnProperty.call(snippet.tools, "profile") ? { profile: snippet.tools.profile } : {}),
+          ...(Object.prototype.hasOwnProperty.call(snippet.tools, "allow") ? { allow: snippet.tools.allow } : {}),
+          ...(Object.prototype.hasOwnProperty.call(snippet.tools, "deny") ? { deny: snippet.tools.deny } : {}),
+        };
+
+  const nextAgent = {
+    ...prev,
+    id: snippet.id,
+    workspace: snippet.workspace,
+    identity: {
+      ...(prev?.identity ?? {}),
+      ...(snippet.identity ?? {}),
+    },
+    tools: nextTools,
+  };
+
+  if (idx >= 0) {
+    list[idx] = nextAgent;
+    return;
+  }
+
+  list.push(nextAgent);
+}

package/src/lib/bindings.ts

@@ -1,59 +1,9 @@
-// Minimal extracted binding helper so we can test precedence without running the CLI.
-
-import crypto from 'node:crypto';
-
-export type BindingMatch = {
-  channel?: string;
-  peer?: string;
-  [k: string]: any;
-};
-
-export type BindingSnippet = {
-  agentId: string;
-  match: BindingMatch;
-  to: any;
-  enabled?: boolean;
-};
-
-function stableStringify(obj: any) {
-  const seen = new WeakSet();
-  const walk = (x: any): any => {
-    if (x && typeof x === 'object') {
-      if (seen.has(x)) return '[Circular]';
-      seen.add(x);
-      if (Array.isArray(x)) return x.map(walk);
-      const keys = Object.keys(x).sort();
-      const out: any = {};
-      for (const k of keys) out[k] = walk(x[k]);
-      return out;
-    }
-    return x;
-  };
-  return JSON.stringify(walk(obj));
-}
-
-export function upsertBindingInConfig(cfgObj: any, binding: BindingSnippet) {
-  if (!Array.isArray(cfgObj.bindings)) cfgObj.bindings = [];
-  const list: any[] = cfgObj.bindings;
-
-  const sigPayload = stableStringify({ agentId: binding.agentId, match: binding.match });
-  const sig = crypto.createHash('sha256').update(sigPayload).digest('hex');
-
-  const idx = list.findIndex((b: any) => {
-    const payload = stableStringify({ agentId: b.agentId, match: b.match });
-    const bsig = crypto.createHash('sha256').update(payload).digest('hex');
-    return bsig === sig;
-  });
-
-  if (idx >= 0) {
-    // Update in place (preserve ordering)
-    list[idx] = { ...list[idx], ...binding };
-    return { changed: false as const, note: 'already-present' as const };
-  }
-
-  // Most-specific-first: if a peer match is specified, insert at front so it wins.
-  if (binding.match?.peer) list.unshift(binding);
-  else list.push(binding);
-
-  return { changed: true as const, note: 'added' as const };
-}
+/**
+ * @deprecated Use recipes-config for BindingMatch, BindingSnippet, upsertBindingInConfig.
+ * This module re-exports from recipes-config for backwards compatibility.
+ */
+export {
+  type BindingMatch,
+  type BindingSnippet,
+  upsertBindingInConfig,
+} from "./recipes-config";

package/src/lib/cleanup-workspaces.ts

@@ -81,7 +81,7 @@ export async function planWorkspaceCleanup(opts: {
   let entries: string[] = [];
   try {
     entries = await fs.readdir(rootDir);
-  } catch (e: any) {
+  } catch (e: unknown) {
     return {
       rootDir,
       prefixes,
@@ -91,7 +91,7 @@ export async function planWorkspaceCleanup(opts: {
           kind: 'skip',
           dirName: rootDir,
           absPath: rootDir,
-          reason: `failed to read rootDir: ${e?.message ? String(e.message) : String(e)}`,
+          reason: `failed to read rootDir: ${e instanceof Error ? e.message : String(e)}`,
         },
       ],
     } satisfies CleanupPlan;
@@ -156,8 +156,8 @@ export async function executeWorkspaceCleanup(plan: CleanupPlan, opts: { yes: bo
     try {
       await fs.rm(c.absPath, { recursive: true, force: true });
       deleted.push(c.absPath);
-    } catch (e: any) {
-      deleteErrors.push({ path: c.absPath, error: e?.message ? String(e.message) : String(e) });
+    } catch (e: unknown) {
+      deleteErrors.push({ path: c.absPath, error: e instanceof Error ? e.message : String(e) });
     }
   }
 

package/src/lib/config.ts

@@ -0,0 +1,47 @@
+export type RecipesConfig = {
+  workspaceRecipesDir?: string;
+  workspaceAgentsDir?: string;
+  workspaceSkillsDir?: string;
+  workspaceTeamsDir?: string;
+  autoInstallMissingSkills?: boolean;
+  confirmAutoInstall?: boolean;
+  cronInstallation?: "off" | "prompt" | "on";
+};
+
+export type RequiredRecipesConfig = Required<RecipesConfig>;
+
+function extractPluginRecipesConfig(config: {
+  plugins?: { entries?: { recipes?: { config?: RecipesConfig }; [k: string]: unknown } };
+}): RecipesConfig {
+  return (config?.plugins?.entries?.["recipes"]?.config ?? config?.plugins?.entries?.recipes?.config ?? {}) as RecipesConfig;
+}
+
+const DEFAULT_RECIPES_CONFIG: RequiredRecipesConfig = {
+  workspaceRecipesDir: "recipes",
+  workspaceAgentsDir: "agents",
+  workspaceSkillsDir: "skills",
+  workspaceTeamsDir: "teams",
+  autoInstallMissingSkills: false,
+  confirmAutoInstall: true,
+  cronInstallation: "prompt",
+};
+
+/**
+ * Get recipes plugin config with defaults.
+ * @param config - OpenClaw config (plugins.entries.recipes.config)
+ * @returns RequiredRecipesConfig with all keys defined
+ */
+export function getRecipesConfig(config: {
+  plugins?: { entries?: { recipes?: { config?: RecipesConfig }; [k: string]: unknown } };
+}): RequiredRecipesConfig {
+  const cfg = extractPluginRecipesConfig(config);
+  return {
+    workspaceRecipesDir: cfg.workspaceRecipesDir ?? DEFAULT_RECIPES_CONFIG.workspaceRecipesDir,
+    workspaceAgentsDir: cfg.workspaceAgentsDir ?? DEFAULT_RECIPES_CONFIG.workspaceAgentsDir,
+    workspaceSkillsDir: cfg.workspaceSkillsDir ?? DEFAULT_RECIPES_CONFIG.workspaceSkillsDir,
+    workspaceTeamsDir: cfg.workspaceTeamsDir ?? DEFAULT_RECIPES_CONFIG.workspaceTeamsDir,
+    autoInstallMissingSkills: cfg.autoInstallMissingSkills ?? DEFAULT_RECIPES_CONFIG.autoInstallMissingSkills,
+    confirmAutoInstall: cfg.confirmAutoInstall ?? DEFAULT_RECIPES_CONFIG.confirmAutoInstall,
+    cronInstallation: cfg.cronInstallation ?? DEFAULT_RECIPES_CONFIG.cronInstallation,
+  };
+}

package/src/lib/constants.ts

@@ -0,0 +1,11 @@
+export const VALID_ROLES = ["dev", "devops", "lead", "test"] as const;
+export type ValidRole = (typeof VALID_ROLES)[number];
+
+export const VALID_STAGES = ["backlog", "in-progress", "testing", "done"] as const;
+export type ValidStage = (typeof VALID_STAGES)[number];
+
+/** Max auto-increment attempts for pickRecipeId (e.g. id-2, id-3, ... id-999). */
+export const MAX_RECIPE_ID_AUTO_INCREMENT = 1000;
+
+/** Fallback ticket number when parsing fails. */
+export const DEFAULT_TICKET_NUMBER = "0000";

package/src/lib/cron-utils.ts

@@ -0,0 +1,54 @@
+import crypto from "node:crypto";
+import { readJsonFile } from "./json-utils";
+import { stableStringify } from "./stable-stringify";
+
+export type CronMappingStateV1 = {
+  version: 1;
+  entries: Record<
+    string,
+    {
+      installedCronId: string;
+      specHash: string;
+      orphaned?: boolean;
+      updatedAtMs: number;
+    }
+  >;
+};
+
+export async function loadCronMappingState(statePath: string): Promise<CronMappingStateV1> {
+  const existing = await readJsonFile<CronMappingStateV1>(statePath);
+  if (existing && existing.version === 1 && existing.entries && typeof existing.entries === "object") return existing;
+  return { version: 1, entries: {} };
+}
+
+export function cronKey(
+  scope:
+    | { kind: "team"; teamId: string; recipeId: string }
+    | { kind: "agent"; agentId: string; recipeId: string },
+  cronJobId: string
+): string {
+  return scope.kind === "team"
+    ? `team:${scope.teamId}:recipe:${scope.recipeId}:cron:${cronJobId}`
+    : `agent:${scope.agentId}:recipe:${scope.recipeId}:cron:${cronJobId}`;
+}
+
+export function hashSpec(spec: unknown): string {
+  const json = stableStringify(spec);
+  return crypto.createHash("sha256").update(json, "utf8").digest("hex");
+}
+
+/**
+ * Parse JSON from tool text output. Throws with label and cause on parse error.
+ */
+export function parseToolTextJson<T = unknown>(text: string, label: string): T | null {
+  const trimmed = String(text ?? "").trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as T;
+  } catch (e) {
+    const err = new Error(`Failed parsing JSON from tool text (${label})`);
+    (err as Error & { text?: string; cause?: unknown }).text = text;
+    (err as Error & { text?: string; cause?: unknown }).cause = e;
+    throw err;
+  }
+}

package/src/lib/fs-utils.ts

@@ -0,0 +1,33 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+/**
+ * Check if a path exists (file or directory).
+ * Uses fs.stat for consistency across the codebase.
+ */
+export async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(p: string): Promise<void> {
+  await fs.mkdir(p, { recursive: true });
+}
+
+/**
+ * Write content to a file, with optional createOnly mode.
+ */
+export async function writeFileSafely(
+  p: string,
+  content: string,
+  mode: "createOnly" | "overwrite"
+): Promise<{ wrote: boolean; reason: "exists" | "ok" }> {
+  if (mode === "createOnly" && (await fileExists(p))) return { wrote: false, reason: "exists" };
+  await ensureDir(path.dirname(p));
+  await fs.writeFile(p, content, "utf8");
+  return { wrote: true, reason: "ok" };
+}

package/src/lib/json-utils.ts

@@ -0,0 +1,17 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { ensureDir } from "./fs-utils";
+
+export async function readJsonFile<T>(p: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(p, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeJsonFile(p: string, data: unknown): Promise<void> {
+  await ensureDir(path.dirname(p));
+  await fs.writeFile(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+}

package/src/lib/lanes.ts

@@ -1,7 +1,7 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
+import fs from "node:fs/promises";
+import path from "node:path";
 
-export type TicketLane = 'backlog' | 'in-progress' | 'testing' | 'done' | 'assignments';
+import { fileExists } from "./fs-utils";
 
 export class RecipesCliError extends Error {
   code: string;
@@ -19,13 +19,15 @@ export class RecipesCliError extends Error {
   }
 }
 
-async function fileExists(p: string) {
-  try {
-    await fs.stat(p);
-    return true;
-  } catch {
-    return false;
-  }
+export type TicketStage = "backlog" | "in-progress" | "testing" | "done" | "assignments";
+
+/** Subset of TicketStage excluding assignments (used for lane search order). */
+export type TicketLane = Exclude<TicketStage, "assignments">;
+
+export function ticketStageDir(teamDir: string, stage: TicketStage): string {
+  return stage === "assignments"
+    ? path.join(teamDir, "work", "assignments")
+    : path.join(teamDir, "work", stage);
 }
 
 /**
@@ -40,7 +42,7 @@ export async function ensureLaneDir(opts: { teamDir: string; lane: TicketLane; c
   if (!existed) {
     try {
       await fs.mkdir(laneDir, { recursive: true });
-    } catch (e: any) {
+    } catch (e: unknown) {
       throw new RecipesCliError({
         code: 'LANE_DIR_CREATE_FAILED',
         command: opts.command,
@@ -49,7 +51,7 @@ export async function ensureLaneDir(opts: { teamDir: string; lane: TicketLane; c
         message:
           `Failed to create required lane directory: ${laneDir}` +
           (opts.command ? ` (command: ${opts.command})` : '') +
-          (e?.message ? `\nUnderlying error: ${String(e.message)}` : ''),
+          (e instanceof Error ? `\nUnderlying error: ${e.message}` : ''),
       });
     }