@clawcipes/recipes 0.2.4 → 0.2.6

package/src/lib/lanes.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export type TicketLane = 'backlog' | 'in-progress' | 'testing' | 'done' | 'assignments';
+
+export class RecipesCliError extends Error {
+  code: string;
+  command?: string;
+  missingPath?: string;
+  suggestedFix?: string;
+
+  constructor(opts: { message: string; code: string; command?: string; missingPath?: string; suggestedFix?: string }) {
+    super(opts.message);
+    this.name = 'RecipesCliError';
+    this.code = opts.code;
+    this.command = opts.command;
+    this.missingPath = opts.missingPath;
+    this.suggestedFix = opts.suggestedFix;
+  }
+}
+
+async function fileExists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a lane dir exists, with a one-line migration hint for older workspaces.
+ *
+ * If creation fails, throws a RecipesCliError with an actionable message.
+ */
+export async function ensureLaneDir(opts: { teamDir: string; lane: TicketLane; command?: string; quiet?: boolean }) {
+  const laneDir = path.join(opts.teamDir, 'work', opts.lane);
+  const existed = await fileExists(laneDir);
+
+  if (!existed) {
+    try {
+      await fs.mkdir(laneDir, { recursive: true });
+    } catch (e: any) {
+      throw new RecipesCliError({
+        code: 'LANE_DIR_CREATE_FAILED',
+        command: opts.command,
+        missingPath: laneDir,
+        suggestedFix: `mkdir -p ${path.join('work', opts.lane)}`,
+        message:
+          `Failed to create required lane directory: ${laneDir}` +
+          (opts.command ? ` (command: ${opts.command})` : '') +
+          (e?.message ? `\nUnderlying error: ${String(e.message)}` : ''),
+      });
+    }
+
+    if (!opts.quiet) {
+      const rel = path.join('work', opts.lane);
+      console.error(`[recipes] migration: created ${rel}/ (older workspace missing this lane)`);
+    }
+  }
+
+  return { path: laneDir, created: !existed };
+}

package/src/lib/recipe-frontmatter.ts

@@ -0,0 +1,59 @@
+import YAML from 'yaml';
+
+export type CronJobSpec = {
+  id: string;
+  schedule: string;
+  message: string;
+  name?: string;
+  description?: string;
+  timezone?: string;
+  channel?: string;
+  to?: string;
+  agentId?: string;
+  enabledByDefault?: boolean;
+};
+
+export type RecipeFrontmatter = {
+  id: string;
+  kind?: string;
+  name?: string;
+  cronJobs?: CronJobSpec[];
+  [k: string]: any;
+};
+
+export function parseFrontmatter(md: string): { frontmatter: RecipeFrontmatter; body: string } {
+  if (!md.startsWith('---\n')) throw new Error('Recipe markdown must start with YAML frontmatter (---)');
+  const end = md.indexOf('\n---\n', 4);
+  if (end === -1) throw new Error('Recipe frontmatter not terminated (---)');
+  const yamlText = md.slice(4, end);
+  const body = md.slice(end + 5);
+  const frontmatter = YAML.parse(yamlText) as RecipeFrontmatter;
+  if (!frontmatter?.id) throw new Error('Recipe frontmatter must include id');
+  return { frontmatter, body };
+}
+
+export function normalizeCronJobs(frontmatter: { cronJobs?: any }): CronJobSpec[] {
+  const raw = (frontmatter as any).cronJobs;
+  if (!raw) return [];
+  if (!Array.isArray(raw)) throw new Error('frontmatter.cronJobs must be an array');
+
+  const seen = new Set<string>();
+  const out: CronJobSpec[] = [];
+
+  for (const j of raw) {
+    if (!j || typeof j !== 'object') throw new Error('cronJobs entries must be objects');
+    const id = String((j as any).id ?? '').trim();
+    if (!id) throw new Error('cronJobs[].id is required');
+    if (seen.has(id)) throw new Error(`Duplicate cronJobs[].id: ${id}`);
+    seen.add(id);
+
+    const schedule = String((j as any).schedule ?? '').trim();
+    const message = String((j as any).message ?? '').trim();
+    if (!schedule) throw new Error(`cronJobs[${id}].schedule is required`);
+    if (!message) throw new Error(`cronJobs[${id}].message is required`);
+
+    out.push({ ...j, id, schedule, message } as CronJobSpec);
+  }
+
+  return out;
+}

package/src/lib/scaffold-templates.ts

@@ -0,0 +1,7 @@
+export function renderTeamMd(teamId: string) {
+  return `# ${teamId}\n\nShared workspace for this agent team.\n\n## Workflow\n- Stages: backlog → in-progress → testing → done\n- Backlog: work/backlog/\n- In progress: work/in-progress/\n- Testing / QA: work/testing/\n- Done: work/done/\n\n## QA verification\nBefore moving a ticket from work/testing/ → work/done/, record verification results.\n- Template: notes/QA_CHECKLIST.md\n- Preferred: create work/testing/<ticket>.testing-verified.md\n\n## Folders\n- inbox/ — requests\n- outbox/ — deliverables\n- shared-context/ — curated shared context + append-only agent outputs\n- shared/ — legacy shared artifacts (back-compat)\n- notes/ — plan + status + templates\n- work/ — working files\n`;
+}
+
+export function renderTicketsMd(teamId: string) {
+  return `# Tickets — ${teamId}\n\n## Workflow\n- Stages: backlog → in-progress → testing → done\n- Backlog tickets live in work/backlog/\n- In-progress tickets live in work/in-progress/\n- Testing / QA tickets live in work/testing/\n- Done tickets live in work/done/\n\n### QA handoff (dev → test)\nWhen development is complete:\n- Move the ticket file to work/testing/\n- Assign to test (set \`Owner: test\`)\n- Add clear test instructions / repro steps\n\n### QA verification (test → done)\nBefore moving a ticket to done, QA must record verification.\n- Template: notes/QA_CHECKLIST.md\n- Preferred: create work/testing/<ticket>.testing-verified.md\n\n## Naming\n- Filename ordering is the queue: 0001-..., 0002-...\n\n## Required fields\nEach ticket should include:\n- Title\n- Context\n- Requirements\n- Acceptance criteria\n- Owner (dev/devops/lead/test)\n- Status (queued/in-progress/testing/done)\n\n## Example\n\n\`\`\`md\n# 0001-example-ticket\n\nOwner: dev\nStatus: queued\n\n## Context\n...\n\n## Requirements\n- ...\n\n## Acceptance criteria\n- ...\n\n## How to test\n- ...\n\`\`\`\n`;
+}

package/src/lib/shared-context.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+async function ensureDir(p: string) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function exists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeCreateOnlyOrOverwrite(filePath: string, content: string, mode: 'createOnly' | 'overwrite') {
+  if (mode === 'createOnly' && (await exists(filePath))) return { wrote: false as const };
+  await fs.writeFile(filePath, content, 'utf8');
+  return { wrote: true as const };
+}
+
+export async function ensureSharedContextScaffold(opts: { teamDir: string; teamId: string; overwrite: boolean }) {
+  const { teamDir, teamId, overwrite } = opts;
+  const sharedContextDir = path.join(teamDir, 'shared-context');
+  const outputsDir = path.join(sharedContextDir, 'agent-outputs');
+  const feedbackDir = path.join(sharedContextDir, 'feedback');
+  const kpisDir = path.join(sharedContextDir, 'kpis');
+  const calendarDir = path.join(sharedContextDir, 'calendar');
+
+  await Promise.all([
+    // Back-compat alias: keep shared/ folder.
+    ensureDir(path.join(teamDir, 'shared')),
+    ensureDir(sharedContextDir),
+    ensureDir(outputsDir),
+    ensureDir(feedbackDir),
+    ensureDir(kpisDir),
+    ensureDir(calendarDir),
+  ]);
+
+  const prioritiesPath = path.join(sharedContextDir, 'priorities.md');
+  const prioritiesMd = `# Priorities — ${teamId}\n\n- (empty)\n\n## Notes\n- Lead curates this file.\n- Non-lead roles should append updates to shared-context/agent-outputs/ instead.\n`;
+
+  const mode = overwrite ? 'overwrite' : 'createOnly';
+  const wrote = await writeCreateOnlyOrOverwrite(prioritiesPath, prioritiesMd, mode);
+
+  return {
+    sharedContextDir,
+    prioritiesPath,
+    wrotePriorities: wrote.wrote,
+  };
+}

package/src/lib/ticket-finder.ts

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+async function fileExists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type TicketLane = 'backlog' | 'in-progress' | 'testing' | 'done';
+
+export function laneDir(teamDir: string, lane: TicketLane) {
+  return path.join(teamDir, 'work', lane);
+}
+
+export function allLaneDirs(teamDir: string) {
+  return [
+    laneDir(teamDir, 'backlog'),
+    laneDir(teamDir, 'in-progress'),
+    laneDir(teamDir, 'testing'),
+    laneDir(teamDir, 'done'),
+  ];
+}
+
+export function parseTicketArg(ticketArg: string) {
+  const ticketNum = ticketArg.match(/^\d{4}$/)
+    ? ticketArg
+    : (ticketArg.match(/^(\d{4})-/)?.[1] ?? null);
+  return { ticketArg, ticketNum };
+}
+
+export async function findTicketFile(opts: {
+  teamDir: string;
+  ticket: string;
+  lanes?: TicketLane[];
+}) {
+  const lanes = opts.lanes ?? ['backlog', 'in-progress', 'testing', 'done'];
+  const { ticketArg, ticketNum } = parseTicketArg(String(opts.ticket));
+
+  for (const lane of lanes) {
+    const dir = laneDir(opts.teamDir, lane);
+    if (!(await fileExists(dir))) continue;
+    const files = await fs.readdir(dir);
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue;
+      if (ticketNum && f.startsWith(`${ticketNum}-`)) return path.join(dir, f);
+      if (!ticketNum && f.replace(/\.md$/, '') === ticketArg) return path.join(dir, f);
+    }
+  }
+
+  return null;
+}
+
+export function parseOwnerFromMd(md: string): string | null {
+  const m = md.match(/^Owner:\s*(.+)\s*$/m);
+  return m?.[1]?.trim() ?? null;
+}

package/src/lib/ticket-workflow.ts

@@ -0,0 +1,94 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ensureLaneDir } from './lanes';
+
+async function fileExists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(p: string) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+export async function findTicketFile(teamDir: string, ticketArg: string) {
+  const stageDir = (stage: string) => path.join(teamDir, 'work', stage);
+  const searchDirs = [stageDir('backlog'), stageDir('in-progress'), stageDir('testing'), stageDir('done')];
+
+  const ticketNum = ticketArg.match(/^\d{4}$/) ? ticketArg : (ticketArg.match(/^(\d{4})-/)?.[1] ?? null);
+
+  for (const dir of searchDirs) {
+    if (!(await fileExists(dir))) continue;
+    const files = await fs.readdir(dir);
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue;
+      if (ticketNum && f.startsWith(`${ticketNum}-`)) return path.join(dir, f);
+      if (!ticketNum && f.replace(/\.md$/, '') === ticketArg) return path.join(dir, f);
+    }
+  }
+  return null;
+}
+
+export async function handoffTicket(opts: { teamDir: string; ticket: string; tester?: string; overwriteAssignment: boolean }) {
+  const teamDir = opts.teamDir;
+  const tester = (opts.tester ?? 'test').trim() || 'test';
+  const testerSafe = tester.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/(^-|-$)/g, '') || 'test';
+
+  const srcPath = await findTicketFile(teamDir, opts.ticket);
+  if (!srcPath) throw new Error(`Ticket not found: ${opts.ticket}`);
+  if (srcPath.includes(`${path.sep}work${path.sep}done${path.sep}`)) throw new Error('Cannot handoff a done ticket (already completed)');
+
+  const testingDir = (await ensureLaneDir({ teamDir, lane: 'testing', command: 'openclaw recipes handoff' })).path;
+
+  const filename = path.basename(srcPath);
+  const destPath = path.join(testingDir, filename);
+
+  const m = filename.match(/^(\d{4})-(.+)\.md$/);
+  const ticketNumStr = m?.[1] ?? (opts.ticket.match(/^\d{4}$/) ? opts.ticket : '0000');
+  const slug = m?.[2] ?? 'ticket';
+
+  const assignmentsDir = path.join(teamDir, 'work', 'assignments');
+  await ensureDir(assignmentsDir);
+  const assignmentPath = path.join(assignmentsDir, `${ticketNumStr}-assigned-${testerSafe}.md`);
+  const assignmentRel = path.relative(teamDir, assignmentPath);
+
+  const patch = (md: string) => {
+    let out = md;
+    if (out.match(/^Owner:\s.*$/m)) out = out.replace(/^Owner:\s.*$/m, `Owner: ${testerSafe}`);
+    else out = out.replace(/^(# .+\n)/, `$1\nOwner: ${testerSafe}\n`);
+
+    if (out.match(/^Status:\s.*$/m)) out = out.replace(/^Status:\s.*$/m, 'Status: testing');
+    else out = out.replace(/^(# .+\n)/, `$1\nStatus: testing\n`);
+
+    if (out.match(/^Assignment:\s.*$/m)) out = out.replace(/^Assignment:\s.*$/m, `Assignment: ${assignmentRel}`);
+    else out = out.replace(/^Owner:.*$/m, (line) => `${line}\nAssignment: ${assignmentRel}`);
+
+    return out;
+  };
+
+  const alreadyInTesting = srcPath === destPath;
+
+  const md = await fs.readFile(srcPath, 'utf8');
+  const nextMd = patch(md);
+  await fs.writeFile(srcPath, nextMd, 'utf8');
+
+  if (!alreadyInTesting) {
+    await fs.rename(srcPath, destPath);
+  }
+
+  const assignmentMd = `# Assignment — ${ticketNumStr}-${slug}\n\nAssigned: ${testerSafe}\n\n## Ticket\n${path.relative(teamDir, destPath)}\n\n## Notes\n- Created by: openclaw recipes handoff\n`;
+
+  const assignmentExists = await fileExists(assignmentPath);
+  if (assignmentExists && !opts.overwriteAssignment) {
+    // createOnly: leave as-is
+  } else {
+    await fs.writeFile(assignmentPath, assignmentMd, 'utf8');
+  }
+
+  return { srcPath, destPath, moved: !alreadyInTesting, assignmentPath };
+}