@nyar/nyar 0.0.1 → 0.0.3

package/README.md

@@ -1,19 +1,31 @@
 # @nyar/nyar
 
-Cross-platform npm facade for the Nyar VM CLI and host APIs. Native and Wasm sidecars are published as separate platform packages under `projects/packages/`.
+Cross-platform Nyar host CLI and TypeScript facade. **CLI orchestration** uses [`@vmz/commander`](https://www.npmjs.com/package/@vmz/commander); **orthogonal native capabilities** are exported from `nyar-napi` via `src/native.ts`.
 
-## Example
+## CLI
 
-```typescript
-import { createNyarHost } from "@nyar/nyar";
-
-const host = await createNyarHost();
-await host.runBytecode(bytes);
+```bash
+nyar version
+nyar host-info
+nyar runtime list
+nyar runtime prepare --family wasi --artifact ./app.wasm --entry main
 ```
 
-Platform-specific binaries (`nyar-win32-x64`, `nyar-linux-x64`, `nyar-darwin-*`, `nyar-unknown-wasm32`) are resolved automatically when this package is installed on a matching host.
+## Programmatic native surface
+
+```typescript
+import { getHostInfo, listRuntimeFamilies, prepareRuntimeCommand } from '@nyar/nyar';
+
+const info = getHostInfo();
+const families = listRuntimeFamilies();
+const cmd = prepareRuntimeCommand({
+    family: 'wasi',
+    artifact: '/path/to/app.wasm',
+    entry: 'main',
+});
+```
 
-Build collect steps (`pnpm build:napi`, `pnpm build:wasm`) live in repository maintainer docs, not on this registry page.
+Platform collects (`nyar-win32-x64`, `nyar-linux-x64`, `nyar-darwin-*`, `nyar-unknown-wasm32`) are resolved automatically when installed on a matching host.
 
 ## License
 

package/bin/nyar.js

@@ -1,53 +1,5 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'node:module';
+#!/usr/bin/env node --experimental-strip-types
+import {runCli} from '../src/cli/cli.ts';
 
-import { hostPlatformKey, resolveCollect } from '../src/platform.ts';
-
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-
-function printUsage() {
-    console.error(`@nyar/nyar ${pkg.version} (${hostPlatformKey()})`);
-    console.error('Usage: nyar <command> [args...]');
-    console.error('Commands:');
-    console.error('  host-info   Print resolved platform collect metadata');
-    console.error('  version     Print package version');
-}
-
-function cmdHostInfo() {
-    const collect = resolveCollect();
-    console.log(JSON.stringify({ version: pkg.version, host: hostPlatformKey(), collect }, null, 2));
-}
-
-function cmdVersion() {
-    console.log(pkg.version);
-}
-
-const [command, ...rest] = process.argv.slice(2);
-
-if (!command || command === '--help' || command === '-h') {
-    printUsage();
-    process.exit(command ? 0 : 1);
-}
-
-if (command === 'version' || command === '--version' || command === '-V') {
-    cmdVersion();
-    process.exit(0);
-}
-
-if (command === 'host-info') {
-    cmdHostInfo();
-    process.exit(0);
-}
-
-// Forward unknown commands to wasmtime when the wasm collect is present (maintainer / CI path).
-const collect = resolveCollect();
-if (collect.kind === 'wasm' && rest.length > 0) {
-    const result = spawnSync('wasmtime', [collect.entry, ...rest], { stdio: 'inherit', shell: false });
-    process.exit(result.status ?? 1);
-}
-
-console.error(`nyar: unknown command '${command}'`);
-printUsage();
-process.exit(1);
+const code = await runCli(process.argv.slice(2));
+process.exit(code ?? 0);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@nyar/nyar",
-  "version": "0.0.1",
-  "description": "Nyar VM — cross-platform CLI (assembled from platform collects).",
+  "version": "0.0.3",
+  "description": "Nyar VM host CLI (@vmz/commander) and orthogonal nyar-napi bindings.",
   "type": "module",
   "license": "MIT",
   "main": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/cli.ts"
   },
   "bin": {
     "nyar": "bin/nyar.js"
@@ -17,14 +18,18 @@
     "readme.md",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+  },
   "dependencies": {
-    "@nyar/nyar-unknown-wasm32": "0.0.1"
+    "@vmz/commander": "^0.3.2",
+    "@nyar/nyar-unknown-wasm32": "0.0.3"
   },
   "optionalDependencies": {
-    "@nyar/nyar-win32-x64": "0.0.1",
-    "@nyar/nyar-linux-x64": "0.0.1",
-    "@nyar/nyar-darwin-x64": "0.0.1",
-    "@nyar/nyar-darwin-arm64": "0.0.1"
+    "@nyar/nyar-win32-x64": "0.0.3",
+    "@nyar/nyar-linux-x64": "0.0.3",
+    "@nyar/nyar-darwin-x64": "0.0.3",
+    "@nyar/nyar-darwin-arm64": "0.0.3"
   },
   "engines": {
     "node": ">=20"

package/readme.md

@@ -1,19 +1,31 @@
 # @nyar/nyar
 
-Cross-platform npm facade for the Nyar VM CLI and host APIs. Native and Wasm sidecars are published as separate platform packages under `projects/packages/`.
+Cross-platform Nyar host CLI and TypeScript facade. **CLI orchestration** uses [`@vmz/commander`](https://www.npmjs.com/package/@vmz/commander); **orthogonal native capabilities** are exported from `nyar-napi` via `src/native.ts`.
 
-## Example
+## CLI
 
-```typescript
-import { createNyarHost } from "@nyar/nyar";
-
-const host = await createNyarHost();
-await host.runBytecode(bytes);
+```bash
+nyar version
+nyar host-info
+nyar runtime list
+nyar runtime prepare --family wasi --artifact ./app.wasm --entry main
 ```
 
-Platform-specific binaries (`nyar-win32-x64`, `nyar-linux-x64`, `nyar-darwin-*`, `nyar-unknown-wasm32`) are resolved automatically when this package is installed on a matching host.
+## Programmatic native surface
+
+```typescript
+import { getHostInfo, listRuntimeFamilies, prepareRuntimeCommand } from '@nyar/nyar';
+
+const info = getHostInfo();
+const families = listRuntimeFamilies();
+const cmd = prepareRuntimeCommand({
+    family: 'wasi',
+    artifact: '/path/to/app.wasm',
+    entry: 'main',
+});
+```
 
-Build collect steps (`pnpm build:napi`, `pnpm build:wasm`) live in repository maintainer docs, not on this registry page.
+Platform collects (`nyar-win32-x64`, `nyar-linux-x64`, `nyar-darwin-*`, `nyar-unknown-wasm32`) are resolved automatically when installed on a matching host.
 
 ## License
 

package/src/cli/catalog.ts

@@ -0,0 +1,18 @@
+import type {LocaleCatalog} from '@vmz/commander';
+
+/** Nyar CLI 英文 catalog（产品层；`commander.*` 由框架 fallback 提供）。 */
+export const NYAR_CLI_CATALOG: LocaleCatalog = {
+    'cli.intro': 'Nyar VM host CLI — runtime dispatch and collect diagnostics',
+    'cli.cmd.version': 'Print package version and host protocol',
+    'cli.cmd.host-info': 'Print resolved platform collect and native host metadata',
+    'cli.cmd.runtime': 'Runtime family helpers',
+    'cli.cmd.runtime.list': 'List supported runtime families',
+    'cli.cmd.runtime.prepare': 'Expand a runtime template without executing',
+    'cli.cmd.runtime.run': 'Prepare and execute a runtime command',
+    'cli.opt.family': 'Runtime family id (clr, jvm, node, wasi, nyar-vm, …)',
+    'cli.opt.artifact': 'Artifact path (binary, jar, wasm module, …)',
+    'cli.opt.classpath': 'Classpath for JVM family',
+    'cli.opt.entry': 'Logical entry symbol',
+    'cli.opt.wasi-p3': 'Enable wasmtime -S p3 for WASI family',
+    'cli.opt.cwd': 'Working directory for runtime run',
+};

package/src/cli/cli.ts

@@ -0,0 +1,136 @@
+import {spawnSync} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+
+import type {Cli, Command, ParsedOptions} from '@vmz/commander';
+import {createCli} from '@vmz/commander';
+
+import {NYAR_CLI_CATALOG} from './catalog.ts';
+import {getHostInfo, listRuntimeFamilies, prepareRuntimeCommand, runPreparedCommand} from '../native.ts';
+import {hostPlatformKey, resolveCollect} from '../platform.ts';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json') as { version: string };
+
+function buildCli(): Cli {
+    const cli = createCli('nyar').catalog(() => NYAR_CLI_CATALOG).intro('cli.intro');
+
+    cli.command('version', 'cli.cmd.version').action(() => {
+        const info = getHostInfo();
+        console.log(`@nyar/nyar ${pkg.version}`);
+        console.log(`host ${info.hostProtocol} (${info.binding})`);
+        return 0;
+    });
+
+    cli.command('host-info', 'cli.cmd.host-info').action(() => {
+        const collect = resolveCollect();
+        const info = getHostInfo();
+        console.log(
+            JSON.stringify(
+                {
+                    version: pkg.version,
+                    host: hostPlatformKey(),
+                    hostProtocol: info.hostProtocol,
+                    binding: info.binding,
+                    collect,
+                },
+                null,
+                2,
+            ),
+        );
+        return 0;
+    });
+
+    const runtime = cli.command('runtime', 'cli.cmd.runtime');
+
+    runtime.command('list', 'cli.cmd.runtime.list').action(() => {
+        for (const family of listRuntimeFamilies()) {
+            console.log(family);
+        }
+        return 0;
+    });
+
+    const runtimeOpts = (cmd: Command) =>
+        cmd
+            .option('--family <id>', 'cli.opt.family')
+            .option('--artifact <path>', 'cli.opt.artifact')
+            .option('--classpath <path>', 'cli.opt.classpath')
+            .option('--entry <name>', 'cli.opt.entry')
+            .option('--wasi-p3', 'cli.opt.wasi-p3');
+
+    runtimeOpts(runtime.command('prepare', 'cli.cmd.runtime.prepare')).action((options: ParsedOptions) => {
+        const family = requireString(options, 'family');
+        const artifact = requireString(options, 'artifact');
+        const entry = requireString(options, 'entry');
+        const prepared = prepareRuntimeCommand({
+            family,
+            artifact: path.resolve(artifact),
+            classpath: typeof options.classpath === 'string' ? options.classpath : undefined,
+            entry,
+            wasiP3: Boolean(options['wasi-p3']),
+        });
+        console.log(JSON.stringify(prepared, null, 2));
+        return 0;
+    });
+
+    runtimeOpts(runtime.command('run', 'cli.cmd.runtime.run'))
+        .option('--cwd <dir>', 'cli.opt.cwd')
+        .action((options: ParsedOptions) => {
+            const family = requireString(options, 'family');
+            const artifact = requireString(options, 'artifact');
+            const entry = requireString(options, 'entry');
+            const prepared = prepareRuntimeCommand({
+                family,
+                artifact: path.resolve(artifact),
+                classpath: typeof options.classpath === 'string' ? options.classpath : undefined,
+                entry,
+                wasiP3: Boolean(options['wasi-p3']),
+            });
+            const cwd = typeof options.cwd === 'string' ? path.resolve(options.cwd) : process.cwd();
+            const code = runPreparedCommand(prepared, cwd);
+            return code;
+        });
+
+    return cli;
+}
+
+function requireString(options: ParsedOptions, key: string): string {
+    const value = options[key];
+    if (typeof value !== 'string' || !value) {
+        throw new Error(`missing required --${key}`);
+    }
+    return value;
+}
+
+/** 解析 argv 并执行 Nyar CLI（@vmz/commander 编排；能力调用走 nyar-napi）。 */
+export async function runCli(argv: string[] = process.argv.slice(2)): Promise<number> {
+    const [cmd] = argv;
+    if (cmd === 'wasm' && resolveCollect().kind === 'wasm') {
+        return forwardWasm(argv.slice(1));
+    }
+    return buildCli().parse(argv);
+}
+
+function forwardWasm(rest: string[]): number {
+    const collect = resolveCollect();
+    if (collect.kind !== 'wasm') {
+        console.error('nyar: wasm forward requires wasm collect');
+        return 1;
+    }
+    if (!existsArtifact(collect.entry)) {
+        console.error(`nyar: missing wasm collect at ${collect.entry}`);
+        return 1;
+    }
+    const result = spawnSync('wasmtime', [collect.entry, ...rest], {stdio: 'inherit', shell: false});
+    return result.status ?? 1;
+}
+
+function existsArtifact(filePath: string): boolean {
+    try {
+        readFileSync(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/index.ts

@@ -1,38 +1,39 @@
-import { readFile } from 'node:fs/promises';
-
 import { type NyarCollect, resolveCollect } from './platform.ts';
 
 export { hostPlatformKey, type NyarCollect, resolveCollect } from './platform.ts';
+export { nativeBinaryName, platformShort, platformTriple } from './platform-triple.ts';
+export {
+    HOST_PROTOCOL,
+    getHostInfo,
+    listRuntimeFamilies,
+    loadNative,
+    prepareRuntimeCommand,
+    runPreparedCommand,
+    type HostInfo,
+    type PrepareRuntimeOptions,
+    type PreparedRuntimeCommand,
+} from './native.ts';
+export { runCli } from './cli/cli.ts';
 
 export type NyarHost = {
     /** Resolved platform collect metadata for diagnostics and tooling. */
     collect: NyarCollect;
-    /** Load bytecode bytes (0.0.0 placeholder — execution wiring lands with Node-API host exports). */
-    runBytecode(bytes: Uint8Array): Promise<void>;
+    /** Host protocol from nyar-napi. */
+    hostProtocol: string;
 };
 
 /**
- * Create a Nyar host for the current platform.
+ * Create a Nyar host handle for the current platform.
  *
  * Native collects are preferred when the matching optional dependency is installed;
- * otherwise the Wasm GC collect from `@nyar/nyar-unknown-wasm32` is used.
+ * otherwise the Wasm collect from `@nyar/nyar-unknown-wasm32` is used.
  */
 export async function createNyarHost(): Promise<NyarHost> {
     const collect = resolveCollect();
-    return {
-        collect,
-        async runBytecode(bytes: Uint8Array) {
-            if (bytes.length === 0) {
-                throw new Error('nyar host received empty bytecode payload');
-            }
-            // 0.0.0 ships collect layout only; bytecode execution is wired in the next host export drop.
-            await readFile(collect.entry);
-            throw new Error(
-                `nyar host collect resolved (${collect.kind} via ${collect.packageName}) but bytecode execution is not wired in 0.0.0`,
-            );
-        },
-    };
+    if (collect.kind === 'native') {
+        const { getHostInfo } = await import('./native.ts');
+        const info = getHostInfo();
+        return { collect, hostProtocol: info.hostProtocol };
+    }
+    return { collect, hostProtocol: 'nyar-host/0' };
 }
-
-/** @deprecated Use {@link createNyarHost}. */
-export const NYAR_CLI_PLACEHOLDER = 'nyar';

package/src/native.ts

@@ -0,0 +1,115 @@
+import {createRequire} from 'node:module';
+import {existsSync} from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {hostPlatformKey} from './platform.ts';
+import {nativeBinaryName, platformShort, platformTriple} from './platform-triple.ts';
+
+/** Node 宿主协议 id（与 nyar-napi `HOST_PROTOCOL` 对齐）。 */
+export const HOST_PROTOCOL = 'nyar-host/0';
+
+export type HostInfo = {
+    hostProtocol: string;
+    binding: string;
+};
+
+export type PrepareRuntimeOptions = {
+    family: string;
+    artifact: string;
+    classpath?: string;
+    entry: string;
+    wasiP3?: boolean;
+};
+
+export type PreparedRuntimeCommand = {
+    family: string;
+    command: string;
+    args: string[];
+};
+
+type NyarNativeAddon = {
+    getHostInfo(): HostInfo;
+    listRuntimeFamilies(): string[];
+    parseRuntimeFamily(value: string): string;
+    prepareRuntimeCommand(options: {
+        family: string;
+        artifact: string;
+        classpath?: string;
+        entry: string;
+        wasiP3?: boolean;
+    }): PreparedRuntimeCommand;
+    runPreparedCommand(prepared: PreparedRuntimeCommand, cwd?: string): number;
+};
+
+const pkgRoot = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolve native `.node` via the platform optionalDependency (`@nyar/nyar-<short>`).
+ */
+export function resolveNativePath(): string {
+    const triple = platformTriple();
+    const short = platformShort(triple);
+    const packageName = `@nyar/nyar-${short}`;
+    const binary = nativeBinaryName(triple);
+    const candidates: string[] = [];
+
+    try {
+        const pkgJson = require.resolve(`${packageName}/package.json`);
+        const pkgDir = path.dirname(pkgJson);
+        candidates.push(path.join(pkgDir, 'lib', binary));
+        candidates.push(path.join(pkgDir, binary));
+    } catch {
+        /* optional dep not installed */
+    }
+
+    candidates.push(path.join(pkgRoot, '..', '..', `nyar-${short}`, 'lib', binary));
+    candidates.push(path.join(pkgRoot, '..', '..', `nyar-${short}`, binary));
+    candidates.push(path.join(pkgRoot, 'node_modules', packageName, 'lib', binary));
+
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) return candidate;
+    }
+
+    throw new Error(
+        `nyar native addon not found for ${packageName}. Run: node scripts/build.mjs napi\n` +
+        `Looked in:\n${candidates.map((c) => `  - ${c}`).join('\n')}\n` +
+        `(host ${hostPlatformKey()})`,
+    );
+}
+
+let nativeAddon: NyarNativeAddon | undefined;
+
+/** 加载当前平台的 nyar-napi 绑定（正交能力面，不含 CLI）。 */
+export function loadNative(): NyarNativeAddon {
+    if (nativeAddon) return nativeAddon;
+    const triple = platformTriple();
+    const short = platformShort(triple);
+    const packageName = `@nyar/nyar-${short}`;
+    nativeAddon = require(resolveNativePath()) as NyarNativeAddon;
+    return nativeAddon;
+}
+
+export function getHostInfo(): HostInfo {
+    return loadNative().getHostInfo();
+}
+
+export function listRuntimeFamilies(): string[] {
+    return loadNative().listRuntimeFamilies();
+}
+
+export function prepareRuntimeCommand(options: PrepareRuntimeOptions): PreparedRuntimeCommand {
+    const native = loadNative();
+    return native.prepareRuntimeCommand({
+        family: options.family,
+        artifact: options.artifact,
+        classpath: options.classpath,
+        entry: options.entry,
+        wasiP3: options.wasiP3,
+    });
+}
+
+export function runPreparedCommand(prepared: PreparedRuntimeCommand, cwd?: string): number {
+    return loadNative().runPreparedCommand(prepared, cwd);
+}

package/src/platform-triple.ts

@@ -0,0 +1,25 @@
+import {arch, platform} from 'node:os';
+
+/** npm platform short id (`win32-x64`, …) from host OS. */
+export function platformShort(triple?: string): string {
+    const t = triple ?? platformTriple();
+    if (t.startsWith('win32-')) return 'win32-x64';
+    if (t.startsWith('linux-')) return 'linux-x64';
+    if (t === 'darwin-arm64') return 'darwin-arm64';
+    if (t === 'darwin-x64') return 'darwin-x64';
+    return t;
+}
+
+/** Host triple used for platform-named native binaries (`nyar.<triple>.node`). */
+export function platformTriple(): string {
+    const {platform: os, arch: cpu} = {platform: platform(), arch: arch()};
+    if (os === 'win32' && cpu === 'x64') return 'win32-x64-msvc';
+    if (os === 'linux' && cpu === 'x64') return 'linux-x64-gnu';
+    if (os === 'darwin' && cpu === 'arm64') return 'darwin-arm64';
+    if (os === 'darwin' && cpu === 'x64') return 'darwin-x64';
+    return `${os}-${cpu}`;
+}
+
+export function nativeBinaryName(triple?: string): string {
+    return `nyar.${triple ?? platformTriple()}.node`;
+}

package/src/platform.ts

@@ -1,6 +1,6 @@
-import { createRequire } from 'node:module';
-import { arch, platform } from 'node:os';
-import { fileURLToPath } from 'node:url';
+import {createRequire} from 'node:module';
+import {arch, platform} from 'node:os';
+import {fileURLToPath} from 'node:url';
 
 const HOST_KEY = `${platform()}-${arch()}`;
 
@@ -48,11 +48,8 @@ export function resolveCollect(): NyarCollect {
     if (nativePackage) {
         const req = requireOptional(nativePackage);
         if (req) {
-            const entry =
-                HOST_KEY === 'win32-x64'
-                    ? req.resolve('./nyar_napi.dll')
-                    : req.resolve(`./libnyar_napi.${HOST_KEY.startsWith('darwin') ? 'dylib' : 'so'}`);
-            return { kind: 'native', packageName: nativePackage, entry };
+            const entry = req.resolve('./index.mjs');
+            return {kind: 'native', packageName: nativePackage, entry};
         }
     }