Implement the bDS2 sync scripting API.

2026-07-20 15:53:31 +02:00
parent b10212d47e
commit 49447ef451
14 changed files with 1140 additions and 51 deletions
--- a/docs/scripting/API_REFERENCE.md
+++ b/docs/scripting/API_REFERENCE.md
@@ -39,6 +39,7 @@ Macro scripts expose `render(input, context)` and transform scripts expose `main
 - [`bds.projects`](#bdsprojects)
 - [`bds.publish`](#bdspublish)
 - [`bds.scripts`](#bdsscripts)
+- [`bds.sync`](#bdssync)
 - [`bds.tags`](#bdstags)
 - [`bds.tasks`](#bdstasks)
 - [`bds.templates`](#bdstemplates)
@@ -3987,6 +3988,280 @@ local result = bds.scripts.rebuild_from_files()
 }
 ```

+## `bds.sync`
+
+### `bds.sync.check_availability`
+
+Return whether Git is available on the current machine.
+
+**Signature**
+
+```text
+bds.sync.check_availability() -> boolean
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`boolean`. `false` means the operation was rejected or failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.check_availability()
+```
+
+**Example response**
+
+```lua
+true
+```
+
+### `bds.sync.get_repo_state`
+
+Return repository state for the active project using the GitRepositoryState shape.
+
+**Signature**
+
+```text
+bds.sync.get_repo_state() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.get_repo_state()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.get_status`
+
+Return Git status for the active project using the GitStatusResult shape.
+
+**Signature**
+
+```text
+bds.sync.get_status() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.get_status()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.get_history`
+
+Return commit history for the active project using the GitHistoryResult shape.
+
+**Signature**
+
+```text
+bds.sync.get_history() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.get_history()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.get_remote_state`
+
+Return the GitRepositoryState for the active project, matching the bDS2 remote-state alias.
+
+**Signature**
+
+```text
+bds.sync.get_remote_state() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.get_remote_state()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.fetch`
+
+Fetch and prune remote Git refs for the active project, returning GitNetworkResult; unavailable in airplane mode.
+
+**Signature**
+
+```text
+bds.sync.fetch() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.fetch()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.pull`
+
+Fast-forward pull the active project, reconcile its cache database, and return GitNetworkResult; unavailable in airplane mode.
+
+**Signature**
+
+```text
+bds.sync.pull() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.pull()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.push`
+
+Push the active project to its configured remote and return GitNetworkResult; unavailable in airplane mode.
+
+**Signature**
+
+```text
+bds.sync.push() -> table | nil
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.push()
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
+### `bds.sync.commit_all`
+
+Stage and commit every pending change in the active project, returning GitCommitResult.
+
+**Signature**
+
+```text
+bds.sync.commit_all(message: string) -> table | nil
+```
+
+**Parameters**
+
+| Name | Type | Required | Example |
+| --- | --- | --- | --- |
+| `message` | `string` | Yes | `"Working"` |
+
+**Returns**
+
+`table | nil`. `nil` means no value was available or the host operation failed.
+
+**Example call**
+
+```lua
+local result = bds.sync.commit_all("Working")
+```
+
+**Example response**
+
+```lua
+{ key = "value" }
+```
+
 ## `bds.tags`

 ### `bds.tags.create`
--- a/docs/scripting/TYPES.md
+++ b/docs/scripting/TYPES.md
@@ -22,6 +22,15 @@ These are the public, JSON-compatible records returned by the Lua host API. They
 - [`TagData`](#tagdata)
 - [`TaskData`](#taskdata)
 - [`TaskStatus`](#taskstatus)
+- [`GitProviderData`](#gitproviderdata)
+- [`GitRepositoryState`](#gitrepositorystate)
+- [`GitFileStatus`](#gitfilestatus)
+- [`GitStatusResult`](#gitstatusresult)
+- [`GitSyncStatus`](#gitsyncstatus)
+- [`GitCommitData`](#gitcommitdata)
+- [`GitHistoryResult`](#githistoryresult)
+- [`GitNetworkResult`](#gitnetworkresult)
+- [`GitCommitResult`](#gitcommitresult)
 - [`ValidationResult`](#validationresult)

 ## `ProjectData`
@@ -185,7 +194,7 @@ Lua script record.
 | `enabled` | `boolean` | Yes | Whether the record is enabled. |
 | `entrypoint` | `string` | Yes | Lua function invoked by the runtime. |
 | `id` | `string` | Yes | Stable record identifier. |
-| `kind` | `string` | Yes | Script or template kind. |
+| `kind` | `string` | Yes | Public enum value. |
 | `project_id` | `string` | Yes | Identifier of the owning project. |
 | `slug` | `string` | Yes | URL-safe record identifier. |
 | `status` | `string` | Yes | Current lifecycle state. |
@@ -217,7 +226,7 @@ Template record for site rendering.
 | `created_at` | `ISO-8601 string` | Yes | Creation timestamp. |
 | `enabled` | `boolean` | Yes | Whether the record is enabled. |
 | `id` | `string` | Yes | Stable record identifier. |
-| `kind` | `string` | Yes | Script or template kind. |
+| `kind` | `string` | Yes | Public enum value. |
 | `project_id` | `string` | Yes | Identifier of the owning project. |
 | `slug` | `string` | Yes | URL-safe record identifier. |
 | `status` | `string` | Yes | Current lifecycle state. |
@@ -306,6 +315,194 @@ Aggregate task status snapshot.
 | `running_count` | `integer` | Yes | Number of currently running tasks. |
 | `tasks` | `TaskData[]` | Yes | Tasks included in this status snapshot. |

+## `GitProviderData`
+
+Git hosting provider classification used by bDS2 repository state.
+
+**Lua shape**
+
+```lua
+{
+  kind = "utility",
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `kind` | `string` | Yes | Public enum value. |
+
+## `GitRepositoryState`
+
+Repository state returned by bds.sync.get_repo_state and get_remote_state.
+
+**Lua shape**
+
+```lua
+{
+  current_branch = "example",
+  has_lfs = true,
+  is_initialized = true,
+  provider = {
+  kind = "utility",
+},
+  remote_url = "example",
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `current_branch` | `string \| nil` | No | Checked-out branch name. |
+| `has_lfs` | `boolean` | Yes | Whether Git LFS tracking is configured. |
+| `is_initialized` | `boolean` | Yes | Whether the project folder is a Git repository. |
+| `provider` | `GitProviderData \| nil` | No | Hosting provider inferred from the remote URL. |
+| `remote_url` | `string \| nil` | No | Configured origin URL. |
+
+## `GitFileStatus`
+
+One changed path in the active repository.
+
+**Lua shape**
+
+```lua
+{
+  old_path = "example",
+  path = "example",
+  status = "draft",
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `old_path` | `string \| nil` | No | Previous repository-relative path for a rename. |
+| `path` | `string` | Yes | Current repository-relative path. |
+| `status` | `string` | Yes | Current lifecycle state. |
+
+## `GitStatusResult`
+
+Repository working-tree status returned by bds.sync.get_status.
+
+**Lua shape**
+
+```lua
+{
+  files = {
+  {
+    old_path = "example",
+    path = "example",
+    status = "draft",
+  }
+},
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `files` | `GitFileStatus[]` | Yes | Changed repository paths. |
+
+## `GitSyncStatus`
+
+Whether a commit exists locally, remotely, or in both histories.
+
+**Lua shape**
+
+```lua
+{
+  kind = "utility",
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `kind` | `string` | Yes | Public enum value. |
+
+## `GitCommitData`
+
+Commit entry returned in bds.sync history.
+
+**Lua shape**
+
+```lua
+{
+  author = "example",
+  date = "2026-07-19T08:00:00Z",
+  hash = "example",
+  subject = "example",
+  sync_status = {
+  kind = "utility",
+},
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `author` | `string \| nil` | No | Commit author. |
+| `date` | `ISO-8601 string \| nil` | No | ISO-8601 commit date. |
+| `hash` | `string` | Yes | Git object identifier. |
+| `subject` | `string \| nil` | No | Commit subject. |
+| `sync_status` | `GitSyncStatus` | Yes | Local/remote presence classification. |
+
+## `GitHistoryResult`
+
+Commit history returned by bds.sync.get_history.
+
+**Lua shape**
+
+```lua
+{
+  commits = {
+  {
+    author = "example",
+    date = "2026-07-19T08:00:00Z",
+    hash = "example",
+    subject = "example",
+    sync_status = {
+    kind = "utility",
+  },
+  }
+},
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `commits` | `GitCommitData[]` | Yes | Commit history entries. |
+
+## `GitNetworkResult`
+
+Result of a successful bds.sync network operation.
+
+**Lua shape**
+
+```lua
+{
+  output = "example",
+  updated = true,
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `output` | `string` | Yes | Git command output. |
+| `updated` | `boolean` | Yes | Whether the Git network command completed successfully. |
+
+## `GitCommitResult`
+
+Result of successfully committing all pending repository changes.
+
+**Lua shape**
+
+```lua
+{
+  message = "Working",
+  output = "example",
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `message` | `string` | Yes | Latest user-facing task message. |
+| `output` | `string` | Yes | Git command output. |
+
 ## `ValidationResult`

 Template validation result.
--- a/docs/scripting/api.json
+++ b/docs/scripting/api.json
@@ -1428,6 +1428,75 @@
      "params": [],
      "returns": "boolean"
    },
+    {
+      "description": "Return whether Git is available on the current machine.",
+      "name": "check_availability",
+      "namespace": "sync",
+      "params": [],
+      "returns": "boolean"
+    },
+    {
+      "description": "Return repository state for the active project using the GitRepositoryState shape.",
+      "name": "get_repo_state",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Return Git status for the active project using the GitStatusResult shape.",
+      "name": "get_status",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Return commit history for the active project using the GitHistoryResult shape.",
+      "name": "get_history",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Return the GitRepositoryState for the active project, matching the bDS2 remote-state alias.",
+      "name": "get_remote_state",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Fetch and prune remote Git refs for the active project, returning GitNetworkResult; unavailable in airplane mode.",
+      "name": "fetch",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Fast-forward pull the active project, reconcile its cache database, and return GitNetworkResult; unavailable in airplane mode.",
+      "name": "pull",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Push the active project to its configured remote and return GitNetworkResult; unavailable in airplane mode.",
+      "name": "push",
+      "namespace": "sync",
+      "params": [],
+      "returns": "table | nil"
+    },
+    {
+      "description": "Stage and commit every pending change in the active project, returning GitCommitResult.",
+      "name": "commit_all",
+      "namespace": "sync",
+      "params": [
+        {
+          "name": "message",
+          "required": true,
+          "type": "string"
+        }
+      ],
+      "returns": "table | nil"
+    },
    {
      "description": "Upload the rendered site using the provided publishing credentials.",
      "name": "upload_site",
@@ -1782,6 +1851,81 @@
      },
      "name": "TaskStatus"
    },
+    {
+      "description": "Git hosting provider classification used by bDS2 repository state.",
+      "fields": {
+        "kind": "string"
+      },
+      "name": "GitProviderData"
+    },
+    {
+      "description": "Repository state returned by bds.sync.get_repo_state and get_remote_state.",
+      "fields": {
+        "current_branch": "string | nil",
+        "has_lfs": "boolean",
+        "is_initialized": "boolean",
+        "provider": "GitProviderData | nil",
+        "remote_url": "string | nil"
+      },
+      "name": "GitRepositoryState"
+    },
+    {
+      "description": "One changed path in the active repository.",
+      "fields": {
+        "old_path": "string | nil",
+        "path": "string",
+        "status": "string"
+      },
+      "name": "GitFileStatus"
+    },
+    {
+      "description": "Repository working-tree status returned by bds.sync.get_status.",
+      "fields": {
+        "files": "GitFileStatus[]"
+      },
+      "name": "GitStatusResult"
+    },
+    {
+      "description": "Whether a commit exists locally, remotely, or in both histories.",
+      "fields": {
+        "kind": "string"
+      },
+      "name": "GitSyncStatus"
+    },
+    {
+      "description": "Commit entry returned in bds.sync history.",
+      "fields": {
+        "author": "string | nil",
+        "date": "ISO-8601 string | nil",
+        "hash": "string",
+        "subject": "string | nil",
+        "sync_status": "GitSyncStatus"
+      },
+      "name": "GitCommitData"
+    },
+    {
+      "description": "Commit history returned by bds.sync.get_history.",
+      "fields": {
+        "commits": "GitCommitData[]"
+      },
+      "name": "GitHistoryResult"
+    },
+    {
+      "description": "Result of a successful bds.sync network operation.",
+      "fields": {
+        "output": "string",
+        "updated": "boolean"
+      },
+      "name": "GitNetworkResult"
+    },
+    {
+      "description": "Result of successfully committing all pending repository changes.",
+      "fields": {
+        "message": "string",
+        "output": "string"
+      },
+      "name": "GitCommitResult"
+    },
    {
      "description": "Template validation result.",
      "fields": {
--- a/docs/scripting/bds2-core-signatures.json
+++ b/docs/scripting/bds2-core-signatures.json
--- a/docs/scripting/completions.json
+++ b/docs/scripting/completions.json
@@ -1546,6 +1546,84 @@
    "parameters": [],
    "returns": "boolean"
  },
+  {
+    "description": "Return whether Git is available on the current machine.",
+    "detail": "bds.sync.check_availability() -> boolean",
+    "insert_text": "bds.sync.check_availability()",
+    "label": "bds.sync.check_availability",
+    "parameters": [],
+    "returns": "boolean"
+  },
+  {
+    "description": "Return repository state for the active project using the GitRepositoryState shape.",
+    "detail": "bds.sync.get_repo_state() -> table | nil",
+    "insert_text": "bds.sync.get_repo_state()",
+    "label": "bds.sync.get_repo_state",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Return Git status for the active project using the GitStatusResult shape.",
+    "detail": "bds.sync.get_status() -> table | nil",
+    "insert_text": "bds.sync.get_status()",
+    "label": "bds.sync.get_status",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Return commit history for the active project using the GitHistoryResult shape.",
+    "detail": "bds.sync.get_history() -> table | nil",
+    "insert_text": "bds.sync.get_history()",
+    "label": "bds.sync.get_history",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Return the GitRepositoryState for the active project, matching the bDS2 remote-state alias.",
+    "detail": "bds.sync.get_remote_state() -> table | nil",
+    "insert_text": "bds.sync.get_remote_state()",
+    "label": "bds.sync.get_remote_state",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Fetch and prune remote Git refs for the active project, returning GitNetworkResult; unavailable in airplane mode.",
+    "detail": "bds.sync.fetch() -> table | nil",
+    "insert_text": "bds.sync.fetch()",
+    "label": "bds.sync.fetch",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Fast-forward pull the active project, reconcile its cache database, and return GitNetworkResult; unavailable in airplane mode.",
+    "detail": "bds.sync.pull() -> table | nil",
+    "insert_text": "bds.sync.pull()",
+    "label": "bds.sync.pull",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Push the active project to its configured remote and return GitNetworkResult; unavailable in airplane mode.",
+    "detail": "bds.sync.push() -> table | nil",
+    "insert_text": "bds.sync.push()",
+    "label": "bds.sync.push",
+    "parameters": [],
+    "returns": "table | nil"
+  },
+  {
+    "description": "Stage and commit every pending change in the active project, returning GitCommitResult.",
+    "detail": "bds.sync.commit_all(message: string) -> table | nil",
+    "insert_text": "bds.sync.commit_all(\"Working\")",
+    "label": "bds.sync.commit_all",
+    "parameters": [
+      {
+        "name": "message",
+        "required": true,
+        "type": "string"
+      }
+    ],
+    "returns": "table | nil"
+  },
  {
    "description": "Upload the rendered site using the provided publishing credentials.",
    "detail": "bds.publish.upload_site(credentials: table) -> TaskData | nil",