@lanework/contracts 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 fuongz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,36 @@
1
- # Temporary Holding Version
1
+ # @lanework/contracts
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The contract every part of [Lanework](https://lanework.dev) builds on: the
4
+ desktop app, its checkpoint hook, the Lanework API and their MCP servers.
5
+
6
+ - **HTTP**: request and response types, path builders, shared constants.
7
+ - **Tools** (`src/tools/`): the board tools (`board.ts`, with run-time output
8
+ shapes in `outputs.ts` for parity checks), lanework-kit's search tools
9
+ (`kit.ts`) and the conductor/lead control tools (`control.ts`), each with
10
+ its input JSON Schema.
11
+
12
+ It has no runtime dependencies.
13
+
14
+ Formerly `@lanework/protocol` (0.1.0, 0.2.0); 0.3.0 is the first release under
15
+ this name.
16
+
17
+ ```ts
18
+ import { paths, type MachineMeResponse } from "@lanework/contracts";
19
+
20
+ const res = await fetch(`https://api.lanework.dev${paths.machinesMe()}`, {
21
+ headers: { authorization: `Bearer ${token}` },
22
+ });
23
+ const me = (await res.json()) as MachineMeResponse;
24
+ ```
25
+
26
+ The package ships TypeScript source (`src/index.ts`). Use it from a bundler or
27
+ from TypeScript with `"moduleResolution": "bundler"`.
28
+
29
+ ## Releasing
30
+
31
+ Bump `version` in `package.json`, commit, then push a tag `v<version>`: the
32
+ `publish` workflow checks the tag against `package.json` and publishes to npm
33
+ through npm Trusted Publishing (OIDC, no token). Nothing else publishes.
34
+
35
+ MIT. See [LICENSE](LICENSE). The name and logo are covered by the
36
+ repository's [TRADEMARKS.md](https://github.com/fuongz/lanework/blob/main/TRADEMARKS.md).
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@lanework/contracts",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.0",
4
+ "type": "module",
5
+ "description": "The contract between the Lanework desktop app, its checkpoint hook, the Lanework API and their MCP servers: HTTP request and response shapes, the board, kit and control tool contracts (types, JSON Schema builders and run-time output shapes).",
6
+ "license": "MIT",
7
+ "author": "fuongz <hi@phuongphung.com>",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/lanework-dev/contracts.git"
11
+ },
12
+ "exports": {
13
+ ".": "./src/index.ts"
14
+ },
15
+ "files": [
16
+ "src",
17
+ "LICENSE",
18
+ "README.md"
19
+ ],
20
+ "publishConfig": {
21
+ "access": "public"
22
+ },
23
+ "//": "Types, JSON Schema builders and output shapes only, no runtime dependencies. The desktop app (open source) and the API and MCP (private) both build on it; neither half may be imported here.",
24
+ "scripts": {
25
+ "typecheck": "tsc --noEmit"
26
+ },
27
+ "homepage": "https://github.com/lanework-dev/contracts#readme",
28
+ "bugs": {
29
+ "url": "https://github.com/lanework-dev/contracts/issues"
30
+ },
31
+ "devDependencies": {
32
+ "typescript": "^7.0.2"
33
+ }
34
+ }
@@ -0,0 +1,46 @@
1
+ // What a project's agent notes say about the Lanework board.
2
+ //
3
+ // One source for two readers: the desktop app writes it into a project's
4
+ // AGENTS.md / CLAUDE.md, and the docs site shows it as the snippet to paste.
5
+ // Both import it from here, so the two cannot drift apart.
6
+
7
+ export const MCP_URL = "https://mcp.lanework.dev/v1";
8
+
9
+ /**
10
+ * The same server with only the tools for working a card (BE-24):
11
+ * list_boards, get_review, set_status, toggle_item, checkpoint.
12
+ *
13
+ * NOTE: Same resource, same token. The server reads `toolset` past its auth
14
+ * gate; the protected-resource metadata and every token's audience stay the
15
+ * bare {@link MCP_URL}. A client must take the OAuth `resource` from that
16
+ * metadata, not from this URL (OpenCode 2.2 sends the URL itself, query and
17
+ * all, and the authorization server refuses it with `invalid_target`).
18
+ */
19
+ export const MCP_WORKER_URL = "https://mcp.lanework.dev/v1?toolset=worker";
20
+
21
+ /** The MCP host alone, which any lanework config or note contains. */
22
+ export const MCP_HOST = "mcp.lanework.dev";
23
+
24
+ export const AGENT_NOTES = `## Lanework board
25
+
26
+ Cards for this repo live on Lanework, through the \`lanework\` MCP server.
27
+
28
+ - Find the board with \`git remote get-url origin\`, then
29
+ \`list_boards({ repo })\`. Never pick a board by its name. If no board is
30
+ linked, ask me which one it is — or whether to make a new one — then call
31
+ \`link_repo\` or \`create_board\`.
32
+ - Before creating a card, read \`board_summary\` and reuse the board's
33
+ categories and tags.
34
+ - Every \`create_review\` sets \`category\`, \`tags\` and \`priority\`.
35
+ - Put decisions in the card's checklist, and start the work only after I
36
+ have ticked them.
37
+ - Move cards with \`set_status\`; tick verify steps with \`toggle_item\`.
38
+ - A card that touches two or more separate areas gets \`streams\`: one
39
+ sub-agent each, with exact \`owns\` paths and a verify step tagged with
40
+ its key. Shared types go in a \`W0\` the others depend on; at most 4
41
+ streams per wave.
42
+ - Handed a card with \`streams\`, you are the lead: run \`dispatch\` wave
43
+ by wave, one sub-agent per stream in its own worktree, each given its
44
+ brief as is. Sub-agents write only in \`owns\`, never commit and never
45
+ call Lanework. After each wave, merge, re-run each stream's checks, tick
46
+ its verify steps and \`checkpoint\` once.`;
package/src/auth.ts ADDED
@@ -0,0 +1,251 @@
1
+ // Enrolling a machine and asking what the control plane thinks of it:
2
+ // `/v1/cli/*` (`lanework login`, loopback PKCE and device code) and
3
+ // `/v1/machines/*`. Derived from the server's `routes/cli.ts` and
4
+ // `routes/machines.ts`.
5
+
6
+ import type { IsoDate } from "./common";
7
+
8
+ // ── Machine facts ───────────────────────────────────────────────────────────
9
+
10
+ /** A coding-agent CLI found on the machine. Unknown providers are ignored. */
11
+ export interface MachineProvider {
12
+ provider: "claude" | "codex";
13
+ version?: string;
14
+ }
15
+
16
+ /**
17
+ * What a client tells the control plane about the machine it enrols.
18
+ *
19
+ * Display data only; the server bounds and trims every field.
20
+ */
21
+ export interface MachineFacts {
22
+ /** 1-120 characters. Required. */
23
+ name: string;
24
+ /** At most 200 characters. */
25
+ hostname?: string | null;
26
+ /** At most 40 characters, e.g. `darwin`. */
27
+ os?: string | null;
28
+ /** At most 40 characters, e.g. `arm64`. */
29
+ arch?: string | null;
30
+ providers?: MachineProvider[];
31
+ }
32
+
33
+ /**
34
+ * A machine credential, returned once.
35
+ *
36
+ * Returned by `POST /v1/cli/token` and `POST /v1/machines/register`, both
37
+ * with HTTP 201. Only its hash is stored.
38
+ */
39
+ export interface MachineCredential {
40
+ machineId: string;
41
+ /** `lw_mch_…`. Sent back as `Authorization: Bearer <secret>`. */
42
+ secret: string;
43
+ }
44
+
45
+ // ── POST /v1/cli/auth — start a login ───────────────────────────────────────
46
+
47
+ /**
48
+ * The PKCE challenge method: S256 only.
49
+ *
50
+ * `plain` would let anyone who reads the authorize URL forge the proof.
51
+ */
52
+ export type PkceMethod = "S256";
53
+
54
+ interface CliAuthBase extends MachineFacts {
55
+ /** base64url(SHA-256(verifier)), 43 characters. */
56
+ code_challenge: string;
57
+ code_challenge_method: PkceMethod;
58
+ }
59
+
60
+ /** Loopback: the browser comes back to a listener on this machine. */
61
+ export interface CliAuthLoopbackRequest extends CliAuthBase {
62
+ /** Absent or anything but `"device"` means loopback. */
63
+ mode?: "loopback";
64
+ /** `http://127.0.0.1:<port>/oauth/callback`, no query, no fragment. */
65
+ redirect_uri: string;
66
+ /** 8-128 url-safe characters, echoed back on the callback. */
67
+ state: string;
68
+ }
69
+
70
+ /** Device: a human types a short code on another machine. */
71
+ export interface CliAuthDeviceRequest extends CliAuthBase {
72
+ mode: "device";
73
+ }
74
+
75
+ export type CliAuthRequest = CliAuthLoopbackRequest | CliAuthDeviceRequest;
76
+
77
+ export interface CliAuthLoopbackResponse {
78
+ id: string;
79
+ /** On the API's own origin: `<api>/cli/authorize?id=<id>`. */
80
+ authorize_url: string;
81
+ /** Seconds the attempt stays alive (600). */
82
+ expires_in: number;
83
+ }
84
+
85
+ export interface CliAuthDeviceResponse {
86
+ id: string;
87
+ /** `lw_dev_…`. The redeem secret; never shown to a human. */
88
+ device_code: string;
89
+ /** `XXXX-XXXX` from `ABCDEFGHJKMNPQRSTUVWXYZ23456789`. */
90
+ user_code: string;
91
+ /** `<api>/cli/device`. */
92
+ verification_uri: string;
93
+ /** `<api>/cli/device?code=<user_code>`. */
94
+ verification_uri_complete: string;
95
+ /** Seconds to wait between polls of `/v1/cli/token` (5). */
96
+ interval: number;
97
+ /** Seconds the attempt stays alive (600). */
98
+ expires_in: number;
99
+ }
100
+
101
+ export type CliAuthResponse = CliAuthLoopbackResponse | CliAuthDeviceResponse;
102
+
103
+ /**
104
+ * Where the loopback flow lands: the API sends the browser to
105
+ * `<redirect_uri>?code=<lw_code_…>&state=<state>`.
106
+ */
107
+ export const LOOPBACK_CALLBACK_PATH = "/oauth/callback";
108
+
109
+ export interface LoopbackCallbackQuery {
110
+ /** `lw_code_…`, useless without the PKCE verifier. */
111
+ code: string;
112
+ state: string;
113
+ }
114
+
115
+ // ── GET /v1/cli/request, POST /v1/cli/approve — the consent screen ─────────
116
+ // Session-authenticated (a signed-in human in a browser), not machine routes.
117
+
118
+ /** `GET /v1/cli/request?id=…` or `?user_code=…`. */
119
+ export interface CliRequestView {
120
+ id: string;
121
+ mode: "loopback" | "device";
122
+ machineName: string;
123
+ hostname: string | null;
124
+ os: string | null;
125
+ arch: string | null;
126
+ createdAt: IsoDate;
127
+ expiresAt: IsoDate;
128
+ }
129
+
130
+ /** `POST /v1/cli/approve`. One of `id` or `user_code` is required. */
131
+ export interface CliApproveRequest {
132
+ id?: string;
133
+ user_code?: string;
134
+ /** Anything but `"deny"` allows. */
135
+ decision?: "allow" | "deny";
136
+ }
137
+
138
+ export type CliApproveResponse =
139
+ | { decision: "deny" }
140
+ /** Loopback approvals carry the URL the browser must follow next. */
141
+ | { decision: "allow"; redirect_to?: string };
142
+
143
+ // ── POST /v1/cli/token — redeem ─────────────────────────────────────────────
144
+
145
+ /**
146
+ * The body of `POST /v1/cli/token`, which is unauthenticated.
147
+ *
148
+ * The code (or device code) plus the PKCE verifier is the authentication.
149
+ * Send `code` for loopback, `device_code` for device.
150
+ */
151
+ export interface CliTokenRequest {
152
+ code?: string;
153
+ device_code?: string;
154
+ code_verifier: string;
155
+ }
156
+
157
+ /** The 201 answer of `POST /v1/cli/token`: the credential. */
158
+ export type CliTokenResponse = MachineCredential;
159
+
160
+ /**
161
+ * The device flow's "not yet" answers (HTTP 400), in RFC 8628's vocabulary.
162
+ *
163
+ * `invalid_grant` at HTTP 401 is the one answer for a wrong, unapproved,
164
+ * spent or expired code, or a bad verifier.
165
+ */
166
+ export type CliTokenErrorCode =
167
+ | "authorization_pending"
168
+ | "slow_down"
169
+ | "access_denied"
170
+ | "expired_token"
171
+ | "invalid_grant"
172
+ | "invalid_request";
173
+
174
+ export interface CliTokenError {
175
+ error: CliTokenErrorCode;
176
+ /** Present on the device-flow poll answers. */
177
+ interval?: number;
178
+ }
179
+
180
+ // ── /v1/machines ────────────────────────────────────────────────────────────
181
+
182
+ /**
183
+ * `POST /v1/machines/register`: trade a registration token for a credential.
184
+ */
185
+ export interface MachineRegisterRequest extends MachineFacts {
186
+ /** `lw_reg_…`, single use, 15 minutes. */
187
+ token: string;
188
+ }
189
+
190
+ /**
191
+ * The 201 answer of `POST /v1/machines/register`.
192
+ *
193
+ * A 401 is one message for "wrong", "already used" and "expired".
194
+ */
195
+ export type MachineRegisterResponse = MachineCredential;
196
+
197
+ /** The account behind a machine. Each field may be null. */
198
+ export interface MachineOwner {
199
+ name: string | null;
200
+ email: string | null;
201
+ image: string | null;
202
+ }
203
+
204
+ /**
205
+ * `GET /v1/machines/me` (machine credential): who this machine is, and whose.
206
+ *
207
+ * Doubles as the presence ping. 401 means revoked or unknown, alike.
208
+ */
209
+ export interface MachineMeResponse {
210
+ machineId: string;
211
+ name: string;
212
+ userId: string;
213
+ /** Null when the account row is gone; absent on an older control plane. */
214
+ user: MachineOwner | null;
215
+ }
216
+
217
+ /** `DELETE /v1/machines/me` (machine), `DELETE /v1/machines/:id` (session). */
218
+ export interface MachineRevokeResponse {
219
+ revoked: string;
220
+ }
221
+
222
+ /** `POST /v1/machines/heartbeat` (machine). */
223
+ export interface MachineHeartbeatResponse {
224
+ ok: true;
225
+ }
226
+
227
+ /** One row of `GET /v1/machines` (session). */
228
+ export interface MachineSummary {
229
+ id: string;
230
+ name: string;
231
+ hostname: string | null;
232
+ os: string | null;
233
+ arch: string | null;
234
+ createdAt: IsoDate;
235
+ lastSeenAt: IsoDate | null;
236
+ revokedAt: IsoDate | null;
237
+ /** Derived from `lastSeenAt`: seen within about 7 minutes and not revoked. */
238
+ online: boolean;
239
+ }
240
+
241
+ export interface MachineListResponse {
242
+ machines: MachineSummary[];
243
+ }
244
+
245
+ /** `POST /v1/tokens/registration` (session): what `/setup` mints. */
246
+ export interface RegistrationTokenResponse {
247
+ /** `lw_reg_…`. */
248
+ token: string;
249
+ expiresAt: IsoDate;
250
+ command: string;
251
+ }