Implement the bDS2-compatible core Lua host API and generated docs #12

New Issue

hugo · 2026-07-18T20:22:02Z

hugo commented

2026-07-18 20:22:02 +00:00

Goal

Complete the core Lua scripting surface so user scripts can perform the same everyday project operations as bDS2, using RuDS engines rather than a parallel data layer.

Current state

crates/bds-core/src/scripting/mod.rs installs only bds.app.log, bds.app.progress, and bds.app.toast.
Script CRUD, publishing, rebuild, metadata diff, macro execution, transforms, cancellation, and the script editor already exist.
specs/script.allium under CoreHostApiCompatibility is the normative method list.
Script files are always scripts/{slug}.lua. Do not introduce an extension setting.

Required behavior

Expose the core namespaces and methods listed in specs/script.allium:

bds.app
bds.projects
bds.meta
bds.posts
bds.media
bds.scripts
bds.templates
bds.tags
bds.tasks
bds.publish
the historical one-shot AI bridge under bds.chat
top-level bds.report_progress(payload)

Bind project-scoped calls to the active project and delegate to existing core engines/query functions. Returned values must contain only serializable public fields. Use ISO-8601 timestamps and string enum values. Lookup/create/update failures return nil; boolean command failures return false, following the generated signature.

Keep the current bds.app.progress and bds.app.toast helpers as additive APIs. Do not expose ambient filesystem, process, package-loading, or unrestricted host access.

bds.sync, bds.embeddings, conversational chat, agents, and MCP are extension work and are out of scope.

Documentation

Add one machine-readable method/type manifest and generate from it:

the Lua API reference under docs/scripting/
the canonical type reference
editor completion data if completion data is part of the current editor design
working macro, transform, and utility examples

Add a sync test that fails if the exposed capability names, manifest, or generated reference diverge. Do not maintain duplicate hand-written method inventories.

Implementation notes

Read docs/UI_STYLE_GUIDE.md before any documentation/editor UI changes.
Reuse existing engines and task manager operations; do not add scripting-only CRUD implementations.
Preserve sandboxing, cancellation, output routing, toast budgets, and airplane-mode gating for AI calls.
Use red/green TDD. Compare behavior with ../bDS2/lib/bds/scripting/capabilities.ex, its capability modules, api_docs.ex, and scripting API tests where the Allium contract is silent.

Acceptance criteria

Every core method named in specs/script.allium is callable from a Lua utility in the active project.
Representative round-trip tests cover each namespace, including mutation, lookup, failure values, project scoping, task progress, publishing delegation, and one-shot AI gating.
A capability/manifest/docs parity test covers the complete method set.
Generated examples execute successfully in tests.
No extension-only namespace is implemented as part of this issue.
allium check specs/*.allium, cargo fmt --all -- --check, cargo build --workspace, and cargo test --workspace pass.

## Goal Complete the core Lua scripting surface so user scripts can perform the same everyday project operations as bDS2, using RuDS engines rather than a parallel data layer. ## Current state - `crates/bds-core/src/scripting/mod.rs` installs only `bds.app.log`, `bds.app.progress`, and `bds.app.toast`. - Script CRUD, publishing, rebuild, metadata diff, macro execution, transforms, cancellation, and the script editor already exist. - `specs/script.allium` under `CoreHostApiCompatibility` is the normative method list. - Script files are always `scripts/{slug}.lua`. Do not introduce an extension setting. ## Required behavior Expose the core namespaces and methods listed in `specs/script.allium`: - `bds.app` - `bds.projects` - `bds.meta` - `bds.posts` - `bds.media` - `bds.scripts` - `bds.templates` - `bds.tags` - `bds.tasks` - `bds.publish` - the historical one-shot AI bridge under `bds.chat` - top-level `bds.report_progress(payload)` Bind project-scoped calls to the active project and delegate to existing core engines/query functions. Returned values must contain only serializable public fields. Use ISO-8601 timestamps and string enum values. Lookup/create/update failures return `nil`; boolean command failures return `false`, following the generated signature. Keep the current `bds.app.progress` and `bds.app.toast` helpers as additive APIs. Do not expose ambient filesystem, process, package-loading, or unrestricted host access. `bds.sync`, `bds.embeddings`, conversational chat, agents, and MCP are extension work and are out of scope. ## Documentation Add one machine-readable method/type manifest and generate from it: - the Lua API reference under `docs/scripting/` - the canonical type reference - editor completion data if completion data is part of the current editor design - working macro, transform, and utility examples Add a sync test that fails if the exposed capability names, manifest, or generated reference diverge. Do not maintain duplicate hand-written method inventories. ## Implementation notes - Read `docs/UI_STYLE_GUIDE.md` before any documentation/editor UI changes. - Reuse existing engines and task manager operations; do not add scripting-only CRUD implementations. - Preserve sandboxing, cancellation, output routing, toast budgets, and airplane-mode gating for AI calls. - Use red/green TDD. Compare behavior with `../bDS2/lib/bds/scripting/capabilities.ex`, its capability modules, `api_docs.ex`, and scripting API tests where the Allium contract is silent. ## Acceptance criteria - Every core method named in `specs/script.allium` is callable from a Lua utility in the active project. - Representative round-trip tests cover each namespace, including mutation, lookup, failure values, project scoping, task progress, publishing delegation, and one-shot AI gating. - A capability/manifest/docs parity test covers the complete method set. - Generated examples execute successfully in tests. - No extension-only namespace is implemented as part of this issue. - `allium check specs/*.allium`, `cargo fmt --all -- --check`, `cargo build --workspace`, and `cargo test --workspace` pass.

hugo added the enhancement label 2026-07-18 20:22:02 +00:00

hugo referenced this issue

2026-07-18 20:48:48 +00:00

Add in-app project and Lua documentation browsers #24

hugo commented

2026-07-19 07:25:24 +00:00

Implemented in commit 9a72287. The core Lua host now exposes the exact bDS2-compatible signatures with project scoping and fail-closed return values; rendered macros and Blogmark transforms receive the project host; Blogmark execution is cancellable; desktop bds.app capabilities delegate to the native shell; Lua reindexing is project-scoped; progress is reported once; and manifest-generated API/type docs, completions, and executable examples are bundled. bds.sync and bds.embeddings remain absent as extension-only work. Verified with Allium check/analyse, cargo fmt, workspace build, strict Clippy, and the complete workspace test suite.

Implemented in commit 9a72287. The core Lua host now exposes the exact bDS2-compatible signatures with project scoping and fail-closed return values; rendered macros and Blogmark transforms receive the project host; Blogmark execution is cancellable; desktop bds.app capabilities delegate to the native shell; Lua reindexing is project-scoped; progress is reported once; and manifest-generated API/type docs, completions, and executable examples are bundled. bds.sync and bds.embeddings remain absent as extension-only work. Verified with Allium check/analyse, cargo fmt, workspace build, strict Clippy, and the complete workspace test suite.

hugo closed this issue

2026-07-19 07:25:32 +00:00

hugo referenced this issue

2026-07-19 16:58:49 +00:00

Add in-app project and Lua documentation browsers #24

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/RuDS#12