@brainervirus/workit-core 0.4.0

package/src/core/ports/youtrack-parse-duration.ts

@@ -0,0 +1,14 @@
+// CLI port of scripts/youtrack/parse-duration.sh.
+import { youTrackParseDuration } from "../youtrack";
+
+const text = process.argv.slice(2).join(" ");
+if (!text) {
+  console.error("ERROR: duration text required");
+  process.exit(1);
+}
+const out = youTrackParseDuration(text);
+if ("error" in out) {
+  console.error("ERROR: " + out.error);
+  process.exit(1);
+}
+console.log(JSON.stringify(out.data));

package/src/core/ports/youtrack-token-create-url.ts

@@ -0,0 +1,4 @@
+// CLI port of scripts/youtrack/token-create-url.sh.
+import { youTrackTokenCreateUrl } from "../youtrack";
+
+console.log(JSON.stringify(youTrackTokenCreateUrl().data, null, 2));

package/src/core/ports/youtrack-verify-token.ts

@@ -0,0 +1,12 @@
+// CLI port of scripts/youtrack/verify-token.sh.
+import { youTrackVerifyToken } from "../youtrack";
+
+const out = youTrackVerifyToken();
+if ("error" in out) {
+  const payload: Record<string, any> = { ok: false, error: out.error };
+  if (out.http_status !== undefined) payload.http_status = out.http_status;
+  if (out.path !== undefined) payload.path = out.path;
+  console.log(JSON.stringify(payload, null, 2));
+  process.exit(1);
+}
+console.log(JSON.stringify(out.data, null, 2));

package/src/core/ports/youtrack-work-date-ms.ts

@@ -0,0 +1,10 @@
+// CLI port of scripts/youtrack/work-date-ms.sh.
+import { youTrackWorkDateMs } from "../youtrack";
+
+const raw = process.argv[2] ?? "auto";
+const out = youTrackWorkDateMs(raw);
+if ("error" in out) {
+  console.error("ERROR: " + out.error);
+  process.exit(1);
+}
+console.log(JSON.stringify(out.data));

package/src/core/pr-create.ts

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { vcsConfig } from "./vcs-config";
+
+// Port of scripts/pr-create.sh — build MR/PR body issue linking + create via glab/gh.
+
+function parseGhRepo(remote: string): string | null {
+  remote = (remote || "").trim().replace(/\/+$/, "");
+  if (!remote) return null;
+  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
+  if (remote.includes(":")) remote = remote.split(":").pop() ?? ""; // drop git@host part (scp-style URL)
+  const parts = remote.split("/").filter(Boolean);
+  return parts.length >= 2 ? parts.slice(-2).join("/") : null;
+}
+
+function parseGhIssue(value: string): string {
+  const m = /issues\/(\d+)/.exec(value);
+  return m ? m[1] : String(value).trim().replace(/^#/, "");
+}
+
+function buildBody(
+  body: string,
+  branch: string,
+  linkIssues: boolean,
+  baseUrl: string,
+  ytIssue: string,
+  ghLinkOnPr: boolean,
+  ghIssue: string,
+  ghRelation: string,
+  ghRepo: string | null,
+): string {
+  let line: string | null = null;
+  if (linkIssues) {
+    let issue = ytIssue;
+    if (!issue && branch) {
+      // anchored prefix + \b boundary, 3+ digits so version-like tokens (POSTGRES-16, HTTP-3) never link
+      const m = /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch);
+      if (m) issue = m[1];
+    }
+    if (issue && baseUrl) line = `Related to: ${baseUrl.replace(/\/+$/, "")}/issue/${issue}`;
+  } else if (ghLinkOnPr) {
+    let issue = parseGhIssue(ghIssue);
+    if (!issue && branch) {
+      // pure-number issue id (feature/42-title -> 42); digits must be followed by a dash or end-of-string
+      // so version tokens (release/1.2.3, backport/8.0.1, lodash-4.17.21, 2024.1) never link
+      // ponytail: known date-style false positive (feature/2024-01-fix -> Closes #2024); accepted — bare 42-title support is deliberate
+      const m = /(?:^|\/|-)(\d+)(?:-|$)/.exec(branch);
+      if (m) issue = m[1];
+    }
+    if (issue) {
+      if (ghRelation === "related") {
+        line = `Related to #${issue}`;
+        if (ghRepo) line += ` — https://github.com/${ghRepo}/issues/${issue}`;
+      } else {
+        line = `Closes #${issue}`;
+      }
+    }
+  }
+  if (line === null) return body;
+  return body ? `${body}\n\n${line}` : line;
+}
+
+const truthy = (v: string | undefined): boolean => ["1", "true", "yes"].includes(String(v ?? "").toLowerCase());
+
+// Port of python's shutil.which — scan PATH in-process (no `which` binary needed).
+function whichOnPath(tool: string): string | null {
+  for (const dir of (process.env.PATH ?? "").split(":")) {
+    if (!dir) continue;
+    const candidate = path.join(dir, tool);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch { /* keep scanning */ }
+  }
+  return null;
+}
+
+function repoRoot(cwd: string): string {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+  return result.status === 0 ? (result.stdout ?? "").trim() : cwd;
+}
+
+/** Port of pr-create.sh --build-body — pure body builder, no network. */
+export function prBuildBody(env: NodeJS.ProcessEnv, cwd?: string): string {
+  const ghLinkOnPr = truthy(env.GH_LINK_ON_PR);
+  let ghRepo = env.GH_REPO || null;
+  if (!ghRepo && ghLinkOnPr) {
+    const result = spawnSync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" });
+    if (result.status === 0) ghRepo = parseGhRepo(result.stdout ?? "");
+  }
+  return buildBody(
+    env.BODY ?? "",
+    env.BRANCH ?? "",
+    truthy(env.LINK_ISSUES),
+    env.YT_BASE_URL ?? "",
+    env.WORKFLOW_YT_ISSUE ?? "",
+    ghLinkOnPr,
+    env.WORKFLOW_GH_ISSUE ?? "",
+    env.WORKFLOW_GH_ISSUE_RELATION ?? "closes",
+    ghRepo,
+  );
+}
+
+/** Port of scripts/pr-create.sh create mode — glab/gh MR/PR creation. */
+export function prCreate(env: NodeJS.ProcessEnv, cwd: string): Record<string, any> {
+  const root = process.env.WORKFLOW_WORKSPACE_ROOT ?? repoRoot(cwd);
+  const cfg = vcsConfig("load", root);
+  if (!cfg.ok) return { error: cfg.error ?? "vcs config missing" };
+  if (!cfg.tokenReady) return { error: "VCS token not ready — run /wk-init and edit token file locally" };
+
+  const provider = cfg.provider as string;
+  if (provider !== "gitlab" && provider !== "github") return { error: `unsupported provider: ${provider}` };
+  const cli = provider === "gitlab" ? "glab" : "gh";
+  const installUrl = provider === "gitlab" ? "https://gitlab.com/gitlab-org/cli" : "https://cli.github.com";
+  if (whichOnPath(cli) === null) {
+    return {
+      ok: false,
+      cli_missing: true,
+      error: `workflow CLI missing: ${cli} (required for ${provider}). Install: ${installUrl}`,
+      install_url: installUrl,
+    };
+  }
+
+  const pr = (cfg.pr ?? {}) as Record<string, any>;
+  const token = fs.readFileSync(cfg.tokenPath as string, "utf8").trim();
+  const title = String(env.WF_PR_TITLE ?? "");
+  const body = env.WF_PR_BODY ?? "";
+  const draft = String(env.WF_PR_DRAFT ?? "false").toLowerCase() === "true";
+  const target = env.WF_PR_TARGET || String(cfg.defaultTargetBranch ?? "develop");
+
+  const br = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, encoding: "utf8" });
+  const branch = br.status === 0 ? (br.stdout ?? "").trim() : "";
+
+  let baseUrl = cfg.youtrack_base_url as string | undefined;
+  if (!baseUrl) {
+    const ytCfg = process.env.WORKFLOW_YOUTRACK_CONFIG ?? path.join(path.dirname(String(cfg.configPath)), "youtrack.json");
+    try {
+      const yt = JSON.parse(fs.readFileSync(ytCfg, "utf8")) as Record<string, any>;
+      if (yt && typeof yt === "object") baseUrl = yt.baseUrl;
+    } catch { /* optional */ }
+  }
+  const ghLinkOnPr = cfg.issues_provider === "github" && cfg.link_on_pr === true;
+  let ghRepo: string | null = null;
+  if (ghLinkOnPr) {
+    const rr = spawnSync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8" });
+    if (rr.status === 0) ghRepo = parseGhRepo(rr.stdout ?? "");
+  }
+  const finalBody = buildBody(
+    body, branch, cfg.link_issues === true, baseUrl ?? "", env.WORKFLOW_YT_ISSUE ?? "",
+    ghLinkOnPr, env.WORKFLOW_GH_ISSUE ?? "", env.WORKFLOW_GH_ISSUE_RELATION ?? "closes", ghRepo,
+  );
+
+  const squash = pr.squashOnMerge !== false;
+  const removeBranch = pr.removeSourceBranch !== false;
+  const push = pr.pushBranch !== false;
+  const skipConfirm = pr.confirmSkip !== false;
+
+  let cmd: string[];
+  let cmdEnv: NodeJS.ProcessEnv;
+  if (provider === "gitlab") {
+    // glab non-interactive mode requires BOTH title and description flags (issue #652).
+    cmd = ["glab", "mr", "create", "-t", title, "-d", finalBody || "", "-b", target];
+    cmd.push(squash ? "--squash-before-merge" : "--squash-before-merge=false");
+    cmd.push(removeBranch ? "--remove-source-branch" : "--remove-source-branch=false");
+    if (draft) cmd.push("--draft");
+    if (push) cmd.push("--push");
+    if (skipConfirm) cmd.push("--yes");
+    cmdEnv = { ...process.env, GITLAB_TOKEN: token };
+  } else {
+    cmd = ["gh", "pr", "create", "--title", title, "--base", target];
+    if (finalBody) cmd.push("--body", finalBody);
+    if (draft) cmd.push("--draft");
+    cmdEnv = { ...process.env, GH_TOKEN: token };
+  }
+
+  const result = spawnSync(cmd[0], cmd.slice(1), { cwd: root, encoding: "utf8", env: cmdEnv });
+  if (result.status !== 0) {
+    const err = (result.stderr ?? result.stdout ?? "").trim();
+    let hint: Record<string, any> | null = null;
+    if (provider === "gitlab" && (err.includes("409") || err.toLowerCase().includes("already exists"))) {
+      const list = spawnSync("glab", ["mr", "list", `--source-branch=${branch}`, "--output=json"],
+        { cwd: root, encoding: "utf8", env: cmdEnv });
+      if (list.status === 0 && (list.stdout ?? "").trim()) {
+        try {
+          const mrs = JSON.parse(list.stdout ?? "") as Array<Record<string, any>>;
+          if (mrs.length) {
+            hint = {
+              reason: "merge_request_already_exists",
+              existing: mrs[0],
+              next_step: "Use glab mr update or close the open MR before creating again",
+            };
+          }
+        } catch { /* no hint */ }
+      }
+    }
+    const payload: Record<string, any> = { error: "create failed", provider, stderr: err.slice(0, 800) };
+    if (hint) payload.hint = hint;
+    return payload;
+  }
+
+  return {
+    ok: true,
+    provider,
+    targetBranch: target,
+    squashOnMerge: squash,
+    removeSourceBranch: removeBranch,
+    output: (result.stdout ?? "").trim(),
+  };
+}
+
+export { buildBody, parseGhRepo, parseGhIssue };

package/src/core/present.ts

@@ -0,0 +1,100 @@
+// Ports of scripts/present/ascii-wireframe.sh + flow-diagram.sh — pure TS renderers.
+
+function boxLine(text: string, width: number): string {
+  const inner = width - 4;
+  let t = text;
+  if (t.length > inner) t = t.slice(0, inner - 1) + "…";
+  return "│ " + t.padEnd(inner) + " │";
+}
+
+export function renderAsciiWireframe(spec: unknown): string {
+  const parsed = typeof spec === "string" ? JSON.parse(spec) : spec;
+  const title = String((parsed as any).title ?? "UI");
+  const width = Number((parsed as any).width ?? 72);
+  const rows = Array.isArray((parsed as any).rows) ? (parsed as any).rows : [];
+
+  const top = "┌" + "─".repeat(Math.max(0, width - 2)) + "┐";
+  const bot = "└" + "─".repeat(Math.max(0, width - 2)) + "┘";
+  const lines = [top, boxLine(title, width)];
+  lines.push("├" + "─".repeat(Math.max(0, width - 2)) + "┤");
+
+  for (const row of rows) {
+    const kind = row?.type ?? "text";
+    if (kind === "separator") {
+      lines.push("├" + "─".repeat(Math.max(0, width - 2)) + "┤");
+      continue;
+    }
+    if (kind === "header") {
+      lines.push(boxLine(String(row?.label ?? ""), width));
+      continue;
+    }
+    if (kind === "button") {
+      const label = "[ " + String(row?.label ?? "Button") + " ]";
+      lines.push(boxLine(label.padStart(Math.max(0, (width - 4 + label.length) / 2)).padEnd(width - 4), width));
+      continue;
+    }
+    if (kind === "field") {
+      const label = String(row?.label ?? "Field");
+      const value = String(row?.value ?? "_______________");
+      lines.push(boxLine(`${label}: ${value}`, width));
+      continue;
+    }
+    if (kind === "columns") {
+      const cols = Array.isArray(row?.columns) ? row.columns : [];
+      const colW = Math.floor((width - 4 - cols.length + 1) / Math.max(cols.length, 1));
+      const parts = cols.map((c: any) => String(c?.label ?? "").slice(0, Math.max(0, colW - 1)).padEnd(Math.max(0, colW)));
+      lines.push(boxLine(parts.join(" | ").trim(), width));
+      continue;
+    }
+    lines.push(boxLine(String(row?.label ?? String(row)), width));
+  }
+
+  lines.push(bot);
+  return lines.join("\n");
+}
+
+export function renderFlowDiagram(spec: unknown): string {
+  const parsed = typeof spec === "string" ? JSON.parse(spec) : spec;
+  const direction = String((parsed as any).direction ?? "TD");
+  const nodes = Array.isArray((parsed as any).nodes) ? (parsed as any).nodes : [];
+  const edges = Array.isArray((parsed as any).edges) ? (parsed as any).edges : [];
+  const title = (parsed as any).title;
+
+  const lines = ["flowchart " + direction];
+  if (title) lines.push("  %% " + String(title));
+
+  for (const n of nodes) {
+    const nid = String(n?.id ?? "");
+    const shape = String(n?.shape ?? "box");
+    const label = String(n?.label ?? nid).replaceAll('"', "'");
+    if (shape === "diamond") lines.push(`  ${nid}{"${label}"}`);
+    else if (shape === "start") lines.push(`  ${nid}(["${label}"])`);
+    else lines.push(`  ${nid}["${label}"]`);
+  }
+
+  for (const e of edges) {
+    const src = String(e?.from ?? "");
+    const dst = String(e?.to ?? "");
+    const lbl = e?.label;
+    if (lbl) lines.push(`  ${src} -->|${lbl}| ${dst}`);
+    else lines.push(`  ${src} --> ${dst}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function asciiWireframe(spec: unknown): Record<string, any> {
+  try {
+    return { data: { ascii: renderAsciiWireframe(spec), format: "ascii-wireframe" } };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "ascii-wireframe render failed" };
+  }
+}
+
+export function flowDiagram(spec: unknown): Record<string, any> {
+  try {
+    return { data: { mermaid: renderFlowDiagram(spec), format: "mermaid" } };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "flow-diagram render failed" };
+  }
+}

package/src/core/reminder.ts

@@ -0,0 +1,82 @@
+export const REMINDER_TEXT = `<workflow-contract-reminder>
+- Bounded user choices → call the native \`question\` tool (never A/B/C or 1/2/3 lists in prose).
+- After a plan is approved → native \`question\` menu with exactly: Subagent-driven, Inline, Handoff (new session only), Review spec first, Review plan first.
+- Tools with \`confirmed\` → call them; never fabricate their result.
+- Before the first \`workflow_spec_approve\`/\`workflow_plan_approve\` (self-review) run the superpowers writing-plans Self-Review checklist: spec coverage (every spec requirement maps to a task), placeholder scan, type consistency; fix findings inline.
+- Delivering docs → clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` + 3-5 bullet summary.
+</workflow-contract-reminder>`;
+
+export const DETECTION_TEXT = `<workflow-detection>
+Your previous message presented choices as a numbered/bulleted list in prose.
+That is a bounded user choice — use the native \`question\` tool instead (re-ask with \`question\` if still relevant).
+</workflow-detection>`;
+
+export const DOC_DELIVERY_TEXT = `<workflow-doc-delivery>
+You referenced a doc with a backtick-only path. Deliver docs with a clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` and a 3-5 bullet summary of the content.
+</workflow-doc-delivery>`;
+
+export const SDD_REMINDER_TEXT = `<workflow-sdd-reminder>
+An approved plan is subagent-driven — execute it via \`wk-implement\` / \`task\` delegation. Never implement the approved plan inline in the main session.
+</workflow-sdd-reminder>`;
+
+export const DOC_RENDER_TEXT = `<workflow-doc-render>
+When delivering a spec or plan, by default render the full markdown content of the doc in chat (headings, tables, mermaid fences preserved) — NOT a backtick-wrapped raw block.
+If the doc exceeds the render threshold (more than 150 lines, over 8KB, or more than 3 mermaid diagrams), deliver only the clickable link \`[spec.md](docs/<slug>/spec.md)\` + a 3-5 bullet summary.
+On an explicit raw request ("raw", "para copiar", "sin render"), show the full fenced block instead.
+Platform note: always use the standard \`\`\`mermaid fence — Cursor CLI renders it as an ASCII diagram, editors/GitHub render it natively; OpenCode TUI shows it as code text (renderer limitation, not a defect). Inline markdown links are not clickable in the OpenCode TUI.
+</workflow-doc-render>`;
+
+export const ISSUE_RAIL_TEXT = `<workflow-issue-rail>
+A clickable \`question\` option whose label is an instruction (e.g. "Type the issue URL/ID") returns the label literal when clicked, not free text — ask for free text in plain prose with the custom answer field enabled instead.
+</workflow-issue-rail>`;
+
+export const CONFIG_GUARD_TEXT = `<workflow-config-guard>
+A tool failed with a config-gap error (\`workflow config missing\`). Never configure without asking — ask with the native \`question\` tool, exactly three options: (1) configure only what's missing (guided, via the /wk-init skill flow for those actions), (2) run the full wizard (\`npx workit init\`), (3) skip — report the final error naming the missing items and how to configure them.
+</workflow-config-guard>`;
+
+export const VERIFICATION_TEXT = `<workflow-verification-rail>
+Skill: verification-before-completion. NO completion claims without fresh verification evidence — run the check command (e.g. \`bun run check\` / \`workflow_verify\`) and show its output before claiming done/fixed/passing. If you haven't run the verification command in this message, you cannot claim it passes.
+</workflow-verification-rail>`;
+
+export const TDD_TEXT = `<workflow-tdd-rail>
+Skill: test-driven-development. NO production code without a failing test first — write the test, watch it fail, then write the minimal code to pass.
+</workflow-tdd-rail>`;
+
+export const BRAINSTORM_TEXT = `<workflow-brainstorm-rail>
+Skill: brainstorming. NO implementation until a design is presented and approved — explore intent, ask clarifying questions one at a time, present the design, and get user approval before writing any code.
+</workflow-brainstorm-rail>`;
+
+export const DEBUG_TEXT = `<workflow-debug-rail>
+Skill: systematic-debugging. NO fixes without root cause investigation first — read the error, reproduce consistently, find the root cause, then fix. Symptom fixes are failure.
+</workflow-debug-rail>`;
+
+export const REVIEW_RECEPTION_TEXT = `<workflow-review-reception-rail>
+Skill: receiving-code-review. Verify before implementing — evaluate review feedback against codebase reality (read, restate, verify) before accepting or acting on it.
+</workflow-review-reception-rail>`;
+
+export const shouldInjectVerification = (currentText: string): boolean =>
+  !currentText.includes(VERIFICATION_TEXT);
+
+export const shouldInjectTdd = (currentText: string): boolean =>
+  !currentText.includes(TDD_TEXT);
+
+export const shouldInjectBrainstorm = (currentText: string): boolean =>
+  !currentText.includes(BRAINSTORM_TEXT);
+
+export const shouldInjectDebug = (currentText: string): boolean =>
+  !currentText.includes(DEBUG_TEXT);
+
+export const shouldInjectReviewReception = (currentText: string): boolean =>
+  !currentText.includes(REVIEW_RECEPTION_TEXT);
+
+export const shouldInjectDocRender = (currentText: string): boolean =>
+  !currentText.includes(DOC_RENDER_TEXT);
+
+export const shouldInjectSddReminder = (currentText: string): boolean =>
+  !currentText.includes(SDD_REMINDER_TEXT);
+
+export const shouldInjectConfigGuard = (currentText: string): boolean =>
+  !currentText.includes(CONFIG_GUARD_TEXT);
+
+export const shouldInjectIssueRail = (currentText: string): boolean =>
+  !currentText.includes(ISSUE_RAIL_TEXT);

package/src/core/repo-tool.ts

@@ -0,0 +1,9 @@
+import { resolveWorkspaceRoot } from "./scripts";
+
+/** Attach the resolved repository root to each repository tool response. */
+export function withWorkspace(workspaceRoot: string, data: Record<string, any> = {}): Record<string, any> {
+  return {
+    workspace_root: resolveWorkspaceRoot(workspaceRoot),
+    ...data,
+  };
+}

package/src/core/rules.ts

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configDir } from "./config";
+
+export type RulePlatform = "cursor" | "opencode";
+export type CanonicalRule = {
+  name: string;
+  description: string;
+  platforms: RulePlatform[];
+  body: string;
+};
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+export const rulesDir = () => path.join(configDir(), "rules");
+
+export const parseRule = (markdown: string): CanonicalRule | { error: string } => {
+  const fm = markdown.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fm) return { error: "rule must start with frontmatter (--- name/description/platforms ---)" };
+  const meta: Record<string, string> = {};
+  const unquote = (v: string) => v.replace(/^["']|["']$/g, "").trim();
+  for (const line of fm[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) meta[line.slice(0, idx).trim()] = unquote(line.slice(idx + 1).trim());
+  }
+  const name = meta.name ?? "";
+  const description = meta.description ?? "";
+  const rawPlatforms = (meta.platforms ?? "")
+    .replace(/^\[|\]$/g, "").split(",").map((p) => p.trim().replace(/['"]/g, ""))
+    .filter(Boolean);
+  const platforms = rawPlatforms.filter((p): p is RulePlatform => p === "cursor" || p === "opencode");
+  if (!name || !description || platforms.length === 0) {
+    return { error: "rule frontmatter requires name, description, and platforms" };
+  }
+  if (platforms.length !== rawPlatforms.length) {
+    return { error: `invalid platform in frontmatter: ${rawPlatforms.join(", ")}` };
+  }
+  return { name, description, platforms, body: fm[2].trim() + "\n" };
+};
+
+export const listRules = (): { name: string; platforms: string[]; source: "config" | "repo" }[] => {
+  const result: { name: string; platforms: string[]; source: "config" | "repo" }[] = [];
+  const dir = rulesDir();
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const file = path.join(dir, entry, "rule.md");
+      if (!existsSync(file)) continue;
+      const parsed = parseRule(readFileSync(file, "utf8"));
+      if ("error" in parsed) continue;
+      result.push({ name: parsed.name, platforms: parsed.platforms, source: "config" });
+    }
+  }
+  return result;
+};
+
+export const readRule = (
+  name: string,
+): { source: "config" | "repo" | "missing"; rule: CanonicalRule } | { error: string } => {
+  const file = path.join(rulesDir(), name, "rule.md");
+  if (existsSync(file)) {
+    const parsed = parseRule(readFileSync(file, "utf8"));
+    if ("error" in parsed) return { error: parsed.error };
+    return { source: "config", rule: parsed };
+  }
+  return { source: "missing", rule: { name, description: "", platforms: [], body: "" } };
+};
+
+const RULE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export const writeRule = (
+  rule: CanonicalRule,
+  confirmed: boolean,
+): { ok: true; path: string } | { ok: false; error: string } => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  if (!RULE_NAME_RE.test(rule.name)) return { ok: false, error: `invalid rule name: ${JSON.stringify(rule.name)}` };
+  const dir = path.join(rulesDir(), rule.name);
+  mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, "rule.md");
+  const md = `---\nname: ${rule.name}\ndescription: ${rule.description}\nplatforms: [${rule.platforms.join(", ")}]\n---\n${rule.body}`;
+  writeFileSync(file, md, "utf8");
+  return { ok: true, path: file };
+};
+
+export const compileRuleCursor = (rule: CanonicalRule): string =>
+  `---\ndescription: ${rule.description}\nalwaysApply: true\n---\n\n${rule.body}`;
+
+export const compileRuleOpenCode = (rule: CanonicalRule): string =>
+  `## ${rule.name}\n\n${rule.body}`;
+
+export const compiledOpenCodeSections = (): string => {
+  const sections: string[] = [];
+  const dir = rulesDir();
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const file = path.join(dir, entry, "rule.md");
+      if (!existsSync(file)) continue;
+      const parsed = parseRule(readFileSync(file, "utf8"));
+      if ("error" in parsed || !parsed.platforms.includes("opencode")) continue;
+      sections.push(compileRuleOpenCode(parsed));
+    }
+  }
+  return sections.join("\n\n");
+};
+
+export const writeCompiledCursorRules = (targetDir: string): string[] => {
+  const written: string[] = [];
+  const dir = rulesDir();
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const file = path.join(dir, entry, "rule.md");
+      if (!existsSync(file)) continue;
+      const parsed = parseRule(readFileSync(file, "utf8"));
+      if ("error" in parsed || !parsed.platforms.includes("cursor")) continue;
+      if (!RULE_NAME_RE.test(parsed.name)) continue;
+      const out = path.join(targetDir, `${parsed.name}.mdc`);
+      writeFileSync(out, compileRuleCursor(parsed), "utf8");
+      written.push(out);
+    }
+  }
+  return written;
+};

package/src/core/scripts.ts

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = path.resolve(dirname, "../..");
+
+export const resolveWorkspaceRoot = (explicit?: string) => explicit || process.cwd();
+
+export function runScript(
+  scriptName: string,
+  args: string[],
+  workspaceRoot: string,
+  extraEnv?: Record<string, string>,
+) {
+  const cwd = resolveWorkspaceRoot(workspaceRoot);
+  const scriptPath = path.join(PLUGIN_ROOT, "scripts", scriptName);
+  const result = spawnSync("bash", [scriptPath, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...(extraEnv ?? {}) },
+  });
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    exitCode: result.status ?? 1,
+    scriptPath,
+    cwd,
+  };
+}
+
+export function runScriptJson(scriptName: string, args: string[], workspaceRoot: string, extraEnv?: Record<string, string>) {
+  const { stdout, stderr, exitCode } = runScript(scriptName, args, workspaceRoot, extraEnv);
+  if (exitCode !== 0) {
+    return { error: (stderr || stdout || "script failed").trim(), exitCode };
+  }
+  try {
+    return { data: JSON.parse(stdout.trim()) };
+  } catch {
+    return { error: "invalid JSON from script", raw: stdout.trim() };
+  }
+}