owlrunkit 0.13.0 → 0.14.0

package/scripts/runkit-contract/runkit-cli.mjs

@@ -66,6 +66,80 @@ import {
   exportOfflineReceipt,
   importOfflineReceipt,
 } from "./offline-store.mjs";
+import {
+  detectProfiles,
+  resolveProfilesImpact,
+  validateProfiles,
+} from "./profile-onboarding.mjs";
+import {
+  formatDoctorHuman,
+  runDoctor,
+} from "./onboarding-doctor.mjs";
+import {
+  formatAdoptionHuman,
+  runRegistryAdoption,
+} from "./registry-adoption.mjs";
+import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
+
+const TOP_LEVEL_HELP = `OwlRunKit 0.14.0
+
+Usage:
+  owlrunkit <command> [options]
+
+Start here:
+  owlrunkit doctor --workspace .
+  owlrunkit profiles detect --workspace . --dry-run
+  owlrunkit adopt --workspace . --exact owlrunkit@0.14.0
+
+Quick Verification
+  owlrunkit quick-verify --workspace . -- <command> [args...]
+  Low-risk, source-bound reusable evidence without writer leases or acceptance.
+
+Formal Delivery
+  owlrunkit start --workspace . --run-id <id> --goal <file> \\
+    --work-item <id> --owned-path <path>
+  Use for multi-writer, long-running, migration, integration, release, funds,
+  production, or formal acceptance work.
+
+Other onboarding commands:
+  owlrunkit profiles validate --workspace .
+  owlrunkit profiles impact --workspace . --changed <path>
+  owlrunkit inspect --workspace . --json
+
+Quick receipts cannot become Formal acceptance.
+Formal accepted does not grant Git or release authority.
+Those always require separate explicit authorization.
+`;
+
+function withHumanOutput(result, humanOutput) {
+  Object.defineProperty(result, "humanOutput", {
+    configurable: false,
+    enumerable: false,
+    value: humanOutput,
+    writable: false,
+  });
+  return result;
+}
+
+function onboardingProjection() {
+  return {
+    nextAllowedAction: "run_onboarding_diagnostics",
+    steps: [
+      {
+        id: "doctor",
+        command: "owlrunkit doctor --workspace .",
+      },
+      {
+        id: "profiles_detect",
+        command: "owlrunkit profiles detect --workspace . --dry-run",
+      },
+      {
+        id: "adopt_or_start",
+        command: "owlrunkit adopt --workspace . --exact owlrunkit@0.14.0 or owlrunkit start",
+      },
+    ],
+  };
+}
 
 function parseOptions(values, { multi = [], boolean = [] } = {}) {
   const options = {};
@@ -592,7 +666,25 @@ function closeoutGateRejected(runId, decision, issues) {
 }
 
 async function initialize(options) {
-  return initializeProjectRunKit({ workspaceRoot: workspace(options) });
+  const initialized = await initializeProjectRunKit({ workspaceRoot: workspace(options) });
+  const result = {
+    ...initialized,
+    onboarding: onboardingProjection(),
+    nextAllowedAction: "run_onboarding_diagnostics",
+  };
+  if (options.json === true) return result;
+  return withHumanOutput(
+    result,
+    [
+      `Initialized OwlRunKit ${result.core.coreVersion} in ${result.runtimeRoot}`,
+      "",
+      "Next:",
+      "1. owlrunkit doctor --workspace .",
+      "2. owlrunkit profiles detect --workspace . --dry-run",
+      "3. owlrunkit adopt --workspace . --exact owlrunkit@0.14.0 or owlrunkit start",
+      "",
+    ].join("\n"),
+  );
 }
 
 function plan(options) {
@@ -844,7 +936,7 @@ function inspect(options) {
           execution: executions.find(execution => execution.runId === requestedRunId),
         }
       : { mode: "summary" };
-  return { ...result, summary, view };
+  return { ...result, summary, view, onboarding: onboardingProjection() };
 }
 
 function closeout(options) {
@@ -1025,29 +1117,95 @@ function requestCommand(options, handler) {
 export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
   try {
     const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h") {
+      return withHumanOutput({
+        status: "help",
+        exitCode: 0,
+        authorizationGranted: false,
+      }, TOP_LEVEL_HELP);
+    }
+    if (command === "--version" || command === "-v") {
+      return withHumanOutput({
+        status: "version",
+        exitCode: 0,
+        version: "0.14.0",
+        authorizationGranted: false,
+      }, "owlrunkit 0.14.0\n");
+    }
     const separatorIndex = rest.indexOf("--");
     if (separatorIndex >= 0 && command !== "verify" && command !== "quick-verify") {
       throw new Error("Only runkit verify accepts an exact command after --.");
     }
     const optionValues = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
     const commandArgv = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
-    const nested = new Set(["lease", "delivery"]).has(command);
+    const nested = new Set(["lease", "delivery", "profiles"]).has(command);
     const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
     const options = parseOptions(nested ? nestedOptions : optionValues, {
-      multi: (command === "lease" && action === "acquire") || command === "start" ? ["owned-path"] : [],
+      multi: command === "profiles" && action === "impact"
+        ? ["changed"]
+        : (command === "lease" && action === "acquire") || command === "start"
+          ? ["owned-path"]
+          : [],
       boolean: command === "inspect"
         ? ["json", "verbose", "history"]
+        : command === "init"
+          ? ["json"]
+          : command === "doctor" || command === "adopt"
+            ? ["json"]
+          : command === "profiles"
+            ? ["json", "dry-run"]
         : new Set(["quick-verify", "quick-attest", "quick-metrics"]).has(command)
           ? ["json", "local"]
           : [],
     });
     if (command === "init") return await initialize(options);
+    if (command === "doctor") {
+      const timeoutMs = options["timeout-ms"] === undefined
+        ? 1_500
+        : Number.parseInt(options["timeout-ms"], 10);
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 25 || timeoutMs > 10_000) {
+        throw new Error("--timeout-ms must be an integer from 25 to 10000.");
+      }
+      const report = await runDoctor({
+        workspaceRoot: requireOption(options, "workspace"),
+        registryUrl: options.registry ?? OFFICIAL_NPM_REGISTRY,
+        timeoutMs,
+      });
+      report.exitCode = report.status === "ready" ? 0 : 2;
+      return options.json === true
+        ? report
+        : withHumanOutput(report, formatDoctorHuman(report));
+    }
+    if (command === "adopt") {
+      const result = await runRegistryAdoption({
+        workspaceRoot: requireOption(options, "workspace"),
+        exactSpec: requireOption(options, "exact"),
+      });
+      result.exitCode = result.status === "adopted" ? 0 : 2;
+      return options.json === true
+        ? result
+        : withHumanOutput(result, formatAdoptionHuman(result));
+    }
     if (command === "start") return startExecution(options);
     if (command === "plan") {
       const root = workspace(options);
       return withControlTransaction(root, () => plan(options));
     }
     if (command === "inspect") return inspect(options);
+    if (command === "profiles") {
+      const root = requireOption(options, "workspace");
+      if (action === "detect") {
+        if (options["dry-run"] !== true) throw new Error("profiles detect requires --dry-run.");
+        return detectProfiles({ workspaceRoot: root });
+      }
+      if (action === "validate") return validateProfiles({ workspaceRoot: root });
+      if (action === "impact") {
+        const changedPaths = options.changed ?? [];
+        if (changedPaths.length === 0) throw new Error("profiles impact requires --changed.");
+        return resolveProfilesImpact({ workspaceRoot: root, changedPaths });
+      }
+      throw new Error("Usage: owlrunkit profiles <detect|validate|impact> [options]");
+    }
     if (command === "lease") {
       const root = workspace(options);
       const runId = safeRunId(requireOption(options, "run-id"));
@@ -1184,7 +1342,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       return withControlTransaction(root, () => closeout(options));
     }
     if (command === "finish") return finishExecution(options);
-    throw new Error("Usage: runkit-cli.mjs <init|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|profiles|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
   } catch (error) {
     return {
       status: "invalid_input",
@@ -1209,6 +1367,16 @@ if (isDirectExecution(import.meta.url)) {
     ? parseOptions(argv.slice(1), { boolean: ["json", "verbose", "history"] })
     : null;
   const humanInspect = inspectOptions !== null && inspectOptions.json !== true;
-  process.stdout.write(humanInspect ? formatInspectHuman(result) : `${JSON.stringify(result)}\n`);
+  const onboardingHumanCommand = new Set(["init", "doctor", "adopt", "profiles"]).has(argv[0]);
+  const interactiveOnboarding = onboardingHumanCommand
+    && !argv.includes("--json")
+    && process.stdout.isTTY === true;
+  process.stdout.write(
+    typeof result.humanOutput === "string" && (!onboardingHumanCommand || interactiveOnboarding)
+      ? result.humanOutput
+      : humanInspect
+        ? formatInspectHuman(result)
+        : `${JSON.stringify(result)}\n`,
+  );
   process.exitCode = result.exitCode;
 }

package/scripts/runkit-contract/schemas/adoption-evidence-v1.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/registry-adoption-evidence-v1.json",
+  "title": "OwlCoda RunKit Registry Adoption Evidence V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "decision",
+    "packageName",
+    "version",
+    "exactSpec",
+    "registryRelease",
+    "installedBinding",
+    "authority",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitRegistryAdoptionEvidenceV1" },
+    "status": { "const": "adopted" },
+    "decision": { "const": "ELIGIBLE" },
+    "packageName": { "const": "owlrunkit" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "exactSpec": { "type": "string", "pattern": "^owlrunkit@[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "registryRelease": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["registry", "packageName", "version", "shasum", "integrity", "tarballUrl"],
+      "properties": {
+        "registry": { "const": "https://registry.npmjs.org" },
+        "packageName": { "const": "owlrunkit" },
+        "version": { "type": "string" },
+        "shasum": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "integrity": { "type": "string", "pattern": "^sha512-" },
+        "tarballUrl": { "type": "string", "pattern": "^https://registry\\.npmjs\\.org/owlrunkit/-/owlrunkit-[0-9]+\\.[0-9]+\\.[0-9]+\\.tgz$" }
+      }
+    },
+    "installedBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requestedSpec", "packageName", "version", "resolved", "integrity"],
+      "properties": {
+        "requestedSpec": { "type": "string" },
+        "packageName": { "const": "owlrunkit" },
+        "version": { "type": "string" },
+        "resolved": { "type": "string" },
+        "integrity": { "type": "string" }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["git", "release", "foreignProjectWrite"],
+      "properties": {
+        "git": { "const": false },
+        "release": { "const": false },
+        "foreignProjectWrite": { "const": false }
+      }
+    },
+    "authorizationGranted": { "const": false }
+  }
+}