run402 4.17.0 → 4.17.2

package/fixtures/buzz-v0.5.2-cli-capabilities.json

@@ -0,0 +1,93 @@
+{
+  "fixture_version": 1,
+  "fixture_id": "buzz-cli-v0.5.2-capabilities",
+  "purpose": "released_buzz_cli_capability_first_compatibility",
+  "buzz_release": {
+    "version": "0.5.2",
+    "release_tag": "v0.5.2",
+    "release_tag_commit": "3e48f1b2365d326ee1c9582448d86a99b44ecd5d",
+    "run402_change_required": false
+  },
+  "help_probes": [
+    {
+      "argv": ["buzz", "--help"],
+      "exit_code": 0,
+      "stdout_contains": [
+        "Buzz CLI — interact with a Buzz relay",
+        "users",
+        "social",
+        "Errors are JSON on stderr"
+      ]
+    },
+    {
+      "argv": ["buzz", "users", "get", "--help"],
+      "exit_code": 0,
+      "stdout_contains": [
+        "Usage: buzz users get",
+        "--pubkey",
+        "Omit for your own profile"
+      ]
+    },
+    {
+      "argv": ["buzz", "social", "publish", "--help"],
+      "exit_code": 0,
+      "stdout_contains": [
+        "Usage: buzz social publish",
+        "--content"
+      ]
+    },
+    {
+      "argv": ["buzz", "social", "event", "--help"],
+      "exit_code": 0,
+      "stdout_contains": [
+        "Usage: buzz social event",
+        "--event"
+      ]
+    }
+  ],
+  "version_probe": {
+    "argv": ["buzz", "--version"],
+    "supported": false,
+    "exit_code": 1,
+    "stderr_json": {
+      "error": "user_error",
+      "retryable": false
+    },
+    "message_contains": "unexpected argument '--version'"
+  },
+  "json_contract": {
+    "default_output_format": "json",
+    "users_get_success_stdout": {
+      "type": "array",
+      "empty_array_means": "public_self_profile_unverified",
+      "profile_pubkey_field": "pubkey"
+    },
+    "social_event_success_stdout": {
+      "type": "array",
+      "event_pubkey_field": "pubkey"
+    },
+    "error_stderr": {
+      "type": "object",
+      "required_fields": ["error", "message", "retryable"],
+      "stdout_is_empty": true
+    }
+  },
+  "managed_sidecar": {
+    "distribution": "bundled_with_buzz_desktop",
+    "session_discovery": "managed_agent_path",
+    "public_package_manager_install": false,
+    "repair_surface": "buzz_settings",
+    "repair_destination": "Buzz Desktop > Settings > Updates",
+    "repair_instruction": "Open Buzz Desktop > Settings > Updates, install the available Buzz update or reinstall Buzz Desktop if no update is offered, then restart this agent and rerun setup."
+  },
+  "public_self_observation": {
+    "argv": ["buzz", "users", "get"],
+    "requires_private_key_value_inspection": false,
+    "empty_or_malformed_result": "BUZZ_AGENT_TARGET_UNVERIFIED"
+  },
+  "write_surface_policy": {
+    "capability_probes_use_help_only": true,
+    "publish_is_never_invoked_by_doctor": true,
+    "event_read_requires_explicit_event_id_and_is_not_used_for_self_discovery": true
+  }
+}

package/fixtures/run402-buzz-doctor-v1-contract.json

@@ -0,0 +1,140 @@
+{
+  "schema_version": 1,
+  "contract_id": "run402.buzz-doctor.v1",
+  "mode": "buzz",
+  "canonical_invocation": [
+    "run402",
+    "--wallet",
+    "<profile>",
+    "doctor",
+    "--buzz",
+    "--buzz-agent",
+    "<npub-or-hex>"
+  ],
+  "flags": {
+    "mode": "--buzz",
+    "agent": "--buzz-agent",
+    "profile": "--wallet"
+  },
+  "check_order": [
+    "session_shell",
+    "node_runtime",
+    "run402_cli",
+    "buzz_cli",
+    "buzz_agent_target",
+    "run402_api",
+    "run402_console",
+    "buzz_relay",
+    "wallet_profile"
+  ],
+  "statuses": [
+    "ok",
+    "warning",
+    "blocked"
+  ],
+  "codes_by_check": {
+    "session_shell": [
+      "BUZZ_PREFLIGHT_SHELL_UNAVAILABLE"
+    ],
+    "node_runtime": [
+      "BUZZ_PREFLIGHT_NODE_UNAVAILABLE",
+      "BUZZ_PREFLIGHT_NODE_INCOMPATIBLE"
+    ],
+    "run402_cli": [
+      "BUZZ_PREFLIGHT_RUN402_UNAVAILABLE",
+      "BUZZ_PREFLIGHT_RUN402_INCOMPATIBLE",
+      "BUZZ_PREFLIGHT_RUN402_UPDATE_AVAILABLE"
+    ],
+    "buzz_cli": [
+      "BUZZ_PREFLIGHT_BUZZ_CLI_UNAVAILABLE",
+      "BUZZ_PREFLIGHT_BUZZ_CLI_INCOMPATIBLE"
+    ],
+    "buzz_agent_target": [
+      "BUZZ_AGENT_TARGET_REQUIRED",
+      "BUZZ_AGENT_TARGET_UNVERIFIED",
+      "BUZZ_AGENT_TARGET_MISMATCH"
+    ],
+    "run402_api": [
+      "BUZZ_PREFLIGHT_API_UNREACHABLE"
+    ],
+    "run402_console": [
+      "BUZZ_PREFLIGHT_CONSOLE_UNREACHABLE"
+    ],
+    "buzz_relay": [
+      "BUZZ_PREFLIGHT_RELAY_UNSAFE",
+      "BUZZ_PREFLIGHT_RELAY_UNREACHABLE"
+    ],
+    "wallet_profile": [
+      "BUZZ_PREFLIGHT_WALLET_PROFILE_REQUIRED",
+      "BUZZ_PREFLIGHT_WALLET_PROFILE_NOT_FOUND",
+      "BUZZ_PREFLIGHT_WALLET_PROFILE_MISMATCH"
+    ]
+  },
+  "next_action": {
+    "required_fields": [
+      "type",
+      "surface",
+      "command",
+      "why",
+      "safe_to_auto_execute",
+      "requires_approval",
+      "destructive",
+      "idempotent",
+      "spend_impact"
+    ],
+    "surfaces": [
+      "shell",
+      "buzz_chat",
+      "buzz_settings"
+    ],
+    "shell_required_fields": [
+      "argv"
+    ],
+    "non_shell_forbidden_fields": [
+      "argv",
+      "cwd"
+    ],
+    "cardinality_per_actionable_check": 1
+  },
+  "exit_behavior": {
+    "passed_or_warning_only": 0,
+    "completed_with_blocked_checks": 1,
+    "usage_error": 1,
+    "completed_report_stream": "stdout",
+    "usage_error_stream": "stderr"
+  },
+  "freshness": {
+    "max_age_seconds": 60,
+    "binding_fields": [
+      "contract_id",
+      "expected_subject_hex",
+      "wallet_profile",
+      "node_executable",
+      "run402_executable",
+      "relay_origin"
+    ]
+  },
+  "setup_rejection_codes": [
+    "BUZZ_PREFLIGHT_REPORT_INVALID",
+    "BUZZ_PREFLIGHT_REPORT_STALE",
+    "BUZZ_PREFLIGHT_REPORT_MISMATCH"
+  ],
+  "zero_mutation": {
+    "mutation_state": "not_started",
+    "forbidden": [
+      "buzz_event_publish",
+      "buzz_arbitrary_sign",
+      "run402_profile_create_or_select",
+      "run402_wallet_create",
+      "run402_identity_link_mutation",
+      "run402_faucet",
+      "run402_tier_mutation",
+      "run402_project_mutation",
+      "run402_deploy"
+    ],
+    "allowed_lossy_local_writes": [
+      "cli_update_cache",
+      "redacted_diagnostic_queue"
+    ]
+  }
+}

package/lib/buzz-doctor-contract.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 
-const CONTRACT_URL = new URL("../../buzz/fixtures/run402-buzz-doctor-v1-contract.json", import.meta.url);
+const CONTRACT_URL = new URL("../fixtures/run402-buzz-doctor-v1-contract.json", import.meta.url);
 
 export const BUZZ_DOCTOR_CONTRACT = deepFreeze(JSON.parse(readFileSync(CONTRACT_URL, "utf8")));
 export const BUZZ_DOCTOR_CONTRACT_ID = BUZZ_DOCTOR_CONTRACT.contract_id;

package/lib/buzz-doctor-contract.test.mjs

@@ -9,7 +9,9 @@ import {
   validateBuzzDoctorReport,
 } from "./buzz-doctor-contract.mjs";
 
-const FIXTURE = JSON.parse(readFileSync(new URL("../../buzz/fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url), "utf8"));
+const FIXTURE = JSON.parse(readFileSync(new URL("../fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url), "utf8"));
+const RELEASED_FIXTURE = JSON.parse(readFileSync(new URL("../../buzz/fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url), "utf8"));
+const RELEASED_CONTRACT = JSON.parse(readFileSync(new URL("../../buzz/fixtures/run402-buzz-doctor-v1-contract.json", import.meta.url), "utf8"));
 
 function shellAction() {
   return {
@@ -47,6 +49,11 @@ function passingReport(now) {
 }
 
 describe("Buzz doctor v1 frozen contract", () => {
+  it("packages byte-semantic copies of the released Buzz fixture and frozen doctor contract", () => {
+    assert.deepEqual(FIXTURE, RELEASED_FIXTURE);
+    assert.deepEqual(BUZZ_DOCTOR_CONTRACT, RELEASED_CONTRACT);
+  });
+
   it("freezes the ordered checks, flags, statuses, exit streams, freshness binding, and zero-mutation verdict", () => {
     assert.equal(BUZZ_DOCTOR_CONTRACT_ID, "run402.buzz-doctor.v1");
     assert.deepEqual(BUZZ_DOCTOR_CHECK_ORDER, [

package/lib/buzz-doctor.mjs

@@ -15,7 +15,7 @@ import {
 } from "./buzz-doctor-contract.mjs";
 
 const BUZZ_CAPABILITIES = JSON.parse(readFileSync(
-  new URL("../../buzz/fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url),
+  new URL("../fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url),
   "utf8",
 ));
 
@@ -42,7 +42,10 @@ export const BUZZ_DOCTOR_REPAIR_MATRIX = Object.freeze({
   BUZZ_PREFLIGHT_API_UNREACHABLE: { type: "restore_run402_api_access", surface: "buzz_settings" },
   BUZZ_PREFLIGHT_CONSOLE_UNREACHABLE: { type: "restore_run402_console_access", surface: "buzz_settings" },
   BUZZ_PREFLIGHT_RELAY_UNSAFE: { type: "repair_buzz_relay_url", surface: "buzz_settings" },
-  BUZZ_PREFLIGHT_RELAY_UNREACHABLE: { type: "restore_buzz_relay_access", surface: "buzz_settings" },
+  BUZZ_PREFLIGHT_RELAY_UNREACHABLE: {
+    type: ["repair_buzz_relay_tls", "repair_buzz_relay_dns", "repair_buzz_relay_service", "restore_buzz_relay_access"],
+    surface: "buzz_settings",
+  },
   BUZZ_PREFLIGHT_WALLET_PROFILE_REQUIRED: { type: "rerun_buzz_setup_with_explicit_identity", surface: "buzz_chat" },
   BUZZ_PREFLIGHT_WALLET_PROFILE_NOT_FOUND: { type: "create_buzz_wallet_profile", surface: "shell" },
   BUZZ_PREFLIGHT_WALLET_PROFILE_MISMATCH: { type: "rerun_buzz_doctor", surface: "shell" },
@@ -343,9 +346,11 @@ async function checkBuzzRelay({ relay, lookup, pinnedRelayRead }) {
         failure: error.message,
       });
     }
-    return blocked("buzz_relay", "BUZZ_PREFLIGHT_RELAY_UNREACHABLE", "The configured safe Buzz relay did not complete its bounded public read.", relayReachabilityRepair(relay.origin), {
+    const failure = safeFailure(error);
+    return warning("buzz_relay", "BUZZ_PREFLIGHT_RELAY_UNREACHABLE", "The configured Buzz relay is safe to probe but unavailable; founder-agent setup may continue without community installation or enrollment.", relayAvailabilityRepair(relay.origin, failure), {
       origin: relay.origin,
-      failure: safeFailure(error),
+      failure,
+      community_operations: "unavailable",
     });
   }
 }
@@ -686,12 +691,36 @@ function relayUnsafeRepair() {
   });
 }
 
-function relayReachabilityRepair(origin) {
+function relayAvailabilityRepair(origin, failure) {
+  if (failure === "tls_handshake_failed") {
+    return nonShellAction({
+      type: "repair_buzz_relay_tls",
+      surface: "buzz_settings",
+      command: `Ask the Buzz community operator to provision a valid TLS certificate and public hostname route for ${origin}; after the endpoint completes verified TLS, restart this agent and rerun Run402 setup.`,
+      why: "Reconnect cannot repair a relay hostname whose public TLS handshake fails; community installation and enrollment stay unavailable until the endpoint is fixed.",
+    });
+  }
+  if (failure === "dns") {
+    return nonShellAction({
+      type: "repair_buzz_relay_dns",
+      surface: "buzz_settings",
+      command: `Ask the Buzz community operator to publish working public DNS for ${origin}; after the hostname resolves publicly, restart this agent and rerun Run402 setup.`,
+      why: "Community installation and enrollment require a publicly resolvable relay, while founder-agent setup remains independent.",
+    });
+  }
+  if (failure.startsWith("http_") || failure === "nip11_invalid" || failure === "redirect_rejected" || failure === "response_too_large") {
+    return nonShellAction({
+      type: "repair_buzz_relay_service",
+      surface: "buzz_settings",
+      command: `Ask the Buzz community operator to restore the public NIP-11 endpoint at ${origin}; after it returns a bounded non-redirecting JSON response, restart this agent and rerun Run402 setup.`,
+      why: "Community installation and enrollment require the relay's public NIP-11 service, while founder-agent setup remains independent.",
+    });
+  }
   return nonShellAction({
     type: "restore_buzz_relay_access",
     surface: "buzz_settings",
-    command: `Open Buzz Desktop > Settings > Communities, reconnect the current community relay ${origin}, restart this agent, then rerun Run402 setup.`,
-    why: "The current safe relay must complete a bounded public NIP-11 read before setup can proceed.",
+    command: `Ask the Buzz community operator to restore public relay access at ${origin}; after the endpoint is reachable, restart this agent and rerun Run402 setup.`,
+    why: "Community installation and enrollment require a live public relay, while founder-agent setup remains independent.",
   });
 }
 
@@ -777,11 +806,13 @@ function safeOrigin(value) {
 
 function safeFailure(error) {
   if (error?.name === "AbortError") return "timeout";
-  const message = error instanceof Error ? error.message : String(error);
-  if (/certificate|tls|ssl/i.test(message)) return "tls";
-  if (/dns|getaddrinfo|enotfound/i.test(message)) return "dns";
+  const message = error instanceof Error ? `${error.message} ${error.code ?? ""} ${error.cause?.message ?? ""} ${error.cause?.code ?? ""}` : String(error);
+  if (/certificate|tls|ssl|eproto|secure tls connection|handshake/i.test(message)) return "tls_handshake_failed";
+  if (/dns|dns_empty|getaddrinfo|enotfound|eai_again/i.test(message)) return "dns";
   if (/timeout|timed out|abort/i.test(message)) return "timeout";
   if (/redirect/i.test(message)) return "redirect_rejected";
+  if (/response_too_large/i.test(message)) return "response_too_large";
+  if (/nip11_invalid/i.test(message)) return "nip11_invalid";
   if (/http_\d+/.test(message)) return message.match(/http_\d+/)[0];
   return "network";
 }

package/lib/buzz-doctor.test.mjs

@@ -194,6 +194,46 @@ describe("Buzz doctor bounded zero-mutation runner", () => {
     assert.equal(report.ok, true);
   });
 
+  it("keeps founder setup usable when a public relay hostname fails TLS and returns an operator repair", async () => {
+    const tlsError = Object.assign(new Error("write EPROTO ssl3 alert handshake failure"), { code: "EPROTO" });
+    const dependencies = healthyDependencies({
+      env: {
+        ...healthyDependencies().env,
+        BUZZ_RELAY_URL: "wss://kychee.com.communities.buzz.xyz",
+      },
+      pinnedRelayRead: async () => { throw tlsError; },
+    });
+    const report = await buildBuzzDoctorReport(dependencies);
+    const relay = report.checks.find((check) => check.name === "buzz_relay");
+    assert.equal(report.ok, true);
+    assert.equal(relay.status, "warning");
+    assert.equal(relay.code, "BUZZ_PREFLIGHT_RELAY_UNREACHABLE");
+    assert.equal(relay.value.failure, "tls_handshake_failed");
+    assert.equal(relay.value.community_operations, "unavailable");
+    assert.equal(relay.next_actions[0].type, "repair_buzz_relay_tls");
+    assert.match(relay.next_actions[0].command, /kychee\.com\.communities\.buzz\.xyz/);
+    assert.doesNotMatch(relay.next_actions[0].command, /reconnect/i);
+    assert.equal(relay.next_actions[0].surface, "buzz_settings");
+    assert.equal("argv" in relay.next_actions[0], false);
+  });
+
+  it("continues to block an unsafe relay destination before making the pinned read", async () => {
+    let reads = 0;
+    const dependencies = healthyDependencies({
+      lookup: async () => [
+        { address: "93.184.216.34", family: 4 },
+        { address: "127.0.0.1", family: 4 },
+      ],
+      pinnedRelayRead: async () => { reads += 1; return { ok: true }; },
+    });
+    const report = await buildBuzzDoctorReport(dependencies);
+    const relay = report.checks.find((check) => check.name === "buzz_relay");
+    assert.equal(report.ok, false);
+    assert.equal(relay.status, "blocked");
+    assert.equal(relay.code, "BUZZ_PREFLIGHT_RELAY_UNSAFE");
+    assert.equal(reads, 0);
+  });
+
   it("rejects private, loopback, link-local, mapped, and documentation addresses", () => {
     for (const address of ["127.0.0.1", "10.0.0.1", "169.254.169.254", "192.0.2.1", "::1", "fc00::1", "fe80::1", "::ffff:127.0.0.1", "2001:db8::1"]) {
       assert.equal(isPublicAddress(address), false, address);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.17.0",
+  "version": "4.17.2",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   "files": [
     "cli.mjs",
     "lib/",
+    "fixtures/",
     "core-dist/",
     "sdk/"
   ],
@@ -26,6 +27,7 @@
     "@x402/evm": "^2.19.0",
     "@x402/extensions": "^2.19.0",
     "@x402/fetch": "^2.19.0",
+    "ipaddr.js": "1.9.1",
     "json-canonicalize": "2.0.0",
     "mppx": "^0.4.7",
     "tsx": "^4.21.0",