@telorun/cli 0.76.0 → 0.78.0

package/dist/release/verify-requires.js

@@ -0,0 +1,176 @@
+/**
+ * Verification of a module's declared `requires.telo` range — by RUNNING the CLI
+ * at each edge of it.
+ *
+ * This is the half of declared runtime requirements that cannot live in the
+ * analyzer: it spawns a process and reaches the network, while the analyzer is
+ * browser-safe. It is also a *publishing* concern — an author editing a manifest
+ * needs to know whether their runtime can read a module, not whether someone
+ * else's declaration is honest.
+ *
+ * **Why execution rather than a `since:` table.** The obvious design annotates
+ * every vocabulary entry with the version that introduced it and takes the
+ * maximum over what a manifest uses. That re-creates the discipline problem one
+ * level down — every future additive change must remember its `since`, and
+ * forgetting is silent, which is the failure mode this whole mechanism exists to
+ * remove — and it cannot see a *shape* change (an object where a zone annotation
+ * used to take a pointer, a new key on a closed kernel-owned schema) without a
+ * second annotation mechanism. Running the old CLI is not a prediction of the
+ * property; it IS the property, executed.
+ *
+ * **Two edges bound the whole range**, rather than sampling it, because syntax
+ * support is monotonic: a construct added in 0.43 works in 0.44 and later, one
+ * removed in 0.60 works in 0.59 and earlier. Nothing in the middle can fail
+ * while both edges pass. For a range open above the high edge is HEAD, which
+ * normal CI already checks, so an open declaration costs one run.
+ *
+ * **Infrastructure failure warns; evidence of breakage fails.** A CLI that
+ * cannot be installed (offline, a registry outage) leaves the claim unverified,
+ * and blocking a publish on network reachability trades one failure for a worse
+ * one. A CLI that runs and rejects the manifest is evidence, and evidence is
+ * what this gate is for.
+ */
+import { readRequires, lowerBound, upperBound } from "@telorun/analyzer";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** How long a single edge check may take. An old CLI has to be fetched on first
+ *  use, so this is generous; it exists to bound a hang, not to pace the work. */
+const EDGE_TIMEOUT_MS = 300_000;
+/**
+ * Verify a module manifest against the edges of its own declared range.
+ *
+ * `manifestPath` is checked, not the module directory, so the caller controls
+ * which document is the subject. A module declaring nothing returns immediately:
+ * absent means no requirement, permanently, for everything published before this
+ * mechanism existed.
+ */
+export async function verifyRequires(manifestPath, moduleDoc, options) {
+    const { block } = readRequires(moduleDoc);
+    const declared = block.telo;
+    if (!declared)
+        return { outcomes: [], refuted: false };
+    const edges = [];
+    const low = lowerBound(declared);
+    if (low)
+        edges.push(low.raw);
+    const high = upperBound(declared);
+    // The high edge of an open range is HEAD, which the ordinary check already
+    // covers; only a closed bound names a version worth installing. A bound equal
+    // to the low edge is one edge, not two.
+    if (high && high.raw !== low?.raw)
+        edges.push(high.raw);
+    const outcomes = [];
+    for (const edge of edges) {
+        // The running CLI is the edge, and the caller has ALREADY checked this
+        // manifest with it — `publishOne` runs static analysis before reaching here
+        // and returns on any error. Spawning `telo check` would re-run that same
+        // analysis to learn what we know; worse, `telo` is not on PATH in a
+        // development checkout (it is `pnpm run telo`), so the spawn would ENOENT and
+        // report a spurious "could not run" against every module.
+        if (edge === options.currentVersion) {
+            outcomes.push({ edge, status: "passed" });
+            continue;
+        }
+        outcomes.push(await runEdge(manifestPath, edge));
+    }
+    return { declared, outcomes, refuted: outcomes.some((o) => o.status === "failed") };
+}
+async function runEdge(manifestPath, edge) {
+    try {
+        await run("npx", ["-y", `@telorun/cli@${edge}`, "check", manifestPath], {
+            timeout: EDGE_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return { edge, status: "passed" };
+    }
+    catch (err) {
+        const e = err;
+        if (typeof e.code !== "number") {
+            // Never ran: the binary is missing, a fetch failed, the timeout fired. The
+            // claim is unverified, not disproven, and the two must not be conflated.
+            return { edge, status: "unavailable", reason: e.message ?? String(err) };
+        }
+        const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+        if (!mentionsManifest(output, manifestPath)) {
+            // It ran and exited non-zero WITHOUT saying anything about the manifest
+            // under test. `telo check` also exits non-zero for an argument shape an
+            // older parser does not accept, an unreachable remote import, or a bad
+            // registry URL — and reporting any of those as "the declared range is
+            // false" is precisely the misattribution this mechanism exists to remove.
+            // Refuting a range needs evidence about THIS manifest.
+            return {
+                edge,
+                status: "unavailable",
+                reason: `telo ${edge} exited non-zero without reporting on ${manifestPath} — ` +
+                    `treating the range as unverified rather than refuted. Output: ` +
+                    `${output.slice(0, 400) || "(none)"}`,
+            };
+        }
+        return { edge, status: "failed", output: output || (e.message ?? "check failed") };
+    }
+}
+/** Whether the edge CLI's output actually concerns the manifest under test.
+ *  Compared on the basename as well as the full path, since a CLI renders a
+ *  path relative to its own cwd. */
+function mentionsManifest(output, manifestPath) {
+    if (!output)
+        return false;
+    const base = manifestPath.split(/[\\/]/).filter(Boolean).slice(-2).join("/");
+    return output.includes(manifestPath) || (base.length > 0 && output.includes(base));
+}
+/**
+ * The published `@telorun/cli` versions, for the "an upper bound must already
+ * exist" check. `null` when the registry could not be reached — the caller warns
+ * rather than blocking, since the rule gates a bound absent from almost every
+ * module and an unreachable npm should not stop a publish.
+ *
+ * **Memoized for the process**, because `telo publish` runs per module and
+ * `scripts/publish-modules.mjs` publishes the whole standard library in one
+ * pass: without this, one release is ~60 `npm view` round trips (each with a
+ * 60-second timeout) for a single answer that cannot change mid-run. The failed
+ * lookup is cached too — a registry unreachable for the first module is
+ * unreachable for the rest, and retrying it sixty times turns a warning into a
+ * minutes-long stall.
+ *
+ * `@telorun/cli` is deliberately the package queried: it is the one the
+ * verification path installs (`npx @telorun/cli@<edge>`) and the one
+ * `TELO_SURFACE_VERSION` is generated from, so the constant, the existence check
+ * and the thing that actually runs all name one package.
+ */
+let publishedVersionsCache;
+export function resetPublishedTeloVersionsCache() {
+    publishedVersionsCache = undefined;
+}
+export function publishedTeloVersions() {
+    publishedVersionsCache ??= fetchPublishedTeloVersions();
+    return publishedVersionsCache;
+}
+async function fetchPublishedTeloVersions() {
+    try {
+        const { stdout } = await run("npm", ["view", "@telorun/cli", "versions", "--json"], {
+            timeout: 60_000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed))
+            return parsed.filter((v) => typeof v === "string");
+        return typeof parsed === "string" ? [parsed] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The declared upper bound when it names a version the registry does not have —
+ *  an unverifiable bound, which the grammar exists to forbid. `undefined` when
+ *  the range is open above, the bound exists, or the registry was unreachable. */
+export function unpublishedUpperBound(declared, published) {
+    if (!declared || published === null)
+        return undefined;
+    const high = upperBound(declared);
+    if (!high)
+        return undefined;
+    const normalized = new Set(published.map((v) => (v.startsWith("v") ? v.slice(1) : v)));
+    return normalized.has(high.raw) ? undefined : high.raw;
+}
+//# sourceMappingURL=verify-requires.js.map

package/dist/release/verify-requires.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-requires.js","sourceRoot":"","sources":["../../src/release/verify-requires.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/cli",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "description": "Telo CLI - Command-line interface for the Telo runtime.",
   "keywords": [
     "telo",
@@ -34,11 +34,11 @@
     "dist"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.61.0",
+    "@telorun/analyzer": "0.62.1",
     "@telorun/glob": "0.2.0",
-    "@telorun/ide-support": "0.13.3",
-    "@telorun/kernel": "0.76.0",
-    "@telorun/sdk": "0.75.0",
+    "@telorun/ide-support": "0.14.1",
+    "@telorun/kernel": "0.78.0",
+    "@telorun/sdk": "0.77.0",
     "@telorun/templating": "0.16.0",
     "dotenv": "^17.4.0",
     "packageurl-js": "^2.0.1",