@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.
Files changed (2) hide show
  1. package/README.md +220 -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,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 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 |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softpractice/softpractice-cli",
3
- "version": "0.1.6",
3
+ "version": "0.2.2",
4
4
  "description": "CLI for SoftPractice, an online platform for project-based programming practice",
5
5
  "license": "MIT",
6
6
  "author": "Arthur Sultanbekov",