mustardscript 0.1.0

package/mustard.d.ts

@@ -0,0 +1,220 @@
+export type StructuredValue =
+  | undefined
+  | null
+  | boolean
+  | number
+  | string
+  | StructuredValue[]
+  | { [key: string]: StructuredValue };
+
+export interface CapabilityError extends Error {
+  code?: string;
+  details?: StructuredValue;
+}
+
+export type Capability = (
+  ...args: StructuredValue[]
+) => StructuredValue | Promise<StructuredValue>;
+
+export interface ConsoleCallbacks {
+  log?: Capability;
+  warn?: Capability;
+  error?: Capability;
+}
+
+export interface CompileOptions {
+  inputs?: string[];
+}
+
+export type SnapshotKey = string | Buffer | Uint8Array;
+
+export interface ExecutionOptions {
+  inputs?: Record<string, StructuredValue>;
+  capabilities?: Record<string, Capability>;
+  console?: ConsoleCallbacks;
+  limits?: RuntimeLimits;
+  signal?: AbortSignal;
+  snapshotKey?: SnapshotKey;
+}
+
+export interface ResumeOptions {
+  signal?: AbortSignal;
+}
+
+export interface ProgressLoadOptionsBase {
+  limits: RuntimeLimits;
+  snapshotKey: SnapshotKey;
+}
+
+export type ProgressLoadOptions =
+  | (ProgressLoadOptionsBase & {
+      capabilities: Record<string, Capability>;
+      console?: ConsoleCallbacks;
+    })
+  | (ProgressLoadOptionsBase & {
+      capabilities?: Record<string, Capability>;
+      console: ConsoleCallbacks;
+    });
+
+export interface RuntimeLimits {
+  instructionBudget?: number;
+  heapLimitBytes?: number;
+  allocationBudget?: number;
+  callDepthLimit?: number;
+  maxOutstandingHostCalls?: number;
+}
+
+export type MustardJobId = string;
+
+export type MustardJobState =
+  | 'queued'
+  | 'running'
+  | 'waiting'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export interface MustardJobError {
+  name: string;
+  message: string;
+  code?: string;
+  details?: StructuredValue;
+}
+
+export interface MustardJobRecord<
+  TInput extends Record<string, StructuredValue> = Record<string, StructuredValue>,
+  TResult extends StructuredValue = StructuredValue,
+> {
+  jobId: MustardJobId;
+  state: MustardJobState;
+  input: TInput;
+  capability?: string;
+  args?: StructuredValue[];
+  result?: TResult;
+  error?: MustardJobError;
+  attempts: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PersistedProgress extends SerializedProgress {}
+
+export interface MustardExecutorStore<
+  TInput extends Record<string, StructuredValue> = Record<string, StructuredValue>,
+  TResult extends StructuredValue = StructuredValue,
+> {
+  enqueue(record: MustardJobRecord<TInput, TResult>): Promise<{
+    jobId: MustardJobId;
+    inserted: boolean;
+  }>;
+  get(jobId: MustardJobId): Promise<MustardJobRecord<TInput, TResult> | null>;
+  claimRunnable(limit: number, workerId: string, now: number): Promise<MustardJobId[]>;
+  releaseClaim(jobId: MustardJobId, workerId: string): Promise<void>;
+  update(
+    jobId: MustardJobId,
+    patch: Partial<MustardJobRecord<TInput, TResult>>,
+  ): Promise<void>;
+  saveProgress(jobId: MustardJobId, progress: PersistedProgress): Promise<void>;
+  loadProgress(jobId: MustardJobId): Promise<PersistedProgress | null>;
+  deleteProgress(jobId: MustardJobId): Promise<void>;
+  requestCancel(jobId: MustardJobId): Promise<'cancelled' | 'requested' | 'ignored'>;
+  consumeCancel(jobId: MustardJobId): Promise<boolean>;
+}
+
+export interface MustardExecutorOptions<
+  TInput extends Record<string, StructuredValue> = Record<string, StructuredValue>,
+  TResult extends StructuredValue = StructuredValue,
+> {
+  program: Mustard;
+  capabilities: Record<string, Capability>;
+  snapshotKey?: SnapshotKey;
+  store: MustardExecutorStore<TInput, TResult>;
+  limits?: RuntimeLimits;
+}
+
+export interface MustardExecutorRunWorkerOptions {
+  maxConcurrentJobs?: number;
+  signal?: AbortSignal;
+  drain?: boolean;
+}
+
+export type MustardErrorKind =
+  | 'Parse'
+  | 'Validation'
+  | 'Runtime'
+  | 'Limit'
+  | 'Serialization';
+
+export class MustardError extends Error {
+  constructor(kind: MustardErrorKind, message: string, cause?: unknown);
+
+  readonly kind: MustardErrorKind;
+  readonly cause?: unknown;
+}
+
+export interface SerializedProgress {
+  capability: string;
+  args: StructuredValue[];
+  snapshot: Buffer;
+  snapshot_id: string;
+  snapshot_key_digest: string;
+  token: string;
+}
+
+export class Progress {
+  readonly capability: string;
+  readonly args: StructuredValue[];
+  readonly snapshot: Buffer;
+
+  dump(): SerializedProgress;
+  resume(value: StructuredValue, options?: ResumeOptions): StructuredValue | Progress;
+  resumeError(error: unknown, options?: ResumeOptions): StructuredValue | Progress;
+  cancel(): StructuredValue | Progress;
+
+  static load(state: SerializedProgress, options: ProgressLoadOptions): Progress;
+}
+
+export class Mustard {
+  constructor(code: string, options?: CompileOptions);
+
+  run(options?: ExecutionOptions): Promise<StructuredValue>;
+  start(options?: ExecutionOptions): StructuredValue | Progress;
+  dump(): Buffer;
+
+  static validateProgram(code: string): void;
+  static load(buffer: Buffer): Mustard;
+}
+
+export class InMemoryMustardExecutorStore<
+  TInput extends Record<string, StructuredValue> = Record<string, StructuredValue>,
+  TResult extends StructuredValue = StructuredValue,
+> implements MustardExecutorStore<TInput, TResult> {
+  enqueue(record: MustardJobRecord<TInput, TResult>): Promise<{
+    jobId: MustardJobId;
+    inserted: boolean;
+  }>;
+  get(jobId: MustardJobId): Promise<MustardJobRecord<TInput, TResult> | null>;
+  claimRunnable(limit: number, workerId: string, now: number): Promise<MustardJobId[]>;
+  releaseClaim(jobId: MustardJobId, workerId: string): Promise<void>;
+  update(
+    jobId: MustardJobId,
+    patch: Partial<MustardJobRecord<TInput, TResult>>,
+  ): Promise<void>;
+  saveProgress(jobId: MustardJobId, progress: PersistedProgress): Promise<void>;
+  loadProgress(jobId: MustardJobId): Promise<PersistedProgress | null>;
+  deleteProgress(jobId: MustardJobId): Promise<void>;
+  requestCancel(jobId: MustardJobId): Promise<'cancelled' | 'requested' | 'ignored'>;
+  consumeCancel(jobId: MustardJobId): Promise<boolean>;
+}
+
+export class MustardExecutor<
+  TInput extends Record<string, StructuredValue> = Record<string, StructuredValue>,
+  TResult extends StructuredValue = StructuredValue,
+> {
+  constructor(options: MustardExecutorOptions<TInput, TResult>);
+
+  enqueue(input: TInput, options?: { jobId?: MustardJobId }): Promise<MustardJobId>;
+  get(jobId: MustardJobId): Promise<MustardJobRecord<TInput, TResult> | null>;
+  cancel(jobId: MustardJobId): Promise<void>;
+  runWorker(options?: MustardExecutorRunWorkerOptions): Promise<void>;
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "mustardscript",
+  "version": "0.1.0",
+  "description": "Sandboxed, subset JavaScript runtime for Node services.",
+  "main": "dist/index.js",
+  "types": "mustard.d.ts",
+  "files": [
+    "Cargo.lock",
+    "Cargo.toml",
+    "LICENSE",
+    "SECURITY.md",
+    "dist",
+    "index.d.ts",
+    "mustard.d.ts",
+    "crates/mustard/Cargo.toml",
+    "crates/mustard/src/**",
+    "crates/mustard-bridge/Cargo.toml",
+    "crates/mustard-bridge/src/**",
+    "crates/mustard-node/Cargo.toml",
+    "crates/mustard-node/build.rs",
+    "crates/mustard-node/src/**",
+    "crates/mustard-sidecar/Cargo.toml",
+    "crates/mustard-sidecar/src/**"
+  ],
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "tests"
+  },
+  "napi": {
+    "binaryName": "index",
+    "packageName": "mustardscript",
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu"
+    ]
+  },
+  "optionalDependencies": {
+    "mustardscript-darwin-arm64": "0.1.0",
+    "mustardscript-darwin-x64": "0.1.0",
+    "mustardscript-linux-x64-gnu": "0.1.0",
+    "mustardscript-win32-x64-msvc": "0.1.0"
+  },
+  "scripts": {
+    "install": "node -e \"const fs=require('node:fs'); const cp=require('node:child_process'); if (!fs.existsSync('dist/install.js')) { cp.execFileSync(process.execPath, ['scripts/build-ts-dist.ts'], { stdio: 'inherit' }); } cp.execFileSync(process.execPath, ['dist/install.js'], { stdio: 'inherit' });\"",
+    "prepack": "node scripts/build-ts-dist.ts",
+    "build": "node scripts/build-ts-dist.ts && napi build --platform --manifest-path crates/mustard-node/Cargo.toml --js-package-name mustardscript --output-dir . --no-js",
+    "ralph-loop": "node scripts/ralph-loop.ts",
+    "test": "npm run build && node --test tests/node/**/*.test.js && npm run test:types && npm run test:package-smoke",
+    "test:conformance": "npm run test:differential && npm run test:test262",
+    "test:differential": "node --test tests/node/differential.test.js tests/node/ast-conformance.test.js tests/node/property-differential.test.js tests/node/coverage-audit.test.js",
+    "test:node": "node --test tests/node/**/*.test.js",
+    "test:use-cases": "node scripts/audit-use-cases.ts",
+    "test:package-smoke": "node --test tests/package-smoke.test.js",
+    "test:test262": "node --test tests/test262/**/*.test.js",
+    "test:types": "tsc --noEmit -p tsconfig.typecheck.json",
+    "test:rust": "cargo test --workspace",
+    "test:hardening": "scripts/run-hardening.sh",
+    "test:mutation-guards": "npm run build && node --test tests/hardening/**/*.test.js",
+    "seed:fuzz-corpus": "node scripts/seed-fuzz-corpus.ts",
+    "bench:smoke": "npm run build && node --expose-gc benchmarks/smoke.ts",
+    "prebuilt:dirs": "napi create-npm-dirs",
+    "prebuilt:artifacts": "napi artifacts --output-dir artifacts",
+    "verify:prebuilt": "node scripts/verify-prebuilt.ts",
+    "verify:release": "node scripts/release-verify.ts",
+    "lint": "cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keppoai/mustardscript.git"
+  },
+  "keywords": [
+    "javascript",
+    "runtime",
+    "sandbox",
+    "napi",
+    "vm"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "devDependencies": {
+    "@napi-rs/cli": "^3.3.0",
+    "@types/node": "^25.6.0",
+    "fast-check": "^4.6.0",
+    "typescript": "^6.0.2"
+  },
+  "bugs": {
+    "url": "https://github.com/keppoai/mustardscript/issues"
+  },
+  "homepage": "https://github.com/keppoai/mustardscript#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}