owlrunkit 0.13.0 → 0.15.0

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

@@ -0,0 +1,510 @@
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  readWorkspaceJsonBounded,
+  resolveBoundedWorkspaceRoot,
+} from "./onboarding-doctor.mjs";
+import { resolveProfileImpactDetailed } from "./profile-impact.mjs";
+import {
+  safeIdentifier,
+  safeRelativePath,
+} from "./provenance-common.mjs";
+
+function resolveRegularExecutable(name) {
+  const pathEntries = (process.env.PATH ?? "").split(path.delimiter);
+  const suffixes = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
+    : [""];
+  for (const directory of pathEntries) {
+    for (const suffix of suffixes) {
+      const candidate = path.resolve(directory || ".", `${name}${suffix}`);
+      try {
+        const resolved = realpathSync(candidate);
+        const stat = lstatSync(resolved);
+        if (stat.isFile() && !stat.isSymbolicLink()) return resolved;
+      } catch {
+        // Continue through PATH without treating a missing or unsafe entry as authority.
+      }
+    }
+  }
+  return null;
+}
+
+function command(id, script, executable) {
+  return {
+    id,
+    cwd: ".",
+    executable,
+    argv: ["run", script],
+  };
+}
+
+function workspaceCommand(id, workspacePath, script, executable) {
+  return {
+    id,
+    cwd: ".",
+    executable,
+    argv: ["run", "--workspace", workspacePath, script],
+  };
+}
+
+function detectedScripts(manifest) {
+  return Object.keys(manifest.scripts ?? {}).sort();
+}
+
+function workspacePatterns(manifest) {
+  if (Array.isArray(manifest.workspaces)) return manifest.workspaces;
+  if (
+    manifest.workspaces
+    && typeof manifest.workspaces === "object"
+    && Array.isArray(manifest.workspaces.packages)
+  ) {
+    return manifest.workspaces.packages;
+  }
+  return [];
+}
+
+function safeWorkspacePattern(value) {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || path.isAbsolute(value)
+    || value.includes("\\")
+    || value.includes("\0")
+  ) {
+    return null;
+  }
+  const segments = value.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    return null;
+  }
+  const wildcardCount = [...value].filter((character) => character === "*").length;
+  if (wildcardCount === 0) return { kind: "literal", path: value };
+  if (wildcardCount === 1 && value.endsWith("/*")) {
+    return { kind: "children", path: value.slice(0, -2) };
+  }
+  return null;
+}
+
+function discoverWorkspaces(root, manifest) {
+  const warnings = [];
+  const paths = new Set();
+  for (const rawPattern of workspacePatterns(manifest)) {
+    const pattern = safeWorkspacePattern(rawPattern);
+    if (pattern === null) {
+      warnings.push(`unsupported_workspace_pattern:${String(rawPattern)}`);
+      continue;
+    }
+    if (pattern.kind === "literal") {
+      paths.add(pattern.path);
+      continue;
+    }
+    const parent = path.join(root, pattern.path);
+    try {
+      const parentStat = lstatSync(parent);
+      if (
+        parentStat.isSymbolicLink()
+        || !parentStat.isDirectory()
+        || realpathSync(parent) !== path.resolve(parent)
+      ) {
+        warnings.push(`unsafe_workspace_parent:${pattern.path}`);
+        continue;
+      }
+      for (const entry of readdirSync(parent, { withFileTypes: true })
+        .sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+          paths.add(`${pattern.path}/${entry.name}`);
+        }
+      }
+    } catch {
+      // A declared workspace pattern may legitimately have no current matches.
+    }
+  }
+
+  const workspaces = [];
+  for (const workspacePath of [...paths].sort()) {
+    try {
+      const workspaceManifest = readWorkspaceJsonBounded(
+        root,
+        path.join(workspacePath, "package.json"),
+      );
+      workspaces.push({
+        name: typeof workspaceManifest.name === "string"
+          ? workspaceManifest.name
+          : workspacePath,
+        path: workspacePath,
+        scripts: detectedScripts(workspaceManifest),
+      });
+    } catch {
+      warnings.push(`workspace_manifest_unreadable:${workspacePath}`);
+    }
+  }
+  return {
+    workspaces,
+    warnings: [...new Set(warnings)].sort(),
+  };
+}
+
+function profileIdForWorkspace(workspacePath) {
+  return `workspace-${workspacePath.replace(/[^A-Za-z0-9._-]+/g, "-")}`;
+}
+
+function workspaceProfiles(workspaces, npmExecutable) {
+  return workspaces
+    .map((workspace) => {
+      const qualityScripts = workspace.scripts.filter((script) =>
+        ["build", "e2e", "lint", "test", "typecheck"].includes(script));
+      if (qualityScripts.length === 0) return null;
+      const profileId = profileIdForWorkspace(workspace.path);
+      return {
+        id: profileId,
+        paths: [`${workspace.path}/**`],
+        role: "primary",
+        primary: false,
+        requiresProfileIds: [],
+        commands: npmExecutable
+          ? qualityScripts.map((script) => workspaceCommand(
+              `npm-${profileId}-${script}`,
+              workspace.path,
+              script,
+              npmExecutable,
+            ))
+          : [],
+      };
+    })
+    .filter(Boolean);
+}
+
+function profileCandidates(root, manifest, npmExecutable, workspaces) {
+  const scripts = new Set(detectedScripts(manifest));
+  const candidates = [];
+  if (
+    existsSync(path.join(root, "prisma"))
+    || [...scripts].some((script) => /^(db:|prisma)/.test(script))
+  ) {
+    const commands = [...scripts]
+      .filter((script) => /^(db:|prisma)/.test(script))
+      .map((script) => npmExecutable
+        ? command(`npm-${script.replaceAll(":", "-")}`, script, npmExecutable)
+        : null)
+      .filter(Boolean);
+    candidates.push({
+      id: "database",
+      paths: ["prisma/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  if (
+    existsSync(path.join(root, "package.json"))
+    && [...scripts].some((script) => ["build", "lint", "test", "typecheck"].includes(script))
+  ) {
+    const commands = ["build", "lint", "test", "typecheck"]
+      .filter((script) => scripts.has(script))
+      .map((script) => npmExecutable ? command(`npm-${script}`, script, npmExecutable) : null)
+      .filter(Boolean);
+    candidates.push({
+      id: "node-quality",
+      paths: ["src/**", "tests/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  if (
+    existsSync(path.join(root, "playwright.config.ts"))
+    || existsSync(path.join(root, "playwright.config.js"))
+    || scripts.has("e2e")
+  ) {
+    const commands = scripts.has("e2e") && npmExecutable
+      ? [command("npm-e2e", "e2e", npmExecutable)]
+      : [];
+    candidates.push({
+      id: "web-e2e",
+      paths: ["playwright.config.ts", "tests/e2e/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  candidates.push(...workspaceProfiles(workspaces, npmExecutable));
+  return candidates.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function detectProfiles({ workspaceRoot } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const manifest = readWorkspaceJsonBounded(root, "package.json");
+  const npmExecutable = resolveRegularExecutable("npm");
+  const discovered = discoverWorkspaces(root, manifest);
+  const candidates = profileCandidates(root, manifest, npmExecutable, discovered.workspaces);
+  const primaryCandidates = candidates.filter((profile) => profile.role === "primary");
+  const warnings = primaryCandidates.length > 1
+    ? [`ambiguous_primary_profile:${primaryCandidates.map((profile) => profile.id).join(",")}`]
+    : [];
+  warnings.push(...discovered.warnings);
+  if (
+    npmExecutable === null
+    && (
+      detectedScripts(manifest).some((script) =>
+        /^(build|db:|e2e|lint|prisma|test|typecheck)/.test(script))
+      || discovered.workspaces.some((workspace) => workspace.scripts.some((script) =>
+        /^(build|e2e|lint|test|typecheck)$/.test(script)))
+    )
+  ) {
+    warnings.push("npm_regular_executable_unavailable");
+  }
+  return {
+    schemaVersion: "OwlCodaRunKitProfileDetectionV1",
+    status: "profiles_detected",
+    dryRun: true,
+    writesPerformed: 0,
+    candidates,
+    primaryProfileId: primaryCandidates.length === 1 ? primaryCandidates[0].id : null,
+    warnings,
+    detectedScripts: detectedScripts(manifest),
+    detectedWorkspaces: discovered.workspaces,
+    authorizationGranted: false,
+  };
+}
+
+function exactKeys(value, allowed) {
+  return value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function representativePath(rule) {
+  return rule.endsWith("/**")
+    ? `${rule.slice(0, -3)}/__owlrunkit_profile_surface__`
+    : rule;
+}
+
+function validateProfileDocument(config) {
+  const issues = [];
+  if (
+    !exactKeys(config, ["schemaVersion", "profiles"])
+    || config.schemaVersion !== "OwlCodaRunKitProfilesV1"
+    || !Array.isArray(config.profiles)
+    || config.profiles.length === 0
+  ) {
+    return ["profiles_document_invalid"];
+  }
+
+  const ids = new Set();
+  const commandIds = new Set();
+  for (const profile of config.profiles) {
+    if (!exactKeys(profile, [
+      "commands",
+      "id",
+      "paths",
+      "primary",
+      "requiresProfileIds",
+      "role",
+    ])) {
+      issues.push("profile_shape_invalid");
+      continue;
+    }
+    if (typeof profile.id !== "string" || profile.id.length === 0) {
+      issues.push("profile_id_invalid");
+    } else if (ids.has(profile.id)) {
+      issues.push(`duplicate_profile_id:${profile.id}`);
+    } else {
+      ids.add(profile.id);
+    }
+    if (!Array.isArray(profile.paths) || profile.paths.length === 0) {
+      issues.push(`profile_paths_missing:${profile.id ?? "unknown"}`);
+    }
+    if (profile.role !== undefined && !["primary", "supporting"].includes(profile.role)) {
+      issues.push(`profile_role_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (profile.primary !== undefined && typeof profile.primary !== "boolean") {
+      issues.push(`profile_primary_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (
+      profile.requiresProfileIds !== undefined
+      && (
+        !Array.isArray(profile.requiresProfileIds)
+        || profile.requiresProfileIds.some((id) => typeof id !== "string" || id.length === 0)
+        || new Set(profile.requiresProfileIds).size !== profile.requiresProfileIds.length
+      )
+    ) {
+      issues.push(`profile_requirements_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (profile.commands !== undefined) {
+      if (!Array.isArray(profile.commands)) {
+        issues.push(`profile_commands_invalid:${profile.id ?? "unknown"}`);
+      } else {
+        for (const entry of profile.commands) {
+          if (
+            !exactKeys(entry, ["argv", "cwd", "executable", "id"])
+            || typeof entry.id !== "string"
+            || entry.id.length === 0
+            || typeof entry.cwd !== "string"
+            || entry.cwd.length === 0
+            || typeof entry.executable !== "string"
+            || entry.executable.length === 0
+            || !Array.isArray(entry.argv)
+            || entry.argv.some((argument) => typeof argument !== "string" || argument.length === 0)
+          ) {
+            issues.push(`profile_command_invalid:${profile.id ?? "unknown"}`);
+            break;
+          }
+          try {
+            safeIdentifier(entry.id, "profile command id");
+          } catch {
+            issues.push(`profile_command_id_invalid:${profile.id}:${entry.id}`);
+          }
+          try {
+            safeRelativePath(entry.cwd, "profile command cwd", { allowDot: true });
+          } catch {
+            issues.push(`profile_command_cwd_invalid:${profile.id}:${entry.id}`);
+          }
+          if (commandIds.has(entry.id)) {
+            issues.push(`duplicate_profile_command_id:${entry.id}`);
+          } else {
+            commandIds.add(entry.id);
+          }
+        }
+      }
+    }
+  }
+  if (issues.length > 0) return [...new Set(issues)].sort();
+
+  try {
+    const changedPaths = config.profiles.flatMap((profile) =>
+      profile.paths.map(representativePath));
+    resolveProfileImpactDetailed({ changedPaths, profiles: config.profiles });
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+  }
+
+  for (const profile of config.profiles) {
+    for (const requiredId of profile.requiresProfileIds ?? []) {
+      if (!ids.has(requiredId)) {
+        issues.push(`required_profile_missing:${profile.id}:${requiredId}`);
+      }
+    }
+  }
+  const actionable = config.profiles.filter((profile) =>
+    (profile.role ?? "primary") === "primary"
+    && Array.isArray(profile.commands)
+    && profile.commands.length > 0);
+  if (actionable.length === 0) issues.push("actionable_primary_profile_missing");
+  const explicitPrimaryIds = actionable
+    .filter((profile) => profile.primary === true)
+    .map((profile) => profile.id)
+    .sort();
+  if (explicitPrimaryIds.length > 1) {
+    issues.push(`ambiguous_primary_profile:${explicitPrimaryIds.join(",")}`);
+  } else if (explicitPrimaryIds.length === 0 && actionable.length > 1) {
+    issues.push(`ambiguous_primary_profile:${actionable.map((profile) => profile.id).sort().join(",")}`);
+  }
+  return [...new Set(issues)].sort();
+}
+
+export function validateProfiles({ workspaceRoot } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const issues = [];
+  let profileIds = [];
+  try {
+    const config = readWorkspaceJsonBounded(
+      root,
+      path.join(".owlcoda", "runkit", "profiles.json"),
+    );
+    profileIds = Array.isArray(config.profiles)
+      ? config.profiles
+        .map((profile) => profile?.id)
+        .filter((id) => typeof id === "string")
+        .sort()
+      : [];
+    issues.push(...validateProfileDocument(config));
+    if (issues.length === 0) {
+      const detected = detectProfiles({ workspaceRoot: root });
+      const detectedPaths = detected.candidates.flatMap((profile) =>
+        profile.paths.map(representativePath));
+      if (detectedPaths.length > 0) {
+        const impact = resolveProfileImpactDetailed({
+          changedPaths: detectedPaths,
+          profiles: config.profiles,
+        });
+        issues.push(...impact.uncoveredPaths.map((value) =>
+          `uncovered_detected_surface:${value}`));
+        issues.push(...impact.warnings
+          .filter((warning) => warning.startsWith("supporting_only_match:"))
+          .map((warning) => `detected_surface_${warning}`));
+      }
+    }
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+  }
+  const valid = issues.length === 0;
+  return {
+    schemaVersion: "OwlCodaRunKitProfilesValidationV1",
+    status: valid ? "valid" : "invalid",
+    valid,
+    exitCode: valid ? 0 : 2,
+    profileIds,
+    issues: [...new Set(issues)].sort(),
+    authorizationGranted: false,
+  };
+}
+
+export function resolveProfilesImpact({ workspaceRoot, changedPaths } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const config = readWorkspaceJsonBounded(
+    root,
+    path.join(".owlcoda", "runkit", "profiles.json"),
+  );
+  const documentIssues = validateProfileDocument(config);
+  if (documentIssues.length > 0) {
+    return {
+      schemaVersion: "OwlCodaRunKitProfileImpactV1",
+      status: "profile_impact_blocked",
+      valid: false,
+      exitCode: 2,
+      changedPaths: [...new Set(changedPaths)].sort(),
+      decision: "invalid_profiles",
+      primaryProfileId: null,
+      directProfileIds: [],
+      transitiveProfileIds: [],
+      supportingProfileIds: [],
+      selectedProfileIds: [],
+      uncoveredPaths: [],
+      warnings: [],
+      issues: documentIssues,
+      authorizationGranted: false,
+    };
+  }
+  const impact = resolveProfileImpactDetailed({
+    changedPaths,
+    profiles: config.profiles,
+  });
+  const issues = [
+    ...impact.uncoveredPaths.map((value) => `uncovered_changed_path:${value}`),
+    ...impact.warnings.filter((warning) =>
+      warning.startsWith("supporting_only_match:")
+      || warning.startsWith("ambiguous_primary_profile:")),
+  ];
+  const valid = impact.decision === "targeted_profiles" && issues.length === 0;
+  return {
+    schemaVersion: "OwlCodaRunKitProfileImpactV1",
+    status: valid ? "profile_impact_resolved" : "profile_impact_blocked",
+    valid,
+    exitCode: valid ? 0 : 2,
+    changedPaths: [...new Set(changedPaths)].sort(),
+    ...impact,
+    issues: [...new Set(issues)].sort(),
+    authorizationGranted: false,
+  };
+}

package/scripts/runkit-contract/registry-adoption-gate.mjs

@@ -21,6 +21,45 @@ const RELEASE_EVIDENCE_FIELDS = Object.freeze([
   "version",
 ]);
 
+const STORED_EVIDENCE_FIELDS = Object.freeze([
+  "authorizationGranted",
+  "authority",
+  "decision",
+  "exactSpec",
+  "installedBinding",
+  "packageName",
+  "registryRelease",
+  "schemaVersion",
+  "status",
+  "version",
+]);
+
+const STORED_RELEASE_FIELDS = Object.freeze([
+  "integrity",
+  "packageName",
+  "registry",
+  "shasum",
+  "tarballUrl",
+  "version",
+]);
+
+const STORED_INSTALL_FIELDS = Object.freeze([
+  "integrity",
+  "packageName",
+  "requestedSpec",
+  "resolved",
+  "version",
+]);
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactFields(value, fields) {
+  return isRecord(value)
+    && Object.keys(value).sort().join("\n") === [...fields].sort().join("\n");
+}
+
 function decision(policy, issueCodes) {
   return {
     schemaVersion: "OwlCodaRunKitRegistryAdoptionDecisionV1",
@@ -32,12 +71,12 @@ function decision(policy, issueCodes) {
   };
 }
 
-function expectedTarballUrl(policy) {
-  const tarballName = policy.packageName.split("/").at(-1);
-  return `${OFFICIAL_NPM_REGISTRY}/${policy.packageName}/-/${tarballName}-${policy.candidateVersion}.tgz`;
+export function expectedRegistryTarballUrl(packageName, version) {
+  const tarballName = packageName.split("/").at(-1);
+  return `${OFFICIAL_NPM_REGISTRY}/${packageName}/-/${tarballName}-${version}.tgz`;
 }
 
-function validSha512Integrity(value) {
+export function isCanonicalSha512Integrity(value) {
   if (typeof value !== "string") return false;
   const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(value);
   if (!match) return false;
@@ -45,13 +84,88 @@ function validSha512Integrity(value) {
   return bytes.length === 64 && bytes.toString("base64") === match[1];
 }
 
+export function validateStoredRegistryAdoptionEvidence({
+  evidence,
+  packageName,
+  version,
+  localInstall,
+}) {
+  const issues = [];
+  const exactSpec = `${packageName}@${version}`;
+  const expectedTarball = expectedRegistryTarballUrl(packageName, version);
+  if (
+    !hasExactFields(evidence, STORED_EVIDENCE_FIELDS)
+    || evidence.schemaVersion !== "OwlCodaRunKitRegistryAdoptionEvidenceV1"
+    || evidence.status !== "adopted"
+    || evidence.decision !== "ELIGIBLE"
+    || evidence.packageName !== packageName
+    || evidence.version !== version
+    || evidence.exactSpec !== exactSpec
+    || evidence.authorizationGranted !== false
+  ) {
+    issues.push("adoption_evidence_invalid");
+  }
+  const release = evidence?.registryRelease;
+  if (
+    !hasExactFields(release, STORED_RELEASE_FIELDS)
+    || release.registry !== OFFICIAL_NPM_REGISTRY
+    || release.packageName !== packageName
+    || release.version !== version
+    || !/^[0-9a-f]{40}$/i.test(release.shasum)
+    || !isCanonicalSha512Integrity(release.integrity)
+    || release.tarballUrl !== expectedTarball
+  ) {
+    issues.push("adoption_registry_binding_invalid");
+  }
+  const installed = evidence?.installedBinding;
+  if (
+    !hasExactFields(installed, STORED_INSTALL_FIELDS)
+    || installed.requestedSpec !== exactSpec
+    || installed.packageName !== packageName
+    || installed.version !== version
+    || installed.integrity !== release?.integrity
+    || installed.resolved !== expectedTarball
+  ) {
+    issues.push("adoption_installed_binding_invalid");
+  }
+  if (
+    !hasExactFields(evidence?.authority, ["foreignProjectWrite", "git", "release"])
+    || evidence.authority.git !== false
+    || evidence.authority.release !== false
+    || evidence.authority.foreignProjectWrite !== false
+  ) {
+    issues.push("adoption_authority_invalid");
+  }
+  if (
+    localInstall !== undefined
+    && (
+      localInstall.status !== "bound"
+      || localInstall.requestedSpec !== exactSpec
+      || localInstall.packageName !== packageName
+      || localInstall.version !== version
+      || localInstall.integrity !== release?.integrity
+      || localInstall.resolved !== expectedTarball
+    )
+  ) {
+    issues.push("adoption_local_install_drift");
+  }
+  const issueCodes = [...new Set(issues)].sort();
+  return {
+    valid: issueCodes.length === 0,
+    issueCodes,
+  };
+}
+
 function validReleaseEvidence(policy, release) {
   if (
     policy.registry !== OFFICIAL_NPM_REGISTRY
     || Object.keys(release).sort().join("\n") !== RELEASE_EVIDENCE_FIELDS.join("\n")
-    || !/^[0-9a-f]{40}$/.test(release.shasum)
-    || !validSha512Integrity(release.integrity)
-    || release.tarballUrl !== expectedTarballUrl(policy)
+    || !/^[0-9a-f]{40}$/i.test(release.shasum)
+    || !isCanonicalSha512Integrity(release.integrity)
+    || release.tarballUrl !== expectedRegistryTarballUrl(
+      policy.packageName,
+      policy.candidateVersion,
+    )
   ) {
     return false;
   }