spl-lang 0.4.1 → 0.5.0

package/README.md

@@ -42,6 +42,10 @@ under `~/.spl` (override with `SPL_HOME`); `spl logout` removes those saved cred
   `{}` remains an empty dict. Functions still require explicit `return`.
 - **Logging:** `log(...)` defaults to info. `log{level=debug}(...)` selects error/info/debug;
   bare level names, strings and expressions are accepted and checked at runtime.
+- **Runtime inputs:** `$env.NAME` / `$env['NAME']` reads process environment strings;
+  `$args[i]` reads repeated CLI `--arg` strings in order (empty list by default).
+  Missing environment names and out-of-range argument indexes return `None`.
+  Both are read-only snapshots, including through aliases, and are not automatically persisted.
 
 Common generation modifiers are `len`, `fmt`, `reasoning`, `show`, `schema`, `repairs`,
 and `model`. Values are evaluated once, then validated before calling the model.
@@ -67,6 +71,7 @@ spl script.spl [--model id] [--mcp file.json] [--cwd dir] [--timeout seconds]
                [--store file.json | --store-module module]
                [--record file.jsonl | --replay file.jsonl]
                [--log-level error|info|debug] [--silent] [--check]
+               [--arg value ...]
 ```
 
 Results are printed on stdout, logs on stderr. Full prompts/responses and statement traces
@@ -87,6 +92,8 @@ The package exports `parse`, `run`, `Logger`, `CopilotBackend`, `RecordingBacken
 `ReplayBackend`, variable stores, authentication helpers, and related types.
 Call `close()` on the backend after running; replay also checks for unused entries there.
 Custom backends must honor the request kind: only `agent` may execute tools.
+Embedding callers can pass `args: ['first', 'second']` in `RunOptions`; omitted
+arguments default to `[]`, not the host's `process.argv`. Each run snapshots `process.env`.
 See [embedding](../docs/internals.html#embedding).
 
 ## Migration

package/dist/ast.d.ts

@@ -14,6 +14,9 @@ export type Expr = {
     t: 'name';
     name: string;
     line: number;
+} | {
+    t: 'special';
+    name: 'env' | 'args';
 } | {
     t: 'list';
     items: Expr[];

package/dist/builtins.js

@@ -1,4 +1,4 @@
-import { compareValues, equals, fromJson, hasKey, isDict, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
+import { assertMutable, compareValues, equals, fromJson, hasKey, isDict, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
 function arity(name, args, min, max = min) {
     if (args.length < min || args.length > max) {
         const expected = min === max ? `${min}` : `${min}-${max}`;
@@ -346,5 +346,10 @@ export function callMethod(self, name, args) {
     if (!table || !Object.prototype.hasOwnProperty.call(table, name)) {
         throw runtimeError(`${typeName(self)} has no method '${name}'`);
     }
+    const mutating = isList(self)
+        ? ['append', 'extend', 'insert', 'pop', 'remove', 'reverse', 'sort', 'clear']
+        : isDict(self) ? ['pop', 'update', 'clear'] : [];
+    if (mutating.includes(name))
+        assertMutable(self);
     return table[name](self, args);
 }

package/dist/cli.js

@@ -24,6 +24,7 @@ Options:
                           All levels include LLM transcripts and [deterministic] statement traces.
   --silent                suppress all logs; only the result is printed
   --model <id>            model override (takes precedence over @{model=...})
+  --arg <value>           script argument exposed in $args (repeatable; also --arg=value)
   --mcp <file.json>       MCP servers in VS Code mcp.json format
   --store <file.json>     persist top-level variables in a JSON file
   --store-module <path>   custom variable store: module exporting createStore() -> { load(), save(vars) }
@@ -79,6 +80,7 @@ async function main() {
                 'log-level': { type: 'string' },
                 silent: { type: 'boolean' },
                 model: { type: 'string' },
+                arg: { type: 'string', multiple: true },
                 mcp: { type: 'string' },
                 store: { type: 'string' },
                 'store-module': { type: 'string' },
@@ -177,7 +179,7 @@ async function main() {
     }
     let result;
     try {
-        result = await run(program, { backend, logger, store: values.replay ? undefined : store, cwd, model: values.model });
+        result = await run(program, { backend, logger, store: values.replay ? undefined : store, cwd, model: values.model, args: values.arg });
     }
     finally {
         try {

package/dist/interpreter.d.ts

@@ -12,6 +12,8 @@ export interface RunOptions {
     cwd?: string;
     /** Overrides the `@{model=...}` directive. */
     model?: string;
+    /** Script arguments exposed as read-only `$args`; defaults to an empty list. */
+    args?: readonly string[];
     maxCallDepth?: number;
 }
 export type RunResult = {

package/dist/interpreter.js

@@ -5,7 +5,7 @@ import { compileSchema } from './schema.js';
 import { Restrictions, makeRestriction } from './restrict.js';
 import { MemoryStore } from './store.js';
 import { ToolHost, TOOL_SPECS } from './tools.js';
-import { compareValues, equals, hasKey, isDict, isFunction, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
+import { assertMutable, compareValues, equals, hasKey, isDict, isFunction, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
 class ExpressionSignal {
     signal;
     constructor(signal) {
@@ -24,6 +24,8 @@ class Interpreter {
     cwd;
     model;
     maxDepth;
+    runtimeEnv = newDict();
+    runtimeArgs;
     constraints = [];
     restrictions;
     depth = 0;
@@ -34,6 +36,13 @@ class Interpreter {
         this.store = opts.store ?? new MemoryStore();
         this.model = opts.model ?? program.directives.model;
         this.maxDepth = opts.maxCallDepth ?? 200;
+        for (const [name, value] of Object.entries(process.env)) {
+            if (value !== undefined)
+                setKey(this.runtimeEnv, name, value);
+        }
+        this.runtimeArgs = [...(opts.args ?? [])];
+        Object.freeze(this.runtimeEnv);
+        Object.freeze(this.runtimeArgs);
         this.restrictions = new Restrictions(this.cwd);
         this.builtins = makeBuiltins({ log: (m) => opts.logger.info(`log: ${m}`) });
         for (const tool of Object.keys(TOOL_SPECS)) {
@@ -263,6 +272,7 @@ class Interpreter {
             return;
         }
         const obj = await this.eval(target.obj, env);
+        assertMutable(obj);
         if (target.t === 'member') {
             if (!isDict(obj))
                 throw runtimeError(`cannot set member '${target.name}' on ${typeName(obj)}`);
@@ -314,6 +324,7 @@ class Interpreter {
                 return null;
             }
             case 'name': return this.lookup(e.name, env);
+            case 'special': return e.name === 'env' ? this.runtimeEnv : this.runtimeArgs;
             case 'list': {
                 const out = [];
                 for (const it of e.items)
@@ -379,8 +390,11 @@ class Interpreter {
         }
     }
     getKey(d, k) {
-        if (!hasKey(d, k))
+        if (!hasKey(d, k)) {
+            if (d === this.runtimeEnv)
+                return null;
             throw runtimeError(`key '${k}' not found`);
+        }
         return d[k];
     }
     async evalCall(callee, argExprs, env) {
@@ -493,13 +507,13 @@ class Interpreter {
         if (typeof index !== 'number' || !Number.isInteger(index))
             throw runtimeError(`indices must be integers, got ${typeName(index)}`);
         const i = index < 0 ? list.length + index : index;
-        if (i < 0 || i >= list.length)
+        if ((i < 0 || i >= list.length) && list !== this.runtimeArgs)
             throw runtimeError(`index ${index} out of range`);
         return i;
     }
     index(obj, index) {
         if (isList(obj))
-            return obj[this.listIndex(obj, index)];
+            return obj[this.listIndex(obj, index)] ?? null;
         if (typeof obj === 'string') {
             const chars = Array.from(obj);
             return chars[this.listIndex(chars, index)];

package/dist/lexer.js

@@ -71,8 +71,10 @@ export function tokenize(src, opts = {}) {
             tokens.push(readString(raw));
             continue;
         }
-        if (isNameStart(c)) {
-            let j = i;
+        if (isNameStart(c) || c === '$') {
+            if (c === '$' && (i + 1 >= src.length || !isNameStart(src[i + 1])))
+                err("unexpected character '$'");
+            let j = i + (c === '$' ? 1 : 0);
             while (j < src.length && isNameChar(src[j]))
                 j++;
             const value = src.slice(i, j);

package/dist/parser.js

@@ -69,6 +69,8 @@ class Parser {
         if (t.type !== 'name')
             this.fail(`expected ${what} but found ${this.describe(t)}`);
         const name = t.value;
+        if (name.startsWith('$'))
+            this.fail(`special variable '${name}' cannot be used as ${what}`);
         if (KEYWORDS.has(name))
             this.fail(`'${name}' is a reserved word and cannot be used as ${what}`);
         this.next();
@@ -476,7 +478,7 @@ class Parser {
             else if (this.isOp('.')) {
                 this.next();
                 const t = this.tok;
-                if (t.type !== 'name')
+                if (t.type !== 'name' || t.value.startsWith('$'))
                     this.fail("expected a member name after '.'");
                 this.next();
                 e = { t: 'member', obj: e, name: t.value };
@@ -585,6 +587,12 @@ class Parser {
         return this.fail(`unexpected ${this.describe(t)}`);
     }
     parseNamePrimary(t) {
+        if (t.value.startsWith('$')) {
+            if (t.value !== '$env' && t.value !== '$args')
+                this.fail(`unknown special variable '${t.value}'`);
+            this.next();
+            return { t: 'special', name: t.value === '$env' ? 'env' : 'args' };
+        }
         switch (t.value) {
             case 'True':
                 this.next();

package/dist/values.d.ts

@@ -21,6 +21,7 @@ export interface BuiltinFunction {
 }
 export type FunctionValue = UserFunction | BuiltinFunction;
 export declare const runtimeError: (msg: string) => Failure;
+export declare function assertMutable(v: Value): void;
 export declare function isFunction(v: unknown): v is FunctionValue;
 export declare function isList(v: unknown): v is Value[];
 export declare function isDict(v: unknown): v is {

package/dist/values.js

@@ -1,5 +1,10 @@
 import { Failure } from './errors.js';
 export const runtimeError = (msg) => new Failure('runtime_error', msg);
+export function assertMutable(v) {
+    if (typeof v === 'object' && v !== null && Object.isFrozen(v)) {
+        throw runtimeError('cannot modify a read-only value');
+    }
+}
 export function isFunction(v) {
     return typeof v === 'object' && v !== null && '__fn' in v && (v.__fn === 'user' || v.__fn === 'builtin');
 }

package/docs/syntax.ebnf

@@ -46,9 +46,10 @@ call           = "(" , [ expr , { "," , expr } , [ "," ] ] , ")" ;
 index          = "[" , expr , "]" ;
 slice          = "[" , [ expr ] , ":" , [ expr ] , "]" ;
 member         = "." , NAME ;
-primary        = NUMBER | string | "True" | "False" | "None" | NAME
+primary        = NUMBER | string | "True" | "False" | "None" | NAME | special_var
                | "(" , expr , ")" | list | dict | block | if_stmt | log_expr
                | ( "think" | "agent" ) , [ modifiers ] , postfix ;
+special_var    = "$env" | "$args" ;
 list           = "[" , [ expr , { "," , expr } , [ "," ] ] , "]" ;
 dict           = "{" , [ expr , ":" , expr , { "," , expr , ":" , expr } , [ "," ] ] , "}" ;
 modifiers      = "{" , [ modifier , { "," , modifier } , [ "," ] ] , "}" ;
@@ -84,6 +85,12 @@ NAME           = ( letter | "_" ) , { letter | digit | "_" } ;
 NL             = newline ;
 
 (* "{{"/"}}" are literal braces; raw strings have no interpolation or escapes.
+   $env is a read-only process-environment dict snapshot; missing keys return None.
+   $args is a read-only list of repeated CLI --arg strings (empty by default);
+   out-of-range integer indexes return None, and negative indexes count from the end.
+   Both are available in every scope and interpolation, cannot be rebound or mutated
+   (including through aliases), and are not automatically persisted.
+   Other $-prefixed names are syntax errors. Ordinary dict/list missing reads still fail.
    Reserved words: let if elif else for in while def return try except assert fail success
    enforce forbid restrict think agent break continue pass and or not True False None.
    Removed syntax: think{level=...}, tool{param=...} 'instructions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
   "type": "module",
   "main": "./dist/index.js",