@softpractice/softpractice-cli 0.1.6 → 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.
Files changed (2) hide show
  1. package/README.md +226 -10
  2. 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 check the current lesson:
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
- Check the submission and open its result:
61
+ Read the result again at any time, or open it in the browser:
60
62
 
61
63
  ```bash
62
- softpractice submission show
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 current lesson and local project state |
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 submission show` | Show the latest submission and review result |
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 workspace or latest result in the browser |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softpractice/softpractice-cli",
3
- "version": "0.1.6",
3
+ "version": "0.2.1",
4
4
  "description": "CLI for SoftPractice, an online platform for project-based programming practice",
5
5
  "license": "MIT",
6
6
  "author": "Arthur Sultanbekov",