@everfur/cli 0.2.0 → 0.4.1

package/dist/{chunk-S6UN7D2O.js → chunk-2MTX6YWO.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, offlineSuggestions, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, knownCodes, buildExplanationDocument, renderExplanation, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, buildSdkExplanationDocument, renderSdkExplanation, buildContractTableExplanationDocument, renderContractTableExplanation, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-CEWWBPPT.js';
+import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, checkTenantMode, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, resolveWithoutRegistry, knownCodes, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, registryAlsoIn, buildExplanationDocument, renderExplanation, alsoInLines, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, offlineDocument, renderOffline, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-EBVP6FAD.js';
 import { isAbsolute, resolve } from 'path';
 
 // src/cli/format.ts
@@ -186,6 +186,9 @@ function renderRefusal(document) {
     lines.push(`  ${fact.fact}`);
     lines.push(`    why:    ${fact.reason}`);
     lines.push(`    supply: ${fact.supplyWith}`);
+    if (fact.requiredWhen !== void 0) {
+      lines.push(`    only when: ${fact.requiredWhen.fact} is ${fact.requiredWhen.oneOf.join(" or ")}; answer it with that fact`);
+    }
   }
   lines.push("");
   lines.push(...renderDetected(document));
@@ -523,6 +526,14 @@ var CONTRACT_FLAG = Object.freeze({
   summary: "Path to a contract-public projection, used to explain any error code returned.",
   placeholder: "file"
 });
+var PLAN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection to plan from (its decision trees), read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
+var EXPLAIN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection whose error registry answers the code, read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
 var CONTRACT_ENV_VAR = "EVERFUR_CONTRACT_PUBLIC";
 var DEFAULT_CONTRACT_PATHS = Object.freeze([
   "contract-public/contract-public.json",
@@ -613,6 +624,7 @@ var POLL_DELAY_MS = 500;
 var MAX_ATTEMPTS = 20;
 var VERIFICATION_SCHEMA_VERSION = 1;
 var VERIFICATION_DOCUMENT_KIND = "everfur.verification";
+var WEB_EMBEDDINGS = Object.freeze(["in-page", "frame"]);
 var FLAGS = Object.freeze([
   BASE_URL_FLAG,
   {
@@ -630,9 +642,16 @@ var FLAGS = Object.freeze([
   {
     name: "origin",
     kind: "string",
-    summary: "For a web integration: the page origin (https://shop.example.com) the surface is embedded on. Adds the embed fence, CORS exposure, session policy and loader checks.",
+    summary: "For a framed web page (the loader and an iframe): the page origin (https://shop.example.com) the frame renders on. Adds the CORS preflight, embed fence, CORS exposure, session policy and loader checks. An in-page integration needs no --origin.",
     placeholder: "origin"
   },
+  {
+    // The same flag name `plan` takes for the same fact (the argv parser knows it as a value flag).
+    name: "embedding",
+    kind: "string",
+    summary: `With --origin: how the page embeds the surface, ${WEB_EMBEDDINGS.join(" or ")}. frame (the default without --project-root) runs every check; in-page (the SDK's React components in the page) reports the embed fence and the loader N/A, since only the frame uses them. Read from --project-root when not given.`,
+    placeholder: "mode"
+  },
   {
     name: "loader-url",
     kind: "string",
@@ -665,10 +684,12 @@ var FLAGS = Object.freeze([
 function buildVerificationDocument(verification, baseUrl, cliVersion) {
   const counts = { passed: 0, failed: 0, skipped: 0 };
   let gated = 0;
+  let notApplicable = 0;
   for (const entry of verification.steps) {
     if (entry.result === "PASS") counts.passed += 1;
     else if (entry.result === "FAIL") counts.failed += 1;
     else if (entry.result === "GATED") gated += 1;
+    else if (entry.result === "N/A") notApplicable += 1;
     else counts.skipped += 1;
   }
   return {
@@ -677,8 +698,9 @@ function buildVerificationDocument(verification, baseUrl, cliVersion) {
     generatedBy: { name: "@everfur/cli", version: cliVersion },
     status: verification.status,
     baseUrl,
-    // `gated` appears only when a step was GATED, so a document from a run with no surface checks is unchanged.
-    summary: gated === 0 ? counts : { ...counts, gated },
+    // `gated` appears only when a step was GATED, and `notApplicable` only when one was N/A, so a document from a run
+    // with neither is unchanged.
+    summary: { ...counts, ...gated === 0 ? {} : { gated }, ...notApplicable === 0 ? {} : { notApplicable } },
     steps: verification.steps.map((entry) => ({
       id: entry.id,
       title: entry.title,
@@ -709,6 +731,8 @@ function renderVerification(verification, baseUrl) {
     lines.push("Nothing failed, but a step was skipped, so the wire was not fully exercised.");
   } else if (verification.steps.some((entry) => entry.result === "GATED")) {
     lines.push("Nothing failed. A GATED step is a surface Everfur has not switched on for this tenant, not a fault in the integration.");
+  } else if (verification.steps.some((entry) => entry.result === "N/A")) {
+    lines.push("Nothing failed. An N/A step is a check that does not apply to this integration, and it was not run.");
   } else {
     lines.push(
       verification.steps.some((entry) => entry.id === "anonymous-identity") ? "Every step passed. The anonymous identity, the verdict read, and the verdict itself are all healthy." : "Every step passed. The session mint, the verdict read, and the verdict itself are all healthy."
@@ -716,6 +740,12 @@ function renderVerification(verification, baseUrl) {
   }
   return lines.join("\n");
 }
+function parseEmbedding2(raw) {
+  if (raw === null) return { value: null, errors: [] };
+  const value = raw.trim();
+  const known2 = WEB_EMBEDDINGS.find((embedding) => embedding === value);
+  return known2 === void 0 ? { value: null, errors: [`--embedding must be ${WEB_EMBEDDINGS.join(" or ")}, not "${raw}"`] } : { value: known2, errors: [] };
+}
 function parseAttempts(raw) {
   if (raw === null) return { value: DEFAULT_ATTEMPTS, errors: [] };
   const parsed = Number(raw.trim());
@@ -730,7 +760,7 @@ function parseAttempts(raw) {
 var verifyCommand = {
   path: ["verify"],
   summary: "Exercise the wire: mint a session, read the verdict, assert it is not empty.",
-  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
+  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--embedding <mode>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
   flags: FLAGS,
   /**
    * Exactly what `mintSession` resolves: the session token first, else the key pair it mints with locally. Without
@@ -741,6 +771,7 @@ var verifyCommand = {
     const attempts = parseAttempts(flags.string("attempts"));
     const originFlag = flags.string("origin");
     const origin = originFlag === null ? { origin: null, error: null } : parseOrigin(originFlag);
+    const embedding = parseEmbedding2(flags.string("embedding"));
     const loaderFlag = flags.string("loader-url");
     const loader = loaderFlag === null ? { url: null, error: null } : parseLoaderUrl(loaderFlag);
     const surfaces = parseSurfaces(flags.string("surfaces"));
@@ -751,6 +782,7 @@ var verifyCommand = {
     const flagErrors = [
       ...attempts.errors,
       ...origin.error === null ? [] : [origin.error],
+      ...embedding.errors,
       ...loader.error === null ? [] : [loader.error],
       ...surfaces.errors,
       ...identityMode.errors,
@@ -771,6 +803,7 @@ var verifyCommand = {
       attempts: attempts.value,
       pollDelayMs: POLL_DELAY_MS,
       origin: origin.origin,
+      embedding: embedding.value,
       loaderUrl: loader.url,
       transport: context.transport,
       surfaces: surfaces.value ?? [],
@@ -826,7 +859,7 @@ var FLAGS2 = Object.freeze([
     summary: `The Everfur deployment the generated configuration targets: ${ENVIRONMENTS.join(", ")}. Required for a plan that writes configuration; never assumed.`,
     placeholder: "name"
   },
-  CONTRACT_FLAG
+  PLAN_CONTRACT_FLAG
 ]);
 function asJsonObject(document) {
   return JSON.parse(JSON.stringify(document));
@@ -912,8 +945,10 @@ var planCommand = {
         ...environment.errors
       ]);
     }
+    const mode = await checkTenantMode({ env: context.env, environment: environment.value, transport: context.transport, clock: context.clock });
+    if (mode.kind === "mismatch") return errorOutcome("usage_error", mode.message, mode.details);
     const detection = detectProject(context.fs, root);
-    const document = planIntegration({
+    const planned = planIntegration({
       detection,
       capabilities: supplied.capabilities,
       allCapabilities: supplied.allCapabilities,
@@ -924,6 +959,7 @@ var planCommand = {
       space,
       cliVersion: context.version
     });
+    const document = mode.kind === "not_checked" && planned.status === "ready" ? Object.freeze({ ...planned, warnings: Object.freeze([...planned.warnings, mode.warning]) }) : planned;
     const json = asJsonObject(document);
     const text = renderPlan(document);
     if (document.status === "underspecified") return fail(ExitCode.UNDERSPECIFIED, json, text);
@@ -1115,7 +1151,7 @@ var diagnoseCommand = {
 };
 
 // src/commands/explain-error/index.ts
-var FLAGS5 = Object.freeze([CONTRACT_FLAG]);
+var FLAGS5 = Object.freeze([EXPLAIN_CONTRACT_FLAG]);
 var POSITIONALS = Object.freeze([
   {
     name: "code",
@@ -1136,7 +1172,7 @@ var explainErrorCommand = {
       return errorOutcome("usage_error", "no error code was given", ["usage: everfur explain-error <code>"]);
     }
     const offline = resolveOffline(code);
-    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version);
+    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version, "no_registry");
     const contractFlag = flags.string("contract");
     const contractPath = findContractPath(context, contractFlag);
     let load;
@@ -1148,10 +1184,13 @@ var explainErrorCommand = {
         ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
       });
       if (fetched.kind === "unavailable") {
-        if (offline !== null) return offlineOutcome(offline, context.version);
-        const suggestions = offlineSuggestions(code);
-        return contractUnavailableOutcome(fetched, [
-          ...suggestions.length > 0 ? [`did you mean: ${suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no code similar to "${code}" exists in the SDK taxonomy or the SDK contract table this CLI carries`]
+        const resolved = resolveWithoutRegistry(code);
+        if (resolved.kind !== "unknown") return offlineOutcome(resolved, context.version, "no_registry");
+        return errorOutcome("unknown_error_code", `"${code}" is not a code this CLI knows`, [
+          ...resolved.suggestions.length > 0 ? [`did you mean: ${resolved.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no similar code exists in the ${knownCodes(null).length} codes this CLI carries`],
+          "searched: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums",
+          `the live error registry was not read (${fetched.message}); it can list a code these tables predate:`,
+          ...fetched.details.filter((detail) => detail.startsWith("export "))
         ]);
       }
       load = loadErrorRegistryFromContract(fetched.contract);
@@ -1168,11 +1207,11 @@ var explainErrorCommand = {
     const entry = load.registry.lookup(code);
     if (entry === null) {
       const fallback = resolveAfterRegistryMiss(code, load.registry);
-      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version);
+      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version, "registry_miss");
       return errorOutcome("unknown_error_code", `"${code}" is not in the error registry`, [
         ...fallback.suggestions.length > 0 ? [`did you mean: ${fallback.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : ["no similar code exists in the registry"],
         `the registry loaded from ${load.path} lists ${load.registry.codes.length} codes`,
-        `neither the SDK taxonomy nor the SDK contract table this CLI carries knows it either (${knownCodes(load.registry).length} codes searched in all)`
+        `no other table this CLI carries knows it either: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums (${knownCodes(load.registry).length} codes searched in all)`
       ]);
     }
     const input = {
@@ -1181,11 +1220,13 @@ var explainErrorCommand = {
       digest: load.digest,
       cliVersion: context.version
     };
-    return succeed(buildExplanationDocument(input), renderExplanation(input));
+    const document = { ...buildExplanationDocument(input), ...registryAlsoIn(code) };
+    return succeed(document, [renderExplanation(input), ...alsoInLines(document)].join("\n"));
   }
 };
-function offlineOutcome(resolution, cliVersion) {
-  return resolution.kind === "sdk_member" ? succeed(buildSdkExplanationDocument(resolution.code, cliVersion), renderSdkExplanation(resolution.code)) : succeed(buildContractTableExplanationDocument(resolution.row, cliVersion), renderContractTableExplanation(resolution.row));
+function offlineOutcome(resolution, cliVersion, context) {
+  const document = offlineDocument(resolution, cliVersion, context);
+  return succeed(document, renderOffline(resolution, document, context));
 }
 function contractOutcome2(outcome) {
   switch (outcome.kind) {
@@ -1233,7 +1274,11 @@ var FLAGS6 = Object.freeze([
 ]);
 var sandboxCreateCommand = {
   path: ["sandbox", "create"],
-  summary: "Provision a partner secret key and return a claim URL. Never prints the secret.",
+  /**
+   * What the command does TODAY (ROADMAP.md), not the designed claim flow: the live route returns the secret inline and
+   * no claim URL, so the key is revoked unread and the command exits 8 (SECRET_UNCLAIMABLE).
+   */
+  summary: "Everfur-internal. Mints a partner secret key and, because no claim flow exists to hand it over safely, revokes it again and exits 8. Never prints the secret.",
   usage: "sandbox create --client <client-id> [--label <text>] [--base-url <url>] [--json]",
   flags: FLAGS6,
   /** The one credential this command resolves. It never reads a partner key of either kind. */
@@ -1357,20 +1402,14 @@ function parseArgv(argv) {
   const path = [];
   const flags = /* @__PURE__ */ new Map();
   const errors = [];
-  let sawFlag = false;
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === void 0) continue;
     if (token === "--") break;
     if (!isFlagToken(token)) {
-      if (sawFlag) {
-        errors.push(`unexpected argument "${token}" after flags began`);
-      } else {
-        path.push(token);
-      }
+      path.push(token);
       continue;
     }
-    sawFlag = true;
     const equalsAt = token.indexOf("=");
     const rawName = equalsAt === -1 ? token : token.slice(0, equalsAt);
     const inlineValue = equalsAt === -1 ? null : token.slice(equalsAt + 1);
@@ -1477,7 +1516,7 @@ function renderRootHelp(commands, version) {
   lines.push("", "Global flags");
   for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
   lines.push("    --version".padEnd(FLAG_COLUMN) + "Print the CLI version.");
-  lines.push(...environmentBlock(CREDENTIAL_SPECS));
+  lines.push(...environmentBlock(CREDENTIAL_SPECS, "all"));
   lines.push(
     "",
     "Not in this release",
@@ -1486,9 +1525,10 @@ function renderRootHelp(commands, version) {
   );
   return lines.join("\n");
 }
-function environmentBlock(specs) {
+function environmentBlock(specs, baseUrlFlag) {
   const lines = ["", "Environment"];
-  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + "API base URL. Overridden by --base-url.");
+  const override = baseUrlFlag === "all" ? " Overridden by --base-url on the commands that take it." : baseUrlFlag ? " Overridden by --base-url." : "";
+  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + `API base URL.${override}`);
   for (const spec of specs) {
     lines.push(`    ${spec.envVar}`.padEnd(FLAG_COLUMN) + spec.summary);
   }
@@ -1521,7 +1561,9 @@ function renderCommandHelp(command) {
   lines.push("", "Global flags");
   for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
   const credentials = command.credentials ?? [];
-  if (credentials.length > 0) lines.push(...environmentBlock(credentials));
+  if (credentials.length > 0) {
+    lines.push(...environmentBlock(credentials, command.flags.some((spec) => spec.name === "base-url")));
+  }
   return lines.join("\n");
 }
 
@@ -1561,8 +1603,10 @@ async function runCli(options) {
   const specs = match.command.positionals ?? [];
   if (positionals.length > specs.length) {
     const surplus = positionals[specs.length] ?? "";
+    const flagErrors = bindFlags(match.command.flags, parsed);
     return formatOutcome(
       errorOutcome("usage_error", `unexpected argument "${surplus}" after "${commandName(match.command)}"`, [
+        ...flagErrors.ok ? [] : flagErrors.errors,
         `usage: everfur ${match.command.usage}`
       ]),
       format

package/dist/{chunk-TBFOL2D3.js → chunk-A2QEBO5U.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { buildServer } from './chunk-WCH6AI6K.js';
+import { buildServer } from './chunk-QCXZJW5C.js';
 import { createServer } from 'http';
 import { timingSafeEqual } from 'crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';