@kujolang/kujo-runtime 1.2.2

package/README.md

@@ -0,0 +1,14 @@
+# `@kujolang/kujo-runtime`
+
+This package installs the `kujo` command from a platform-specific optional
+dependency. It performs no network access and runs no npm lifecycle scripts.
+
+The package also exports `resolveKujoBinary()` and `getKujoRuntimeInfo()` for
+tools that need to locate the native executable without starting it. Runtime
+information includes the package/runtime versions, binary path, and bundled
+source. TypeScript declarations are included. Typed resolution failures include
+stable `code`, `platform`, and `arch` fields.
+
+Supported targets are Linux x64/arm64, macOS x64/arm64, and Windows x64.
+Installing with optional dependencies disabled omits the runtime binary;
+the launcher reports that condition with remediation guidance.

package/bin/kujo.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { resolveKujoBinary } = require('..');
+
+function fail(message) {
+  process.stderr.write(`kujo: ${message}\n`);
+  process.exitCode = 1;
+}
+
+let binaryPath;
+try {
+  binaryPath = resolveKujoBinary();
+} catch (error) {
+  fail(error.message);
+  return;
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  shell: false,
+  windowsHide: false
+});
+
+if (result.error) {
+  fail(`failed to start the bundled runtime: ${result.error.message}`);
+} else if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exitCode = result.status === null ? 1 : result.status;
+}

package/index.d.ts

@@ -0,0 +1,39 @@
+export type KujoRuntimeSource = 'bundled';
+export type KujoRuntimePlatform = 'darwin' | 'linux' | 'win32';
+export type KujoRuntimeArch = 'arm64' | 'x64';
+
+export interface KujoRuntimeInfo {
+  platform: KujoRuntimePlatform;
+  arch: KujoRuntimeArch;
+  packageName: string;
+  packageVersion: string;
+  runtimeVersion: string;
+  binaryName: 'kujo' | 'kujo.exe';
+  binaryPath: string;
+  source: KujoRuntimeSource;
+}
+
+export interface KujoRuntimeOptions {
+  platform?: KujoRuntimePlatform;
+  arch?: KujoRuntimeArch;
+}
+
+export class KujoRuntimeError extends Error {
+  readonly code: string;
+  readonly platform: string;
+  readonly arch: string;
+}
+
+export class UnsupportedPlatformError extends KujoRuntimeError {}
+
+export class MissingPlatformPackageError extends KujoRuntimeError {
+  readonly packageName: string;
+}
+
+export class BinaryNotFoundError extends KujoRuntimeError {
+  readonly packageName: string;
+  readonly binaryPath: string;
+}
+
+export function getKujoRuntimeInfo(options?: KujoRuntimeOptions): KujoRuntimeInfo;
+export function resolveKujoBinary(options?: KujoRuntimeOptions): string;

package/index.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const RUNTIME_PACKAGE_VERSION = require('./package.json').version;
+
+const TARGETS = Object.freeze({
+  'darwin-arm64': Object.freeze({
+    packageName: '@kujolang/kujo-darwin-arm64',
+    binaryName: 'kujo'
+  }),
+  'darwin-x64': Object.freeze({
+    packageName: '@kujolang/kujo-darwin-x64',
+    binaryName: 'kujo'
+  }),
+  'linux-x64': Object.freeze({
+    packageName: '@kujolang/kujo-linux-x64',
+    binaryName: 'kujo'
+  }),
+  'linux-arm64': Object.freeze({
+    packageName: '@kujolang/kujo-linux-arm64',
+    binaryName: 'kujo'
+  }),
+  'win32-x64': Object.freeze({
+    packageName: '@kujolang/kujo-win32-x64',
+    binaryName: 'kujo.exe'
+  })
+});
+
+function targetFor(platform = process.platform, arch = process.arch) {
+  return TARGETS[`${platform}-${arch}`] || null;
+}
+
+class KujoRuntimeError extends Error {
+  constructor(message, code, platform, arch, options = {}) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.platform = platform;
+    this.arch = arch;
+  }
+}
+
+class UnsupportedPlatformError extends KujoRuntimeError {
+  constructor(platform, arch) {
+    const supported = Object.keys(TARGETS).sort().join(', ');
+    super(
+      `Kujo does not provide an npm runtime for ${platform}-${arch}. Supported targets: ${supported}.`,
+      'KUJO_UNSUPPORTED_PLATFORM',
+      platform,
+      arch
+    );
+  }
+}
+
+class MissingPlatformPackageError extends KujoRuntimeError {
+  constructor(platform, arch, target, cause) {
+    super(
+      [
+        `Kujo's platform package ${target.packageName} is not installed.`,
+        'Reinstall @kujolang/kujo-runtime without --omit=optional or --no-optional,',
+        'and ensure your package manager is allowed to install optional dependencies.'
+      ].join(' '),
+      'KUJO_PLATFORM_PACKAGE_MISSING',
+      platform,
+      arch,
+      { cause }
+    );
+    this.packageName = target.packageName;
+  }
+}
+
+class BinaryNotFoundError extends KujoRuntimeError {
+  constructor(platform, arch, packageName, binaryPath) {
+    super(
+      `Kujo's platform package ${packageName} does not contain the expected binary at ${binaryPath}. Reinstall the package and verify your npm cache.`,
+      'KUJO_BINARY_MISSING',
+      platform,
+      arch
+    );
+    this.packageName = packageName;
+    this.binaryPath = binaryPath;
+  }
+}
+
+function selectedTarget(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const target = targetFor(platform, arch);
+
+  if (!target) {
+    throw new UnsupportedPlatformError(platform, arch);
+  }
+
+  return { platform, arch, ...target };
+}
+
+function resolveRuntime(options = {}) {
+  const { platform, arch, packageName, binaryName } = selectedTarget(options);
+  const resolvePackage = options.resolvePackage || require.resolve;
+  const fileExists = options.fileExists || fs.existsSync;
+  const readManifest = options.readManifest || ((manifestPath) => JSON.parse(fs.readFileSync(manifestPath, 'utf8')));
+
+  let manifestPath;
+  try {
+    manifestPath = resolvePackage(`${packageName}/package.json`);
+  } catch (error) {
+    throw new MissingPlatformPackageError(platform, arch, { packageName }, error);
+  }
+
+  const binaryPath = path.join(path.dirname(manifestPath), 'bin', binaryName);
+  if (!fileExists(binaryPath)) {
+    throw new BinaryNotFoundError(platform, arch, packageName, binaryPath);
+  }
+
+  const platformManifest = readManifest(manifestPath);
+  return Object.freeze({
+    platform,
+    arch,
+    packageName,
+    packageVersion: RUNTIME_PACKAGE_VERSION,
+    runtimeVersion: platformManifest.version,
+    binaryName,
+    binaryPath,
+    source: 'bundled'
+  });
+}
+
+function getKujoRuntimeInfo(options = {}) {
+  return resolveRuntime(options);
+}
+
+function resolveKujoBinary(options = {}) {
+  return resolveRuntime(options).binaryPath;
+}
+
+module.exports = {
+  BinaryNotFoundError,
+  KujoRuntimeError,
+  MissingPlatformPackageError,
+  TARGETS,
+  UnsupportedPlatformError,
+  getKujoRuntimeInfo,
+  resolveKujoBinary,
+  targetFor
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kujolang/kujo-runtime",
+  "version": "1.2.2",
+  "description": "Kujo programming language runtime",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kujolang/kujo.git",
+    "directory": "npm/runtime"
+  },
+  "homepage": "https://github.com/kujolang/kujo",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "kujo": "bin/kujo.js"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/kujo.js",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@kujolang/kujo-darwin-arm64": "1.2.2",
+    "@kujolang/kujo-darwin-x64": "1.2.2",
+    "@kujolang/kujo-linux-arm64": "1.2.2",
+    "@kujolang/kujo-linux-x64": "1.2.2",
+    "@kujolang/kujo-win32-x64": "1.2.2"
+  }
+}