@awebai/oats 0.32.0 → 0.34.0

package/lib/resolve.mjs

@@ -474,12 +474,29 @@ export function packageRef(id, entry, catalog, remote) {
 const SAFE_REL = (rel) => typeof rel === "string" && rel && !posix.isAbsolute(rel) && !/^[\\/]/.test(rel) && !/\0/.test(rel) && !rel.split(/[\\/]/).some((p) => p === "..");
 
 /** Normalize a manifest-declared relative path ("./skills/x/" → "skills/x"); null when unsafe. */
-function declaredPath(rel) {
+export function declaredPath(rel) {
   if (!SAFE_REL(rel)) return null;
   const n = posix.normalize(rel).replace(/\/+$/, "");
   return n === "." || n === "" || n.startsWith("../") ? null : n;
 }
 
+/** A relative path no listing of a checkout can hold: absolute, empty, a `.`/`..`/`.git` (any case) or empty
+ *  component, a trailing slash, a backslash or a NUL. */
+export function unsafeRelPath(path) {
+  if (typeof path !== "string" || path === "" || path.startsWith("/") || path.endsWith("/") || /[\\\0]/.test(path)) return true;
+  return path.split("/").some((c) => c === "" || c === "." || c === ".." || c.toLowerCase() === ".git");
+}
+
+/** A manifest-declared path as the module install reads it (lib/materialize.mjs modulePath: a backslash is a
+ *  separator, `./` and trailing slashes dropped), and only when the result is a safe POSIX path (unsafeRelPath);
+ *  else null. What `oats capabilities show` reports for an inject or a skill. */
+export function manifestFilePath(rel) {
+  const declared = declaredPath(rel);
+  if (!declared) return null;
+  const n = posix.normalize(declared.replace(/\\/g, "/")).replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+  return unsafeRelPath(n) ? null : n;
+}
+
 /**
  * Skills declared by a manifest: each `skills[]` entry is a directory under the capability that either
  * IS a skill (holds SKILL.md) or holds skill directories (<entry>/<skill>/SKILL.md) — the same reading
@@ -525,14 +542,31 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
  *  would), commands and hooks. `skills` is null when its declared skills cannot be listed (a spawn of it
  *  would refuse; the listing does not). */
 export async function capabilityProvides({ ref, commit, dir, manifest, remote: injected, remoteOptions }) {
-  const remote = remoteOf({ remote: injected, remoteOptions });
   const keys = (o) => (isObject(o) ? Object.keys(o).sort(byCodepoint) : []);
-  let skills;
+  const { skills } = await capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions });
+  return { skills: skills && skills.map((s) => s.name), commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+}
+
+/** A capability's skills as a spawn enumerates them (enumerateSkills), sorted by name in codepoint order:
+ *  → { skills: [{ name, path }] (path relative to the capability directory), problem: null }, or
+ *  { skills: null, problem } when the declared skills cannot be enumerated — `problem` the oats error a spawn
+ *  would meet (`missingCode`: E_CAPABILITY_MISSING for a member, E_PACKAGE_MANIFEST for a package), or a skill
+ *  path that is not safe (manifestFilePath). Paths are as the install reads them. The one reading of
+ *  `manifest.skills` behind `oats capabilities` (capabilityProvides) and `oats capabilities show`. */
+export async function capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions, missingCode = "E_CAPABILITY_MISSING" }) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const missing = (raw, why, text) => fail(missingCode, `${manifest.capability} ${text}`, { capability: manifest.capability, skill: raw, why });
   try {
-    const missing = (raw, why, text) => fail("E_CAPABILITY_MISSING", text, { skill: raw, why });
-    skills = (await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })).map((x) => x.name).sort(byCodepoint);
-  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) skills = null; else throw e; }
-  return { skills, commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+    const skills = [];
+    for (const { name, path } of await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })) {
+      // A skill path is reported as the install reads it, and only when it is a safe POSIX path (a `.git`
+      // directory the remote serves is one a spawn's fetch refuses).
+      const safe = manifestFilePath(path);
+      if (!safe) throw missing(path, "unsafe", `declares skill ${show(name)} at ${show(path)}, which is not a safe path inside the capability`);
+      skills.push({ name, path: safe });
+    }
+    return { skills: skills.sort((a, b) => byCodepoint(a.name, b.name)), problem: null };
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return { skills: null, problem: e }; throw e; }
 }
 
 /** The capability manifests of a locked package, read at its locked commit (feature desktop-facts). */
@@ -543,6 +577,20 @@ export async function lockedPackageCapabilities(id, entry, { catalog = null, rem
   return { ref, capabilities };
 }
 
+/** The lock must describe the tree it names: the capability list a package's manifests declare at the locked
+ *  commit (`capabilities`, readPackageManifests) must equal the lock entry's, and must hold `name`, else
+ *  E_PACKAGE_INTEGRITY. → that capability { name, dir, manifest }. Spawn's check (resolveSoul), shared with
+ *  `oats capabilities show`. */
+export function lockedCapability(name, id, entry, capabilities, details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path }) {
+  const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
+  if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
+    throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
+  }
+  const cap = capabilities.find((c) => c.name === name);
+  if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+  return cap;
+}
+
 /* ───────────────────────────── resolveSoul ────────────────────────────── */
 
 /**
@@ -601,13 +649,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
-      // The lock must describe the tree it names: its capability list is what the package declares there.
-      const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
-      if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
-        throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
-      }
-      const cap = capabilities.find((c) => c.name === name);
-      if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+      const cap = lockedCapability(name, id, entry, capabilities, details);
       const layer = layerOf(cap.manifest);
       if (layer && emptied.has(layer) && via !== "soul") { turnedOff.push({ name, reason: "slot-none", slot: layer, overrides: fromOfVia(via) }); continue; }
       module = {

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.3",
+      "ref": "v1.17.5",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -28,7 +28,7 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.3.0",
+      "ref": "v1.4.0",
       "path": "oats-package"
     },
     "oats.framework": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",