owlrunkit 0.13.0 → 0.14.0

package/scripts/runkit-contract/onboarding-doctor.mjs

@@ -0,0 +1,607 @@
+import {
+  closeSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  currentCoreIdentity,
+  validateProjectConfigV2,
+} from "./core-contract.mjs";
+import {
+  expectedRegistryTarballUrl,
+  isCanonicalSha512Integrity,
+} from "./registry-adoption-gate.mjs";
+
+const PACKAGE_NAME = "owlrunkit";
+const EXPECTED_VERSION = "0.14.0";
+const MAX_JSON_BYTES = 1_048_576;
+const MAX_JSON_DEPTH = 64;
+const MAX_JSON_NODES = 50_000;
+
+class StrictJsonParser {
+  constructor(text) {
+    this.text = text;
+    this.index = 0;
+    this.nodes = 0;
+  }
+
+  parse() {
+    const value = this.parseValue(0);
+    this.skipWhitespace();
+    if (this.index !== this.text.length) this.fail("unexpected trailing content");
+    return value;
+  }
+
+  parseValue(depth) {
+    this.skipWhitespace();
+    this.nodes += 1;
+    if (this.nodes > MAX_JSON_NODES) throw new Error("JSON input exceeds the node limit");
+    const character = this.text[this.index];
+    if (character === "{") return this.parseObject(depth);
+    if (character === "[") return this.parseArray(depth);
+    if (character === '"') return this.parseString();
+    if (character === "t") return this.parseLiteral("true", true);
+    if (character === "f") return this.parseLiteral("false", false);
+    if (character === "n") return this.parseLiteral("null", null);
+    if (character === "-" || (character >= "0" && character <= "9")) {
+      return this.parseNumber();
+    }
+    this.fail("expected a JSON value");
+  }
+
+  parseObject(depth) {
+    const childDepth = this.enter(depth);
+    this.index += 1;
+    this.skipWhitespace();
+    const value = {};
+    const keys = new Set();
+    if (this.text[this.index] === "}") {
+      this.index += 1;
+      return value;
+    }
+    while (true) {
+      if (this.text[this.index] !== '"') this.fail("expected an object key");
+      const key = this.parseString();
+      if (keys.has(key)) throw new Error(`duplicate object key: ${key}`);
+      keys.add(key);
+      this.skipWhitespace();
+      if (this.text[this.index] !== ":") this.fail("expected ':' after an object key");
+      this.index += 1;
+      Object.defineProperty(value, key, {
+        value: this.parseValue(childDepth),
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+      this.skipWhitespace();
+      if (this.text[this.index] === "}") {
+        this.index += 1;
+        return value;
+      }
+      if (this.text[this.index] !== ",") this.fail("expected ',' or '}' in an object");
+      this.index += 1;
+      this.skipWhitespace();
+    }
+  }
+
+  parseArray(depth) {
+    const childDepth = this.enter(depth);
+    this.index += 1;
+    this.skipWhitespace();
+    const value = [];
+    if (this.text[this.index] === "]") {
+      this.index += 1;
+      return value;
+    }
+    while (true) {
+      value.push(this.parseValue(childDepth));
+      this.skipWhitespace();
+      if (this.text[this.index] === "]") {
+        this.index += 1;
+        return value;
+      }
+      if (this.text[this.index] !== ",") this.fail("expected ',' or ']' in an array");
+      this.index += 1;
+    }
+  }
+
+  parseString() {
+    const start = this.index;
+    this.index += 1;
+    while (this.index < this.text.length) {
+      const character = this.text[this.index];
+      if (character === '"') {
+        this.index += 1;
+        try {
+          return JSON.parse(this.text.slice(start, this.index));
+        } catch {
+          this.fail("invalid JSON string");
+        }
+      }
+      if (character.charCodeAt(0) < 0x20) this.fail("unescaped control character");
+      if (character === "\\") {
+        this.index += 1;
+        const escape = this.text[this.index];
+        if (escape === "u") {
+          const digits = this.text.slice(this.index + 1, this.index + 5);
+          if (!/^[0-9a-fA-F]{4}$/.test(digits)) this.fail("invalid Unicode escape");
+          this.index += 4;
+        } else if (!'"\\/bfnrt'.includes(escape)) {
+          this.fail("invalid escape");
+        }
+      }
+      this.index += 1;
+    }
+    this.fail("unterminated JSON string");
+  }
+
+  parseLiteral(token, value) {
+    if (this.text.slice(this.index, this.index + token.length) !== token) {
+      this.fail(`invalid literal: expected ${token}`);
+    }
+    this.index += token.length;
+    return value;
+  }
+
+  parseNumber() {
+    const match = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(
+      this.text.slice(this.index),
+    );
+    if (!match) this.fail("invalid JSON number");
+    this.index += match[0].length;
+    const value = Number(match[0]);
+    if (!Number.isFinite(value)) this.fail("JSON number is outside the finite range");
+    return value;
+  }
+
+  enter(depth) {
+    const nextDepth = depth + 1;
+    if (nextDepth > MAX_JSON_DEPTH) throw new Error("JSON input exceeds the nesting limit");
+    return nextDepth;
+  }
+
+  skipWhitespace() {
+    while (this.index < this.text.length && [" ", "\t", "\n", "\r"].includes(this.text[this.index])) {
+      this.index += 1;
+    }
+  }
+
+  fail(message) {
+    throw new Error(`${message} at byte offset ${this.index}`);
+  }
+}
+
+function parseJsonStrict(text) {
+  if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > MAX_JSON_BYTES) {
+    throw new Error("JSON input exceeds the input-byte limit");
+  }
+  return new StrictJsonParser(text).parse();
+}
+
+export function resolveBoundedWorkspaceRoot(workspaceRoot) {
+  const requested = path.resolve(workspaceRoot);
+  const stat = lstatSync(requested);
+  if (
+    stat.isSymbolicLink()
+    || !stat.isDirectory()
+    || realpathSync(requested) !== requested
+  ) {
+    throw new Error("workspace root must be a real directory without symlink ancestors");
+  }
+  return requested;
+}
+
+function identityMatches(left, right) {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs;
+}
+
+export function readWorkspaceFileBounded(root, relativePath, { optional = false } = {}) {
+  const target = path.resolve(root, relativePath);
+  if (!strictDescendant(root, target)) throw new Error("workspace file escaped the workspace root");
+  const segments = path.relative(root, target).split(path.sep);
+  let current = root;
+  for (let index = 0; index < segments.length; index += 1) {
+    current = path.join(current, segments[index]);
+    let stat;
+    try {
+      stat = lstatSync(current);
+    } catch (error) {
+      if (optional && error?.code === "ENOENT") return null;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) throw new Error("workspace file path contains a symlink");
+    const leaf = index === segments.length - 1;
+    if ((!leaf && !stat.isDirectory()) || (leaf && !stat.isFile())) {
+      throw new Error("workspace file path has an invalid entry type");
+    }
+  }
+  const realTarget = realpathSync(target);
+  if (!strictDescendant(root, realTarget)) throw new Error("workspace file escaped the workspace root");
+
+  const descriptor = openSync(target, "r");
+  try {
+    const before = fstatSync(descriptor);
+    if (!before.isFile() || before.size > MAX_JSON_BYTES) {
+      throw new Error("workspace file exceeds the input-byte limit");
+    }
+    const buffer = Buffer.allocUnsafe(MAX_JSON_BYTES + 1);
+    let offset = 0;
+    while (offset <= MAX_JSON_BYTES) {
+      const bytesRead = readSync(descriptor, buffer, offset, buffer.length - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    if (offset > MAX_JSON_BYTES) throw new Error("workspace file exceeds the input-byte limit");
+    const after = fstatSync(descriptor);
+    const currentStat = lstatSync(target);
+    if (
+      currentStat.isSymbolicLink()
+      || !currentStat.isFile()
+      || !identityMatches(before, after)
+      || !identityMatches(after, currentStat)
+      || realpathSync(target) !== realTarget
+    ) {
+      throw new Error("workspace file identity changed while reading");
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function readWorkspaceJsonBounded(root, relativePath, options) {
+  const text = readWorkspaceFileBounded(root, relativePath, options);
+  return text === null ? null : parseJsonStrict(text);
+}
+
+async function readResponseJsonBounded(response) {
+  if (!response.body) throw new Error("registry response body is missing");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_JSON_BYTES) {
+        await reader.cancel();
+        throw new Error("registry response exceeds the input-byte limit");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return parseJsonStrict(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+}
+
+function strictDescendant(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== ""
+    && relative !== ".."
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+function assertPathWithoutSymlinks(root, target, { targetType }) {
+  const realRoot = realpathSync(root);
+  const relative = path.relative(realRoot, target);
+  if (!strictDescendant(realRoot, target)) {
+    throw new Error("installed_package_path_invalid");
+  }
+  let current = realRoot;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error("installed_package_symlink_rejected");
+  }
+  const finalStat = lstatSync(target);
+  if (
+    (targetType === "file" && !finalStat.isFile())
+    || (targetType === "directory" && !finalStat.isDirectory())
+  ) {
+    throw new Error("installed_package_path_invalid");
+  }
+  const realTarget = realpathSync(target);
+  if (!strictDescendant(realRoot, realTarget)) {
+    throw new Error("installed_package_path_invalid");
+  }
+}
+
+function dependencyDeclarations(manifest) {
+  return ["dependencies", "devDependencies", "optionalDependencies"]
+    .filter((section) => Object.hasOwn(manifest[section] ?? {}, PACKAGE_NAME))
+    .map((section) => ({ section, spec: manifest[section][PACKAGE_NAME] }));
+}
+
+export function readLocalInstallBinding({ workspaceRoot } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const manifestPath = path.join(root, "package.json");
+  const lockPath = path.join(root, "package-lock.json");
+  const installedRoot = path.join(root, "node_modules", PACKAGE_NAME);
+  const installedManifestPath = path.join(installedRoot, "package.json");
+  try {
+    for (const [target, targetType] of [
+      [installedRoot, "directory"],
+    ]) {
+      assertPathWithoutSymlinks(root, target, { targetType });
+    }
+    const manifest = readWorkspaceJsonBounded(root, "package.json");
+    const lock = readWorkspaceJsonBounded(root, "package-lock.json");
+    const installedManifest = readWorkspaceJsonBounded(
+      root,
+      path.join("node_modules", PACKAGE_NAME, "package.json"),
+    );
+    const declarations = dependencyDeclarations(manifest);
+    if (declarations.length !== 1) {
+      return {
+        status: "mismatch",
+        issueCodes: ["registry_install_binding_ambiguous"],
+      };
+    }
+    const requestedSpec = declarations[0].spec;
+    const lockBinding = lock.packages?.[`node_modules/${PACKAGE_NAME}`];
+    if (
+      requestedSpec !== EXPECTED_VERSION
+      || lockBinding?.version !== EXPECTED_VERSION
+      || installedManifest.name !== PACKAGE_NAME
+      || installedManifest.version !== EXPECTED_VERSION
+      || typeof lockBinding.resolved !== "string"
+      || typeof lockBinding.integrity !== "string"
+    ) {
+      return {
+        status: "mismatch",
+        issueCodes: ["registry_install_binding_mismatch"],
+      };
+    }
+    return {
+      status: "bound",
+      requestedSpec: `${PACKAGE_NAME}@${requestedSpec}`,
+      packageName: PACKAGE_NAME,
+      version: EXPECTED_VERSION,
+      resolved: lockBinding.resolved,
+      integrity: lockBinding.integrity,
+    };
+  } catch (error) {
+    return {
+      status: "mismatch",
+      issueCodes: [
+        error instanceof Error && error.message.startsWith("installed_package_")
+          ? error.message
+          : "registry_install_binding_mismatch",
+      ],
+    };
+  }
+}
+
+export async function readRegistryExact({
+  registryUrl,
+  packageName = PACKAGE_NAME,
+  version = EXPECTED_VERSION,
+  timeoutMs = 1_500,
+} = {}) {
+  const base = registryUrl.replace(/\/+$/, "");
+  const url = `${base}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`;
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: {
+        accept: "application/json",
+      },
+      redirect: "manual",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    return {
+      status: "unavailable",
+      issueCodes: ["registry_dns_or_timeout"],
+    };
+  }
+  if (response.status === 401 || response.status === 403) {
+    return {
+      status: "unauthorized",
+      issueCodes: ["registry_auth_failed"],
+    };
+  }
+  if (response.status === 404) {
+    return {
+      status: "version_missing",
+      issueCodes: ["registry_version_missing"],
+    };
+  }
+  if (response.status >= 300 && response.status < 400) {
+    return {
+      status: "invalid",
+      issueCodes: ["registry_redirect_rejected"],
+    };
+  }
+  if (!response.ok) {
+    return {
+      status: "unavailable",
+      issueCodes: [`registry_http_${response.status}`],
+    };
+  }
+  try {
+    const metadata = await readResponseJsonBounded(response);
+    const dist = metadata.dist;
+    if (
+      metadata.name !== packageName
+      || metadata.version !== version
+      || !/^[0-9a-f]{40}$/i.test(dist?.shasum ?? "")
+      || !isCanonicalSha512Integrity(dist?.integrity)
+      || dist?.tarball !== expectedRegistryTarballUrl(packageName, version)
+    ) {
+      return {
+        status: "invalid",
+        issueCodes: ["registry_release_evidence_invalid"],
+      };
+    }
+    return {
+      schemaVersion: "OwlCodaRunKitRegistryReleaseEvidenceV1",
+      status: "registry_verified",
+      registry: base,
+      packageName,
+      version,
+      shasum: dist.shasum,
+      integrity: dist.integrity,
+      tarballUrl: dist.tarball,
+      authorizationGranted: false,
+    };
+  } catch {
+    return {
+      status: "invalid",
+      issueCodes: ["registry_release_evidence_invalid"],
+    };
+  }
+}
+
+function readProjectScripts(root) {
+  try {
+    const manifest = readWorkspaceJsonBounded(root, "package.json");
+    return Object.keys(manifest.scripts ?? {}).sort();
+  } catch {
+    return [];
+  }
+}
+
+function configCheck(root) {
+  try {
+    const config = readWorkspaceJsonBounded(
+      root,
+      path.join(".owlcoda", "runkit", "config.json"),
+      { optional: true },
+    );
+    if (config === null) return { status: "missing" };
+    const gate = validateProjectConfigV2(config);
+    return gate.valid ? { status: "ok" } : { status: "invalid", issues: gate.issues };
+  } catch {
+    return { status: "invalid" };
+  }
+}
+
+function profilesCheck(root) {
+  try {
+    const profiles = readWorkspaceJsonBounded(
+      root,
+      path.join(".owlcoda", "runkit", "profiles.json"),
+      { optional: true },
+    );
+    if (profiles === null) return { status: "missing" };
+    return profiles.schemaVersion === "OwlCodaRunKitProfilesV1" && Array.isArray(profiles.profiles)
+      ? { status: "ok", count: profiles.profiles.length }
+      : { status: "invalid" };
+  } catch {
+    return { status: "invalid" };
+  }
+}
+
+export async function runDoctor({
+  workspaceRoot,
+  registryUrl,
+  timeoutMs = 1_500,
+  registryClient,
+} = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const core = currentCoreIdentity();
+  const installed = readLocalInstallBinding({ workspaceRoot: root });
+  const registry = registryClient
+    ? await registryClient.readExact({ packageName: PACKAGE_NAME, version: EXPECTED_VERSION })
+    : await readRegistryExact({
+        registryUrl,
+        packageName: PACKAGE_NAME,
+        version: EXPECTED_VERSION,
+        timeoutMs,
+      });
+  const nodeOk = Number(process.versions.node.split(".")[0]) >= 20;
+  const config = configCheck(root);
+  const profiles = profilesCheck(root);
+  const checks = {
+    node: {
+      status: nodeOk ? "ok" : "unsupported",
+      version: process.versions.node,
+    },
+    core: {
+      status: core.coreVersion === EXPECTED_VERSION ? "ok" : "mismatch",
+      version: core.coreVersion,
+      manifestSha256: core.coreManifestSha256,
+    },
+    config,
+    installedPackage: installed.status === "bound"
+      ? { status: "ok", version: installed.version }
+      : { status: "mismatch" },
+    registry: registry.status === "registry_verified"
+      ? { status: "ok", version: registry.version }
+      : { status: "issue", issueCodes: registry.issueCodes ?? [] },
+    profiles,
+    projectScripts: {
+      status: "observed",
+      detected: readProjectScripts(root),
+    },
+  };
+  const issueCodes = [...(registry.issueCodes ?? [])];
+  if (!nodeOk) issueCodes.push("node_version_unsupported");
+  if (checks.core.status !== "ok") issueCodes.push("core_version_mismatch");
+  if (config.status === "missing") issueCodes.push("runkit_config_missing");
+  if (config.status === "invalid") issueCodes.push("runkit_config_invalid");
+  if (profiles.status === "missing") issueCodes.push("profiles_missing");
+  if (profiles.status === "invalid") issueCodes.push("profiles_invalid");
+  if (installed.status !== "bound") {
+    issueCodes.push(...(installed.issueCodes ?? ["registry_install_binding_mismatch"]));
+  }
+  if (
+    registry.status === "registry_verified"
+    && (
+      installed.status !== "bound"
+      || installed.version !== registry.version
+      || installed.integrity !== registry.integrity
+      || installed.resolved !== registry.tarballUrl
+    )
+  ) {
+    issueCodes.push("registry_install_binding_mismatch");
+  }
+  const uniqueIssues = [...new Set(issueCodes)].sort();
+  const nextAllowedAction = uniqueIssues.length === 0
+    ? "detect_profiles"
+    : uniqueIssues.some((code) => code === "node_version_unsupported")
+      ? "upgrade_node"
+      : uniqueIssues.some((code) => code === "core_version_mismatch")
+        ? "install_matching_core"
+        : uniqueIssues.some((code) => code.startsWith("runkit_config_"))
+          ? "run_init_or_repair_config"
+          : uniqueIssues.some((code) => code.startsWith("profiles_"))
+            ? "detect_or_repair_profiles"
+            : "repair_registry_binding";
+  return {
+    schemaVersion: "OwlCodaRunKitDoctorReportV1",
+    status: uniqueIssues.length === 0 ? "ready" : "issues_found",
+    checks,
+    issueCodes: uniqueIssues,
+    nextAllowedAction,
+    authorizationGranted: false,
+  };
+}
+
+export function formatDoctorHuman(report) {
+  return [
+    `Doctor: ${report.status}`,
+    `Node: ${report.checks.node.status} (${report.checks.node.version})`,
+    `Core: ${report.checks.core.status} (${report.checks.core.version})`,
+    `Installed package: ${report.checks.installedPackage.status}`,
+    `Registry: ${report.checks.registry.status}`,
+    `Profiles: ${report.checks.profiles.status}`,
+    ...(report.issueCodes.length > 0 ? [`Issues: ${report.issueCodes.join(", ")}`] : []),
+    `Next: ${report.nextAllowedAction === "detect_profiles"
+      ? "owlrunkit profiles detect --workspace . --dry-run"
+      : report.nextAllowedAction}`,
+    "",
+  ].join("\n");
+}