@lanework/contracts 0.4.0 → 0.5.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lanework/contracts",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
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
6
  "license": "MIT",
@@ -22,7 +22,9 @@
22
22
  },
23
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
24
  "scripts": {
25
- "typecheck": "tsc --noEmit"
25
+ "typecheck": "tsc --noEmit",
26
+ "test": "bun test",
27
+ "check:size": "bun scripts/check-size.ts"
26
28
  },
27
29
  "homepage": "https://github.com/lanework-dev/contracts#readme",
28
30
  "bugs": {
package/src/avatar.ts ADDED
@@ -0,0 +1,191 @@
1
+ // A project's chosen avatar: a letter, an emoji or an icon on a colour from a
2
+ // fixed palette. Synced with the project, so every machine and teammate sees
3
+ // the same mark. A project without one keeps its default mark: its owner's
4
+ // GitHub icon, or the letter tile.
5
+
6
+ /**
7
+ * Colour ids, never hex: there are no custom colours. Each app draws an id
8
+ * its own way, in light and dark.
9
+ */
10
+ export const PROJECT_AVATAR_COLORS = [
11
+ // solid
12
+ "slate",
13
+ "red",
14
+ "orange",
15
+ "amber",
16
+ "green",
17
+ "teal",
18
+ "sky",
19
+ "blue",
20
+ "violet",
21
+ "pink",
22
+ // gradient
23
+ "sunset",
24
+ "ocean",
25
+ "forest",
26
+ "candy",
27
+ "dusk",
28
+ "aurora",
29
+ ] as const;
30
+
31
+ export type ProjectAvatarColor = (typeof PROJECT_AVATAR_COLORS)[number];
32
+
33
+ /**
34
+ * The icons a project may pick: export names from `@hugeicons/core-free-icons`
35
+ * (checked against 4.3.0). A curated list, not the whole set, so an app only
36
+ * bundles these. Removing a name is a breaking change; adding one is minor.
37
+ */
38
+ export const PROJECT_AVATAR_ICONS = [
39
+ // work and code
40
+ "Rocket01Icon",
41
+ "SourceCodeIcon",
42
+ "ComputerTerminal01Icon",
43
+ "GitBranchIcon",
44
+ "Bug01Icon",
45
+ "Database01Icon",
46
+ "ServerStack01Icon",
47
+ "CloudIcon",
48
+ "Globe02Icon",
49
+ "Link01Icon",
50
+ "Layers01Icon",
51
+ "Package01Icon",
52
+ "DashboardSquare01Icon",
53
+ "Settings01Icon",
54
+ "Wrench01Icon",
55
+ "Shield01Icon",
56
+ "LockIcon",
57
+ "Robot01Icon",
58
+ "AiBrain01Icon",
59
+ "SparklesIcon",
60
+ "MagicWand01Icon",
61
+ // business
62
+ "Briefcase01Icon",
63
+ "Analytics01Icon",
64
+ "ChartLineData01Icon",
65
+ "Wallet01Icon",
66
+ "CreditCardIcon",
67
+ "ShoppingCart01Icon",
68
+ "ShoppingBag01Icon",
69
+ "Store01Icon",
70
+ "Target02Icon",
71
+ "Flag01Icon",
72
+ "Award01Icon",
73
+ // communication and documents
74
+ "Mail01Icon",
75
+ "BubbleChatIcon",
76
+ "Notification01Icon",
77
+ "Calendar03Icon",
78
+ "Clock01Icon",
79
+ "Folder01Icon",
80
+ "File01Icon",
81
+ "Book02Icon",
82
+ "School01Icon",
83
+ "PencilEdit01Icon",
84
+ // people and places
85
+ "Home01Icon",
86
+ "UserIcon",
87
+ "UserGroupIcon",
88
+ "Location01Icon",
89
+ "Compass01Icon",
90
+ "Car01Icon",
91
+ "Airplane01Icon",
92
+ "AnchorIcon",
93
+ // media and play
94
+ "PaintBoardIcon",
95
+ "ColorsIcon",
96
+ "Image01Icon",
97
+ "Camera01Icon",
98
+ "MusicNote01Icon",
99
+ "HeadphonesIcon",
100
+ "GameController01Icon",
101
+ "PuzzleIcon",
102
+ // science
103
+ "Atom01Icon",
104
+ "TestTube01Icon",
105
+ "Idea01Icon",
106
+ // nature and things
107
+ "Sun01Icon",
108
+ "Moon02Icon",
109
+ "FlashIcon",
110
+ "FireIcon",
111
+ "Leaf01Icon",
112
+ "Plant01Icon",
113
+ "Tree01Icon",
114
+ "Coffee01Icon",
115
+ "Pizza01Icon",
116
+ "BirthdayCakeIcon",
117
+ "GiftIcon",
118
+ "Diamond01Icon",
119
+ "CrownIcon",
120
+ "StarIcon",
121
+ "FavouriteIcon",
122
+ "SmileIcon",
123
+ ] as const;
124
+
125
+ export type ProjectAvatarIcon = (typeof PROJECT_AVATAR_ICONS)[number];
126
+
127
+ /**
128
+ * A project's chosen avatar. On the wire `avatar?: ProjectAvatar | null`:
129
+ * absent leaves it alone, `null` clears it back to the default mark.
130
+ */
131
+ export type ProjectAvatar =
132
+ /** 1-2 characters (graphemes), e.g. initials. */
133
+ | { kind: "letter"; text: string; color: ProjectAvatarColor }
134
+ /** Exactly one emoji grapheme. */
135
+ | { kind: "emoji"; emoji: string; color: ProjectAvatarColor }
136
+ /** A name from {@link PROJECT_AVATAR_ICONS}. */
137
+ | { kind: "icon"; icon: ProjectAvatarIcon; color: ProjectAvatarColor };
138
+
139
+ const COLORS: ReadonlySet<string> = new Set(PROJECT_AVATAR_COLORS);
140
+ const ICONS: ReadonlySet<string> = new Set(PROJECT_AVATAR_ICONS);
141
+ const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
142
+ // Control and format characters (zero-width joiners, direction marks).
143
+ const CONTROL = /\p{Cc}|\p{Cf}/u;
144
+ // A grapheme that is an emoji: a pictograph, a flag (regional indicators) or
145
+ // a keycap.
146
+ const EMOJI = /\p{Extended_Pictographic}|\p{Regional_Indicator}|⃣/u;
147
+
148
+ function graphemes(text: string): string[] {
149
+ return Array.from(GRAPHEMES.segment(text), (s) => s.segment);
150
+ }
151
+
152
+ function isObject(value: unknown): value is Record<string, unknown> {
153
+ return typeof value === "object" && value !== null && !Array.isArray(value);
154
+ }
155
+
156
+ /**
157
+ * Read an avatar from untrusted input, strictly: an unknown kind, colour or
158
+ * icon, letter text that is empty, blank or over 2 characters, or an emoji
159
+ * that is not exactly one emoji grapheme gives null. Extra keys are dropped.
160
+ */
161
+ export function parseProjectAvatar(value: unknown): ProjectAvatar | null {
162
+ if (!isObject(value)) return null;
163
+ const { kind, color } = value;
164
+ if (typeof color !== "string" || !COLORS.has(color)) return null;
165
+ const c = color as ProjectAvatarColor;
166
+
167
+ switch (kind) {
168
+ case "letter": {
169
+ const { text } = value;
170
+ if (typeof text !== "string" || text.trim() !== text) return null;
171
+ if (CONTROL.test(text)) return null;
172
+ const n = graphemes(text).length;
173
+ if (n < 1 || n > 2) return null;
174
+ return { kind, text, color: c };
175
+ }
176
+ case "emoji": {
177
+ const { emoji } = value;
178
+ if (typeof emoji !== "string") return null;
179
+ const g = graphemes(emoji);
180
+ if (g.length !== 1 || !EMOJI.test(emoji)) return null;
181
+ return { kind, emoji, color: c };
182
+ }
183
+ case "icon": {
184
+ const { icon } = value;
185
+ if (typeof icon !== "string" || !ICONS.has(icon)) return null;
186
+ return { kind, icon: icon as ProjectAvatarIcon, color: c };
187
+ }
188
+ default:
189
+ return null;
190
+ }
191
+ }
package/src/index.ts CHANGED
@@ -9,6 +9,7 @@
9
9
 
10
10
  export * from "./agent-notes";
11
11
  export * from "./auth";
12
+ export * from "./avatar";
12
13
  export * from "./boards";
13
14
  export * from "./checkpoints";
14
15
  export * from "./common";
package/src/sync.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  // only; `/v1/workspaces` is the session twin and refuses a machine with 401.
3
3
  // Derived from the server's `routes/sync.ts`.
4
4
 
5
+ import type { ProjectAvatar } from "./avatar";
5
6
  import type { IsoDate } from "./common";
6
7
 
7
8
  export interface SyncProfile {
@@ -20,6 +21,12 @@ export interface SyncWorkspace {
20
21
  color: string | null;
21
22
  /** The R2 key of the project's icon, or null. */
22
23
  iconKey: string | null;
24
+ /**
25
+ * The avatar picked for the project, or null for the default mark (the
26
+ * owner's GitHub icon, or the letter tile). Absent from a server older
27
+ * than 0.5.0.
28
+ */
29
+ avatar?: ProjectAvatar | null;
23
30
  laneworkStyle: boolean;
24
31
  baseBranch: string | null;
25
32
  addedAt: IsoDate;
@@ -117,6 +124,11 @@ export interface SyncWorkspaceSlugTakenError {
117
124
  export interface SyncWorkspacePatchRequest {
118
125
  name?: string;
119
126
  color?: string | null;
127
+ /**
128
+ * Set the avatar; `null` clears it back to the default mark. The server
129
+ * refuses with 400 what `parseProjectAvatar` refuses.
130
+ */
131
+ avatar?: ProjectAvatar | null;
120
132
  baseBranch?: string | null;
121
133
  laneworkStyle?: boolean;
122
134
  autoRoute?: boolean;
@@ -128,6 +140,7 @@ export interface SyncWorkspacePatchResponse {
128
140
  slug: string;
129
141
  name: string;
130
142
  color: string | null;
143
+ avatar?: ProjectAvatar | null;
131
144
  baseBranch: string | null;
132
145
  };
133
146
  }
@@ -23,62 +23,54 @@ const FIND_BOARD =
23
23
 
24
24
  /** What a full session does when the repo has no board, or several. */
25
25
  const NO_BOARD =
26
- "None: call list_boards without repo and ask the user which board this " +
27
- "repo belongs to — the boards you can see, PLUS an option to create a " +
28
- "new board for this repo (suggest `owner/name` from the remote as its " +
29
- "name). Then link_repo the one they picked, or create_board if they " +
30
- "chose a new one; never create a board they did not ask for. A board " +
31
- "links to ONE repo: linking a board that already has another repo " +
32
- "MOVES it (replace), it never adds a second. Several: ask the user. No " +
33
- "git remote: ask the user. Never pick a board by its name. ";
26
+ "None: list_boards without repo and ask which board this repo belongs to, " +
27
+ "offering also a new one (suggest `owner/name` from the remote); then " +
28
+ "link_repo their pick, or create_board only if they asked. Linking a board " +
29
+ "that has another repo MOVES the link. Several, or no remote: ask. Never " +
30
+ "pick a board by its name. ";
31
+ ("git remote: ask the user. Never pick a board by its name. ");
34
32
 
35
33
  /** Creating a card: what every create_review must carry. */
36
34
  const NEW_CARD =
37
- "Before creating a card, read board_summary so its category and tags " +
38
- "match the vocabulary the board already uses; the category is also what " +
39
- "mints the card's permanent task id. Every create_review (a successor " +
40
- "card too) passes category, 1-3 tags and priority explicitly: high for " +
41
- "blockers and release prerequisites, medium for planned work, low for " +
42
- "polish. Put context, an out-of-scope section and the files touched in " +
43
- "the body; decisions the user approves and verify steps that prove the " +
44
- "work in the checklist, a pick-ONE choice as boxes sharing a `group` " +
45
- "with the recommendation marked. Never invent a task id: the server " +
46
- "mints it. After create_review, offer to review the new card right " +
47
- "here. ";
35
+ "Before create_review, read board_summary and reuse its categories and " +
36
+ "tags (the category mints the task id; never invent one). Every " +
37
+ "create_review passes category, 1-3 tags and priority (high: blockers, " +
38
+ "release prerequisites; medium: planned work; low: polish). Body: context, " +
39
+ "out of scope, files touched. Checklist: decisions the user approves, " +
40
+ "verify steps that prove the work; a pick-ONE choice is boxes sharing a " +
41
+ "`group`, the recommendation marked. ";
42
+ ("here. ");
48
43
 
49
44
  /** The gate between a card's plan and its implementation. */
50
45
  const REVIEW_GATE =
51
- "Behavior-changing work starts only once every decision box is ticked " +
52
- "(a card in todo with decisions open is a plan, not a go). Read-only " +
53
- "requests, single-file obvious fixes, or work whose exact shape the user " +
54
- "gave need no card. Use toggle_item for checklist boxes and notes, " +
55
- "update_review for metadata, set_status for lanes; ticking a verify item " +
56
- "sends evidence (the command and whether it passed). ";
46
+ "Behavior-changing work starts only once every decision is ticked; " +
47
+ "read-only requests, obvious one-file fixes and work whose exact shape the " +
48
+ "user gave need no card. toggle_item ticks boxes and notes (a verify tick " +
49
+ "sends evidence: the command and whether it passed), update_review edits " +
50
+ "metadata, set_status moves lanes. ";
51
+ ("sends evidence (the command and whether it passed). ");
57
52
 
58
53
  const CHECKPOINT_FLOW =
59
- "While working a card, call checkpoint after each checklist item you " +
60
- "finish and before you stop mid-task. Asked to resume a card: " +
61
- "get_review it and read its checkpoint. If checkpoint.git.wipRef is " +
62
- "set AND you are not in the checkout it came from (checkpoint.host " +
63
- "is another machine, or this is a fresh clone or a cloud sandbox), " +
64
- "check out checkpoint.git.head, then `git fetch origin <wipRef> && " +
65
- "git cherry-pick --no-commit FETCH_HEAD && git reset` to restore the " +
66
- "uncommitted work; in the same checkout that work is already on " +
67
- "disk, so skip it. Re-run every check it claims passed, then " +
68
- "continue from nextStep (or the summary). ";
54
+ "While working a card, call checkpoint after each item you finish and " +
55
+ "before you stop. To resume: get_review and read its checkpoint; if " +
56
+ "checkpoint.git.wipRef is set and this is not the checkout it came from " +
57
+ "(another host, a fresh clone, a sandbox), check out checkpoint.git.head " +
58
+ "and `git fetch origin <wipRef> && git cherry-pick --no-commit FETCH_HEAD " +
59
+ "&& git reset`. Re-run every check it claims passed, then continue from " +
60
+ "nextStep. ";
61
+ ("continue from nextStep (or the summary). ");
69
62
 
70
63
  const STALE =
71
- "A card with `stale` set was left mid-task by another agent: before " +
72
- "opening a new card for the same work, get_review it and resume from " +
73
- "its checkpoint. ";
64
+ "A card with `stale` set was left mid-task: resume it from its checkpoint " +
65
+ "rather than opening a duplicate. ";
66
+ ("its checkpoint. ");
74
67
 
75
68
  const HAND_OFF =
76
- "Finished and verified work goes to the board's review-role lane via " +
77
- "set_status, not done; only a human moves it to done. A card sent " +
78
- "back from review carries changesRequested.reason in get_review: " +
79
- "read it first. " +
80
- "When set_status returns retro, propose at most 3 lessons and ask the " +
81
- "user before writing any. ";
69
+ "Finished, verified work goes to the review-role lane via set_status; only " +
70
+ "a human moves it to done. A card sent back carries changesRequested.reason " +
71
+ "in get_review: read it first. When set_status returns retro, propose at " +
72
+ "most 3 lessons and ask before writing any. ";
73
+ ("user before writing any. ");
82
74
 
83
75
  /** Leading a card's streams (BE-19); also the `work` prompt's text. */
84
76
  export const STREAMS_FLOW =
@@ -99,10 +91,10 @@ export const STREAMS_FLOW =
99
91
  /** Splitting a new card into streams, when writing it. */
100
92
  const WRITE_STREAMS =
101
93
  "Split a card into streams only when it touches two or more independent " +
102
- "write areas: each stream has a key (W0, W1…), a goal, a role and exact " +
103
- "`owns` paths no other stream in its wave owns, and at least one verify " +
104
- "item tagged with its key; shared types go in a W0 the others depend " +
105
- "on, at most 4 streams per wave. ";
94
+ "write areas: each has a key (W0…), goal, role, exact `owns` paths no " +
95
+ "other stream in its wave owns, and a verify item tagged with its key; " +
96
+ "shared types go in a W0 the others depend on; at most 4 per wave. ";
97
+ ("on, at most 4 streams per wave. ");
106
98
 
107
99
  /** Reviewing a card with the user (BE-14); also the `review` prompt's text. */
108
100
  export const REVIEW_FLOW =
@@ -121,6 +113,30 @@ export const REVIEW_FLOW =
121
113
  "review_card does not move the card, and work starts only once it answers " +
122
114
  "ready: true.";
123
115
 
116
+ /**
117
+ * The streams and review flows, short, for the instructions. The full texts
118
+ * (STREAMS_FLOW, REVIEW_FLOW) stay the `work` and `review` prompts'.
119
+ *
120
+ * ⚠️ The instructions stay under 4,000 characters: Claude Code cuts a
121
+ * server's instructions at 4,096 (`… [truncated]`), and what falls past it
122
+ * is lost. `bun run check:size` in CI holds them to it.
123
+ */
124
+ const RUN_STREAMS =
125
+ "A card with streams comes back from get_review with dispatch { waves, " +
126
+ "briefs }: you are its lead. Per wave, spawn one sub-agent per stream at " +
127
+ "once (own worktree unless shared) with its brief verbatim; sub-agents " +
128
+ "never call Lanework or commit. After the wave, merge, revert anything " +
129
+ "outside each stream's owns, re-run its checks, tick its verify items, " +
130
+ "checkpoint once. Then the untagged verify items. ";
131
+
132
+ const REVIEW_SHORT =
133
+ "To review a card with the user: get_review it and ask with your option " +
134
+ "picker, one single-select question per pick-ONE group (recommended " +
135
+ "first) and the other decisions as multi-select, at most 4 questions a " +
136
+ "turn; then call review_card ONCE with exactly what they picked (unpicked " +
137
+ "offered boxes false, Other text as the note). Never tick a decision they " +
138
+ "did not pick. Work starts only once it answers ready: true.";
139
+
124
140
  /** Every board tool's rules: the full toolset's `initialize` instructions. */
125
141
  export const BOARD_INSTRUCTIONS =
126
142
  INTRO +
@@ -132,9 +148,8 @@ export const BOARD_INSTRUCTIONS =
132
148
  STALE +
133
149
  HAND_OFF +
134
150
  WRITE_STREAMS +
135
- STREAMS_FLOW +
136
- " " +
137
- REVIEW_FLOW;
151
+ RUN_STREAMS +
152
+ REVIEW_SHORT;
138
153
 
139
154
  /**
140
155
  * The worker toolset's instructions (BE-24): only what a session working
@@ -150,4 +165,4 @@ export const BOARD_WORKER_INSTRUCTIONS =
150
165
  "its name. Do not start a card still in todo with decisions unticked. " +
151
166
  CHECKPOINT_FLOW +
152
167
  HAND_OFF +
153
- STREAMS_FLOW;
168
+ RUN_STREAMS.trimEnd();