owlrunkit 0.15.0 → 0.16.0

package/scripts/runkit-contract/fleet-discovery.mjs

@@ -0,0 +1,456 @@
+import {
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { userInfo } from "node:os";
+import path from "node:path";
+
+const MAX_FLEET_MANIFEST_BYTES = 1_048_576;
+const MAX_FLEET_WORKSPACES = 256;
+const MAX_FLEET_ROOTS = 32;
+const MAX_SCAN_DIRECTORIES = 10_000;
+const MAX_SCAN_DEPTH = 16;
+const FLEET_REGISTRY_SCHEMA =
+  "OwlCodaRunKitFleetRootRegistryV1";
+const SKIPPED_DIRECTORIES = new Set([
+  ".cache",
+  ".git",
+  ".hg",
+  ".owlcoda",
+  ".svn",
+  "node_modules",
+]);
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+async function canonicalWorkspace(workspaceRoot) {
+  if (typeof workspaceRoot !== "string" || workspaceRoot.length === 0) {
+    throw new Error("fleet_workspace_invalid");
+  }
+  const requested = path.resolve(workspaceRoot);
+  const stat = await lstat(requested);
+  if (stat.isSymbolicLink()) throw new Error("fleet_workspace_symlink_rejected");
+  if (!stat.isDirectory()) throw new Error("fleet_workspace_invalid");
+  return realpath(requested);
+}
+
+function frozenManifestSha256({ coverageRoots, workspaceRoots }) {
+  const frozen = {
+    schemaVersion: "OwlCodaRunKitFrozenFleetManifestV1",
+    skillName: "owlcoda-runkit",
+    coverageRoots,
+    workspaceRoots,
+    authorizationGranted: false,
+  };
+  return `sha256:${createHash("sha256")
+    .update(`${JSON.stringify(frozen)}\n`)
+    .digest("hex")}`;
+}
+
+function sha256Json(value) {
+  return `sha256:${createHash("sha256")
+    .update(`${JSON.stringify(value)}\n`)
+    .digest("hex")}`;
+}
+
+export function defaultFleetRegistryPath() {
+  const owlcodaHome = process.env.OWLCODA_HOME
+    ? path.resolve(process.env.OWLCODA_HOME)
+    : path.join(userInfo().homedir, ".owlcoda");
+  return path.join(owlcodaHome, "runkit-fleet-root-registry-v1.json");
+}
+
+async function hasRunKitConfig(directory) {
+  const owlRoot = path.join(directory, ".owlcoda");
+  const runkitRoot = path.join(owlRoot, "runkit");
+  const configPath = path.join(runkitRoot, "config.json");
+
+  let owlStat;
+  try {
+    owlStat = await lstat(owlRoot);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  if (
+    owlStat.isSymbolicLink()
+    || !owlStat.isDirectory()
+    || await realpath(owlRoot) !== path.resolve(owlRoot)
+  ) {
+    throw new Error("fleet_project_marker_invalid");
+  }
+
+  let runkitStat;
+  try {
+    runkitStat = await lstat(runkitRoot);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  if (
+    runkitStat.isSymbolicLink()
+    || !runkitStat.isDirectory()
+    || await realpath(runkitRoot) !== path.resolve(runkitRoot)
+  ) {
+    throw new Error("fleet_project_marker_invalid");
+  }
+
+  let configStat;
+  try {
+    configStat = await lstat(configPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("fleet_project_marker_incomplete");
+    }
+    throw error;
+  }
+  if (
+    configStat.isSymbolicLink()
+    || !configStat.isFile()
+    || await realpath(configPath) !== path.resolve(configPath)
+  ) {
+    throw new Error("fleet_project_marker_invalid");
+  }
+  return true;
+}
+
+async function scanFleetRoot(fleetRoot) {
+  const requested = path.resolve(fleetRoot);
+  const canonicalRoot = await canonicalWorkspace(requested);
+  const projects = [];
+  let visitedDirectories = 0;
+  async function visit(directory, depth) {
+    if (depth > MAX_SCAN_DEPTH) throw new Error("fleet_scan_depth_exceeded");
+    visitedDirectories += 1;
+    if (visitedDirectories > MAX_SCAN_DIRECTORIES) {
+      throw new Error("fleet_scan_directory_limit_exceeded");
+    }
+    if (await hasRunKitConfig(directory)) projects.push(directory);
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => compareCodeUnits(left.name, right.name));
+    for (const entry of entries) {
+      if (SKIPPED_DIRECTORIES.has(entry.name) || entry.isSymbolicLink()) continue;
+      if (!entry.isDirectory()) continue;
+      await visit(path.join(directory, entry.name), depth + 1);
+    }
+  }
+  await visit(canonicalRoot, 0);
+  return {
+    coverageRoot: canonicalRoot,
+    workspaceRoots: projects,
+  };
+}
+
+async function discoverFromFleetRoots(
+  fleetRoots,
+  {
+    source = "fleet_roots",
+    registryPath = null,
+    registrySha256 = null,
+  } = {},
+) {
+  if (
+    !Array.isArray(fleetRoots)
+    || fleetRoots.length === 0
+    || fleetRoots.length > MAX_FLEET_ROOTS
+  ) {
+    throw new Error("fleet_roots_required");
+  }
+  const coverageRoots = [];
+  const unreachableRoots = [];
+  const workspaceRoots = [];
+  for (const fleetRoot of fleetRoots) {
+    if (typeof fleetRoot !== "string" || fleetRoot.length === 0) {
+      throw new Error("fleet_root_invalid");
+    }
+    try {
+      const scanned = await scanFleetRoot(fleetRoot);
+      coverageRoots.push(scanned.coverageRoot);
+      workspaceRoots.push(...scanned.workspaceRoots);
+    } catch {
+      unreachableRoots.push(path.resolve(fleetRoot));
+    }
+  }
+  const normalizedCoverage = [...new Set(coverageRoots)].sort(compareCodeUnits);
+  const normalizedUnreachable = [...new Set(unreachableRoots)].sort(compareCodeUnits);
+  const normalizedWorkspaces = [...new Set(workspaceRoots)].sort(compareCodeUnits);
+  if (normalizedWorkspaces.length > MAX_FLEET_WORKSPACES) {
+    throw new Error("fleet_workspace_limit_exceeded");
+  }
+  return {
+    schemaVersion: "OwlCodaRunKitFleetDiscoveryV1",
+    source,
+    ...(registryPath === null
+      ? {}
+      : { registryPath, registrySha256 }),
+    coverageRoots: normalizedCoverage,
+    unreachableRoots: normalizedUnreachable,
+    workspaceRoots: normalizedWorkspaces,
+    complete: normalizedUnreachable.length === 0,
+    frozenManifestSha256: frozenManifestSha256({
+      coverageRoots: normalizedCoverage,
+      workspaceRoots: normalizedWorkspaces,
+    }),
+    authorizationGranted: false,
+  };
+}
+
+async function readFleetRegistry(fleetRegistryPath) {
+  const selected = path.resolve(
+    fleetRegistryPath ?? defaultFleetRegistryPath(),
+  );
+  let loaded;
+  try {
+    loaded = await readManifestBounded(selected);
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error("fleet_registry_missing");
+    throw error;
+  }
+  const registry = loaded.manifest;
+  if (
+    registry === null
+    || typeof registry !== "object"
+    || Array.isArray(registry)
+    || Object.keys(registry).sort().join(",")
+      !== "authorizationGranted,coverageRoots,registrySha256,schemaVersion"
+    || registry.schemaVersion !== FLEET_REGISTRY_SCHEMA
+    || registry.authorizationGranted !== false
+    || !Array.isArray(registry.coverageRoots)
+    || registry.coverageRoots.length === 0
+    || registry.coverageRoots.length > MAX_FLEET_ROOTS
+  ) {
+    throw new Error("fleet_registry_invalid");
+  }
+  const body = {
+    schemaVersion: registry.schemaVersion,
+    coverageRoots: registry.coverageRoots,
+    authorizationGranted: false,
+  };
+  if (registry.registrySha256 !== sha256Json(body)) {
+    throw new Error("fleet_registry_hash_mismatch");
+  }
+  return {
+    registryPath: loaded.manifestPath,
+    registrySha256: registry.registrySha256,
+    coverageRoots: [...registry.coverageRoots],
+  };
+}
+
+export async function registerFleetCoverageRoot({
+  fleetRoot,
+  fleetRegistryPath = defaultFleetRegistryPath(),
+} = {}) {
+  const coverageRoot = await canonicalWorkspace(fleetRoot);
+  const registryPath = path.resolve(fleetRegistryPath);
+  const parent = path.dirname(registryPath);
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const lockPath = `${registryPath}.lock`;
+  try {
+    await mkdir(lockPath);
+  } catch (error) {
+    if (error?.code === "EEXIST") throw new Error("fleet_registry_transaction_active");
+    throw error;
+  }
+  try {
+    let coverageRoots = [];
+    try {
+      coverageRoots = (await readFleetRegistry(registryPath)).coverageRoots;
+    } catch (error) {
+      if (error?.message !== "fleet_registry_missing") throw error;
+    }
+    const alreadyRegistered = coverageRoots.includes(coverageRoot);
+    const normalized = [...new Set([
+      ...coverageRoots,
+      coverageRoot,
+    ])].sort(compareCodeUnits);
+    if (normalized.length > MAX_FLEET_ROOTS) {
+      throw new Error("fleet_registry_root_limit_exceeded");
+    }
+    const body = {
+      schemaVersion: FLEET_REGISTRY_SCHEMA,
+      coverageRoots: normalized,
+      authorizationGranted: false,
+    };
+    const registry = {
+      ...body,
+      registrySha256: sha256Json(body),
+    };
+    if (!alreadyRegistered) {
+      const temporaryPath = `${registryPath}.tmp-${process.pid}`;
+      try {
+        await writeFile(
+          temporaryPath,
+          `${JSON.stringify(registry, null, 2)}\n`,
+          { flag: "wx", mode: 0o600 },
+        );
+        await rename(temporaryPath, registryPath);
+      } finally {
+        await rm(temporaryPath, { force: true });
+      }
+    }
+    return {
+      status: alreadyRegistered
+        ? "fleet_root_already_registered"
+        : "fleet_root_registered",
+      registryPath,
+      registrySha256: registry.registrySha256,
+      coverageRoots: normalized,
+      authorizationGranted: false,
+    };
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
+
+async function readManifestBounded(fleetManifestPath) {
+  if (typeof fleetManifestPath !== "string" || fleetManifestPath.length === 0) {
+    throw new Error("fleet_manifest_path_invalid");
+  }
+  const requested = path.resolve(fleetManifestPath);
+  const stat = await lstat(requested);
+  if (stat.isSymbolicLink()) throw new Error("fleet_manifest_symlink_rejected");
+  if (!stat.isFile()) throw new Error("fleet_manifest_path_invalid");
+  if (stat.size > MAX_FLEET_MANIFEST_BYTES) {
+    throw new Error("fleet_manifest_too_large");
+  }
+  const canonicalPath = await realpath(requested);
+  const handle = await open(canonicalPath, "r");
+  try {
+    const before = await handle.stat();
+    const bytes = await handle.readFile();
+    const after = await handle.stat();
+    const current = await lstat(canonicalPath);
+    if (
+      current.isSymbolicLink()
+      || before.dev !== after.dev
+      || before.ino !== after.ino
+      || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs
+      || after.dev !== current.dev
+      || after.ino !== current.ino
+      || after.size !== current.size
+      || bytes.length !== current.size
+    ) {
+      throw new Error("fleet_manifest_changed_during_read");
+    }
+    try {
+      return {
+        manifest: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)),
+        manifestPath: canonicalPath,
+      };
+    } catch {
+      throw new Error("fleet_manifest_invalid_json");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+function validateManifest(manifest) {
+  if (
+    manifest === null
+    || typeof manifest !== "object"
+    || Array.isArray(manifest)
+    || Object.keys(manifest).some(key => ![
+      "authorizationGranted",
+      "schemaVersion",
+      "skillName",
+      "workspaceRoots",
+    ].includes(key))
+    || manifest.schemaVersion !== "OwlCodaRunKitFleetManifestV1"
+    || manifest.skillName !== "owlcoda-runkit"
+    || manifest.authorizationGranted !== false
+    || !Array.isArray(manifest.workspaceRoots)
+    || manifest.workspaceRoots.length === 0
+    || manifest.workspaceRoots.length > MAX_FLEET_WORKSPACES
+  ) {
+    throw new Error("fleet_manifest_invalid");
+  }
+}
+
+async function canonicalizeRoots(workspaceRoots, { rejectDuplicates }) {
+  if (
+    !Array.isArray(workspaceRoots)
+    || workspaceRoots.length === 0
+    || workspaceRoots.length > MAX_FLEET_WORKSPACES
+  ) {
+    throw new Error("fleet_workspaces_required");
+  }
+  const roots = [];
+  for (const workspaceRoot of workspaceRoots) {
+    roots.push(await canonicalWorkspace(workspaceRoot));
+  }
+  if (rejectDuplicates && new Set(roots).size !== roots.length) {
+    throw new Error("fleet_workspace_duplicate");
+  }
+  return [...new Set(roots)].sort(compareCodeUnits);
+}
+
+export async function discoverFleet({
+  workspaceRoots = null,
+  fleetManifestPath = null,
+  fleetRoots = null,
+  fleetRegistryPath = null,
+} = {}) {
+  const sources = [workspaceRoots, fleetManifestPath, fleetRoots]
+    .filter(source => source !== null);
+  if (sources.length > 1) {
+    throw new Error("fleet_source_ambiguous");
+  }
+  if (fleetRoots !== null) return discoverFromFleetRoots(fleetRoots);
+  if (fleetManifestPath !== null) {
+    const { manifest, manifestPath } = await readManifestBounded(fleetManifestPath);
+    validateManifest(manifest);
+    const normalizedWorkspaces = await canonicalizeRoots(
+      manifest.workspaceRoots,
+      { rejectDuplicates: true },
+    );
+    return {
+      schemaVersion: "OwlCodaRunKitFleetDiscoveryV1",
+      source: "fleet_manifest",
+      manifestPath,
+      coverageRoots: [],
+      unreachableRoots: [],
+      workspaceRoots: normalizedWorkspaces,
+      complete: true,
+      frozenManifestSha256: frozenManifestSha256({
+        coverageRoots: [],
+        workspaceRoots: normalizedWorkspaces,
+      }),
+      authorizationGranted: false,
+    };
+  }
+  if (workspaceRoots === null) {
+    const registry = await readFleetRegistry(fleetRegistryPath);
+    return discoverFromFleetRoots(registry.coverageRoots, {
+      source: "fleet_registry",
+      registryPath: registry.registryPath,
+      registrySha256: registry.registrySha256,
+    });
+  }
+  const normalizedWorkspaces = await canonicalizeRoots(workspaceRoots, {
+    rejectDuplicates: false,
+  });
+  return {
+    schemaVersion: "OwlCodaRunKitFleetDiscoveryV1",
+    source: "explicit_workspaces",
+    coverageRoots: [],
+    unreachableRoots: [],
+    workspaceRoots: normalizedWorkspaces,
+    complete: true,
+    frozenManifestSha256: frozenManifestSha256({
+      coverageRoots: [],
+      workspaceRoots: normalizedWorkspaces,
+    }),
+    authorizationGranted: false,
+  };
+}