velaris-lang 4.3.0

package/README.md

@@ -0,0 +1,34 @@
+# velaris-lang
+
+Run code you did not write.
+
+```
+npx velaris-lang script.vel --allow io
+```
+
+That program cannot read a file, reach the network or call Python -
+whatever its source says about itself - and a refusal cannot be caught
+and carried past.
+
+```javascript
+import { audit, run } from "velaris-lang";
+
+const report = await audit(source);
+console.log(report.effects);        // ['fs', 'net']
+console.log(report.proven_share);   // 66.7
+
+const result = await run(source, { allow: ["io"] });
+console.log(result.ok, result.output, result.refusedEffect);
+```
+
+Velaris is a language where a function's signature declares its types,
+the effects it may perform, whether it can fail, and promises a theorem
+prover checks before the program runs. This package is a thin wrapper:
+the compiler is a Python package, so `pip install velaris-lang` once.
+
+Not a security boundary - allowing `ffi` grants everything Python can
+do. It is a real guard for running a script a model wrote.
+
+[Documentation](https://gowrishankar-infra.github.io/velaris-lang/) ·
+[Playground](https://gowrishankar-infra.github.io/velaris-lang/playground.html) ·
+[Source](https://github.com/gowrishankar-infra/velaris-lang)

package/bin/velaris.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// npx velaris hello.vel
+//
+// Velaris's compiler is one Python file. This hands your arguments to
+// it, and if it is not installed, says exactly how to fix that rather
+// than failing with a confusing spawn error.
+
+import { spawn, spawnSync } from "node:child_process";
+
+function pythons() {
+  return process.platform === "win32"
+    ? ["py", "python", "python3"]
+    : ["python3", "python"];
+}
+
+function findVelaris() {
+  for (const exe of pythons()) {
+    const probe = spawnSync(exe, ["-c", "import velaris"], {
+      stdio: "ignore",
+    });
+    if (probe.status === 0) return exe;
+  }
+  return null;
+}
+
+const exe = findVelaris();
+if (!exe) {
+  console.error(
+    "Velaris needs its compiler, which is a Python package:\n" +
+      "\n    pip install velaris-lang\n" +
+      "\nOr try it with nothing installed:\n" +
+      "    https://gowrishankar-infra.github.io/velaris-lang/playground.html"
+  );
+  process.exit(127);
+}
+
+const child = spawn(exe, ["-m", "velaris", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/index.d.ts

@@ -0,0 +1,57 @@
+export type Effect = "io" | "fs" | "net" | "clock" | "rand" | "ffi";
+
+export interface Problem {
+  code: string;
+  message: string;
+  line: number;
+  file: string | null;
+  fixes: string[];
+}
+
+export interface CheckResult {
+  ok: boolean;
+  problems: Problem[];
+  proven: string[];
+  runtime_checked: string[];
+}
+
+export interface AuditFunction {
+  name: string;
+  effects: Effect[];
+  can_fail: boolean;
+  requires: string[];
+  ensures: string[];
+  status: string;
+}
+
+export interface AuditResult {
+  schema: "velaris.audit/1";
+  velaris_version: string;
+  ok: boolean;
+  problems: Problem[];
+  effects: Effect[];
+  functions: AuditFunction[];
+  proven_share: number | null;
+  safe_command: string;
+  warnings: string[];
+}
+
+export interface RunResult {
+  ok: boolean;
+  output: string;
+  logs: string;
+  problems: Problem[];
+  refusedEffect: Effect | null;
+  exitCode: number;
+}
+
+export interface RunOptions {
+  allow?: Effect[];
+  stdin?: string;
+  args?: string[];
+}
+
+export function check(source: string): Promise<CheckResult>;
+export function audit(source: string): Promise<AuditResult>;
+export function run(source: string, options?: RunOptions): Promise<RunResult>;
+export function card(): Promise<string>;

package/index.js

@@ -0,0 +1,120 @@
+// Velaris from Node: check what a program does, audit what it may
+// touch, and run it under an effect budget.
+//
+//   import { check, audit, run } from "velaris-lang";
+//
+//   const report = await audit(source);
+//   console.log(report.effects);              // ['fs', 'net']
+//
+//   const result = await run(source, { allow: ["io"] });
+//   console.log(result.ok, result.output, result.refusedEffect);
+//
+// Every call goes to the same compiler the command line uses, so the
+// guarantees are the same: an effect outside the budget is refused
+// while the program runs, whatever its source claims, and a refusal
+// cannot be caught by the program.
+
+import { spawn, spawnSync } from "node:child_process";
+
+let cachedPython = null;
+
+function findPython() {
+  if (cachedPython) return cachedPython;
+  const candidates =
+    process.platform === "win32"
+      ? ["py", "python", "python3"]
+      : ["python3", "python"];
+  for (const exe of candidates) {
+    const probe = spawnSync(exe, ["-c", "import velaris"], {
+      stdio: "ignore",
+    });
+    if (probe.status === 0) return (cachedPython = exe);
+  }
+  throw new Error(
+    "velaris is not installed: pip install velaris-lang"
+  );
+}
+
+function callPython(script, payload) {
+  const exe = findPython();
+  return new Promise((resolve, reject) => {
+    const child = spawn(exe, ["-c", script], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", reject);
+    child.on("close", () => {
+      try {
+        resolve(JSON.parse(out));
+      } catch {
+        reject(new Error(err.trim() || "velaris gave no answer"));
+      }
+    });
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+const BRIDGE = `
+import json, sys
+import velaris
+ask = json.load(sys.stdin)
+what = ask["what"]
+source = ask["source"]
+if what == "check":
+    print(json.dumps(velaris.check(source).as_dict()))
+elif what == "audit":
+    print(json.dumps(velaris.audit(source).as_dict()))
+elif what == "card":
+    print(json.dumps({"card": velaris.card()}))
+else:
+    out = velaris.run(source, allow=set(ask.get("allow") or ["io"]),
+                      stdin=ask.get("stdin", ""),
+                      args=ask.get("args") or [])
+    print(json.dumps(out.as_dict()))
+`;
+
+/** Compile without running. Problems, and what was proven. */
+export async function check(source) {
+  return callPython(BRIDGE, { what: "check", source });
+}
+
+/** What a program can touch, promise and fail at - before running. */
+export async function audit(source) {
+  return callPython(BRIDGE, { what: "audit", source });
+}
+
+/** The language, small enough to paste into a model. */
+export async function card() {
+  const answer = await callPython(BRIDGE, { what: "card", source: "x" });
+  return answer.card;
+}
+
+/**
+ * Run under an effect budget.
+ *
+ * allow: ["io"] means it cannot read files, reach the network, call
+ * Python, ask the clock or use randomness - whatever the source says.
+ * Not a security boundary: allowing "ffi" grants everything Python can.
+ */
+export async function run(source, options = {}) {
+  const answer = await callPython(BRIDGE, {
+    what: "run",
+    source,
+    allow: options.allow ?? ["io"],
+    stdin: options.stdin ?? "",
+    args: options.args ?? [],
+  });
+  return {
+    ok: answer.ok,
+    output: answer.output,
+    logs: answer.logs,
+    problems: answer.problems,
+    refusedEffect: answer.refused_effect,
+    exitCode: answer.exit_code,
+  };
+}
+
+export default { check, audit, run, card };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "velaris-lang",
+  "version": "4.3.0",
+  "description": "Run code you did not write. A language where a signature declares its effects and promises, and the runtime refuses anything you did not allow.",
+  "keywords": [
+    "velaris",
+    "sandbox",
+    "effects",
+    "verification",
+    "ai-generated-code",
+    "agent",
+    "mcp",
+    "prover"
+  ],
+  "homepage": "https://gowrishankar-infra.github.io/velaris-lang/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gowrishankar-infra/velaris-lang.git"
+  },
+  "bugs": "https://github.com/gowrishankar-infra/velaris-lang/issues",
+  "license": "MIT",
+  "author": "Palakurthi Gowri Shankar <gowrishankar@gowrishankar.dev>",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "velaris": "bin/velaris.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}