@shings/raven 0.1.13

package/bin/raven.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/cli");
+
+main(process.argv.slice(2))
+  .then((code) => {
+    if (Number.isInteger(code)) process.exit(code);
+  })
+  .catch((error) => {
+    console.error(error && error.message ? error.message : String(error));
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@shings/raven",
+  "version": "0.1.13",
+  "description": "npx runner for the Raven engine and UI GitHub Release bundle",
+  "license": "MIT",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shingyusik/oracle-todo.git",
+    "directory": "npm/raven"
+  },
+  "bin": {
+    "raven": "bin/raven.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/archive.js

@@ -0,0 +1,99 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+async function downloadFile(url, destination, { fetchImpl = globalThis.fetch } = {}) {
+  if (!fetchImpl) throw new Error("Download requires Node.js 18 or newer with global fetch support");
+  const response = await fetchImpl(url);
+  if (!response.ok) throw new Error(`Download failed with HTTP ${response.status}`);
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(destination, buffer);
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore", ...options });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with code ${code}`));
+    });
+  });
+}
+
+async function extractArchive(archivePath, destination, { platform = process.platform } = {}) {
+  await fs.mkdir(destination, { recursive: true });
+  if (archivePath.endsWith(".tar.gz")) {
+    await run("tar", ["-xzf", archivePath, "-C", destination]);
+    return;
+  }
+  if (archivePath.endsWith(".zip")) {
+    if (platform === "win32") {
+      await run("powershell", ["-NoProfile", "-Command", `Expand-Archive -Force ${JSON.stringify(archivePath)} ${JSON.stringify(destination)}`]);
+      return;
+    }
+    await run("unzip", ["-q", "-o", archivePath, "-d", destination]);
+    return;
+  }
+  throw new Error(`Unsupported archive format: ${archivePath}`);
+}
+
+async function verifyChecksum(archivePath, checksumsText, expectedName) {
+  const line = checksumsText
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find((entry) => entry.endsWith(` ${expectedName}`) || entry.endsWith(` *${expectedName}`));
+  if (!line) {
+    throw new Error(`Checksum entry not found for ${expectedName}`);
+  }
+
+  const expected = line.split(/\s+/)[0];
+  const actual = crypto.createHash("sha256").update(await fs.readFile(archivePath)).digest("hex");
+  if (actual !== expected) {
+    throw new Error(`Checksum mismatch for ${expectedName}`);
+  }
+}
+
+async function findExtractedBinary(directory, binaryName) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isFile() && entry.name === binaryName) {
+      return entryPath;
+    }
+    if (entry.isDirectory()) {
+      try {
+        const found = await findExtractedBinary(entryPath, binaryName);
+        if (found) return found;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  return null;
+}
+
+async function activateBinary(paths, binaryName) {
+  await fs.mkdir(paths.binDir, { recursive: true });
+  let source = paths.versionedBinary;
+  try {
+    await fs.access(source);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    source = await findExtractedBinary(paths.versionDir, binaryName);
+    if (!source) throw error;
+  }
+  await fs.copyFile(source, paths.activeBinary);
+  if (!binaryName.endsWith(".exe")) {
+    await fs.chmod(paths.activeBinary, 0o755);
+  }
+}
+
+module.exports = {
+  activateBinary,
+  downloadFile,
+  extractArchive,
+  verifyChecksum,
+};

package/src/cache.js

@@ -0,0 +1,62 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+function pathsFor(root, version, binaryName) {
+  const binDir = path.join(root, "bin");
+  const versionsDir = path.join(root, "versions");
+  const versionDir = path.join(versionsDir, version);
+  return {
+    root,
+    binDir,
+    versionsDir,
+    versionDir,
+    metadataPath: path.join(root, "metadata.json"),
+    activeBinary: path.join(binDir, binaryName),
+    versionedBinary: path.join(versionDir, binaryName),
+  };
+}
+
+function uiPathsFor(root, version) {
+  const uiDir = path.join(root, "ui");
+  const uiVersionDir = path.join(uiDir, version);
+  return {
+    uiDir,
+    uiVersionDir,
+    uiIndexPath: path.join(uiVersionDir, "index.html"),
+  };
+}
+
+async function readMetadata(root) {
+  try {
+    return JSON.parse(await fs.readFile(path.join(root, "metadata.json"), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeMetadata(root, metadata) {
+  await fs.mkdir(root, { recursive: true });
+  await fs.writeFile(path.join(root, "metadata.json"), `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+async function isUsableFile(filePath, executable = false) {
+  if (!filePath) return false;
+  try {
+    if (!(await fs.stat(filePath)).isFile()) return false;
+    const mode = fs.constants.R_OK | (executable && process.platform !== "win32" ? fs.constants.X_OK : 0);
+    await fs.access(filePath, mode);
+    return true;
+  } catch (error) {
+    if (["EACCES", "ENOENT", "ENOTDIR"].includes(error.code)) return false;
+    throw error;
+  }
+}
+
+module.exports = {
+  isUsableFile,
+  pathsFor,
+  readMetadata,
+  uiPathsFor,
+  writeMetadata,
+};

package/src/cli.js

@@ -0,0 +1,65 @@
+const path = require("node:path");
+
+const { isUsableFile, readMetadata } = require("./cache");
+const { topLevelCommandIndex } = require("./command-index");
+const { cacheDir, PACKAGE_NAME } = require("./config");
+const { installBundle, installEngine, updateBundle } = require("./install");
+const { runEngine } = require("./runner");
+const { runUi } = require("./ui-command");
+
+async function main(args, options = {}) {
+  const env = options.env || process.env;
+  const log = options.log || console.log;
+  const install = options.installEngine || installEngine;
+  const installAll = options.installBundle || installBundle;
+  const updateAll = options.updateBundle || updateBundle;
+  const run = options.runEngine || runEngine;
+  const ui = options.runUi || runUi;
+  const command = args[topLevelCommandIndex(args)];
+
+  if (command === "install") {
+    const result = await installAll({ env });
+    log(`${PACKAGE_NAME}: ${result.status || "installed"} ${result.installedVersion || ""}`.trim());
+    return 0;
+  }
+
+  if (command === "update") {
+    const result = await updateAll({ env });
+    log(`${PACKAGE_NAME}: ${result.status || "installed"} ${result.installedVersion || ""}`.trim());
+    return 0;
+  }
+
+  if (command === "ui") {
+    return ui(args, { env, installBundle: installAll, log });
+  }
+
+  if (command === "version") {
+    const metadata = await readMetadata(cacheDir(env));
+    log(`${PACKAGE_NAME} wrapper`);
+    log(`raven ${metadata ? metadata.installedVersion : "not installed"}`);
+    log(`raven-ui ${metadata && metadata.uiVersion ? metadata.uiVersion : "not installed"}`);
+    return 0;
+  }
+
+  if (command === "doctor") {
+    const metadata = await readMetadata(cacheDir(env));
+    if (!metadata) throw new Error("raven is not installed; run install first");
+    if (!(await isUsableFile(metadata.binaryPath, true))) {
+      throw new Error("raven binary is missing or unusable; run install first");
+    }
+    if (!metadata.uiPath) throw new Error("raven-ui is not installed; run install first");
+    if (!(await isUsableFile(path.join(metadata.uiPath, "index.html")))) {
+      throw new Error("raven-ui is missing or unusable; run install first");
+    }
+    log(`cache ok: ${metadata.binaryPath}`);
+    log(`ui ok: ${metadata.uiPath}`);
+    return 0;
+  }
+
+  const installed = await install({ env });
+  const binaryPath = installed.binaryPath;
+  const exitCode = await run(args, { binaryPath });
+  return exitCode;
+}
+
+module.exports = { main };

package/src/command-index.js

@@ -0,0 +1,9 @@
+function topLevelCommandIndex(args) {
+  let index = 0;
+  while (args[index] === "--home" || args[index]?.startsWith("--home=")) {
+    index += args[index] === "--home" ? 2 : 1;
+  }
+  return index;
+}
+
+module.exports = { topLevelCommandIndex };

package/src/config.js

@@ -0,0 +1,21 @@
+const path = require("node:path");
+const os = require("node:os");
+
+const PACKAGE_NAME = "@shings/raven";
+const COMMAND_NAME = "raven";
+const ENGINE_BINARY = "raven";
+const GITHUB_REPOSITORY = "shingyusik/oracle-todo";
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".local", "share", "raven");
+
+function cacheDir(env = process.env) {
+  return env.RAVEN_CACHE_DIR || DEFAULT_CACHE_DIR;
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  COMMAND_NAME,
+  ENGINE_BINARY,
+  GITHUB_REPOSITORY,
+  DEFAULT_CACHE_DIR,
+  cacheDir,
+};

package/src/github.js

@@ -0,0 +1,38 @@
+function tagFor(version) {
+  if (!version) return null;
+  return String(version).startsWith("v") ? String(version) : `v${version}`;
+}
+
+async function fetchRelease({ version, repository, token, fetchImpl = globalThis.fetch }) {
+  if (!fetchImpl) {
+    throw new Error("This command requires Node.js 18 or newer with global fetch support");
+  }
+
+  const endpoint = version
+    ? `https://api.github.com/repos/${repository}/releases/tags/${tagFor(version)}`
+    : `https://api.github.com/repos/${repository}/releases/latest`;
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "@shings/raven",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const response = await fetchImpl(endpoint, { headers });
+  if (!response.ok) {
+    throw new Error(`GitHub release lookup failed with HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+function selectAsset(release, expectedName) {
+  const asset = (release.assets || []).find((candidate) => candidate.name === expectedName);
+  if (!asset) {
+    throw new Error(`Release asset not found: ${expectedName}`);
+  }
+  return asset;
+}
+
+module.exports = {
+  fetchRelease,
+  selectAsset,
+};

package/src/install.js

@@ -0,0 +1,149 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const { downloadFile, extractArchive, activateBinary, verifyChecksum } = require("./archive");
+const { isUsableFile, pathsFor, readMetadata, writeMetadata } = require("./cache");
+const { cacheDir, GITHUB_REPOSITORY } = require("./config");
+const { fetchRelease, selectAsset } = require("./github");
+const { assetName, resolvePlatform } = require("./platform");
+const { installUiArtifact } = require("./ui-artifact");
+const { compareVersions, normalizeVersion } = require("./version");
+
+async function fetchRequestedRelease(options, env) {
+  return (options.fetchReleaseImpl || fetchRelease)({
+    repository: options.repository || GITHUB_REPOSITORY,
+    version: env.RAVEN_VERSION,
+    token: env.RAVEN_GITHUB_TOKEN,
+    fetchImpl: options.fetchImpl,
+  });
+}
+
+async function installBundle(options = {}) {
+  const env = options.env || process.env;
+  const cacheRoot = options.cacheRoot || cacheDir(env);
+  const platformInfo = options.platformInfo || resolvePlatform();
+  const metadata = await readMetadata(cacheRoot);
+  const release = await fetchRequestedRelease(options, env);
+  const version = normalizeVersion(release.tag_name);
+
+  if (
+    metadata
+    && metadata.installedVersion === version
+    && metadata.uiVersion === version
+    && await isUsableFile(metadata.binaryPath, true)
+    && await isUsableFile(metadata.uiPath && path.join(metadata.uiPath, "index.html"))
+  ) {
+    return { status: "already-installed", ...metadata };
+  }
+
+  const engine = await installRelease({
+    ...options,
+    cacheRoot,
+    platformInfo,
+    release,
+    version,
+    activate: false,
+    writeMetadata: false,
+  });
+  const ui = await installUiArtifact({ ...options, cacheRoot, release, version });
+  await activateBinary(pathsFor(cacheRoot, version, platformInfo.binaryName), platformInfo.binaryName);
+  const metadataNext = {
+    ...engine,
+    uiVersion: ui.uiVersion,
+    uiAssetName: ui.uiAssetName,
+    uiPath: ui.uiPath,
+  };
+  await writeMetadata(cacheRoot, metadataNext);
+  return metadataNext;
+}
+
+async function updateBundle(options = {}) {
+  return installBundle(options);
+}
+
+async function installEngine(options = {}) {
+  const env = options.env || process.env;
+  const cacheRoot = options.cacheRoot || cacheDir(env);
+  const platformInfo = options.platformInfo || resolvePlatform();
+  const metadata = await readMetadata(cacheRoot);
+  const requestedVersion = env.RAVEN_VERSION;
+
+  if (metadata && !requestedVersion && await isUsableFile(metadata.binaryPath, true)) {
+    return { status: "already-installed", ...metadata };
+  }
+
+  const release = await (options.fetchReleaseImpl || fetchRelease)({
+    repository: options.repository || GITHUB_REPOSITORY,
+    version: requestedVersion,
+    token: env.RAVEN_GITHUB_TOKEN,
+    fetchImpl: options.fetchImpl,
+  });
+
+  const version = normalizeVersion(release.tag_name);
+  if (metadata && metadata.installedVersion === version && await isUsableFile(metadata.binaryPath, true)) {
+    return { status: "already-installed", ...metadata };
+  }
+
+  return installRelease({ ...options, cacheRoot, platformInfo, release, version });
+}
+
+async function updateEngine(options = {}) {
+  const env = options.env || process.env;
+  const cacheRoot = options.cacheRoot || cacheDir(env);
+  const platformInfo = options.platformInfo || resolvePlatform();
+  const metadata = await readMetadata(cacheRoot);
+  const release = await (options.fetchReleaseImpl || fetchRelease)({
+    repository: options.repository || GITHUB_REPOSITORY,
+    version: env.RAVEN_VERSION,
+    token: env.RAVEN_GITHUB_TOKEN,
+    fetchImpl: options.fetchImpl,
+  });
+  const version = normalizeVersion(release.tag_name);
+
+  if (
+    metadata
+    && compareVersions(version, metadata.installedVersion) <= 0
+    && await isUsableFile(metadata.binaryPath, true)
+  ) {
+    return { status: "up-to-date", ...metadata };
+  }
+
+  return installRelease({ ...options, cacheRoot, platformInfo, release, version });
+}
+
+async function installRelease(options) {
+  const expectedAsset = assetName(options.version, options.platformInfo.target);
+  const asset = selectAsset(options.release, expectedAsset);
+  const checksumAsset = selectAsset(options.release, "SHA256SUMS");
+  const paths = pathsFor(options.cacheRoot, options.version, options.platformInfo.binaryName);
+  const archivePath = path.join(paths.versionDir, expectedAsset);
+  const checksumPath = path.join(paths.versionDir, "SHA256SUMS");
+
+  await fs.rm(paths.versionDir, { recursive: true, force: true });
+  await fs.mkdir(paths.versionDir, { recursive: true });
+  await (options.downloadFileImpl || downloadFile)(asset.browser_download_url, archivePath, { fetchImpl: options.fetchImpl });
+  await (options.downloadFileImpl || downloadFile)(checksumAsset.browser_download_url, checksumPath, { fetchImpl: options.fetchImpl });
+  await verifyChecksum(archivePath, await fs.readFile(checksumPath, "utf8"), expectedAsset);
+  await (options.extractArchiveImpl || extractArchive)(archivePath, paths.versionDir, { platform: process.platform });
+  if (options.activate !== false) {
+    await activateBinary(paths, options.platformInfo.binaryName);
+  }
+
+  const metadata = {
+    installedVersion: options.version,
+    assetName: expectedAsset,
+    binaryPath: paths.activeBinary,
+    installedAt: (options.now || (() => new Date()))().toISOString(),
+  };
+  if (options.writeMetadata !== false) {
+    await writeMetadata(options.cacheRoot, metadata);
+  }
+  return { status: "installed", ...metadata };
+}
+
+module.exports = {
+  installBundle,
+  installEngine,
+  updateBundle,
+  updateEngine,
+};

package/src/platform.js

@@ -0,0 +1,37 @@
+const SUPPORTED_TARGETS = [
+  "aarch64-apple-darwin",
+  "x86_64-apple-darwin",
+  "x86_64-unknown-linux-gnu",
+  "x86_64-pc-windows-msvc",
+];
+
+const TARGETS = {
+  "darwin/arm64": { target: "aarch64-apple-darwin", extension: ".tar.gz", binaryName: "raven" },
+  "darwin/x64": { target: "x86_64-apple-darwin", extension: ".tar.gz", binaryName: "raven" },
+  "linux/x64": { target: "x86_64-unknown-linux-gnu", extension: ".tar.gz", binaryName: "raven" },
+  "win32/x64": { target: "x86_64-pc-windows-msvc", extension: ".zip", binaryName: "raven.exe" },
+};
+
+function normalizeVersion(version) {
+  return String(version).replace(/^v/, "");
+}
+
+function resolvePlatform({ platform = process.platform, arch = process.arch } = {}) {
+  const key = `${platform}/${arch}`;
+  const resolved = TARGETS[key];
+  if (!resolved) {
+    throw new Error(`Unsupported platform ${key}. Supported targets: ${SUPPORTED_TARGETS.join(", ")}`);
+  }
+  return { platform, arch, ...resolved };
+}
+
+function assetName(version, target) {
+  const extension = target === "x86_64-pc-windows-msvc" ? ".zip" : ".tar.gz";
+  return `raven-${normalizeVersion(version)}-${target}${extension}`;
+}
+
+module.exports = {
+  SUPPORTED_TARGETS,
+  assetName,
+  resolvePlatform,
+};

package/src/runner.js

@@ -0,0 +1,11 @@
+const { spawn } = require("node:child_process");
+
+function runEngine(args, { binaryPath, stdio = "inherit" }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binaryPath, args, { stdio });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code || 0));
+  });
+}
+
+module.exports = { runEngine };

package/src/ui-artifact.js

@@ -0,0 +1,67 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const { downloadFile, extractArchive, verifyChecksum } = require("./archive");
+const { uiPathsFor } = require("./cache");
+const { selectAsset } = require("./github");
+
+function uiAssetName(version) {
+  return `raven-ui-${version}.tar.gz`;
+}
+
+async function findIndexRoot(directory) {
+  const indexPath = path.join(directory, "index.html");
+  try {
+    await fs.access(indexPath);
+    return directory;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const found = await findIndexRoot(path.join(directory, entry.name));
+    if (found) return found;
+  }
+  return null;
+}
+
+async function installUiArtifact(options) {
+  const expectedAsset = uiAssetName(options.version);
+  const asset = selectAsset(options.release, expectedAsset);
+  const checksumAsset = selectAsset(options.release, "SHA256SUMS");
+  const paths = uiPathsFor(options.cacheRoot, options.version);
+  const archivePath = path.join(paths.uiVersionDir, expectedAsset);
+  const checksumPath = path.join(paths.uiVersionDir, "SHA256SUMS");
+
+  await fs.rm(paths.uiVersionDir, { recursive: true, force: true });
+  await fs.mkdir(paths.uiVersionDir, { recursive: true });
+  await (options.downloadFileImpl || downloadFile)(asset.browser_download_url, archivePath, { fetchImpl: options.fetchImpl });
+  await (options.downloadFileImpl || downloadFile)(checksumAsset.browser_download_url, checksumPath, { fetchImpl: options.fetchImpl });
+  await verifyChecksum(archivePath, await fs.readFile(checksumPath, "utf8"), expectedAsset);
+  await (options.extractArchiveImpl || extractArchive)(archivePath, paths.uiVersionDir, { platform: process.platform });
+
+  const root = await findIndexRoot(paths.uiVersionDir);
+  if (!root) {
+    throw new Error(`UI artifact is missing index.html: ${expectedAsset}`);
+  }
+  if (root !== paths.uiVersionDir) {
+    const stagingDir = `${paths.uiVersionDir}.staging`;
+    await fs.rm(stagingDir, { recursive: true, force: true });
+    await fs.rename(root, stagingDir);
+    await fs.rm(paths.uiVersionDir, { recursive: true, force: true });
+    await fs.rename(stagingDir, paths.uiVersionDir);
+  }
+
+  return {
+    uiVersion: options.version,
+    uiAssetName: expectedAsset,
+    uiPath: paths.uiVersionDir,
+  };
+}
+
+module.exports = {
+  installUiArtifact,
+  uiAssetName,
+};

package/src/ui-command.js

@@ -0,0 +1,17 @@
+const { runEngine } = require("./runner");
+const { topLevelCommandIndex } = require("./command-index");
+
+async function runUi(args, options = {}) {
+  const uiIndex = topLevelCommandIndex(args);
+  if (args[uiIndex] !== "ui") throw new Error("Expected native raven ui command");
+
+  const installed = await options.installBundle({ env: options.env || process.env });
+  const uiArgs = args.slice(uiIndex + 1);
+  const hasUiPath = uiArgs.some((arg) => arg === "--ui-path" || arg.startsWith("--ui-path="));
+  const nativeArgs = hasUiPath
+    ? args
+    : [...args.slice(0, uiIndex + 1), "--ui-path", installed.uiPath, ...uiArgs];
+  return (options.runEngine || runEngine)(nativeArgs, { binaryPath: installed.binaryPath });
+}
+
+module.exports = { runUi };

package/src/version.js

@@ -0,0 +1,19 @@
+function normalizeVersion(version) {
+  return String(version).trim().replace(/^v/, "");
+}
+
+function compareVersions(left, right) {
+  const a = normalizeVersion(left).split(".").map((part) => Number.parseInt(part, 10));
+  const b = normalizeVersion(right).split(".").map((part) => Number.parseInt(part, 10));
+  for (let index = 0; index < 3; index += 1) {
+    const delta = (a[index] || 0) - (b[index] || 0);
+    if (delta > 0) return 1;
+    if (delta < 0) return -1;
+  }
+  return 0;
+}
+
+module.exports = {
+  compareVersions,
+  normalizeVersion,
+};