@softpractice/softpractice-cli 0.1.6 → 0.2.2
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/README.md +220 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -42,25 +42,27 @@ Download the starter project for your current practicum:
|
|
|
42
42
|
softpractice starter
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Open the created directory and
|
|
45
|
+
Open the created directory, check the project state, and read the assignment:
|
|
46
46
|
|
|
47
47
|
```bash
|
|
48
48
|
cd <project-directory>
|
|
49
49
|
softpractice status
|
|
50
|
+
softpractice task
|
|
51
|
+
softpractice material
|
|
50
52
|
```
|
|
51
53
|
|
|
52
54
|
Work on the project and commit your changes with Git. When the solution is
|
|
53
|
-
ready, submit the current commit:
|
|
55
|
+
ready, submit the current commit and wait for the result:
|
|
54
56
|
|
|
55
57
|
```bash
|
|
56
|
-
softpractice submit
|
|
58
|
+
softpractice submit --wait
|
|
57
59
|
```
|
|
58
60
|
|
|
59
|
-
|
|
61
|
+
Read the result again at any time, or open it in the browser:
|
|
60
62
|
|
|
61
63
|
```bash
|
|
62
|
-
softpractice
|
|
63
|
-
softpractice open
|
|
64
|
+
softpractice result
|
|
65
|
+
softpractice open result
|
|
64
66
|
```
|
|
65
67
|
|
|
66
68
|
After an accepted solution, apply the transition to the next available lesson:
|
|
@@ -69,18 +71,28 @@ After an accepted solution, apply the transition to the next available lesson:
|
|
|
69
71
|
softpractice update
|
|
70
72
|
```
|
|
71
73
|
|
|
74
|
+
`softpractice status` always ends with the next step.
|
|
75
|
+
|
|
72
76
|
## Common commands
|
|
73
77
|
|
|
74
78
|
| Command | Description |
|
|
75
79
|
| --- | --- |
|
|
76
80
|
| `softpractice login` | Sign in through the browser |
|
|
77
81
|
| `softpractice starter` | Download the first lesson project |
|
|
78
|
-
| `softpractice status` | Show the
|
|
82
|
+
| `softpractice status` | Show the project state and the next step |
|
|
83
|
+
| `softpractice task` | Show the assignment |
|
|
84
|
+
| `softpractice material` | Show the theory material; `--lesson ID` for another lesson |
|
|
85
|
+
| `softpractice hint` | Show the hints you have opened; the next one is opened on the assignment page |
|
|
79
86
|
| `softpractice check` | Run public checks against the current working tree |
|
|
80
|
-
| `softpractice submit` | Submit the current committed Git revision |
|
|
81
|
-
| `softpractice
|
|
87
|
+
| `softpractice submit` | Submit the current committed Git revision; `--wait` waits for the result |
|
|
88
|
+
| `softpractice result` | Show the evaluation result; `--wait` waits for it, `--directions` adds the reviewer's recommendations |
|
|
89
|
+
| `softpractice submissions` | Show the recent submissions of the lesson |
|
|
82
90
|
| `softpractice update` | Apply the transition to the next lesson, or move to a newer version of the current lesson (replaces only lesson files, never yours; optional until the lesson ends) |
|
|
83
|
-
| `softpractice open` | Open the
|
|
91
|
+
| `softpractice open` | Open the task, material, or latest result in the browser |
|
|
92
|
+
| `softpractice mcp` | Run the MCP server for Claude Code, Codex, Claude Desktop, and other agents |
|
|
93
|
+
| `softpractice mcp setup codex-desktop` | Configure MCP for Codex Desktop without installing Codex CLI |
|
|
94
|
+
| `softpractice mcp status` | Check the running server and its project |
|
|
95
|
+
| `softpractice mcp remove codex-desktop` | Remove the connection from Codex settings |
|
|
84
96
|
| `softpractice project restore` | Restore a project from the latest usable revision |
|
|
85
97
|
|
|
86
98
|
Run `softpractice help <command>` for detailed help.
|
|
@@ -108,6 +120,204 @@ softpractice set auto-checks true
|
|
|
108
120
|
run. Unlike `softpractice check`, submission checks require a clean working
|
|
109
121
|
tree and run in an isolated snapshot of `HEAD`.
|
|
110
122
|
|
|
123
|
+
## Reviewer questions
|
|
124
|
+
|
|
125
|
+
When the reviewer asks questions about your solution, `softpractice result`
|
|
126
|
+
and `softpractice status` say so and give the link to the result page, where
|
|
127
|
+
you answer them.
|
|
128
|
+
|
|
129
|
+
## Machine-readable output
|
|
130
|
+
|
|
131
|
+
`status`, `task`, `material`, `hint`, `result`, `submissions`, and `submit`
|
|
132
|
+
accept `--json`. Each document has a `kind`; on an error the command prints a
|
|
133
|
+
`softpractice.error` document, also for an invalid command line (code
|
|
134
|
+
`usage`) and for a declined `submit` confirmation (code `declined`).
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
softpractice result --wait --timeout 10m --json
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Exit codes: `0` done, `1` error, `2` invalid arguments, `3` the evaluation is
|
|
141
|
+
not ready yet, `4` the evaluation was superseded and will have no result.
|
|
142
|
+
|
|
143
|
+
## Agent instructions
|
|
144
|
+
|
|
145
|
+
Every starter project already contains `AGENTS.md` and `CLAUDE.md` in its root
|
|
146
|
+
folder, so Codex, Claude Code, and other coding agents pick up the project
|
|
147
|
+
rules automatically. The files are tracked in Git, `softpractice update`
|
|
148
|
+
never replaces them, and they are not part of your submission.
|
|
149
|
+
|
|
150
|
+
## MCP server
|
|
151
|
+
|
|
152
|
+
`softpractice mcp` connects a coding agent to your SoftPractice lesson:
|
|
153
|
+
reading the task and material, running public checks, submitting a commit, and
|
|
154
|
+
reading the evaluation.
|
|
155
|
+
|
|
156
|
+
### Configure once, from any folder
|
|
157
|
+
|
|
158
|
+
Install the CLI (see [Install](#install)), then configure your desktop client.
|
|
159
|
+
You do not need a lesson project yet:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
softpractice mcp setup claude-desktop
|
|
163
|
+
# or
|
|
164
|
+
softpractice mcp setup codex-desktop
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Setup registers the CLI's absolute executable path and `mcp connect` as the
|
|
168
|
+
launch arguments. It preserves other settings and saves the previous file as
|
|
169
|
+
`.bak`. Claude Desktop uses `claude_desktop_config.json`; on Windows, setup
|
|
170
|
+
also finds the configuration used by the Microsoft Store version. Codex uses
|
|
171
|
+
`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and a tool timeout of
|
|
172
|
+
180 seconds. Codex Desktop, CLI, and the IDE extension share these settings.
|
|
173
|
+
No separate Codex CLI installation is needed for desktop setup.
|
|
174
|
+
|
|
175
|
+
For manual configuration, append `--print` to either setup command. It prints
|
|
176
|
+
the JSON or TOML entry without writing settings. Replace an existing
|
|
177
|
+
`softpractice` entry rather than adding a duplicate.
|
|
178
|
+
|
|
179
|
+
### Start the lesson server
|
|
180
|
+
|
|
181
|
+
Sign in, then start the server for a Git project downloaded with
|
|
182
|
+
`softpractice starter` or restored with `softpractice project restore`:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
softpractice login
|
|
186
|
+
cd /path/to/your/lesson-project
|
|
187
|
+
softpractice mcp
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Or start from any folder with an explicit project:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
softpractice mcp --project /path/to/your/lesson-project
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Keep this terminal open. The server validates the Git repository and
|
|
197
|
+
SoftPractice project link before accepting connections. It uses the CLI's
|
|
198
|
+
saved sign-in; it never opens a sign-in flow itself.
|
|
199
|
+
|
|
200
|
+
Start the server before restarting the desktop client. The client's stdio
|
|
201
|
+
bridge, `softpractice mcp connect`, forwards MCP messages to the running
|
|
202
|
+
server on `127.0.0.1:39473`. Connections require a random per-run key saved in
|
|
203
|
+
the CLI's user configuration folder. Both processes must run on the same
|
|
204
|
+
computer under the same user and use the same `SOFTPRACTICE_CONFIG_DIR` if
|
|
205
|
+
that environment variable is set. This address is not an HTTP URL.
|
|
206
|
+
|
|
207
|
+
Only one lesson server can run on this computer at a time. To switch projects,
|
|
208
|
+
stop it with Ctrl+C, start it in the other lesson folder, and reconnect the
|
|
209
|
+
client's MCP connection (or restart the client). Setup does not need to be
|
|
210
|
+
repeated. If the server is offline, the bridge prints the startup command to
|
|
211
|
+
stderr and exits; start the server and reconnect.
|
|
212
|
+
|
|
213
|
+
### Claude Code and Codex CLI
|
|
214
|
+
|
|
215
|
+
To use the same manually started server:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
claude mcp add --transport stdio --scope user softpractice -- softpractice mcp connect
|
|
219
|
+
# or, if Codex Desktop setup has not already configured it:
|
|
220
|
+
codex mcp add softpractice -- softpractice mcp connect
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
If the client cannot find `softpractice`, use the executable's full path.
|
|
224
|
+
See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
|
|
225
|
+
and [Codex MCP documentation](https://developers.openai.com/codex/mcp).
|
|
226
|
+
|
|
227
|
+
`softpractice mcp` always starts the local server, including with redirected
|
|
228
|
+
stdin or in the background. Only server startup selects the project. Setup
|
|
229
|
+
connects the client to the single running server and does not accept `--project`.
|
|
230
|
+
|
|
231
|
+
### Checking the server
|
|
232
|
+
|
|
233
|
+
From any folder, check which server is running:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
softpractice mcp status
|
|
237
|
+
softpractice mcp status --json
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The command checks a live connection and shows the lesson folder, PID,
|
|
241
|
+
local address, and CLI version. A stopped server returns `not_running`;
|
|
242
|
+
a key file left after a crash is not treated as proof of a running server.
|
|
243
|
+
No lesson project or sign-in is needed. This reports the local process;
|
|
244
|
+
lesson information remains available through `softpractice status` and the
|
|
245
|
+
MCP `status` tool.
|
|
246
|
+
|
|
247
|
+
### Stopping the server and removing the connection
|
|
248
|
+
|
|
249
|
+
Press Ctrl+C in the server's terminal to stop the lesson server. The client
|
|
250
|
+
configuration remains available for the next startup.
|
|
251
|
+
|
|
252
|
+
To remove the client connection, run from any folder:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
softpractice mcp remove claude-desktop
|
|
256
|
+
# or
|
|
257
|
+
softpractice mcp remove codex-desktop
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
This removes only the SoftPractice entry, preserves other settings, and saves
|
|
261
|
+
the previous file as `.bak`. Repeating the command is safe: missing entries
|
|
262
|
+
or files are left untouched. Restart the client to apply the change. Codex
|
|
263
|
+
shares these settings between Desktop, CLI, and the IDE extension; project
|
|
264
|
+
settings may override them.
|
|
265
|
+
|
|
266
|
+
Removing the connection does not stop the lesson server. To reconnect,
|
|
267
|
+
run the corresponding `softpractice mcp setup` command again.
|
|
268
|
+
|
|
269
|
+
### Using the server
|
|
270
|
+
|
|
271
|
+
The server exposes nine tools. Ask the agent in ordinary language; it chooses
|
|
272
|
+
the tool and passes structured arguments. These are MCP tool names, not slash
|
|
273
|
+
commands. See the [MCP usage guide](docs/mcp.md) for example requests, exact
|
|
274
|
+
parameters, the lesson workflow, and troubleshooting.
|
|
275
|
+
|
|
276
|
+
| Tool | What it does |
|
|
277
|
+
| --- | --- |
|
|
278
|
+
| `status` | Project state and `next_actions`, each naming the tool to call next or a page for you |
|
|
279
|
+
| `task` | The assignment of the lesson in this folder |
|
|
280
|
+
| `material` | The theory material; `lesson_id` for another lesson |
|
|
281
|
+
| `hints` | The hints you have already opened |
|
|
282
|
+
| `check` | Run the public checks on the working tree |
|
|
283
|
+
| `submit` | Submit the committed `HEAD`, after you confirm; `wait_seconds` waits for the result |
|
|
284
|
+
| `result` | The evaluation result; `wait_seconds` waits for it |
|
|
285
|
+
| `submissions` | The recent submissions of the lesson |
|
|
286
|
+
| `update` | Apply the lesson update, after you confirm the list of files it changes |
|
|
287
|
+
|
|
288
|
+
The task and the material are also available as the resources
|
|
289
|
+
`softpractice://lesson/task` and `softpractice://lesson/material`.
|
|
290
|
+
|
|
291
|
+
What the server leaves to you:
|
|
292
|
+
|
|
293
|
+
- `submit` and `update` ask you to confirm in the client, with the commit or
|
|
294
|
+
the list of files. If the client cannot ask (it does not support MCP
|
|
295
|
+
elicitation), they do nothing and return `confirmation_unavailable`; run
|
|
296
|
+
`softpractice submit` or `softpractice update` in a terminal instead.
|
|
297
|
+
- Results never include the reviewer's recommendations (`--directions`) or
|
|
298
|
+
the text of the reviewer's questions. You answer the questions on the result
|
|
299
|
+
page; the agent gets their number and the link.
|
|
300
|
+
- The agent sees only the hints you have opened; you open the next one on the
|
|
301
|
+
assignment page.
|
|
302
|
+
- `check` runs only the checks the server publishes for the lesson. If
|
|
303
|
+
`.softpractice/checks.json` differs, it returns `checks_not_published`:
|
|
304
|
+
review the commands and run `softpractice check` in a terminal.
|
|
305
|
+
- `login`, `logout`, `starter`, `project restore`, `set`, and `open` are not
|
|
306
|
+
available through MCP.
|
|
307
|
+
|
|
308
|
+
These limits apply to the MCP tools. An agent that can run shell commands can
|
|
309
|
+
also run the `softpractice` commands themselves.
|
|
310
|
+
|
|
311
|
+
Errors are tool results with `isError` and a JSON body
|
|
312
|
+
`{"error": {"code", "message", "action"}}`; `action` says what you have to do,
|
|
313
|
+
for example `login_required` asks you to run `softpractice login`.
|
|
314
|
+
|
|
315
|
+
Tool names and descriptions are in English, for the model. Messages meant for
|
|
316
|
+
you, such as the confirmation and error messages, use the CLI language (see
|
|
317
|
+
below); when no language is configured, the MCP server uses Russian, the
|
|
318
|
+
language of the course. To change it, set `SOFTPRACTICE_LANGUAGE` in the
|
|
319
|
+
server's `env` in the client configuration, or pass `--lang en` before `mcp`.
|
|
320
|
+
|
|
111
321
|
## Language
|
|
112
322
|
|
|
113
323
|
SoftPractice CLI supports English and Russian and selects a language from the
|
package/package.json
CHANGED