@govela/compiler 0.0.0-stage → 0.4.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abullo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @govela/compiler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Vela compiler for JavaScript toolchains: `npm i -D @govela/compiler` installs
+the `vela` command with a prebuilt binary for this platform, no Go
+toolchain needed. Install `@govela/runtime` of the same version for
+bundled applications.
+
+```sh
+npx vela --project src --out build --runtime-import=bare
+npx vela check --project src
+```
+
+## JavaScript API
+
+```js
+import { compile, startService } from '@govela/compiler';
+
+const result = await compile({ path: 'src/App.vela' });
+// result.ok, result.js, result.css, result.map, result.diagnostics, result.imports
+
+const service = await startService();   // one `vela serve --stdio` process
+const a = await service.compile({ path: 'src/App.vela', source, options: { sourcemap: true } });
+await service.close();
+```
+
+Requests, results and options are those of the compiler service protocol
+(`docs/TOOLING_PROTOCOL.md` in the compiler repository). `startService`
+rejects a binary that speaks another protocol or has another version.
+
+Supported platforms: linux x64/arm64, macOS x64/arm64, Windows x64. Set
+`VELA_BINARY` to the path of a `vela` binary to use another build.
+
+License: MIT.

package/bin/vela.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// The `vela` command of @govela/compiler: runs the binary of this platform
+// with the arguments, standard streams and exit code of the command.
+import { spawnSync } from 'node:child_process';
+import { binaryPath } from '../index.js';
+
+let binary;
+try {
+  binary = binaryPath();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit', windowsHide: true });
+if (result.error) {
+  console.error(`vela: cannot run ${binary}: ${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

package/index.d.ts

@@ -0,0 +1,91 @@
+// Types of the compiler service protocol (docs/TOOLING_PROTOCOL.md).
+
+export declare const version: string;
+export declare const protocol: 1;
+
+/** The file options of a request; each is the build flag of the same name. */
+export interface CompileOptions {
+  minify?: boolean;
+  css?: 'inject' | 'external';
+  sourcemap?: boolean;
+  target?: 'permissive' | 'browser' | 'worker' | 'node' | 'ssr';
+  unavailableCapabilities?: string[];
+  strict?: boolean;
+  hydrationVerify?: 'repair' | 'fail' | 'off';
+  mode?: 'development' | 'production';
+  runtimeImport?: 'relative' | 'bare';
+  checkDeps?: boolean;
+  /** 'vela' keeps `.vela` specifiers of component imports, for bundler plugins. */
+  componentImports?: 'js' | 'vela';
+}
+
+export interface CompileRequest {
+  /** The component, absolute or relative to the service's working directory. */
+  path: string;
+  /** The text to compile; without it the service reads path. */
+  source?: string;
+  options?: CompileOptions;
+}
+
+export interface Diagnostic {
+  severity: 'error' | 'warning' | 'hint';
+  code?: string;
+  file?: string;
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  message: string;
+  suggestion?: string;
+}
+
+export interface ModuleImport {
+  specifier: string;
+  kind: 'component' | 'module' | 'runtime' | 'package' | 'url';
+  resolved?: string;
+}
+
+export interface CompileResult {
+  ok: boolean;
+  js?: string;
+  css?: string;
+  /** A v3 source map with options.sourcemap. */
+  map?: object;
+  diagnostics: Diagnostic[];
+  imports: ModuleImport[];
+  error?: string;
+}
+
+export interface Handshake {
+  protocol: number;
+  compilerVersion: string;
+  runtimePackage: string;
+  runtimeContract: string;
+}
+
+export interface ServiceOptions {
+  /** Working directory of the service: paths and vela.config.json resolve against it. */
+  cwd?: string;
+  /** A configuration file instead of vela.config.json in cwd. */
+  config?: string;
+  /** Further flags of `vela serve`, e.g. ['--target', 'browser']. */
+  args?: string[];
+  /** A vela binary instead of the platform package's. */
+  binary?: string;
+}
+
+export interface Service {
+  handshake(): Handshake;
+  compile(request: CompileRequest): Promise<CompileResult>;
+  /** Ends the input; resolves when the service has answered every request and exited. */
+  close(): Promise<void>;
+}
+
+/** The vela binary: VELA_BINARY, else the binary of the platform package. */
+export declare function binaryPath(): string;
+
+/** Starts `vela serve --stdio`; rejects a binary of another protocol or version. */
+export declare function startService(options?: ServiceOptions): Promise<Service>;
+
+/** Compiles one component with a short-lived service. */
+export declare function compile(request: CompileRequest, options?: ServiceOptions): Promise<CompileResult>;

package/index.js

@@ -0,0 +1,144 @@
+// The JavaScript API of @govela/compiler: the binary of this platform, and
+// the compiler service protocol (docs/TOOLING_PROTOCOL.md) over
+// `vela serve --stdio`.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+
+const require = createRequire(import.meta.url);
+const manifest = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+
+/** The version of this package; the binary must have the same version. */
+export const version = manifest.version;
+
+/** The service protocol version this package speaks. */
+export const protocol = 1;
+
+const platforms = {
+  'linux-x64': 'bin/vela',
+  'linux-arm64': 'bin/vela',
+  'darwin-x64': 'bin/vela',
+  'darwin-arm64': 'bin/vela',
+  'win32-x64': 'bin/vela.exe',
+};
+
+function velaError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * The path of the vela binary: VELA_BINARY when it is set, else the binary
+ * of the installed platform package.
+ */
+export function binaryPath() {
+  if (process.env.VELA_BINARY) {
+    return process.env.VELA_BINARY;
+  }
+  const platform = `${process.platform}-${process.arch}`;
+  const file = platforms[platform];
+  const name = `${manifest.name}-${platform}`;
+  if (!file) {
+    throw velaError('VELA_PLATFORM', `vela: no prebuilt binary for ${platform}; supported: ${Object.keys(platforms).join(', ')}. Install the compiler with \`go install github.com/elauven/vela@v${version}\` and set VELA_BINARY to it.`);
+  }
+  try {
+    return require.resolve(`${name}/${file}`);
+  } catch {
+    throw velaError('VELA_BINARY', `vela: the package ${name} is not installed. It is an optional dependency of ${manifest.name}; reinstall without --no-optional / --omit=optional, or set VELA_BINARY to a vela binary.`);
+  }
+}
+
+/**
+ * Starts `vela serve --stdio`. Resolves when the compiler has answered the
+ * handshake with this package's protocol and version.
+ */
+export function startService({ cwd, config, args = [], binary } = {}) {
+  const command = binary ?? binaryPath();
+  const argv = ['serve', '--stdio', '--protocol', String(protocol), ...(config ? ['--config', config] : []), ...args];
+  const child = spawn(command, argv, { cwd, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+  const lines = createInterface({ input: child.stdout });
+  const pending = new Map();
+  let stderr = '';
+  let nextId = 1;
+  let closed = false;
+  child.stderr.on('data', (chunk) => { stderr += chunk; });
+
+  return new Promise((resolve, reject) => {
+    let handshake = null;
+    const fail = (error) => {
+      for (const { reject: rejectRequest } of pending.values()) rejectRequest(error);
+      pending.clear();
+      if (!handshake) reject(error);
+    };
+    child.on('error', (error) => fail(velaError('VELA_BINARY', `vela: cannot run ${command}: ${error.message}`)));
+    // 'close' comes after the last output line, unlike 'exit'.
+    child.on('close', (code, signal) => {
+      closed = true;
+      if (pending.size > 0 || !handshake) {
+        fail(velaError('VELA_EXIT', `vela serve exited (${signal ?? code})${stderr ? `: ${stderr.trim()}` : ''}`));
+      }
+    });
+    lines.on('line', (line) => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        fail(velaError('VELA_PROTOCOL', `vela serve wrote a line that is not JSON: ${line}`));
+        return;
+      }
+      if (!handshake) {
+        handshake = message;
+        if (message.error || message.protocol !== protocol) {
+          child.kill();
+          reject(velaError('VELA_PROTOCOL', `vela: ${message.error ?? `the compiler speaks protocol ${message.protocol}, ${manifest.name} ${version} speaks ${protocol}`}`));
+          return;
+        }
+        if (message.compilerVersion !== version) {
+          child.kill();
+          reject(velaError('VELA_VERSION', `vela: the binary ${command} is version ${message.compilerVersion}, ${manifest.name} is ${version}; install matching versions${process.env.VELA_BINARY ? ' or unset VELA_BINARY' : ''}`));
+          return;
+        }
+        resolve(service);
+        return;
+      }
+      const request = pending.get(JSON.stringify(message.id));
+      if (request) {
+        pending.delete(JSON.stringify(message.id));
+        request.resolve(message);
+      }
+    });
+
+    const service = {
+      handshake: () => handshake,
+      compile(request) {
+        if (closed) {
+          return Promise.reject(velaError('VELA_EXIT', 'vela serve is closed'));
+        }
+        const id = nextId++;
+        return new Promise((resolveRequest, rejectRequest) => {
+          pending.set(JSON.stringify(id), { resolve: resolveRequest, reject: rejectRequest });
+          child.stdin.write(JSON.stringify({ ...request, id }) + '\n');
+        });
+      },
+      close() {
+        if (closed) return Promise.resolve();
+        return new Promise((resolveClose) => {
+          child.once('close', () => resolveClose());
+          child.stdin.end();
+        });
+      },
+    };
+  });
+}
+
+/** Compiles one component with a short-lived service. */
+export async function compile(request, serviceOptions) {
+  const service = await startService(serviceOptions);
+  try {
+    return await service.compile(request);
+  } finally {
+    await service.close();
+  }
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@govela/compiler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.5",
+  "description": "The Vela compiler: single-file components to ES modules, and Go server renderers. Manifest generated by the compiler repository; do not edit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elauven/vela.git",
+    "directory": "packages/compiler"
+  },
+  "type": "module",
+  "bin": {
+    "vela": "bin/vela.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "index.d.ts",
+  "files": [
+    "bin/vela.js",
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@govela/compiler-darwin-arm64": "0.4.5",
+    "@govela/compiler-darwin-x64": "0.4.5",
+    "@govela/compiler-linux-arm64": "0.4.5",
+    "@govela/compiler-linux-x64": "0.4.5",
+    "@govela/compiler-win32-x64": "0.4.5"
+  }
+}