Implement the bds.sync Lua namespace for bDS2 script compatibility #45

New Issue

hugo · 2026-07-20T10:38:18Z

hugo commented

2026-07-20 10:38:18 +00:00

Context

The RuDS spec specs/script.allium (guarantee CoreHostApiCompatibility) currently says "bds.sync remains a future extension contract" — but this deferral was introduced in RuDS's own spec edit, not inherited from the baseline: bDS2 ships a full bds.sync Lua namespace (../bDS2/lib/bds/scripting/capabilities.ex, sync_capabilities/2, and api_docs.ex module "sync"). Since docs/scripting/API_REFERENCE.md promises "the same published script file can run in either application", a bDS2 script using bds.sync currently fails on RuDS. All underlying operations already exist in RuDS's GitEngine (crates/bds-core/src/engine/git.rs) — this is a binding task, not new engine work.

Task

Implement the bds.sync namespace in the Lua core host (crates/bds-core/src/scripting/core_host.rs) with bDS2-identical signatures and failure values (nil on lookup/command failure per HostApiFailureValues):

Method	bDS2 behavior
`check_availability()`	boolean — Git binary available on this machine
`get_repo_state()`	table or nil — repository state for the active project
`get_status()`	table or nil — git status
`get_history()`	table or nil — commit history
`get_remote_state()`	table or nil — remote state (bDS2 maps this to the same repo-state call)
`fetch()`	table or nil — git fetch
`pull()`	table or nil — ff-only pull
`push()`	table or nil — git push
`commit_all(message)`	table or nil — stage all + commit

Requirements:

Project-scoped to the active project, like every other namespace.
Airplane mode gates the network methods (fetch, pull, push) exactly like the Git UI/CLI paths — blocked with the standard failure value, no network calls.
pull must run the same post-pull reconciliation as CLI pull (incremental cache update through the shared rebuild path) so the database reflects pulled files.
Return tables mirror bDS2's shapes (see ../bDS2/lib/bds/scripting/capabilities.ex and the capability helpers it calls); timestamps as ISO-8601 strings, enums as strings.
Add the namespace to the machine-readable manifest (crates/bds-core/src/scripting/manifest.rs) so generated API reference, type definitions, and editor completion data pick it up; the manifest drift-check test must pass.
Update docs/scripting/API_REFERENCE.md generation inputs so bds.sync appears; regenerate.
Update specs/script.allium: move bds.sync (with its 9 methods) into the CoreHostApiCompatibility capability list and delete the "future extension contract" sentence. Validate with allium check specs/*.allium.
Red/green TDD: unit tests against a temporary git repository covering success, non-repo failure (nil), airplane blocking of fetch/pull/push, and commit_all with an empty message rejected.

Definition of done

A Lua utility script calling every bds.sync method runs identically on RuDS and bDS2 (modulo table field ordering).
Manifest, generated docs, completion data, and spec are in sync; cargo test --workspace passes.

## Context The RuDS spec `specs/script.allium` (guarantee `CoreHostApiCompatibility`) currently says "bds.sync remains a future extension contract" — but this deferral was introduced in RuDS's own spec edit, not inherited from the baseline: bDS2 **ships** a full `bds.sync` Lua namespace (`../bDS2/lib/bds/scripting/capabilities.ex`, `sync_capabilities/2`, and `api_docs.ex` module "sync"). Since `docs/scripting/API_REFERENCE.md` promises "the same published script file can run in either application", a bDS2 script using `bds.sync` currently fails on RuDS. All underlying operations already exist in RuDS's `GitEngine` (`crates/bds-core/src/engine/git.rs`) — this is a binding task, not new engine work. ## Task Implement the `bds.sync` namespace in the Lua core host (`crates/bds-core/src/scripting/core_host.rs`) with bDS2-identical signatures and failure values (nil on lookup/command failure per `HostApiFailureValues`): | Method | bDS2 behavior | |---|---| | `check_availability()` | boolean — Git binary available on this machine | | `get_repo_state()` | table or nil — repository state for the active project | | `get_status()` | table or nil — git status | | `get_history()` | table or nil — commit history | | `get_remote_state()` | table or nil — remote state (bDS2 maps this to the same repo-state call) | | `fetch()` | table or nil — git fetch | | `pull()` | table or nil — ff-only pull | | `push()` | table or nil — git push | | `commit_all(message)` | table or nil — stage all + commit | Requirements: 1. Project-scoped to the active project, like every other namespace. 2. Airplane mode gates the network methods (`fetch`, `pull`, `push`) exactly like the Git UI/CLI paths — blocked with the standard failure value, no network calls. 3. `pull` must run the same post-pull reconciliation as CLI `pull` (incremental cache update through the shared rebuild path) so the database reflects pulled files. 4. Return tables mirror bDS2's shapes (see `../bDS2/lib/bds/scripting/capabilities.ex` and the capability helpers it calls); timestamps as ISO-8601 strings, enums as strings. 5. Add the namespace to the machine-readable manifest (`crates/bds-core/src/scripting/manifest.rs`) so generated API reference, type definitions, and editor completion data pick it up; the manifest drift-check test must pass. 6. Update `docs/scripting/API_REFERENCE.md` generation inputs so `bds.sync` appears; regenerate. 7. Update `specs/script.allium`: move `bds.sync` (with its 9 methods) into the `CoreHostApiCompatibility` capability list and delete the "future extension contract" sentence. Validate with `allium check specs/*.allium`. 8. Red/green TDD: unit tests against a temporary git repository covering success, non-repo failure (nil), airplane blocking of fetch/pull/push, and commit_all with an empty message rejected. ## Definition of done - A Lua utility script calling every `bds.sync` method runs identically on RuDS and bDS2 (modulo table field ordering). - Manifest, generated docs, completion data, and spec are in sync; `cargo test --workspace` passes.

hugo added the enhancement label 2026-07-20 10:39:54 +00:00

hugo commented

2026-07-20 13:54:51 +00:00

Implemented in 49447ef.

Added the complete bDS2-compatible bds.sync Lua namespace with all nine methods, project-scoped GitEngine dispatch, bDS2 table shapes, string enums, ISO dates, nil failure values, airplane-mode network gating, and shared CLI/Lua post-pull incremental reconciliation. Added manifest types, frozen signature coverage, generated API/type/completion docs, README and Allium updates.

Verification uses real temporary repositories and a bare remote to exercise every method, successful fetch/pull/commit/push, database reconciliation after pull, non-repository nil behavior, blank-commit rejection, and proof that offline network calls leave local, tracking, and remote refs unchanged. Neutral review against the issue, bDS2 bridges and Git behavior, and Allium found no gaps. The formatting, clippy, build, dependency-audit, dependency-freshness, Allium check/analyse, and full workspace test gates all pass.

Implemented in 49447ef. Added the complete bDS2-compatible bds.sync Lua namespace with all nine methods, project-scoped GitEngine dispatch, bDS2 table shapes, string enums, ISO dates, nil failure values, airplane-mode network gating, and shared CLI/Lua post-pull incremental reconciliation. Added manifest types, frozen signature coverage, generated API/type/completion docs, README and Allium updates. Verification uses real temporary repositories and a bare remote to exercise every method, successful fetch/pull/commit/push, database reconciliation after pull, non-repository nil behavior, blank-commit rejection, and proof that offline network calls leave local, tracking, and remote refs unchanged. Neutral review against the issue, bDS2 bridges and Git behavior, and Allium found no gaps. The formatting, clippy, build, dependency-audit, dependency-freshness, Allium check/analyse, and full workspace test gates all pass.

hugo closed this issue

2026-07-20 13:55:00 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/RuDS#45