From 56f17f199ee2bc0a77e090c43dd367f43c909f2c Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 08:28:04 +0000 Subject: docs(plugin): explain terminal execution and verification Co-Authored-By: Claude Fable 5.1 --- plugin/AGENTS/ARCH.md | 29 ++++++++++++++++++++++++++++- plugin/AGENTS/DEVELOPMENT.md | 11 ++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) (limited to 'plugin/AGENTS') diff --git a/plugin/AGENTS/ARCH.md b/plugin/AGENTS/ARCH.md index 3199457..1a1c076 100644 --- a/plugin/AGENTS/ARCH.md +++ b/plugin/AGENTS/ARCH.md @@ -2,7 +2,8 @@ The extension registers `cie-pseudocode` for `.cps` files. It targets VS Code 1.85+ and dark themes. Runtime code uses CommonJS JavaScript and the VS Code API, with -no npm runtime dependencies or connection to the compiler or cpptools. +no npm runtime dependencies. Running files invokes the installed `cpsc` executable; +there is no compiler library or cpptools integration. ## Native editor capabilities and upstream references @@ -17,6 +18,9 @@ no npm runtime dependencies or connection to the compiler or cpptools. server are not called, imported or bundled. This extension is not a cpptools fork. The formatting API accepts locally computed edits; it does not implement CIE indentation itself. +- `src/runner.js` adapts Code Runner's terminal creation, display, reuse, close + handling and Windows shell detection. The editor title button uses the same + native `$(play)` icon. Upstream revision and notice are in `ThirdPartyNotices.md`. Native `indentationRules` and `onEnterRules` are not currently configured. The on-type provider uses the same custom block-depth engine as selection formatting. @@ -42,6 +46,29 @@ Source attribution is retained in `ThirdPartyNotices.md`. - `src/brackets.js` uses a stack to report unmatched opening and closing brackets and crossed types. Only invalid brackets receive the red decoration; native bracket coloring handles valid pairs. +- `src/runner.js` registers `cie-pseudocode.runFile`. It saves the target document, + uses the new file URI after an untitled save, ignores selections and runs + `cpsc file -r` in a focused, reusable terminal. Only that terminal's close event + clears the cached terminal; extension disposal closes it. + +## Terminal execution + +`cie-pseudocode.compilerPath` is a resource-scoped executable name or full path, +defaulting to `cpsc`. Read it for the saved file. The working directory is that +file's workspace folder, falling back to its containing directory. + +Unix commands use POSIX single-quote escaping and `cd ... && ...`. Windows +PowerShell uses literal paths, doubled single quotes, `if ($?)` and the `&` call +operator. Command Prompt uses quoted paths, `cd /d` and `&&`. Windows detection +adapts Code Runner's default-profile logic and also recognizes `pwsh` and custom +profile paths. Cache the shell kind with the terminal, since changing the default +profile does not change an existing terminal. Windows bash profiles and non-POSIX +Unix shells are outside the supported terminal set. + +Save cancellation starts nothing. Save or terminal setup failures show an English +error message; compiler and program diagnostics go directly to the terminal. +Terminal execution follows Code Runner's reuse behavior: users must finish or +interrupt an interactive program with Ctrl+C before running another file. ## Language rules and defaults diff --git a/plugin/AGENTS/DEVELOPMENT.md b/plugin/AGENTS/DEVELOPMENT.md index 6a7da98..be4dbe7 100644 --- a/plugin/AGENTS/DEVELOPMENT.md +++ b/plugin/AGENTS/DEVELOPMENT.md @@ -24,7 +24,8 @@ instructions. Do not introduce a complex test framework for routine changes. ## Verification The existing tests check real TextMate tokenization, nested block indentation, -selection context, idempotence and bracket errors. Keep Unicode offset tests, +selection context, idempotence, bracket errors, terminal command quoting, +save cancellation and terminal lifecycle. Keep Unicode offset tests, using English text and non-CJK characters such as an emoji. For changes to editor integration, check in VS Code with a dark theme: @@ -34,6 +35,14 @@ For changes to editor integration, check in VS Code with a dark theme: - Format a selection inside a nested block and check its surrounding context. - Check mixed bracket nesting, unmatched left/right brackets, quotes and comments. - Repair errors and switch language or files to check decoration cleanup. +- Click the run button on `.cps`; confirm it is absent on other languages. +- Run `OUTPUT` and `INPUT`, including paths with spaces and unsaved changes. +- Read a relative file from the workspace root, then run without a workspace. +- Close the run terminal and run again to check recreation. + +Terminal commands have been exercised in isolated VS Code 1.85.2 on Linux +with bash and zsh. Windows PowerShell/cmd command construction is covered by +Node tests; native Windows and macOS execution still needs testing there. Existing local editor smoke scripts, if present, live under the ignored `reference/vscode-smoke/` directory. They are not a required build dependency. -- cgit v1.3.1-4-g156e