@rcrsr/rill 0.6.0 → 0.6.1

package/README.md

@@ -0,0 +1,149 @@
+# @rcrsr/rill
+
+Embeddable runtime for the [rill](https://github.com/rcrsr/rill) workflow language. Zero dependencies. Browser and Node.js compatible.
+
+> **Experimental.** Breaking changes will occur until v1.0.
+
+## Install
+
+```bash
+npm install @rcrsr/rill
+```
+
+## Quick Start
+
+```typescript
+import { parse, execute, createRuntimeContext } from '@rcrsr/rill';
+
+const script = `
+  prompt("Analyze this code for issues")
+    -> .contains("ERROR") ? error($) ! "Analysis complete"
+`;
+
+const ctx = createRuntimeContext({
+  functions: {
+    prompt: {
+      params: [{ name: 'message', type: 'string' }],
+      fn: async (args) => await callYourLLM(args[0]),
+    },
+  },
+});
+
+const result = await execute(parse(script), ctx);
+console.log(result.value);
+```
+
+## API
+
+### Core Pipeline
+
+```
+Source Text → parse() → AST → execute() → Result
+```
+
+| Export | Purpose |
+|--------|---------|
+| `parse(source)` | Parse rill source into an AST |
+| `execute(ast, ctx)` | Execute an AST with a runtime context |
+| `createRuntimeContext(opts)` | Create a configured runtime context |
+| `callable(fn, isProperty?)` | Wrap a function as a rill-callable value |
+| `prefixFunctions(prefix, fns)` | Namespace host functions (e.g., `app::`) |
+
+### Runtime Options
+
+```typescript
+const ctx = createRuntimeContext({
+  // Host functions available to scripts
+  functions: {
+    prompt: {
+      params: [{ name: 'text', type: 'string' }],
+      fn: async (args, ctx, location) => { /* ... */ },
+    },
+  },
+
+  // Variables injected into script scope
+  variables: {
+    config: { greeting: 'hello' },
+  },
+
+  // Callbacks
+  callbacks: {
+    onLog: (value) => console.log(value),
+  },
+
+  // Observability hooks
+  observability: {
+    onStepStart: (e) => { /* ... */ },
+    onStepEnd: (e) => { /* ... */ },
+  },
+
+  // Execution limits
+  timeout: 30000,
+  signal: abortController.signal,
+});
+```
+
+### Stepper API
+
+Step through execution one statement at a time:
+
+```typescript
+import { parse, createRuntimeContext, createStepper } from '@rcrsr/rill';
+
+const stepper = createStepper(parse(script), createRuntimeContext());
+
+let step;
+while (!(step = await stepper.next()).done) {
+  console.log(step.value);
+}
+```
+
+### Additional Exports
+
+| Export | Purpose |
+|--------|---------|
+| `parseWithRecovery(source)` | Parse with error recovery (for editors) |
+| `tokenize(source)` | Tokenize source into a token stream |
+| `TOKEN_HIGHLIGHT_MAP` | Syntax highlighting category map |
+| `getLanguageReference()` | LLM-optimized language reference text |
+| `getDocumentationCoverage()` | Coverage stats for doc examples |
+| `getFunctions()` | List of built-in function metadata |
+| `VERSION` / `VERSION_INFO` | Runtime version string and metadata |
+
+### Error Handling
+
+```typescript
+import { parse, execute, createRuntimeContext, AbortError } from '@rcrsr/rill';
+
+try {
+  const result = await execute(parse(script), ctx);
+} catch (err) {
+  if (err instanceof AbortError) {
+    // Execution was cancelled via signal
+  }
+  // Runtime errors include source location and error code
+}
+```
+
+### Type Guards
+
+| Export | Purpose |
+|--------|---------|
+| `isDict(value)` | Check if value is a rill dict |
+| `isTuple(value)` | Check if value is a rill tuple |
+| `isCallable(value)` | Check if value is any callable |
+| `isScriptCallable(value)` | Check if value is a script-defined closure |
+| `isApplicationCallable(value)` | Check if value is a host-provided callable |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Host Integration](https://github.com/rcrsr/rill/blob/main/docs/integration-host.md) | Embedding guide |
+| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Complete TypeScript API |
+| [Language Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-language.md) | Language specification |
+| [Extensions](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Reusable host function packages |
+
+## License
+
+MIT

package/dist/generated/version-data.d.ts

@@ -10,7 +10,7 @@ export interface VersionInfo {
 /**
  * Version string from package.json
  */
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.6.1";
 /**
  * Parsed version components
  */

package/dist/generated/version-data.js

@@ -3,14 +3,14 @@
 /**
  * Version string from package.json
  */
-export const VERSION = '0.6.0';
+export const VERSION = '0.6.1';
 /**
  * Parsed version components
  */
 export const VERSION_INFO = {
     major: 0,
     minor: 6,
-    patch: 0,
+    patch: 1,
     prerelease: undefined,
 };
 //# sourceMappingURL=version-data.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc --build",
+    "build": "tsx scripts/generate-version.ts && tsc --build",
     "test": "vitest run",
     "test:examples": "tsx ../../scripts/test-examples.ts ../../docs/",
     "typecheck": "tsc --noEmit",