@soleur/opencode 1.0.0 → 3.354.3

package/scripts/install-opencode-adapter.ts

@@ -16,9 +16,12 @@
  * Shapes here are each forced by a measurement:
  *
  *   - `agents/` and `commands/` are copied straight into the config dir, because those are
- *     the roots OpenCode discovers (§3.0, §4.0). Skills are **not** copied — they register
- *     from the canonical tree through the `skills` key (§2.0), so the config points at the
- *     checkout and a second skill tree that could drift is never created.
+ *     the roots OpenCode discovers (§3.0, §4.0). Skills are **not** copied on a checkout
+ *     install — they register from the canonical tree through the `skills` key (§2.0), so the
+ *     config points at the checkout and a second skill tree that could drift is never created.
+ *   - On an npm install (`--vendor-payload`), the canonical payload is mirrored into
+ *     `<configdir>/soleur/` so every installed reference points at a durable directory that
+ *     survives `npx` / `bunx` cache eviction.
  *   - The config fragment is merged rather than written, so an operator's existing
  *     `skills` / `instructions` entries and every other key survive — for a config this script
  *     can READ. A config it cannot parse (JSONC comments, a syntax error, a torn write) is
@@ -28,14 +31,24 @@
  *     `opencode.json` whose next read takes the unparseable path.
  *   - The hook module (`opencode/plugin.ts`, source rather than a generated stub) is copied
  *     into `<configdir>/plugins/`, OpenCode's plugin discovery directory (measurement §6.6),
- *     with the plugin-root token resolved so the installed copy still reaches the checkout's
- *     guard scripts.
+ *     with the plugin-root token resolved so the installed copy still reaches the guard scripts.
  *
  * `--check` writes nothing: it compares the target against `expectedInstalled` and exits 1
  * on a difference.
  */
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
 import { dirname, join, relative, resolve } from "path";
 import {
   ADAPTER_DIR,
@@ -60,12 +73,6 @@ export const VENDOR_DIR = "soleur";
 /**
  * The plugin-root subtrees a vendored payload carries.
  *
- * A vendored payload is the canonical plugin root copied into the config dir. It exists because
- * the npm distribution has **no checkout to point at**: `npx` runs the installer out of an
- * ephemeral cache directory, so a config that named the package path rots the moment that cache
- * is pruned — and the failure is silent, because the `skills` key and the guard scripts simply
- * stop resolving. The copy is the durable root.
- *
  * Each entry is load-bearing: `skills` is what the `skills` key registers, `agents`/`commands`
  * are what the generated stubs name, `hooks` is what the installed hook module spawns its guards
  * from, `scripts` is what the canonical prose calls as `<root>/scripts/<name>.sh` (404 call
@@ -99,18 +106,22 @@ export function isVendoredRoot(root: string): boolean {
   return existsSync(join(root, VENDOR_MARKER));
 }
 
-/**
- * Deterministic marker bytes. No version and no timestamp: the payload's own files carry the
- * version (an upgrade changes them and `--check` reports STALE), and a version here would make
- * the marker flap between the two install modes.
- */
 function vendorMarkerContent(): string {
   return `${JSON.stringify({ format: 1, kind: "soleur-opencode-payload", owns: [...PAYLOAD_DIRS] }, null, 2)}\n`;
 }
 
-/** Every file under `<root>/<dir>`, keyed `<dir>/<relative path>`, in sorted order. */
-function walkPayloadFiles(root: string, dir: string): Array<[string, string]> {
-  const found: Array<[string, string]> = [];
+export interface PayloadEntry {
+  content: string;
+  executable: boolean;
+}
+
+/**
+ * Every regular file under `<root>/<dir>`, keyed `<dir>/<relative path>`, in sorted order.
+ * Symlinks are refused so a stray symlink in the source tree can never be dereferenced into
+ * the published npm tarball or vendored config directory.
+ */
+export function walkPayloadFiles(root: string, dir: string): Array<[string, PayloadEntry]> {
+  const found: Array<[string, PayloadEntry]> = [];
   const visit = (relativeDir: string): void => {
     let entries;
     try {
@@ -119,32 +130,53 @@ function walkPayloadFiles(root: string, dir: string): Array<[string, string]> {
       return;
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-      const path = `${relativeDir}/${entry.name}`;
+      const path = `${currentPath(relativeDir, entry.name)}`;
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Refusing symbolic link in payload tree: ${join(root, path)}`);
+      }
       if (entry.isDirectory()) {
         visit(path);
         continue;
       }
-      found.push([path, readFileSync(join(root, path), "utf-8")]);
+      if (!entry.isFile()) continue;
+      const full = join(root, path);
+      const executable = (statSync(full).mode & 0o111) !== 0;
+      found.push([path, { content: readFileSync(full, "utf-8"), executable }]);
     }
   };
   visit(dir);
   return found;
 }
 
+function currentPath(dir: string, name: string): string {
+  return `${dir}/${name}`;
+}
+
+/** Full payload map for `root`, shared with `sync-npm-package.ts`. */
+export function expectedPayloadEntries(root: string): Map<string, PayloadEntry> {
+  const expected = new Map<string, PayloadEntry>();
+  for (const dir of PAYLOAD_DIRS) {
+    for (const [path, entry] of walkPayloadFiles(root, dir)) {
+      expected.set(path, entry);
+    }
+  }
+  return expected;
+}
+
 export interface InstallOptions {
   force?: boolean;
   /**
    * Mirror the canonical payload into `<target>/soleur/` and point every installed file at that
    * copy instead of at `pluginRoot`. Used by the npm distribution, which has no checkout.
-   *
-   * A vendored payload is also recognised without this flag: a root carrying `VENDOR_MARKER`
-   * owns its payload wherever it sits inside the target, so the copy's own `--check` agrees
-   * with the install that produced it.
    */
   vendorPayload?: boolean;
 }
 
-/** `__SOLEUR_PLUGIN_ROOT__` → the real checkout. The only substitution in the whole install. */
+function resolveEffectiveRoot(targetDir: string, pluginRoot: string, options: InstallOptions): string {
+  return options.vendorPayload === true ? join(targetDir, VENDOR_DIR) : pluginRoot;
+}
+
+/** `__SOLEUR_PLUGIN_ROOT__` → the resolved root. The only substitution in the whole install. */
 function resolveToken(content: string, pluginRoot: string): string {
   return content.split(PLUGIN_ROOT_TOKEN).join(pluginRoot);
 }
@@ -162,13 +194,6 @@ export function mergeFragment(
   return merged;
 }
 
-/**
- * A config file that exists but cannot be read as a JSON object.
- *
- * This is not a generic parse error: it is the branch that decides between merging into an
- * operator's config and destroying it. It names the path and the remedy because the caller's
- * only sane action is to look at that file.
- */
 export class UnparseableConfigError extends Error {
   constructor(
     readonly path: string,
@@ -181,14 +206,6 @@ export class UnparseableConfigError extends Error {
   }
 }
 
-/**
- * Where each generated file lands in a config dir, with tokens resolved.
- *
- * The plugin module is the one file here that is **source, not a generated stub**: it is
- * hand-written in the generator's namespace (`ADAPTER_SOURCE_FILES`) and installed into
- * OpenCode's plugin discovery directory, `<configdir>/plugins/`, with the plugin-root token
- * resolved so the checkout's guard scripts stay reachable from the installed copy.
- */
 export function expectedInstalled(
   targetDir: string,
   pluginRoot = PLUGIN_ROOT,
@@ -196,79 +213,48 @@ export function expectedInstalled(
   options: InstallOptions = {},
 ): Map<string, string> {
   const expected = new Map<string, string>();
-  // Where the installed files POINT, as opposed to where their bytes come from. The two are the
-  // same for a checkout install. They differ for a vendored payload, where the bytes come from
-  // the package and the pointer must name the copy — the only path that outlives the npm cache.
-  const effectiveRoot = options.vendorPayload === true ? join(targetDir, VENDOR_DIR) : pluginRoot;
+  const effectiveRoot = resolveEffectiveRoot(targetDir, pluginRoot, options);
   for (const [path, content] of expectedOpenCodeAdapter(pluginRoot)) {
-    if (path === `${ADAPTER_DIR}/opencode.json`) continue; // merged below, never copied verbatim
-    // `opencode/` is the generator's namespace, not a discovery root. INSTRUCTIONS.md keeps a
-    // `soleur/` prefix so it cannot collide with anything the operator already has.
+    if (path === `${ADAPTER_DIR}/opencode.json`) continue;
     const installed =
       path === `${ADAPTER_DIR}/INSTRUCTIONS.md` ? `soleur/${relative(ADAPTER_DIR, path)}` : relative(ADAPTER_DIR, path);
     expected.set(installed, resolveToken(content, effectiveRoot));
   }
   for (const source of ADAPTER_SOURCE_FILES) {
     if (!source.startsWith(`${ADAPTER_DIR}/`)) continue;
-    // Every `*.ts` in `<configdir>/plugins/` loads (measurement §6.6), so the installed name
-    // carries the plugin's namespace: a bare `plugin.ts` would collide with an operator's own.
     const installed = `plugins/soleur-${source.slice(ADAPTER_DIR.length + 1)}`;
     expected.set(installed, resolveToken(readFileSync(join(pluginRoot, source), "utf-8"), effectiveRoot));
   }
-  for (const [path, content] of payloadExpected(targetDir, pluginRoot, effectiveRoot, options)) {
-    expected.set(path, content);
+  for (const [path, entry] of payloadExpected(targetDir, pluginRoot, effectiveRoot, options)) {
+    expected.set(path, entry.content);
   }
-  // One definition of the fragment's shape, shared with the generator: the generator emits it
-  // with the token, this resolves the token and unions it into the operator's config.
   const fragment = configFragmentValues(effectiveRoot);
   const merged = mergeFragment(config ?? readConfig(join(targetDir, "opencode.json")), {
     skills: fragment.skills,
-    // The installed path (`soleur/`), not the generator's `opencode/` namespace.
     instructions: [join(targetDir, "soleur", "INSTRUCTIONS.md")],
   });
   expected.set("opencode.json", `${JSON.stringify(merged, null, 2)}\n`);
   return expected;
 }
 
-/**
- * The payload files this install owns, keyed target-relative.
- *
- * Content always comes from `sourceRoot` and is written under `effectiveRoot`, which is what
- * makes the two install modes one code path: a checkout install has no payload inside the target
- * (the checkout is the root, so `effectiveRoot` is outside it and this returns nothing), while a
- * vendored install has `effectiveRoot` inside the target and mirrors the bytes there.
- *
- * Ownership is the point, not the copy: these paths join `expected`, so the extras sweep — which
- * deletes anything under `soleur/` the installer did not write — keeps them instead of deleting
- * the payload one pass after writing it.
- */
 function payloadExpected(
   targetDir: string,
   sourceRoot: string,
   effectiveRoot: string,
   options: InstallOptions,
-): Map<string, string> {
+): Map<string, PayloadEntry> {
   const owned = options.vendorPayload === true || isVendoredRoot(sourceRoot);
-  const result = new Map<string, string>();
+  const result = new Map<string, PayloadEntry>();
   if (!owned) return result;
   const prefix = relative(targetDir, effectiveRoot).split("\\").join("/");
-  // A root outside the target owns nothing inside it: that is the checkout install.
   if (prefix === "" || prefix.startsWith("..")) return result;
-  for (const dir of PAYLOAD_DIRS) {
-    for (const [path, content] of walkPayloadFiles(sourceRoot, dir)) {
-      result.set(`${prefix}/${path}`, content);
-    }
+  for (const [path, entry] of expectedPayloadEntries(sourceRoot)) {
+    result.set(`${prefix}/${path}`, entry);
   }
-  result.set(`${prefix}/${VENDOR_MARKER}`, vendorMarkerContent());
+  result.set(`${prefix}/${VENDOR_MARKER}`, { content: vendorMarkerContent(), executable: false });
   return result;
 }
 
-/**
- * Read an operator config. A **missing** config is an empty one (a first install); anything
- * else that is not a JSON object throws `UnparseableConfigError`. The two cases were one branch
- * (`catch → {}`), which made "first install" and "operator config with JSONC comments"
- * indistinguishable — and the write path then replaced the second with the fragment alone.
- */
 function readConfig(path: string): Record<string, unknown> {
   let raw: string;
   try {
@@ -284,12 +270,15 @@ function readConfig(path: string): Record<string, unknown> {
     throw new UnparseableConfigError(path, String(error));
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new UnparseableConfigError(path, `top level is ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`);
+    throw new UnparseableConfigError(
+      path,
+      `top level is ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`,
+    );
   }
   return parsed as Record<string, unknown>;
 }
 
-/** Target-relative paths of every file under `dir` (empty when the directory is absent). */
+/** Target-relative paths of every regular file under `dir` (skips symlinks; empty when absent). */
 function walkFiles(targetDir: string, dir: string): string[] {
   const found: string[] = [];
   const visit = (relativeDir: string): void => {
@@ -300,45 +289,32 @@ function walkFiles(targetDir: string, dir: string): string[] {
       return;
     }
     for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
       const path = `${relativeDir}/${entry.name}`;
       if (entry.isDirectory()) visit(path);
-      else found.push(path);
+      else if (entry.isFile()) found.push(path);
     }
   };
   visit(dir);
   return found.sort();
 }
 
-/**
- * The generated stubs' own signature. `agents/` and `commands/` are SHARED with the operator, so
- * a file there is only removable when it says, in its own text, that this generator wrote it and
- * that it points at the resolved checkout. Anything else in those roots is not ours.
- */
 const STUB_SIGNATURES = ["Stub for the canonical agent `", "Run the canonical `"] as const;
 
 function isGeneratedStub(content: string, pluginRoot: string): boolean {
   return content.includes(pluginRoot) && STUB_SIGNATURES.some((signature) => content.includes(signature));
 }
 
-/**
- * Files an install owns but no longer generates. Without this, deleting an agent or renaming a
- * command in the canonical tree leaves its installed stub loading forever — a half-updated
- * install that `--check` would call ok.
- */
 export function installedExtras(
   targetDir: string,
   expected: Map<string, string>,
   root = PLUGIN_ROOT,
 ): string[] {
   const extras: string[] = [];
-  // Exclusive namespaces: everything under `soleur/` and `plugins/soleur-*` is ours by name.
-  // A vendored payload's own files are in `expected`, so they are not "extras".
   for (const path of walkFiles(targetDir, "soleur")) if (!expected.has(path)) extras.push(path);
   for (const path of walkFiles(targetDir, "plugins")) {
     if (path.startsWith("plugins/soleur-") && !expected.has(path)) extras.push(path);
   }
-  // Shared roots: attributed by content, never by location. A stub names the RESOLVED root, so
-  // `root` here is the effective root the install wrote into those stubs, not the source.
   for (const root_ of ["agents", "commands"]) {
     for (const path of walkFiles(targetDir, root_)) {
       if (expected.has(path)) continue;
@@ -354,20 +330,18 @@ export function installedExtras(
   return extras.sort();
 }
 
-/** Write through a sibling temp file and rename, so a reader never sees a partial file. */
-function writeAtomic(full: string, content: string): void {
+/** Write through a sibling temp file and rename, preserving executable mode when needed. */
+function writeAtomic(full: string, content: string, executable = false): void {
   mkdirSync(dirname(full), { recursive: true });
   const temp = `${full}.soleur-tmp-${process.pid}`;
   writeFileSync(temp, content);
+  if (executable) chmodSync(temp, 0o755);
   renameSync(temp, full);
 }
 
 export interface InstallResult {
-  /** Config-dir-relative files written or updated, sorted. */
   written: string[];
-  /** Config-dir-relative files that were already correct, sorted. */
   unchanged: string[];
-  /** Config-dir-relative stale files removed, sorted. */
   removed: string[];
 }
 
@@ -389,21 +363,25 @@ export function installOpenCodeAdapter(
     console.error(`[soleur] --force: replaced ${configPath}; the previous bytes are at ${backup}`);
     config = {};
   }
+  const effectiveRoot = resolveEffectiveRoot(targetDir, pluginRoot, options);
+  const payload = payloadExpected(targetDir, pluginRoot, effectiveRoot, options);
   const expected = expectedInstalled(targetDir, pluginRoot, config, options);
-  const effectiveRoot = options.vendorPayload === true ? join(targetDir, VENDOR_DIR) : pluginRoot;
   for (const [path, content] of expected) {
     const full = join(targetDir, path);
+    const wantExec = payload.get(path)?.executable === true;
     let current: string | undefined;
+    let currentExec = false;
     try {
       current = readFileSync(full, "utf-8");
+      currentExec = (statSync(full).mode & 0o111) !== 0;
     } catch {
       current = undefined;
     }
-    if (current === content) {
+    if (current === content && (!wantExec || currentExec)) {
       result.unchanged.push(path);
       continue;
     }
-    writeAtomic(full, content);
+    writeAtomic(full, content, wantExec);
     result.written.push(path);
   }
   for (const path of installedExtras(targetDir, expected, effectiveRoot)) {
@@ -416,19 +394,24 @@ export function installOpenCodeAdapter(
   return result;
 }
 
-/** Read-only: paths the target does not already match. Empty means installed and current. */
 export function installProblems(targetDir: string, pluginRoot = PLUGIN_ROOT, options: InstallOptions = {}): string[] {
   const problems: string[] = [];
+  const effectiveRoot = resolveEffectiveRoot(targetDir, pluginRoot, options);
+  const payload = payloadExpected(targetDir, pluginRoot, effectiveRoot, options);
   const expected = expectedInstalled(targetDir, pluginRoot, undefined, options);
-  const effectiveRoot = options.vendorPayload === true ? join(targetDir, VENDOR_DIR) : pluginRoot;
   for (const [path, content] of expected) {
+    const full = join(targetDir, path);
+    const wantExec = payload.get(path)?.executable === true;
     let current: string | undefined;
+    let currentExec = false;
     try {
-      current = readFileSync(join(targetDir, path), "utf-8");
+      current = readFileSync(full, "utf-8");
+      currentExec = (statSync(full).mode & 0o111) !== 0;
     } catch {
       current = undefined;
     }
-    if (current !== content) problems.push(current === undefined ? `MISSING: ${path}` : `STALE: ${path}`);
+    if (current === undefined) problems.push(`MISSING: ${path}`);
+    else if (current !== content || (wantExec && !currentExec)) problems.push(`STALE: ${path}`);
   }
   for (const path of installedExtras(targetDir, expected, effectiveRoot)) {
     problems.push(`EXTRA: ${path}`);
@@ -439,13 +422,11 @@ export function installProblems(targetDir: string, pluginRoot = PLUGIN_ROOT, opt
 function parseArg(argv: readonly string[], flag: string): string | undefined {
   const index = argv.indexOf(flag);
   if (index === -1) return undefined;
-  const value = argv[index + 1];
-  if (value === undefined) throw new Error(`${flag} requires a directory`);
-  return value;
+  return argv[index + 1];
 }
 
 const USAGE = [
-  "Usage: bun plugins/soleur/scripts/install-opencode-adapter.ts [--target DIR] [--plugin-root DIR] [--vendor-payload] [--check] [--force] [--help]",
+  "Usage: bun plugins/soleur/scripts/install-opencode-adapter.ts [install] [--target DIR] [--plugin-root DIR] [--vendor-payload] [--check] [--force] [--help]",
   "",
   "  --target DIR       config dir to install into (default: $HOME/.config/opencode)",
   "  --plugin-root DIR  checkout (or package) the installed files should point at (default: this checkout)",
@@ -456,30 +437,38 @@ const USAGE = [
   "  --help, -h         print this text and exit 0 without writing",
 ].join("\n");
 
-/**
- * Unknown arguments are rejected: a typo (`--chek`) otherwise falls through to the WRITE path,
- * which is the direction that changes an operator's machine.
- */
-function validateArgs(argv: readonly string[]): void {
+function validateArgs(argv: readonly string[], usage = USAGE): void {
   const withValue = new Set(["--target", "--plugin-root"]);
   const known = new Set([...withValue, "--vendor-payload", "--check", "--force", "--help", "-h"]);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
-      console.log(USAGE);
+      console.log(usage);
       process.exit(0);
     }
     if (!known.has(arg)) {
-      console.error(`unknown argument: ${arg}\n${USAGE}`);
+      console.error(`unknown argument: ${arg}\n${usage}`);
       process.exit(2);
     }
-    if (withValue.has(arg)) i += 1;
+    if (withValue.has(arg)) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("-")) {
+        console.error(`${arg} requires a directory\n${usage}`);
+        process.exit(2);
+      }
+      i += 1;
+    }
   }
 }
 
-function main(): void {
-  const argv = process.argv.slice(2);
-  validateArgs(argv);
+export function runCli(
+  rawArgv: readonly string[],
+  defaultPluginRoot = PLUGIN_ROOT,
+  defaultVendorPayload = false,
+  usage = USAGE,
+): void {
+  const argv = rawArgv[0] === "install" ? rawArgv.slice(1) : rawArgv;
+  validateArgs(argv, usage);
   const explicitTarget = parseArg(argv, "--target");
   const home = process.env["HOME"];
   if (explicitTarget === undefined && (home === undefined || home === "")) {
@@ -489,10 +478,10 @@ function main(): void {
     process.exit(2);
   }
   const targetDir = resolve(explicitTarget ?? join(home as string, ".config", "opencode"));
-  const pluginRoot = resolve(parseArg(argv, "--plugin-root") ?? PLUGIN_ROOT);
+  const pluginRoot = resolve(parseArg(argv, "--plugin-root") ?? defaultPluginRoot);
   const options: InstallOptions = {
     force: argv.includes("--force"),
-    vendorPayload: argv.includes("--vendor-payload"),
+    vendorPayload: defaultVendorPayload || argv.includes("--vendor-payload"),
   };
   try {
     if (argv.includes("--check")) {
@@ -517,4 +506,4 @@ function main(): void {
   }
 }
 
-if (import.meta.main) main();
+if (import.meta.main) runCli(process.argv.slice(2));

package/scripts/monitor-pr-checks.sh

@@ -323,7 +323,7 @@ while :; do
   # the draft run is not a recovery (it reuses the cached draft-light output and can cancel the in-flight ready run).
   case "$V_STATE" in
     stalled)
-      printf 'READY RUN STALLED — PR #%s was marked ready but no full CI run decided (%s: the stall window counts from the ready event); the red test row is the DRAFT run'"'"'s, by design. Do NOT start a fix loop on it. First confirm in the Actions tab that the ready run is not still in flight; recovery with a user token (never GITHUB_TOKEN): gh pr ready --undo %s ; gh pr ready %s\n' "$PR" "$V_WHY" "$PR" "$PR"
+      printf 'READY RUN STALLED — PR #%s was marked ready but no full CI run decided (%s: see ci-head-verdict.sh --help for the stall clock); the red test row is the DRAFT run'"'"'s, by design. Do NOT start a fix loop on it. First confirm in the Actions tab that the ready run is not still in flight; recovery with a user token (never GITHUB_TOKEN): gh pr ready --undo %s ; gh pr ready %s\n' "$PR" "$V_WHY" "$PR" "$PR"
       exit 1 ;;
     no-run)
       # A conflicting PR gets no pull_request run (GitHub builds no merge ref), so the PENDING relabel above would watch it

package/scripts/precommit-guard.sh

@@ -104,7 +104,9 @@ while IFS= read -r seg; do
   else
     continue # nowhere to resolve — nothing to refuse on
   fi
-  if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
+  # The alternation is the stamped default-branch set — soleur:verification-scaffold
+  # emits this file with `main|master` substituted for the target's resolved default.
+  if [[ "$BRANCH" =~ ^(main|master)$ ]]; then
     printf 'BLOCKED: Committing directly to %s is not allowed. Create a feature branch first.\n' "$BRANCH" >&2
     exit 1
   fi