@softpractice/softpractice-cli 0.1.5 → 0.2.1
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 +227 -11
- 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,26 @@ 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
|
|
82
|
-
| `softpractice
|
|
83
|
-
| `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 |
|
|
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) |
|
|
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 |
|
|
84
94
|
| `softpractice project restore` | Restore a project from the latest usable revision |
|
|
85
95
|
|
|
86
96
|
Run `softpractice help <command>` for detailed help.
|
|
@@ -108,6 +118,212 @@ softpractice set auto-checks true
|
|
|
108
118
|
run. Unlike `softpractice check`, submission checks require a clean working
|
|
109
119
|
tree and run in an isolated snapshot of `HEAD`.
|
|
110
120
|
|
|
121
|
+
## Reviewer questions
|
|
122
|
+
|
|
123
|
+
When the reviewer asks questions about your solution, `softpractice result`
|
|
124
|
+
and `softpractice status` say so and give the link to the result page, where
|
|
125
|
+
you answer them.
|
|
126
|
+
|
|
127
|
+
## Machine-readable output
|
|
128
|
+
|
|
129
|
+
`status`, `task`, `material`, `hint`, `result`, `submissions`, and `submit`
|
|
130
|
+
accept `--json`. Each document has a `kind`; on an error the command prints a
|
|
131
|
+
`softpractice.error` document, also for an invalid command line (code
|
|
132
|
+
`usage`) and for a declined `submit` confirmation (code `declined`).
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
softpractice result --wait --timeout 10m --json
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Exit codes: `0` done, `1` error, `2` invalid arguments, `3` the evaluation is
|
|
139
|
+
not ready yet, `4` the evaluation was superseded and will have no result.
|
|
140
|
+
|
|
141
|
+
## Agent instructions
|
|
142
|
+
|
|
143
|
+
Every starter project already contains `AGENTS.md` and `CLAUDE.md` in its root
|
|
144
|
+
folder, so Codex, Claude Code, and other coding agents pick up the project
|
|
145
|
+
rules automatically. The files are tracked in Git, `softpractice update`
|
|
146
|
+
never replaces them, and they are not part of your submission.
|
|
147
|
+
|
|
148
|
+
## MCP server
|
|
149
|
+
|
|
150
|
+
`softpractice mcp` connects a coding agent to your SoftPractice lesson:
|
|
151
|
+
reading the task and material, running public checks, submitting a commit, and
|
|
152
|
+
reading the evaluation. It is a local **stdio** MCP server: your MCP client
|
|
153
|
+
starts the process and communicates with it. No server URL or listening port
|
|
154
|
+
is needed.
|
|
155
|
+
|
|
156
|
+
### Before connecting
|
|
157
|
+
|
|
158
|
+
Install the CLI (see [Install](#install)), sign in, and open an existing lesson
|
|
159
|
+
Git project, downloaded with `softpractice starter` or restored with
|
|
160
|
+
`softpractice project restore`:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
softpractice login
|
|
164
|
+
cd /path/to/your/lesson-project
|
|
165
|
+
softpractice status
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
The MCP server uses the CLI's saved sign-in. It never starts a sign-in itself;
|
|
169
|
+
there is no separate MCP OAuth login. Configure the launch command
|
|
170
|
+
`softpractice mcp` in your client. The client starts it for you, so you do not
|
|
171
|
+
need to leave it running in a terminal.
|
|
172
|
+
|
|
173
|
+
By default it works in the directory where the client starts it. Use
|
|
174
|
+
`--project /absolute/path/to/your/lesson-project` to pin the folder, especially
|
|
175
|
+
for desktop clients. When switching projects, change that path. If the client
|
|
176
|
+
cannot find `softpractice` on `PATH`, use the executable's full path as the
|
|
177
|
+
command. The client must run on the computer where the CLI and project exist.
|
|
178
|
+
|
|
179
|
+
### Claude Desktop
|
|
180
|
+
|
|
181
|
+
From the lesson project folder:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
softpractice mcp setup claude-desktop
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The command adds the `softpractice` server to the Claude Desktop settings
|
|
188
|
+
file, `claude_desktop_config.json`, with absolute paths to the program and the
|
|
189
|
+
project: Claude Desktop does not see the `PATH` from your terminal profile and
|
|
190
|
+
does not start the server in your project folder. Other servers and app
|
|
191
|
+
settings in the file are kept; the previous file is saved next to it as
|
|
192
|
+
`claude_desktop_config.json.bak`. On Windows, the command also finds the file
|
|
193
|
+
that the Microsoft Store version of the app actually reads.
|
|
194
|
+
|
|
195
|
+
Then quit Claude Desktop completely, not just its window, and start it again.
|
|
196
|
+
The `softpractice` tools appear in the chat's tools menu. When you switch to
|
|
197
|
+
another lesson project, run the command again in its folder.
|
|
198
|
+
|
|
199
|
+
To configure the app manually, print the entry and add it to `mcpServers` in
|
|
200
|
+
the file opened by **Settings → Developer → Edit Config**, keeping the servers
|
|
201
|
+
already configured:
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
softpractice mcp setup claude-desktop --print
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Claude Code
|
|
208
|
+
|
|
209
|
+
From the lesson project folder:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
claude mcp add --transport stdio --scope local softpractice -- softpractice mcp
|
|
213
|
+
claude mcp list
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
This registration is private to you and applies to this project. Start Claude
|
|
217
|
+
Code in the same folder; use `/mcp` to check the connection. See the
|
|
218
|
+
[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
|
|
219
|
+
|
|
220
|
+
### Codex Desktop
|
|
221
|
+
|
|
222
|
+
From the lesson project folder:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
softpractice mcp setup codex-desktop
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
You do not need to install Codex CLI. The command adds the `softpractice`
|
|
229
|
+
server to `~/.codex/config.toml` with absolute paths to the program and project
|
|
230
|
+
and a tool timeout of 180 seconds. If `CODEX_HOME` is set, it uses
|
|
231
|
+
`config.toml` in that folder. Other settings, servers, and their comments
|
|
232
|
+
are kept; the previous file is saved next to it as `config.toml.bak`.
|
|
233
|
+
Running setup again for the same project leaves the file unchanged.
|
|
234
|
+
|
|
235
|
+
Restart Codex Desktop, open the lesson project folder, and check the
|
|
236
|
+
`softpractice` server in the MCP settings. Ask the agent: “Use the
|
|
237
|
+
SoftPractice MCP server to show my lesson status and current task.” It
|
|
238
|
+
should call `status` and `task`. When switching to another lesson project,
|
|
239
|
+
run the command again in its folder or pass
|
|
240
|
+
`--project /absolute/path/to/your/lesson-project`.
|
|
241
|
+
|
|
242
|
+
To configure the app manually, print the TOML entry:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
softpractice mcp setup codex-desktop --print
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Add it to `config.toml`, keeping the servers already configured. If
|
|
249
|
+
`[mcp_servers.softpractice]` already exists, replace that table instead of
|
|
250
|
+
adding a duplicate. Codex Desktop, CLI, and the IDE extension share these
|
|
251
|
+
settings on the same host. Setup pins one project to the `softpractice`
|
|
252
|
+
server for all these clients. A trusted project's `.codex/config.toml` can
|
|
253
|
+
override user-level settings. See the
|
|
254
|
+
[official Codex MCP documentation](https://developers.openai.com/codex/mcp).
|
|
255
|
+
|
|
256
|
+
### Codex CLI
|
|
257
|
+
|
|
258
|
+
If you already configured Codex Desktop with the command above, no further
|
|
259
|
+
registration is needed. Start `codex` in the lesson folder; `/mcp` shows
|
|
260
|
+
active servers.
|
|
261
|
+
|
|
262
|
+
To configure using Codex CLI, replace the project path:
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
codex mcp add softpractice -- softpractice mcp --project /path/to/your/lesson-project
|
|
266
|
+
codex mcp list
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
For local checks and evaluation polling, add `tool_timeout_sec = 180` to
|
|
270
|
+
the generated `[mcp_servers.softpractice]` table in `~/.codex/config.toml`.
|
|
271
|
+
If the client cannot find `softpractice`, use the executable's full path.
|
|
272
|
+
You can also use `softpractice mcp setup codex-desktop`: it configures the
|
|
273
|
+
same file.
|
|
274
|
+
|
|
275
|
+
### Using the server
|
|
276
|
+
|
|
277
|
+
The server exposes nine tools. Ask the agent in ordinary language; it chooses
|
|
278
|
+
the tool and passes structured arguments. These are MCP tool names, not slash
|
|
279
|
+
commands. See the [MCP usage guide](docs/mcp.md) for example requests, exact
|
|
280
|
+
parameters, the lesson workflow, and troubleshooting.
|
|
281
|
+
|
|
282
|
+
| Tool | What it does |
|
|
283
|
+
| --- | --- |
|
|
284
|
+
| `status` | Project state and `next_actions`, each naming the tool to call next or a page for you |
|
|
285
|
+
| `task` | The assignment of the lesson in this folder |
|
|
286
|
+
| `material` | The theory material; `lesson_id` for another lesson |
|
|
287
|
+
| `hints` | The hints you have already opened |
|
|
288
|
+
| `check` | Run the public checks on the working tree |
|
|
289
|
+
| `submit` | Submit the committed `HEAD`, after you confirm; `wait_seconds` waits for the result |
|
|
290
|
+
| `result` | The evaluation result; `wait_seconds` waits for it |
|
|
291
|
+
| `submissions` | The recent submissions of the lesson |
|
|
292
|
+
| `update` | Apply the lesson update, after you confirm the list of files it changes |
|
|
293
|
+
|
|
294
|
+
The task and the material are also available as the resources
|
|
295
|
+
`softpractice://lesson/task` and `softpractice://lesson/material`.
|
|
296
|
+
|
|
297
|
+
What the server leaves to you:
|
|
298
|
+
|
|
299
|
+
- `submit` and `update` ask you to confirm in the client, with the commit or
|
|
300
|
+
the list of files. If the client cannot ask (it does not support MCP
|
|
301
|
+
elicitation), they do nothing and return `confirmation_unavailable`; run
|
|
302
|
+
`softpractice submit` or `softpractice update` in a terminal instead.
|
|
303
|
+
- Results never include the reviewer's recommendations (`--directions`) or
|
|
304
|
+
the text of the reviewer's questions. You answer the questions on the result
|
|
305
|
+
page; the agent gets their number and the link.
|
|
306
|
+
- The agent sees only the hints you have opened; you open the next one on the
|
|
307
|
+
assignment page.
|
|
308
|
+
- `check` runs only the checks the server publishes for the lesson. If
|
|
309
|
+
`.softpractice/checks.json` differs, it returns `checks_not_published`:
|
|
310
|
+
review the commands and run `softpractice check` in a terminal.
|
|
311
|
+
- `login`, `logout`, `starter`, `project restore`, `set`, and `open` are not
|
|
312
|
+
available through MCP.
|
|
313
|
+
|
|
314
|
+
These limits apply to the MCP tools. An agent that can run shell commands can
|
|
315
|
+
also run the `softpractice` commands themselves.
|
|
316
|
+
|
|
317
|
+
Errors are tool results with `isError` and a JSON body
|
|
318
|
+
`{"error": {"code", "message", "action"}}`; `action` says what you have to do,
|
|
319
|
+
for example `login_required` asks you to run `softpractice login`.
|
|
320
|
+
|
|
321
|
+
Tool names and descriptions are in English, for the model. Messages meant for
|
|
322
|
+
you, such as the confirmation and error messages, use the CLI language (see
|
|
323
|
+
below); when no language is configured, the MCP server uses Russian, the
|
|
324
|
+
language of the course. To change it, set `SOFTPRACTICE_LANGUAGE` in the
|
|
325
|
+
server's `env` in the client configuration, or pass `--lang en` before `mcp`.
|
|
326
|
+
|
|
111
327
|
## Language
|
|
112
328
|
|
|
113
329
|
SoftPractice CLI supports English and Russian and selects a language from the
|
package/package.json
CHANGED