diff --git a/README.md b/README.md index 9fddfa5..05c2862 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,18 @@ The following are intentionally not part of the behavioral contract: - ORM choice. - Internal state management, concurrency model, or runtime libraries. +## Scripting Direction + +bDS2 should use Lua as its user-facing scripting language. + +The reason is host fit, not language fashion: Lua has a better embedding story for the BEAM than Python does, while still being small, expressive, and suitable for user-authored macros, transforms, and utility scripts. The current direction is: + +- Lua script files as the persisted user script format. +- A BEAM-hosted execution boundary with explicit host capabilities instead of unrestricted runtime access. +- Bounded script execution for user-authored code. + +This keeps the scripting surface lightweight and aligned with the Elixir host application. Python remains a possible integration boundary for specialized tasks, but it is no longer the default scripting model for the rewrite. + ## Repository Layout - [mix.exs](/Users/gb/Projects/bDS2/mix.exs): Mix project definition. diff --git a/specs/editor_script.allium b/specs/editor_script.allium index 7cc5a81..347fdfd 100644 --- a/specs/editor_script.allium +++ b/specs/editor_script.allium @@ -16,7 +16,7 @@ value ScriptEditorView { title: String -- editable text input slug: String -- editable text input, auto-generated from title kind: String -- select: utility | macro | transform - entrypoint: String -- select: dynamically discovered functions, "main" always first + entrypoint: String -- select: discovered Lua functions available as entrypoints enabled: Boolean -- checkbox content: String -- code editor content created_at: String -- locale-formatted date @@ -50,11 +50,11 @@ surface ScriptEditorSurface { -- Two rows of metadata fields above the editor. -- Row 1: Title (text input), Slug (text input, auto-generated from title). -- Row 2: Kind (select: utility/macro/transform), - -- Entrypoint (select: dynamically discovered functions with "main" always first), + -- Entrypoint (select: discovered Lua functions exposed by the script), -- Enabled (checkbox). @guarantee EditorBody - -- Code editor with syntax highlighting for the configured scripting language. + -- Code editor with Lua syntax highlighting. -- Toolbar: "Content" label. -- Syntax errors shown as inline markers in editor gutter. @@ -66,23 +66,23 @@ surface ScriptEditorSurface { rule ScriptSave { when: ScriptSaveRequested(script_id) - -- Syntax check first using the configured scripting runtime semantics + -- Lua syntax check first using the configured runtime semantics -- If syntax error: blocks save, shows error inline in editor gutter -- If valid: bumps version, saves to DB + rewrites the published script file - -- Entrypoint list re-discovered from AST after save + -- Entrypoint list re-discovered from Lua source after save } rule ScriptCheckSyntax { when: ScriptCheckSyntaxRequested(script_id) - -- Validates script syntax without saving + -- Validates Lua syntax without saving -- Shows errors inline in editor gutter -- Success shown as toast or status indicator } rule ScriptRun { when: ScriptRunRequested(script_id) - -- Executes script in the configured runtime - -- Calls configured entrypoint function (default: main) + -- Executes the script in the configured Lua runtime + -- Calls the configured Lua entrypoint function -- stdout/stderr directed to Output panel tab -- Output panel auto-opens if not already visible -- Errors shown in Output panel with line numbers diff --git a/specs/frontmatter.allium b/specs/frontmatter.allium index 179a546..62c24bc 100644 --- a/specs/frontmatter.allium +++ b/specs/frontmatter.allium @@ -79,7 +79,7 @@ surface MenuOpmlSurface { } config { - script_extension: String = "script" + script_extension: String = "lua" } -- ============================================================================ @@ -202,7 +202,7 @@ value ScriptFrontmatter { slug: String title: String kind: macro | utility | transform - entrypoint: String -- Default: "render" + entrypoint: String -- Named Lua function used when invoking the script enabled: Boolean version: Integer created_at: Timestamp diff --git a/specs/script.allium b/specs/script.allium index ef1f485..540cace 100644 --- a/specs/script.allium +++ b/specs/script.allium @@ -2,11 +2,12 @@ -- bDS Scripting System -- Scope: core (Wave 6 — scripting behaviour and file contracts) -- Distilled from: src/main/engine/ScriptEngine.ts, schema.ts --- The scripting runtime is intentionally unspecified here; only behavioural --- contracts are normative. +-- Lua is the normative scripting language for user-authored scripts in the +-- rewrite. The concrete embedding strategy remains an implementation choice; +-- only the behavioural contract is normative here. config { - script_extension: String = "script" + script_extension: String = "lua" } enum ScriptStatus { @@ -18,7 +19,7 @@ entity Script { slug: String title: String kind: macro | utility | transform - entrypoint: String -- default: "render" for macros + entrypoint: String -- named Lua function used as the script entrypoint enabled: Boolean status: ScriptStatus content: String? @@ -139,7 +140,7 @@ rule PublishScript { when: PublishScriptRequested(script) requires: script.status = draft requires: ValidateScript(script.content) = valid - -- AST parsing must succeed + -- Lua parsing must succeed before a script can be published ensures: script.status = published ensures: ScriptFileWritten(script) ensures: script.content = null @@ -160,6 +161,8 @@ rule ExecuteMacro { -- Macro scripts are invoked during template rendering -- via [[slug param1=value1 param2=value2]] syntax in post content -- They receive named parameters and the template context, return HTML + -- from a bounded Lua execution environment that exposes only approved + -- host capabilities ensures: MacroOutputProduced(script, html_output) } @@ -167,7 +170,8 @@ rule ExecuteUtility { when: RunUtilityRequested(script) requires: script.kind = utility requires: script.enabled = true - -- Runs on-demand from the UI, produces stdout output + -- Runs on-demand from the UI in a bounded Lua execution environment, + -- produces stdout output ensures: UtilityOutputProduced(script, stdout) } @@ -175,7 +179,8 @@ rule ExecuteTransform { when: BlogmarkReceived(data) -- Transform scripts run sequentially on blogmark deep link data -- Input: title, content, tags, categories, source url - -- Each transform can modify the data before post creation + -- Each transform can modify the data before post creation. + -- Execution uses the same bounded Lua host API contract as other scripts. let transforms = Scripts where kind = transform and enabled = true for t in ordered_by(transforms, s => s.slug): ensures: TransformApplied(t, data)