msdev 0.11.0__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msdev
-Version: 0.11.0
+Version: 0.13.0
 Summary: Portable nodes and execution environments for msModelSlim development
 Author: msModelSlim Agent Contributors
 License-Expression: MulanPSL-2.0
@@ -25,16 +25,16 @@ Dynamic: license-file
 
 # 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.
+`msdev` exposes three capabilities: **`node`** (connect + host agent),
+**`env`** (shared execution context, shell, files), and **`exec`** (commands).
 
-The CLI is intentionally stateless:
+A Node owns SSH reachability and `msdevd` deployment. An Env owns the full
+execution context: host or Docker runtime, conda/venv/uv layers, optional
+`setup` script (root switch, proxy, etc.), command `wrap`, and static env vars.
 
-- 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.
+The CLI is intentionally stateless: execution always names the env as the first
+`exec` argument.
+MCP is not part of the architecture.
 
 ## Install
 
@@ -47,6 +47,20 @@ msdev --help
 
 The package installs `msdev` and `msdevd`.
 
+Install the agent skill for Cursor and Claude Code, and sync SSH config:
+
+```bash
+msdev init
+msdev init --scope project
+msdev init -f
+```
+
+`init` registers Host aliases from `~/.ssh/config`, prints added/removed
+changes, and writes `skills/msdev-cli/SKILL.md` into `~/.cursor/skills/` and
+`~/.claude/skills/` (or into `.cursor/` / `.claude/` under the current
+directory with `--scope project`). Outdated skill files prompt before
+overwrite; use `-f` to force.
+
 ## Windows client
 
 The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
@@ -59,13 +73,13 @@ implement ControlMaster multiplexing, so msdev:
   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);
+  `env put`/`get` stay on sftp/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
+  ssh/sftp) 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
@@ -83,36 +97,48 @@ If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
 
 ## Nodes and execution environments
 
-Register a host from `~/.ssh/config`:
+Use **`node connect`** as the single entry point: it writes `~/.ssh/config`
+when needed, registers the node, saves passwords, installs the local public
+key, and deploys `msdevd`:
 
 ```bash
-msdev node add dev-122 --ssh-host dev-122
+msdev node connect dev-122 --hostname 80.48.33.133 --user root --password PASSWORD
+msdev node connect dev-122
+msdev node sync-ssh
+msdev node list --ssh
 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:
+Connect writes or updates a dedicated `Host <name>` block in OpenSSH config.
+The msdev registry stores only the Host alias plus msdevd settings
+(`remote_bin`, `auto_bootstrap`). User, port, keys, and proxy remain in SSH
+config. `node sync-ssh` registers Host aliases that were added manually.
+
+Connect atomically creates a same-named host Env on first use and uploads a
+**static Go msdevd** binary matching the node architecture
+(`linux-amd64` / `linux-arm64`) when the agent is missing or stale. No Python
+is required on the node.
+
+Build the static daemons before release or local testing:
 
 ```bash
-msdev node bootstrap dev-122
+bash msdevd/build-static.sh
+bash file-helper/build-static.sh
 ```
 
+Packaged artifacts live under `src/msdev/helpers/` (gitignored until built).
+The Go source is in `msdev/`.
+
 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:
+are disabled. Supply `--password` on connect; it is saved to ``~/.ssh/config``
+as ``# msdev Password ...`` and used to install the local public key
+(``~/.ssh/id_ed25519``, generated if missing) so later connections can be
+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 --hostname 80.48.33.133 --user root --password PASSWORD
 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
@@ -128,32 +154,38 @@ 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.
+`~/.config/msdev/guides/environments/`. **Node guides** document how to
+connect; **Env guides** document how to initialize shared context (`setup`).
 
-Open a human-operated interactive shell in an Env:
+Share a full local configuration (registry + guides) with:
 
 ```bash
-msdev env shell dev-122
-msdev env shell dev-122 --cwd /srv/project
+msdev config export ./msdev-config.tar.gz
+msdev config import ./msdev-config.tar.gz
+msdev config import ./msdev-config.tar.gz --force   # overwrite name conflicts
 ```
 
-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:
+Bundles contain `resources.json`, both guide trees, and a `manifest.json`.
+SSH keys and passwords are never exported.
 
 ```bash
-msdev env add dev-122-vllm \
+msdev env add dev-122-root \
   --node dev-122 \
-  --docker-container vllm-ascend \
-  --layer conda:base \
-  --layer venv:/srv/project/.venv
+  --setup-file ./setup-root.sh \
+  --wrap sudo --wrap -n --wrap --
+
+msdev env open dev-122-root
 ```
 
+Open a human-operated interactive shell in an Env:
+
+```bash
+msdev env shell dev-122
+msdev env shell dev-122 --cwd /srv/project
+```
+
+Agent automation should use `msdev exec`, not `env shell`.
+
 ## File put, get, read, and write
 
 Bulk transfer copies a local file into an Env filesystem, or fetches one back:
@@ -165,7 +197,7 @@ 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``
+absolute. Host Envs use direct filesystem copy locally and ``sftp``/``ssh``
 streams remotely. Docker Envs stage through the node with ``docker cp``.
 File bytes never pass through JSON RPC.
 
@@ -181,29 +213,42 @@ msdev env write dev-122 /srv/project/note.md --file /tmp/note.md \
 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.
+terminal support for long jobs.
+
+Pick **one** form:
+
+| Scenario | Form |
+|----------|------|
+| Simple one-liner | `-c '…'` |
+| Quotes, pipes, multi-line | `--file -` + heredoc (see below) |
+| Script on disk | `--file ./script.sh` |
+
+**Heredoc** (`<<'EOF'`) is a local-shell mechanism: it writes a multi-line
+string to msdev's **stdin** when you pass `--file -`. Quote the delimiter
+(`<<'EOF'`) so `$` and backticks are not expanded locally. msdev then runs the
+body through a remote shell (`sh -c`), or via shebang if the body starts with
+`#!`.
 
 ```bash
-msdev exec \
-  --env dev-122 \
-  --cwd /srv/project \
-  --timeout-seconds 1800 \
-  --env-var MODE=test \
-  -- python3 run.py
+msdev exec dev-122 --file - <<'EOF'
+python3 -c 'print("no local quoting")'
+grep 'pattern' /var/log/app.log | tail -20
+EOF
+
+msdev exec dev-122 -c 'python3 train.py --config "path with spaces" | tee log.txt'
+
+msdev exec dev-122 --file ./scripts/run.sh
 ```
 
+Positional commands after `--` are not supported. The env name is the first
+argument after `exec`; use `-c` for inline strings or `--file` for script
+content (path or `-` for stdin/heredoc). `-c -` is accepted but identical to
+`--file -`; prefer **`--file -`** only.
+
 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
@@ -221,30 +266,13 @@ 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
+  -> per-user msdevd (env session + job runner + files)
 ```
 
 Remote RPC responses and command output are bounded. Node/Env registries use

{msdev-0.11.0 → msdev-0.13.0}/README.md

@@ -1,15 +1,15 @@
 # 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.
+`msdev` exposes three capabilities: **`node`** (connect + host agent),
+**`env`** (shared execution context, shell, files), and **`exec`** (commands).
 
-The CLI is intentionally stateless:
+A Node owns SSH reachability and `msdevd` deployment. An Env owns the full
+execution context: host or Docker runtime, conda/venv/uv layers, optional
+`setup` script (root switch, proxy, etc.), command `wrap`, and static env vars.
 
-- 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.
+The CLI is intentionally stateless: execution always names the env as the first
+`exec` argument.
+MCP is not part of the architecture.
 
 ## Install
 
@@ -22,6 +22,20 @@ msdev --help
 
 The package installs `msdev` and `msdevd`.
 
+Install the agent skill for Cursor and Claude Code, and sync SSH config:
+
+```bash
+msdev init
+msdev init --scope project
+msdev init -f
+```
+
+`init` registers Host aliases from `~/.ssh/config`, prints added/removed
+changes, and writes `skills/msdev-cli/SKILL.md` into `~/.cursor/skills/` and
+`~/.claude/skills/` (or into `.cursor/` / `.claude/` under the current
+directory with `--scope project`). Outdated skill files prompt before
+overwrite; use `-f` to force.
+
 ## Windows client
 
 The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
@@ -34,13 +48,13 @@ implement ControlMaster multiplexing, so msdev:
   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);
+  `env put`/`get` stay on sftp/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
+  ssh/sftp) 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
@@ -58,36 +72,48 @@ If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
 
 ## Nodes and execution environments
 
-Register a host from `~/.ssh/config`:
+Use **`node connect`** as the single entry point: it writes `~/.ssh/config`
+when needed, registers the node, saves passwords, installs the local public
+key, and deploys `msdevd`:
 
 ```bash
-msdev node add dev-122 --ssh-host dev-122
+msdev node connect dev-122 --hostname 80.48.33.133 --user root --password PASSWORD
+msdev node connect dev-122
+msdev node sync-ssh
+msdev node list --ssh
 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:
+Connect writes or updates a dedicated `Host <name>` block in OpenSSH config.
+The msdev registry stores only the Host alias plus msdevd settings
+(`remote_bin`, `auto_bootstrap`). User, port, keys, and proxy remain in SSH
+config. `node sync-ssh` registers Host aliases that were added manually.
+
+Connect atomically creates a same-named host Env on first use and uploads a
+**static Go msdevd** binary matching the node architecture
+(`linux-amd64` / `linux-arm64`) when the agent is missing or stale. No Python
+is required on the node.
+
+Build the static daemons before release or local testing:
 
 ```bash
-msdev node bootstrap dev-122
+bash msdevd/build-static.sh
+bash file-helper/build-static.sh
 ```
 
+Packaged artifacts live under `src/msdev/helpers/` (gitignored until built).
+The Go source is in `msdev/`.
+
 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:
+are disabled. Supply `--password` on connect; it is saved to ``~/.ssh/config``
+as ``# msdev Password ...`` and used to install the local public key
+(``~/.ssh/id_ed25519``, generated if missing) so later connections can be
+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 --hostname 80.48.33.133 --user root --password PASSWORD
 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
@@ -103,32 +129,38 @@ 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.
+`~/.config/msdev/guides/environments/`. **Node guides** document how to
+connect; **Env guides** document how to initialize shared context (`setup`).
 
-Open a human-operated interactive shell in an Env:
+Share a full local configuration (registry + guides) with:
 
 ```bash
-msdev env shell dev-122
-msdev env shell dev-122 --cwd /srv/project
+msdev config export ./msdev-config.tar.gz
+msdev config import ./msdev-config.tar.gz
+msdev config import ./msdev-config.tar.gz --force   # overwrite name conflicts
 ```
 
-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:
+Bundles contain `resources.json`, both guide trees, and a `manifest.json`.
+SSH keys and passwords are never exported.
 
 ```bash
-msdev env add dev-122-vllm \
+msdev env add dev-122-root \
   --node dev-122 \
-  --docker-container vllm-ascend \
-  --layer conda:base \
-  --layer venv:/srv/project/.venv
+  --setup-file ./setup-root.sh \
+  --wrap sudo --wrap -n --wrap --
+
+msdev env open dev-122-root
 ```
 
+Open a human-operated interactive shell in an Env:
+
+```bash
+msdev env shell dev-122
+msdev env shell dev-122 --cwd /srv/project
+```
+
+Agent automation should use `msdev exec`, not `env shell`.
+
 ## File put, get, read, and write
 
 Bulk transfer copies a local file into an Env filesystem, or fetches one back:
@@ -140,7 +172,7 @@ 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``
+absolute. Host Envs use direct filesystem copy locally and ``sftp``/``ssh``
 streams remotely. Docker Envs stage through the node with ``docker cp``.
 File bytes never pass through JSON RPC.
 
@@ -156,29 +188,42 @@ msdev env write dev-122 /srv/project/note.md --file /tmp/note.md \
 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.
+terminal support for long jobs.
+
+Pick **one** form:
+
+| Scenario | Form |
+|----------|------|
+| Simple one-liner | `-c '…'` |
+| Quotes, pipes, multi-line | `--file -` + heredoc (see below) |
+| Script on disk | `--file ./script.sh` |
+
+**Heredoc** (`<<'EOF'`) is a local-shell mechanism: it writes a multi-line
+string to msdev's **stdin** when you pass `--file -`. Quote the delimiter
+(`<<'EOF'`) so `$` and backticks are not expanded locally. msdev then runs the
+body through a remote shell (`sh -c`), or via shebang if the body starts with
+`#!`.
 
 ```bash
-msdev exec \
-  --env dev-122 \
-  --cwd /srv/project \
-  --timeout-seconds 1800 \
-  --env-var MODE=test \
-  -- python3 run.py
+msdev exec dev-122 --file - <<'EOF'
+python3 -c 'print("no local quoting")'
+grep 'pattern' /var/log/app.log | tail -20
+EOF
+
+msdev exec dev-122 -c 'python3 train.py --config "path with spaces" | tee log.txt'
+
+msdev exec dev-122 --file ./scripts/run.sh
 ```
 
+Positional commands after `--` are not supported. The env name is the first
+argument after `exec`; use `-c` for inline strings or `--file` for script
+content (path or `-` for stdin/heredoc). `-c -` is accepted but identical to
+`--file -`; prefer **`--file -`** only.
+
 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
@@ -196,30 +241,13 @@ 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
+  -> per-user msdevd (env session + job runner + files)
 ```
 
 Remote RPC responses and command output are bounded. Node/Env registries use

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "msdev"
-version = "0.11.0"
+version = "0.13.0"
 description = "Portable nodes and execution environments for msModelSlim development"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -44,7 +44,11 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-msdev = ["helpers/msdev-file-helper-*"]
+msdev = [
+  "helpers/msdev-file-helper-*",
+  "helpers/msdevd-linux-*",
+  "skills/msdev-cli/SKILL.md",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

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

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