@ctxr/skill-llm-wiki 1.0.1

package/scripts/commands/remote.mjs

@@ -0,0 +1,93 @@
+// remote.mjs — `skill-llm-wiki remote <wiki> <subcommand> [args]`
+//
+// Thin wrapper around git's remote management, routed through the
+// private repo's isolation env. Subcommands:
+//
+//   add <name> <url>    register a new remote
+//   remove <name>       delete a configured remote
+//   list                list all remotes with (fetch, push) URLs
+//
+// The skill never talks to a remote on its own. `remote add` just
+// records the URL in the private repo's config; nothing is fetched,
+// pushed, or authenticated here. The user invokes `skill-llm-wiki
+// sync <wiki>` explicitly to actually exchange objects with the
+// remote.
+//
+// All operations fail loudly on collision, missing args, or git
+// errors — there is no silent "remote already exists, overwrite"
+// behavior. If a caller needs idempotent add-or-replace they do
+// `remove` then `add`.
+
+import {
+  gitRemoteAdd,
+  gitRemoteList,
+  gitRemoteRemove,
+  redactUrl,
+} from "../lib/git.mjs";
+
+const REMOTE_SUBCOMMANDS = new Set(["add", "remove", "list"]);
+
+export function cmdRemote(wikiRoot, { subcommand, args = [] }) {
+  if (!wikiRoot) {
+    process.stderr.write("remote: <wiki> is required\n");
+    return 1;
+  }
+  if (!subcommand || !REMOTE_SUBCOMMANDS.has(subcommand)) {
+    process.stderr.write(
+      `remote: subcommand must be one of ${[...REMOTE_SUBCOMMANDS].join(", ")}; got "${subcommand}"\n`,
+    );
+    return 1;
+  }
+  try {
+    switch (subcommand) {
+      case "add": {
+        const [name, url] = args;
+        // Defence in depth: reject whitespace-only or empty after
+        // trim so we never hand garbage to git.
+        if (!name || !name.trim() || !url || !url.trim()) {
+          process.stderr.write(
+            "remote add: <name> <url> are both required and non-empty\n",
+          );
+          return 1;
+        }
+        gitRemoteAdd(wikiRoot, name.trim(), url.trim());
+        // Always redact the URL before echoing — https URLs with
+        // embedded credentials like `https://token@host/repo.git`
+        // are common and must never surface on stdout.
+        process.stdout.write(
+          `remote ${name.trim()} added (${redactUrl(url.trim())})\n`,
+        );
+        return 0;
+      }
+      case "remove": {
+        const [name] = args;
+        if (!name) {
+          process.stderr.write("remote remove: <name> is required\n");
+          return 1;
+        }
+        gitRemoteRemove(wikiRoot, name);
+        process.stdout.write(`remote ${name} removed\n`);
+        return 0;
+      }
+      case "list": {
+        const remotes = gitRemoteList(wikiRoot);
+        if (remotes.length === 0) {
+          process.stdout.write("(no remotes configured)\n");
+          return 0;
+        }
+        for (const r of remotes) {
+          process.stdout.write(
+            `${r.name}\n` +
+              `  fetch: ${redactUrl(r.fetch ?? "(none)")}\n` +
+              `  push:  ${redactUrl(r.push ?? "(none)")}\n`,
+          );
+        }
+        return 0;
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`remote ${subcommand}: ${err.message}\n`);
+    return 1;
+  }
+  return 0;
+}

package/scripts/commands/review.mjs

@@ -0,0 +1,253 @@
+// review.mjs — `skill-llm-wiki rebuild <wiki> --review`
+//
+// After the orchestrator's operator-convergence phase produces its
+// per-iteration commits but before validation + commit-finalize
+// run, the review flow:
+//
+//   1. Reads `git diff --stat pre-op/<id>..HEAD` and prints the
+//      file-level summary of what the operators touched.
+//   2. Reads `git log --oneline pre-op/<id>..HEAD` and prints the
+//      per-iteration commit list.
+//   3. Prompts the user: approve / abort / drop <iteration-N>.
+//
+// Approve: orchestrator proceeds to validation + commit-finalize
+//          as normal.
+// Abort:   `git reset --hard pre-op/<id>` + `git clean -fd`, roll
+//          everything back, exit with code 2 so the caller knows
+//          the op didn't land.
+// Drop N:  `git revert --no-edit <sha-of-iteration-N>` produces an
+//          inverse commit for iteration N directly in git history,
+//          then the loop re-prompts so the user can drop more
+//          iterations one at a time. The final outcome is
+//          `"approve"` with a populated `dropped[]` array; the
+//          revert commits are already in history by the time the
+//          orchestrator sees the result.
+//
+// The prompt is gated on `isInteractive()`. In non-interactive
+// mode the review flow is a no-op that returns immediately, and
+// the orchestrator proceeds as if `--review` hadn't been passed.
+
+import {
+  gitClean,
+  gitResetHard,
+  gitRun,
+  gitRunChecked,
+} from "../lib/git.mjs";
+import { choose, isInteractive, NonInteractiveError } from "../lib/interactive.mjs";
+
+export const REVIEW_APPROVE = "approve";
+export const REVIEW_ABORT = "abort";
+export const REVIEW_DROP = "drop";
+
+// Pure logic: given the current commit list between pre-tag and HEAD,
+// and the user's choice, produce an action record. Exported so tests
+// can drive every branch without spawning git.
+export function planReviewAction(choice, pendingCommits) {
+  if (choice === REVIEW_APPROVE) {
+    return { action: "approve" };
+  }
+  if (choice === REVIEW_ABORT) {
+    return { action: "abort" };
+  }
+  if (typeof choice === "string" && choice.startsWith("drop:")) {
+    const rest = choice.slice("drop:".length).trim();
+    if (rest === "") {
+      return {
+        action: "error",
+        error:
+          "drop: commit identifier missing (use drop:<sha> or drop:<subject-substring>)",
+      };
+    }
+    // Exact sha match always wins, even when an earlier commit's
+    // subject happens to contain the sha prefix as a substring.
+    const exact = pendingCommits.find((c) => c.sha === rest);
+    if (exact) {
+      return { action: "drop", commit: exact };
+    }
+    const matches = pendingCommits.filter((c) => c.subject.includes(rest));
+    if (matches.length === 0) {
+      return { action: "error", error: `no commit matches "${rest}"` };
+    }
+    if (matches.length > 1) {
+      const shas = matches.map((c) => c.sha.slice(0, 10)).join(", ");
+      return {
+        action: "error",
+        error: `ambiguous drop: "${rest}" matches ${matches.length} commits (${shas}) — use a full sha`,
+      };
+    }
+    return { action: "drop", commit: matches[0] };
+  }
+  return { action: "error", error: `unknown review choice: ${choice}` };
+}
+
+// Read the commit list between `pre-op/<opId>` and HEAD as an array
+// of { sha, subject } records. Used by the review prompt and tests.
+export function readPendingCommits(wikiRoot, opId) {
+  const r = gitRun(wikiRoot, [
+    "log",
+    "--oneline",
+    "--no-decorate",
+    "--format=%H\t%s",
+    `pre-op/${opId}..HEAD`,
+  ]);
+  if (r.status !== 0) {
+    throw new Error(
+      `review: git log pre-op/${opId}..HEAD exited ${r.status}: ${r.stderr.trim()}`,
+    );
+  }
+  const lines = r.stdout.trim().split(/\r?\n/).filter((l) => l.length > 0);
+  return lines.map((l) => {
+    const [sha, ...rest] = l.split("\t");
+    return { sha, subject: rest.join("\t") };
+  });
+}
+
+// Print the stat + commit list to stdout. Tests capture stdout to
+// verify the output shape.
+export function printReviewSummary(wikiRoot, opId) {
+  process.stdout.write(
+    `\n=== Review pending changes for op ${opId} ===\n\n`,
+  );
+  const diff = gitRun(wikiRoot, [
+    "diff",
+    "--stat",
+    "--find-renames",
+    `pre-op/${opId}..HEAD`,
+  ]);
+  process.stdout.write(diff.stdout || "(no diff)\n");
+  process.stdout.write("\nCommits (oldest first):\n");
+  const commits = readPendingCommits(wikiRoot, opId).reverse();
+  for (let i = 0; i < commits.length; i++) {
+    process.stdout.write(
+      `  ${i + 1}. ${commits[i].sha.slice(0, 10)}  ${commits[i].subject}\n`,
+    );
+  }
+  process.stdout.write("\n");
+  return commits;
+}
+
+// Interactive prompt that returns one of REVIEW_APPROVE /
+// REVIEW_ABORT / `drop:<n>`. Uses `choose()` from interactive.mjs
+// so non-TTY mode throws NonInteractiveError that the caller
+// translates into a pass-through (just approve the op).
+export async function promptReviewChoice(commits, opts = {}) {
+  if (!isInteractive(opts)) {
+    throw new NonInteractiveError("review: non-interactive");
+  }
+  const options = [
+    { label: "approve — proceed to validation + commit-finalize", value: REVIEW_APPROVE },
+    { label: "abort    — roll back to pre-op state", value: REVIEW_ABORT },
+  ];
+  for (let i = 0; i < commits.length; i++) {
+    options.push({
+      label: `drop ${i + 1} (${commits[i].subject})`,
+      value: `drop:${commits[i].sha}`,
+    });
+  }
+  return choose("What would you like to do with this review?", options, opts);
+}
+
+// Apply an abort: reset working tree to pre-op.
+export function applyAbort(wikiRoot, opId) {
+  gitResetHard(wikiRoot, `pre-op/${opId}`);
+  gitClean(wikiRoot);
+}
+
+// Apply a drop: `git revert --no-edit <sha>` to produce an inverse
+// commit for the dropped iteration. On a clean revert, returns
+// `{ ok: true }`. On conflict (common for non-adjacent commits
+// that touch the same files), calls `git revert --abort` to clean
+// up the working tree and returns `{ ok: false, conflict: true,
+// stderr }` so the review loop can re-prompt without leaving merge
+// markers on disk. Throws only for true errors — the conflict
+// path is normal and recoverable.
+export function applyDrop(wikiRoot, commit) {
+  const r = gitRun(wikiRoot, ["revert", "--no-edit", commit.sha]);
+  if (r.status === 0) {
+    return { ok: true };
+  }
+  // Non-zero exit is typically a conflict. Abort the in-progress
+  // revert so the working tree is consistent, then report.
+  try {
+    gitRunChecked(wikiRoot, ["revert", "--abort"]);
+  } catch {
+    /* best effort; caller will reset on full abort */
+  }
+  return { ok: false, conflict: true, stderr: r.stderr.trim() };
+}
+
+// Full review cycle: print summary, prompt, apply. Loops until the
+// user approves, aborts, or hits an error — so the user can drop
+// multiple iterations one at a time. Each drop produces a revert
+// commit and re-prints the updated summary before re-prompting.
+//
+// Returns one of:
+//   { outcome: "approve" }
+//   { outcome: "abort" }
+//   { outcome: "dropped", commits: [...] }   ← all dropped commits
+//   { outcome: "non-interactive" }
+//
+// Tests may inject a `promptFn` seam to avoid a real TTY. For
+// multi-drop scenarios the injected promptFn is called once per
+// iteration of the loop and returns the next user decision.
+export async function runReviewCycle(wikiRoot, opId, opts = {}) {
+  const {
+    promptFn = promptReviewChoice,
+    forceInteractive = false,
+    maxIterations = 32,
+  } = opts;
+  // `isInteractive` already honours `forceInteractive` — pulling
+  // that check out separately is dead code.
+  if (!isInteractive({ forceInteractive })) {
+    return { outcome: "non-interactive" };
+  }
+  const dropped = [];
+  for (let iter = 0; iter < maxIterations; iter++) {
+    const commits = printReviewSummary(wikiRoot, opId);
+    if (commits.length === 0) {
+      process.stdout.write("(no pending commits to review — approving)\n");
+      return { outcome: "approve" };
+    }
+    let choice;
+    try {
+      choice = await promptFn(commits, { forceInteractive });
+    } catch (err) {
+      if (err instanceof NonInteractiveError) {
+        return { outcome: "non-interactive" };
+      }
+      throw err;
+    }
+    const plan = planReviewAction(choice, commits);
+    switch (plan.action) {
+      case "approve":
+        return dropped.length > 0
+          ? { outcome: "approve", dropped }
+          : { outcome: "approve" };
+      case "abort":
+        applyAbort(wikiRoot, opId);
+        return { outcome: "abort" };
+      case "drop": {
+        const dropResult = applyDrop(wikiRoot, plan.commit);
+        if (dropResult.conflict) {
+          // Clean abort of the in-progress revert so the working
+          // tree is consistent before we re-prompt.
+          process.stderr.write(
+            `review: drop of ${plan.commit.sha.slice(0, 10)} conflicts with later commits ` +
+              "(git revert aborted). Pick a different iteration, " +
+              "approve to keep everything, or abort to roll back.\n",
+          );
+          continue;
+        }
+        dropped.push(plan.commit);
+        continue;
+      }
+      case "error":
+      default:
+        process.stderr.write(`review: ${plan.error}\n`);
+        continue;
+    }
+  }
+  throw new Error(
+    `review: exceeded maxIterations=${maxIterations} without reaching approve/abort`,
+  );
+}

package/scripts/commands/sync.mjs

@@ -0,0 +1,84 @@
+// sync.mjs — `skill-llm-wiki sync <wiki> [--remote <name>]
+//                                          [--push-branch <ref>]`
+//
+// Explicit, user-invoked object exchange with a configured remote.
+// Fetches tags from the remote first (read side), then pushes the
+// private repo's `op/*` and `pre-op/*` tags (write side). Nothing is
+// ever pushed automatically — `sync` is always a conscious user
+// action and the only way to propagate history to a shared location.
+//
+// By default the push refspec is `refs/tags/op/*` + `refs/tags/
+// pre-op/*`, so the remote receives a read-only history mirror
+// without any competing `main` branch head. A user who genuinely
+// wants to push a branch passes `--push-branch <name>` and takes
+// responsibility for that refspec.
+
+import { gitFetch, gitPush, gitRemoteList } from "../lib/git.mjs";
+
+// A branch name that `git` and our refspec interpolation will accept
+// without surprise. Refs containing `:`, `+`, `*`, or leading `-` can
+// change push semantics (force-push, refspec patterns, flag smuggling),
+// so we refuse them at the gate. Matches the conservative subset of
+// `git check-ref-format`'s rules that we care about. Phase 8 security
+// sweep finding D7.
+const SAFE_BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+
+export function cmdSync(wikiRoot, opts = {}) {
+  const { remote = "origin", pushBranch = null, skipFetch = false, skipPush = false } = opts;
+  if (!wikiRoot) {
+    process.stderr.write("sync: <wiki> is required\n");
+    return 1;
+  }
+  if (pushBranch !== null && !SAFE_BRANCH_RE.test(pushBranch)) {
+    process.stderr.write(
+      `sync: invalid --push-branch "${pushBranch}" — branch must match ` +
+        `[A-Za-z0-9][A-Za-z0-9._/-]*; refusing to build an unsafe refspec.\n`,
+    );
+    return 1;
+  }
+  // Verify the remote exists before we start. A typo or missing
+  // remote should be a loud "unknown remote" error, not a
+  // surprising git fatal from deep in the fetch path.
+  let remotes;
+  try {
+    remotes = gitRemoteList(wikiRoot);
+  } catch (err) {
+    process.stderr.write(`sync: could not list remotes: ${err.message}\n`);
+    return 1;
+  }
+  const known = new Set(remotes.map((r) => r.name));
+  if (!known.has(remote)) {
+    process.stderr.write(
+      `sync: unknown remote "${remote}" (configured: ${[...known].join(", ") || "none"})\n` +
+        "  add one first: skill-llm-wiki remote <wiki> add <name> <url>\n",
+    );
+    return 1;
+  }
+
+  if (!skipFetch) {
+    try {
+      gitFetch(wikiRoot, remote);
+      process.stdout.write(`sync: fetched from ${remote}\n`);
+    } catch (err) {
+      process.stderr.write(`sync: fetch failed: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  if (!skipPush) {
+    const refspecs = pushBranch
+      ? ["refs/tags/op/*", "refs/tags/pre-op/*", `refs/heads/${pushBranch}`]
+      : ["refs/tags/op/*", "refs/tags/pre-op/*"];
+    try {
+      gitPush(wikiRoot, remote, { refspecs });
+      process.stdout.write(
+        `sync: pushed ${refspecs.join(", ")} to ${remote}\n`,
+      );
+    } catch (err) {
+      process.stderr.write(`sync: push failed: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  return 0;
+}