@memohai/cloud-runtime 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@memohai/cloud-runtime",
+  "version": "0.1.0",
+  "description": "Memoh Cloud Remote Runtime CLI — connects a local machine to Memoh Cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memohai/Memoh-Cloud.git",
+    "directory": "packages/cloud-runtime"
+  },
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "memoh-cloud-runtime": "dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "esbuild": "0.27.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,191 @@
+import { spawn } from 'node:child_process'
+import { access, chmod, copyFile, mkdir, readFile, rm } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { build } from 'esbuild'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const submodule = resolve(root, '../memoh')
+const upstreamRuntime = resolve(submodule, 'packages/runtime')
+const protoSource = resolve(submodule, 'internal/workspace/bridgepb/bridge.proto')
+const outdir = resolve(root, 'dist')
+
+// This package ships no runtime dependencies: the entire implementation is
+// bundled from the memoh submodule. Node resolves the upstream sources' own
+// imports (ws, @grpc/*) against packages/memoh's node_modules — resolution
+// walks up from the importing file, not from this package — so the submodule
+// has to be both checked out and installed.
+await requirePath(
+  resolve(upstreamRuntime, 'src/cli.ts'),
+  'packages/memoh submodule is not checked out — run `git submodule update --init --recursive`',
+)
+await requirePath(
+  resolve(upstreamRuntime, 'node_modules/ws'),
+  'packages/memoh is not installed — run `pnpm install --filter @memohai/runtime...` from packages/memoh',
+)
+await requirePath(
+  protoSource,
+  'canonical bridge.proto is missing from the memoh submodule',
+)
+
+// Which upstream runtime ends up inside the bundle is decided by the submodule
+// gitlink, and nothing in the published tarball would otherwise record it.
+// Stamp it in so a build in the wild can identify itself — see src/build-info.ts.
+const cloudVersion = await readVersion(resolve(root, 'package.json'))
+const upstreamVersion = await readVersion(resolve(upstreamRuntime, 'package.json'))
+const upstreamCommit = await readSubmoduleCommit()
+
+await rm(outdir, { recursive: true, force: true })
+await mkdir(outdir, { recursive: true })
+
+await build({
+  entryPoints: { cli: resolve(root, 'src/cli.ts') },
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node20',
+  packages: 'bundle',
+  define: {
+    __CLOUD_RUNTIME_VERSION__: JSON.stringify(cloudVersion),
+    __UPSTREAM_RUNTIME_VERSION__: JSON.stringify(upstreamVersion),
+    __UPSTREAM_RUNTIME_COMMIT__: JSON.stringify(upstreamCommit),
+  },
+  // grpc-js and ws are CommonJS. The bundled ESM artifact needs a require shim
+  // to load them — the same bridge the upstream build installs. esbuild emits
+  // the entry's shebang above this banner, so the bin stays executable.
+  banner: {
+    js: [
+      `// @memohai/cloud-runtime ${cloudVersion} — bundles @memohai/runtime ${upstreamVersion} (memoh ${upstreamCommit})`,
+      "import { createRequire as __memohCreateRequire } from 'node:module'",
+      'const require = __memohCreateRequire(import.meta.url)',
+    ].join('\n'),
+  },
+  outdir,
+  outExtension: { '.js': '.mjs' },
+})
+
+await chmod(resolve(outdir, 'cli.mjs'), 0o755)
+
+// service.ts resolves the descriptor next to the built artifact first, so the
+// canonical proto has to travel with the bundle.
+await copyFile(protoSource, resolve(outdir, 'bridge.proto'))
+
+await verifyBundleLoads()
+await verifyVersionStamp()
+await verifyHelpBranding()
+
+/**
+ * Runs the bundle far enough to prove its whole module graph evaluates under
+ * ESM — the CommonJS grpc-js/ws bridge above is the fragile part, and it only
+ * fails at load time. The upstream CLI validates arguments *after* that graph
+ * is live, so its own error is the success signal here.
+ */
+async function verifyBundleLoads() {
+  const { code, stderr, stdout } = await run(process.execPath, [resolve(outdir, 'cli.mjs')], {
+    // Scrub the developer's own credentials: with a key present the CLI would
+    // skip validation and try to connect, hanging the build.
+    ...process.env,
+    MEMOH_RUNTIME_SERVER: '',
+    MEMOH_RUNTIME_KEY: '',
+    MEMOH_RUNTIME_TEAM_ID: '',
+  })
+  if (!stderr.includes('--server and --key are required')) {
+    throw new Error(`bundle smoke test failed (exit ${code}):\n${stderr || stdout}`)
+  }
+}
+
+/**
+ * Guards the `define` wiring: an un-substituted stamp silently degrades to
+ * "unknown" at runtime rather than failing the build, which would leave
+ * published artifacts unable to identify themselves.
+ */
+async function verifyVersionStamp() {
+  const { code, stdout, stderr } = await run(
+    process.execPath,
+    [resolve(outdir, 'cli.mjs'), '--version'],
+    process.env,
+  )
+  if (!stdout.includes(upstreamVersion) || !stdout.includes(upstreamCommit)) {
+    throw new Error(`version stamp missing from the bundle (exit ${code}):\n${stdout || stderr}`)
+  }
+}
+
+/**
+ * Guards the import order in src/cli.ts — the one thing this package's design
+ * hinges on. If the upstream entry ever evaluates first, --help prints
+ * upstream's `memoh-runtime` usage (or worse, starts a session) before
+ * bootstrap can intercept. The branding is the observable proof that
+ * bootstrap still runs first.
+ */
+async function verifyHelpBranding() {
+  const { stderr, stdout } = await run(
+    process.execPath,
+    [resolve(outdir, 'cli.mjs'), '--help'],
+    process.env,
+  )
+  if (!stderr.includes('memoh-cloud-runtime') || stderr.includes('Usage: memoh-runtime ')) {
+    throw new Error(`--help is not Cloud-branded — bootstrap did not run first:\n${stderr || stdout}`)
+  }
+}
+
+async function readVersion(packageJsonPath) {
+  const { version } = JSON.parse(await readFile(packageJsonPath, 'utf8'))
+  if (!version) {
+    throw new Error(`no version field in ${packageJsonPath}`)
+  }
+  return version
+}
+
+/**
+ * Identifies the exact submodule tree that was bundled. Falls back to "unknown"
+ * rather than failing: builds from a source tarball have no git metadata, and
+ * that is not a reason to block a release.
+ */
+async function readSubmoduleCommit() {
+  // A missing git *binary* rejects the spawn promise outright — same
+  // "no git metadata" situation as a failing rev-parse, same fallback.
+  try {
+    const head = await run('git', ['-C', submodule, 'rev-parse', '--short=8', 'HEAD'], process.env)
+    if (head.code !== 0) {
+      return 'unknown'
+    }
+    const commit = head.stdout.trim()
+    // A dirty submodule means the bundle contains code that exists in no
+    // commit; saying so is the whole point of the stamp.
+    const status = await run('git', ['-C', submodule, 'status', '--porcelain'], process.env)
+    return status.code === 0 && status.stdout.trim() ? `${commit}-dirty` : commit
+  } catch {
+    return 'unknown'
+  }
+}
+
+function run(command, args, env) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, { env, stdio: ['ignore', 'pipe', 'pipe'] })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      rejectPromise(new Error('bundle smoke test timed out after 30s'))
+    }, 30_000)
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', chunk => (stdout += chunk))
+    child.stderr.on('data', chunk => (stderr += chunk))
+    child.on('error', error => {
+      clearTimeout(timer)
+      rejectPromise(error)
+    })
+    child.on('close', code => {
+      clearTimeout(timer)
+      resolvePromise({ code, stdout, stderr })
+    })
+  })
+}
+
+async function requirePath(path, message) {
+  try {
+    await access(path)
+  } catch {
+    throw new Error(message)
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,29 @@
+/**
+ * Side-effect module: adjusts process state before the upstream CLI runs.
+ *
+ * cli.ts imports this ahead of the upstream entry point, and ES modules
+ * evaluate their imports depth-first in source order, so this body is
+ * guaranteed to finish first — which matters because the upstream module
+ * starts a session as soon as *its* body evaluates. That ordering is a
+ * language guarantee, not a bundler behaviour, so it survives esbuild.
+ */
+import { versionReport } from './build-info'
+import { applyCloudDefaults, cloudUsage } from './cloud'
+
+const args = process.argv.slice(2)
+
+// Both flags are handled here rather than upstream: the usage string there
+// names `memoh-runtime` and cannot know the Cloud default endpoint, and
+// upstream has no --version at all.
+if (args.includes('--help') || args.includes('-h')) {
+  // stderr and exit 0, matching upstream's usage() contract.
+  console.error(cloudUsage())
+  process.exit(0)
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(versionReport())
+  process.exit(0)
+}
+
+applyCloudDefaults(args, process.env)

package/src/build-info.ts

@@ -0,0 +1,40 @@
+/**
+ * Build stamps injected by scripts/build.mjs through esbuild `define`.
+ *
+ * The artifact is the only place that can answer which upstream runtime it
+ * contains. This package bundles its implementation from the packages/memoh
+ * submodule at build time, so the upstream version is pinned by a gitlink
+ * rather than by a semver range in package.json — nothing in the published
+ * tarball would otherwise record it. Stamping it here is what lets a build in
+ * the wild identify itself during an incident.
+ *
+ * Drop this module when the package moves to a plain npm dependency on
+ * @memohai/runtime: at that point the lockfile records the version instead.
+ */
+
+const unknownStamp = 'unknown'
+
+declare const __CLOUD_RUNTIME_VERSION__: string
+declare const __UPSTREAM_RUNTIME_VERSION__: string
+declare const __UPSTREAM_RUNTIME_COMMIT__: string
+
+// The `typeof` guards keep this module loadable outside the bundle, where the
+// identifiers are never declared — tests and `tsc` import it directly. Reading
+// an undeclared identifier throws; `typeof` on one does not. Inside the bundle
+// esbuild substitutes literals and these fold away.
+export const cloudRuntimeVersion
+  = typeof __CLOUD_RUNTIME_VERSION__ === 'string' ? __CLOUD_RUNTIME_VERSION__ : unknownStamp
+
+export const upstreamRuntimeVersion
+  = typeof __UPSTREAM_RUNTIME_VERSION__ === 'string' ? __UPSTREAM_RUNTIME_VERSION__ : unknownStamp
+
+/** Short commit of the packages/memoh submodule, `-dirty` when built from edits. */
+export const upstreamRuntimeCommit
+  = typeof __UPSTREAM_RUNTIME_COMMIT__ === 'string' ? __UPSTREAM_RUNTIME_COMMIT__ : unknownStamp
+
+export function versionReport(): string {
+  return [
+    `@memohai/cloud-runtime ${cloudRuntimeVersion}`,
+    `bundles @memohai/runtime ${upstreamRuntimeVersion} (memoh ${upstreamRuntimeCommit})`,
+  ].join('\n')
+}

package/src/cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// Import order is load-bearing. ./bootstrap seeds the Cloud endpoint and may
+// exit for --help; the upstream module below connects the moment it evaluates,
+// so it must come second. See src/bootstrap.ts.
+import './bootstrap'
+import '../../memoh/packages/runtime/src/cli'

package/src/cloud.ts

@@ -0,0 +1,62 @@
+/**
+ * Everything Memoh Cloud adds on top of the upstream runtime CLI.
+ *
+ * The rest of this package *is* @memohai/runtime, bundled straight from the
+ * packages/memoh submodule at build time (see scripts/build.mjs). Keeping the
+ * Cloud behaviour confined to this file is what makes the divergence from open
+ * source auditable: if this file is empty, the two CLIs are identical.
+ */
+
+/**
+ * Where the CLI dials when the operator does not say otherwise.
+ *
+ * `app.memoh.net` is the Cloud public ingress (deploy/AGENTS.md) and the BFF
+ * mounts the shared Memoh data plane under `/api/memoh`. The CLI appends
+ * `/runtimes/connect` itself, so this value stays an origin plus prefix — see
+ * packages/bff/internal/handler/runtime_connect.go.
+ */
+export const cloudDefaultServerUrl = 'https://app.memoh.net/api/memoh'
+
+/** The environment variable the upstream CLI reads as its `--server` fallback. */
+export const serverUrlEnvVar = 'MEMOH_RUNTIME_SERVER'
+
+/**
+ * Seeds the Cloud endpoint without taking precedence away from the operator.
+ *
+ * Resolution order stays `--server` > `MEMOH_RUNTIME_SERVER` > Cloud default.
+ * The upstream CLI already prefers the flag over the environment variable, so
+ * seeding the variable is enough to add a default — and it must never overwrite
+ * a value the caller set deliberately (staging, a tunnel, a self-hosted
+ * install), which is why both escape hatches are checked first.
+ */
+export function applyCloudDefaults(args: readonly string[], env: NodeJS.ProcessEnv): void {
+  // The prefix match also catches `--server=url`, a spelling upstream does NOT
+  // parse. Seeding the default there would silently redirect a mistyped-but-
+  // explicit endpoint to Cloud production; deferring lets upstream's own
+  // usage error surface so the caller fixes the spelling instead.
+  if (args.some(arg => arg === '--server' || arg.startsWith('--server='))) {
+    return
+  }
+  if (env[serverUrlEnvVar]?.trim()) {
+    return
+  }
+  env[serverUrlEnvVar] = cloudDefaultServerUrl
+}
+
+/**
+ * Cloud-branded help text. The upstream string names `memoh-runtime` and omits
+ * the default endpoint, so this package prints its own and never reaches it.
+ */
+export function cloudUsage(): string {
+  return [
+    'Usage: memoh-cloud-runtime --key <key> [--team-id <uuid>] [--server <url>] [--insecure-localhost]',
+    '',
+    'Connects this machine to Memoh Cloud as a remote runtime.',
+    '',
+    `  --server   defaults to ${cloudDefaultServerUrl}`,
+    '             (or $MEMOH_RUNTIME_SERVER when exported)',
+    '  --key      team-scoped runtime key, mrk_...',
+    '  --team-id  tenant UUID issued alongside the key',
+    '  --version  this build, and the upstream runtime bundled into it',
+  ].join('\n')
+}