@caura-ai/caura 0.10.2

package/README.md

@@ -0,0 +1,41 @@
+# `@caura-ai/caura` — npx / npm wrapper
+
+Install and run the Caura broker from the Node ecosystem:
+
+```bash
+npx @caura-ai/caura --help        # run without a global install
+npm install -g @caura-ai/caura    # or install the `caura` command globally
+```
+
+## How it works
+
+This package is a thin dispatcher — the broker itself is a single Go binary.
+
+- On install (`postinstall`, [`scripts/install.js`](scripts/install.js)) it
+  detects your platform, downloads the matching release archive from the public
+  release mirror, verifies its SHA-256 against the published `checksums.txt`,
+  and copies the canonical root payload into `bin/`. Pre-bridge archives fall
+  back to their compatibility payload.
+- [`bin/caura.js`](bin/caura.js) uses the shared launcher to execute that binary
+  with forwarded arguments and a canonical invocation name.
+
+The binary is downloaded from the public release mirror
+(`https://memclaw.net/memclaw/<tag>/`) — the same source the native installer <!-- legacy-name-floor: published mirror path -->
+uses, not this repository's private GitHub Releases. SHA-256 verification is
+the integrity gate.
+
+## Environment overrides
+
+Both are also read under their historical `MEMCLAW_*` spellings<!-- legacy-name-ok: rule 3 dual-read alias -->, which keep
+working indefinitely; the `CAURA_*` name wins when it holds a non-empty value.
+
+- `CAURA_BINARY_BASE` — base URL of a release mirror (default
+  `https://memclaw.net/memclaw`). Point it at an on-prem gateway's <!-- legacy-name-floor: published mirror path -->
+  `<origin>/memclaw` to install from a private deployment. <!-- legacy-name-floor: served mirror path -->
+- `CAURA_VERSION` — pin a specific release tag instead of the installed
+  package's version.
+
+The published package version is set from the release tag by the canonical npm
+workflow; the `0.0.0` in `package.json` is a local-checkout placeholder.
+
+Licensed under Apache-2.0, matching the `LICENSE` at the repository root.

package/bin/caura.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { invocationCommand, launch } = require('../lib/launcher.js');
+
+process.exit(launch(invocationCommand(process.argv[1])));

package/lib/launcher.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CANONICAL_COMMAND = 'caura';
+const LEGACY_COMMAND = 'memclaw'; // legacy-name-ok: permanent npm compatibility command
+const CANONICAL_PACKAGE = '@caura-ai/caura';
+const LEGACY_PACKAGE = '@caura-ai/memclawd'; // legacy-name-ok: permanent npm compatibility alias
+
+function invocationCommand(executable) {
+  let name = String(executable || '').split(/[\\/]/).pop().toLowerCase();
+  for (const suffix of ['.js', '.cmd', '.exe']) {
+    if (name.endsWith(suffix)) name = name.slice(0, -suffix.length);
+  }
+  return name === LEGACY_COMMAND ? LEGACY_COMMAND : CANONICAL_COMMAND;
+}
+
+function installPackage(command) {
+  return command === LEGACY_COMMAND ? LEGACY_PACKAGE : CANONICAL_PACKAGE;
+}
+
+function launch(command, args = process.argv.slice(2), runtime = {}) {
+  const platform = runtime.platform || process.platform;
+  const existsSync = runtime.existsSync || fs.existsSync;
+  const run = runtime.spawnSync || spawnSync;
+  const report = runtime.report || ((message) => console.error(message));
+  const suffix = platform === 'win32' ? '.exe' : '';
+  const binPath = path.join(__dirname, '..', 'bin', `${CANONICAL_COMMAND}${suffix}`);
+
+  if (!existsSync(binPath)) {
+    report(
+      `${command}: binary not found at ${binPath}. ` +
+        `The postinstall hook may have failed; reinstall via ` +
+        `'npm install -g ${installPackage(command)}' or download manually from ` +
+        `https://github.com/caura-ai/caura-daemon/releases.`,
+    );
+    return 1;
+  }
+
+  const result = run(binPath, args, {
+    stdio: 'inherit',
+    argv0: command,
+  });
+  if (result.error) {
+    report(`${command}: ${result.error.message || String(result.error)}`);
+    return 1;
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+module.exports = {
+  CANONICAL_COMMAND,
+  LEGACY_COMMAND,
+  invocationCommand,
+  launch,
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@caura-ai/caura",
+  "version": "0.10.2",
+  "description": "npx/npm wrapper for the Caura broker: downloads the platform binary from the public release mirror, SHA-256-verifies it, and executes it.",
+  "license": "Apache-2.0",
+  "homepage": "https://caura.ai",
+  "bin": {
+    "caura": "bin/caura.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/caura.js",
+    "lib/launcher.js",
+    "scripts/install.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caura-ai/caura-daemon.git",
+    "directory": "wrappers/npx"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,249 @@
+// Caura broker — npx wrapper postinstall (T124).
+//
+// Downloads the platform-specific signed binary from the public
+// release mirror and verifies SHA-256 against the published
+// checksums.txt. Same source + security posture as the
+// curl-pipe-shell installer at wrappers/curl/install.sh —
+// SHA-256 verification is the integrity gate.
+//
+// Runs as `npm install` / `npx` postinstall. On Windows
+// installs the .exe; on Unix-ish OSes installs the
+// unsuffixed binary.
+//
+// What this script does NOT do:
+//   - Auto-start the daemon.
+//   - Modify shell rc files (the binary lives in
+//     node_modules/@caura-ai/caura/bin/; `npx @caura-ai/caura`
+//     execs it directly).
+//   - Verify GPG signatures. The release pipeline
+//     publishes signed binaries (T116/T117/T118 once cert
+//     procurement lands) — npm's own provenance can also
+//     gate the wrapper itself; per-binary signatures are
+//     additive.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+const { pipeline } = require('stream/promises');
+const { spawnSync } = require('child_process');
+
+const CANONICAL_COMMAND = 'caura';
+const LEGACY_COMMAND = 'memclaw'; // legacy-name-ok: pre-bridge archive payload
+
+// Binaries come from the public release mirror, NOT this repo's GitHub
+// Releases: the repo is private, so unauthenticated downloads 404. The
+// mirror layout matches wrappers/curl/install.sh — <base>/<tag>/<archive>
+// plus <base>/latest.txt — and is owned by publish-mirror.yml. On-prem
+// gateways serve their own mirror at <origin>/memclaw; point
+// CAURA_BINARY_BASE there to install from a private deployment.
+//
+// Both spellings are read, CAURA_* first, and `||` picks the first
+// NON-EMPTY one rather than the first defined one — an operator whose
+// environment carries a blank CAURA_BINARY_BASE beside a working
+// old-spelling one would otherwise silently fetch from the public
+// mirror instead of their private deployment. Same contract as
+// wrappers/curl/install.sh and the uvx wrapper, which is the point: an
+// operator sets one name and every entry point honors it.
+const BINARY_BASE = (process.env.CAURA_BINARY_BASE || process.env.MEMCLAW_BINARY_BASE || 'https://memclaw.net/memclaw').replace(/\/+$/, ''); // legacy-name-ok: rule 3 dual-read alias
+const VERSION = (process.env.CAURA_VERSION || process.env.MEMCLAW_VERSION || readPackageVersion()).replace(/^v/, ''); // legacy-name-ok: rule 3 dual-read alias
+const BIN_DIR = path.join(__dirname, '..', 'bin');
+
+// Map node's `process.platform` / `process.arch` to the
+// goreleaser archive naming.
+function mapPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+  switch (platform) {
+    case 'darwin':
+      // The npm wrapper installs per-arch binaries (not
+      // universal) so the postinstall payload is smaller.
+      return { os: 'darwin', arch: arch === 'arm64' ? 'arm64' : 'x86_64', exe: false };
+    case 'linux':
+      return { os: 'linux', arch: arch === 'arm64' ? 'arm64' : 'x86_64', exe: false };
+    case 'win32':
+      return { os: 'windows', arch: arch === 'arm64' ? 'arm64' : 'x86_64', exe: true };
+    default:
+      die(`unsupported platform: ${platform}`);
+  }
+}
+
+function die(msg) {
+  console.error(`${CANONICAL_COMMAND} postinstall: ${msg}`);
+  process.exit(1);
+}
+
+function readPackageVersion() {
+  const pkg = require('../package.json');
+  // The wrapper's npm version is derived from the broker's
+  // git tag at publish time (see publish-npm.yml). Strip any
+  // leading "v" — npm versions don't carry it but the
+  // GitHub Release tag does.
+  return pkg.version.replace(/^v/, '');
+}
+
+function archiveName({ os, arch, exe }) {
+  const v = VERSION;
+  if (exe) {
+    return `memclaw_${v}_${os}_${arch}.zip`;
+  }
+  return `memclaw_${v}_${os}_${arch}.tar.gz`;
+}
+
+function rootMemberName(name) {
+  while (name.startsWith('./')) name = name.slice(2);
+  if (!name || name.includes('/') || name.includes('\\')) return null;
+  return name;
+}
+
+function selectRootMember(members, exe) {
+  const suffix = exe ? '.exe' : '';
+  const candidates = [`${CANONICAL_COMMAND}${suffix}`, `${LEGACY_COMMAND}${suffix}`];
+  const matches = new Map();
+
+  for (const member of members) {
+    const normalized = rootMemberName(member);
+    if (!candidates.includes(normalized)) continue;
+    if (matches.has(normalized)) {
+      throw new Error(`archive contains duplicate '${normalized}' entries`);
+    }
+    matches.set(normalized, member);
+  }
+
+  for (const candidate of candidates) {
+    if (matches.has(candidate)) return { archiveName: matches.get(candidate), candidate };
+  }
+  throw new Error(
+    `archive did not contain a canonical or pre-bridge root binary: ${candidates.join(', ')}`,
+  );
+}
+
+function runTar(args, capture = false) {
+  const options = capture
+    ? { encoding: 'utf8', maxBuffer: 1024 * 1024 }
+    : { stdio: 'inherit' };
+  const result = spawnSync('tar', args, options);
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = capture && result.stderr ? `: ${result.stderr.trim()}` : '';
+    throw new Error(`tar ${args[0]} failed with exit code ${result.status}${detail}`);
+  }
+  return capture ? result.stdout : '';
+}
+
+function extractPayload(archivePath, binDir, exe) {
+  const members = runTar(['-tf', archivePath], true).split(/\r?\n/).filter(Boolean);
+  const selected = selectRootMember(members, exe);
+  const tempDir = fs.mkdtempSync(path.join(binDir, '.caura-extract-'));
+
+  try {
+    runTar(['-xf', archivePath, '-C', tempDir, selected.archiveName]);
+    const extracted = path.join(tempDir, selected.candidate);
+    const info = fs.lstatSync(extracted);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new Error(`archive member '${selected.archiveName}' is not a regular file`);
+    }
+
+    const destination = path.join(binDir, `${CANONICAL_COMMAND}${exe ? '.exe' : ''}`);
+    fs.copyFileSync(extracted, destination);
+    if (!exe) fs.chmodSync(destination, 0o755);
+    return destination;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function fetchToFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { 'User-Agent': 'caura-npx-postinstall' } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return fetchToFile(res.headers.location, dest).then(resolve, reject);
+        }
+        if (res.statusCode !== 200) {
+          return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        }
+        const out = fs.createWriteStream(dest);
+        pipeline(res, out).then(resolve, reject);
+      })
+      .on('error', reject);
+  });
+}
+
+async function fetchText(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { 'User-Agent': 'caura-npx-postinstall' } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return fetchText(res.headers.location).then(resolve, reject);
+        }
+        if (res.statusCode !== 200) {
+          return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        }
+        let buf = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (buf += chunk));
+        res.on('end', () => resolve(buf));
+      })
+      .on('error', reject);
+  });
+}
+
+function sha256(filePath) {
+  return new Promise((resolve, reject) => {
+    const h = crypto.createHash('sha256');
+    const s = fs.createReadStream(filePath);
+    s.on('error', reject);
+    s.on('end', () => resolve(h.digest('hex')));
+    s.pipe(h);
+  });
+}
+
+async function main() {
+  const plat = mapPlatform();
+  const archive = archiveName(plat);
+  // The tag directory carries a leading "v" (VERSION is stripped of
+  // it); archive names do not.
+  const base = `${BINARY_BASE}/v${VERSION}`;
+  const archiveURL = `${base}/${archive}`;
+  const checksumsURL = `${base}/checksums.txt`;
+
+  if (!fs.existsSync(BIN_DIR)) fs.mkdirSync(BIN_DIR, { recursive: true });
+  const archivePath = path.join(BIN_DIR, archive);
+
+  console.log(`${CANONICAL_COMMAND} postinstall: downloading ${archiveURL}`);
+  await fetchToFile(archiveURL, archivePath);
+
+  console.log(`${CANONICAL_COMMAND} postinstall: downloading checksums`);
+  const checksums = await fetchText(checksumsURL);
+  const expectedLine = checksums.split('\n').find((l) => l.endsWith(` ${archive}`));
+  if (!expectedLine) die(`no checksum entry for ${archive}`);
+  const expected = expectedLine.split(/\s+/)[0];
+
+  console.log(`${CANONICAL_COMMAND} postinstall: verifying SHA-256`);
+  const actual = await sha256(archivePath);
+  if (actual !== expected) {
+    die(`checksum mismatch for ${archive}: expected=${expected} actual=${actual}`);
+  }
+
+  console.log(`${CANONICAL_COMMAND} postinstall: extracting`);
+  let binPath;
+  try {
+    binPath = extractPayload(archivePath, BIN_DIR, plat.exe);
+  } finally {
+    fs.rmSync(archivePath, { force: true });
+  }
+  console.log(`${CANONICAL_COMMAND} postinstall: installed ${binPath}`);
+}
+
+if (require.main === module) {
+  main().catch((err) => die(err.message || String(err)));
+}
+
+module.exports = {
+  extractPayload,
+  rootMemberName,
+  selectRootMember,
+};