@awebai/oats 0.24.13 → 0.25.1

package/lib/operator-dispatch.mjs

@@ -0,0 +1,117 @@
+/** Operator-level capability commands — `oats <ns> <cmd>` run from a DEPLOYMENT
+ *  directory (one holding `oats-local.yaml`), not from an instance home.
+ *
+ *  Contract (docs/design/2026-09-23-workspace-module-contracts.md, "Post-0.25.0
+ *  clarifications"): resolve exactly as `oats spawn --soul <name>` would —
+ *  `prepareInstance(dir, soul)` → the soul's Resolution — find the module whose
+ *  manifest `command` is the namespace, fetch that capability into the
+ *  deployment's per-commit module store `<deployment>/.oats/modules/<cap>@<commit12>/`
+ *  (the same store capability-defined agents use; see
+ *  lib/instance-resolution.mjs#resolvePackageCapabilityAgent) and dispatch to that
+ *  copy with the soul's merged payload as `OATS_SETTINGS`.
+ *
+ *  Never "the newest instance's copy" (an instance is not an authority for the
+ *  deployment) and never an unlocked cache read: trust is exactly spawn's —
+ *  members by membership, packages by the lock's approval (`prepareInstance`
+ *  already refuses E_PACKAGE_UNAPPROVED). A module in the Resolution IS active.
+ *
+ *  `--soul` is required: without a soul there is no Resolution to answer from
+ *  (E_BAD_ARGS naming --soul). Nothing here reads oats-config.yaml. */
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { randomBytes } from "node:crypto";
+import { oatsError } from "./errors.mjs";
+import { loadLocal } from "./workspace.mjs";
+import { packageRef, refForKey } from "./resolve.mjs";
+import { MODULES_DIR } from "./materialize.mjs";
+import * as defaultRemote from "./remote.mjs";
+import { prepareInstance } from "./instance-resolution.mjs";
+
+function err(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
+
+/** Is `dir` (or an ancestor) a v2 deployment? → the loadLocal result or null when
+ *  no oats-local.yaml is in reach (the caller then falls back to the classic chain).
+ *  Any OTHER failure (a malformed oats-local.yaml → E_WORKSPACE_SCHEMA) propagates. */
+export function deploymentOf(dir) {
+  try { return loadLocal(dir); }
+  catch (e) { if (e?.code === "E_LOCAL_MISSING") return null; throw e; }
+}
+
+/** The repo ref a module's tree is fetched from, spelled as lib/remote.mjs accepts it:
+ *  member → the member repoKey (`local/<abs>` → the abs path, else `git:<key>`);
+ *  package → packageRef over the lock entry (catalog url or git source). */
+export function moduleRef(module, lock, { catalog = null, remote = defaultRemote } = {}) {
+  const from = module?.from;
+  if (!from || typeof from !== "object") throw err("E_CAPABILITY_BROKEN", `module ${module?.name ?? "?"}: resolution carries no provenance`, { module: module?.name ?? null });
+  if (from.kind === "member") return refForKey(from.repoKey);
+  if (from.kind === "package") {
+    const entry = lock?.packages?.[from.package];
+    if (!entry || typeof entry !== "object") throw err("E_PACKAGE_MISSING", `module ${module.name}: package ${from.package} is not in the deployment's lock`, { module: module.name, id: from.package });
+    return packageRef(from.package, entry, catalog, remote);
+  }
+  throw err("E_CAPABILITY_BROKEN", `module ${module.name}: unknown provenance kind ${JSON.stringify(from.kind)}`, { module: module.name, kind: from.kind ?? null });
+}
+
+/** `<deployment>/.oats/modules/<cap>@<commit12>` — the per-commit store path of a module. */
+export function moduleStoreDir(deployment, module) {
+  return join(deployment, MODULES_DIR, `${module.name}@${String(module.from.commit).slice(0, 12)}`);
+}
+
+/** Ensure the module's capability tree is in the deployment store; returns its dir.
+ *  A tree already there (oats.json present) is reused — the commit is in the name,
+ *  so it cannot be stale. The fetch lands in a sibling staging dir and is renamed
+ *  into place, so a failed or interrupted fetch never leaves a half tree that a
+ *  later call would trust. */
+export async function ensureModuleTree(deployment, module, lock, { catalog = null, remote = defaultRemote, remoteOptions, fetch = defaultRemote.fetchRemoteTree } = {}) {
+  const store = join(deployment, MODULES_DIR);
+  const dir = moduleStoreDir(deployment, module);
+  if (existsSync(join(dir, "oats.json"))) return dir;
+  const ref = moduleRef(module, lock, { catalog, remote });
+  if (typeof module.dir !== "string" || !module.dir) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: resolution records no capability directory`, { module: module.name });
+  mkdirSync(store, { recursive: true });
+  const staging = join(store, `.staging-${module.name}-${process.pid}-${randomBytes(4).toString("hex")}`);
+  try {
+    await fetch(ref, module.from.commit, module.dir, staging, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
+    if (!existsSync(join(staging, "oats.json"))) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: ${module.dir} at ${String(module.from.commit).slice(0, 12)} has no oats.json`, { module: module.name, dir: module.dir, commit: module.from.commit });
+    // A concurrent call may have won; its tree is the same commit — keep it.
+    if (existsSync(join(dir, "oats.json"))) { rmSync(staging, { recursive: true, force: true }); return dir; }
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true }); // a half tree from an interrupted direct write
+    renameSync(staging, dir);
+    return dir;
+  } catch (x) { try { rmSync(staging, { recursive: true, force: true }); } catch { /* nothing */ } throw x; }
+}
+
+/**
+ * Resolve an operator-level command namespace from a deployment directory.
+ *
+ *   contextDir  — where the operator stands (oats-local.yaml is found walking up)
+ *   namespace   — the `<ns>` the operator typed (`okf`)
+ *   soulName    — the value of --soul; REQUIRED (undefined/true/"" → E_BAD_ARGS)
+ *
+ * → { deployment, soul: { name, repoKey, commit, team }, module, manifest, commands,
+ *     settings: <resolution.payloads[cap] or {}>, resolution, prepared,
+ *     ensureTree(): Promise<dir> }   — or null when no module of the soul's
+ *     resolution claims the namespace (the caller answers E_UNKNOWN_COMMAND).
+ * Two modules claiming one namespace → E_DUPLICATE_NAMESPACE. Everything
+ * prepareInstance can throw (E_SOUL_UNKNOWN, E_PACKAGE_UNAPPROVED,
+ * E_REMOTE_UNREADABLE, …) propagates untouched.
+ */
+export async function resolveOperatorDispatch(contextDir, namespace, soulName, { remoteOptions, remote, catalog = null, fetch, prepare = prepareInstance } = {}) {
+  if (typeof namespace !== "string" || !namespace) throw err("E_BAD_ARGS", "a command namespace is required");
+  if (typeof soulName !== "string" || !soulName.trim()) {
+    throw err("E_BAD_ARGS", `oats ${namespace}: outside an instance home a capability command resolves as a spawn would — pass --soul <name> (the soul whose resolution provides the "${namespace}" namespace)`, { namespace, flag: "--soul" });
+  }
+  const prepared = await prepare(resolvePath(contextDir), soulName, { remoteOptions, remote });
+  const { resolution, lock } = prepared;
+  const deployment = prepared.deployment ?? dirname(loadLocal(contextDir).path);
+  const claimants = (resolution.modules || []).filter((m) => m?.manifest && m.manifest.command === namespace && m.manifest.commands && typeof m.manifest.commands === "object");
+  if (!claimants.length) return null;
+  if (claimants.length > 1) throw err("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${namespace}": ${claimants.map((m) => m.name).join(", ")}`, { namespace, modules: claimants.map((m) => m.name) });
+  const module = claimants[0];
+  const payload = resolution.payloads?.[module.name];
+  const settings = payload && typeof payload === "object" ? { ...payload } : {};
+  return {
+    deployment, soul: resolution.soul, module, manifest: module.manifest, commands: module.manifest.commands, settings, resolution, prepared,
+    ensureTree: () => ensureModuleTree(deployment, module, lock, { catalog, remote, remoteOptions: remoteOptions ?? prepared.remoteOptions, fetch }),
+  };
+}