@smartspec/cli 0.1.2 → 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.
Files changed (2) hide show
  1. package/lib/server.json +150 -22
  2. package/package.json +1 -1
package/lib/server.json CHANGED
@@ -11,7 +11,7 @@
11
11
  "listChanged": true
12
12
  }
13
13
  },
14
- "instructions": "This server is SmartSpec: a desktop app holding the design of a system as schematics, for the user and for other agents to act on. It's about system design at any scale: a schematic can describe a whole business, one service, or one module inside a single application.\nA schematic has a name, a summary and a contract, which are what show when it's collapsed inside another schematic, so write them to stand on their own. The contract is its boundary: what it promises and what it needs.\nA schematic's design is a set of items, each of a kind: document (Markdown), flow (a diagram of nodes and connections), sequence (a diagram of participants and messages), table, or image. Use whichever explain it best, and as many as it needs. Diagrams are data, not a text language: the app lays them out and draws them. Give a description to anything in a diagram whose reason isn't obvious from its label, especially loops, alternatives and activations.\nItems link to each other, so a schematic is a connected graph. A link is an item's id, or item#part for a part inside it: a document's heading (as a slug), a flow's node or connection, a sequence's participant or message, or a table's row. In Markdown, write [text](item#part). Nodes, connections, participants, messages and rows can each have a link. Any item can list links too, which is the way to link from an image. A link can reach the contract, and the schematics this one embeds, but not inside them. Links that go nowhere are refused.\nSchematics embed other schematics: a standard structure, such as machine to machine auth, is one schematic, and shows as a single element in each schematic that uses it. Each use is pinned to a draft and can only set the parameters the embedded schematic declares. To change anything else, propose a new draft of that schematic, or a separate schematic.\nRead only what you need: get_schematic lists a schematic's items and links without their content, with its uses collapsed. Fetch an item with get_schematic_item when you need it, and open further levels by asking for them.\nA focus is what the user wants this work to be for: their prompt may say \"focusing on\" a goal. Keep to it, and pass it to propose_schematic as goal, with a short goal_title if you're given one or can name it, so the app can show it. If the user's prompt names a window, call use_window with it first, so that window becomes yours.\nOnly the user accepts what you propose: propose_schematic creates a proposal, and it becomes a draft once they accept it in the app. Send only what changes: the rest carries over. Tell the user straight away to switch to SmartSpec and review it. Each reply gives a wait command, a shell command that ends when they have answered: run it in the background if you can, or call get_schematic later to see where it stands. A schematic you embed must have an accepted draft, so wait for the acceptance before building on it.\nSchematics are organised into groups, such as a team, a department or a set like \"Auth\"; a schematic in none is Ungrouped. list_groups shows them. create_group, rename_group and move_schematic take effect straight away, so only use them when the user asks. A new schematic can go straight into a group with propose_schematic's group_id.\nThe user comments on what you propose, and on drafts: get_schematic and get_proposal say how many comments there are, and get_comments reads them, each on an item, a part of it or words they quoted. Answer each one with reply_to_comment, saying what you changed or why you didn't. A comment whose target has card: true is about the item's card, what shows for it around the schematic: answer it by changing the item's title, description or card lines. Comments on a proposal stay with it as you revise it.",
14
+ "instructions": "This server is SmartSpec: a desktop app holding the design of a system as schematics, for the user and for other agents to act on. It's about system design at any scale: a schematic can describe a whole business, one service, or one module inside a single application.\nA schematic has a name, a summary and a contract, which are what show when it's collapsed inside another schematic, so write them to stand on their own. The contract is its boundary: what it promises and what it needs.\nA schematic's design is a set of items, each of a kind: document (Markdown), flow (a diagram of nodes and connections), sequence (a diagram of participants and messages), table, or image. Use whichever explain it best, and as many as it needs. Diagrams are data, not a text language: the app lays them out and draws them. Give a description to anything in a diagram whose reason isn't obvious from its label, especially loops, alternatives and activations.\nItems link to each other, so a schematic is a connected graph. A link is an item's id, or item#part for a part inside it: a document's heading (as a slug), a flow's node or connection, a sequence's participant or message, or a table's row. In Markdown, write [text](item#part). Nodes, connections, participants, messages and rows can each have a link. Any item can list links too, which is the way to link from an image. A link can reach the contract, and the schematics this one embeds, but not inside them. Links that go nowhere are refused.\nSchematics embed other schematics: a standard structure, such as machine to machine auth, is one schematic, and shows as a single element in each schematic that uses it. Each use is pinned to a draft and can only set the parameters the embedded schematic declares. To change anything else, propose a new draft of that schematic, or a separate schematic.\nRead only what you need: get_schematic lists a schematic's items and links without their content, with its uses collapsed. Fetch an item with get_schematic_item when you need it, and open further levels by asking for them.\nA focus is what the user wants this work to be for: their prompt may say \"focusing on\" a goal. Keep to it, and pass it to propose_schematic as goal, with a short goal_title if you're given one or can name it, so the app can show it. If the user's prompt names a window, call use_window with it first, so that window becomes yours.\nOnly the user accepts what you propose: propose_schematic creates a proposal, and it becomes a draft once they accept it in the app. Send only what changes: the rest carries over. Tell the user straight away to switch to SmartSpec and review it. Each reply gives a wait command, a shell command that ends when they have answered: run it in the background if you can, or call get_schematic later to see where it stands. A schematic you embed must have an accepted draft, so wait for the acceptance before building on it.\nSchematics belong to domains: a domain is a set of schematics owned by one team or one department, such as \"Auth\". A schematic in none is in No domain. Domains are organised in folders, which nest, so they can follow the organisation (a department's folder holding its teams'). list_domains and list_folders show them. create_domain, rename_domain, move_schematic, create_folder, rename_folder and move_domain take effect straight away, so only use them when the user asks. A new schematic can go straight into a domain with propose_schematic's domain_id.\nThe user comments on what you propose, and on drafts: get_schematic and get_proposal say how many are open, and get_comments reads them, each on the whole schematic (schematic: true), an item, a part of it, a point in it or words they quoted. Answer each one with reply_to_comment: say what you changed or why you didn't, and give its outcome, how you dealt with it in a word or two of your own (\"Actioned\", \"Noted\", \"Answered\", \"Not changed\"). Some comments only need reading. When nothing more is needed, set no_further_action: the comment then folds away and get_comments leaves it out. The user can set or clear that too, so one that comes back open needs another look. A comment whose target has card: true is about the item's card, what shows for it around the schematic: answer it by changing the item's title, description or card lines. One with point is about that place in the item: read the item to see what's there. One on the whole schematic is about all of it, or anything not in one item. Comments on a proposal stay with it as you revise it.",
15
15
  "tools": [
16
16
  {
17
17
  "name": "use_window",
@@ -40,7 +40,7 @@
40
40
  },
41
41
  {
42
42
  "name": "list_schematics",
43
- "description": "Every schematic, most recently changed first: its id, name, summary, number of accepted drafts, status, the group it's in (null for Ungrouped), and any proposal waiting for the user.",
43
+ "description": "Every schematic, most recently changed first: its id, name, summary, number of accepted drafts, status, the domain it's in (null for No domain), and any proposal waiting for the user.",
44
44
  "inputSchema": {
45
45
  "type": "object",
46
46
  "properties": {},
@@ -56,8 +56,8 @@
56
56
  }
57
57
  },
58
58
  {
59
- "name": "list_groups",
60
- "description": "The groups schematics are organised into, by name: each with its id, name and how many schematics are in it, and how many schematics are Ungrouped.",
59
+ "name": "list_domains",
60
+ "description": "The domains schematics belong to, by name: each with its id, name, how many schematics are in it and the folder it's in (null for the top level, with the folder's path), and how many schematics are in No domain.",
61
61
  "inputSchema": {
62
62
  "type": "object",
63
63
  "properties": {},
@@ -73,8 +73,8 @@
73
73
  }
74
74
  },
75
75
  {
76
- "name": "create_group",
77
- "description": "Makes a group to organise schematics into, such as a team, a department or a set like \"Auth\", straight away. Only use it when the user asks.",
76
+ "name": "create_domain",
77
+ "description": "Makes a domain, a set of schematics owned by one team or one department, such as \"Auth\", straight away: at the top level or in a folder. Only use it when the user asks.",
78
78
  "inputSchema": {
79
79
  "type": "object",
80
80
  "properties": {
@@ -82,6 +82,10 @@
82
82
  "type": "string",
83
83
  "minLength": 1,
84
84
  "maxLength": 80
85
+ },
86
+ "folder_id": {
87
+ "description": "The folder to put it in, from list_folders (default: the top level)",
88
+ "type": "string"
85
89
  }
86
90
  },
87
91
  "required": [
@@ -99,14 +103,14 @@
99
103
  }
100
104
  },
101
105
  {
102
- "name": "rename_group",
103
- "description": "Renames a group, straight away. Only use it when the user asks.",
106
+ "name": "rename_domain",
107
+ "description": "Renames a domain, straight away. Only use it when the user asks.",
104
108
  "inputSchema": {
105
109
  "type": "object",
106
110
  "properties": {
107
- "group_id": {
111
+ "domain_id": {
108
112
  "type": "string",
109
- "description": "From list_groups"
113
+ "description": "From list_domains"
110
114
  },
111
115
  "name": {
112
116
  "type": "string",
@@ -115,7 +119,7 @@
115
119
  }
116
120
  },
117
121
  "required": [
118
- "group_id",
122
+ "domain_id",
119
123
  "name"
120
124
  ],
121
125
  "$schema": "http://json-schema.org/draft-07/schema#"
@@ -131,15 +135,15 @@
131
135
  },
132
136
  {
133
137
  "name": "move_schematic",
134
- "description": "Puts a schematic in a group, or back in Ungrouped, straight away. Only its place on the list changes: its drafts stay as they are. Only use it when the user asks.",
138
+ "description": "Puts a schematic in a domain, or in No domain, straight away. Only its place on the list changes: its drafts stay as they are. Only use it when the user asks.",
135
139
  "inputSchema": {
136
140
  "type": "object",
137
141
  "properties": {
138
142
  "schematic_id": {
139
143
  "type": "string"
140
144
  },
141
- "group_id": {
142
- "description": "From list_groups, or null for Ungrouped",
145
+ "domain_id": {
146
+ "description": "From list_domains, or null for No domain",
143
147
  "type": [
144
148
  "string",
145
149
  "null"
@@ -148,7 +152,118 @@
148
152
  },
149
153
  "required": [
150
154
  "schematic_id",
151
- "group_id"
155
+ "domain_id"
156
+ ],
157
+ "$schema": "http://json-schema.org/draft-07/schema#"
158
+ },
159
+ "annotations": {
160
+ "readOnlyHint": false,
161
+ "destructiveHint": false,
162
+ "openWorldHint": false
163
+ },
164
+ "execution": {
165
+ "taskSupport": "forbidden"
166
+ }
167
+ },
168
+ {
169
+ "name": "list_folders",
170
+ "description": "The folders organising the domains in the app: each with its id, name, path and how many folders and domains are directly in it.",
171
+ "inputSchema": {
172
+ "type": "object",
173
+ "properties": {},
174
+ "$schema": "http://json-schema.org/draft-07/schema#"
175
+ },
176
+ "annotations": {
177
+ "readOnlyHint": true,
178
+ "destructiveHint": false,
179
+ "openWorldHint": false
180
+ },
181
+ "execution": {
182
+ "taskSupport": "forbidden"
183
+ }
184
+ },
185
+ {
186
+ "name": "create_folder",
187
+ "description": "Makes a folder to organise domains in, at the top level or inside another, straight away. Only use it when the user asks.",
188
+ "inputSchema": {
189
+ "type": "object",
190
+ "properties": {
191
+ "name": {
192
+ "type": "string",
193
+ "minLength": 1,
194
+ "maxLength": 80
195
+ },
196
+ "parent_folder_id": {
197
+ "description": "The folder to put it in, from list_folders (default: the top level)",
198
+ "type": "string"
199
+ }
200
+ },
201
+ "required": [
202
+ "name"
203
+ ],
204
+ "$schema": "http://json-schema.org/draft-07/schema#"
205
+ },
206
+ "annotations": {
207
+ "readOnlyHint": false,
208
+ "destructiveHint": false,
209
+ "openWorldHint": false
210
+ },
211
+ "execution": {
212
+ "taskSupport": "forbidden"
213
+ }
214
+ },
215
+ {
216
+ "name": "rename_folder",
217
+ "description": "Renames a folder, straight away. Only use it when the user asks.",
218
+ "inputSchema": {
219
+ "type": "object",
220
+ "properties": {
221
+ "folder_id": {
222
+ "type": "string",
223
+ "description": "From list_folders"
224
+ },
225
+ "name": {
226
+ "type": "string",
227
+ "minLength": 1,
228
+ "maxLength": 80
229
+ }
230
+ },
231
+ "required": [
232
+ "folder_id",
233
+ "name"
234
+ ],
235
+ "$schema": "http://json-schema.org/draft-07/schema#"
236
+ },
237
+ "annotations": {
238
+ "readOnlyHint": false,
239
+ "destructiveHint": false,
240
+ "openWorldHint": false
241
+ },
242
+ "execution": {
243
+ "taskSupport": "forbidden"
244
+ }
245
+ },
246
+ {
247
+ "name": "move_domain",
248
+ "description": "Moves a domain into a folder, or back to the top level, straight away. Only its place on the list changes: its schematics stay as they are. Only use it when the user asks.",
249
+ "inputSchema": {
250
+ "type": "object",
251
+ "properties": {
252
+ "domain_id": {
253
+ "type": "string",
254
+ "description": "From list_domains"
255
+ },
256
+ "folder_id": {
257
+ "description": "The folder, from list_folders, or null for the top level",
258
+ "type": [
259
+ "string",
260
+ "null"
261
+ ]
262
+ }
263
+ },
264
+ "required": [
265
+ "domain_id",
266
+ "folder_id"
152
267
  ],
153
268
  "$schema": "http://json-schema.org/draft-07/schema#"
154
269
  },
@@ -263,7 +378,7 @@
263
378
  },
264
379
  {
265
380
  "name": "get_comments",
266
- "description": "The user's comments on a schematic's draft (the latest unless you name one) or on the proposal waiting on it, oldest first. Each says what it's on (target: the item and its title, the part and its name, any words the user quoted, or card: true for the item's card; missing or partMissing if that's no longer there), what the user said, and the replies so far.",
381
+ "description": "The user's open comments on a schematic's draft (the latest unless you name one) or on the proposal waiting on it, oldest first: those not marked \"No further action required\", unless you ask for all. Each says what it's on (target: schematic: true for the schematic as a whole; else the item and its title, with the part and its name, any words the user quoted, a point in the item's content (point: x and y as fractions of it, the item as a whole being the context), or card: true for the item's card; missing or partMissing if that's no longer there), what the user said, the replies so far, its outcome (how it was last dealt with) and noFurtherAction (who marked it so, and when).",
267
382
  "inputSchema": {
268
383
  "type": "object",
269
384
  "properties": {
@@ -277,6 +392,10 @@
277
392
  "proposal": {
278
393
  "description": "Read the comments on the proposal waiting on the schematic instead",
279
394
  "type": "boolean"
395
+ },
396
+ "all": {
397
+ "description": "Include the comments marked \"No further action required\"",
398
+ "type": "boolean"
280
399
  }
281
400
  },
282
401
  "required": [
@@ -295,7 +414,7 @@
295
414
  },
296
415
  {
297
416
  "name": "reply_to_comment",
298
- "description": "Answers one of the user's comments, shown under it in the app: say what you changed, or why you didn't. A comment can have several replies, so reply again after a further revision.",
417
+ "description": "Answers one of the user's comments, shown under it in the app: say what you changed, or why you didn't, and how you dealt with it. Give text, an outcome, or both. A comment can have several replies, so reply again after a further revision.",
299
418
  "inputSchema": {
300
419
  "type": "object",
301
420
  "properties": {
@@ -306,15 +425,24 @@
306
425
  "type": "string"
307
426
  },
308
427
  "text": {
428
+ "description": "Your reply, in a sentence or two. Can be left out when the outcome says it all, such as \"Noted\"",
429
+ "type": "string",
430
+ "minLength": 1
431
+ },
432
+ "outcome": {
433
+ "description": "How you dealt with it, in a word or two of your own, shown as a tag on the comment: such as \"Actioned\", \"Noted\", \"Answered\", \"Partly done\" or \"Not changed\"",
309
434
  "type": "string",
310
435
  "minLength": 1,
311
- "description": "Your reply, in a sentence or two"
436
+ "maxLength": 40
437
+ },
438
+ "no_further_action": {
439
+ "description": "True when nothing more is needed on it (a comment that only needed reading, or one you've fully dealt with): it folds away and get_comments leaves it out. False takes that back. Leave it out to keep it as it is",
440
+ "type": "boolean"
312
441
  }
313
442
  },
314
443
  "required": [
315
444
  "schematic_id",
316
- "comment_id",
317
- "text"
445
+ "comment_id"
318
446
  ],
319
447
  "$schema": "http://json-schema.org/draft-07/schema#"
320
448
  },
@@ -1026,8 +1154,8 @@
1026
1154
  ]
1027
1155
  }
1028
1156
  },
1029
- "group_id": {
1030
- "description": "For a new schematic: the group to put it in, from list_groups (default: Ungrouped)",
1157
+ "domain_id": {
1158
+ "description": "For a new schematic: the domain to put it in, from list_domains (default: No domain)",
1031
1159
  "type": "string"
1032
1160
  },
1033
1161
  "goal": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@smartspec/cli",
3
- "version": "0.1.2",
3
+ "version": "0.3.0",
4
4
  "description": "The smartspec command: installs the SmartSpec app, sets up Claude Desktop and Claude Code to use it, checks the connection, and runs SmartSpec's MCP connection for agents set up with npx.",
5
5
  "license": "MIT",
6
6
  "type": "module",