@soleur/opencode 0.0.0-stage → 1.0.0

package/scripts/sync-grok-agent-compat.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env bun
+/**
+ * Generate Grok agent compat artifacts from the canonical agent registry.
+ *
+ * Writes:
+ *   - plugins/soleur/.claude-plugin/agents.manifest.json
+ *   - <repo-root>/.grok/agents/<qualified-id-dashes>.md (thin project-agent stubs)
+ *
+ * Usage:
+ *   bun run scripts/sync-grok-agent-compat.ts          # write artifacts
+ *   bun run scripts/sync-grok-agent-compat.ts --check  # exit 1 on drift
+ *   bun run scripts/sync-grok-agent-compat.ts --verbose
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from "fs";
+import { resolve, join } from "path";
+import {
+  buildAgentsManifest,
+  discoverAgentEntries,
+  agentIdToCompatFilename,
+  agentIdToGrokSubagentType,
+  buildCompatStubBody,
+  renderAgentIdsForGrok,
+  PLUGIN_ROOT,
+} from "../lib/agent-registry";
+
+const REPO_ROOT = resolve(PLUGIN_ROOT, "../..");
+const MANIFEST_PATH = resolve(PLUGIN_ROOT, ".claude-plugin/agents.manifest.json");
+const GROK_AGENTS_DIR = resolve(REPO_ROOT, ".grok/agents");
+
+const args = new Set(process.argv.slice(2));
+const checkOnly = args.has("--check");
+const verbose = args.has("--verbose");
+
+function log(msg: string): void {
+  if (verbose) console.log(msg);
+}
+
+function manifestJson(manifest: ReturnType<typeof buildAgentsManifest>): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/** Claude Code aliases. Grok's catalog does not resolve them (ADR-110 decision 4). */
+const CLAUDE_MODEL_ALIASES = new Set(["haiku", "sonnet", "opus", "fable"]);
+
+/** Omit the line for a Claude alias so the Grok stub inherits the session model. */
+function grokStubModelLine(model: string): string | null {
+  if (CLAUDE_MODEL_ALIASES.has(model)) return null;
+  return `model: ${model}`;
+}
+
+/**
+ * YAML-safe double-quoted scalar for frontmatter fields that may contain `:`, `§`, etc. Line
+ * breaks and control characters are escaped too: a raw newline could close the stub's
+ * frontmatter early under a `^---` regex parser.
+ */
+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}"`;
+}
+
+function compatStubMarkdown(
+  entry: ReturnType<typeof discoverAgentEntries>[number],
+  agentIds: ReadonlySet<string>,
+): string {
+  const description = renderAgentIdsForGrok(entry.description || entry.name, agentIds);
+  // Frontmatter name MUST match the Grok spawn key (filename stem = colons→hyphens).
+  // Using colon-form here lists `soleur:product:cpo` in available types while
+  // spawn only accepts `soleur-product-cpo` (Grok ≤0.2.102 filename-stem match).
+  const grokName = agentIdToGrokSubagentType(entry.id);
+  const lines = [
+    "---",
+    `name: ${grokName}`,
+    `description: ${yamlQuote(description)}`,
+  ];
+  const modelLine = grokStubModelLine(entry.model);
+  if (modelLine !== null) lines.push(modelLine);
+  lines.push("---", "", buildCompatStubBody(entry.path), "");
+  return lines.join("\n");
+}
+
+function expectedCompatFiles(): Map<string, string> {
+  const files = new Map<string, string>();
+  const entries = discoverAgentEntries();
+  const agentIds = new Set(entries.map((e) => e.id));
+  for (const entry of entries) {
+    files.set(agentIdToCompatFilename(entry.id), compatStubMarkdown(entry, agentIds));
+  }
+  return files;
+}
+
+function readText(path: string): string {
+  return readFileSync(path, "utf-8");
+}
+
+function checkDrift(): boolean {
+  let drift = false;
+  const manifest = buildAgentsManifest();
+  const expectedManifest = manifestJson(manifest);
+
+  try {
+    if (readText(MANIFEST_PATH) !== expectedManifest) {
+      console.error(`DRIFT: ${MANIFEST_PATH}`);
+      drift = true;
+    }
+  } catch {
+    console.error(`MISSING: ${MANIFEST_PATH}`);
+    drift = true;
+  }
+
+  const expected = expectedCompatFiles();
+  let onDisk: string[] = [];
+  try {
+    onDisk = readdirSync(GROK_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+  } catch {
+    console.error(`MISSING: ${GROK_AGENTS_DIR}`);
+    drift = true;
+  }
+
+  const expectedNames = new Set(expected.keys());
+  const onDiskSet = new Set(onDisk);
+
+  for (const name of expectedNames) {
+    if (!onDiskSet.has(name)) {
+      console.error(`MISSING compat stub: .grok/agents/${name}`);
+      drift = true;
+      continue;
+    }
+    const path = join(GROK_AGENTS_DIR, name);
+    if (readText(path) !== expected.get(name)) {
+      console.error(`DRIFT compat stub: .grok/agents/${name}`);
+      drift = true;
+    }
+  }
+
+  for (const name of onDisk) {
+    if (!expectedNames.has(name)) {
+      console.error(`EXTRA compat stub: .grok/agents/${name}`);
+      drift = true;
+    }
+  }
+
+  return drift;
+}
+
+function writeArtifacts(): void {
+  const manifest = buildAgentsManifest();
+  mkdirSync(resolve(PLUGIN_ROOT, ".claude-plugin"), { recursive: true });
+  mkdirSync(GROK_AGENTS_DIR, { recursive: true });
+
+  writeFileSync(MANIFEST_PATH, manifestJson(manifest));
+  log(`Wrote ${MANIFEST_PATH} (${manifest.count} agents)`);
+
+  const expected = expectedCompatFiles();
+  const keep = new Set(expected.keys());
+
+  for (const [filename, content] of expected) {
+    writeFileSync(join(GROK_AGENTS_DIR, filename), content);
+    log(`Wrote .grok/agents/${filename}`);
+  }
+
+  for (const existing of readdirSync(GROK_AGENTS_DIR)) {
+    if (existing.endsWith(".md") && !keep.has(existing)) {
+      rmSync(join(GROK_AGENTS_DIR, existing));
+      log(`Removed stale .grok/agents/${existing}`);
+    }
+  }
+}
+
+if (checkOnly) {
+  process.exit(checkDrift() ? 1 : 0);
+}
+
+writeArtifacts();
+if (checkDrift()) {
+  console.error("sync-grok-agent-compat: write completed but drift check failed");
+  process.exit(1);
+}
+
+console.log(
+  `sync-grok-agent-compat: ${discoverAgentEntries().length} agents → manifest + .grok/agents/`,
+);

package/scripts/sync-npm-package.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * Generate the `@soleur/opencode` payload from the canonical tree.
+ *
+ *   bun plugins/soleur/scripts/sync-npm-package.ts
+ *   bun plugins/soleur/scripts/sync-npm-package.ts --check
+ *
+ * The npm distribution is a **copy** of the plugin root, and this is the only thing that writes
+ * that copy. Nothing under `packages/opencode-plugin/` is hand-copied: the package's hand-written
+ * files are `package.json`, `README.md`, `install.js` and `bin/`, and everything else is a mirror
+ * of a subtree this script owns.
+ *
+ * Why a copy at all, when ADR-291 has OpenCode register skills straight from the canonical tree
+ * with no second tree to drift? Because npm has no checkout to point at. The package has to carry
+ * the bytes it installs, so a copy is unavoidable at the boundary; what ADR-245's drift obligation
+ * buys us instead is that the copy cannot be *wrong*: `--check` compares it against a fresh walk
+ * and exits 1 naming the path, so a canonical skill, agent, script or hook edited without
+ * regenerating the package reds in CI rather than shipping stale.
+ *
+ * `PAYLOAD_DIRS` is imported from the installer rather than restated here: the set the copy
+ * carries and the set the installer owns inside a config dir are the same set, and two lists
+ * would drift apart silently.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { PAYLOAD_DIRS } from "./install-opencode-adapter";
+
+/** The canonical plugin root — the copy's source. */
+const CANONICAL_ROOT = resolve(dirname(import.meta.filename), "..");
+
+/** Repo-relative location of the npm package. */
+const PACKAGE_RELATIVE = "packages/opencode-plugin";
+
+/** Files at the package root that this script does NOT own. */
+export const PACKAGE_SOURCE_FILES = ["package.json", "README.md", "install.js", "bin"] as const;
+
+function packageRoot(repoRoot: string): string {
+  return join(repoRoot, PACKAGE_RELATIVE);
+}
+
+/** Every file under `<root>/<relativeDir>`, keyed `<relativeDir>/<path>`. */
+function walk(root: string, relativeDir: string): Map<string, string> {
+  const found = new Map<string, string>();
+  const visit = (current: string): void => {
+    let entries;
+    try {
+      entries = readdirSync(join(root, current), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = `${current}/${entry.name}`;
+      if (entry.isDirectory()) {
+        visit(path);
+        continue;
+      }
+      found.set(path, readFileSync(join(root, path), "utf-8"));
+    }
+  };
+  visit(relativeDir);
+  return found;
+}
+
+/** The canonical payload, keyed package-relative — the whole truth `--check` compares against. */
+export function expectedPackage(repoRoot: string): Map<string, string> {
+  const canonical = join(repoRoot, "plugins", "soleur");
+  const expected = new Map<string, string>();
+  for (const dir of PAYLOAD_DIRS) {
+    for (const [path, content] of walk(canonical, dir)) expected.set(path, content);
+  }
+  return expected;
+}
+
+/** Committed payload files under the package, package-relative. */
+function committedPackage(repoRoot: string): string[] {
+  const found: string[] = [];
+  for (const dir of PAYLOAD_DIRS) {
+    for (const path of walk(packageRoot(repoRoot), dir).keys()) found.push(path);
+  }
+  return found.sort();
+}
+
+/** Drift between the committed package and a fresh walk of the canonical tree. Empty means clean. */
+export function packageProblems(repoRoot: string): string[] {
+  const expected = expectedPackage(repoRoot);
+  const root = packageRoot(repoRoot);
+  const problems: string[] = [];
+  for (const [path, content] of expected) {
+    let current: string | undefined;
+    try {
+      current = readFileSync(join(root, path), "utf-8");
+    } catch {
+      current = undefined;
+    }
+    if (current === undefined) problems.push(`MISSING: ${path}`);
+    else if (current !== content) problems.push(`DRIFT: ${path}`);
+  }
+  for (const path of committedPackage(repoRoot)) {
+    if (!expected.has(path)) problems.push(`EXTRA: ${path}`);
+  }
+  // The hand-written files are what makes the mirror a package. Their absence is a defect a
+  // payload-only comparison cannot see: a directory of the right bytes with no bin installs
+  // nothing.
+  for (const path of PACKAGE_SOURCE_FILES) {
+    if (!existsSync(join(root, path))) problems.push(`MISSING-SOURCE: ${path}`);
+  }
+  return problems.sort();
+}
+
+/** Write the payload, then report the post-write check (which catches stale extras). */
+export function writePackage(repoRoot: string): string[] {
+  const root = packageRoot(repoRoot);
+  const expected = expectedPackage(repoRoot);
+  for (const [path, content] of expected) {
+    const full = join(root, path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  // A payload file the canonical tree no longer has is not removed by writing it back; drop it
+  // so a retired skill cannot keep installing from the package.
+  for (const path of committedPackage(repoRoot)) {
+    if (!expected.has(path)) rmSync(join(root, path), { force: true });
+  }
+  return packageProblems(repoRoot);
+}
+
+function repoRoot(argv: readonly string[]): string {
+  const index = argv.indexOf("--repo-root");
+  if (index === -1) return resolve(CANONICAL_ROOT, "..", "..");
+  const value = argv[index + 1];
+  if (value === undefined) throw new Error("--repo-root requires a directory");
+  return resolve(value);
+}
+
+const USAGE = [
+  "Usage: bun plugins/soleur/scripts/sync-npm-package.ts [--repo-root DIR] [--check] [--help]",
+  "",
+  "  --repo-root DIR  repository root containing plugins/soleur and packages/opencode-plugin",
+  "                   (default: this checkout)",
+  "  --check          compare the committed package against a fresh walk; write nothing",
+  "  --help, -h       print this text and exit 0 without writing",
+].join("\n");
+
+/**
+ * Every argument must be known. A silently ignored typo (`--chek`) takes the WRITE path while the
+ * operator believes they asked for a check — the direction that overwrites the package.
+ */
+function validateArgs(argv: readonly string[]): void {
+  const withValue = new Set(["--repo-root"]);
+  const known = new Set([...withValue, "--check", "--help", "-h"]);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log(USAGE);
+      process.exit(0);
+    }
+    if (!known.has(arg)) {
+      console.error(`unknown argument: ${arg}\n${USAGE}`);
+      process.exit(2);
+    }
+    if (withValue.has(arg)) i += 1;
+  }
+}
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  validateArgs(argv);
+  const root = repoRoot(argv);
+  const problems = argv.includes("--check") ? packageProblems(root) : writePackage(root);
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(problem);
+    process.exit(1);
+  }
+  if (argv.includes("--check")) console.log("npm-package ok");
+}
+
+if (import.meta.main) main();