@rcrsr/rill 0.16.0 → 0.17.0

package/README.md

@@ -13,24 +13,34 @@ npm install @rcrsr/rill
 ## Quick Start
 
 ```typescript
-import { parse, execute, createRuntimeContext } from '@rcrsr/rill';
+import { parse, execute, createRuntimeContext, toCallable } from '@rcrsr/rill';
+import type { ExtensionFactoryResult } from '@rcrsr/rill';
+
+function createMyExtension(): ExtensionFactoryResult {
+  return {
+    value: {
+      prompt: toCallable({
+        params: [{ name: 'message', type: { kind: 'string' } }],
+        fn: async (args) => await callYourLLM(args.message),
+        annotations: { description: 'Call your LLM' },
+        returnType: { kind: 'string' },
+      }),
+    },
+  };
+}
+
+const ext = createMyExtension();
+const ctx = createRuntimeContext({
+  variables: { app: ext.value },
+});
 
 const script = `
-  prompt("Analyze this code for issues")
+  app.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);
+console.log(result.result);
 ```
 
 ## API
@@ -47,25 +57,31 @@ Source Text → parse() → AST → execute() → Result
 | `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::`) |
+| `toCallable(def)` | Convert a `RillFunction` to an `ApplicationCallable` |
+| `createTestContext(extensions)` | Wire extensions for testing without config infrastructure |
 
 ### Runtime Options
 
 ```typescript
+const ext = createMyExtension();
+
 const ctx = createRuntimeContext({
-  // Host functions available to scripts
+  // Extension values injected as variables (recommended)
+  variables: {
+    app: ext.value,
+    config: { greeting: 'hello' },
+  },
+
+  // Legacy: direct function registration (still supported)
   functions: {
     prompt: {
-      params: [{ name: 'text', type: 'string' }],
+      params: [{ name: 'text', type: { kind: 'string' } }],
       fn: async (args, ctx, location) => { /* ... */ },
+      annotations: {},
+      returnType: { kind: 'string' },
     },
   },
 
-  // Variables injected into script scope
-  variables: {
-    config: { greeting: 'hello' },
-  },
-
   // Callbacks
   callbacks: {
     onLog: (value) => console.log(value),
@@ -159,7 +175,7 @@ import { createCryptoExtension } from '@rcrsr/rill/ext/crypto';
 | `@rcrsr/rill/ext/kv` | `createKvExtension(config)` | Key-value store with JSON persistence and schema validation |
 | `@rcrsr/rill/ext/crypto` | `createCryptoExtension(config)` | Cryptographic functions (hash, hmac, uuid, random) |
 
-Each factory returns an `ExtensionResult` with host function definitions ready to integrate into your runtime context.
+Each factory returns an `ExtensionFactoryResult` with a `value` dict of host functions and optional lifecycle hooks (`dispose`, `suspend`, `restore`) ready to integrate into your runtime context.
 
 > **Note:** These extensions require Node.js APIs and are not compatible with browser environments.
 

package/dist/ext/crypto/index.d.ts

@@ -4,7 +4,7 @@
  * Provides cryptographic functions via thin wrapper around node:crypto.
  * Functions: hash, hmac, uuid, random
  */
-import type { ExtensionResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
+import type { ExtensionFactoryResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
 export declare const configSchema: ExtensionConfigSchema;
 /** Crypto extension configuration */
 export interface CryptoConfig {
@@ -19,7 +19,7 @@ export interface CryptoConfig {
  * Returns 4 functions: hash, hmac, uuid, random.
  *
  * @param config - Crypto configuration
- * @returns ExtensionResult with 4 crypto functions
+ * @returns ExtensionFactoryResult with 4 crypto functions
  *
  * @example
  * ```typescript
@@ -29,5 +29,5 @@ export interface CryptoConfig {
  * });
  * ```
  */
-export declare function createCryptoExtension(config?: CryptoConfig): ExtensionResult;
+export declare function createCryptoExtension(config?: CryptoConfig): ExtensionFactoryResult;
 export declare const extensionManifest: ExtensionManifest;

package/dist/ext/crypto/index.js

@@ -6,6 +6,7 @@
  */
 import crypto from 'node:crypto';
 import { RuntimeError } from '../../error-classes.js';
+import { toCallable } from '../../runtime/core/callable.js';
 import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
 // ============================================================
 // TYPES
@@ -23,7 +24,7 @@ export const configSchema = {
  * Returns 4 functions: hash, hmac, uuid, random.
  *
  * @param config - Crypto configuration
- * @returns ExtensionResult with 4 crypto functions
+ * @returns ExtensionFactoryResult with 4 crypto functions
  *
  * @example
  * ```typescript
@@ -100,64 +101,66 @@ export function createCryptoExtension(config = {}) {
     // EXTENSION RESULT
     // ============================================================
     return {
-        hash: {
-            params: [
-                {
-                    name: 'input',
-                    type: { type: 'string' },
-                    defaultValue: undefined,
-                    annotations: { description: 'Content to hash' },
+        value: {
+            hash: toCallable({
+                params: [
+                    {
+                        name: 'input',
+                        type: { kind: 'string' },
+                        defaultValue: undefined,
+                        annotations: { description: 'Content to hash' },
+                    },
+                    {
+                        name: 'algorithm',
+                        type: { kind: 'string' },
+                        defaultValue: defaultAlgorithm,
+                        annotations: { description: 'Hash algorithm' },
+                    },
+                ],
+                fn: hash,
+                annotations: { description: 'Hash content, returns hex output' },
+                returnType: rillTypeToTypeValue({ kind: 'string' }),
+            }),
+            hmac: toCallable({
+                params: [
+                    {
+                        name: 'input',
+                        type: { kind: 'string' },
+                        defaultValue: undefined,
+                        annotations: { description: 'Content to authenticate' },
+                    },
+                    {
+                        name: 'algorithm',
+                        type: { kind: 'string' },
+                        defaultValue: defaultAlgorithm,
+                        annotations: { description: 'Hash algorithm' },
+                    },
+                ],
+                fn: hmac,
+                annotations: {
+                    description: 'Generate HMAC signature, returns hex output',
                 },
-                {
-                    name: 'algorithm',
-                    type: { type: 'string' },
-                    defaultValue: defaultAlgorithm,
-                    annotations: { description: 'Hash algorithm' },
-                },
-            ],
-            fn: hash,
-            annotations: { description: 'Hash content, returns hex output' },
-            returnType: rillTypeToTypeValue({ type: 'string' }),
-        },
-        hmac: {
-            params: [
-                {
-                    name: 'input',
-                    type: { type: 'string' },
-                    defaultValue: undefined,
-                    annotations: { description: 'Content to authenticate' },
-                },
-                {
-                    name: 'algorithm',
-                    type: { type: 'string' },
-                    defaultValue: defaultAlgorithm,
-                    annotations: { description: 'Hash algorithm' },
-                },
-            ],
-            fn: hmac,
-            annotations: {
-                description: 'Generate HMAC signature, returns hex output',
-            },
-            returnType: rillTypeToTypeValue({ type: 'string' }),
-        },
-        uuid: {
-            params: [],
-            fn: uuid,
-            annotations: { description: 'Generate random UUID v4' },
-            returnType: rillTypeToTypeValue({ type: 'string' }),
-        },
-        random: {
-            params: [
-                {
-                    name: 'bytes',
-                    type: { type: 'number' },
-                    defaultValue: undefined,
-                    annotations: { description: 'Number of bytes' },
-                },
-            ],
-            fn: random,
-            annotations: { description: 'Generate random bytes as hex string' },
-            returnType: rillTypeToTypeValue({ type: 'string' }),
+                returnType: rillTypeToTypeValue({ kind: 'string' }),
+            }),
+            uuid: toCallable({
+                params: [],
+                fn: uuid,
+                annotations: { description: 'Generate random UUID v4' },
+                returnType: rillTypeToTypeValue({ kind: 'string' }),
+            }),
+            random: toCallable({
+                params: [
+                    {
+                        name: 'bytes',
+                        type: { kind: 'number' },
+                        defaultValue: undefined,
+                        annotations: { description: 'Number of bytes' },
+                    },
+                ],
+                fn: random,
+                annotations: { description: 'Generate random bytes as hex string' },
+                returnType: rillTypeToTypeValue({ kind: 'string' }),
+            }),
         },
     };
 }

package/dist/ext/exec/index.d.ts

@@ -4,7 +4,7 @@
  * Provides sandboxed command execution via allowlist/blocklist security controls.
  * Each declared command becomes a function with argument validation and process isolation.
  */
-import type { ExtensionResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
+import type { ExtensionFactoryResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
 import { type CommandConfig } from './runner.js';
 export declare const configSchema: ExtensionConfigSchema;
 /** exec extension configuration */
@@ -27,7 +27,7 @@ export type { CommandConfig };
  * Returns dispose() function to abort in-flight processes.
  *
  * @param config - Command definitions and defaults
- * @returns ExtensionResult with command functions and dispose
+ * @returns ExtensionFactoryResult with command functions and dispose
  *
  * @example
  * ```typescript
@@ -42,5 +42,5 @@ export type { CommandConfig };
  * });
  * ```
  */
-export declare function createExecExtension(config: ExecConfig): ExtensionResult;
+export declare function createExecExtension(config: ExecConfig): ExtensionFactoryResult;
 export declare const extensionManifest: ExtensionManifest;

package/dist/ext/exec/index.js

@@ -4,6 +4,7 @@
  * Provides sandboxed command execution via allowlist/blocklist security controls.
  * Each declared command becomes a function with argument validation and process isolation.
  */
+import { toCallable } from '../../runtime/core/callable.js';
 import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
 import { runCommand, } from './runner.js';
 // ============================================================
@@ -23,7 +24,7 @@ export const configSchema = {
  * Returns dispose() function to abort in-flight processes.
  *
  * @param config - Command definitions and defaults
- * @returns ExtensionResult with command functions and dispose
+ * @returns ExtensionFactoryResult with command functions and dispose
  *
  * @example
  * ```typescript
@@ -118,13 +119,13 @@ export function createExecExtension(config) {
             params: [
                 {
                     name: 'args',
-                    type: { type: 'list' },
+                    type: { kind: 'list' },
                     defaultValue: [],
                     annotations: { description: 'Command arguments' },
                 },
                 {
                     name: 'stdin',
-                    type: { type: 'string' },
+                    type: { kind: 'string' },
                     defaultValue: '',
                     annotations: { description: 'Standard input data' },
                 },
@@ -133,7 +134,7 @@ export function createExecExtension(config) {
             annotations: {
                 description: commandConfig.description ?? `Execute ${commandName} command`,
             },
-            returnType: rillTypeToTypeValue({ type: 'dict' }),
+            returnType: rillTypeToTypeValue({ kind: 'dict' }),
         };
     }
     // ============================================================
@@ -153,7 +154,7 @@ export function createExecExtension(config) {
         params: [],
         fn: commands,
         annotations: { description: 'List all configured commands' },
-        returnType: rillTypeToTypeValue({ type: 'list' }),
+        returnType: rillTypeToTypeValue({ kind: 'list' }),
     };
     // ============================================================
     // DISPOSE FUNCTION
@@ -169,9 +170,14 @@ export function createExecExtension(config) {
     // ============================================================
     // EXTENSION RESULT
     // ============================================================
-    const result = functions;
-    result.dispose = dispose;
-    return result;
+    const callableDict = {};
+    for (const [name, def] of Object.entries(functions)) {
+        callableDict[name] = toCallable(def);
+    }
+    return {
+        value: callableDict,
+        dispose,
+    };
 }
 // ============================================================
 // MANIFEST

package/dist/ext/fetch/index.d.ts

@@ -5,7 +5,7 @@
  * Scripts call endpoints with positional args or single dict argument.
  * All URLs are constructed from config - scripts cannot specify arbitrary URLs.
  */
-import type { ExtensionResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
+import type { ExtensionFactoryResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
 export declare const configSchema: ExtensionConfigSchema;
 /** Parameter definition for endpoint */
 export interface EndpointParam {
@@ -46,7 +46,7 @@ export interface FetchConfig {
  * All URLs constructed from config - scripts cannot create arbitrary URLs.
  *
  * @param config - Fetch configuration with endpoints
- * @returns ExtensionResult with endpoint functions and introspection
+ * @returns ExtensionFactoryResult with endpoint functions and introspection
  * @throws Error on invalid configuration
  *
  * @example
@@ -65,5 +65,5 @@ export interface FetchConfig {
  * });
  * ```
  */
-export declare function createFetchExtension(config: FetchConfig): ExtensionResult;
+export declare function createFetchExtension(config: FetchConfig): ExtensionFactoryResult;
 export declare const extensionManifest: ExtensionManifest;

package/dist/ext/fetch/index.js

@@ -6,7 +6,7 @@
  * All URLs are constructed from config - scripts cannot specify arbitrary URLs.
  */
 import { RuntimeError } from '../../error-classes.js';
-import {} from '../../runtime/core/callable.js';
+import { toCallable } from '../../runtime/core/callable.js';
 import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
 import { buildRequest, executeRequest, createSemaphore, } from './request.js';
 // ============================================================
@@ -96,7 +96,7 @@ function processArguments(args, params, functionName) {
  * All URLs constructed from config - scripts cannot create arbitrary URLs.
  *
  * @param config - Fetch configuration with endpoints
- * @returns ExtensionResult with endpoint functions and introspection
+ * @returns ExtensionFactoryResult with endpoint functions and introspection
  * @throws Error on invalid configuration
  *
  * @example
@@ -164,10 +164,10 @@ export function createFetchExtension(config) {
         };
         // Build parameter definitions for RillFunction
         const rillParams = params.map((param) => {
-            // Map EndpointParam type string to RillType object
+            // Map EndpointParam type string to TypeStructure object
             const rillType = param.type !== 'dict'
-                ? { type: param.type }
-                : { type: 'dict' };
+                ? { kind: param.type }
+                : { kind: 'dict' };
             return {
                 name: param.name,
                 type: rillType,
@@ -176,8 +176,8 @@ export function createFetchExtension(config) {
             };
         });
         const returnTypeValue = (endpointConfig.responseShape ?? defaultResponseShape) === 'full'
-            ? rillTypeToTypeValue({ type: 'dict' })
-            : rillTypeToTypeValue({ type: 'any' });
+            ? rillTypeToTypeValue({ kind: 'dict' })
+            : rillTypeToTypeValue({ kind: 'any' });
         const hostFunctionDef = {
             params: rillParams,
             fn: endpointFn,
@@ -211,7 +211,7 @@ export function createFetchExtension(config) {
         params: [],
         fn: endpoints,
         annotations: { description: 'List configured endpoints' },
-        returnType: rillTypeToTypeValue({ type: 'list' }),
+        returnType: rillTypeToTypeValue({ kind: 'list' }),
     };
     // ============================================================
     // DISPOSAL
@@ -229,9 +229,14 @@ export function createFetchExtension(config) {
     // ============================================================
     // EXTENSION RESULT
     // ============================================================
-    const result = functions;
-    result.dispose = dispose;
-    return result;
+    const callableDict = {};
+    for (const [name, def] of Object.entries(functions)) {
+        callableDict[name] = toCallable(def);
+    }
+    return {
+        value: callableDict,
+        dispose,
+    };
 }
 // ============================================================
 // MANIFEST

package/dist/ext/fs/index.d.ts

@@ -4,7 +4,7 @@
  * Provides sandboxed filesystem operations via mount-based access control.
  * All 12 functions implement path validation, permission checks, and glob filtering.
  */
-import type { ExtensionResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
+import type { ExtensionFactoryResult, ExtensionConfigSchema, ExtensionManifest } from '../../runtime/ext/extensions.js';
 import { type MountConfig } from './sandbox.js';
 /** Filesystem extension configuration */
 export interface FsConfig {
@@ -24,7 +24,7 @@ export declare const configSchema: ExtensionConfigSchema;
  * Returns 12 functions: read, write, append, list, find, exists, remove, stat, mkdir, copy, move, mounts.
  *
  * @param config - Mount configuration and defaults
- * @returns ExtensionResult with 12 filesystem functions
+ * @returns ExtensionFactoryResult with 12 filesystem functions
  * @throws RuntimeError if mount initialization fails
  *
  * @example
@@ -36,5 +36,5 @@ export declare const configSchema: ExtensionConfigSchema;
  * });
  * ```
  */
-export declare function createFsExtension(config: FsConfig): ExtensionResult;
+export declare function createFsExtension(config: FsConfig): ExtensionFactoryResult;
 export declare const extensionManifest: ExtensionManifest;