msdev 0.10.0__tar.gz → 0.11.0__tar.gz

{msdev-0.10.0 → msdev-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msdev
-Version: 0.10.0
+Version: 0.11.0
 Summary: Portable nodes and execution environments for msModelSlim development
 Author: msModelSlim Agent Contributors
 License-Expression: MulanPSL-2.0
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.10
@@ -32,7 +33,6 @@ The CLI is intentionally stateless:
 
 - Node-scoped NPU/model operations name `--node` or use `--all`;
 - execution names `--env`;
-- every workspace operation names the registered workspace;
 - no harness conversation binding or implicit current Env exists;
 - MCP is not part of the architecture.
 
@@ -47,6 +47,40 @@ msdev --help
 
 The package installs `msdev` and `msdevd`.
 
+## Windows client
+
+The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
+(`C:\Windows\System32\OpenSSH\ssh.exe`). Native Windows OpenSSH does not
+implement ControlMaster multiplexing, so msdev:
+
+- omits `ControlMaster`/`ControlPath` on Windows (override with
+  `MSDEV_SSH_CONTROL_MASTER=1` only if your SSH client actually supports mux);
+- starts a persistent `ssh -L` LocalForward tunnel automatically on the first
+  RPC (same role as ControlMaster). Explicit `msdev node connect NODE` is
+  optional; disable persist with `MSDEV_SSH_LOCAL_FORWARD_PERSIST=0`;
+- reuses that tunnel for captured RPC and default streaming `msdev exec`;
+  `env put`/`get` stay on scp/ssh streams (file bytes do not go through JSON RPC);
+- hides SSH console windows (`CREATE_NO_WINDOW`) and kills process trees with
+  `taskkill /T` on timeout or cancel;
+- SSH is non-interactive: `BatchMode` unless a password is supplied, host keys
+  use `accept-new`, and there is no password/passphrase/yes-no prompt. When a
+  password is known, injects OpenSSH `SSH_ASKPASS` so `node connect` (and later
+  ssh/scp) can authenticate without a TTY; the local public key is then
+  installed on the Node so later logins are passwordless. The password is
+  never written to the node registry;
+- serves a TCP loopback endpoint for local `msdevd` when this Python build has
+  no `AF_UNIX` sockets.
+
+Install with `python -m pip install -e .`. `install-user.py` writes
+`msdev.cmd` / `msdevd.cmd` under `%USERPROFILE%\.local\bin`.
+
+Remote paths inside a Linux Env remain POSIX (`/srv/...`). Local `env put`/`get`
+on Windows accept Windows absolute paths (`C:\...`).
+
+Local `exec` on Windows wraps Conda with `conda run` and venvs with
+`Scripts\activate.bat` (remote Linux Nodes still use POSIX `sh`/`bash` wrappers).
+If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
+
 ## Nodes and execution environments
 
 Register a host from `~/.ssh/config`:
@@ -64,10 +98,23 @@ the remote user daemon:
 msdev node bootstrap dev-122
 ```
 
-Persistent OpenSSH masters are optional:
+Persistent OpenSSH masters are optional. All SSH from msdev is
+non-interactive: host keys use `accept-new`, and password/passphrase prompts
+are disabled. Supply a password via environment or file (never a prompt);
+connect then installs the local public key (`~/.ssh/id_ed25519`, generated
+if missing) so later connections are passwordless:
 
 ```bash
+# Environment (also used by exec / env put after connect if persist is off)
+export MSDEV_SSH_PASSWORD='...'
+export MSDEV_SSH_PASSWORD_DEV_122='...'   # per-node override
+
 msdev node connect dev-122
+msdev node connect dev-122 --password-file FILE
+msdev node connect dev-122 --password-env VAR
+msdev node connect dev-122 --password PASSWORD   # non-interactive; visible in ps
+msdev node connect dev-122 --identity FILE     # choose which key to install
+msdev node connect dev-122 --no-install-key    # password only, do not copy key
 msdev node disconnect dev-122
 ```
 
@@ -107,6 +154,33 @@ msdev env add dev-122-vllm \
   --layer venv:/srv/project/.venv
 ```
 
+## File put, get, read, and write
+
+Bulk transfer copies a local file into an Env filesystem, or fetches one back:
+
+```bash
+msdev env put dev-122 ./config.yaml /srv/project/config.yaml
+msdev env get dev-122 /srv/project/config.yaml --output ./config.yaml
+msdev env get dev-122 /srv/project/config.yaml > ./config.yaml
+```
+
+Editing uses content-oriented read/write. Paths inside the Env must be
+absolute. Host Envs use direct filesystem copy locally and ``scp``/``ssh``
+streams remotely. Docker Envs stage through the node with ``docker cp``.
+File bytes never pass through JSON RPC.
+
+```bash
+msdev env read dev-122 /srv/project/config.yaml
+msdev env read dev-122 /srv/project/config.yaml --json
+msdev env write dev-122 /srv/project/note.md --file /tmp/note.md
+msdev env write dev-122 /srv/project/note.md < /tmp/note.md
+msdev env write dev-122 /srv/project/note.md --file /tmp/note.md \
+  --expected-sha256 <digest>
+```
+
+Read before replacing an existing file. `--expected-sha256` is compare-and-swap
+replacement that refuses to overwrite a changed remote file.
+
 ## NPU inventory
 
 ```bash
@@ -130,8 +204,15 @@ msdev exec \
   -- python3 run.py
 ```
 
-`--timeout-seconds` defaults to 300, accepts any positive finite duration, and
-uses `-1` for no deadline. A positive timeout kills the complete command
+Quoted pipelines and `|` tokens are executed through a remote POSIX shell
+(`sh -c`), so they run on the Node instead of being treated as a single
+executable name. On a Windows `local` Env they use `cmd.exe /s /c`. Prefer
+`sh -c '…'` for complex scripts. Default streaming writes POSIX newlines as
+CRLF on a Windows console so remote line output does not staircase; piped
+CLI output keeps LF.
+
+`--timeout-seconds` defaults to `-1` (no deadline). Any positive finite duration
+is also accepted. A positive timeout kills the complete command
 process group and returns exit code 124. Cancelling the local CLI closes the RPC
 connection, causing `msdevd` to kill and reap the remote process group. Finite
 SSH/Unix RPC deadlines include a short completion grace for output drain and
@@ -140,66 +221,6 @@ serialization.
 `--result-json` selects captured, non-streaming execution and prints one
 structured JSON result containing stdout and stderr.
 
-## Remote workspaces
-
-A workspace gives a stable name to an Env and filesystem root:
-
-```bash
-msdev workspace add project \
-  --env dev-122 \
-  --root /srv/project
-
-msdev workspace list
-msdev workspace inspect project
-```
-
-Workspace operations are file- and Git-oriented. There is no
-`msdev workspace exec`; use `msdev exec --env ... --cwd ...` for commands.
-
-### Read and inspect
-
-```bash
-msdev workspace stat project README.md
-msdev workspace read project README.md
-msdev workspace read project weights.bin --output /tmp/weights.bin
-msdev workspace list project src --json
-msdev workspace glob project '**/*.py' --json
-msdev workspace search project 'TODO' src tests --json
-```
-
-### Write safely
-
-For non-trivial content, use stdin or `--file` rather than shell-escaped
-`--content`:
-
-```bash
-msdev workspace write project docs/note.md < /tmp/note.md
-msdev workspace write project docs/note.md --file /tmp/note.md
-```
-
-Compare-and-swap replacement prevents overwriting a changed remote file:
-
-```bash
-msdev workspace apply-patch project docs/note.md \
-  --file /tmp/note.md \
-  --expected-sha256 <digest>
-```
-
-Delete an explicit remote file:
-
-```bash
-msdev workspace delete project docs/obsolete.md
-```
-
-### Git
-
-```bash
-msdev workspace git-status project --result-json
-msdev workspace git-diff project --result-json -- --stat
-```
-
-Git diff rejects options that can write files or invoke external diff helpers.
-
 ## Model inventory
 
 Examples:
@@ -216,59 +237,6 @@ msdev model audit --node dev-122
 Use `msdev model --help` and the individual subcommand help for register,
 update, replicas, refresh, verify, export, import, and rebind.
 
-## Explicit CLI sessions and runbooks
-
-Create a session before a reproducible workflow:
-
-```bash
-msdev session begin --name qwen3-quant --json
-```
-
-Pass the returned ID explicitly or set it in a persistent terminal:
-
-```bash
-export MSDEV_SESSION_ID=<session-id>
-```
-
-Intent metadata is global and must appear before the subcommand:
-
-```bash
-msdev \
-  --session-id <session-id> \
-  --intent-kind execution \
-  --intent-summary 'Run Qwen3 quantization' \
-  --intent-phase quantization \
-  --intent-step-id quant-1 \
-  exec --env dev-122 --timeout-seconds 1800 -- python3 quant.py
-```
-
-Intent kinds:
-
-- `execution`: core reproduction step;
-- `verification`: optional confirmation;
-- `diagnostic`: troubleshooting, excluded from core steps;
-- `exploration`: discovery, excluded from core steps.
-
-Each invocation receives a unique `operation_id`. `session_id` groups CLI
-operations only; it never supplies a Node, Env, or workspace default.
-
-Logs are private JSONL files under:
-
-```text
-${XDG_STATE_HOME:-~/.local/state}/msdev/sessions/
-```
-
-They retain sanitized logical arguments, preview, explicit resource, intent,
-exit code, and elapsed time. Command stdout/stderr and environment values are
-not duplicated into logs.
-
-```bash
-msdev session list
-msdev session export --session-id <session-id> --output runbook.md
-msdev session export --latest --detail normal --output runbook.md
-msdev session export --input /path/to/session.jsonl --detail full
-```
-
 ## Architecture
 
 ```text
@@ -276,15 +244,18 @@ msdev CLI
   -> typed core service
   -> UnixRpcTransport or SshRpcTransport
   -> per-user msdevd
-  -> host/container command, workspace filesystem, NPU, or inventory
+  -> host/container command, env file transfer, NPU, or inventory
 ```
 
-Remote RPC responses and command output are bounded. Workspace paths are
-normalized under the registered root. Writes are atomic and support SHA-256
-compare-and-swap. Node/Env and workspace registries use locked atomic updates.
+Remote RPC responses and command output are bounded. Node/Env registries use
+locked atomic updates.
 
 ## Testing
 
 ```bash
 python3 -m unittest discover -s tests -v
 ```
+
+Feature work must include at least one actual scenario test on the real
+control path (`msdev` CLI → service → transport → `msdevd` → effect). Unit
+tests alone are not sufficient.

msdev-0.11.0/README.md

@@ -0,0 +1,236 @@
+# msdev
+
+`msdev` manages connection Nodes and execution Envs. A Node owns SSH and its
+per-user `msdevd`; an Env references a Node and adds a host/Docker runtime plus
+optional conda/venv/uv layers.
+
+The CLI is intentionally stateless:
+
+- Node-scoped NPU/model operations name `--node` or use `--all`;
+- execution names `--env`;
+- no harness conversation binding or implicit current Env exists;
+- MCP is not part of the architecture.
+
+## Install
+
+```bash
+git clone https://gitcode.com/rookie_hongchuan/msdev.git
+cd msdev
+python3 -m pip install -e .
+msdev --help
+```
+
+The package installs `msdev` and `msdevd`.
+
+## Windows client
+
+The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
+(`C:\Windows\System32\OpenSSH\ssh.exe`). Native Windows OpenSSH does not
+implement ControlMaster multiplexing, so msdev:
+
+- omits `ControlMaster`/`ControlPath` on Windows (override with
+  `MSDEV_SSH_CONTROL_MASTER=1` only if your SSH client actually supports mux);
+- starts a persistent `ssh -L` LocalForward tunnel automatically on the first
+  RPC (same role as ControlMaster). Explicit `msdev node connect NODE` is
+  optional; disable persist with `MSDEV_SSH_LOCAL_FORWARD_PERSIST=0`;
+- reuses that tunnel for captured RPC and default streaming `msdev exec`;
+  `env put`/`get` stay on scp/ssh streams (file bytes do not go through JSON RPC);
+- hides SSH console windows (`CREATE_NO_WINDOW`) and kills process trees with
+  `taskkill /T` on timeout or cancel;
+- SSH is non-interactive: `BatchMode` unless a password is supplied, host keys
+  use `accept-new`, and there is no password/passphrase/yes-no prompt. When a
+  password is known, injects OpenSSH `SSH_ASKPASS` so `node connect` (and later
+  ssh/scp) can authenticate without a TTY; the local public key is then
+  installed on the Node so later logins are passwordless. The password is
+  never written to the node registry;
+- serves a TCP loopback endpoint for local `msdevd` when this Python build has
+  no `AF_UNIX` sockets.
+
+Install with `python -m pip install -e .`. `install-user.py` writes
+`msdev.cmd` / `msdevd.cmd` under `%USERPROFILE%\.local\bin`.
+
+Remote paths inside a Linux Env remain POSIX (`/srv/...`). Local `env put`/`get`
+on Windows accept Windows absolute paths (`C:\...`).
+
+Local `exec` on Windows wraps Conda with `conda run` and venvs with
+`Scripts\activate.bat` (remote Linux Nodes still use POSIX `sh`/`bash` wrappers).
+If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
+
+## Nodes and execution environments
+
+Register a host from `~/.ssh/config`:
+
+```bash
+msdev node add dev-122 --ssh-host dev-122
+msdev node list
+msdev node status dev-122
+```
+
+Adding a Node atomically creates a same-named host Env. Bootstrap or refresh
+the remote user daemon:
+
+```bash
+msdev node bootstrap dev-122
+```
+
+Persistent OpenSSH masters are optional. All SSH from msdev is
+non-interactive: host keys use `accept-new`, and password/passphrase prompts
+are disabled. Supply a password via environment or file (never a prompt);
+connect then installs the local public key (`~/.ssh/id_ed25519`, generated
+if missing) so later connections are passwordless:
+
+```bash
+# Environment (also used by exec / env put after connect if persist is off)
+export MSDEV_SSH_PASSWORD='...'
+export MSDEV_SSH_PASSWORD_DEV_122='...'   # per-node override
+
+msdev node connect dev-122
+msdev node connect dev-122 --password-file FILE
+msdev node connect dev-122 --password-env VAR
+msdev node connect dev-122 --password PASSWORD   # non-interactive; visible in ps
+msdev node connect dev-122 --identity FILE     # choose which key to install
+msdev node connect dev-122 --no-install-key    # password only, do not copy key
+msdev node disconnect dev-122
+```
+
+Nodes and Envs have separate private Markdown guides:
+
+```bash
+msdev node guide dev-122
+msdev node guide dev-122 --write ./dev-122-guide.md
+msdev env guide dev-122
+msdev env guide dev-122 --write ./host-env-guide.md
+```
+
+Guides are stored under `~/.config/msdev/guides/nodes/` and
+`~/.config/msdev/guides/environments/`, with private permissions and a 256 KiB
+limit. Agents read the applicable guides once before first use in a session.
+
+Open a human-operated interactive shell in an Env:
+
+```bash
+msdev env shell dev-122
+msdev env shell dev-122 --cwd /srv/project
+```
+
+The command allocates an OpenSSH PTY and enters the Env's Docker runtime and
+conda/venv/uv layers. Exiting returns
+to the local shell. Only the shell session start and final status are visible
+to msdev; commands typed inside it are not individually logged. Agent
+automation should continue using `msdev exec`.
+
+Create another Env on the same Node for Docker and Python layers:
+
+```bash
+msdev env add dev-122-vllm \
+  --node dev-122 \
+  --docker-container vllm-ascend \
+  --layer conda:base \
+  --layer venv:/srv/project/.venv
+```
+
+## File put, get, read, and write
+
+Bulk transfer copies a local file into an Env filesystem, or fetches one back:
+
+```bash
+msdev env put dev-122 ./config.yaml /srv/project/config.yaml
+msdev env get dev-122 /srv/project/config.yaml --output ./config.yaml
+msdev env get dev-122 /srv/project/config.yaml > ./config.yaml
+```
+
+Editing uses content-oriented read/write. Paths inside the Env must be
+absolute. Host Envs use direct filesystem copy locally and ``scp``/``ssh``
+streams remotely. Docker Envs stage through the node with ``docker cp``.
+File bytes never pass through JSON RPC.
+
+```bash
+msdev env read dev-122 /srv/project/config.yaml
+msdev env read dev-122 /srv/project/config.yaml --json
+msdev env write dev-122 /srv/project/note.md --file /tmp/note.md
+msdev env write dev-122 /srv/project/note.md < /tmp/note.md
+msdev env write dev-122 /srv/project/note.md --file /tmp/note.md \
+  --expected-sha256 <digest>
+```
+
+Read before replacing an existing file. `--expected-sha256` is compare-and-swap
+replacement that refuses to overwrite a changed remote file.
+
+## NPU inventory
+
+```bash
+msdev npu list --node dev-122 --json
+msdev npu list --all --json
+```
+
+## Command execution
+
+Commands execute synchronously and stream stdout and stderr to the terminal as
+they are produced. Cursor or Claude Code should use their native background
+terminal support for long jobs. Long jobs may also write a persistent progress
+log when later inspection is required.
+
+```bash
+msdev exec \
+  --env dev-122 \
+  --cwd /srv/project \
+  --timeout-seconds 1800 \
+  --env-var MODE=test \
+  -- python3 run.py
+```
+
+Quoted pipelines and `|` tokens are executed through a remote POSIX shell
+(`sh -c`), so they run on the Node instead of being treated as a single
+executable name. On a Windows `local` Env they use `cmd.exe /s /c`. Prefer
+`sh -c '…'` for complex scripts. Default streaming writes POSIX newlines as
+CRLF on a Windows console so remote line output does not staircase; piped
+CLI output keeps LF.
+
+`--timeout-seconds` defaults to `-1` (no deadline). Any positive finite duration
+is also accepted. A positive timeout kills the complete command
+process group and returns exit code 124. Cancelling the local CLI closes the RPC
+connection, causing `msdevd` to kill and reap the remote process group. Finite
+SSH/Unix RPC deadlines include a short completion grace for output drain and
+serialization.
+
+`--result-json` selects captured, non-streaming execution and prints one
+structured JSON result containing stdout and stderr.
+
+## Model inventory
+
+Examples:
+
+```bash
+msdev model discover --node dev-122 --root /data/models
+msdev model list --node dev-122 --json
+msdev model list --all --json
+msdev model inspect model://qwen/Qwen3-32B@main --node dev-122
+msdev model validate model://qwen/Qwen3-32B@main --node dev-122
+msdev model audit --node dev-122
+```
+
+Use `msdev model --help` and the individual subcommand help for register,
+update, replicas, refresh, verify, export, import, and rebind.
+
+## Architecture
+
+```text
+msdev CLI
+  -> typed core service
+  -> UnixRpcTransport or SshRpcTransport
+  -> per-user msdevd
+  -> host/container command, env file transfer, NPU, or inventory
+```
+
+Remote RPC responses and command output are bounded. Node/Env registries use
+locked atomic updates.
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Feature work must include at least one actual scenario test on the real
+control path (`msdev` CLI → service → transport → `msdevd` → effect). Unit
+tests alone are not sufficient.

{msdev-0.10.0 → msdev-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "msdev"
-version = "0.10.0"
+version = "0.11.0"
 description = "Portable nodes and execution environments for msModelSlim development"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,6 +23,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
   "Operating System :: POSIX :: Linux",
   "Topic :: Software Development :: Build Tools",
 ]

{msdev-0.10.0 → msdev-0.11.0}/src/msdev/__init__.py

@@ -1,3 +1,3 @@
 """Portable node and execution-environment tooling for msModelSlim."""
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"