gemmein 0.0.2 → 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Gemmein Limited
+
+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.
+
+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.
+
+NOTE: this license covers the launcher ("shim") only. The Gemmein engine
+artifact it downloads is separately licensed under proprietary terms
+presented at download time — see ARTIFACT-LICENSE.md in the distribution
+repository.

package/bin/gemmein.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// gemmein — thin launcher. Downloads the Gemmein local engine once,
+// verifies it against hashes baked into this package, caches it, runs it.
+// Everything real happens in the engine, locally, offline.
+
+import { ENGINE_VERSION, ENGINE_FILES, DOWNLOAD_BASE } from "../lib/versions.mjs";
+import { engineCached, fetchEngine, runEngine } from "../lib/engine.mjs";
+
+const args = process.argv.slice(2);
+
+try {
+  if (!engineCached(ENGINE_VERSION, ENGINE_FILES)) {
+    console.log(`Fetching the Gemmein engine (v${ENGINE_VERSION}, one time — everything runs locally after this)…`);
+    await fetchEngine(ENGINE_VERSION, ENGINE_FILES, DOWNLOAD_BASE);
+    console.log("Verified and cached. You're set — this never needs the network again.\n");
+  }
+  runEngine(ENGINE_VERSION, args);
+} catch (error) {
+  console.error(`\n${error.message}\n`);
+  process.exit(1);
+}

package/lib/engine.mjs

@@ -0,0 +1,74 @@
+// Fetch-verify-cache-run. Small on purpose: this file is the entire trust
+// surface of what executes on a user's machine, and it's shipped as
+// readable source so anyone can audit it.
+//
+// OFFLINE-LAW: the network is touched ONLY when the pinned engine version
+// isn't cached yet. Once cached, everything — including every future
+// `gemmein dev` — runs fully offline.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+export function engineDir(version, base = join(homedir(), ".gemmein", "engine")) {
+  return join(base, version);
+}
+
+function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+/** True when every pinned file exists in the cache with the pinned hash. */
+export function engineCached(version, files, base) {
+  const dir = engineDir(version, base);
+  return Object.entries(files).every(([name, hash]) => {
+    try { return sha256(readFileSync(join(dir, name))) === hash; } catch { return false; }
+  });
+}
+
+/**
+ * Download the pinned engine and verify BEFORE it lands in the cache.
+ * A hash mismatch aborts everything — nothing unverified is ever written
+ * to its final location, so nothing unverified can ever run.
+ */
+export async function fetchEngine(version, files, downloadBase, base) {
+  if (Object.values(files).some((h) => !/^[a-f0-9]{64}$/.test(h))) {
+    throw new Error(
+      "this shim build has no released engine pinned — update the gemmein package (npm i -g gemmein@latest)"
+    );
+  }
+  const dir = engineDir(version, base);
+  mkdirSync(dir, { recursive: true });
+  for (const [name, expected] of Object.entries(files)) {
+    const url = `${downloadBase}/${version}/${name}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`couldn't download the Gemmein engine (${res.status} for ${name}) — check your connection and try again`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    const actual = sha256(bytes);
+    if (actual !== expected) {
+      throw new Error(
+        `SECURITY: ${name} from the download server does not match the hash pinned in this npm package ` +
+        `(expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…). Refusing to run it. ` +
+        `This should never happen — please report it: hello@gemmein.com`
+      );
+    }
+    const tmp = join(dir, `${name}.tmp`);
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, join(dir, name));
+  }
+  chmodSync(join(dir, "gemmein.js"), 0o755);
+}
+
+/** Hand over to the cached engine, argv passed through, cwd preserved. */
+export function runEngine(version, args, base) {
+  const entry = join(engineDir(version, base), "gemmein.js");
+  if (!existsSync(entry)) throw new Error("engine missing after verification — report this: hello@gemmein.com");
+  const child = spawn(process.execPath, [entry, ...args], { stdio: "inherit" });
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    process.exit(code ?? 0);
+  });
+  return child;
+}

package/lib/versions.mjs

@@ -0,0 +1,21 @@
+// THE COMPILE-TIME CONSTANTS (CARVE-BOUNDARY hash law).
+//
+// These hashes are baked into the published npm package and are the ONLY
+// thing the downloaded engine is verified against. They are never fetched
+// at runtime and never served from the CDN — the hash travels through npm,
+// the artifact travels through downloads.gemmein.com, and compromising one
+// channel is useless without the other.
+//
+// Updated ONLY by the promotion ritual (PROMOTION.md). The TBD placeholder
+// fails closed: the shim refuses to download anything until a real release
+// has been promoted.
+
+export const ENGINE_VERSION = "0.1.0";
+
+/** file name -> hex sha256 */
+export const ENGINE_FILES = {
+  "gemmein.js": "6dc0ad751f0f2023039d58f1f44a80824ec4b44d67bca57b44c097729a65936f",
+  "llms.txt": "1aa0989dd1624e93014122a451e22043659caa02e32a5b096da90d2b1cff6217",
+};
+
+export const DOWNLOAD_BASE = "https://downloads.gemmein.com/engine";

package/package.json

@@ -1,8 +1,37 @@
 {
   "name": "gemmein",
-  "version": "0.0.2",
-  "description": "Gemmein \u2014 the secure backend for AI-built apps. For the SDK, install @gemmein/sdk. This name is reserved for the future Gemmein CLI.",
+  "version": "0.1.0",
+  "description": "gemmein \u2014 declare your business boundaries, prove them locally, ship. Thin launcher: downloads the Gemmein local engine, verifies it, runs it. What you read here is what runs.",
   "license": "MIT",
+  "type": "module",
+  "bin": {
+    "gemmein": "./bin/gemmein.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "backend",
+    "auth",
+    "storage",
+    "payments",
+    "local-first",
+    "ai",
+    "vibe-coding"
+  ],
+  "homepage": "https://gemmein.com",
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "Gemmein Limited",
-  "homepage": "https://gemmein.com"
+  "bugs": {
+    "email": "hello@gemmein.com"
+  }
 }

package/README.md

@@ -1,11 +0,0 @@
-# gemmein
-
-You probably want the SDK:
-
-```
-npm i @gemmein/sdk
-```
-
-This package name is reserved for the future Gemmein CLI.
-
-Docs: https://docs.gemmein.com · Site: https://gemmein.com