@soleur/opencode 1.0.0 → 3.354.3

package/scripts/sync-npm-package.ts

@@ -1,30 +1,22 @@
 #!/usr/bin/env bun
 /**
- * Generate the `@soleur/opencode` payload from the canonical tree.
+ * Materialize and verify the `@soleur/opencode` npm package payload from the canonical tree.
  *
  *   bun plugins/soleur/scripts/sync-npm-package.ts
  *   bun plugins/soleur/scripts/sync-npm-package.ts --check
+ *   bun plugins/soleur/scripts/sync-npm-package.ts --out-dir DIR
  *
- * 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.
+ * The npm distribution carries a materialized copy of `PAYLOAD_DIRS` because `npm publish` packs
+ * files from the package directory. To avoid duplicating ~800 files in git, the generated payload
+ * subtrees under `packages/opencode-plugin/` are gitignored and materialized at build/publish time
+ * by this script. `PAYLOAD_DIRS` and `expectedPayloadEntries` are imported from
+ * `install-opencode-adapter.ts` so the package builder and the vendored installer share one
+ * definition of the payload and preserve executable file bits (`0755`).
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { PAYLOAD_DIRS } from "./install-opencode-adapter";
+import { PAYLOAD_DIRS, expectedPayloadEntries, walkPayloadFiles } from "./install-opencode-adapter";
 
 /** The canonical plugin root — the copy's source. */
 const CANONICAL_ROOT = resolve(dirname(import.meta.filename), "..");
@@ -32,123 +24,105 @@ 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. */
+/** Hand-written source 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 {
+function defaultPackageRoot(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. */
+/** The canonical payload, keyed package-relative — the 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);
+  for (const [path, entry] of expectedPayloadEntries(canonical)) {
+    expected.set(path, entry.content);
   }
   return expected;
 }
 
-/** Committed payload files under the package, package-relative. */
-function committedPackage(repoRoot: string): string[] {
+/** Materialized payload files under `pkgRoot`, package-relative. */
+function materializedPackage(pkgRoot: string): string[] {
   const found: string[] = [];
   for (const dir of PAYLOAD_DIRS) {
-    for (const path of walk(packageRoot(repoRoot), dir).keys()) found.push(path);
+    for (const [path] of walkPayloadFiles(pkgRoot, dir)) 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);
+/** Drift between a materialized package root and a fresh walk of the canonical tree. */
+export function packageProblems(repoRoot: string, outDir?: string): string[] {
+  const canonical = join(repoRoot, "plugins", "soleur");
+  const expected = expectedPayloadEntries(canonical);
+  const root = outDir ?? defaultPackageRoot(repoRoot);
   const problems: string[] = [];
-  for (const [path, content] of expected) {
+  for (const [path, entry] of expected) {
+    const full = join(root, path);
     let current: string | undefined;
+    let currentExec = false;
     try {
-      current = readFileSync(join(root, path), "utf-8");
+      current = readFileSync(full, "utf-8");
+      currentExec = (statSync(full).mode & 0o111) !== 0;
     } catch {
       current = undefined;
     }
     if (current === undefined) problems.push(`MISSING: ${path}`);
-    else if (current !== content) problems.push(`DRIFT: ${path}`);
+    else if (current !== entry.content || (entry.executable && !currentExec)) problems.push(`DRIFT: ${path}`);
   }
-  for (const path of committedPackage(repoRoot)) {
+  for (const path of materializedPackage(root)) {
     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) {
+/** Write the payload into `outDir` (default: `packages/opencode-plugin`), preserving executable bits. */
+export function writePackage(repoRoot: string, outDir?: string): string[] {
+  const canonical = join(repoRoot, "plugins", "soleur");
+  const root = outDir ?? defaultPackageRoot(repoRoot);
+  const expected = expectedPayloadEntries(canonical);
+  for (const [path, entry] of expected) {
     const full = join(root, path);
     mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, content);
+    writeFileSync(full, entry.content);
+    if (entry.executable) chmodSync(full, 0o755);
   }
-  // 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)) {
+  for (const path of materializedPackage(root)) {
     if (!expected.has(path)) rmSync(join(root, path), { force: true });
   }
-  return packageProblems(repoRoot);
+  return packageProblems(repoRoot, root);
+}
+
+/** Remove generated payload subtrees from `outDir` (default: `packages/opencode-plugin`). */
+export function cleanPackage(repoRoot: string, outDir?: string): void {
+  const root = outDir ?? defaultPackageRoot(repoRoot);
+  for (const dir of PAYLOAD_DIRS) {
+    rmSync(join(root, dir), { recursive: true, force: true });
+  }
 }
 
-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);
+function parseArg(argv: readonly string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  if (index === -1) return undefined;
+  return argv[index + 1];
 }
 
 const USAGE = [
-  "Usage: bun plugins/soleur/scripts/sync-npm-package.ts [--repo-root DIR] [--check] [--help]",
+  "Usage: bun plugins/soleur/scripts/sync-npm-package.ts [--repo-root DIR] [--out-dir DIR] [--check] [--clean] [--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",
+  "  --out-dir DIR    package root to materialize/check (default: <repo-root>/packages/opencode-plugin)",
+  "  --check          compare the materialized package against a fresh walk; write nothing",
+  "  --clean          remove generated payload directories from the package root",
   "  --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"]);
+  const withValue = new Set(["--repo-root", "--out-dir"]);
+  const known = new Set([...withValue, "--check", "--clean", "--help", "-h"]);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -159,15 +133,28 @@ function validateArgs(argv: readonly string[]): void {
       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);
-  const root = repoRoot(argv);
-  const problems = argv.includes("--check") ? packageProblems(root) : writePackage(root);
+  const root = resolve(parseArg(argv, "--repo-root") ?? resolve(CANONICAL_ROOT, "..", ".."));
+  const explicitOut = parseArg(argv, "--out-dir");
+  const outDir = explicitOut !== undefined ? resolve(explicitOut) : undefined;
+  if (argv.includes("--clean")) {
+    cleanPackage(root, outDir);
+    return;
+  }
+  const problems = argv.includes("--check") ? packageProblems(root, outDir) : writePackage(root, outDir);
   if (problems.length > 0) {
     for (const problem of problems) console.error(problem);
     process.exit(1);

package/scripts/sync-opencode-adapter.ts

@@ -302,6 +302,25 @@ function instructions(): string {
     "JavaScript rather than a command and are not decided by the Bash guards — a limitation this",
     "harness shares with the guard scripts' own input contract.",
     "",
+    "**One canonical gate is absent here, and its consequence is a refusal you cannot talk around.**",
+    "`hooks/operator-stage-approval.sh` is what mints the digest-bound approval receipt a staged",
+    "`--apply` consumes, and no OpenCode surface can both rewrite the command and ask in the same",
+    "decision (ADR-264). So `plugins/soleur/scripts/lib/operator-script.sh`'s `soleur_op_stage_gate`",
+    "finds no receipt and exits **75** (`SOLEUR_BOOTSTRAP_APPROVAL_REQUIRED`). The typed-`yes`",
+    "fallback is gated on `-t 0`/`-t 1` **and** `soleur_op_in_agent_harness`, which recognises only",
+    "`CLAUDECODE`/`CLAUDE_CODE_ENTRYPOINT` — neither is set under OpenCode — so that arm is open",
+    "here whenever the spawned shell has a tty, and a terminal confirmation from an agent is not",
+    "evidence of a person. **No receipt can be minted on this harness**, so a staged `--apply`",
+    "refuses rather than approving. Nothing is approved silently.",
+    "",
+    "A degraded hook decision — a shell call whose `workdir` could not be correlated, or a runtime",
+    "with no `tool.execute.before` surface — is announced on stderr **and** written to the event log",
+    "when `SOLEUR_OPENCODE_EVENT_LOG` names a file (its parent directory must exist; unset means no",
+    "log). Whether your terminal surfaces plugin stderr is not something this adapter measured, so",
+    "arm the log when you need certainty. A `shell` call whose `workdir` cannot be used is",
+    "**prompted** rather than run unchecked — the guards still run, against the session directory,",
+    "and only their declining becomes the prompt.",
+    "",
     "The post-compaction re-read is **armed, not guaranteed**, unlike Codex and Devin:",
     "`ctx.session.hook(\"compaction\")` sets state and the next `ctx.session.hook(\"context\")`",
     "re-injects the rule corpus plus the re-read directive. §12.3 captured that `context` fire",