@ctxr/skill-llm-wiki 1.0.2 → 1.2.0

package/scripts/lib/intent.mjs

@@ -33,6 +33,16 @@
 //   INT-12   ambiguity reached interactive resolution in a non-TTY
 //            context (emitted by cli.mjs when NonInteractiveError fires)
 //   INT-13   unknown --quality-mode value
+//   INT-14   invalid --fanout-target value (must be a positive integer
+//            in [FANOUT_TARGET_MIN, FANOUT_TARGET_MAX])
+//   INT-14a  --fanout-target used on a subcommand other than build /
+//            rebuild (balance enforcement is build/rebuild-only)
+//   INT-15   invalid --max-depth value (must be a positive integer in
+//            [MAX_DEPTH_MIN, MAX_DEPTH_MAX])
+//   INT-15a  --max-depth used on a subcommand other than build /
+//            rebuild (balance enforcement is build/rebuild-only)
+//   INT-16a  --soft-dag-parents used on a subcommand other than build /
+//            rebuild (soft-DAG synthesis is build/rebuild-only)
 //
 // Plan shape (status === "ok"):
 //   {
@@ -50,7 +60,11 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  DEFAULT_COLLISION_POLICY,
+  VALID_COLLISION_POLICIES,
+} from "./join-constants.mjs";
 import {
   defaultSiblingPath,
   hasPrivateGit,
@@ -64,14 +78,53 @@ export const VALID_LAYOUT_MODES = Object.freeze(["sibling", "in-place", "hosted"
 // rejects typos BEFORE the orchestrator runs, avoiding expensive
 // rollbacks on a trivial flag error. Must stay in sync with
 // tiered.mjs:QUALITY_MODES — the unit test
-// tests/unit/intent-resolve.test.mjs:valid-quality-modes verifies
-// this.
+// tests/unit/intent-resolve.test.mjs::"VALID_QUALITY_MODES is in
+// sync with tiered.mjs::QUALITY_MODES" pins that both lists contain
+// the same modes in the same order so a future drift fails loud
+// instead of silently letting one layer accept a mode the other
+// rejects.
 export const VALID_QUALITY_MODES = Object.freeze([
   "tiered-fast",
   "claude-first",
-  "tier0-only",
+  "deterministic",
 ]);
 
+// Range bounds for the balance-enforcement flags (`--fanout-target`,
+// `--max-depth`). Exported so tests and the balance module can
+// reference them directly without re-stating the literal values.
+//
+// The ranges cover the band where a post-convergence rebalance pass
+// has a meaningful effect. Fanout 1 is degenerate (every split forces
+// single-child chains); 100+ is effectively unbounded for any real
+// corpus (the cluster detector caps individual clusters at 8).
+// Max depth starts at 1 — the "no nesting"/flat-layout case is out
+// of this flag's scope; balance's purpose is to flatten OVERDEEP
+// branches, not to undo nesting the pipeline already decided to
+// create, and the regular NEST operator handles the no-nesting
+// starting condition anyway. 11+ max-depth is deeper than any
+// hand-authored corpus anyone has reported, so the flag becomes a
+// silent no-op above that. Out-of-range values are treated as user
+// errors at intent time so the flag is never a silent no-op at
+// runtime.
+export const FANOUT_TARGET_MIN = 2;
+export const FANOUT_TARGET_MAX = 100;
+export const MAX_DEPTH_MIN = 1;
+export const MAX_DEPTH_MAX = 10;
+
+// Parse + validate an integer-in-range flag value. Returns a short
+// human-readable reason string when the value is invalid (for use in
+// the ambiguity error), or null when valid. Factored out so INT-14
+// and INT-15 share one implementation.
+function invalidIntInRange(raw, min, max) {
+  if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+    return `expected a positive integer, got "${raw}"`;
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < min) return `${n} is below the minimum ${min}`;
+  if (n > max) return `${n} is above the maximum ${max}`;
+  return null;
+}
+
 export function ok(plan) {
   return { status: "ok", plan };
 }
@@ -265,6 +318,153 @@ export function resolveIntent(ctx) {
       "--quality-mode",
     );
   }
+  // Validate `LLM_WIKI_QUALITY_MODE` here too, but only for
+  // subcommands that actually consult runtime quality-mode
+  // resolution (build / extend / rebuild / fix / join all call
+  // through `resolveQualityMode` in the orchestrator). Commands
+  // like `rollback`, `validate`, `init`, `heal` never touch
+  // tiered.mjs, so blocking them on a stale env var — especially
+  // `rollback`, which is a recovery path — would make a trivial
+  // shell-config typo catastrophic. Without this gate, a stale
+  // `LLM_WIKI_QUALITY_MODE=tier0-only` would lock the user out of
+  // recovering the wiki they were trying to rollback.
+  //
+  // Symmetric with the flag path — same code, same suggestions,
+  // same exit-2 ambiguous shape — for the subcommands where the
+  // env var is actually consumed.
+  const QUALITY_MODE_CONSUMERS = new Set([
+    "build",
+    "extend",
+    "rebuild",
+    "fix",
+    "join",
+  ]);
+  const envQualityMode = process.env.LLM_WIKI_QUALITY_MODE;
+  if (
+    QUALITY_MODE_CONSUMERS.has(subcommand) &&
+    !f.quality_mode &&
+    envQualityMode &&
+    !VALID_QUALITY_MODES.includes(envQualityMode)
+  ) {
+    return ambiguous(
+      "INT-13",
+      `unknown LLM_WIKI_QUALITY_MODE value "${envQualityMode}"`,
+      VALID_QUALITY_MODES.map((m) => ({
+        description: `use ${m} quality mode`,
+        flag: `--quality-mode ${m}`,
+      })),
+      "LLM_WIKI_QUALITY_MODE",
+    );
+  }
+  // Balance-enforcement flags are build/rebuild-only. The CLI parser
+  // accepts them globally (to produce a uniform flag table), so intent
+  // has to gate the subcommand explicitly — otherwise `fix`, `join`,
+  // `rollback` etc. would silently carry them through to the
+  // orchestrator, where the hook would fire and apply unexpected
+  // structural mutations outside the documented surface.
+  const BALANCE_FLAG_SUBCOMMANDS = new Set(["build", "rebuild"]);
+  // Subcommands that operate on an existing wiki (take a wiki path).
+  // For these, the natural remediation is `rebuild` (which walks an
+  // existing wiki). For source-operating subcommands with no wiki
+  // path, `build` is the right suggestion. `build` itself isn't in
+  // either set since it can't reach this branch.
+  const WIKI_OPERATING = new Set(["fix", "validate", "extend", "rebuild", "rollback", "join"]);
+  const suggestedSub = WIKI_OPERATING.has(subcommand) ? "rebuild" : "build";
+  if (f.fanout_target !== undefined) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-14a",
+        `--fanout-target is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --fanout-target",
+            flag: "(remove --fanout-target)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --fanout-target <N>`,
+          },
+        ],
+        "--fanout-target",
+      );
+    }
+    const bad = invalidIntInRange(
+      f.fanout_target,
+      FANOUT_TARGET_MIN,
+      FANOUT_TARGET_MAX,
+    );
+    if (bad) {
+      return ambiguous(
+        "INT-14",
+        `invalid --fanout-target "${f.fanout_target}" (${bad})`,
+        [
+          {
+            description: `use a positive integer in [${FANOUT_TARGET_MIN}, ${FANOUT_TARGET_MAX}]`,
+            flag: "--fanout-target <integer>",
+          },
+        ],
+        "--fanout-target",
+      );
+    }
+  }
+  if (f.max_depth !== undefined) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-15a",
+        `--max-depth is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --max-depth",
+            flag: "(remove --max-depth)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --max-depth <D>`,
+          },
+        ],
+        "--max-depth",
+      );
+    }
+    const bad = invalidIntInRange(f.max_depth, MAX_DEPTH_MIN, MAX_DEPTH_MAX);
+    if (bad) {
+      return ambiguous(
+        "INT-15",
+        `invalid --max-depth "${f.max_depth}" (${bad})`,
+        [
+          {
+            description: `use a positive integer in [${MAX_DEPTH_MIN}, ${MAX_DEPTH_MAX}]`,
+            flag: "--max-depth <integer>",
+          },
+        ],
+        "--max-depth",
+      );
+    }
+  }
+  // --soft-dag-parents shares balance's subcommand scope (build /
+  // rebuild only). Same defense-in-depth as INT-14a / INT-15a: the
+  // CLI parser accepts the flag globally, so intent has to gate
+  // explicitly — otherwise `fix`, `join`, `rollback` etc. would
+  // silently carry the flag through to the orchestrator and rewrite
+  // parents[] on every leaf, outside the documented surface.
+  if (f.soft_dag_parents === true) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-16a",
+        `--soft-dag-parents is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --soft-dag-parents",
+            flag: "(remove --soft-dag-parents)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --soft-dag-parents`,
+          },
+        ],
+        "--soft-dag-parents",
+      );
+    }
+  }
   if (f.layout_mode === "in-place" && f.target) {
     return ambiguous(
       "INT-09a",
@@ -324,6 +524,172 @@ export function resolveIntent(ctx) {
     });
   }
 
+  // ─── Join: N >= 2 existing wikis into a unified output ───────────
+  //
+  // Positional shape: `join <wiki-a> <wiki-b> [<wiki-c>...]`. The
+  // `--target` flag is REQUIRED (where to write the unified output)
+  // — join is inherently hosted-mode because the output belongs
+  // neither next to source A nor source B. Each source must exist
+  // and be a skill-managed wiki (have `.llmwiki/git`). Target must
+  // not already exist (or must be empty): the CLI materialises into
+  // a fresh tree so the source wikis stay strictly read-only.
+  //
+  // `--id-collision` selects the cross-source id-collision policy
+  // (`namespace` / `merge` / `ask`); defaults to `namespace`. The
+  // value is validated here against the same canonical list
+  // scripts/lib/join.mjs exports, so a typo fails at the intent
+  // layer with structured INT-17 rather than burning a pre-op
+  // snapshot and rolling back.
+  if (subcommand === "join") {
+    if (args.length < 2) {
+      return ambiguous(
+        "INT-06",
+        `join requires at least 2 <wiki-path> positionals (got ${args.length})`,
+        [
+          {
+            description: "specify two or more source wikis",
+            flag: "join <wiki-a> <wiki-b> [<wiki-c>...]",
+          },
+        ],
+        "positional wiki paths",
+      );
+    }
+    const sources = args.map((a) => absolute(cwd, a));
+    for (const s of sources) {
+      if (!existsSync(s)) {
+        return ambiguous(
+          "INT-06",
+          `join: source wiki ${s} does not exist`,
+          [
+            {
+              description: "point at an existing skill-managed wiki",
+              flag: `join <existing-wiki> <existing-wiki>`,
+            },
+          ],
+          "each positional must exist",
+        );
+      }
+      if (!hasPrivateGit(s)) {
+        return ambiguous(
+          "INT-06",
+          `join: ${s} is not a skill-managed wiki (no .llmwiki/git)`,
+          [
+            {
+              description: "build each source first",
+              flag: `build ${s} --layout-mode in-place`,
+            },
+          ],
+          "each source must be a managed wiki",
+        );
+      }
+    }
+    if (!f.target) {
+      return ambiguous(
+        "INT-09b",
+        `join requires --target <path> (join output is always hosted; see guide/operations/ingest/join.md)`,
+        [
+          {
+            description: "set an explicit output path",
+            flag: "--target <path/for/unified/wiki>",
+          },
+        ],
+        "--target",
+      );
+    }
+    const target = absolute(cwd, f.target);
+    // Source immutability guard: --target must not equal, nest
+    // under, or contain any source wiki. Join writes to target;
+    // any path relationship between target and a source means the
+    // write would either clobber source files or place output
+    // inside the source tree (violating the documented "sources
+    // are read-only" guarantee). Detect both subpath directions
+    // with `path.relative` and reject with INT-18 before the
+    // pre-op snapshot fires. This check runs BEFORE the
+    // empty-target check — a target that equals or contains a
+    // source would otherwise be (correctly) flagged as non-empty
+    // under INT-01, masking the more specific semantic problem.
+    for (const s of sources) {
+      const relTargetFromSource = relative(s, target);
+      const relSourceFromTarget = relative(target, s);
+      const targetUnderSource =
+        relTargetFromSource === "" ||
+        (!relTargetFromSource.startsWith("..") &&
+          !isAbsolute(relTargetFromSource));
+      const sourceUnderTarget =
+        relSourceFromTarget !== "" &&
+        !relSourceFromTarget.startsWith("..") &&
+        !isAbsolute(relSourceFromTarget);
+      if (targetUnderSource || sourceUnderTarget) {
+        return ambiguous(
+          "INT-18",
+          `join: --target ${target} must not equal, nest under, or contain any source wiki (conflicts with ${s})`,
+          [
+            {
+              description:
+                "pick a target path outside every source wiki tree",
+              flag: "--target <path-outside-sources>",
+            },
+          ],
+          "--target must not overlap sources",
+        );
+      }
+    }
+    if (existsSync(target)) {
+      // Allow an empty directory but nothing else — the target must
+      // be safe to materialise into without clobbering user data.
+      let entries;
+      try {
+        entries = readdirSync(target);
+      } catch {
+        entries = null;
+      }
+      if (!entries || entries.length > 0) {
+        return ambiguous(
+          "INT-01",
+          `join: --target path ${target} already exists and is not empty`,
+          [
+            {
+              description: "pick a fresh output path",
+              flag: "--target <new-path>",
+            },
+          ],
+          "--target must be empty or new",
+        );
+      }
+    }
+    // Share VALID_COLLISION_POLICIES with `join.mjs` — the single
+    // canonical list. A local copy here risked silent drift if the
+    // set gained or lost a policy; importing keeps the intent
+    // validator and the runtime in lockstep.
+    const policy = f.id_collision || DEFAULT_COLLISION_POLICY;
+    if (!VALID_COLLISION_POLICIES.includes(policy)) {
+      return ambiguous(
+        "INT-17",
+        `unknown --id-collision value "${policy}"`,
+        VALID_COLLISION_POLICIES.map((p) => ({
+          description: `use ${p} policy`,
+          flag: `--id-collision ${p}`,
+        })),
+        "--id-collision",
+      );
+    }
+    return ok({
+      operation: "join",
+      layout_mode: "hosted",
+      source: null,
+      sources,
+      target,
+      is_new_wiki: true,
+      flags: {
+        accept_dirty: f.accept_dirty === true,
+        no_prompt: f.no_prompt === true,
+        json_errors: f.json_errors === true || f.json === true,
+        id_collision: policy,
+        quality_mode: f.quality_mode,
+      },
+    });
+  }
+
   // ─── Rebuild / fix: the positional IS the wiki, not a source ──────
   // These operations read frontmatter from an existing wiki and write
   // back in place. There is no separate source — the wiki is both.

package/scripts/lib/join-constants.mjs

@@ -0,0 +1,22 @@
+// join-constants.mjs — the minimal shared constants between the
+// runtime pipeline (`join.mjs`) and the intent layer
+// (`intent.mjs`).
+//
+// Kept in its own file so that importing the policy allow-list
+// at intent time does NOT drag in the full join pipeline module
+// (ingest + convergence + indices + validation + every transitive
+// dependency). CLI paths that never run a join — build, rebuild,
+// fix, validate, rollback, init, heal, where — would otherwise
+// pay the cold-start cost of loading `join.mjs` and its
+// dependency graph on every invocation just to resolve the
+// `--id-collision` flag. Keeping this module dependency-light
+// (zero imports, plain string constants) keeps every non-join
+// CLI startup path fast.
+
+export const VALID_COLLISION_POLICIES = Object.freeze([
+  "namespace",
+  "merge",
+  "ask",
+]);
+
+export const DEFAULT_COLLISION_POLICY = "namespace";