@kybernesis/create 0.15.7 → 0.15.8

package/dist/doctor.js

@@ -9,6 +9,7 @@ import { classifyModelReach } from "./model-reach.js";
 import { countAbandonedRuns } from "./run-store.js";
 import { describeStaleSidecar, newestPackageChange, staleSidecars } from "./stale-sidecar.js";
 import { checkSelfVersion } from "./self-version.js";
+import { envUrlProblems } from "./env-urls.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -215,6 +216,22 @@ export async function doctor() {
     };
     if (!existsSync(envPath))
         add("warn", ".env.local missing", "copy .env.example and fill it");
+    /**
+     * Config that is shaped wrong rather than missing.
+     *
+     * A URL-valued setting with no scheme does not fail at start; it fails inside
+     * whatever background drain uses it, once per turn, forever. The reference
+     * fleet logged 121 of these and lost every analytics event of a deployment
+     * while reporting healthy throughout. The value alone is enough to know, so
+     * this costs nothing and lands before a client's first turn.
+     */
+    const urlProblems = existsSync(envPath) ? envUrlProblems(readFileSync(envPath, "utf8")) : [];
+    for (const problem of urlProblems) {
+        add("fail", `${problem.name} cannot build a request (${problem.reason})`, problem.fix);
+    }
+    if (existsSync(envPath) && urlProblems.length === 0) {
+        add("pass", "every URL-valued setting is an absolute http(s) URL");
+    }
     const githubCheck = githubToolsDoctorCheck(existsSync(join(cwd, "agent/extensions/github.ts")), env);
     if (githubCheck)
         add(githubCheck.verdict, githubCheck.label, githubCheck.detail);

package/dist/env-urls.d.ts

@@ -0,0 +1,17 @@
+/** Does this name hold a whole URL? */
+export declare function expectsUrl(name: string): boolean;
+export type EnvUrlProblem = {
+    readonly name: string;
+    /** Why it cannot be used to build a request. Never includes the value. */
+    readonly reason: "no scheme" | "not a url" | "not http(s)";
+    readonly fix: string;
+};
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export declare function checkEnvUrl(name: string, value: string): EnvUrlProblem | undefined;
+/** Every URL-shaped value in this env text that cannot build a request. */
+export declare function envUrlProblems(text: string): EnvUrlProblem[];

package/dist/env-urls.js

@@ -0,0 +1,79 @@
+import { parseEnv } from "./util.js";
+/**
+ * Environment values that are used to build a URL, and whether they can be.
+ *
+ * An SDK handed `POSTHOG_HOST=eu.i.posthog.com` does not complain at start. It
+ * fails once per turn, forever, inside a background drain: `Failed to parse URL
+ * from eu.i.posthog.com/batch/`. On the reference fleet that was 121 logged
+ * failures and every analytics event of the deployment silently discarded,
+ * while the agent itself looked perfectly healthy. Nothing surfaces it because
+ * nothing that matters to the turn depends on it.
+ *
+ * Hence checking the SHAPE of the value at rest, which costs nothing and finds
+ * it before a client's first turn.
+ */
+/**
+ * Names whose value is unambiguously a whole URL.
+ *
+ * `_HOST` is deliberately NOT here: plenty of them legitimately hold a bare
+ * hostname (`SMTP_HOST`, `PGHOST`, `REDIS_HOST`), and flagging those would make
+ * doctor cry wolf on a correct config.
+ */
+const URL_SUFFIXES = ["_URL", "_ENDPOINT", "_ISSUER"];
+/**
+ * `_HOST` names that specific SDKs use as a base URL, so they do need a scheme.
+ * An allowlist rather than a rule, because only the SDK knows which it is.
+ */
+const BASE_URL_HOSTS = new Set(["POSTHOG_HOST"]);
+/** Does this name hold a whole URL? */
+export function expectsUrl(name) {
+    if (BASE_URL_HOSTS.has(name))
+        return true;
+    return URL_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export function checkEnvUrl(name, value) {
+    const trimmed = value.trim().replace(/^["']|["']$/g, "");
+    if (trimmed === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        // A bare host is by far the common case, and the remedy differs from junk.
+        const bare = /^[a-z0-9.-]+(:\d+)?(\/.*)?$/i.test(trimmed);
+        return {
+            name,
+            reason: bare ? "no scheme" : "not a url",
+            fix: bare
+                ? `${name} has no scheme, so anything built from it fails to parse. Prefix it with https://`
+                : `${name} is not a URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return {
+            name,
+            reason: "not http(s)",
+            fix: `${name} is a ${parsed.protocol.replace(":", "")} URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    return undefined;
+}
+/** Every URL-shaped value in this env text that cannot build a request. */
+export function envUrlProblems(text) {
+    const problems = [];
+    for (const [name, value] of Object.entries(parseEnv(text))) {
+        if (!expectsUrl(name))
+            continue;
+        const problem = checkEnvUrl(name, value);
+        if (problem)
+            problems.push(problem);
+    }
+    return problems;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.15.7",
+  "version": "0.15.8",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,5 +46,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "peerDependencies": {}
 }