msdev 0.12.0__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msdev
-Version: 0.12.0
+Version: 0.13.0
 Summary: Portable nodes and execution environments for msModelSlim development
 Author: msModelSlim Agent Contributors
 License-Expression: MulanPSL-2.0
@@ -32,7 +32,8 @@ 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.
 
-The CLI is intentionally stateless: execution always names `--env` explicitly.
+The CLI is intentionally stateless: execution always names the env as the first
+`exec` argument.
 MCP is not part of the architecture.
 
 ## Install
@@ -46,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
@@ -58,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
@@ -82,22 +97,25 @@ 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. Connect deploys and
-starts the remote `msdevd` when needed:
+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.
 
-```bash
-msdev node connect dev-122
-```
-
-Connect uploads a **static Go msdevd** binary matching the node architecture
+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.
 
@@ -113,19 +131,14 @@ 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
@@ -144,6 +157,17 @@ Guides are stored under `~/.config/msdev/guides/nodes/` and
 `~/.config/msdev/guides/environments/`. **Node guides** document how to
 connect; **Env guides** document how to initialize shared context (`setup`).
 
+Share a full local configuration (registry + guides) with:
+
+```bash
+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
+```
+
+Bundles contain `resources.json`, both guide trees, and a `manifest.json`.
+SSH keys and passwords are never exported.
+
 ```bash
 msdev env add dev-122-root \
   --node dev-122 \
@@ -173,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.
 
@@ -193,18 +217,38 @@ replacement that refuses to overwrite a changed remote file.
 
 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

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

@@ -7,7 +7,8 @@ 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.
 
-The CLI is intentionally stateless: execution always names `--env` explicitly.
+The CLI is intentionally stateless: execution always names the env as the first
+`exec` argument.
 MCP is not part of the architecture.
 
 ## Install
@@ -21,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
@@ -33,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
@@ -57,22 +72,25 @@ 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. Connect deploys and
-starts the remote `msdevd` when needed:
+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.
 
-```bash
-msdev node connect dev-122
-```
-
-Connect uploads a **static Go msdevd** binary matching the node architecture
+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.
 
@@ -88,19 +106,14 @@ 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
@@ -119,6 +132,17 @@ Guides are stored under `~/.config/msdev/guides/nodes/` and
 `~/.config/msdev/guides/environments/`. **Node guides** document how to
 connect; **Env guides** document how to initialize shared context (`setup`).
 
+Share a full local configuration (registry + guides) with:
+
+```bash
+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
+```
+
+Bundles contain `resources.json`, both guide trees, and a `manifest.json`.
+SSH keys and passwords are never exported.
+
 ```bash
 msdev env add dev-122-root \
   --node dev-122 \
@@ -148,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.
 
@@ -168,18 +192,38 @@ replacement that refuses to overwrite a changed remote file.
 
 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "msdev"
-version = "0.12.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-*", "helpers/msdevd-linux-*"]
+msdev = [
+  "helpers/msdev-file-helper-*",
+  "helpers/msdevd-linux-*",
+  "skills/msdev-cli/SKILL.md",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

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

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