1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
---@meta progit
-- SPDX-License-Identifier: LSL-1.0
-- ProGit Plugin SDK — LuaCATS type stubs for IDE autocomplete.
--
-- Plugin authors point sumneko-lua / lua-language-server at this file
-- via .luarc.json:
--
-- {
-- "Lua.workspace.library": [
-- "../progit-plugin-sdk/stubs"
-- ],
-- "Lua.diagnostics.globals": ["plugin", "context", "init"]
-- }
--
-- The runtime sandbox enforces these signatures; this file just helps
-- your editor catch typos before the plugin runs.
---@alias hook_name
---| "on_issue_created"
---| "on_issue_updated"
---| "on_issue_deleted"
---| "on_status_changed"
---| "on_sync_push"
---| "on_sync_pull"
---| "on_merge_request_created"
---| "on_external_sync"
---| "on_webhook_received"
---| "on_due_date_approaching"
---| "on_due_date_passed"
---| "on_report_requested"
---| "on_metric_query"
---@class HookFlags : table<hook_name, boolean>
---@class PluginMeta
---@field name string Unique plugin identifier (also the directory name).
---@field version string Plugin semver, e.g. "1.0.0".
---@field author string Author handle or organisation.
---@field description string One-line summary.
---@field sdk_api? string SDK API constraint, e.g. ">=0.2". Defaults to ">=0.1.0".
---@field hooks HookFlags
plugin =
---@class Issue
---@field id string
---@field title string
---@field description string
---@field status string "backlog" | "in-progress" | "done" | ...
---@field tags string[]
---@field assignee string|nil
---@field effort integer|nil 1..5
---@field blocked boolean
---@field created string ISO 8601
---@field updated string ISO 8601
---@field due string|nil ISO 8601
---@field metadata table<string, any>
---@class PluginContext
---@field repo_path string Absolute path to the active repository.
---@field user string|nil Current user, when known.
---@field env table<string, string> Environment variables exposed to the plugin.
---@field config table<string, any> Plugin slice of `.project/config.kdl`.
context = nil
---@class HttpResponse
---@field ok boolean `true` for 2xx.
---@field status integer HTTP status code.
---@field body string Response body, decoded as UTF-8 text.
---@class HttpModule
---@field get fun(url: string, headers?: table<string, string>): HttpResponse
---@field post fun(url: string, body: string, headers?: table<string, string>): HttpResponse
---@field put fun(url: string, body: string, headers?: table<string, string>): HttpResponse
---@field delete fun(url: string, headers?: table<string, string>): HttpResponse
---
--- Capability-gated. Requires `capabilities.network = true` in the
--- plugin manifest. If `capabilities.network_allow` is set, only those
--- hosts (suffix match) may be reached.
http =
---@class JsonModule
---@field encode fun(value: any): string
---@field decode fun(s: string): any
json =
---@class LogModule
---@field debug fun(msg: string)
---@field info fun(msg: string)
---@field warn fun(msg: string)
---@field error fun(msg: string)
log =
---@class StorageModule
---@field get fun(key: string): any|nil Returns the previously-set value, or nil.
---@field set fun(key: string, value: any) Persists value as JSON. Auto-saves on every write.
---@field delete fun(key: string): boolean Returns whether the key existed.
---@field keys fun(): string[]
---@field clear fun()
---
--- Plugin-private storage scoped to `<repo>/.progit/plugins/<plugin-name>/state.json`.
--- Requires `capabilities.storage = true` in the manifest (default for
--- legacy plugins; new plugins must declare it).
storage =
---@class SoberRunResult
---@field ok boolean
---@field data table|nil
---@field error string|nil
---@class SoberModule
---@field run fun(action: string, opts?: table): SoberRunResult
---
--- Capability-gated. Requires `capabilities.sober = true` in the plugin
--- manifest and a ProGit host bridge. The host decides which actions exist;
--- `cli` is the bounded Sober argv bridge used by command contributions.
sober =
---@class CommandContribution
---@field name string
---@field title string|nil
---@field description string|nil
---@field entrypoint "on_command"|nil
---@field args "none"|"fixed"|"passthrough"|nil
---@field aliases string[]|nil
---@field palette boolean|nil
---@field tui table|nil
---
--- Plugins expose host-visible command endpoints through
--- `.progit-plugin.json` at `contributions.commands`. Root-level `commands`
--- is not part of the current SDK contract.
-- ── Hook signatures (informational; you implement these as global functions) ──
--- Called once after metadata extraction, before any hook fires.
--- Read `context.config` here, fail fast with `error("...")` if config is invalid.
---@param issue Issue
---@return table hook result; convention is `{ success = true, ... }`
---@param issue Issue
---@return table
---@param data { id: string }
---@return table
---@param data { id: string, title: string, old_status: string, new_status: string }
---@return table
---@param data { message: string, branch: string, files_changed: integer }
---@return table e.g. `{ allow = true, refs = { 42 } }` or `{ allow = false, message = "..." }`
---@param issues Issue[]
---@return table
---@param issue Issue
---@return table
---@param issue Issue
---@return table
-- ── Event-style API (alternative to per-hook functions) ──
---@class PluginEvent
---@field type string The event variant, e.g. "IssueCreated".
---@field data table|nil Variant payload.
---@param event PluginEvent
---@return any|nil return nil to indicate the plugin doesn't handle this event