@farmslot/skills 0.1.0

package/scripts/lib.cjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function readJsonLines(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return [];
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function appendJsonl(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`, 'utf8');
+}
+
+function expandTemplate(template, vars = {}) {
+  let result = String(template || '');
+  for (const [key, value] of Object.entries(vars)) {
+    const rendered = value == null ? '' : String(value);
+    result = result.replaceAll(`{{${key}}}`, rendered);
+    result = result.replaceAll(`{{${String(key).toUpperCase()}}}`, rendered);
+  }
+  return result;
+}
+
+function qualitySemanticToScore(semantic) {
+  if (semantic === 'good') return 1.0;
+  if (semantic === 'ok') return 0.6;
+  return 0.0;
+}
+
+function resolvePassRate(meta, laneResult) {
+  if (laneResult.live_run_exit === 0) return 1.0;
+  if (typeof laneResult.live_run_exit === 'number' && laneResult.live_run_exit !== 0) return 0.0;
+  if (meta && meta.validate_exit === 0) return 1.0;
+  if (meta && typeof meta.validate_exit === 'number' && meta.validate_exit > 0) return 0.0;
+  if (meta && meta.validate_exit === -1) return null;
+  return null;
+}
+
+function resolveInferenceCost(sessionMetrics) {
+  if (sessionMetrics && typeof sessionMetrics.costEstimate === 'number')
+    return sessionMetrics.costEstimate;
+  const costString = sessionMetrics && sessionMetrics.session && sessionMetrics.session.cost_usd;
+  if (costString != null) {
+    const parsed = Number(costString);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  return null;
+}
+
+function normalizeCostEfficiency(cost, baseline) {
+  if (cost == null || baseline == null || baseline <= 0) return null;
+  return 1 - Math.min(cost / baseline, 1);
+}
+
+function aggregateAverage(values) {
+  const filtered = values.filter((value) => value != null);
+  if (filtered.length === 0) return null;
+  return filtered.reduce((sum, value) => sum + value, 0) / filtered.length;
+}
+
+const RECIPE_COOK_SELF_EDIT_ROOTS = [
+  'recipe-cook/',
+  'packages/skills/skills/recipe-cook/',
+  '.agents/skills/recipe-cook/',
+  '.codex/skills/recipe-cook/',
+  '.claude/skills/recipe-cook/',
+  '.cursor/skills/recipe-cook/',
+];
+
+function normalizeRepoPath(value) {
+  return String(value || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+}
+
+function isRecipeCookSelfEditPath(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  return RECIPE_COOK_SELF_EDIT_ROOTS.some((root) => normalized.startsWith(root));
+}
+
+function validateLearningArtifact(artifact, expectedArtifactDir) {
+  const required = [
+    'run_id',
+    'scenario_type',
+    'target_repo',
+    'artifact_dir',
+    'validation_results',
+    'evidence_verdict',
+    'recipe_path',
+    'next_delta',
+    'touched_files',
+  ];
+  required.forEach((field) =>
+    assert(
+      Object.prototype.hasOwnProperty.call(artifact || {}, field),
+      `Learning artifact missing required field: ${field}`,
+    ),
+  );
+  const normalizePath = (value) => {
+    const resolved = path.resolve(value);
+    try {
+      return fs.realpathSync.native ? fs.realpathSync.native(resolved) : fs.realpathSync(resolved);
+    } catch {
+      return resolved;
+    }
+  };
+  assert(
+    normalizePath(artifact.artifact_dir) === normalizePath(expectedArtifactDir),
+    'Learning artifact artifact_dir does not match scenario artifact dir',
+  );
+  assert(Array.isArray(artifact.touched_files), 'Learning artifact touched_files must be an array');
+  const illegalTouch = artifact.touched_files.find((item) => isRecipeCookSelfEditPath(item));
+  assert(!illegalTouch, `Cooking run illegally touched recipe-cook package path: ${illegalTouch}`);
+}
+
+function compareScoreVectors(current, previous) {
+  const currentBalanced = current.balanced_score;
+  const previousBalanced =
+    previous && previous.balanced_score != null ? previous.balanced_score : null;
+
+  if (currentBalanced != null && previousBalanced != null) {
+    if (currentBalanced > previousBalanced) return 1;
+    if (currentBalanced < previousBalanced) return -1;
+  }
+
+  if (current.quality > (previous ? previous.quality : -1)) return 1;
+  if (current.quality < (previous ? previous.quality : -1)) return -1;
+  if (current.pass_rate > (previous ? previous.pass_rate : -1)) return 1;
+  if (current.pass_rate < (previous ? previous.pass_rate : -1)) return -1;
+  if ((current.cost_efficiency ?? -1) > (previous ? (previous.cost_efficiency ?? -1) : -1))
+    return 1;
+  if ((current.cost_efficiency ?? -1) < (previous ? (previous.cost_efficiency ?? -1) : -1))
+    return -1;
+  return 0;
+}
+
+function decisionFromScores(scoreVector, laneResults, previousVersion) {
+  const floorsMet = laneResults.every(
+    (lane) => lane.quality >= 0.8 && lane.pass_rate != null && lane.pass_rate >= 0.8,
+  );
+  if (!floorsMet) {
+    return { decision: 'reject', reason: 'One or more lanes failed quality/pass-rate floors.' };
+  }
+
+  if (scoreVector.cost_efficiency == null) {
+    if (!previousVersion) {
+      return {
+        decision: 'reject',
+        reason: 'Missing cost coverage cannot promote the first candidate to keep.',
+      };
+    }
+    if (
+      previousVersion.aggregate_score_vector &&
+      previousVersion.aggregate_score_vector.cost_efficiency != null
+    ) {
+      const previousComparable = {
+        quality: previousVersion.aggregate_score_vector.quality,
+        pass_rate: previousVersion.aggregate_score_vector.pass_rate,
+        cost_efficiency: previousVersion.aggregate_score_vector.cost_efficiency,
+        balanced_score: null,
+      };
+      const compare = compareScoreVectors(scoreVector, previousComparable);
+      if (compare >= 0) {
+        return {
+          decision: 'reject',
+          reason: 'Missing cost coverage cannot replace the current best-known version.',
+        };
+      }
+      return {
+        decision: 'reject',
+        reason: 'Missing cost coverage loses on quality/pass-rate tie-breaks.',
+      };
+    }
+  }
+
+  if (!previousVersion) {
+    return { decision: 'keep', reason: 'First candidate that clears all required floors.' };
+  }
+
+  const compare = compareScoreVectors(scoreVector, previousVersion.aggregate_score_vector);
+  if (compare >= 0) {
+    return {
+      decision: 'keep',
+      reason: 'Candidate improves or matches incumbent under score/tie-break rules.',
+    };
+  }
+  return { decision: 'reject', reason: 'Candidate underperforms the current incumbent.' };
+}
+
+function computeConvergenceState(versionLedger, runEntries = []) {
+  const versions = [...(versionLedger.versions || [])];
+  const recent = versions.slice(-3);
+  const plateau =
+    recent.length === 3 &&
+    recent.every(
+      (entry) =>
+        entry.aggregate_score_vector && entry.aggregate_score_vector.balanced_score != null,
+    ) &&
+    Math.max(...recent.map((entry) => entry.aggregate_score_vector.balanced_score)) -
+      Math.min(...recent.map((entry) => entry.aggregate_score_vector.balanced_score)) <=
+      0.02;
+
+  const latest = versions[versions.length - 1];
+  const latestRuns = latest
+    ? runEntries.filter((entry) => entry.version_id_under_test === latest.version_id)
+    : [];
+  const laneSuccess =
+    latestRuns.length > 0 &&
+    latestRuns.every(
+      (entry) => entry.quality >= 0.9 && entry.pass_rate != null && entry.pass_rate >= 0.9,
+    );
+  const bestKnownCost =
+    versions
+      .map(
+        (entry) =>
+          entry.aggregate_score_vector && entry.aggregate_score_vector.raw_inference_cost_usd,
+      )
+      .filter((value) => value != null)
+      .sort((a, b) => a - b)[0] ?? null;
+  const latestCost =
+    latest && latest.aggregate_score_vector
+      ? latest.aggregate_score_vector.raw_inference_cost_usd
+      : null;
+  const costWithinBand =
+    bestKnownCost != null && latestCost != null && latestCost <= bestKnownCost * 1.1;
+  const successBand =
+    latest &&
+    latest.aggregate_score_vector &&
+    latest.aggregate_score_vector.quality >= 0.9 &&
+    latest.aggregate_score_vector.pass_rate >= 0.9 &&
+    laneSuccess &&
+    costWithinBand;
+
+  return {
+    plateau,
+    converged: Boolean(plateau || successBand),
+  };
+}
+
+function computeAggregateScore(laneResults, baseline) {
+  const quality = aggregateAverage(laneResults.map((result) => result.quality));
+  const passRate = aggregateAverage(laneResults.map((result) => result.pass_rate));
+  const rawCost = aggregateAverage(laneResults.map((result) => result.inference_cost_usd));
+  const costs = laneResults.map((result) =>
+    normalizeCostEfficiency(result.inference_cost_usd, baseline),
+  );
+  const costEfficiency = aggregateAverage(costs);
+  const balancedScore =
+    costEfficiency == null ? null : quality * 0.45 + passRate * 0.4 + costEfficiency * 0.15;
+  return {
+    quality,
+    pass_rate: passRate,
+    cost_efficiency: costEfficiency,
+    balanced_score: balancedScore,
+    raw_inference_cost_usd: rawCost,
+  };
+}
+
+function buildLaneResult({ lane, scenarioId, artifactDir, learningArtifactPath }) {
+  const gradePath = path.join(artifactDir, 'grade.json');
+  const metaPath = path.join(artifactDir, 'meta.json');
+  const sessionMetricsPath = path.join(artifactDir, 'session-metrics.json');
+  const probeStatePath = path.join(artifactDir, 'probe-state.json');
+  const recipePath = path.join(artifactDir, 'recipe.json');
+  const recipeCookPath = path.join(artifactDir, 'recipe-cook.json');
+
+  const grade = readJsonIfExists(gradePath);
+  const meta = readJsonIfExists(metaPath);
+  const sessionMetrics = readJsonIfExists(sessionMetricsPath);
+  const probeState = readJsonIfExists(probeStatePath);
+  const recipeCook = readJsonIfExists(recipeCookPath);
+  assert(fs.existsSync(recipePath), `Missing required recipe artifact: ${recipePath}`);
+
+  let qualitySemantic = grade && grade.recipe_semantic;
+  let qualityReasoning = (grade && grade.reasoning) || '';
+  if (!qualitySemantic) {
+    qualitySemantic = recipeCook ? 'ok' : 'bad';
+    qualityReasoning = recipeCook
+      ? 'Fallback semantic score derived from recipe-cook artifact presence.'
+      : 'No grade or recipe-cook artifact available.';
+  }
+
+  const passRateInput = resolvePassRate(meta, { live_run_exit: null });
+  const liveRunExit =
+    meta && typeof meta.validate_exit === 'number' && meta.validate_exit >= 0
+      ? meta.validate_exit
+      : null;
+  const inferenceCost = resolveInferenceCost(sessionMetrics);
+
+  return {
+    lane,
+    scenario_id: scenarioId,
+    task_artifact_dir: artifactDir,
+    learning_artifact_path: learningArtifactPath,
+    recipe_path: recipePath,
+    recipe_cook_path: fs.existsSync(recipeCookPath) ? recipeCookPath : null,
+    quality_semantic: qualitySemantic,
+    quality_reasoning: qualityReasoning,
+    live_run_exit: liveRunExit,
+    pass_rate_input: passRateInput,
+    inference_cost_usd: inferenceCost,
+    source_artifacts: {
+      grade_path: fs.existsSync(gradePath) ? gradePath : null,
+      meta_path: fs.existsSync(metaPath) ? metaPath : null,
+      session_metrics_path: fs.existsSync(sessionMetricsPath) ? sessionMetricsPath : null,
+      probe_state_path: probeState ? probeStatePath : null,
+    },
+    quality: qualitySemanticToScore(qualitySemantic),
+    pass_rate: passRateInput,
+  };
+}
+
+module.exports = {
+  appendJsonl,
+  assert,
+  buildLaneResult,
+  compareScoreVectors,
+  computeAggregateScore,
+  computeConvergenceState,
+  decisionFromScores,
+  expandTemplate,
+  isRecipeCookSelfEditPath,
+  normalizeRepoPath,
+  normalizeCostEfficiency,
+  qualitySemanticToScore,
+  readJsonIfExists,
+  readJsonLines,
+  resolveInferenceCost,
+  resolvePassRate,
+  validateLearningArtifact,
+  writeJson,
+};

package/scripts/prepare-cooking-run.cjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { expandTemplate } = require('./lib.cjs');
+
+const TEMPLATE_PATH = path.resolve(__dirname, '../skills/recipe-cook/references/TASK.md');
+const OVERLAYS = {
+  'example-browser': path.resolve(__dirname, '../skills/recipe-cook/repos/example-browser.md'),
+  'example-mobile': path.resolve(__dirname, '../skills/recipe-cook/repos/example-mobile.md'),
+};
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    repo: '',
+    repoRoot: '',
+    sourceKind: '',
+    sourceRef: '',
+    sourceText: '',
+    outputDir: '',
+    runId: '',
+    wrapper: '',
+    ghRepo: '',
+    jiraBaseUrl: process.env.JIRA_BASE_URL || '',
+    jiraEmail: process.env.JIRA_EMAIL || '',
+    jiraToken: process.env.JIRA_API_TOKEN || '',
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    switch (argv[i]) {
+      case '--repo':
+        args.repo = argv[++i] || '';
+        break;
+      case '--repo-root':
+        args.repoRoot = path.resolve(argv[++i] || '');
+        break;
+      case '--source-kind':
+        args.sourceKind = argv[++i] || '';
+        break;
+      case '--source-ref':
+        args.sourceRef = argv[++i] || '';
+        break;
+      case '--source-text':
+        args.sourceText = argv[++i] || '';
+        break;
+      case '--output-dir':
+        args.outputDir = path.resolve(argv[++i] || '');
+        break;
+      case '--run-id':
+        args.runId = argv[++i] || '';
+        break;
+      case '--wrapper':
+        args.wrapper = argv[++i] || '';
+        break;
+      case '--gh-repo':
+        args.ghRepo = argv[++i] || '';
+        break;
+      case '--jira-base-url':
+        args.jiraBaseUrl = argv[++i] || '';
+        break;
+      case '--jira-email':
+        args.jiraEmail = argv[++i] || '';
+        break;
+      case '--jira-token':
+        args.jiraToken = argv[++i] || '';
+        break;
+      default:
+        break;
+    }
+  }
+
+  return args;
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'run'
+  );
+}
+
+function writeFile(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents, 'utf8');
+}
+
+function writeJson(filePath, value) {
+  writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function inferRepoName(repoRoot) {
+  const base = path.basename(repoRoot);
+  if (base.includes('browser')) return 'example-browser';
+  if (base.includes('mobile')) return 'example-mobile';
+  return base;
+}
+
+function fetchPrBundle(sourceRef, ghRepo) {
+  assert(ghRepo, 'PR source kind requires --gh-repo <owner/name>');
+  const view = spawnSync(
+    'gh',
+    [
+      'pr',
+      'view',
+      sourceRef,
+      '--repo',
+      ghRepo,
+      '--json',
+      'title,body,headRefName,changedFiles,labels,author,mergeStateStatus,state,mergedAt,url',
+    ],
+    { encoding: 'utf8' },
+  );
+  assert(view.status === 0, `gh pr view failed: ${view.stderr || view.stdout}`);
+  const diff = spawnSync('gh', ['pr', 'diff', sourceRef, '--repo', ghRepo], {
+    encoding: 'utf8',
+    maxBuffer: 20 * 1024 * 1024,
+  });
+  assert(
+    diff.error?.code !== 'ENOBUFS',
+    `gh pr diff exceeded 20MB buffer for PR ${sourceRef}; stream to disk or split the source.`,
+  );
+  assert(diff.status === 0, `gh pr diff failed: ${diff.stderr || diff.stdout}`);
+  return [
+    `# Source Kind: PR`,
+    `# Source Ref: ${sourceRef}`,
+    '',
+    '## PR Metadata',
+    '```json',
+    view.stdout.trim(),
+    '```',
+    '',
+    '## PR Diff',
+    '```diff',
+    diff.stdout.trim(),
+    '```',
+    '',
+  ].join('\n');
+}
+
+function resolveJiraSource(sourceRef, jiraBaseUrl) {
+  const raw = String(sourceRef || '').trim();
+  const urlMatch = raw.match(/https?:\/\/[^/]+\/browse\/([A-Z][A-Z0-9]+-\d+)/i);
+  const issueKey = urlMatch ? urlMatch[1].toUpperCase() : raw.toUpperCase();
+  const browseUrl = urlMatch
+    ? raw
+    : `${String(jiraBaseUrl || '').replace(/\/$/, '')}/browse/${issueKey}`;
+  return {
+    issueKey,
+    browseUrl,
+  };
+}
+
+function fetchJiraBundle(sourceRef, jiraBaseUrl, jiraEmail, jiraToken) {
+  assert(jiraBaseUrl, 'Jira source kind requires --jira-base-url or JIRA_BASE_URL');
+  const { issueKey, browseUrl } = resolveJiraSource(sourceRef, jiraBaseUrl);
+  if (!(jiraEmail && jiraToken)) {
+    return [
+      `# Source Kind: Jira`,
+      `# Source Ref: ${issueKey}`,
+      `# Source URL: ${browseUrl}`,
+      '',
+      '## Jira Issue',
+      '',
+      'Jira API fetch unavailable from the current shell context.',
+      'Use the ticket URL above plus any local notes/branch context as the source of truth for the first iteration.',
+      '',
+    ].join('\n');
+  }
+  const url = `${jiraBaseUrl.replace(/\/$/, '')}/rest/api/3/issue/${issueKey}?expand=renderedFields`;
+  const res = spawnSync('curl', ['-s', '-u', `${jiraEmail}:${jiraToken}`, url], {
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  assert(res.status === 0, `curl Jira fetch failed: ${res.stderr || res.stdout}`);
+  return [
+    `# Source Kind: Jira`,
+    `# Source Ref: ${issueKey}`,
+    `# Source URL: ${browseUrl}`,
+    '',
+    '## Jira Issue',
+    '```json',
+    res.stdout.trim(),
+    '```',
+    '',
+  ].join('\n');
+}
+
+function fetchTextBundle(sourceRef, sourceText) {
+  return [
+    `# Source Kind: Text`,
+    `# Source Ref: ${sourceRef || 'text'}`,
+    '',
+    '## Input Text',
+    '```text',
+    sourceText.trim(),
+    '```',
+    '',
+  ].join('\n');
+}
+
+function fetchFileBundle(sourceRef) {
+  const filePath = path.resolve(sourceRef);
+  assert(fs.existsSync(filePath), `Source file does not exist: ${filePath}`);
+  const content = fs.readFileSync(filePath, 'utf8');
+  return [
+    `# Source Kind: File`,
+    `# Source Ref: ${filePath}`,
+    '',
+    '## File Contents',
+    '```',
+    content.trim(),
+    '```',
+    '',
+  ].join('\n');
+}
+
+function resolveTemplatePath() {
+  return TEMPLATE_PATH;
+}
+
+function main() {
+  const args = parseArgs();
+  assert(args.repoRoot, 'Missing --repo-root <path>');
+  const repoName = args.repo || inferRepoName(args.repoRoot);
+  assert(OVERLAYS[repoName], `Unsupported --repo / inferred repo: ${repoName}`);
+  assert(args.sourceKind, 'Missing --source-kind <pr|jira|text|file>');
+
+  let sourceBundle = '';
+  switch (args.sourceKind) {
+    case 'pr':
+      sourceBundle = fetchPrBundle(args.sourceRef, args.ghRepo);
+      break;
+    case 'jira':
+      sourceBundle = fetchJiraBundle(
+        args.sourceRef,
+        args.jiraBaseUrl,
+        args.jiraEmail,
+        args.jiraToken,
+      );
+      break;
+    case 'text':
+      sourceBundle = fetchTextBundle(args.sourceRef, args.sourceText);
+      break;
+    case 'file':
+      sourceBundle = fetchFileBundle(args.sourceRef);
+      break;
+    default:
+      throw new Error(`Unsupported --source-kind: ${args.sourceKind}`);
+  }
+
+  const runId =
+    args.runId ||
+    `${slugify(`${args.sourceKind}-${args.sourceRef || 'source'}`)}-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  const runDir =
+    args.outputDir || path.resolve(args.repoRoot, '.omx', 'artifacts', 'recipe-cook-runs', runId);
+  const artifactsDir = path.join(runDir, 'artifacts');
+  fs.mkdirSync(artifactsDir, { recursive: true });
+
+  const sourceBundlePath = path.join(runDir, 'SOURCE-BUNDLE.md');
+  writeFile(sourceBundlePath, sourceBundle);
+
+  const templatePath = resolveTemplatePath();
+  const templateText = fs.readFileSync(templatePath, 'utf8');
+  const taskPath = path.join(runDir, 'TASK.md');
+  const taskText = expandTemplate(templateText, {
+    WRAPPER: args.wrapper || 'recipe-cook',
+    SCENARIO_ID: runId,
+    TARGET_REPO: repoName,
+    REPO_ROOT: args.repoRoot,
+    SOURCE_KIND: args.sourceKind,
+    SOURCE_REF: args.sourceRef || args.sourceKind,
+    SOURCE_ARTIFACT_DIR: '',
+    TASK_DIR: runDir,
+    ARTIFACT_DIR: artifactsDir,
+    SOURCE_BUNDLE_FILE: sourceBundlePath,
+    VALIDATION_MODE: 'pending',
+  });
+  writeFile(taskPath, taskText);
+
+  writeJson(path.join(runDir, 'run-meta.json'), {
+    run_id: runId,
+    wrapper: args.wrapper || 'recipe-cook',
+    repo: repoName,
+    repo_root: args.repoRoot,
+    source_kind: args.sourceKind,
+    source_ref: args.sourceRef,
+    source_bundle_path: sourceBundlePath,
+    task_path: taskPath,
+    artifacts_dir: artifactsDir,
+    gh_repo: args.ghRepo || null,
+    jira_base_url: args.jiraBaseUrl || null,
+    template_path: templatePath,
+    prepared_at: new Date().toISOString(),
+  });
+
+  process.stdout.write(`${runDir}\n`);
+}
+
+if (require.main === module) {
+  main();
+}