@soleur/opencode 0.0.0-stage → 1.0.0

package/scripts/setup-ralph-loop.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+
+# Ralph Loop Setup Script
+# Creates state file for in-session Ralph loop.
+#
+# Ported from the ralph-loop plugin (Anthropic, Apache 2.0).
+# Original: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
+
+set -euo pipefail
+
+# Source shared helper for repo root resolution
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/resolve-git-root.sh" || {
+  echo "Error: Not inside a git repository." >&2
+  exit 1
+}
+PROJECT_ROOT="$GIT_COMMON_ROOT"
+
+# Session identifier: PPID by default, overridable via RALPH_LOOP_PID for testing
+_RALPH_LOOP_PID="${RALPH_LOOP_PID:-$PPID}"
+
+# Parse arguments
+PROMPT_PARTS=()
+MAX_ITERATIONS=25
+COMPLETION_PROMISE="null"
+STUCK_THRESHOLD=3
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help)
+      cat << 'HELP_EOF'
+Ralph Loop - Interactive self-referential development loop
+
+USAGE:
+  /soleur:ralph-loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: 25, 0 for unlimited)
+  --completion-promise '<text>'  Promise phrase (USE QUOTES for multi-word)
+  --stuck-threshold <n>          Consecutive empty responses before auto-stop (default: 3, 0 to disable)
+  -h, --help                     Show this help message
+
+DESCRIPTION:
+  Starts a Ralph Loop in your CURRENT session. The stop hook prevents
+  exit and feeds your output back as input until completion or iteration limit.
+
+  To signal completion, output: <promise>YOUR_PHRASE</promise>
+
+  Stuck detection: The loop auto-terminates when responses are idle:
+  - Short responses (< 150 chars): counted as minimal
+  - Idle patterns (< 200 chars): responses matching "all done", "nothing
+    left to do", etc. are counted as semantically idle
+  - Repetition: 3 consecutive identical responses trigger termination
+  - Similarity: 3 consecutive responses sharing >=80% words trigger
+    termination (catches minor variations of the same response)
+  Set --stuck-threshold 0 to disable length/idle detection (repetition
+  and similarity detection remain active).
+
+EXAMPLES:
+  /soleur:ralph-loop Build a todo API --completion-promise 'DONE' --max-iterations 20
+  /soleur:ralph-loop --max-iterations 10 Fix the auth bug
+  /soleur:ralph-loop Refactor cache layer  (default: 25 iterations)
+  /soleur:ralph-loop --completion-promise 'TASK COMPLETE' Create a REST API
+
+STOPPING:
+  By reaching --max-iterations, detecting --completion-promise,
+  stuck detection (N consecutive empty/idle responses), or repetition
+  detection (3 identical responses). Or manually remove the state file:
+  rm .claude/ralph-loop.*.local.md
+
+MONITORING:
+  # View current iteration:
+  grep '^iteration:' .claude/ralph-loop.*.local.md
+
+  # View full state:
+  head -10 .claude/ralph-loop.*.local.md
+HELP_EOF
+      exit 0
+      ;;
+    --max-iterations)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --max-iterations requires a number argument" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "Error: --max-iterations must be a positive integer or 0, got: $2" >&2
+        exit 1
+      fi
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --completion-promise requires a text argument" >&2
+        exit 1
+      fi
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    --stuck-threshold)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --stuck-threshold requires a number argument" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "Error: --stuck-threshold must be a non-negative integer, got: $2" >&2
+        exit 1
+      fi
+      STUCK_THRESHOLD="$2"
+      shift 2
+      ;;
+    *)
+      PROMPT_PARTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Join all prompt parts with spaces
+PROMPT="${PROMPT_PARTS[*]}"
+
+# Validate prompt is non-empty
+if [[ -z "$PROMPT" ]]; then
+  echo "Error: No prompt provided" >&2
+  echo "" >&2
+  echo "Examples:" >&2
+  echo "  /soleur:ralph-loop Build a REST API for todos" >&2
+  echo "  /soleur:ralph-loop Fix the auth bug --max-iterations 20" >&2
+  echo "  /soleur:ralph-loop --completion-promise 'DONE' Refactor code" >&2
+  exit 1
+fi
+
+# Create state file for stop hook (markdown with YAML frontmatter)
+mkdir -p "${PROJECT_ROOT}/.claude"
+
+# Remove legacy state files (pre-PID naming) that collide across sessions
+LEGACY_FILE="${PROJECT_ROOT}/.claude/ralph-loop.local.md"
+if [[ -f "$LEGACY_FILE" ]]; then
+  echo "Removing legacy ralph-loop state file (no session isolation)." >&2
+  rm -f "$LEGACY_FILE"
+fi
+
+# Check for other sessions' active loops
+for existing in "${PROJECT_ROOT}/.claude"/ralph-loop.*.local.md; do
+  [[ -f "$existing" ]] || continue
+  EXISTING_PID=$(basename "$existing" | sed 's/^ralph-loop\.\([0-9]*\)\.local\.md$/\1/')
+  if [[ "$EXISTING_PID" =~ ^[0-9]+$ ]] && [[ "$EXISTING_PID" != "$_RALPH_LOOP_PID" ]]; then
+    if kill -0 "$EXISTING_PID" 2>/dev/null; then
+      echo "Warning: Another session (PID $EXISTING_PID) has an active ralph loop." >&2
+      echo "  File: $existing" >&2
+      echo "  Remove it to start a new loop: rm $existing" >&2
+      exit 1
+    else
+      echo "Removing orphaned state file from dead session (PID $EXISTING_PID)." >&2
+      rm -f "$existing"
+    fi
+  fi
+done
+
+# Quote completion promise for YAML if it contains special chars or is not null
+if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
+else
+  COMPLETION_PROMISE_YAML="null"
+fi
+
+cat > "${PROJECT_ROOT}/.claude/ralph-loop.${_RALPH_LOOP_PID}.local.md" <<EOF
+---
+active: true
+iteration: 1
+max_iterations: $MAX_ITERATIONS
+completion_promise: $COMPLETION_PROMISE_YAML
+stuck_count: 0
+stuck_threshold: $STUCK_THRESHOLD
+last_response_hash:
+repeat_count: 0
+similarity_count: 0
+last_response_words:
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+$PROMPT
+EOF
+
+# Output setup message
+cat <<EOF
+Ralph loop activated in this session!
+
+Iteration: 1
+Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
+Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "${COMPLETION_PROMISE//\"/} (ONLY output when TRUE - do not lie!)"; else echo "none (runs forever)"; fi)
+
+The stop hook is now active. When you try to exit, the SAME PROMPT will be
+fed back to you. You'll see your previous work in files, creating a
+self-referential loop where you iteratively improve on the same task.
+
+To monitor: head -10 .claude/ralph-loop.${_RALPH_LOOP_PID}.local.md
+To cancel: rm .claude/ralph-loop.${_RALPH_LOOP_PID}.local.md
+
+NOTE: Default cap is 25 iterations. Pass --max-iterations 0 to run
+without a cap (not recommended -- stale state files trap future sessions).
+EOF
+
+# Output the initial prompt
+if [[ -n "$PROMPT" ]]; then
+  echo ""
+  echo "$PROMPT"
+fi
+
+# Display completion promise requirements if set
+if [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  echo ""
+  echo "==================================================================="
+  echo "CRITICAL - Ralph Loop Completion Promise"
+  echo "==================================================================="
+  echo ""
+  echo "To complete this loop, output this EXACT text:"
+  echo "  <promise>$COMPLETION_PROMISE</promise>"
+  echo ""
+  echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
+  echo "  - Use <promise> XML tags EXACTLY as shown above"
+  echo "  - The statement MUST be completely and unequivocally TRUE"
+  echo "  - Do NOT output false statements to exit the loop"
+  echo "  - Do NOT lie even if you think you should exit"
+  echo ""
+  echo "IMPORTANT - Do not circumvent the loop:"
+  echo "  Even if you believe you're stuck, the task is impossible,"
+  echo "  or you've been running too long - you MUST NOT output a"
+  echo "  false promise statement. The loop is designed to continue"
+  echo "  until the promise is GENUINELY TRUE. Trust the process."
+  echo ""
+  echo "  If the loop should stop, the promise statement will become"
+  echo "  true naturally. Do not force it by lying."
+  echo "==================================================================="
+fi

package/scripts/sync-cursor-name-map.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env bun
+/**
+ * Generate the Cursor CLI skill and agent stubs from the canonical tree.
+ *
+ *   bun plugins/soleur/scripts/sync-cursor-name-map.ts
+ *   bun plugins/soleur/scripts/sync-cursor-name-map.ts --check
+ *
+ * `--check` reprints nothing but `cursor-name-map ok` when the committed tree
+ * matches a fresh walk. A drift, a missing stub, an extra stub, or two sources
+ * that share one output name exits non-zero and names the path. There is no
+ * second checker.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+
+const HEADER =
+  "On Cursor, do not call the Skill tool, the Task tool, `run_subagent`, or AwaitShell, and do not expand `CLAUDE_PLUGIN_ROOT`. If the canonical file tells you to call those tools, stop. Slice 1 does not run hooks, does not classify the session as cursor, and does not block a commit.";
+
+const HELP_DEVIN_SENTENCE = "Detect the active harness as Devin";
+const BARE_SKILLS = new Set(["go", "sync"]);
+const MODEL_DISABLED = new Set(["plan", "help", "review"]);
+const STEM = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function cursorSkillName(folder: string): string {
+  if (BARE_SKILLS.has(folder)) return folder;
+  return `soleur-${folder}`;
+}
+
+export function cursorSkillSlash(folder: string): string {
+  return `/${cursorSkillName(folder)}`;
+}
+
+export function cursorAgentName(relUnderAgents: string): string {
+  const stem = relUnderAgents.replace(/\.md$/i, "").replaceAll("/", "-");
+  return `soleur-${stem}`;
+}
+
+export function cursorAgentSlash(relUnderAgents: string): string {
+  return `/${cursorAgentName(relUnderAgents)}`;
+}
+
+/** YAML double-quoted scalar. A colon in `soleur:finance:cfo` stays inside the quotes. */
+export function yamlQuote(value: string): string {
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+    .replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+  return `"${escaped}"`;
+}
+
+type BuiltMap = {
+  files: Map<string, string>;
+  problems: string[];
+};
+
+function skillTarget(folder: string): string {
+  if (folder === "go" || folder === "sync" || folder === "help") return `commands/${folder}.md`;
+  return `skills/${folder}/SKILL.md`;
+}
+
+function readFrontmatter(
+  abs: string,
+  source: string,
+  problems: string[],
+): { description: string | null; disableModel: boolean } {
+  const raw = readFileSync(abs, "utf8");
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { description: null, disableModel: false };
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(match[1]);
+  } catch (err) {
+    problems.push(`frontmatter parse failed: ${source}: ${err instanceof Error ? err.message : String(err)}`);
+    return { description: null, disableModel: false };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { description: null, disableModel: false };
+  }
+  const record = parsed as Record<string, unknown>;
+  const disableModel = record["disable-model-invocation"] === true;
+  const value = record.description;
+  if (value === undefined || value === null || value === "") return { description: null, disableModel };
+  if (typeof value !== "string") {
+    problems.push(`description is not a string: ${source}`);
+    return { description: null, disableModel: false };
+  }
+  return { description: value, disableModel };
+}
+
+function renderStub(name: string, description: string | null, disable: boolean, target: string): string {
+  const lines = ["---", `name: ${name}`];
+  if (description !== null) lines.push(`description: ${yamlQuote(description)}`);
+  if (disable) lines.push("disable-model-invocation: true");
+  lines.push("---", "", HEADER, "", `Read \`${target}\`, relative to the plugin root.`, "");
+  return lines.join("\n");
+}
+
+function claim(owners: Map<string, string[]>, key: string, source: string): void {
+  const list = owners.get(key) ?? [];
+  list.push(source);
+  owners.set(key, list);
+}
+
+function walkAgents(dir: string, prefix: string, out: string[]): void {
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const ent of entries) {
+    const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) walkAgents(join(dir, ent.name), rel, out);
+    else if (ent.isFile() && ent.name.endsWith(".md")) out.push(rel);
+  }
+}
+
+export function buildCursorNameMap(pluginRoot: string): BuiltMap {
+  const files = new Map<string, string>();
+  const problems: string[] = [];
+  const nameOwners = new Map<string, string[]>();
+  const pathOwners = new Map<string, string[]>();
+
+  const skillsDir = join(pluginRoot, "skills");
+  if (!existsSync(skillsDir)) {
+    problems.push("MISSING: skills");
+  } else {
+    const folders = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((ent) => ent.isDirectory())
+      .map((ent) => ent.name)
+      .sort();
+    for (const folder of folders) {
+      const source = `skills/${folder}/SKILL.md`;
+      const abs = join(skillsDir, folder, "SKILL.md");
+      if (!existsSync(abs)) continue;
+      if (!STEM.test(folder)) {
+        problems.push(`skill folder is not a cursor name stem: ${source}`);
+        continue;
+      }
+      const name = cursorSkillName(folder);
+      const rel = `cursor/skills/${name}/SKILL.md`;
+      const meta = readFrontmatter(abs, source, problems);
+      const body = renderStub(
+        name,
+        meta.description,
+        MODEL_DISABLED.has(folder) || meta.disableModel,
+        skillTarget(folder),
+      );
+      if (folder === "help" && body.includes(HELP_DEVIN_SENTENCE)) {
+        problems.push(`help stub contains the Devin harness sentence: ${rel}`);
+      }
+      claim(nameOwners, name, source);
+      claim(pathOwners, rel, source);
+      if (!files.has(rel)) files.set(rel, body);
+    }
+  }
+
+  const agentsDir = join(pluginRoot, "agents");
+  if (!existsSync(agentsDir)) {
+    problems.push("MISSING: agents");
+  } else {
+    const rels: string[] = [];
+    walkAgents(agentsDir, "", rels);
+    for (const relUnder of rels) {
+      const source = `agents/${relUnder}`;
+      const stem = relUnder.replace(/\.md$/i, "").replaceAll("/", "-");
+      if (!STEM.test(stem)) {
+        problems.push(`agent path is not a cursor name stem: ${source}`);
+        continue;
+      }
+      const name = cursorAgentName(relUnder);
+      const rel = `cursor/agents/${name}.md`;
+      const meta = readFrontmatter(join(agentsDir, relUnder), source, problems);
+      const body = renderStub(name, meta.description, meta.disableModel, source);
+      const afterFrontmatter = body.split("\n---\n").slice(1).join("\n---\n");
+      if (afterFrontmatter.includes("spawn_subagent") || afterFrontmatter.includes("GROK_STUB_SPAWN_RULE")) {
+        problems.push(`agent stub names a Grok spawn rule: ${rel}`);
+      }
+      claim(nameOwners, name, source);
+      claim(pathOwners, rel, source);
+      if (!files.has(rel)) files.set(rel, body);
+    }
+  }
+
+  for (const [rel, sources] of pathOwners) {
+    if (sources.length > 1) problems.push(`${rel} maps from ${sources.join(" and ")}`);
+  }
+  for (const [name, sources] of nameOwners) {
+    if (sources.length < 2) continue;
+    const outputPaths = new Set<string>();
+    for (const source of sources) {
+      for (const [rel, owners] of pathOwners) {
+        if (owners.includes(source)) outputPaths.add(rel);
+      }
+    }
+    // One file claimed twice is already reported above. This row is the case
+    // where a skill and an agent render the same slash name as two files.
+    if (outputPaths.size > 1) problems.push(`${name} maps from ${sources.join(" and ")}`);
+  }
+
+  return { files, problems };
+}
+
+function listGenerated(pluginRoot: string): string[] {
+  const out: string[] = [];
+  const skillsRoot = join(pluginRoot, "cursor/skills");
+  if (existsSync(skillsRoot)) {
+    for (const ent of readdirSync(skillsRoot, { withFileTypes: true })) {
+      const relDir = `cursor/skills/${ent.name}`;
+      if (!ent.isDirectory()) {
+        out.push(relDir);
+        continue;
+      }
+      for (const child of readdirSync(join(skillsRoot, ent.name))) out.push(`${relDir}/${child}`);
+    }
+  }
+  const agentsRoot = join(pluginRoot, "cursor/agents");
+  if (existsSync(agentsRoot)) {
+    for (const ent of readdirSync(agentsRoot, { withFileTypes: true })) out.push(`cursor/agents/${ent.name}`);
+  }
+  return out;
+}
+
+function diskProblems(pluginRoot: string, files: Map<string, string>): string[] {
+  const problems: string[] = [];
+  for (const [rel, body] of files) {
+    const abs = join(pluginRoot, rel);
+    if (!existsSync(abs)) {
+      problems.push(`MISSING: ${rel}`);
+      continue;
+    }
+    if (readFileSync(abs, "utf8") !== body) problems.push(`DRIFT: ${rel}`);
+  }
+  for (const rel of listGenerated(pluginRoot)) {
+    if (!files.has(rel)) problems.push(`EXTRA: ${rel}`);
+  }
+  const helpAbs = join(pluginRoot, "cursor/skills/soleur-help/SKILL.md");
+  if (existsSync(helpAbs) && readFileSync(helpAbs, "utf8").includes(HELP_DEVIN_SENTENCE)) {
+    problems.push("help stub contains the Devin harness sentence: cursor/skills/soleur-help/SKILL.md");
+  }
+  return problems;
+}
+
+export function cursorNameMapProblems(pluginRoot: string): string[] {
+  const built = buildCursorNameMap(pluginRoot);
+  return [...built.problems, ...diskProblems(pluginRoot, built.files)];
+}
+
+export function writeCursorNameMap(pluginRoot: string): string[] {
+  const built = buildCursorNameMap(pluginRoot);
+  if (built.problems.length > 0) return built.problems;
+  const extras = listGenerated(pluginRoot).filter((rel) => !built.files.has(rel));
+  const dirExtras = extras.filter((rel) => {
+    try {
+      return statSync(join(pluginRoot, rel)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+  if (dirExtras.length > 0) return dirExtras.map((rel) => `EXTRA: ${rel}`);
+  for (const [rel, body] of built.files) {
+    const abs = join(pluginRoot, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+  }
+  for (const rel of extras) {
+    const abs = join(pluginRoot, rel);
+    rmSync(abs, { force: true });
+    const parent = dirname(abs);
+    if (parent.includes("/cursor/skills/") && existsSync(parent) && readdirSync(parent).length === 0) {
+      rmSync(parent, { recursive: true });
+    }
+  }
+  return [];
+}
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  let check = false;
+  let rootArg: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+    if (arg === "--root") {
+      rootArg = argv[i + 1];
+      if (!rootArg || rootArg.startsWith("--")) {
+        console.error("missing --root path");
+        process.exit(1);
+      }
+      i++;
+      continue;
+    }
+    console.error(`unknown argument: ${arg}`);
+    process.exit(1);
+  }
+
+  const pluginRoot = rootArg ? resolve(rootArg) : resolve(import.meta.dir, "..");
+  if (!check) {
+    const wrote = writeCursorNameMap(pluginRoot);
+    if (wrote.length > 0) {
+      for (const problem of wrote) console.error(problem);
+      process.exit(1);
+    }
+  }
+  const problems = cursorNameMapProblems(pluginRoot);
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(problem);
+    process.exit(1);
+  }
+  console.log("cursor-name-map ok");
+}
+
+if (import.meta.main) main();