@theappagency/valinor 0.9.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Camber–The App Agency
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+NOTE: This license covers the LAUNCHER ONLY (the contents of this package).
+The Valinor CLI bundle this launcher downloads and executes is PROPRIETARY
+software of Camber–The App Agency, licensed separately under the terms shipped
+inside the bundle (see the LICENSE file within the downloaded artifact). This
+MIT grant conveys no rights to the downloaded bundle.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @theappagency/valinor
+
+The public launcher for the **Valinor CLI** — Camber's CI-native quality-governance tool.
+
+```sh
+npx @theappagency/valinor@latest --version
+npx @theappagency/valinor@0.10.0 claims-verify claims.yml
+```
+
+The launcher is **trivial by design** and contains no Valinor functionality itself. On each run it:
+
+1. resolves the requested version against the Valinor downloads endpoint
+   (`https://downloads.valinorci.com/manifest.json`) — the launcher's own version pins the bundle
+   version (the pipeline publishes them in lockstep), so `@theappagency/valinor@X.Y.Z` runs Valinor `X.Y.Z`;
+2. fetches the version's bundle (`/v/<version>/valinor.tgz`) and **verifies its SHA-256 against the
+   published `SHA256SUMS`, failing closed** — a mismatched artifact is deleted, never executed;
+3. caches the verified bundle at `~/.valinor/cache/<version>/` — an already-cached, exactly-pinned
+   version runs **fully offline** with no network I/O;
+4. executes the cached CLI, passing through all arguments and the exit code.
+
+No npm registry auth, no `.npmrc`, no tokens, no secrets — `npx` it anywhere, including CI.
+**The launcher sends no telemetry.** Its only network activity is fetching the artifact above.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `VALINOR_VERSION` | Run a specific version or dist-tag (e.g. `0.10.0`, `latest`), overriding the launcher's own pinned version. |
+| `VALINOR_DOWNLOADS_URL` | Override the downloads endpoint base URL (staging/fixtures). |
+| `VALINOR_CACHE_DIR` | Override the cache location (default `~/.valinor/cache`). |
+| `VALINOR_FETCH_TIMEOUT_MS` | Per-request fetch timeout in milliseconds (default `30000`) — a silent/blackholed endpoint aborts here rather than hanging. |
+| `VALINOR_LAUNCHER_DEBUG` | Print full error causes (default output is the actionable message only). |
+
+## Licensing
+
+This launcher is MIT-licensed. **The Valinor CLI bundle it downloads is proprietary software of
+Camber–The App Agency**, licensed under the terms shipped inside the downloaded artifact (the
+`LICENSE` file in the bundle). Installing this launcher conveys no rights to the bundle.

package/bin/valinor.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// The launcher bin: delegate to lib/launcher.js and render its loud, actionable errors without a
+// stack trace (the cause chain is preserved on the error for VALINOR_LAUNCHER_DEBUG=1 diagnosis).
+import { run } from "../lib/launcher.js";
+
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (e) {
+  console.error(`valinor launcher: ${e instanceof Error ? e.message : String(e)}`);
+  if (process.env.VALINOR_LAUNCHER_DEBUG) console.error(e);
+  process.exitCode = 1;
+}

package/lib/launcher.js

@@ -0,0 +1,257 @@
+// The Valinor launcher — the trivial-BY-DESIGN public half of the zero-secret distribution model
+// (task #130 Phase 1). It contains NO secret sauce: it resolves a version against the downloads
+// endpoint's manifest, fetches the proprietary bundle, VERIFIES ITS SHA-256 FAIL-CLOSED, caches it
+// at ~/.valinor/cache/<version>/, and spawns the cached CLI with argv + exit code passed through —
+// preserving `npx valinor@X.Y.Z <cmd>` semantics with zero npm auth, zero .npmrc, zero secrets.
+//
+// Design constraints (deliberate):
+//   • ZERO runtime dependencies — nothing to audit, nothing to resolve from any registry.
+//   • NO TELEMETRY — the launcher reports nothing anywhere; only the artifact fetch itself.
+//   • Fail closed on integrity: a checksum mismatch DELETES the download and refuses to run.
+//   • Offline-friendly: an exactly-pinned, already-cached version runs with NO network at all;
+//     only a dist-tag (`latest`) needs the manifest.
+//   • Loud, actionable degradation: an unreachable endpoint names the URL it tried AND the local
+//     cache state (what versions could still run offline) — never a bare stack trace.
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The production downloads endpoint (override with VALINOR_DOWNLOADS_URL — staging/fixtures/tests). */
+export const DEFAULT_DOWNLOADS_URL = "https://downloads.valinorci.com";
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+/** The endpoint base URL, env-overridable, without a trailing slash. */
+export function downloadsUrl(env = process.env) {
+  return (env.VALINOR_DOWNLOADS_URL || DEFAULT_DOWNLOADS_URL).replace(/\/+$/, "");
+}
+
+/** The local cache root, env-overridable (tests point it at a temp dir). */
+export function cacheRoot(env = process.env) {
+  return env.VALINOR_CACHE_DIR || join(homedir(), ".valinor", "cache");
+}
+
+/**
+ * The version this launcher requests: VALINOR_VERSION (exact version or dist-tag) wins, else the
+ * launcher's OWN package version — the release pipeline publishes the launcher in LOCKSTEP with each
+ * bundle, so `npx @theappagency/valinor@0.9.1` runs bundle 0.9.1 (the `valinor@X.Y.Z` semantics preserved).
+ * A dev/unpublished launcher (version 0.0.0) defaults to the `latest` dist-tag.
+ */
+export function requestedVersion(env = process.env) {
+  if (env.VALINOR_VERSION) return env.VALINOR_VERSION;
+  const own = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
+  return own === "0.0.0" ? "latest" : own;
+}
+
+/** The versions present in the local cache (complete installs only), newest-ish last. Never throws. */
+export function cachedVersions(root) {
+  try {
+    return readdirSync(root)
+      .filter((name) => SEMVER_RE.test(name) && existsSync(join(root, name, ".complete")))
+      .sort();
+  } catch (e) {
+    // ENOENT only = "no cache dir yet" — a genuinely empty cache. Anything else (EACCES, EIO, …)
+    // is a REAL problem the user should see; swallowing it silently would misreport the offline
+    // hint as "nothing cached". It is still non-fatal here (this function only feeds diagnostics —
+    // rethrowing would mask the primary error being rendered), so: warn loudly, return empty.
+    if (e?.code !== "ENOENT") {
+      console.error(`valinor launcher: warning — could not read the cache at ${root} (${e?.code ?? e}); treating it as empty`);
+    }
+    return [];
+  }
+}
+
+/**
+ * Resolve a requested version (exact semver or dist-tag) against the endpoint manifest. Pure.
+ * Throws a descriptive error when the version is absent — which is exactly how a RETRACTED bundle
+ * presents (retraction is server-side deletion; the launcher must refuse, loudly, not fall back).
+ */
+export function resolveVersion(manifest, requested) {
+  const versions = Array.isArray(manifest?.versions) ? manifest.versions : null;
+  const distTags = manifest?.distTags;
+  if (!versions || typeof distTags !== "object" || distTags === null) {
+    throw new Error("the downloads manifest is malformed (expected { versions: [...], distTags: {...} })");
+  }
+  if (SEMVER_RE.test(requested)) {
+    if (versions.includes(requested)) return requested;
+    throw new Error(
+      `version ${requested} is not available from the downloads endpoint (it may have been retracted). Available: ${versions.join(", ") || "(none)"}`,
+    );
+  }
+  const tagged = distTags[requested];
+  if (typeof tagged === "string" && SEMVER_RE.test(tagged)) return tagged;
+  throw new Error(
+    `unknown version or dist-tag ${JSON.stringify(requested)}. Tags: ${Object.keys(distTags).join(", ") || "(none)"}; versions: ${versions.join(", ") || "(none)"}`,
+  );
+}
+
+/**
+ * Parse a sha256sum-format SHA256SUMS body and return the hex digest recorded for `filename`.
+ * Throws when the file carries no entry for it (fail closed — never "skip verification").
+ */
+export function parseSha256Sums(text, filename) {
+  for (const line of String(text).split("\n")) {
+    const m = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+    if (m && m[2].trim() === filename) return m[1].toLowerCase();
+  }
+  throw new Error(`SHA256SUMS carries no entry for ${filename} — refusing to run an unverifiable artifact`);
+}
+
+/**
+ * The per-request timeout (ms): a firewalled/blackholed endpoint that ACCEPTS a connection but never
+ * replies must fail LOUDLY in seconds, not hang forever. Reads the supplied env (NOT a hard-coded
+ * `process.env` — `run()` threads its own env through so a caller/test override actually engages).
+ * Default 30s; tests dial it down to prove the abort fires.
+ */
+export function fetchTimeoutMs(env = process.env) {
+  const parsed = Number(env.VALINOR_FETCH_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;
+}
+
+/**
+ * GET a URL, throwing a loud error naming the URL on any non-200, TIMEOUT, or network failure.
+ * `timeoutMs` is REQUIRED (resolved once by the caller from its env) — passing it explicitly is what
+ * fixes the bug where `fetchTimeoutMs()` read the ambient `process.env` and a `run(args, env)`
+ * override was silently dropped. A timed-out abort surfaces as `TimeoutError`, named in the message.
+ */
+async function fetchOrThrow(url, fetchImpl, timeoutMs) {
+  let res;
+  try {
+    res = await (fetchImpl ?? fetch)(url, { redirect: "follow", signal: AbortSignal.timeout(timeoutMs) });
+  } catch (e) {
+    // AbortSignal.timeout rejects with a DOMException named "TimeoutError" — surface that distinctly
+    // so the failure reads as "timed out after Nms", not an opaque cause code.
+    const cause =
+      e?.name === "TimeoutError"
+        ? `timed out after ${timeoutMs}ms`
+        : (e?.cause?.code ?? e?.code ?? (e instanceof Error ? e.message : String(e)));
+    throw new Error(`could not reach ${url} (${cause})`, { cause: e });
+  }
+  if (!res.ok) throw new Error(`${url} returned HTTP ${res.status}`);
+  return res;
+}
+
+/** Fetch + validate the endpoint manifest. `timeoutMs` is threaded from the caller's env. */
+export async function fetchManifest(base, fetchImpl, timeoutMs = fetchTimeoutMs()) {
+  const res = await fetchOrThrow(`${base}/manifest.json`, fetchImpl, timeoutMs);
+  return res.json();
+}
+
+/**
+ * Ensure `version` is present + verified in the cache; returns the cache dir for that version.
+ * Cache HIT (a completed prior install) is served with NO network I/O. On a miss: download the
+ * tarball AND its SHA256SUMS, recompute the digest, and FAIL CLOSED on mismatch (the partial
+ * download is deleted; nothing executable is left behind). The verified tarball is extracted into
+ * a temp dir and atomically renamed into place, so a crashed install can never half-populate a
+ * version dir that a later run would trust.
+ */
+export async function ensureVersion(base, version, root, fetchImpl, timeoutMs = fetchTimeoutMs()) {
+  const versionDir = join(root, version);
+  if (existsSync(join(versionDir, ".complete"))) return versionDir; // cache hit — zero network.
+
+  const tarballUrl = `${base}/v/${version}/valinor.tgz`;
+  const [tarballRes, sumsRes] = await Promise.all([
+    fetchOrThrow(tarballUrl, fetchImpl, timeoutMs),
+    fetchOrThrow(`${base}/v/${version}/SHA256SUMS`, fetchImpl, timeoutMs),
+  ]);
+  const tarball = Buffer.from(await tarballRes.arrayBuffer());
+  const expected = parseSha256Sums(await sumsRes.text(), "valinor.tgz");
+  const actual = createHash("sha256").update(tarball).digest("hex");
+  if (actual !== expected) {
+    throw new Error(
+      `SHA-256 MISMATCH for ${tarballUrl}: expected ${expected}, got ${actual}. ` +
+        "Refusing to run — the artifact may have been tampered with or corrupted in transit. Nothing was cached.",
+    );
+  }
+
+  const stagingDir = join(root, `.tmp-${version}-${randomBytes(6).toString("hex")}`);
+  mkdirSync(stagingDir, { recursive: true });
+  try {
+    const tgzPath = join(stagingDir, "valinor.tgz");
+    writeFileSync(tgzPath, tarball);
+    // `tar` ships with every supported platform (incl. Windows 10+'s bsdtar); using it (rather than
+    // npm) keeps the install registry-free and auth-free by construction.
+    execFileSync("tar", ["-xzf", tgzPath, "-C", stagingDir]);
+    rmSync(tgzPath);
+    writeFileSync(join(stagingDir, ".complete"), `${expected}\n`);
+    try {
+      renameSync(stagingDir, versionDir);
+    } catch (e) {
+      if (existsSync(join(versionDir, ".complete"))) return versionDir; // lost a concurrent race — theirs is verified too.
+      throw e;
+    }
+  } catch (e) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw e;
+  }
+  return versionDir;
+}
+
+/** The cached CLI's entry path, read from the artifact package.json's `bin` (never hard-coded). */
+export function cachedBinPath(versionDir) {
+  const pkg = JSON.parse(readFileSync(join(versionDir, "package", "package.json"), "utf8"));
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.valinor;
+  if (!bin) throw new Error(`the cached artifact at ${versionDir} declares no runnable bin — the cache may be corrupt; delete it and retry`);
+  return join(versionDir, "package", bin);
+}
+
+/** Spawn the cached CLI with argv passed through; returns its exit code (stdio inherited). */
+export function spawnCli(binPath, args) {
+  const result = spawnSync(process.execPath, [binPath, ...args], { stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.signal) {
+    process.kill(process.pid, result.signal); // propagate the signal-death faithfully (Ctrl-C etc.).
+    return 1; // unreachable in practice; a safe fallback if the signal is ignored.
+  }
+  return result.status ?? 1;
+}
+
+/**
+ * The end-to-end run: resolve → ensure cached+verified → spawn → return the CLI's exit code.
+ * Network is touched ONLY when needed (a dist-tag resolution, or a cache miss). Throws the loud,
+ * actionable errors above; the bin wrapper renders them.
+ */
+export async function run(args, env = process.env) {
+  const base = downloadsUrl(env);
+  const root = cacheRoot(env);
+  const requested = requestedVersion(env);
+  // Resolve the timeout ONCE from THIS call's env (the bug fix — `fetchOrThrow` used to read the
+  // ambient process.env, so a `run(args, env)` override never engaged) and thread it into every fetch.
+  const timeoutMs = fetchTimeoutMs(env);
+
+  let version;
+  if (SEMVER_RE.test(requested)) {
+    version = requested; // exact pin — resolvable (and runnable, if cached) without the manifest.
+  } else {
+    let manifest;
+    try {
+      manifest = await fetchManifest(base, undefined, timeoutMs);
+    } catch (e) {
+      throw new Error(`${e instanceof Error ? e.message : String(e)}\n${offlineHint(base, root)}`, { cause: e });
+    }
+    version = resolveVersion(manifest, requested);
+  }
+
+  let versionDir;
+  try {
+    versionDir = await ensureVersion(base, version, root, undefined, timeoutMs);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Integrity failures are terminal as-is; reachability failures get the offline hint.
+    throw new Error(msg.includes("SHA-256 MISMATCH") ? msg : `${msg}\n${offlineHint(base, root)}`, { cause: e });
+  }
+  return spawnCli(cachedBinPath(versionDir), args);
+}
+
+/** The actionable degradation message: name the endpoint + the offline cache state. */
+function offlineHint(base, root) {
+  const cached = cachedVersions(root);
+  const cacheLine =
+    cached.length > 0
+      ? `Cached versions available OFFLINE at ${root}: ${cached.join(", ")} — pin one to run without the network (e.g. VALINOR_VERSION=${cached[cached.length - 1]} or npx @theappagency/valinor@${cached[cached.length - 1]}).`
+      : `No versions are cached locally at ${root}, so nothing can run offline.`;
+  return `The Valinor downloads endpoint (${base}) is unreachable or missing the requested artifact.\n${cacheLine}\nIf this persists, check https://downloads.valinorci.com and your network/proxy configuration.`;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@theappagency/valinor",
+  "version": "0.9.0",
+  "description": "Public launcher for the Valinor CLI — fetches, SHA-256-verifies, caches, and runs the proprietary Valinor bundle from downloads.valinorci.com. Zero setup, zero secrets, zero npm auth.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cmbrcreative/valinor.git",
+    "directory": "launcher"
+  },
+  "type": "module",
+  "bin": {
+    "valinor": "bin/valinor.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "cd .. && npx vitest run launcher/test"
+  }
+}