restorm-cli 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,36 @@
+# restorm-cli
+
+Run a [Restorm](https://restorm.app) scenario from a terminal, or from CI where
+there is no terminal to click in.
+
+```bash
+npm install -g restorm-cli
+restorm --open ./api.restorm --run "Smoke tests" --headless
+```
+
+## Your token
+
+A headless run authenticates with an organization token (prefixed `rstk_`) read
+from `RESTORM_TOKEN`.
+
+Create one **inside Restorm**: the account button in the title bar, then *My
+CLI/CI tokens*. Give it a label and a lifetime, and copy it — the value is shown
+once, at creation, and is never retrievable afterwards, including by us. You can
+revoke it at any time, and a revoked or expired token stops working immediately.
+
+Tokens can also be managed from your account dashboard at
+[my.restorm.app](https://my.restorm.app).
+
+→ [Accounts, sign-in and CLI/CI tokens](https://restorm.app/en/docs/entreprise/comptes-et-connexion/)
+
+## In a pipeline
+
+```yaml
+- name: API smoke tests
+  run: npx restorm-cli --open ./api.restorm --run "Smoke tests" --headless
+  env:
+    RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}
+```
+
+→ [Headless execution and CI](https://restorm.app/en/docs/scenarios/execution-headless-ci/)
+· [All CLI arguments and output formats](https://restorm.app/en/docs/reference/cli/)

package/bin/restorm.js

@@ -1,20 +1,28 @@
 #!/usr/bin/env node
 /**
- * Restorm installer bootstrap.
+ * Restorm launcher.
  *
- * If Restorm is already installed, exec it (all arguments pass through, so
- * `restorm --run scenario.restorm` works). Otherwise, detect the platform,
- * download the right build from the official release bucket, and guide the
- * install. Zero dependencies.
+ * `restorm …` runs Restorm and passes every argument through, so
+ * `restorm --open api.restorm --run "Smoke tests" --headless` behaves exactly as
+ * it does on a desktop install. The application itself is not in this package —
+ * it is resolved, in order:
+ *
+ *   1. a system installation, if the machine has one (a user who installed the
+ *      .deb, the .dmg or the Windows installer expects THAT build to run);
+ *   2. the per-user cache, from a previous run;
+ *   3. a fresh download of the official build, verified against the checksum
+ *      published in the release manifest, then cached.
+ *
+ * Step 3 happens once per version. A CI job that runs this twice downloads
+ * once. Zero dependencies.
  */
 'use strict'
 
-const { spawnSync, execFileSync } = require('node:child_process')
-const { createWriteStream, existsSync, mkdirSync, chmodSync } = require('node:fs')
+const { spawnSync } = require('node:child_process')
+const { existsSync } = require('node:fs')
 const { join } = require('node:path')
-const { homedir, tmpdir } = require('node:os')
 
-const BASE = 'https://dl.restorm.app/latest'
+const { ensureBuild } = require('../lib/install')
 
 const CANDIDATES = {
   linux: ['/opt/Restorm/restorm-bin', '/snap/bin/restorm', '/usr/bin/restorm'],
@@ -32,71 +40,32 @@ function findInstalled() {
   return null
 }
 
-function artifact() {
-  const { platform, arch } = process
-  if (platform === 'linux') return { url: `${BASE}/Restorm.AppImage`, file: 'Restorm.AppImage', run: true }
-  if (platform === 'darwin') {
-    return arch === 'arm64'
-      ? { url: `${BASE}/Restorm-arm64.dmg`, file: 'Restorm-arm64.dmg' }
-      : { url: `${BASE}/Restorm.dmg`, file: 'Restorm.dmg' }
-  }
-  if (platform === 'win32') return { url: `${BASE}/Restorm-Setup.exe`, file: 'Restorm-Setup.exe' }
-  return null
+function run(exe, args) {
+  const r = spawnSync(exe, args, { stdio: 'inherit' })
+  if (r.error) throw r.error
+  process.exit(r.status ?? 0)
 }
 
-async function download(url, dest) {
-  const res = await fetch(url, { redirect: 'follow' })
-  if (!res.ok) throw new Error(`download failed: HTTP ${res.status} for ${url}`)
-  const total = Number(res.headers.get('content-length') || 0)
-  let done = 0
-  const out = createWriteStream(dest)
-  const reader = res.body.getReader()
-  for (;;) {
-    const { value, done: end } = await reader.read()
-    if (end) break
-    out.write(Buffer.from(value))
-    done += value.length
-    if (total && process.stdout.isTTY) {
-      process.stdout.write(`\r  ${(done / 1048576).toFixed(1)} / ${(total / 1048576).toFixed(1)} MiB`)
-    }
-  }
-  await new Promise((resolve, reject) => out.end((e) => (e ? reject(e) : resolve())))
-  if (process.stdout.isTTY) process.stdout.write('\n')
+function progress(done, total) {
+  if (!process.stdout.isTTY) return
+  const mib = (n) => (n / 1048576).toFixed(1)
+  process.stdout.write(total ? `\r  ${mib(done)} / ${mib(total)} MiB` : `\r  ${mib(done)} MiB`)
 }
 
 async function main() {
-  const installed = findInstalled()
-  if (installed) {
-    const r = spawnSync(installed, process.argv.slice(2), { stdio: 'inherit' })
-    process.exit(r.status ?? 0)
-  }
+  const args = process.argv.slice(2)
 
-  const a = artifact()
-  if (!a) {
-    console.error(`Unsupported platform: ${process.platform}/${process.arch}`)
-    console.error('Downloads for every platform: https://restorm.app/download')
-    process.exit(1)
-  }
+  const installed = findInstalled()
+  if (installed) run(installed, args)
 
-  console.log('Restorm is not installed yet — fetching the latest build…')
-  const dir = join(homedir(), 'Downloads')
-  const dest = join(existsSync(dir) ? dir : tmpdir(), a.file)
-  await download(a.url, dest)
-  console.log(`Saved to ${dest}`)
+  const { exe, version, cached } = await ensureBuild({
+    log: (m) => console.error(m),
+    onProgress: progress
+  })
+  if (!cached && process.stdout.isTTY) process.stdout.write('\n')
+  if (!cached) console.error(`Restorm ${version} is ready.`)
 
-  if (a.run && process.platform === 'linux') {
-    chmodSync(dest, 0o755)
-    console.log('Launching the AppImage… (prefer a package? https://restorm.app/download)')
-    const r = spawnSync(dest, process.argv.slice(2), { stdio: 'inherit' })
-    process.exit(r.status ?? 0)
-  }
-  if (process.platform === 'darwin') {
-    console.log('Opening the disk image — drag Restorm to Applications, then run `restorm` again.')
-    try { execFileSync('open', [dest]) } catch {}
-  } else if (process.platform === 'win32') {
-    console.log('Launching the installer — run `restorm` again once it finishes.')
-    try { execFileSync('cmd', ['/c', 'start', '', dest]) } catch {}
-  }
+  run(exe, args)
 }
 
 main().catch((e) => {

package/lib/install.js

@@ -0,0 +1,223 @@
+'use strict'
+
+/**
+ * Fetch, verify and cache the Restorm build this machine needs.
+ *
+ * The contract every caller depends on: what this function returns is either a
+ * complete, checksum-verified executable, or an exception. A half-written
+ * download is never handed back and never left where a later run could mistake
+ * it for a good one.
+ */
+
+const { spawnSync } = require('node:child_process')
+const { createHash } = require('node:crypto')
+const {
+  chmodSync,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} = require('node:fs')
+const { homedir } = require('node:os')
+const { join } = require('node:path')
+
+const resolve = require('./resolve')
+
+const COMPLETE_MARKER = '.complete'
+
+/**
+ * Asks for this package's own version first, and falls back to the newest
+ * release if that manifest is not there — which happens for exactly one reason
+ * worth surviving: the npm package published before, or without, the matching
+ * bucket upload.
+ */
+async function fetchManifest(env, platform, fetchImpl, version) {
+  const call = fetchImpl || fetch
+  const pinned = resolve.manifestUrl(env, platform, version)
+  const res = await call(pinned, { redirect: 'follow' })
+  if (res.ok) return await res.json()
+
+  const newest = resolve.manifestUrl(env, platform, 'latest')
+  if (res.status !== 404 || pinned === newest || env.RESTORM_VERSION) {
+    throw new Error(`release manifest unavailable: HTTP ${res.status} for ${pinned}`)
+  }
+  const fallback = await call(newest, { redirect: 'follow' })
+  if (!fallback.ok) {
+    throw new Error(`release manifest unavailable: HTTP ${fallback.status} for ${newest}`)
+  }
+  return await fallback.json()
+}
+
+/**
+ * Streams to disk while hashing, then compares. Hashing the stream rather than
+ * re-reading the file afterwards keeps a 400 MB artifact off a second pass, and
+ * — more importantly — leaves no window where the file on disk is not the file
+ * that was verified.
+ */
+async function downloadVerified(url, dest, sha256, { fetchImpl, onProgress } = {}) {
+  const res = await (fetchImpl || fetch)(url, { redirect: 'follow' })
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status} for ${url}`)
+  const total = Number(res.headers.get('content-length') || 0)
+  const hash = createHash('sha256')
+  const out = createWriteStream(dest)
+  const reader = res.body.getReader()
+  let done = 0
+  for (;;) {
+    const { value, done: end } = await reader.read()
+    if (end) break
+    const chunk = Buffer.from(value)
+    hash.update(chunk)
+    out.write(chunk)
+    done += chunk.length
+    if (onProgress) onProgress(done, total)
+  }
+  await new Promise((ok, ko) => out.end((e) => (e ? ko(e) : ok())))
+  const actual = hash.digest('hex')
+  if (actual !== sha256) {
+    rmSync(dest, { force: true })
+    throw new Error(
+      `checksum mismatch for ${url}\n  expected ${sha256}\n  got      ${actual}\n` +
+        'The download was discarded rather than executed.'
+    )
+  }
+  return actual
+}
+
+function extractArchive(platform, archive, dir) {
+  const candidates = resolve.extractCommands(platform, archive, dir)
+  if (candidates.length === 0) throw new Error(`no extractor known for ${platform}`)
+  let last = null
+  for (const { cmd, args } of candidates) {
+    const r = spawnSync(cmd, args, { stdio: 'inherit' })
+    if (!r.error && r.status === 0) return cmd
+    last = r.error ? r.error.message : `${cmd} exited ${r.status}`
+  }
+  throw new Error(`could not unpack ${archive}: ${last}`)
+}
+
+/**
+ * Deletes every cached version but the one in use and the most recent other.
+ * Never fatal: a cache we failed to tidy is a disk-space problem, not a reason
+ * to refuse to run.
+ */
+function prune(root, keepVersion, log) {
+  let entries
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const versions = entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+    .map((e) => {
+      try {
+        return { name: e.name, mtimeMs: statSync(join(root, e.name)).mtimeMs }
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+  const victims = resolve.pruneVictims(versions, keepVersion)
+  for (const name of victims) {
+    try {
+      rmSync(join(root, name), { recursive: true, force: true })
+      if (log) log(`Removed cached build ${name}`)
+    } catch {
+      /* a build still running from this directory keeps it; try again next time */
+    }
+  }
+  return victims
+}
+
+async function ensureBuild(options = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    home = homedir(),
+    fetchImpl,
+    log = () => {},
+    onProgress,
+    ownVersion = require('../package.json').version
+  } = options
+
+  const manifest = await fetchManifest(env, platform, fetchImpl, ownVersion)
+  const version = manifest && manifest.version
+  if (!version) throw new Error('the release manifest carries no version')
+
+  const artifact = resolve.pickArtifact(manifest, platform, arch)
+  if (!artifact) {
+    throw new Error(`no Restorm build is published for ${platform}-${arch}`)
+  }
+
+  const root = resolve.cacheRoot(env, platform, home)
+  const versionDir = join(root, version)
+  const dir = join(versionDir, resolve.platformKey(platform, arch))
+  const exe = join(dir, artifact.exec)
+
+  if (existsSync(join(dir, COMPLETE_MARKER)) && existsSync(exe)) {
+    return { exe, version, cached: true }
+  }
+
+  // Everything below happens under a private staging directory, so two runs
+  // racing on the same cache (two CI jobs on one machine) cannot see each
+  // other's partial work. The loser of the race throws its copy away.
+  const stage = join(root, `.staging-${process.pid}-${platform}-${arch}`)
+  rmSync(stage, { recursive: true, force: true })
+  mkdirSync(stage, { recursive: true })
+
+  try {
+    const archive = join(stage, artifact.file)
+    log(`Fetching Restorm ${version} (${artifact.kind === 'appimage' ? 'AppImage' : 'archive'})…`)
+    await downloadVerified(artifact.url, archive, artifact.sha256, { fetchImpl, onProgress })
+
+    const payload = join(stage, 'payload')
+    mkdirSync(payload, { recursive: true })
+    if (artifact.kind === 'appimage') {
+      renameSync(archive, join(payload, artifact.exec))
+      chmodSync(join(payload, artifact.exec), 0o755)
+    } else {
+      extractArchive(platform, archive, payload)
+      rmSync(archive, { force: true })
+      const staged = join(payload, artifact.exec)
+      if (!existsSync(staged)) {
+        throw new Error(`the archive did not contain ${artifact.exec}`)
+      }
+      try {
+        chmodSync(staged, 0o755)
+      } catch {
+        /* Windows has no execute bit */
+      }
+    }
+
+    // The marker goes in before the directory is published, so the name a
+    // later run tests for can only appear on a finished install.
+    writeFileSync(join(payload, COMPLETE_MARKER), `${version}\n`)
+    mkdirSync(versionDir, { recursive: true })
+    try {
+      renameSync(payload, dir)
+    } catch (e) {
+      // Another process published the same version first — theirs is as good
+      // as ours, and verified the same way.
+      if (!existsSync(exe)) throw e
+    }
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+
+  prune(root, version, log)
+  return { exe, version, cached: false }
+}
+
+module.exports = {
+  COMPLETE_MARKER,
+  downloadVerified,
+  ensureBuild,
+  extractArchive,
+  fetchManifest,
+  prune
+}

package/lib/resolve.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * Pure resolution helpers for the launcher: where the cache lives, which
+ * artifact this machine needs, how to unpack it. No I/O happens here, so every
+ * rule below is testable on any platform regardless of the one it describes.
+ */
+
+const { join } = require('node:path')
+
+const DEFAULT_BASE = 'https://dl.restorm.app'
+
+/**
+ * Where the runnable binary sits once the artifact is unpacked. The manifest
+ * carries this per platform; these are the fallbacks for a manifest written
+ * before the field existed.
+ */
+const EXEC_BY_PLATFORM = {
+  linux: 'Restorm.AppImage',
+  darwin: 'Restorm.app/Contents/MacOS/Restorm',
+  win32: 'Restorm.exe'
+}
+
+function platformKey(platform, arch) {
+  return `${platform}-${arch}`
+}
+
+function downloadBase(env) {
+  return String(env.RESTORM_DL_BASE || DEFAULT_BASE).replace(/\/+$/, '')
+}
+
+/**
+ * One manifest per platform rather than a single merged one: the release
+ * workflow publishes from inside its build matrix, so no job ever holds all
+ * three platforms' artifacts at once. A per-platform file lets each job write
+ * its own without coordinating with the others.
+ *
+ * The version asked for is THIS package's own, because the two are published
+ * together and always match. It matters in CI: `restorm-cli@1.0.2` must run
+ * Restorm 1.0.2 six months from now, not whatever shipped since — a pinned
+ * dependency that silently follows a moving target is not pinned at all.
+ * `RESTORM_VERSION` overrides it, and `RESTORM_VERSION=latest` opts back into
+ * the newest release.
+ */
+function manifestUrl(env, platform, version) {
+  const base = downloadBase(env)
+  const want = env.RESTORM_VERSION || version
+  if (!want || want === 'latest' || String(want).startsWith('0.0.0')) {
+    return `${base}/latest/manifest-${platform}.json`
+  }
+  return `${base}/v${want}/manifest-${platform}.json`
+}
+
+/**
+ * The per-user cache. Each OS has a directory the system already understands as
+ * "regenerable data" — a cleaner may empty it, and the next run simply
+ * downloads again.
+ */
+function cacheRoot(env, platform, home) {
+  if (env.RESTORM_CACHE_DIR) return env.RESTORM_CACHE_DIR
+  if (platform === 'win32') {
+    return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'restorm', 'Cache')
+  }
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'restorm')
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'restorm')
+}
+
+function pickArtifact(manifest, platform, arch) {
+  const key = platformKey(platform, arch)
+  const entry = manifest && manifest.artifacts && manifest.artifacts[key]
+  if (!entry) return null
+  if (!entry.url || !entry.sha256) {
+    throw new Error(`the release manifest's ${key} entry has no url or no sha256`)
+  }
+  return {
+    kind: entry.kind || 'zip',
+    url: entry.url,
+    sha256: String(entry.sha256).toLowerCase(),
+    size: Number(entry.size) || 0,
+    file: entry.file || entry.url.split('/').pop(),
+    exec: entry.exec || EXEC_BY_PLATFORM[platform]
+  }
+}
+
+/**
+ * Unpacking is delegated to a tool every supported OS ships with, so the
+ * package keeps its zero dependencies.
+ *
+ * macOS gets `ditto` rather than `unzip`: a `.app` is a tree of symlinks and
+ * extended attributes, and ditto is the only extractor Apple guarantees will
+ * reproduce it faithfully. Windows gets bsdtar (`tar` since Windows 10), which
+ * reads zip and is an order of magnitude faster than Expand-Archive on a
+ * 400 MB archive — the fallback exists for older images.
+ */
+function extractCommands(platform, archive, dir) {
+  if (platform === 'darwin') {
+    return [
+      { cmd: 'ditto', args: ['-x', '-k', archive, dir] },
+      { cmd: 'unzip', args: ['-q', archive, '-d', dir] }
+    ]
+  }
+  if (platform === 'win32') {
+    return [
+      { cmd: 'tar', args: ['-xf', archive, '-C', dir] },
+      {
+        cmd: 'powershell',
+        args: [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          `Expand-Archive -LiteralPath ${JSON.stringify(archive)} -DestinationPath ${JSON.stringify(dir)} -Force`
+        ]
+      }
+    ]
+  }
+  return []
+}
+
+/**
+ * Which cached versions to delete once `keepVersion` is in place. Keeping one
+ * previous version costs disk but saves the whole download when a machine
+ * alternates between a released and a preview build, or when a release is
+ * rolled back.
+ */
+function pruneVictims(versions, keepVersion, keep = 2) {
+  return versions
+    .filter((v) => v.name !== keepVersion)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(Math.max(0, keep - 1))
+    .map((v) => v.name)
+}
+
+module.exports = {
+  DEFAULT_BASE,
+  EXEC_BY_PLATFORM,
+  cacheRoot,
+  downloadBase,
+  extractCommands,
+  manifestUrl,
+  pickArtifact,
+  platformKey,
+  pruneVictims
+}

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "restorm-cli",
-  "version": "1.0.1",
-  "description": "Restorm — local-first API testing environment (REST, GraphQL, gRPC, WebSocket, MQTT, Redis, AMQP…). This package launches your installed Restorm or bootstraps the right build for your platform.",
+  "version": "1.0.2",
+  "description": "Restorm — local-first API testing environment (REST, GraphQL, gRPC, WebSocket, MQTT, Redis, AMQP…). Runs Restorm from a terminal or from CI: your installation if you have one, otherwise the official build, downloaded once, checksum-verified and cached.",
   "bin": {
     "restorm": "bin/restorm.js"
   },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
   "files": [
-    "bin"
+    "bin",
+    "lib",
+    "README.md"
   ],
   "engines": {
     "node": ">=18"