diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2088543..5db1cf6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,26 +1,24 @@ name: CI -# Three operating systems, and none of them on a push. +# The checks, run at the boundaries and nowhere else. # -# A push to main starts NOTHING here: the owner commits and pushes freely, and CI is a -# thing that runs at the boundaries instead - a pull request, a manual dispatch, and - -# through `workflow_call` - the gate a release passes before it -# publishes anything. The check that must never be skipped is the one at the cut, and the -# cut is what pays for it. (Before this, every push to main ran one job, on the platform a -# Windows development machine cannot check for itself; that job now waits for the release.) +# There used to be three operating systems here, because there was a binary to build on +# each. There is no binary: the pack is plain JavaScript with zero npm dependencies and the +# launchers are batch, PowerShell and POSIX sh over the pinned `dsh web`. A `node:22` +# container is the whole toolchain, so one job on one runner covers every platform this +# ships to - and the runtime the checks run on is the one `package.json` declares. # -# This workflow builds the RUST app only. The node/JS half needs no build: it is the same -# files on every platform, it is packaged by release.yml as its own archive, and -# `scripts/run-web.*` works without this app at all. +# A push to main starts NOTHING: CI runs at the boundaries - a pull request, a manual +# dispatch, and, through `workflow_call`, the gate a release passes before it publishes +# anything. # # NO THIRD-PARTY ACTIONS, and that is a constraint rather than a taste: this repository's # Actions policy is `local_only`, so `actions/checkout` is refused at STARTUP (measured: a # pull request produced a `startup_failure` in 0 s). Every step below is a shell command -# against a tool the runner image already carries - git, rustc, cargo, node, gh - so the -# workflow runs under the policy instead of asking for the policy to be relaxed. +# against a tool the image carries, and the checkout is `git` itself. on: - # NO `push` TRIGGER, on purpose. Adding one back brings the per-commit CI bill back with - # it; a release reaches this workflow through `workflow_call` from release.yml. + # NO `push` TRIGGER, on purpose: a release reaches this workflow through `workflow_call` + # from release.yml, and a commit does not need a runner to be believed. pull_request: paths-ignore: - '**.md' @@ -29,7 +27,7 @@ on: workflow_dispatch: workflow_call: -# A superseded push has nothing to say. Cancel it and let the cache serve the next one. +# A superseded push has nothing to say. Cancel it and let the next one run. concurrency: group: ci-${{ github.ref }} cancel-in-progress: true @@ -37,38 +35,27 @@ concurrency: permissions: contents: read -env: - CARGO_TERM_COLOR: always - CARGO_INCREMENTAL: '0' - jobs: - # The matrix is chosen by the event rather than written twice, so the caller and the - # push cannot disagree about what "checked" means. - plan: - name: Choose the matrix + check: + name: Node checks runs-on: ubuntu-latest - timeout-minutes: 2 - outputs: - os: ${{ steps.pick.outputs.os }} + timeout-minutes: 10 + container: node:22-bookworm steps: - - id: pick + # The image is Node and nothing else. `git` is the one addition, for two reasons that + # are not optional: the checkout below IS git, and check-no-secrets reads the set + # `git add -A` would stage, which is a question only git can answer. + - name: git + shell: bash run: | - if [ "${{ github.event_name }}" = "push" ]; then - echo 'os=["ubuntu-latest"]' >> "$GITHUB_OUTPUT" - else - echo 'os=["ubuntu-latest","windows-latest","macos-latest"]' >> "$GITHUB_OUTPUT" - fi + apt-get update -qq + apt-get install -y --no-install-recommends git ca-certificates >/dev/null + git --version + # The container runs as root over a workspace the runner owns, and git refuses a + # repository it thinks belongs to somebody else. Naming the workspace is the fix, + # and it is narrower than trusting every directory. + git config --global --add safe.directory "$GITHUB_WORKSPACE" - check: - name: ${{ matrix.os }} - needs: plan - runs-on: ${{ matrix.os }} - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - os: ${{ fromJSON(needs.plan.outputs.os) }} - steps: # The checkout step, without an action. `pull_request` checks the merge commit GitHub # already built (refs/pull/N/merge); everything else checks the sha. - name: Checkout @@ -84,103 +71,21 @@ jobs: git fetch -q --depth 1 origin "$ref" git checkout -q FETCH_HEAD - # The runner image carries the Rust toolchain and the clippy component. `rust-version` - # in app/Cargo.toml is the floor the code is written to; a toolchain below it fails - # here by name rather than somewhere inside a build. - - name: Toolchain - shell: bash - run: | - rustc --version - cargo --version - cargo clippy --version - - # Warnings denied, so a dependency that arrives with a warning is a failure rather - # than a line nobody reads. The workspace has no GUI toolkit and no web engine to - # link, so this needs no `apt-get install` on the Linux runner - which is one of the - # things the cut bought. - - name: Clippy - working-directory: app - run: cargo clippy --workspace --all-targets --locked -- -D warnings - - # `VNCODE_TEST_DIR` keeps the tests' scratch files inside the checkout. They are - # writable in a CI temp directory, but a test that writes where a confined host - # denies it is how this suite reported failures about the HOST rather than the code. - - name: Test - working-directory: app - shell: bash - env: - VNCODE_TEST_DIR: ${{ github.workspace }}/.test-tmp - run: | - mkdir -p "$VNCODE_TEST_DIR" - cargo test --workspace --locked - - - name: Build (release) - working-directory: app - shell: bash - run: | - if [ "$RUNNER_OS" = "Windows" ]; then - export RUSTFLAGS='-C target-feature=+crt-static' - fi - cargo build --release --locked -p vn-shell - - # The budget is a test, not a hope. A dependency that quietly pulls a GUI stack or a - # web engine changes this number, and that is the change this project exists to - # prevent - so it fails here by name. - - name: Size budget - working-directory: app + # The floor is the pack's own `engines.node`. A check that only passes on another + # runtime fails here by name instead of somewhere inside a script. + - name: Node shell: bash run: | - BIN="target/release/vncode" - [ "$RUNNER_OS" = "Windows" ] && BIN="$BIN.exe" - BYTES=$(wc -c < "$BIN") - MB=$((BYTES / 1048576)) - echo "vncode: $BYTES bytes (${MB} MB)" - if [ "$BYTES" -gt $((6 * 1048576)) ]; then - echo "::error::$BIN is ${MB} MB, over the 6 MB budget - a dependency that draws a window or a web view is the usual cause" - exit 1 - fi + node --version + node -e "const n = process.versions.node.split('.').map(Number); if (n[0] < 22) { console.error('Node ' + process.versions.node + ' is below the pack floor (22)'); process.exit(1) }" - - name: Smoke - working-directory: app - shell: bash - run: | - BIN="target/release/vncode" - [ "$RUNNER_OS" = "Windows" ] && BIN="$BIN.exe" - "$BIN" --version - "$BIN" -Help > /dev/null - # `-Mode embed` is the flag the deleted web view used to answer. It must fail by - # name, not be silently ignored - that is what "no web view" means. - # - # Captured first, then matched. These steps run with `-o pipefail`, where - # `vncode ... | grep -q` reports the BINARY's exit 1 and turns a correct refusal - # into a failed pipeline - measured on the first run of this workflow. - OUT=$("$BIN" -Mode embed 2>&1 || true) - case "$OUT" in - *"unknown flag"*) echo "the deleted mode is refused by name" ;; - *) - echo "::error::-Mode embed was accepted, or refused without naming it" - exit 1 - ;; - esac - - secrets: - name: No secrets - runs-on: ubuntu-latest - timeout-minutes: 5 - steps: - - name: Checkout (full history - the check reads what a push would stage) - shell: bash - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_NUMBER: ${{ github.event.pull_request.number }} - run: | - ref="$GITHUB_SHA" - if [ -n "$PR_NUMBER" ]; then ref="refs/pull/$PR_NUMBER/merge"; fi - git init -q . - git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git fetch -q origin "$ref" - git checkout -q FETCH_HEAD - # The one check that is about the repository rather than a platform, and the one - # whose failure can never be undone by a later commit. `node` is on the runner image. - - name: check-no-secrets + # The one check that is about the repository rather than a platform, and the one whose + # failure can never be undone by a later commit. + - name: No secrets run: node scripts/checks/check-no-secrets.mjs + + # The layout, the console contract, the portable-root rule and the two workflows. + # It drives `setup/install.bat -Help` only on a Windows host and says so loudly + # elsewhere, so this job proves the shape here and the launch is proved by hand. + - name: Scripts and workflows + run: node scripts/checks/check-scripts.mjs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8cbaa65..575a0dc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,45 +1,40 @@ name: Release -# Publishing a tag is what publishes a release. A tag cannot exist without its binaries, -# because the build is what attaches them. +# A tag publishes a release, and the release is ONE file: a zip of the repository at that +# tag. There is no second artefact and no per-OS build, because there is nothing to build - +# the pack is plain JavaScript, the launchers are batch, PowerShell and POSIX sh, and the +# only thing a machine needs is Node.js >= 22. # -# TWO ARTIFACTS, ON PURPOSE, and they are separate things: -# -# vncode--- the Rust app: one small binary per platform. This is the -# only per-OS artefact anywhere in the project. -# vncode-web- the node/JS half: the pack and the launcher scripts, the -# SAME bytes on every platform, built once. It runs on its -# own - scripts/run-web.* needs no vncode binary at all - -# and the app above is a front door that calls it. +# This is what "the distribution is this repository" means in practice: the zip carries the +# pack, the launchers, the checks and the docs, and nothing else is handed out. on: push: tags: ['v*'] workflow_dispatch: inputs: tag: - description: 'Existing tag to build and attach binaries to' + description: 'Existing tag to package' required: true permissions: contents: write env: - CARGO_TERM_COLOR: always STEM: vncode GH_REPO: ${{ github.repository }} jobs: - # A tag is a promise that the commit it names was checked on three platforms. The gate - # calls the same workflow a pull request runs rather than a copy of it, so the two cannot - # drift: a red check stops the release here, before a draft exists to be published. + # A tag is a promise that the commit it names passed the checks. The gate calls the same + # workflow a pull request runs rather than a copy of it, so the two cannot drift: a red + # check stops the release here, before a draft exists to be published. gate: name: Gate uses: ./.github/workflows/ci.yml permissions: contents: read - # Create the release once, as a draft. It becomes visible only after every archive and - # SHA256SUMS.txt are attached, so a half-finished release cannot be installed. + # Create the release once, as a draft. It becomes visible only after the zip and + # SHA256SUMS.txt are attached, so a half-finished release cannot be downloaded. prepare: name: Prepare release needs: gate @@ -54,112 +49,14 @@ jobs: gh release view "$TAG" >/dev/null 2>&1 || \ gh release create "$TAG" --draft --title "${STEM} ${TAG}" --generate-notes - # ---- the Rust app: one binary per OS ------------------------------------- - build: - name: ${{ matrix.target }} - needs: prepare - runs-on: ${{ matrix.os }} - timeout-minutes: 45 - strategy: - fail-fast: false - matrix: - include: - # A STATIC CRT, so the Windows binary needs no redistributable: this app is one - # file somebody drops in a folder, and "install the VC++ runtime first" is the - # kind of requirement that makes a small app not worth installing. - - os: windows-latest - target: x86_64-pc-windows-msvc - os_name: windows - arch: x86_64 - ext: zip - rustflags: '-C target-feature=+crt-static' - # 22.04 rather than `latest`, for the glibc floor: a binary built on 24.04 does - # not run on a distribution released before it. - - os: ubuntu-22.04 - target: x86_64-unknown-linux-gnu - os_name: linux - arch: x86_64 - ext: tar.gz - rustflags: '' - - os: macos-latest - target: aarch64-apple-darwin - os_name: macos - arch: aarch64 - ext: tar.gz - rustflags: '' - steps: - # No third-party actions anywhere in this workflow: the repository's Actions policy - # is `local_only`, so a marketplace action is refused at startup. git, rustc/cargo - # and gh are already on the runner image. - - name: Checkout - shell: bash - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - REF: ${{ github.event.inputs.tag || github.ref }} - run: | - git init -q . - git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git fetch -q --depth 1 origin "$REF" - git checkout -q FETCH_HEAD - - - name: Toolchain - shell: bash - env: - TARGET: ${{ matrix.target }} - run: | - rustc --version - # A no-op when the target is the runner's own, which it is for all three legs. - rustup target add "$TARGET" - - # No GUI toolkit and no web engine to link, which is why this workflow has no - # `apt-get` step: the app draws nothing. - - name: Build - working-directory: app - env: - RUSTFLAGS: ${{ matrix.rustflags }} - run: cargo build --release --locked -p vn-shell --target ${{ matrix.target }} - - - name: Package - shell: bash - run: | - TAG="${{ github.event.inputs.tag || github.ref_name }}" - VERSION="${TAG#v}" - NAME="${STEM}-${VERSION}-${{ matrix.os_name }}-${{ matrix.arch }}" - ROOT="${STEM}-${VERSION}" - BIN="app/target/${{ matrix.target }}/release/vncode" - mkdir -p "dist/${ROOT}" - if [ "${{ matrix.os_name }}" = "windows" ]; then - cp "${BIN}.exe" "dist/${ROOT}/" - cp README.md LICENSE "dist/${ROOT}/" - cp "app/README.md" "dist/${ROOT}/APP-README.md" - # bsdtar writes forward-slash entries; the GNU tar in Git Bash does not make a - # zip at all, so the Windows bsdtar is called explicitly. - "/c/Windows/System32/tar.exe" -a -c -f "dist/${NAME}.zip" -C dist "${ROOT}" - else - cp "${BIN}" "dist/${ROOT}/" - cp README.md LICENSE "dist/${ROOT}/" - cp "app/README.md" "dist/${ROOT}/APP-README.md" - chmod +x "dist/${ROOT}/vncode" - (cd dist && tar -czf "${NAME}.tar.gz" "${ROOT}") - fi - cp "dist/${NAME}.${{ matrix.ext }}" . - echo "ASSET=${NAME}.${{ matrix.ext }}" >> "$GITHUB_ENV" - - - name: Upload - shell: bash - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - TAG="${{ github.event.inputs.tag || github.ref_name }}" - gh release upload "$TAG" "$ASSET" --clobber - - # ---- the node/JS half: built once, because it is the same bytes everywhere ---- - web: - name: Web half (node/JS) + package: + name: Repository zip needs: prepare runs-on: ubuntu-latest timeout-minutes: 10 steps: + # No third-party actions anywhere in this workflow: the repository's Actions policy + # is `local_only`, so a marketplace action is refused at startup. - name: Checkout shell: bash env: @@ -171,13 +68,9 @@ jobs: git fetch -q --depth 1 origin "$REF" git checkout -q FETCH_HEAD - # No node setup step: this job only PACKAGES the JS, and the one thing it runs - # (`run-web.sh -Help`) needs no interpreter at all. - - # The web half must work WITHOUT the app, so it is proved that way: the launcher - # answers its own -Help, the installer answers its own -Help, and neither touches a - # profile while doing it. - - name: It runs on its own + # The launcher must answer its own -Help before it ships, and it must do so with no + # interpreter of this job's own involved: this is the file a person double-clicks. + - name: It runs shell: bash run: | sh scripts/run-web.sh -Help > /dev/null @@ -188,24 +81,13 @@ jobs: run: | TAG="${{ github.event.inputs.tag || github.ref_name }}" VERSION="${TAG#v}" - NAME="${STEM}-web-${VERSION}" - ROOT="${STEM}-web" - mkdir -p "dist/${ROOT}" - - # The pack, the launchers and the pin: everything the browser half needs on a - # machine that has Node.js. The Rust app is NOT in here. - cp -R packages scripts "dist/${ROOT}/" - cp .dsh-version.json package.json README.md LICENSE SECURITY.md ARCHITECTURE.md \ - "dist/${ROOT}/" - cp -R docs "dist/${ROOT}/" - - # Build output that a checkout may be carrying is not content. - rm -rf "dist/${ROOT}/scripts/checks/.tmp" - find "dist/${ROOT}" -name '*.log' -delete - - (cd dist && tar -czf "${NAME}.tar.gz" "${ROOT}") - cp "dist/${NAME}.tar.gz" . - echo "ASSET=${NAME}.tar.gz" >> "$GITHUB_ENV" + NAME="${STEM}-${VERSION}" + # `git archive` IS the ship list: every tracked file, with its mode and its + # `.gitattributes` line endings - so `run-web.sh` arrives executable and the batch + # entry points keep the CRLF cmd.exe expects. Nothing untracked can ride along, + # and there is no include list to fall out of step with the tree. + git archive --format=zip --prefix="${NAME}/" -o "${NAME}.zip" HEAD + echo "ASSET=${NAME}.zip" >> "$GITHUB_ENV" - name: Upload env: @@ -216,12 +98,12 @@ jobs: checksums: name: SHA256SUMS.txt - needs: [build, web] + needs: [package] runs-on: ubuntu-latest timeout-minutes: 5 steps: - # A checksum file computed before the last upload is a lie, so this job waits for - # every artefact and re-downloads what was actually published. + # A checksum file computed before the last upload is a lie, so this job waits for the + # artefact and re-downloads what was actually published. - name: Collect and publish SHA256SUMS.txt env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index e32feb2..6990098 100644 --- a/.gitignore +++ b/.gitignore @@ -13,12 +13,11 @@ node_modules/ /.tmp/ *.log -# THE APP'S LAST-RESORT ROOT, beside the checkout. `$VNCODE_HOME` defaults to the -# platform's own per-user data directory and the harness home is `/home` -# inside it; `/.vncode` is only used when even that data root cannot be -# written - which is exactly the workspace-scoped confinement this repository's own -# checks run inside. It holds a whole harness home (sessions, credentials), so it -# must never be committed. Anchored, for the reason the /tools/ rule above records. +# THE PORTABLE HARNESS HOME, beside the checkout. A folder that is a portable +# installation keeps its harness home - sessions, credentials, the installed +# profile - at `/.vncode/home`, and `run-web.*` joins it when it is there. It +# holds a whole harness home, so it must never be committed. Anchored, for the +# reason the /tools/ rule above records. /.vncode/ # A version bump unpacks a throwaway harness install and drives pnpm through a @@ -53,13 +52,6 @@ id_ed25519* # zero npm dependencies); if you ever need a committed one, force-add it. .npmrc -# The shell's Rust build tree (app/). Cargo writes hundreds of megabytes of -# objects and binaries under app/target/, and none of it is content: -# `run-desktop.*` rebuilds it, and a fresh clone builds it once. The rule is -# written as a bare `target/` because a cargo WORKSPACE puts the directory at the -# workspace root, and any crate added under app/crates/ keeps it there. -target/ - # The PROTOTYPING LAB (`dsh-proto-lab`) is a workshop, not an exhibit: `lab_new` # generates runs into `/lab/` for the agent to try things in, and a # repository that accumulated every sketch anyone ever generated would stop being diff --git a/AGENTS.md b/AGENTS.md index 737d728..629604a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,14 +11,12 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an ## Hard rules — do not break these 1. **One install target.** The web profile only. No desktop edition, no - `-Target desktop`, no desktop detection, **no window and no web view**. `app/` is a - **front door** to the same pinned `dsh web`: it decides the root and the home, writes - the key, runs this pack's own installer (`scripts/setup/install.*`, given `-DshHome - `) when that profile lacks the bundles, and then runs - `scripts/run-web.*` — the same launcher a person double-clicks — in the foreground. - It starts no node, binds no port, opens no tab and draws nothing: **the launcher owns - the harness, the ready line and the browser tab.** Launching only the web must keep - working on a machine with no `vncode` at all. + `-Target desktop`, no desktop detection, **no window and no web view** — and no + native code at all: this repository is Node/TS/JS, and a compiler is not among its + build dependencies. `scripts/run-web.*` IS the front door: it decides the home, runs + the pinned `dsh web --no-open`, watches the ready line and opens the tab in Chrome. It + starts no second server, holds no port of its own and draws nothing, and it must keep + working on a machine that has nothing but Node.js and npm. 2. **Nothing patches core.** A row change is a new bundle layer. `dsh-vn-master` is the pack's final layer (it installs last), so pack-wide row patches belong there, and a package that *replaces* a row carries that row's @@ -28,16 +26,14 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an `$PSVersionTable`; never `$IsWindows` unguarded, never a hardcoded `npx.cmd`, `%USERPROFILE%` or `\`). macOS/Linux tooling is POSIX shell and must **never** require PowerShell — Node.js with npm/npx and nothing else. -4. **Launchers.** Every entry point lives in `scripts/`, one per action per host - (`run-web.*`, `run-desktop.*`), and there are **no forwarders**. The install and - uninstall pairs live one level down in `scripts/setup/`, beside the workers they - call, and the app's `install` / `uninstall` verbs run those same entry points. Nothing - else sits at - the top level: `console/` is the shared console layer, `tools/` is - maintainer-only, `checks/` is the contract, and `check-scripts.mjs` fails on a - stray file. On Windows the entry point calls the PowerShell worker beside it (or - the console layer, for the setup pair) and gets its console behaviour from the one - shared layer: +4. **Launchers.** Every entry point lives in `scripts/`, one per host (`run-web.bat` + and `run-web.ps1` on Windows, `run-web.sh` on macOS/Linux), and there are **no + forwarders**. The install and uninstall pairs live one level down in + `scripts/setup/`, beside the workers they call. Nothing else sits at the top level: + `console/` is the shared console layer, `tools/` is maintainer-only, `checks/` is the + contract, and `check-scripts.mjs` fails on a stray file. On Windows the entry point + calls the PowerShell worker beside it (or the console layer, for the setup pair) and + gets its console behaviour from the one shared layer: if not defined VNCODE_CONSOLE set "VNCODE_ARGV=%*" call "%~dp0console\adapt.cmd" "%~f0" "" @@ -49,9 +45,8 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an `theme.sh`. 5. **The launch token is a live credential.** It is read in memory, never written to a file, echoed, or handed to a shell, and a URL that is not loopback is - refused rather than opened. It appears only in `scripts/run-web.ps1` / - `scripts/run-web.sh` — **never in `app/`**, which starts the launcher and reads its - exit code. + refused rather than opened. It appears in exactly two files, `scripts/run-web.ps1` + and `scripts/run-web.sh`, and nowhere else. 6. **No secrets, ever.** Run `node scripts/checks/check-no-secrets.mjs` before pushing. A vendored bundle can ship its author's own credentials: redact them in the **build** (a patch under that engine's `vendor//patches/`, read @@ -59,16 +54,15 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an 7. **Zero npm dependencies** in shipped packages, and no network egress a plugin starts on its own. Engines are vendored under `lib/vendor/` or resolved from the harness already on disk. -8. **CI builds the app; the checks prove it.** `.github/workflows/ci.yml` runs clippy - with warnings denied, the workspace tests, a release build, a **6 MB size ceiling** - and a smoke run - on all three OSes for a pull request, the Monday schedule, a manual - dispatch, and `release.yml`, which calls it as its gate. **A push to `main` starts no - CI at all**: commits and pushes are free, and CI runs at the boundaries (a PR, the - weekly run, or the cut). A release - publishes **two** artefacts: one `vncode` per OS, and one `vncode-web` for the - node/JS half, which is the same bytes everywhere. The checks in `scripts/checks/` - are still run by hand; they are the contract, and `scripts/checks/README.md` lists - them. +8. **CI proves the tree; the checks prove the change.** `.github/workflows/ci.yml` is + one job in a `node:22` container - the runtime `package.json` declares - running + `check-no-secrets.mjs` and `check-scripts.mjs` behind a Node floor assertion. There is + no compiler, no build and no per-OS matrix, because nothing here is native. **A push + to `main` starts no CI at all**: commits and pushes are free, and CI runs at the + boundaries (a PR, a manual dispatch, or the cut). A release publishes **one** + artefact: `vncode-.zip`, a zip of this repository at the tag, which is the + whole distribution. The checks in `scripts/checks/` are still run by hand; they are + the contract, and `scripts/checks/README.md` lists them. ## Layout @@ -158,25 +152,13 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an `dsh-diagrams`, `dsh-frontend-craft`, `dsh-proto-lab`, `dsh-ocr`, `dsh-wsl`, `dsh-docker`, `dsh-ollama` and `dsh-image-upscale`), and the pack-wide checks still own the routes, the bundle and the manifest. -- `scripts/` — the launchers (`run-web.*`, `run-desktop.*`), and four folders: - `console/` (the shared console layer), `setup/` (install and uninstall, which the - app's verbs run), `tools/` (maintainer-only: the fork re-sync for the client bundles - this pack vendors) and `checks/`. -- `app/` — the Rust **front door**: a cargo workspace of three crates whose binary is - `vncode`, about 0.5 MB, with **no window and no web view**. It decides the root its - harness home lives in (`$VNCODE_HOME`, with `DSH_HOME` at `/home` unless a - `-DshHome` or a writable inherited `DSH_HOME` says otherwise — **nothing outside its - own root is ever the home it runs against**), composes every child's environment - rather than inheriting one, cleans every path before it uses one, writes the DeepSeek - key into `/.env` when asked, runs `scripts/setup/install.*` when the profile - lacks the pack, and then runs `scripts/run-web.*` in the foreground. Its verbs are - `start` (default), `install`, `uninstall`, `status` and `key`; `-Mode embed` is - refused **by name**, because there is no embedded browser to select. - `app/README.md` explains it. `check-shell.mjs` is what proves it, and it drives - the real binary. +- `scripts/` — the launcher (`run-web.*`), and four folders: `console/` (the shared + console layer), `setup/` (install and uninstall, which a fresh machine runs once), + `tools/` (maintainer-only: the fork re-sync for the client bundles this pack vendors) + and `checks/`. - `docs/` — install, build, deploy, release, paths, compatibility. There is no - distributer and no ship list: the distribution is this - repository plus the binary, and the app installs the pack itself. + distributer and no ship list: the distribution is this repository, zipped at the tag, + and the pack installs itself with `scripts/setup/install.*`. - `.dsh-version.json` — the pinned harness line and the pack manifest (its versions must match every `package.json`; `check-node-routes.mjs` enforces that). @@ -186,21 +168,14 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an Run the check that owns the area, and say which ones you ran: - `check-no-secrets.mjs` — before anything is pushed; -- `check-scripts.mjs` — the `scripts/` layout, the console contract, and both setup - entry points driven with `-Help` (which installs nothing); +- `check-scripts.mjs` — the `scripts/` layout, the console contract, `run-web.*` and both + setup entry points driven with `-Help` (which starts nothing and installs nothing), and + the two workflows; - `check-node-routes.mjs` — every Node route, the manifest, the pack-wide patches; - `check-client-bundles.mjs` — every browser bundle, loaded and driven for real; - `check-media-node.mjs`, `check-pdf-node.mjs`, `check-browser-node.mjs` — the tool and host halves; -- `check-shell.mjs` — the app, **driven**: the verbs and `-Help`; `-Mode embed` refused - BY NAME (the flag the deleted web view used to answer); a size ceiling a GUI stack - cannot pass; and `start` run against **stub scripts** in a throwaway tree — the - installer is run because that home lacks the pack, the launcher is handed `-DshHome` - and `-NoTerminal` and a **composed** environment, the app's own root and the console - markers are absent from both children, no key file is written with no terminal to ask - at, and `status` names the same home. It also proves `scripts/run-web.* -Help` answers - with no binary involved, and it skips loudly with no cargo and no built binary; - `check-skill-examples.mjs`, `check-media-examples.mjs` — every fenced example in the shipped skills (parsed, compiled, or actually run); - `npm run check` **in a package folder that ships its own** — today diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 9798f44..e637352 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -3,13 +3,11 @@ A plugin pack for **one install target**: the DeepSeek Harness **web** profile (`npx @deepseek-ai/dsh web`, profile `web` under `$DSH_HOME`, default `~/.dsh`). Every plugin here is a standard dsh **bundle**; nothing patches a harness file, -and there is no desktop edition. (`app/` is a *front door*: a small Rust console -program with no window and no web view that decides the root its harness home lives -in — `$VNCODE_HOME`, with the harness's `DSH_HOME` at `/home` unless `-DshHome` -or a writable inherited `DSH_HOME` says otherwise — takes the key, installs the pack, -and then runs `scripts/run-web.*`, the same launcher a person double-clicks. That -launcher owns the harness, the ready line and the browser tab; the app owns none of -them.) +and there is no desktop edition and no native code. `scripts/run-web.*` is the whole +front door: it decides the harness home (a portable `/.vncode/home`, else +`$DSH_HOME`, else `~/.dsh`), runs the pinned `dsh web --no-open`, watches the ready line +and opens that URL in Chrome. It owns the harness, the ready line and the browser tab, +and it is plain Node, batch and POSIX shell — there is nothing to compile. The three planes below are the whole system — what npm ships, what the `web` profile boots, and what the page renders: @@ -103,12 +101,11 @@ disable/replace a core row **in its own layer** — a later layer wins per row. - operations: `docs/INSTALL.md`, `docs/BUILD.md`, `docs/DEPLOY.md`, `docs/RELEASE.md`, `docs/PATHS.md`, `docs/COMPATIBILITY.md`; -- the app: `app/README.md` (the verbs, the bridge to `scripts/run-web.*`, the app's own - root and the harness home inside it, and the three crates); -- the port: `docs/RUST-PORT.md` (the boundary, the phases and their gates) and - `port/README.md` (that folder's rules). `port/` is a **second cargo workspace**, - deliberately separate from `app/` and building nothing that ships yet; +- the launcher: `scripts/run-web.bat` / `run-web.ps1` / `run-web.sh` (the flags, the + home ladder, the ready line and the browser hand-off), and `check-scripts.mjs`, which + drives them; - security: `SECURITY.md`; - **the checks are the contract**: `scripts/checks/*.mjs` pin route registrations, bundle wiring, budgets, the launcher contract and the credential rules. They are run by hand; - CI runs the build, the tests and the size budget. `scripts/checks/README.md` lists them. + CI runs the two that need a runner (`check-no-secrets`, `check-scripts`) in a Node + container. `scripts/checks/README.md` lists them. diff --git a/README.md b/README.md index b1760cc..5884a22 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ # vn-code

- Language: JavaScript Runtime: Node.js Language: Rust License: AGPL-3.0-only Platforms: Windows | macOS | Linux DeepSeek Harness 0.2.0-rc.2 + Language: JavaScript Runtime: Node.js License: AGPL-3.0-only Platforms: Windows | macOS | Linux DeepSeek Harness 0.2.0-rc.2

@@ -22,37 +22,28 @@ ![vncode: the plugin pack, a Node application - the vncode README header](./assets/vncode-banner5.png) -Cross-platform Node ADE with core [DSH](https://www.deepseek.com/harness/en/) for professional Engineering and Design: every plugin is **Node.js** (plain JavaScript bundles, zero npm dependencies), while **Rust** is only the small front-door installer binary that composes the harness home and runs the launcher. The launchers run on **Windows, macOS and Linux**. +Cross-platform Node ADE with core [DSH](https://www.deepseek.com/harness/en/) for professional Engineering and Design: every plugin is **Node.js** (plain JavaScript bundles, zero npm dependencies), and so is every launcher - there is no native code in this repository and nothing to compile. The launchers run on **Windows, macOS and Linux**. ## Run -| | Windows | macOS / Linux | -|---|---|---| -| **The app** | `scripts\run-desktop.bat` | `./scripts/run-desktop.sh` | -| **Browser tab only** | `scripts\run-web.bat` | `./scripts/run-web.sh` | - -`run-web` starts the pinned harness and opens the URL it prints in Chrome, falling back to -your default browser. `run-desktop` builds `vncode` when there is none and runs it: it -installs the pack if the home in use lacks it, asks for the DeepSeek key if there is none, -and then runs that same `run-web` in the foreground. - -`vncode` is a small Rust binary - about **0.5 MB per OS** - with **no window and no embedded -browser**: the interface is the same web application, in the browser you already use. Its -verbs are `start` (the default), `install`, `uninstall`, `status` and `key`; `-Help` lists -the flags, and [`app/README.md`](app/README.md) is the whole app on one page. - -```sh -cd app -cargo build --release --locked # -> app/target/release/vncode (~0.5 MB) -./target/release/vncode status # the pin, the home, the pack, the key, the launcher -./target/release/vncode # install if needed, key if needed, then run-web -./target/release/vncode key # write DEEPSEEK_API_KEY into /.env -./target/release/vncode -Help # every verb and flag -``` - -`vncode` never runs node itself: it starts `scripts/run-web.*`, which does. Nothing it does -needs a window, a port or a browser of its own. +| Windows | macOS / Linux | +|---|---| +| `scripts\run-web.bat` | `./scripts/run-web.sh` | + +`run-web` starts the pinned harness (`npx @deepseek-ai/dsh@ web --no-open`), watches for +the `dsh web:` ready line and opens **that URL** in Google Chrome, falling back to your default +browser. Chrome is looked for on PATH, in the standard install folders, and in the App Paths +registry on Windows; `-DefaultBrowser` skips it and `-NoBrowser` opens nothing. + +The harness runs in the **foreground** of that window: Ctrl+C stops it. A machine needs the +pack installed once - `scripts\setup\install.bat` / `./scripts/setup/install.sh` - and every +run after that is the one file above. `-Help` lists every flag, `-Port ` moves it off the +default 3080, and `-DshHome

` points one run at another harness home. + +The DeepSeek key belongs to the harness, not to the launcher: it resolves `DEEPSEEK_API_KEY` +from the environment, then a `.env` beside the launcher, then `/.env`. Add one in the +harness under **Settings > Models**, or put that line in `/.env`. The URL is opened only when it names a **loopback** address, and the launch token is never written to a file - both rules are in [SECURITY.md](SECURITY.md). @@ -65,36 +56,36 @@ way and what it touches. The exact versions are in | Package | What it adds | |---|---| -| [`dsh-vn-master`](packages/dsh-vn-master/README.md) | the browser-free master, installed **last** - the slot pack-wide patches and row restatements go in (it enables the Browser tab on the web profile, and removes the feedback surface) | -| [`dsh-rightbar`](packages/dsh-rightbar/README.md) | the pack's own right bar: tab strip, docking panel and the `sidebarRight` registry (a fork of the shipped bar) | -| [`dsh-rightbar-files`](packages/dsh-rightbar-files/README.md) | the Files tab type on top of that bar | +| [`dsh-audio`](packages/dsh-audio/README.md) | a waveform surface: WAV/AIFF/FLAC, one track per channel, dBFS, selection and playback | +| [`dsh-browser`](packages/dsh-browser/README.md) | the **Browser** tab, replacing the shipped iframe one: the page is rendered on the host in a disposable engine behind an https-only egress gate (screenshot, post-script text, measured styles) for the tab and for `browser_render` / `browser_query` / `browser_text` — **built and shipped, but turned OFF**: the master layer disables the row, so a profile loads no tab, no routes, no tools and no client bundle | +| [`dsh-cmdbar`](packages/dsh-cmdbar/README.md) | the **command bar**: the agent's own commands in a bottom dock (a read-only transcript of the conversation's log — the terminals were removed in alpha.12; the panel follows whichever conversation is on screen) | +| [`dsh-diagrams`](packages/dsh-diagrams/README.md) | Mermaid, TikZ **and the Diagram Design kit** as tabs *and* seven agent tools — the kit's 204 examples and 44 documented types are vendored at a pinned commit, browsable on the index page, insertable in one call, and every write (a self-contained HTML document included) is validated before it is stored | +| [`dsh-docker`](packages/dsh-docker/README.md) | **Docker (or Podman) as a surface**: nine `docker_*` tools over the machine's own CLI — state, containers, images, inspect, logs, pull, run, lifecycle and a `docker_start` that launches **Docker Desktop** (or a `podman machine`) and waits for its **daemon** — plus a Docker tab listing containers and images with start/stop/remove, pull and run. argv-only, no shell, every removal confirmed by repeating the target, and no spelling for `exec`, `system prune` or `--privileged`. A Docker Desktop that is closed is the normal state on Windows 11: the answer says so and offers the button | | [`dsh-editor`](packages/dsh-editor/README.md) | text and code tabs (vendored CodeMirror 6), with a Markdown preview and Save/Create | +| [`dsh-frontend-craft`](packages/dsh-frontend-craft/README.md) | front-end design craft: **Impeccable's** Apache-2.0 corpus vendored at a pinned commit — 24 commands, 41 references, the craft floor, the four visitor modes and the native platform references — plus its **61-rule detector built to WebAssembly inside the package**, so there is no `npx impeccable`, no engine download and no network. Five `fe_*` tools (`fe_context`, `fe_detect`, `fe_direction`, `fe_artifact`, and `fe_render`, which renders a workspace HTML file or a loopback dev-server URL in the machine's own headless Chrome/Edge and measures contrast, tap targets, overflow, line length, type size, heading order and missing alt), an 18-world local direction deck so the roll always carries a challenger the agent did not write, and a **Frontend** tab with findings, artifacts, the direction round and the rendered picture. The detector's findings match the upstream CLI **186/186** on its own fixtures | | [`dsh-gittree`](packages/dsh-gittree/README.md) | **read-only** History tab: the workspace's commits as a graph rail (lanes, merges, PR chips), and the files each one touched | | [`dsh-image`](packages/dsh-image/README.md) | an image viewer that fits, zooms, pans, and reads the source pixel under the pointer | | [`dsh-image-upscale`](packages/dsh-image-upscale/README.md) | the agent can make a small image **big without making it worse**: four `upscale_*` tools over **Real-ESRGAN** (`realesr-general-x4v3` by default) run through the Python and torch **this machine already has** — `upscale_info` says whether CUDA is there and which models are on disk, `upscale_image` writes a NEW file (never the original) with the model, device, ms and bytes in the answer, `upscale_batch` takes a manifest and is a dry run by DEFAULT (existing outputs skipped, not replaced), and `upscale_fetch_weights` downloads one 4.7 MB model only after `confirm` repeats its name. Zero npm dependencies, no engine bundled, and a four-line `torchvision.transforms.functional_tensor` shim so a `realesrgan` that is broken against torchvision 0.17+ still runs | -| [`dsh-audio`](packages/dsh-audio/README.md) | a waveform surface: WAV/AIFF/FLAC, one track per channel, dBFS, selection and playback | | [`dsh-media`](packages/dsh-media/README.md) | media the agent can work with: `media_probe` / `media_run` / `media_frames` over a **pinned, SHA-256-verified** ffmpeg copy, plus the routes the video tab streams through | -| [`dsh-supercollider`](packages/dsh-supercollider/README.md) | SuperCollider the agent can **play**: ten `sc_*` tools over one long-lived `sclang` session (a warm round trip is ~31 ms, and what the agent defines is still there next call) and a hand-written OSC client to `scsynth`, the installed `.schelp` reference indexed for `sc_help`, the `.scd` file workflow, and **five skills** that teach the language, SynthDefs and live coding — every code example in them compiled by a check. Zero npm dependencies and nothing bundled — it finds the machine's own SuperCollider — and its own UI is one small console tab, with `.scd` files opening in the editor | -| [`dsh-video`](packages/dsh-video/README.md) | a player tab that streams and seeks any video container, with an ffprobe facts panel, chapter jumps and a one-click remux when the browser cannot decode it | -| [`dsh-diagrams`](packages/dsh-diagrams/README.md) | Mermaid, TikZ **and the Diagram Design kit** as tabs *and* seven agent tools — the kit's 204 examples and 44 documented types are vendored at a pinned commit, browsable on the index page, insertable in one call, and every write (a self-contained HTML document included) is validated before it is stored | -| [`dsh-frontend-craft`](packages/dsh-frontend-craft/README.md) | front-end design craft: **Impeccable's** Apache-2.0 corpus vendored at a pinned commit — 24 commands, 41 references, the craft floor, the four visitor modes and the native platform references — plus its **61-rule detector built to WebAssembly inside the package**, so there is no `npx impeccable`, no engine download and no network. Five `fe_*` tools (`fe_context`, `fe_detect`, `fe_direction`, `fe_artifact`, and `fe_render`, which renders a workspace HTML file or a loopback dev-server URL in the machine's own headless Chrome/Edge and measures contrast, tap targets, overflow, line length, type size, heading order and missing alt), an 18-world local direction deck so the roll always carries a challenger the agent did not write, and a **Frontend** tab with findings, artifacts, the direction round and the rendered picture. The detector's findings match the upstream CLI **186/186** on its own fixtures | -| [`dsh-shaders`](packages/dsh-shaders/README.md) | **GLSL that compiles for real**: seven `shader_*` tools drive the browser this machine already has — argv-only, throwaway profile, every name resolved to `NOTFOUND` — and every answer names the rung it **actually reached** (`v1-static` → `v2-compiled` → `v3-drawn` → `v4-measured`), with each diagnostic mapped back onto *your* line numbers and the active uniforms read out of the linked program. Five dialects are kept apart because they are not interchangeable, and **desktop GLSL is refused rather than faked** (ANGLE cannot compile it). `shader_target` emits a standalone web page, a `.frag`+`.vert` pair, **ISF** (which Resolume reads), a FreeFrameGL C++ **scaffold** — never a build, FFGL is a C++ ABI — or Shadertoy names. The corpus is 3.1 MB of pinned MIT shaders: **106 Radiant pages with 79 extracted fragment sources**, **20 reusable GLSL modules, 11 templates, 11 finished pieces and 14 written references** from `shader-skills`, and a 48-link curated index; every byte re-derives **offline** (`vendor/*/build.mjs --check`). A **Shaders** tab draws the live WebGL preview with one slider per `@param`, five skills teach the language and the triage order, and the checks compile **every fragment in both corpora** and draw every finished piece | -| [`dsh-pdf`](packages/dsh-pdf/README.md) | PDF as a surface the agent can read and **scan**, plus a reader tab with thumbnails and bookmarks | +| [`dsh-modal`](packages/dsh-modal/README.md) | the shared dialog surface (`modals`) the pack's controls use | | [`dsh-ocr`](packages/dsh-ocr/README.md) | the agent can read a **picture**: one `ocr` tool over `tesseract` from PATH or — on Windows, with **nothing installed at all** — the OCR engine Windows ships, which rasterizes a PDF page itself. Names the engine, the language and the page count, refuses a language this host has no data for with the list of what it CAN read, and says every answer is a transcription | -| [`dsh-screenshot`](packages/dsh-screenshot/README.md) | **screenshots worth publishing**: four tools over three surfaces and one placement pass — `shot_url` renders a page in a disposable headless Chrome/Edge (a loopback dev server, a workspace `.html`, or a public site **only** with `remote: true`, because every other name resolves to `NOTFOUND`), at a named viewport with `dpr`, `dark`, `fullPage` or `clip: ".card"`, and reports the file's **real** size from its own IHDR; `shot_window` / `shot_screen` capture a **real application window** or the display on Windows through Win32 `PrintWindow` with a screen fallback that names itself and the window's own DPI as the scale; `shot_place` writes `-[-dark].png` plus a manifest and returns the README ``/`` block with alt text required. **No git and no credential**, no bundled engine, no dependency — and **three skills** (`screenshot-surfaces`, `readme-media`, `app-tour`) | -| [`dsh-wsl`](packages/dsh-wsl/README.md) | the **POSIX half of this pack, testable on Windows**: `wsl_status` (the launcher's table decoded from UTF-16, the default distribution marked, and with `probe` whether a distribution can actually run a check), `wsl_run` (one **argv array** in a distribution — no shell string — with a deadline, a tree kill, a 1 MB cap per stream and the exit code in the answer) and `wsl_path` (`C:\…` ⇄ `/mnt/c/…`). It exists so `run-web.sh`, `install.sh` and the `sh` branches of the checks run on the machine that writes them; the launcher's default on a Docker machine is `docker-desktop-data`, so the tools name the distribution they used | -| [`dsh-docker`](packages/dsh-docker/README.md) | **Docker (or Podman) as a surface**: nine `docker_*` tools over the machine's own CLI — state, containers, images, inspect, logs, pull, run, lifecycle and a `docker_start` that launches **Docker Desktop** (or a `podman machine`) and waits for its **daemon** — plus a Docker tab listing containers and images with start/stop/remove, pull and run. argv-only, no shell, every removal confirmed by repeating the target, and no spelling for `exec`, `system prune` or `--privileged`. A Docker Desktop that is closed is the normal state on Windows 11: the answer says so and offers the button | | [`dsh-ollama`](packages/dsh-ollama/README.md) | **Ollama as a measured surface**: five `ollama_*` tools over the machine's own daemon — status (the models on disk, what is **loaded** right now, and `ollama serve` when nothing answers), **one bounded inference** with the token counts and nanosecond durations Ollama reports and nothing in the pack used to read, a **benchmark that refuses fewer than 3 runs** and reports a median with spread (cold vs warm stated at the *first token*, because a cold load never lowers tok/s), A/B and `num_ctx` sweeps, models with pull/delete confirmed by repeating the tag, embeddings with cosine similarity — plus **three skills** (the REST API, the metric arithmetic, the Python client) whose examples a check parses, and a **loopback fence** that refuses a daemon on another machine before any request. A daemon that is down is an answer, not a failure | -| [`dsh-sql-server`](packages/dsh-sql-server/README.md) | **SQL Server as a surface**: seven `sql_*` tools over a container this row owns (the 2022 image, port 1433, a named volume) or the `sqlcmd` already on your PATH, keeping apart the **four facts that fail independently** — a *server*, a *client*, a *listening port*, and the machine-wide **ODBC driver** an application connects with, which no container can supply. `sql_server action=start` waits until the server **answers a `SELECT 1`**, not until the container says running; `sql_driver` changes your machine only when `confirm: "install"` repeats the request; and `sql_script` streams a multi-gigabyte dump through `sqlcmd -i` (stdin silently dropped rows) with BOM-aware code pages for SSMS's UTF-16 and an optional filter that drops the dump's own `CREATE DATABASE` header naming another machine's paths. Two skills, host-only, zero npm dependencies, no bundled engine | +| [`dsh-open-in-app`](packages/dsh-open-in-app/README.md) | *Open In…* patched to open the OS file browser directly | +| [`dsh-pdf`](packages/dsh-pdf/README.md) | PDF as a surface the agent can read and **scan**, plus a reader tab with thumbnails and bookmarks | | [`dsh-proto-lab`](packages/dsh-proto-lab/README.md) | a **prototyping lab** the agent fills: five `lab_*` tools write a run into the workspace's own `/lab///` — p5.js sketches a browser opens, and openFrameworks projects that are three real C++ files (`src/main.cpp`, `src/ofApp.h`, `src/ofApp.cpp`) built with your own projectGenerator and `make`. A **runtime registry** makes a third language one module and one line (Processing in Rust, Cinder), a committed example library sits beside each skill and is driven by the checks, and verification is an explicit ladder — structure, parse, compile, render, measure — whose answer always names the tier that was actually reached. The lab itself is **gitignored**: the bundle ships the generator and the examples, never the runs | | [`dsh-research`](packages/dsh-research/README.md) | research as a **folder you keep**: your instruction and every gate answer recorded **in your own words**, nine `rs_*` tools over an append-only claim and source ledger — `rs_write` refuses until *you* confirm the question, and a claim's quote is checked against its source. Numbers are data (`p = .000` refused), a **method record**'s screening counts cannot increase, and a **disclosure record** must be *complete* — authors, ethics, funding, conflicts, data, AI use — before the submission folder prints it beside the title page, never in the manuscript a reviewer sees. `rs_verify action=calibrate` **measures the reader**, and the tab is rendered and measured in a real browser. Eight skills, an editable tab, no socket, no child process, nothing vendored | -| [`dsh-browser`](packages/dsh-browser/README.md) | the **Browser** tab, replacing the shipped iframe one: the page is rendered on the host in a disposable engine behind an https-only egress gate (screenshot, post-script text, measured styles) for the tab and for `browser_render` / `browser_query` / `browser_text` — **built and shipped, but turned OFF**: the master layer disables the row, so a profile loads no tab, no routes, no tools and no client bundle | +| [`dsh-rightbar`](packages/dsh-rightbar/README.md) | the pack's own right bar: tab strip, docking panel and the `sidebarRight` registry (a fork of the shipped bar) | +| [`dsh-rightbar-files`](packages/dsh-rightbar-files/README.md) | the Files tab type on top of that bar | +| [`dsh-screenshot`](packages/dsh-screenshot/README.md) | **screenshots worth publishing**: four tools over three surfaces and one placement pass — `shot_url` renders a page in a disposable headless Chrome/Edge (a loopback dev server, a workspace `.html`, or a public site **only** with `remote: true`, because every other name resolves to `NOTFOUND`), at a named viewport with `dpr`, `dark`, `fullPage` or `clip: ".card"`, and reports the file's **real** size from its own IHDR; `shot_window` / `shot_screen` capture a **real application window** or the display on Windows through Win32 `PrintWindow` with a screen fallback that names itself and the window's own DPI as the scale; `shot_place` writes `-[-dark].png` plus a manifest and returns the README ``/`` block with alt text required. **No git and no credential**, no bundled engine, no dependency — and **three skills** (`screenshot-surfaces`, `readme-media`, `app-tour`) | +| [`dsh-shaders`](packages/dsh-shaders/README.md) | **GLSL that compiles for real**: seven `shader_*` tools drive the browser this machine already has — argv-only, throwaway profile, every name resolved to `NOTFOUND` — and every answer names the rung it **actually reached** (`v1-static` → `v2-compiled` → `v3-drawn` → `v4-measured`), with each diagnostic mapped back onto *your* line numbers and the active uniforms read out of the linked program. Five dialects are kept apart because they are not interchangeable, and **desktop GLSL is refused rather than faked** (ANGLE cannot compile it). `shader_target` emits a standalone web page, a `.frag`+`.vert` pair, **ISF** (which Resolume reads), a FreeFrameGL C++ **scaffold** — never a build, FFGL is a C++ ABI — or Shadertoy names. The corpus is 3.1 MB of pinned MIT shaders: **106 Radiant pages with 79 extracted fragment sources**, **20 reusable GLSL modules, 11 templates, 11 finished pieces and 14 written references** from `shader-skills`, and a 48-link curated index; every byte re-derives **offline** (`vendor/*/build.mjs --check`). A **Shaders** tab draws the live WebGL preview with one slider per `@param`, five skills teach the language and the triage order, and the checks compile **every fragment in both corpora** and draw every finished piece | | [`dsh-skills`](packages/dsh-skills/README.md) | the **Skills browser**: a header button left of the zoom control opens every skill this conversation loads, with its markdown and inline editing | -| [`dsh-cmdbar`](packages/dsh-cmdbar/README.md) | the **command bar**: the agent's own commands in a bottom dock (a read-only transcript of the conversation's log — the terminals were removed in alpha.12; the panel follows whichever conversation is on screen) | +| [`dsh-sql-server`](packages/dsh-sql-server/README.md) | **SQL Server as a surface**: seven `sql_*` tools over a container this row owns (the 2022 image, port 1433, a named volume) or the `sqlcmd` already on your PATH, keeping apart the **four facts that fail independently** — a *server*, a *client*, a *listening port*, and the machine-wide **ODBC driver** an application connects with, which no container can supply. `sql_server action=start` waits until the server **answers a `SELECT 1`**, not until the container says running; `sql_driver` changes your machine only when `confirm: "install"` repeats the request; and `sql_script` streams a multi-gigabyte dump through `sqlcmd -i` (stdin silently dropped rows) with BOM-aware code pages for SSMS's UTF-16 and an optional filter that drops the dump's own `CREATE DATABASE` header naming another machine's paths. Two skills, host-only, zero npm dependencies, no bundled engine | +| [`dsh-supercollider`](packages/dsh-supercollider/README.md) | SuperCollider the agent can **play**: ten `sc_*` tools over one long-lived `sclang` session (a warm round trip is ~31 ms, and what the agent defines is still there next call) and a hand-written OSC client to `scsynth`, the installed `.schelp` reference indexed for `sc_help`, the `.scd` file workflow, and **five skills** that teach the language, SynthDefs and live coding — every code example in them compiled by a check. Zero npm dependencies and nothing bundled — it finds the machine's own SuperCollider — and its own UI is one small console tab, with `.scd` files opening in the editor | | [`dsh-themes`](packages/dsh-themes/README.md) | header controls (themes incl. Nord/Monokai/Hacker/Cyber, screenshot, page zoom), the Markdown paper, VN branding, and the shipped account-menu Feedback row hidden | | [`dsh-ui-state`](packages/dsh-ui-state/README.md) | the pack's own UI state (zoom, theme, dock, column widths) remembered host-side | -| [`dsh-modal`](packages/dsh-modal/README.md) | the shared dialog surface (`modals`) the pack's controls use | -| [`dsh-open-in-app`](packages/dsh-open-in-app/README.md) | *Open In…* patched to open the OS file browser directly | +| [`dsh-video`](packages/dsh-video/README.md) | a player tab that streams and seeks any video container, with an ffprobe facts panel, chapter jumps and a one-click remux when the browser cannot decode it | +| [`dsh-vn-master`](packages/dsh-vn-master/README.md) | the browser-free master, installed **last** - the slot pack-wide patches and row restatements go in (it enables the Browser tab on the web profile, and removes the feedback surface) | +| [`dsh-wsl`](packages/dsh-wsl/README.md) | the **POSIX half of this pack, testable on Windows**: `wsl_status` (the launcher's table decoded from UTF-16, the default distribution marked, and with `probe` whether a distribution can actually run a check), `wsl_run` (one **argv array** in a distribution — no shell string — with a deadline, a tree kill, a 1 MB cap per stream and the exit code in the answer) and `wsl_path` (`C:\…` ⇄ `/mnt/c/…`). It exists so `run-web.sh`, `install.sh` and the `sh` branches of the checks run on the machine that writes them; the launcher's default on a Docker machine is `docker-desktop-data`, so the tools name the distribution they used | The pack used to ship its own Files panel (`dsh-files`, earlier `dsh-focus`); that was retired when the harness grew a real right Sidebar, and the installer prunes diff --git a/SECURITY.md b/SECURITY.md index b45e025..c2c7221 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,7 +7,7 @@ download below. ## The short version -- **Loopback only.** The app binds `127.0.0.1`; the CLI refuses an all-interfaces +- **Loopback only.** The harness binds `127.0.0.1`; the CLI refuses an all-interfaces bind. Never put it behind a proxy, tunnel, port forward or published container port — that turns an authenticated surface into network-exposed code execution. - **The printed URL is a password** (it carries the launch token). Never paste it @@ -96,98 +96,72 @@ run. ![A sequence diagram of one authenticated call: the page exchanges the launch token for a session cookie, asks a pack route with that cookie, and the gates verify the cookie and the Host/Origin fence before dispatching anything; the alternate region shows the refusal - 401 without a session, 403 for a foreign authority or a cross-site fetch](./assets/security.svg) -## The app's own root, the home inside it, and the browser - -`app/` owns a root — `$VNCODE_HOME` (`%LOCALAPPDATA%\vncode` by default) — and hands -the harness a home inside it, `/home`, as `DSH_HOME`. It does **not** use `~/.dsh` -as a default: that folder belongs to whichever harness used it first, and a home the app -did not create is a home it cannot promise. A candidate is used only after a real write -probe, the first rung of the ladder is a `-DshHome` the person typed (a refusal there -ends the run rather than quietly using another path), and **the app never writes a -note, a log or a record into a home it refused** — the one write it makes outside its own -root is the probe file, created and deleted at the root of a home it is considering, because -"a child can write here" is not knowable any other way. - -**Nothing outside this app's own root is ever the home it runs against.** The harness's own -default, `~/.dsh`, is not a candidate: a folder that carries everything it needs must not reach -into a person's profile to START. It survives as the SOURCE of a one-way **copy** — read, never -written, never run against — offered while it can be read and there is something left to bring, -and the copy's own credentials file is a byte copy behind a second click that this process never -parses. Start installs the pack into the home in use, and the key row asks for the key, which is -what that rung used to exist for. - -Four hardening rules travel with those paths, and each is a `cargo test` case: - -1. **A path is cleaned before it is used** (`userpath.rs`): `~` expanded, relative - resolved against a captured cwd, `.`/`..` folded lexically, a NUL or an empty value - refused by name, and the exported path is the REAL one with the Windows `\\?\` form - stripped. A path that means two things to two processes is how a write lands - somewhere nobody chose. -2. **Only a directory this app CREATED is hardened** to `0700` on Unix — the home holds - `.credentials.yaml`, the root holds an npm cache that can hold registry credentials. - A home the app merely JOINED is never chmodded: it has an owner and a history, and - the probe reports `created` precisely so those two cases cannot be confused. On - Windows nothing is chmodded: the directories live under the user's profile and - inherit its ACL, and a half-written ACL is worse than an inherited one. -3. **Nothing in the preferences can name a program.** `/prefs.json` stores a - browser **id** the table already knows and a home path, both validated on read; a - record this build cannot vouch for (wrong version, unknown id, empty path) is - DISCARDED rather than repaired. This matters because the app runs a program for you: - a stored path would be an execution primitive. -4. **The browser launch is checked at the last moment.** `browser::command` refuses any - URL that is not loopback — the ready line was already checked, and a rule that holds - at one end of a pipe is not a rule — starts a PROGRAM with the URL as exactly one - argv element, and never a shell. On Windows the platform opener is - `rundll32.exe url.dll,FileProtocolHandler`, which is a program rather than a shell; - `explorer.exe` was dropped because it silently did nothing from a child. The - Chrome-first table's last rung is the platform's own opener, so "a browser this build - has never heard of" is still the OS's business rather than a refusal. **The launcher is - the only process that ever hands the token to a browser** — once, in memory, as one argv - element, after the ready line has been checked. The app never holds it: `vncode` starts - the launcher and waits for its exit code. - -**No home is ever read to borrow a key, and nothing is copied out of one.** The first-run -COPY and the "use the existing home" rung left with the panel that offered them: a home -outside this app's own root is now nothing more than the harness's own default that the -launcher falls back to. What replaced them is one prompt. - -**A key never has to come from the machine at all.** `vncode key` asks for it at the -terminal — hidden input, no echo — and `keystate::write_env_key` puts -`DEEPSEEK_API_KEY=` into `/.env` (`0600` on POSIX, atomic). That is a layer -the harness's own resolution reads, it needs no machine credentials, and it keeps the -secret inside the folder. Nothing is read on the way: the prompt is one-way, the value is -not parsed back, not drawn and not logged, and the only thing the app learns afterwards is -which layer a fresh `keystate::read` found a key in. - -Every child's environment is **composed rather than inherited** -(`vn-shell-runtime`'s `env.rs`): `DSH_HOME` is set, the app's own `VNCODE_HOME` and the -launcher's console markers are *removed* — an environment is inherited unless a variable -is removed, a leak that was measured while this was written and is now read back out of -the child by `check-shell.mjs` — and `TMP`/`TEMP`/`TMPDIR` point at `/tmp` when -the machine's own temp refuses a child, which is the case a real log measured (the -harness's spill store died on `mkdtemp`). +## What the launcher touches, and the browser + +`scripts/run-web.*` is a launcher, not a supervisor, and its whole list is short: read the +pin from `.dsh-version.json`, decide the harness home, run the pinned +`npx @deepseek-ai/dsh@ web --no-open` in the **foreground**, read the ready line from +its stdout, and open one URL. It starts no second server, writes no file of its own and +holds no credential. + +**The home ladder is four rungs**, in both workers, and the order is the reason: `-DshHome` +(the person named it for this run), an inherited `DSH_HOME` (a harness session that started +this shell), a portable `/.vncode/home` when the tree carries the `PORTABLE` marker or +already holds a home, and `~/.dsh` - the harness's own default. A portable installation +keeps the pack, the sessions and the key inside the folder, so nothing lands in the user's +profile; `check-scripts.mjs` reads both workers for the marker and the `home` folder so the +rule cannot drift out of one of them. + +**The environment is inherited, not composed.** The launcher hands the harness the +environment it was started with, so an exported `DEEPSEEK_API_KEY` reaches it exactly as it +would from a terminal. Nothing is copied between homes: a home outside this tree is only +ever the harness's own default that the launcher falls back to, and no file is read to +borrow a key from one. + +Three rules the launcher holds, each the fact a future editor must not break: + +1. **The ready line is read, never guessed.** The harness prints one line, `dsh web: `, + and the launcher takes the FIRST URL out of a line that names `dsh web:`, with ANSI + colour stripped first - so an unrelated URL in the output is never mistaken for the tab. + The token is read in memory: it is never written to a file, never echoed, and never put + in a child's environment. +2. **Only a loopback URL is opened.** The check runs immediately before the browser starts, + on the parsed host - a rule that holds at one end of a pipe is not a rule - and a line + naming any other authority is refused rather than opened. That is what keeps a launch + token from being handed to a browser pointed at somebody else's machine. +3. **The URL is one argv element, never a shell.** Chrome is started with the URL as a + single argument, and the default-browser fallback goes through the platform opener + (`ShellExecute`, `open`, `xdg-open`) with that same single argument. No shell is + involved, so nothing in a URL can be read as a metacharacter. + +**The key is the harness's, not the launcher's.** No command of this pack asks for it: the +harness resolves `DEEPSEEK_API_KEY` from its own environment, then a `.env` beside the +launcher, then `/.env`, and the launcher inherits whatever the person's shell has. +A key is added in the harness itself under **Settings > Models**, or by putting that line in +`/.env` - a layer the harness's own resolution reads, which keeps the secret inside +the folder and out of this repository. ## There is no embedded engine -The app draws no web view, and that is a security decision as much as a size one. `wry`, -WebView2, WKWebView and WebKitGTK were all deleted with the pane, so: +Nothing in this repository draws a page, and that is a security decision as much as a +packaging one. The harness is a **web application**; the pack adds bundles to it and a +launcher that opens it: -- the launch token reaches **one program**: the browser the person already runs, as one - argv element, from the launcher — not an engine inside this process; -- there is no engine profile under the app's root to keep a browsing record, because there +- the launch token reaches **one program**: the browser the person already runs, as one argv + element, from the launcher - not an engine inside this process; +- there is no engine profile anywhere in this tree to keep a browsing record, because there is no engine. A browser keeps its own history, in its own profile, where the person can see and manage it; - there is no IPC channel, no injected script, no download handler, no permission handler and no navigation handler to audit, because there is no page in this process to attach them to. The whole class of "the engine recorded the token" findings is gone rather than - mitigated: **measured**, after a single load of the harness a `wry` build had the full URL - — token and all — in `History`, `Favicons` and `Top Sites` inside its own profile; -- the app's attack surface is the four things it does: write `.env`, run - `scripts/setup/install.*`, run `scripts/run-web.*`, and read the pin. + mitigated: **measured**, after a single load of the harness a web-view build had the full + URL - token and all - in `History`, `Favicons` and `Top Sites` inside its own profile; +- the launcher's attack surface is the four things it does: read the pin, decide the home, + run `npx @deepseek-ai/dsh@ web`, and open one loopback URL. -The one rule that used to be about the pane survives, and now belongs to the launcher: only -a **loopback** URL is ever opened, checked in the launcher immediately before the process -starts. +The one rule that outlived every pane: only a **loopback** URL is ever opened, checked in +the launcher immediately before the browser starts. ## Code execution this pack adds on purpose @@ -214,7 +188,7 @@ should be read as such: 1. **Never expose the port.** No `--host`, no proxy, no tunnel, no published container port, no reverse proxy — this route is what makes "LAN-exposed" mean "remote code execution as you", not "someone can read my conversation". -2. **Stop the app when you are done**, and treat the printed URL as a password (a leaked +2. **Stop the harness when you are done**, and treat the printed URL as a password (a leaked URL buys a cookie, and a cookie buys `eval`). 3. **Uninstall the package if you do not use SuperCollider** — a row you never open is still a route that is mounted. @@ -227,13 +201,13 @@ should be read as such: 1. **Keep it on loopback**: the pack's launcher or `npx @deepseek-ai/dsh@0.2.0-rc.2 web`, no `--host`, no `--trusted-host`. Loopback traffic does not cross a firewall, so no firewall rule "fixes" an exposed bind. -2. **Treat the printed URL as a password**, and stop the app when you are not using +2. **Treat the printed URL as a password**, and stop the harness when you are not using it. -3. **Know what logs out**: stopping the app kills the launch token; deleting the +3. **Know what logs out**: stopping the harness kills the launch token; deleting the site's cookies ends that browser's session; a **different port** invalidates cookies (name and audience derive from `host:port`); a plain restart does **not** log anyone out — the signing secret is durable. -4. **Rotate the secret** to revoke every cookie at once: stop the app, delete +4. **Rotate the secret** to revoke every cookie at once: stop the harness, delete **only** the `client-connection/browser-session` entry from `$DSH_HOME/.credentials.yaml` (it also holds your model keys), save, restart. To shorten sessions instead, set `cookieMaxAgeDays` on the `connection` row in @@ -333,19 +307,13 @@ scanning and push protection as a second net. ## What the pack does not do - No API keys are read: `$DSH_HOME/.credentials.yaml` is touched for **presence** - only — a boolean, never a value. `vncode key` is the same rule from the other - side: a value the person TYPES at the prompt is written to `/.env` as - `DEEPSEEK_API_KEY`, which the harness's own credential resolution reads as a documented - fallback layer (`@deepseek-ai/dsh-credentials-local`: the managed store first, then the - invoking project's `.env`, then the home's). The managed document is **never written by - this app** — it is a strict `CredentialRef`-to-string YAML the harness refuses to boot on - when it is malformed or readable beyond its owner. What the prompt guarantees, and what - `keystate::write_env_key` is: the value is hidden as it is typed, held in memory only while - the prompt is open, never parsed back, never held in a `KeyState`, never drawn, never - logged (the log line and the note name the FILE), written atomically with `0600` on Unix, - and every other line of an existing `.env` is preserved. A value that cannot be carried - unambiguously (a newline, a quote, a backslash) is refused by name, and the sentence - names the reason and never the value. + only — a boolean, never a value. The DeepSeek key is the harness's own business: it + resolves `DEEPSEEK_API_KEY` from its own environment, then a `.env` beside the + launcher, then `/.env` (`@deepseek-ai/dsh-credentials-local`: the managed store + first, then the invoking project's `.env`, then the home's), and no command in this + repository prompts for one or writes one. The managed document is **never written by + this pack** — it is a strict `CredentialRef`-to-string YAML the harness refuses to boot + on when it is malformed or readable beyond its owner. - No way to weaken the harness's authentication, and no flag, setting or variable that turns the session check off. - No WebSocket upgrade and **no shell of its own** — the dock is a read-only diff --git a/app/Cargo.lock b/app/Cargo.lock deleted file mode 100644 index e70b073..0000000 --- a/app/Cargo.lock +++ /dev/null @@ -1,164 +0,0 @@ -# This file is automatically @generated by Cargo. -# It is not intended for manual editing. -version = 4 - -[[package]] -name = "itoa" -version = "1.0.18" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" - -[[package]] -name = "libc" -version = "0.2.190" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78" - -[[package]] -name = "memchr" -version = "2.8.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" - -[[package]] -name = "proc-macro2" -version = "1.0.107" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" -dependencies = [ - "unicode-ident", -] - -[[package]] -name = "quote" -version = "1.0.47" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" -dependencies = [ - "proc-macro2", -] - -[[package]] -name = "rpassword" -version = "7.5.4" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2da316a15f47e3d053de9cb2c439650bd8fa4aaeb9365f2e5f27f492ff73c196" -dependencies = [ - "libc", - "rtoolbox", - "windows-sys", -] - -[[package]] -name = "rtoolbox" -version = "0.0.6" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9a1efe12a1469752d0e6ff5ebec0b6ef4924cc5c4c71046b0ec730040535819d" -dependencies = [ - "libc", - "windows-sys", -] - -[[package]] -name = "serde" -version = "1.0.229" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" -dependencies = [ - "serde_core", -] - -[[package]] -name = "serde_core" -version = "1.0.229" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" -dependencies = [ - "serde_derive", -] - -[[package]] -name = "serde_derive" -version = "1.0.229" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" -dependencies = [ - "proc-macro2", - "quote", - "syn", -] - -[[package]] -name = "serde_json" -version = "1.0.154" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" -dependencies = [ - "itoa", - "memchr", - "serde", - "serde_core", - "zmij", -] - -[[package]] -name = "syn" -version = "3.0.9" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" -dependencies = [ - "proc-macro2", - "quote", - "unicode-ident", -] - -[[package]] -name = "unicode-ident" -version = "1.0.27" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" - -[[package]] -name = "vn-shell" -version = "0.1.2" -dependencies = [ - "rpassword", - "vn-shell-core", - "vn-shell-runtime", -] - -[[package]] -name = "vn-shell-core" -version = "0.1.2" -dependencies = [ - "serde_json", -] - -[[package]] -name = "vn-shell-runtime" -version = "0.1.2" -dependencies = [ - "serde_json", - "vn-shell-core", -] - -[[package]] -name = "windows-link" -version = "0.2.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" - -[[package]] -name = "windows-sys" -version = "0.61.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" -dependencies = [ - "windows-link", -] - -[[package]] -name = "zmij" -version = "1.0.23" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/app/Cargo.toml b/app/Cargo.toml deleted file mode 100644 index 77aac67..0000000 --- a/app/Cargo.toml +++ /dev/null @@ -1,44 +0,0 @@ -[workspace] -resolver = "2" -members = [ - "crates/vn-shell-core", - "crates/vn-shell-runtime", - "crates/vn-shell", -] - -# One pin per dependency, so the shell cannot end up with two of anything. The -# binary is `vncode` because that is the name the distribution ships and the -# launcher looks for. -[workspace.package] -version = "0.1.2" -edition = "2021" -license = "AGPL-3.0-only" -publish = false -rust-version = "1.95" - -[workspace.dependencies] -vn-shell-core = { path = "crates/vn-shell-core" } -vn-shell-runtime = { path = "crates/vn-shell-runtime" } - -serde_json = "1" - -# The ONE dependency this app has that is not `std` plus JSON, and it is about a secret: -# the DeepSeek key is typed at a terminal, so the terminal must not echo it. ~10 KB, three -# platforms, no transitive tree. -rpassword = "7" - -# THERE IS NO WEB ENGINE IN THIS WORKSPACE, and no GUI toolkit either - as a rule rather -# than a default. `wry` (WebView2 / WKWebView / WebKitGTK), `egui`, `eframe` and `wgpu` -# left with the window they drew: they were 13 of this binary's 15 MB. The page is the -# harness's, it is served on loopback, and the browser that shows it is started by -# `scripts/run-web.*`. - -[profile.release] -# What the shipped binary is built with - and the settings are a size decision, measured. -# `strip` removes what nothing reads; `lto = "thin"` pays for itself by removing duplicate -# generic instantiations across crates; `panic = "abort"` drops the unwinding tables a -# console app never uses. `codegen-units = 1` is what makes LTO able to see everything. -lto = "thin" -strip = "symbols" -panic = "abort" -codegen-units = 1 diff --git a/app/README.md b/app/README.md deleted file mode 100644 index 06565dd..0000000 --- a/app/README.md +++ /dev/null @@ -1,106 +0,0 @@ -# `app/` - the vncode front door - -One small console program (~0.5 MB) with no window and no web view. It decides four things -- the root, the harness home, the key and the pack - and then it runs the script a person -would run: `scripts/run-web.bat` on Windows, `scripts/run-web.sh` everywhere else, in the -foreground, with a composed environment and `-DshHome` so both halves agree about which -home is in use. - -It is **not** a desktop edition and not a second harness: `scripts/run-web.*` needs none of -this and works on its own. What the app adds is one command from nothing to a served page. - -```sh -cargo build --release --locked # in this folder; the binary is target/release/vncode -./target/release/vncode status # the facts, and nothing started -./target/release/vncode # install if needed, key if needed, then run-web -./target/release/vncode -Help # the verbs and flags -``` - -`scripts\run-desktop.bat` / `./scripts/run-desktop.sh` build it when it is missing and then -run it. A build needs the **Rust toolchain** ([rustup.rs](https://rustup.rs)) and nothing -else: there is no system library to install, which is what the size cut bought. - -## What it does - -| verb | what happens | -|---|---| -| *(none)* / `start` | **one press to a working instance.** If the home in use does not list the pack's bundles, `scripts/setup/install.*` runs first - it re-links the profile, so it must not run under a live harness, and nothing is running yet. Then, if no DeepSeek key is found in any of the four layers, it is asked for at the terminal (a piped run never blocks: it says so and continues). Then `scripts/run-web.*` is started in the foreground and owns everything from there | -| `install` / `uninstall` | the matching `scripts/setup/*` entry point, in this console, with the same environment the launcher gets | -| `status` | the pin, the root, the home and why it was chosen, the pack, which key layer answered, where the launcher is, and `node`/`npx` - then exits without starting anything | -| `key` | asks for `DEEPSEEK_API_KEY` and writes it into `/.env`. The value goes from the terminal into one file and nowhere else: it is not printed, not logged, and not read back. The sentence names the FILE | - -Flags: `-Port ` (handed to the launcher), `-DshHome `, `-DshVersion `, -`-Help`, `-Version`. There is **no `-Mode`**: `panel`, `chrome`, `headless` and `embed` -described a window this build does not have, and `-Mode embed` now fails *by name* rather -than quietly selecting a browser - a flag that silently means something else is a flag -nobody can trust. - -## The bridge - -``` -vncode ──spawn──▶ scripts/run-web.bat|.sh ──npx──▶ dsh web --no-open --port N - │ │ - │ └─ watches the ready line, opens the tab (Chrome first) - └─ composed env: DSH_HOME, npm cache, temp; VNCODE_* removed -``` - -The app never starts node, never binds a port, and never touches the launch token. The -`-NoTerminal` flag it passes on Windows is the one that matters: without it the console -layer may relaunch the run into a Windows Terminal window this process would not wait for, -and the app would report an instant, silent success. - -**The port is the app's own.** `-Port ` when a person names one, otherwise a free -loopback port - **never the shared 3080**, which is what every `dsh web` on the machine -reaches for. That is a measured rule, not a preference: the first real run of this binary -asked for 3080 on a machine whose harness was already answering there and died with -`EADDRINUSE`; on a machine where 3080 is free, the same request would share an origin with -a process whose launch token this run does not have. A free port costs nothing because the -launcher opens the tab itself with the token in it. `-Port 3080` is how to ask for the -shared origin on purpose. - -## The crates - -| crate | what it is | -|---|---| -| `crates/vn-shell-core` | the **pure** halves, each driven by `cargo test`: `home` (the two ladders), `appdata` (the root, the home inside it, the write probe, the npm cache), `userpath` (what a person typed, turned into a path a child may be given), `keystate` (the four key layers, presence only), `launch` (the pin and the tree's own root), `readyline` (the token, and its redaction), `options` (the verbs and flags), plus `ports`, `prefs`, `profile`, `log` | -| `crates/vn-shell-runtime` | the decided facts: `plan` (which home, which pin, which cache, which temp), `env` (the one composer every child's environment comes from) and `setup` (the runner behind `install`/`uninstall`) | -| `crates/vn-shell` | the binary (`vncode`): the verbs, the key prompt and the bridge | - -The load-bearing modules were **moved** from the old Tauri launcher rather than rewritten, -comments and tests included: `readyline.rs`, `keystate.rs` and `appdata.rs` are each the -record of a bug that was measured on a real machine. - -## The modules that are gone, and why they are not coming back - -`wry` (and with it WebView2, WKWebView and WebKitGTK), `egui`/`eframe`/`wgpu`/`winit`, the -panel, the window record, the first-run cards, the browser table and the location map: 13 -of this binary's former 15 MB, and every one of them existed to draw something that is not -this app's to draw. The interface is a web application served on loopback; the browser -already on the machine shows it. - -The size is enforced rather than hoped for: CI fails a build over **6 MB**, and -`check-shell.mjs` fails over 12 MB. A dependency that draws a window or a web view is the -only way back over either line. - -## The rules that must survive any edit - -1. **The key is never printed.** A layer NAME, never a value; written to one file, `0600` - on POSIX, atomically, and never read back. -2. **A child's environment is composed, not inherited.** A variable that is merely unset is - still inherited - which is how `VNCODE_HOME` once reached the harness, and how a leaked - `VNCODE_CONSOLE` once turned `-Help` into a full install. -3. **The launcher is the only thing that starts node**, and it is the same file a person - runs. If the app needs a harness command, it asks `scripts/run-web.*`, never a copy. -4. **The token is not this app's business.** It is read in memory by the launcher, opened - only on a loopback host, and handed to a browser as one argv element. - -## Files - -| Path | What it is | -|---|---| -| `Cargo.toml` | the workspace: three crates, two dependencies (`serde_json`, `rpassword`), and the release profile the shipped binary is built with (`lto`, `strip`, `panic = "abort"`, one codegen unit) | -| `crates/vn-shell/src/main.rs` | the verbs, the key prompt, the bridge | -| `crates/vn-shell-runtime/src/lib.rs` | `plan`: the home, the pin, the cache, the temp, and the notes | -| `crates/vn-shell-runtime/src/env.rs` | the ONE composer: what is set, what is removed, the working directory | -| `crates/vn-shell-runtime/src/setup.rs` | the runner behind `install` and `uninstall` | -| `crates/vn-shell-core/src/*.rs` | the pure rules, one module per question, each with its tests | diff --git a/app/crates/vn-shell-core/Cargo.toml b/app/crates/vn-shell-core/Cargo.toml deleted file mode 100644 index 05aa8f0..0000000 --- a/app/crates/vn-shell-core/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "vn-shell-core" -description = "The vncode shell's pure half: the home ladders, the key layers, the ready line, the pin and the flags." -version.workspace = true -edition.workspace = true -license.workspace = true -publish.workspace = true -rust-version.workspace = true - -[dependencies] -serde_json.workspace = true diff --git a/app/crates/vn-shell-core/src/appdata.rs b/app/crates/vn-shell-core/src/appdata.rs deleted file mode 100644 index 2d6d1c8..0000000 --- a/app/crates/vn-shell-core/src/appdata.rs +++ /dev/null @@ -1,629 +0,0 @@ -//! Where THIS application keeps its own data, and where the harness home lives. -//! -//! Since M0 the app owns a root — `$VNCODE_HOME` — and the harness home is a -//! directory *inside* it: -//! -//! ```text -//! $VNCODE_HOME the app's root: furniture the app owns -//! ├── window.json the geometry record -//! ├── prefs.json the browser and the home this person chose -//! ├── npm-cache/ the npx fallback's cache -//! └── home/ DSH_HOME by default: everything that matters -//! ├── profiles/ sessions/ storages/ attachments/ skills/ -//! └── .credentials.yaml -//! ``` -//! -//! ## One root, and the portable one -//! -//! Everything the app owns lives under ONE root - the geometry, `prefs.json`, the npm -//! cache and the home - so a folder can be picked up and moved, and so a root the app -//! could not write (a confined run, a read-only mount) never splits the app's memory -//! in two. `/.vncode` is that root when the folder is a **portable -//! installation**: it carries the marker, or it already holds a home (see -//! [`portable_root`]). A folder that is neither uses the platform's own data root, -//! and the app's own home inside it. -//! -//! The furniture sits outside the home because the app must not write its own -//! records into a home it did not create, and because `-DshHome` may point at a -//! folder shared with `scripts\run-web.bat`. `home.rs` owns the order and the proof; -//! this module answers "where does this platform put per-user data", "what is inside -//! a root", and "can this account actually write there". -//! -//! ## Why the npm cache is not the machine's shared one -//! -//! `npx` writes to `%LOCALAPPDATA%\npm-cache` by default, and that directory is a -//! shared, machine-wide resource that other tooling - and an ELEVATED run of -//! anything, this shell included - also writes to. Measured on the machine this was -//! written on: after one run "as Administrator", twelve files inside that cache -//! were owned by `BUILTIN\Administrators` rather than the signed-in user, and the -//! next ordinary (non-elevated) run failed with -//! -//! ```text -//! npm error code EPERM -//! npm error path ...\npm-cache\_cacache\tmp\7493d7c0 -//! npm error Log files were not written due to an error writing to the -//! directory: ...\npm-cache\_logs -//! ``` -//! -//! which is a permission failure the reader is told to fix by running as -//! Administrator - the wrong lesson twice over: this shell never needs elevation, -//! and taking that advice makes the problem worse by writing MORE files as the -//! elevated account. -//! -//! Pointing the cache at this application's own directory removes the shared -//! resource from the equation: the bytes are written under the application's own -//! root, by the account actually running it, and a cache left behind by an elevated -//! run elsewhere cannot poison an ordinary one. It also keeps the cache prunable -//! with the rest of the application's data. -//! -//! This is also half of the reason the VENDORED runtime is preferred at launch -//! (see `launch`): a vendored runtime reads no cache at all, so on that path npm is -//! not merely redirected, it is never started. -//! -//! ## It is not `$DSH_HOME` -//! -//! The OS's own per-user data directory, deliberately: this is the application's -//! own state, not the harness's, and it must survive a `-DshHome` that points -//! somewhere unusual - and a run with no `DSH_HOME` at all, where the harness -//! applies its own default and this shell has nothing to do with it. - -use std::path::{Path, PathBuf}; - -/// The per-user data root for this application on this platform. -pub fn data_root() -> Option { - if cfg!(windows) { - let local = std::env::var("LOCALAPPDATA").ok().filter(|value| !value.trim().is_empty()); - return local.map(PathBuf::from).or_else(|| { - std::env::var("USERPROFILE") - .ok() - .filter(|value| !value.trim().is_empty()) - .map(|home| PathBuf::from(home).join("AppData").join("Local")) - }); - } - if cfg!(target_os = "macos") { - return std::env::var("HOME") - .ok() - .filter(|value| !value.trim().is_empty()) - .map(|home| PathBuf::from(home).join("Library").join("Application Support")); - } - std::env::var("XDG_DATA_HOME") - .ok() - .filter(|value| !value.trim().is_empty()) - .map(PathBuf::from) - .or_else(|| { - std::env::var("HOME") - .ok() - .filter(|value| !value.trim().is_empty()) - .map(|home| PathBuf::from(home).join(".local").join("share")) - }) -} - -/// The per-OS npm cache ROOT - where `npx` unpacks the packages it runs. -/// -/// Not the same thing as [`npm_cache_dir`], which is the cache this shell makes npm -/// use. This one is the machine's own, and it is read for one reason: the harness -/// ALREADY installed there can be run without npm at all (see -/// `launch::installed_harness`). -pub fn npx_cache_root() -> Option { - if cfg!(windows) { - std::env::var_os("LOCALAPPDATA").map(|base| PathBuf::from(base).join("npm-cache")) - } else { - std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".npm")) - } -} - -/// This application's root under a platform data root: `/vncode`. -pub fn root_in(data_root: &std::path::Path) -> PathBuf { - data_root.join("vncode") -} - -/// The app's root, first match winning: `VNCODE_HOME`, then the platform's own -/// per-user data root. -/// -/// This is ONE CANDIDATE, not the decision: `home::root_candidates` walks the whole -/// ladder (`VNCODE_HOME`, a portable folder's own root, this, then the folder beside -/// the tree) and probes each rung by writing. What this function is still the answer -/// to is "where is the record that outlives every root" - the platform copy of -/// `prefs.json` is read as a fallback when the ladder's own root has none, and that is -/// the only reason it is asked before the ladder runs. -/// -/// `None` means neither is available. `home.rs` answers that with the tree-adjacent -/// candidate and then a named failure - never with a guess. -pub fn app_root_with(named: Option<&str>, data_root: Option<&std::path::Path>) -> Option { - if let Some(named) = named { - let named = named.trim(); - if !named.is_empty() { - return Some(PathBuf::from(named)); - } - } - data_root.map(root_in) -} - -/// [`app_root_with`] against this process's own environment. -pub fn app_root() -> Option { - app_root_with(std::env::var("VNCODE_HOME").ok().as_deref(), data_root().as_deref()) -} - -/// The root beside the tree: `/.vncode`. -/// -/// The last root candidate, and the only one a workspace-scoped confinement (this -/// repository's own checks run inside one) always grants. `.gitignore` carries the -/// rule that keeps it out of a commit. -pub fn tree_root(tree: &std::path::Path) -> PathBuf { - tree.join(".vncode") -} - -/// The harness home inside a root: `/home`. -pub fn owned_home(app_root: &std::path::Path) -> PathBuf { - app_root.join("home") -} - -/// The marker a person (or this app's own button) leaves to say **keep everything -/// in this folder**: `/.vncode/PORTABLE`. -/// -/// It is a FILE, not the folder, because the folder is created by anything that -/// falls back to it - including a confined run, which is exactly the case where a -/// last-resort root must not quietly become a policy. The marker is a decision. -pub const PORTABLE_MARKER: &str = "PORTABLE"; - -/// The portable marker inside a tree's own root: `/.vncode/PORTABLE`. -pub fn portable_marker(tree: &std::path::Path) -> PathBuf { - tree_root(tree).join(PORTABLE_MARKER) -} - -/// **The tree's own root, when this folder is a portable installation.** -/// -/// Two facts make it one, and the first is what makes a folder "remembered next -/// time" without anybody pressing anything: -/// -/// * the marker is there (`/.vncode/PORTABLE`) - the explicit choice, written by -/// the panel's own button; or -/// * the folder already holds a home (`/.vncode/home`) - the app has ALREADY put -/// this person's sessions, skills and profile there, so preferring the platform's -/// data directory now would silently start a second installation beside it. That is -/// the measured state of a machine whose app root fell through to the tree under a -/// confinement: the next ordinary double-click must use that home, not a new one. -/// -/// Read only: nothing here creates the folder or the marker. `mark_portable` does -/// that, and only on a click. -pub fn portable_root(tree: &std::path::Path) -> Option { - let root = tree_root(tree); - if portable_marker(tree).is_file() || owned_home(&root).is_dir() { - Some(root) - } else { - None - } -} - -/// Make this folder a portable installation: create its root and write the marker. -/// -/// Returns the root that the NEXT start will use. The running app cannot move its own -/// root (the home, the geometry and the preferences all live in it), which is why the -/// panel says "restart" rather than pretending the click took effect now. -pub fn mark_portable(tree: &std::path::Path) -> Result { - let root = tree_root(tree); - std::fs::create_dir_all(&root) - .map_err(|error| format!("could not create {}: {error}", root.display()))?; - let marker = portable_marker(tree); - std::fs::write(&marker, b"portable\n") - .map_err(|error| format!("could not write {}: {error}", marker.display()))?; - Ok(root) -} - -/// A scratch directory this application owns, under its own root: `/tmp`. -/// -/// Used only when the machine's own temp is not writable by a CHILD of this app - -/// measured, from a log of a real run: the harness's `dsh-spill-local` row died with -/// `EPERM: operation not permitted, mkdtemp 'C:\Users\…\AppData\Local\Temp\dsh-spill-XXXXXX'` -/// and the entry that owned it did not activate. The child had inherited `TEMP`, and -/// the confinement that grants this app its own root does not necessarily grant -/// `%TEMP%` to a process under it. -pub fn owned_temp(app_root: &std::path::Path) -> PathBuf { - app_root.join("tmp") -} - -/// The machine's own temp directory, as the CHILD would inherit it. -/// -/// `TMPDIR` first (Node's `os.tmpdir()` on POSIX), then `TMP`, then `TEMP` - the same -/// order Node uses, because the child is a Node program and that is the variable it -/// will read. -pub fn machine_temp() -> Option { - for name in ["TMPDIR", "TMP", "TEMP"] { - if let Some(value) = std::env::var_os(name) { - if !value.is_empty() { - return Some(PathBuf::from(value)); - } - } - } - None -} - -/// The npm cache this application owns, under its own root. -/// -/// `/npm-cache` - `%LOCALAPPDATA%\vncode\npm-cache` by default, the -/// directory the EPERM bug below moved it to. It follows `VNCODE_HOME`, because it -/// is the app's furniture, and it does NOT follow `-DshHome`. -pub fn npm_cache_dir(app_root: &std::path::Path) -> PathBuf { - app_root.join("npm-cache") -} - -/// What a probe found, and whether it had to create the directory to find it. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Probed { - /// The path, in its real form ([`crate::userpath::canonical`]). - pub path: PathBuf, - /// Whether THIS probe created the directory. Only a directory this app created - /// is ever hardened - see [`harden_if_created`]. - pub created: bool, -} - -/// Whether this application can actually WRITE in a directory, right now - and the -/// error when it cannot. -/// -/// The probe is the operation itself: create the directory, write a file, remove it. -/// A permission bit is not the question and neither is `exists()`; the failures this -/// answers are `EPERM` from npm inside a directory that exists and looks like ours, -/// a read-only mount, and a parent process that confines what its children may write. -/// -/// The path it returns is the REAL one (`userpath::canonical`), because that is what -/// gets exported to the harness and recorded in the panel: two spellings of one home -/// must not look like two homes, and the Windows verbatim form must never reach a -/// child. -pub fn probe(directory: &Path) -> Result { - let created = !directory.exists(); - std::fs::create_dir_all(directory) - .map_err(|error| format!("{} could not be created: {error}", directory.display()))?; - let probe = directory.join(format!(".vncode-write-probe-{}", std::process::id())); - match std::fs::write(&probe, b"probe") { - Ok(()) => { - let _ = std::fs::remove_file(&probe); - } - Err(error) => return Err(format!("{} is not writable: {error}", directory.display())), - } - let path = crate::userpath::canonical(directory); - harden_if_created(&path, created); - Ok(Probed { path, created }) -} - -/// Tighten a directory this app CREATED, and only one it created. -/// -/// On Unix the harness home is set to `0700`, because it holds `.credentials.yaml` -/// (the harness itself refuses to boot if that file is group- or other-readable) and -/// the app root holds an npm cache, which can hold registry credentials. The default -/// `0755 & !umask` is a wider door than either needs. -/// -/// Two deliberate limits: -/// -/// * **A directory this app JOINED is never touched.** Tightening `~/.dsh` because -/// somebody pointed the app at it would be editing a directory that has an owner, -/// a history and possibly other tools inside it. `created` is what keeps that -/// honest, and it is why the probe reports it. -/// * **On Windows this does nothing.** The directories the app creates live under -/// the user's own profile and inherit its ACL; rewriting ACLs would need rights -/// this pack refuses to ask for, and a half-set ACL is worse than an inherited one. -pub fn harden_if_created(path: &Path, created: bool) { - if !created { - return; - } - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt; - let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700)); - } - #[cfg(not(unix))] - { - let _ = path; - } -} - -/// [`probe`] as a boolean, for callers that only need the answer. -pub fn is_writable(directory: &Path) -> bool { - probe(directory).is_ok() -} - -/// Whether the harness home can be written in - asked of the home ITSELF. -/// -/// It used to be asked of `/vncode`, because that is where this app kept its -/// own file inside a home it did not own. It keeps nothing there any more (the -/// furniture lives under `$VNCODE_HOME`), and probing a subdirectory would CREATE a -/// directory inside a home that is about to be refused - a side effect on somebody -/// else's tree. So the probe writes one transient file at the home's own root and -/// removes it, and a refused candidate is left exactly as it was found. -/// -/// This is the check that turns "Start, then wait three minutes for a ready line that -/// cannot come" into one instant sentence. The harness composes its profile into -/// `/profiles//` on every boot, so a home this account cannot write in -/// means the harness CANNOT start - whatever the reason: an ACL an elevated run left -/// behind, a read-only mount, or a parent process that confines what its children may -/// write. -pub fn harness_home_is_writable(home: &std::path::Path) -> bool { - probe(home).is_ok() -} - -/// Whether a cache directory is one npm can actually use. -/// -/// NOT the cache root, and this is the whole reason the function exists. npm writes -/// every payload into `/_cacache/tmp/` and then moves it into place, so -/// a cache whose ROOT is writable while its `_cacache` tree belongs to somebody else -/// fails exactly the way this was reported: -/// -/// ```text -/// npm error code EPERM -/// npm error path C:\...\vncode\npm-cache\_cacache\tmp\a7c995e4 -/// ``` -/// -/// ...while a probe that writes a file at the root - which is what the first -/// version of this check did - cheerfully says the cache is fine. The probe -/// therefore creates and writes in the directory npm really writes in. -pub fn npm_cache_is_usable(cache: &std::path::Path) -> bool { - is_writable(&cache.join("_cacache").join("tmp")) -} - -/// Where npm's cache should go, and why that is not the first choice. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct CacheChoice { - pub path: PathBuf, - /// A line worth printing when an earlier choice had to be refused. - pub warning: Option, -} - -/// Choose a cache npm can really write its payloads into, preferring the -/// application's own directory. -/// -/// `npx` writes its cache wherever `npm_config_cache` points, so a directory the -/// account cannot write in is not a cosmetic problem: npm fails the whole install -/// with `EPERM` and then advises running as Administrator - which is the advice that -/// CREATED the unwritable directory in the first place. -/// -/// A candidate npm could not write in is REFUSED and the next is used, with a line -/// saying so. A run that quietly moved the cache would leave the next reader looking -/// at the wrong directory. -pub fn choose_npm_cache(candidates: &[PathBuf]) -> Option { - let mut warning = None; - for (index, candidate) in candidates.iter().enumerate() { - if npm_cache_is_usable(candidate) { - return Some(CacheChoice { path: candidate.clone(), warning }); - } - if index == 0 { - // A NOTE, not a log line: the caller prefixes its own. A second - // `[vncode] note:` inside it reads as a bug in the transcript. - warning = Some(format!( - "{} is NOT usable by this account, so npm's cache is going somewhere else - an elevated run probably created that directory, and npm's own advice to 'run as Administrator' is what does it", - candidate.display() - )); - } - } - None -} - -/// The cache candidates in order, from the facts a launch has. -/// -/// 1. the app's own root (`$VNCODE_HOME/npm-cache`, `%LOCALAPPDATA%\vncode\npm-cache` -/// by default) - where it belongs, and shared with nobody; -/// 2. the harness home (`$DSH_HOME/vncode/npm-cache`) - normally writable even when -/// the first is broken, because the harness itself writes there; -/// 3. beside the vendored runtime, inside the checkout. -pub fn npm_cache_candidates( - app_root: Option<&std::path::Path>, - harness_home: Option<&std::path::Path>, - repo_root: Option<&std::path::Path>, -) -> Vec { - let mut candidates = Vec::new(); - if let Some(root) = app_root { - candidates.push(npm_cache_dir(root)); - } - if let Some(home) = harness_home { - candidates.push(home.join("vncode").join("npm-cache")); - } - if let Some(repo) = repo_root { - candidates.push(repo.join("runtime").join("npm-cache")); - } - candidates -} - -#[cfg(test)] -mod tests { - use super::*; - - fn scratch(name: &str) -> PathBuf { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - }; - let path = root.join(format!("vncode-appdata-{}-{name}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - path - } - - #[test] - fn the_root_holds_the_home_and_the_cache_beside_each_other() { - // The shape this revision introduced: one root the app owns, the harness home - // a directory inside it, and the cache beside the home rather than inside it - - // so the cache survives a `-DshHome` that points at somebody else's folder. - let root = root_in(std::path::Path::new("/data")); - assert_eq!(root, PathBuf::from("/data").join("vncode")); - assert_eq!(owned_home(&root), PathBuf::from("/data").join("vncode").join("home")); - assert_eq!( - npm_cache_dir(&root), - PathBuf::from("/data").join("vncode").join("npm-cache") - ); - assert!( - !npm_cache_dir(&root).starts_with(owned_home(&root)), - "the app's cache must not live inside the harness home" - ); - } - - #[test] - fn a_named_vncode_home_wins_over_the_platform_root() { - // `VNCODE_HOME` is the app's own override; it is read through this one - // function, and the pure half is what is pinned here so the test cannot race - // another test over the process environment. - assert_eq!( - app_root_with(Some(" /tmp/a-named-root "), Some(std::path::Path::new("/data"))), - Some(PathBuf::from("/tmp/a-named-root")) - ); - assert_eq!( - app_root_with(Some(" "), Some(std::path::Path::new("/data"))), - Some(PathBuf::from("/data").join("vncode")), - "a blank name is not a name, so the platform default stands" - ); - assert_eq!(app_root_with(None, None), None); - } - - #[test] - fn the_tree_candidate_is_the_dot_vncode_folder() { - assert_eq!( - tree_root(std::path::Path::new("/repo")), - PathBuf::from("/repo").join(".vncode") - ); - } - - #[test] - fn a_folder_is_portable_by_the_marker_or_by_the_home_it_already_holds() { - let tree = scratch("portable"); - std::fs::create_dir_all(&tree).unwrap(); - // A fresh checkout is NOT portable: nothing has chosen the folder yet. - assert_eq!(portable_root(&tree), None); - // ...the marker is the explicit choice. - let root = mark_portable(&tree).unwrap(); - assert_eq!(root, tree.join(".vncode")); - assert!(portable_marker(&tree).is_file()); - assert_eq!(portable_root(&tree), Some(root.clone())); - - // ...and a home already inside the root is the same answer without a marker, - // because the app has already put this person's state there. - let other = scratch("portable-home-only"); - std::fs::create_dir_all(owned_home(&tree_root(&other))).unwrap(); - assert_eq!(portable_root(&other), Some(tree_root(&other))); - assert!(!portable_marker(&other).exists(), "reading must not write the marker"); - - let _ = std::fs::remove_dir_all(&tree); - let _ = std::fs::remove_dir_all(&other); - } - - #[test] - fn marking_a_folder_portable_creates_the_root_and_reports_a_refusal() { - let tree = scratch("mark"); - std::fs::create_dir_all(&tree).unwrap(); - assert!(mark_portable(&tree).is_ok()); - // A tree that cannot hold a folder - its own path is a FILE - is refused with - // the path in the sentence rather than silently doing nothing. - let blocker = tree.join("a-file"); - std::fs::write(&blocker, b"x").unwrap(); - let error = mark_portable(&blocker).unwrap_err(); - assert!(error.contains("could not create"), "{error}"); - let _ = std::fs::remove_dir_all(&tree); - } - - #[test] - fn writability_is_probed_by_writing() { - let root = scratch("writable"); - assert!(is_writable(&root), "a fresh scratch directory must be writable"); - // ...and the probe cleans up after itself. - assert_eq!(std::fs::read_dir(&root).unwrap().count(), 0); - // A path whose PARENT is a file can never be created on any platform - the - // portable stand-in for "this account may not write here". - let blocker = root.join("blocker"); - std::fs::write(&blocker, b"a file, not a directory").unwrap(); - assert!(!is_writable(&blocker.join("under-a-file"))); - // ...and the refusal carries the reason the panel prints. - let reason = probe(&blocker.join("under-a-file")).unwrap_err(); - assert!(reason.contains("could not be created"), "{reason}"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_home_probe_leaves_a_refused_home_exactly_as_it_was_found() { - // The probe used to ask about `/vncode`, which CREATED an empty folder - // inside a home it was about to refuse - somebody else's tree. It now asks - // about the home itself, so nothing new appears. - let root = scratch("refused-home"); - let home = root.join("somebody-elses-home"); - std::fs::create_dir_all(&home).unwrap(); - assert!(harness_home_is_writable(&home), "the home root itself is writable"); - assert!(!home.join("vncode").exists(), "the probe created a folder in the home"); - assert_eq!(std::fs::read_dir(&home).unwrap().count(), 0); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn a_broken_first_choice_moves_the_cache_and_says_so() { - // The failure this exists for: `%LOCALAPPDATA%\vncode\npm-cache` owned by an - // elevated run, and npm dying with EPERM. The app must not die with it - and - // must not move the cache quietly either. - let root = scratch("choose"); - std::fs::create_dir_all(&root).unwrap(); - let blocker = root.join("blocker"); - std::fs::write(&blocker, b"file").unwrap(); - let refused = blocker.join("npm-cache"); - let works = root.join("home").join("vncode").join("npm-cache"); - let choice = choose_npm_cache(&[refused.clone(), works.clone()]).expect("a fallback exists"); - assert_eq!(choice.path, works); - let warning = choice.warning.expect("the refusal must be reported"); - assert!(warning.contains("NOT usable"), "{warning}"); - assert!(warning.contains(&refused.display().to_string()), "{warning}"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn a_cache_whose_cacache_tree_is_unwritable_is_refused() { - // THE REPORTED FAILURE, reproduced without needing an elevated account: the - // cache ROOT is perfectly writable, and npm still cannot write, because it - // writes into `_cacache/tmp`. A probe at the root - the first version of - // this check - passed here and let npm fail anyway. - let root = scratch("cacache"); - let broken = root.join("app").join("npm-cache"); - std::fs::create_dir_all(&broken).unwrap(); - assert!(is_writable(&broken), "the cache ROOT is writable, as the report showed"); - // ...but `_cacache` is a file, so nothing under it can be created. - std::fs::write(broken.join("_cacache"), b"not a directory").unwrap(); - assert!(!npm_cache_is_usable(&broken), "the probe must look where npm writes"); - let fresh = root.join("home").join("npm-cache"); - let choice = choose_npm_cache(&[broken, fresh.clone()]).expect("a fallback exists"); - assert_eq!(choice.path, fresh); - assert!(choice.warning.is_some()); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_first_writable_choice_wins_and_carries_no_warning() { - let root = scratch("first-wins"); - let first = root.join("app").join("vncode").join("npm-cache"); - let second = root.join("home").join("vncode").join("npm-cache"); - let choice = choose_npm_cache(&[first.clone(), second]).expect("the first is writable"); - assert_eq!(choice.path, first); - assert_eq!(choice.warning, None); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn no_candidate_at_all_is_an_answer_rather_than_a_panic() { - assert_eq!(choose_npm_cache(&[]), None); - assert!(npm_cache_candidates(None, None, None).is_empty()); - let all = npm_cache_candidates( - Some(std::path::Path::new("/d")), - Some(std::path::Path::new("/h")), - Some(std::path::Path::new("/r")), - ); - assert_eq!(all.len(), 3); - // Order matters: the app's own root, then the harness home, then the tree. - assert_eq!(all[0], PathBuf::from("/d").join("npm-cache")); - assert!(all[1].starts_with("/h")); - assert!(all[2].starts_with("/r"), "the checkout's own runtime/npm-cache"); - } - - #[test] - fn the_root_is_whatever_this_platform_names_and_nothing_invented() { - // On a host with the variable set, the answer is that path; with none of - // them set the answer is `None` rather than a guess - and the caller (the - // npx fallback) then simply leaves npm's own default alone. - let root = data_root(); - if cfg!(windows) { - let expected = std::env::var("LOCALAPPDATA").ok().filter(|v| !v.trim().is_empty()); - assert_eq!(root.is_some(), expected.is_some()); - } - if let Some(root) = root { - assert!(!root.as_os_str().is_empty()); - } - } -} diff --git a/app/crates/vn-shell-core/src/home.rs b/app/crates/vn-shell-core/src/home.rs deleted file mode 100644 index 4076db2..0000000 --- a/app/crates/vn-shell-core/src/home.rs +++ /dev/null @@ -1,1058 +0,0 @@ -//! Where the app's root is, where the harness home is, and the rule that neither is -//! inherited by accident. -//! -//! `DSH_HOME` names the harness's OWN folder - the one holding `.credentials.yaml`, -//! `sessions/`, `profiles/` and the pack's caches. It is NOT the user's home, so a -//! shell that passed `%USERPROFILE%` there would boot a second, unadorned harness -//! inside it: a profile with none of this pack's bundles and none of the user's -//! sessions. Every rule below exists to make that mistake impossible, and the panel -//! SHOWS the outcome rather than hiding it. -//! -//! ## Two ladders, and the second one inside the first -//! -//! Since M0 the app owns a root, and the harness home is a directory inside it: -//! -//! * **the app root** (`$VNCODE_HOME`): `VNCODE_HOME` in the environment, else a -//! **portable** folder's own root (`/.vncode`, when it carries the marker or -//! already holds a home), else `/vncode`, else `/.vncode`, else a -//! named failure. It holds the furniture - the window record, the preferences, the -//! npm cache - and the home. Every one of those lives under the ONE root the ladder -//! chose, so a root that cannot be written never splits the app's memory in two. -//! * **the harness home**: `-DshHome` (strict: a refusal ends the run, because an -//! explicit instruction is never silently ignored), else the home this person chose -//! in the panel (remembered in the app root), else an inherited `DSH_HOME` that is -//! writable, else `/home`. -//! -//! **Nothing outside the app's own root is ever the home it runs against.** The -//! harness's own `~/.dsh` default was once a courtesy rung here - "the installation -//! already on this machine", used while the app's own home was still empty - and it is -//! now gone: a folder that carries everything it needs must not reach into a person's -//! profile to start, and this app already answers the two things that rung existed for -//! (a home with no pack, and a home with no key) on its own: Start installs the pack into -//! the home in use, and the key row asks for the key. `~/.dsh` survives as an *input* to -//! the copy offer alone - a one-way import of a person's own sessions, read and never run -//! against. -//! -//! ## Every candidate is a cleaned-up path -//! -//! Every rung goes through [`crate::userpath`] first: `~` is expanded the way the -//! harness expands it, a relative path is resolved against the directory the app was -//! started in, `.`/`..` are folded lexically, and a NUL or an empty string is refused -//! by name. What is EXPORTED, recorded and shown is the real path -//! (`userpath::canonical`), so two spellings of one home never look like two homes - -//! and a rung whose text cannot be turned into a path at all is carried as a refusal -//! with its reason rather than skipped silently. -//! -//! ## Why a home can be unwritable at all -//! -//! Measured on the machine this was written on: `%USERPROFILE%\.dsh` is owned by the -//! signed-in account and takes a write; the same directory refuses a process whose -//! PARENT confines what its children may write (an agent session, an IDE runner, a -//! CI sandbox - this repository's own checks run inside one). An elevated run can -//! also leave ACLs on it, and a checkout can sit on a read-only mount. The old build -//! answered all three with one sentence asking the person to start it differently, -//! which cannot fix a confinement; this one answers with a root it created and -//! proved, and NAMES every candidate it refused. - -use std::fmt; -use std::path::{Path, PathBuf}; - -use crate::appdata::Probed; - -/// Which candidate decided a root or a home. The panel prints this, so a reader can -/// tell "I set this" from "the app chose it". -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum Origin { - /// `-DshHome` was given. - Flag, - /// The home this person chose in the panel, remembered in the app root. - Remembered, - /// `DSH_HOME` was inherited from this shell's own environment. - Inherited, - /// This app's own home, inside the root. - Owned, - /// `VNCODE_HOME` named the app's root. - NamedRoot, - /// **This folder is a portable installation**: it carries the marker, or it - /// already holds a home, so `/.vncode` is the root rather than the - /// platform's data directory. See `appdata::portable_root`. - PortableRoot, - /// The platform's own per-user data root, plus `vncode`. - PlatformRoot, - /// The folder beside the checkout: `/.vncode`. - TreeRoot, -} - -impl Origin { - pub fn label(self) -> &'static str { - match self { - Origin::Flag => "from -DshHome", - Origin::Remembered => "the home you chose in this panel", - Origin::Inherited => "from the inherited DSH_HOME", - Origin::Owned => "this app's own home (the default)", - Origin::NamedRoot => "from VNCODE_HOME", - Origin::PortableRoot => "this folder, because it is a portable installation", - Origin::PlatformRoot => "this app's root in the platform's data directory", - Origin::TreeRoot => "beside the checkout, because nothing else could be written", - } - } -} - -impl fmt::Display for Origin { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - formatter.write_str(self.label()) - } -} - -/// A candidate that was tried and could not be used, with the reason. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Refusal { - pub path: PathBuf, - pub reason: String, -} - -impl Refusal { - /// One line, for the log and the panel. - pub fn line(&self) -> String { - format!("{} was refused: {}", self.path.display(), self.reason) - } -} - -/// One rung of a ladder. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Candidate { - /// What will be probed. Already cleaned by `userpath` when it could be. - pub path: PathBuf, - pub origin: Origin, - /// A refusal here ENDS the ladder instead of falling through. Only `-DshHome` - /// sets it: the person named that path, and quietly using another one would be - /// answering a question they did not ask. - pub strict: bool, - /// Set when the text could not be turned into a path at all (empty, a NUL, a - /// relative path with no readable working directory). The rung is then refused - /// without the filesystem being asked anything. - pub problem: Option, -} - -/// The rung that was used. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Selection { - /// The REAL path: what is exported to the harness, recorded and drawn. - pub chosen: PathBuf, - pub origin: Origin, - /// Whether this app created it. The panel says so, and only a directory this app - /// created is ever hardened (`appdata::harden_if_created`). - pub created: bool, - /// Everything refused before it, in the order it was refused. - pub refused: Vec, -} - -impl Selection { - /// The panel's row: the path, and always the reason. - pub fn row(&self) -> (String, &'static str) { - (self.chosen.display().to_string(), self.origin.label()) - } -} - -/// What the app decided, and what it had to refuse to get there. -/// -/// `app_root` is `None` only when nothing anywhere could be written - in which case -/// the app still opens (it simply has no memory), says why, and refuses to start a -/// harness. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Resolution { - pub app_root: Option, - /// Which rung of the root ladder was used, for the panel's own row. - pub app_root_origin: Option, - pub home: Option, - /// The app root ladder's refusals, then the home ladder's. - pub refused: Vec, - /// A `-DshHome` was refused: the run must stop and say so. - pub strict: bool, -} - -impl Resolution { - /// The harness home, when one was decided. - pub fn home_path(&self) -> Option<&Path> { - self.home.as_ref().map(|selection| selection.chosen.as_path()) - } - - /// The app's root, when one was decided. - pub fn app_root_path(&self) -> Option<&Path> { - self.app_root.as_deref() - } - - /// The app root's own words, for the panel's `vncode` row. - pub fn app_root_origin_label(&self) -> &'static str { - self.app_root_origin.map(Origin::label).unwrap_or("unknown") - } - - /// Whether the home in use was created by this app - the panel says so, because - /// "I made this" and "I joined this" are different promises. - pub fn home_created(&self) -> bool { - self.home.as_ref().map(|selection| selection.created).unwrap_or(false) - } - - /// The panel's home row: the path when there is one, and always the reason. - pub fn row(&self) -> (String, &'static str) { - match self.home.as_ref() { - Some(selection) => selection.row(), - None => ("unknown".to_string(), "no home could be written anywhere"), - } - } - - /// Why no harness can be started here, if none can - one sentence, naming the - /// flag when a flag is the reason, then every candidate and its own error. - /// - /// `None` means the home is usable, which is the ordinary case even under a - /// parent that confines its children: the app creates a root the confinement - /// grants. - pub fn problem(&self) -> Option { - if self.home.is_some() { - return None; - } - let mut sentence = if self.strict { - let named = self - .refused - .first() - .map(|refusal| refusal.path.display().to_string()) - .unwrap_or_default(); - format!( - "-DshHome names {named}, which this account cannot write in, so the harness cannot compose its profile there and will not start." - ) - } else { - "no harness home could be created: every candidate was refused, and the harness cannot compose its profile without one.".to_string() - }; - sentence.push_str(" Every candidate and its own error:"); - for refusal in &self.refused { - sentence.push_str(&format!("\n - {}: {}", refusal.path.display(), refusal.reason)); - } - if !self.strict { - sentence.push_str( - "\nPass -DshHome to choose one yourself.", - ); - } - Some(sentence) - } - - /// One line per refusal, for the log and the panel's notes. - pub fn notes(&self) -> Vec { - self.refused.iter().map(Refusal::line).collect() - } -} - -/// Everything a resolution reads, so the whole ladder is a `cargo test` case. -#[derive(Clone, Debug, Default)] -pub struct Inputs<'a> { - /// `VNCODE_HOME` in the environment. - pub named_root: Option<&'a str>, - /// `-DshHome`. - pub flag: Option<&'a str>, - /// The home this person chose in the panel, remembered in the app root. - pub remembered: Option<&'a Path>, - /// `DSH_HOME` inherited from whatever started this app. - pub inherited: Option<&'a str>, - /// The platform's own per-user data root. - pub data_root: Option<&'a Path>, - /// Where `.dsh-version.json` was found. - pub tree_root: Option<&'a Path>, - /// The tree's own root, when this folder is a portable installation - /// (`appdata::portable_root`). Read before the ladder runs and passed in, so the - /// ladder itself stays a pure decision over paths. - pub portable: Option<&'a Path>, - /// The directory the app was started in: what a relative path resolves against. - pub cwd: Option<&'a Path>, - /// The user's home, for a leading `~`. - pub user_home: Option<&'a Path>, -} - -/// Build a rung from typed text, carrying a cleaning failure as the rung's problem. -fn candidate( - typed: &str, - origin: Origin, - strict: bool, - inputs: &Inputs<'_>, -) -> Option { - if typed.trim().is_empty() { - return None; - } - Some(match crate::userpath::resolve(typed, inputs.cwd, inputs.user_home) { - Ok(path) => Candidate { path, origin, strict, problem: None }, - // The path cannot be turned into something a process may be given. It is - // still a rung, so the reason reaches the panel instead of vanishing. - Err(reason) => Candidate { - path: PathBuf::from(typed.trim()), - origin, - strict, - problem: Some(reason), - }, - }) -} - -/// The app root ladder, as data. -/// -/// The first rung that passes the probe wins; there is no strict rung, because -/// nothing on this ladder was named by a person in a way that outranks a working -/// alternative - the point is that SOMETHING writable is found rather than nothing. -/// -/// `VNCODE_HOME` first, then **this folder when it is a portable installation**, then -/// the platform's data root, then the folder beside the tree as the last resort. The -/// portable rung sits above the platform one because the alternative - a folder that -/// already holds this person's sessions, and a fresh root somewhere else - is two -/// installations where the person made one. -pub fn root_candidates(inputs: &Inputs<'_>) -> Vec { - let mut candidates = Vec::new(); - if let Some(named) = inputs.named_root { - candidates.extend(candidate(named, Origin::NamedRoot, false, inputs)); - } - if let Some(portable) = inputs.portable { - candidates.push(Candidate { - path: portable.to_path_buf(), - origin: Origin::PortableRoot, - strict: false, - problem: None, - }); - } - if let Some(data_root) = inputs.data_root { - candidates.push(Candidate { - path: crate::appdata::root_in(data_root), - origin: Origin::PlatformRoot, - strict: false, - problem: None, - }); - } - if let Some(tree_root) = inputs.tree_root { - let path = crate::appdata::tree_root(tree_root); - // The last resort - unless the portable rung already IS this path, which is - // what `appdata::portable_root` always hands over: a rung that repeats the one - // above it can only produce a second, identical refusal line. - if inputs.portable != Some(path.as_path()) { - candidates.push(Candidate { - path, - origin: Origin::TreeRoot, - strict: false, - problem: None, - }); - } - } - candidates -} - -/// The harness home ladder, as data. -/// -/// `-DshHome` is the only strict rung. The remembered choice and an inherited -/// `DSH_HOME` that cannot be written fall THROUGH with a line saying so: neither is a -/// reason to refuse to start, and refusing there is exactly the dead end this -/// revision removes. -pub fn home_candidates(inputs: &Inputs<'_>, app_root: Option<&Path>) -> Vec { - let mut candidates = Vec::new(); - if let Some(flag) = inputs.flag { - candidates.extend(candidate(flag, Origin::Flag, true, inputs)); - } - if let Some(remembered) = inputs.remembered { - candidates.push(Candidate { - path: remembered.to_path_buf(), - origin: Origin::Remembered, - strict: false, - problem: None, - }); - } - if let Some(inherited) = inputs.inherited { - candidates.extend(candidate(inherited, Origin::Inherited, false, inputs)); - } - // THIS APP'S OWN HOME, INSIDE ITS OWN ROOT - and nothing else. The rung that used to - // sit here ("the installation already on this machine", `~/.dsh`) is gone: see this - // module's header. A home outside the root is an input to the COPY offer and never a - // home this app runs against. - if let Some(root) = app_root { - candidates.push(Candidate { - path: crate::appdata::owned_home(root), - origin: Origin::Owned, - strict: false, - problem: None, - }); - } - candidates -} - -/// Walk a ladder, proving each rung with `probe`. Pure. -/// -/// Every rung is probed in order; the first `Ok` wins and carries the refusals that -/// came before it. A rung whose text could not even be cleaned is refused with that -/// reason and no filesystem call. A strict rung that fails ends the walk immediately - -/// the caller gets `Err` with the refusals, and `Resolution::strict` is what turns -/// that into the sentence naming the flag. -pub fn select( - candidates: &[Candidate], - probe: &mut impl FnMut(&Path) -> Result, -) -> Result> { - let mut refused = Vec::new(); - for candidate in candidates { - if let Some(reason) = candidate.problem.clone() { - refused.push(Refusal { path: candidate.path.clone(), reason }); - if candidate.strict { - return Err(refused); - } - continue; - } - match probe(&candidate.path) { - Ok(probed) => { - return Ok(Selection { - chosen: probed.path, - origin: candidate.origin, - created: probed.created, - refused, - }) - } - Err(reason) => { - refused.push(Refusal { path: candidate.path.clone(), reason }); - if candidate.strict { - return Err(refused); - } - } - } - } - Err(refused) -} - -/// Resolve both ladders against a probe. Pure, so precedence, the fall-through, the -/// remembered choice and the refusals are `cargo test` cases. -pub fn resolve_with( - inputs: &Inputs<'_>, - probe: &mut impl FnMut(&Path) -> Result, -) -> Resolution { - let mut refused = Vec::new(); - let (app_root, app_root_origin) = match select(&root_candidates(inputs), probe) { - Ok(selection) => { - refused.extend(selection.refused.iter().cloned()); - (Some(selection.chosen), Some(selection.origin)) - } - Err(root_refusals) => { - // Nothing writable at all. There is no home to decide either, and the - // refusals are the whole answer. - refused.extend(root_refusals); - return Resolution { - app_root: None, - app_root_origin: None, - home: None, - refused, - strict: false, - }; - } - }; - - match select(&home_candidates(inputs, app_root.as_deref()), probe) { - Ok(selection) => { - refused.extend(selection.refused.iter().cloned()); - Resolution { app_root, app_root_origin, home: Some(selection), refused, strict: false } - } - Err(home_refusals) => { - let strict = inputs.flag.map(str::trim).is_some_and(|value| !value.is_empty()); - let mut all = refused; - all.extend(home_refusals); - Resolution { app_root, app_root_origin, home: None, refused: all, strict } - } - } -} - -/// The inputs both resolvers are built from, so the root ladder alone and the whole -/// resolution see one environment. -/// -/// Nine of them and not a struct, because this is the ONE place the environment is read -/// and grouping it would only move the same nine fields one call up. The count is the -/// shape of the environment, not a design smell. -#[allow(clippy::too_many_arguments)] -fn inputs_from_env<'a>( - named_root: Option<&'a str>, - flag: Option<&'a str>, - remembered: Option<&'a Path>, - inherited: Option<&'a str>, - data_root: Option<&'a Path>, - tree: Option<&'a Path>, - portable: Option<&'a Path>, - cwd: Option<&'a Path>, - user_home: Option<&'a Path>, -) -> Inputs<'a> { - Inputs { - named_root, - flag, - remembered, - inherited, - data_root, - tree_root: tree, - portable, - cwd, - user_home, - } -} - -/// Resolve against this process's own environment and this machine's real -/// filesystem - the probe WRITES, which is the only proof this app accepts. -/// -/// `remembered` is the home the person chose in the panel, read from the app root by -/// the caller (so this function reads no preferences of its own). -pub fn from_env(flag: Option<&str>, remembered: Option<&Path>) -> Resolution { - let named_root = std::env::var("VNCODE_HOME").ok(); - let inherited = std::env::var("DSH_HOME").ok(); - let data_root = crate::appdata::data_root(); - let tree = crate::launch::repo_root(); - let cwd = std::env::current_dir().ok(); - let user_home = home_dir(); - // The portable decision is made HERE and passed in as a fact, so the ladder below - // stays pure: it is a path the caller has already established, not a probe. - let portable = tree.as_deref().and_then(crate::appdata::portable_root); - let inputs = inputs_from_env( - named_root.as_deref(), - flag, - remembered, - inherited.as_deref(), - data_root.as_deref(), - tree.as_deref(), - portable.as_deref(), - cwd.as_deref(), - user_home.as_deref(), - ); - resolve_with(&inputs, &mut crate::appdata::probe) -} - -/// **The app root alone**, resolved against this process's environment. -/// -/// The ladder is decided by paths only - `VNCODE_HOME`, a portable folder, the platform's -/// data root, the folder beside the tree - so this needs neither a flag nor a remembered -/// home, and it is what lets a caller ask "where does THIS app's own home live" BEFORE it -/// decides whether an installation already on the machine should be used. -/// -/// That order is load-bearing rather than tidy: the courtesy rung is guarded by "this -/// app's own home still holds nothing of yours", and asking that of the PLATFORM home -/// while the ladder had chosen a portable folder's home would let an ordinary `~/.dsh` -/// override the home tucked inside the folder - the exact split this app must not have. -/// -/// A root the ladder refuses is simply absent here: the caller falls back to -/// [`crate::appdata::app_root`], which is the platform candidate by construction. -pub fn root_from_env() -> Option { - let named_root = std::env::var("VNCODE_HOME").ok(); - let data_root = crate::appdata::data_root(); - let tree = crate::launch::repo_root(); - let cwd = std::env::current_dir().ok(); - let user_home = home_dir(); - let portable = tree.as_deref().and_then(crate::appdata::portable_root); - let inputs = inputs_from_env( - named_root.as_deref(), - None, - None, - None, - data_root.as_deref(), - tree.as_deref(), - portable.as_deref(), - cwd.as_deref(), - user_home.as_deref(), - ); - select(&root_candidates(&inputs), &mut crate::appdata::probe) - .ok() - .map(|selection| selection.chosen) -} - -/// Whether a directory has the shape of a harness home. -/// -/// Used for one decision only: whether the panel should offer to USE an existing -/// installation, or to ADOPT a copy of it. A folder with a profile, sessions, the -/// credential file or the storages tree is somebody's harness; an empty folder, or a -/// folder of holiday photos, is not - and offering to adopt either would be noise. -pub fn looks_like_a_harness_home(path: &Path) -> bool { - if !path.is_dir() { - return false; - } - ["profiles", "sessions", "storages", ".credentials.yaml"] - .iter() - .any(|name| path.join(name).exists()) -} - -/// Which variable names the user's home directory, first match winning. -/// -/// Windows is asked for `USERPROFILE` first because that is the variable Node's own -/// `os.homedir()` reads there - and `keystate` uses it to describe where a -/// credentials file could be. It is NOT used to choose the harness home: see this -/// module's header. -pub fn pick_home_variable<'a>( - user_profile: Option<&'a str>, - home: Option<&'a str>, - is_windows: bool, -) -> Option<&'a str> { - let candidates: [Option<&'a str>; 2] = if is_windows { - [user_profile, home] - } else { - [home, user_profile] - }; - candidates - .into_iter() - .flatten() - .find(|value| !value.trim().is_empty()) -} - -/// The user's home directory, resolved the way the harness resolves it. -pub fn home_dir() -> Option { - let user_profile = std::env::var("USERPROFILE").ok(); - let home = std::env::var("HOME").ok(); - pick_home_variable(user_profile.as_deref(), home.as_deref(), cfg!(target_os = "windows")) - .map(PathBuf::from) -} - -/// The harness's own default home under a user home: `~/.dsh`. -/// -/// NOT a candidate this app chooses on its own. It names the folder the panel offers -/// to use or adopt, and the one `-DshHome %USERPROFILE%\.dsh` selects when a person -/// asks for the app and `run-web` to share a home. -pub fn default_dsh_home(user_home: &Path) -> PathBuf { - user_home.join(".dsh") -} - -/// The harness home this machine already has, for the panel's offer and for `adopt`. -pub fn existing_default_home() -> Option { - home_dir().map(|user_home| default_dsh_home(&user_home)) -} - -#[cfg(test)] -mod tests { - use super::*; - - /// A prober over a fixed set of paths: the ladder logic is what is under test, - /// not the filesystem. - fn prober<'a>(allowed: &'a [&'a str]) -> impl FnMut(&Path) -> Result + 'a { - move |path: &Path| { - if allowed.iter().any(|allowed| Path::new(allowed) == path) { - Ok(Probed { path: path.to_path_buf(), created: false }) - } else { - Err("not writable: access is denied".to_string()) - } - } - } - - /// Inputs for a machine with no environment at all, plus whatever a case needs. - fn inputs<'a>() -> Inputs<'a> { - Inputs { - data_root: Some(Path::new("/data")), - tree_root: Some(Path::new("/repo")), - cwd: Some(Path::new("/cwd")), - user_home: Some(Path::new("/home/someone")), - ..Inputs::default() - } - } - - #[test] - fn a_typed_home_and_an_inherited_one_are_the_only_homes_outside_the_root() { - let mut probe = prober(&["/data/vncode", "/flag/.dsh"]); - let resolved = resolve_with(&Inputs { flag: Some("/flag/.dsh"), ..inputs() }, &mut probe); - assert_eq!(resolved.home_path(), Some(Path::new("/flag/.dsh"))); - - let mut probe = prober(&["/data/vncode", "/parent/.dsh"]); - let resolved = - resolve_with(&Inputs { inherited: Some("/parent/.dsh"), ..inputs() }, &mut probe); - assert_eq!(resolved.home_path(), Some(Path::new("/parent/.dsh"))); - assert_eq!(resolved.home.as_ref().unwrap().origin, Origin::Inherited); - } - - #[test] - fn the_harness_default_home_is_never_a_rung_the_app_walks_to() { - // THE REMOVED COURTESY, PINNED AS ABSENT. `~/.dsh` used to be a rung here - used - // while this app's own home was still empty - and a folder that carries - // everything it needs must not reach into a person's profile to start. The - // ladder is offered the path and must not take it: the app's own home wins. - let candidates = home_candidates( - &Inputs { user_home: Some(Path::new("/home/someone")), ..inputs() }, - Some(Path::new("/data/vncode")), - ); - let paths: Vec = - candidates.iter().map(|candidate| candidate.path.clone()).collect(); - assert!( - !paths.iter().any(|path| path.ends_with(".dsh")), - "a home outside the root is still a rung: {paths:?}" - ); - - // The default home still NAMES that folder for the copy offer - it is an input - // to an explicit one-way import, which is a different thing from running there. - assert!(existing_default_home().is_some() || home_dir().is_none()); - assert_eq!(default_dsh_home(Path::new("/home/someone")), Path::new("/home/someone/.dsh")); - } - - #[test] - fn the_default_root_is_the_platform_one_and_the_default_home_is_inside_it() { - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with(&inputs(), &mut probe); - assert_eq!(resolved.app_root_path(), Some(Path::new("/data/vncode"))); - assert_eq!(resolved.home_path(), Some(Path::new("/data/vncode/home"))); - assert_eq!(resolved.home.as_ref().unwrap().origin, Origin::Owned); - // The harness's own `~/.dsh` is never reached by the app's own choice: no - // candidate on either ladder names it. - assert!(resolved.refused.is_empty(), "{:?}", resolved.refused); - } - - #[test] - fn a_writable_inherited_home_is_joined_and_the_furniture_stays_in_the_root() { - // The confirmed behaviour: launched from inside a harness session, the app - // runs against that session's home and shares its sessions and key. - let mut probe = prober(&["/data/vncode", "/parent/.dsh"]); - let resolved = resolve_with( - &Inputs { inherited: Some("/parent/.dsh"), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/parent/.dsh"))); - assert_eq!(resolved.home.as_ref().unwrap().origin, Origin::Inherited); - // ...and the root is still the app's own, so the geometry and the npm cache - // do not follow the home. - assert_eq!(resolved.app_root_path(), Some(Path::new("/data/vncode"))); - } - - #[test] - fn an_unwritable_inherited_home_falls_through_instead_of_refusing() { - // THE REGRESSION THIS REVISION EXISTS FOR. Before M0 this was a refusal that - // named `~/.dsh` and told the person to start the app differently, which - // cannot fix a parent that confines its children. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with( - &Inputs { inherited: Some("/confined/.dsh"), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/data/vncode/home"))); - assert!(resolved.problem().is_none(), "a refused inherited home must not stop the run"); - let notes = resolved.notes(); - assert_eq!(notes.len(), 1, "{notes:?}"); - // The refusal names the path AS IT WAS RESOLVED, which is how the panel and - // the log draw it - built here, so this reads the same on Windows as on POSIX. - let confined = crate::userpath::resolve("/confined/.dsh", None, None).unwrap(); - assert!(notes[0].contains(&confined.display().to_string()), "{notes:?}"); - assert!(notes[0].contains("was refused"), "{notes:?}"); - } - - #[test] - fn the_home_this_person_chose_in_the_panel_wins_over_the_inherited_one() { - // A remembered choice that is still writable is used, because a click in the - // panel is a decision and an environment variable is a circumstance. - let mut probe = prober(&["/data/vncode", "/chosen/home", "/parent/.dsh"]); - let resolved = resolve_with( - &Inputs { - remembered: Some(Path::new("/chosen/home")), - inherited: Some("/parent/.dsh"), - ..inputs() - }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/chosen/home"))); - assert_eq!(resolved.home.as_ref().unwrap().origin, Origin::Remembered); - } - - #[test] - fn a_remembered_home_that_is_gone_falls_through_with_a_line() { - // Uninstalled, moved, or on a drive that is not plugged in: the app comes up - // anyway, and says which home it could not use. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with( - &Inputs { remembered: Some(Path::new("/gone/home")), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/data/vncode/home"))); - assert_eq!(resolved.refused.len(), 1); - assert!(resolved.refused[0].line().contains("/gone/home")); - } - - #[test] - fn a_typed_dshhome_beats_every_other_rung() { - let mut probe = prober(&["/data/vncode", "/flag/.dsh", "/chosen/home", "/parent/.dsh"]); - let resolved = resolve_with( - &Inputs { - flag: Some("/flag/.dsh"), - remembered: Some(Path::new("/chosen/home")), - inherited: Some("/parent/.dsh"), - ..inputs() - }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/flag/.dsh"))); - assert_eq!(resolved.home.as_ref().unwrap().origin, Origin::Flag); - } - - #[test] - fn an_unwritable_dshhome_refuses_and_names_the_flag() { - // The one place an explicit instruction outranks a working default. - let mut probe = prober(&["/data/vncode"]); - let resolved = - resolve_with(&Inputs { flag: Some("/locked/.dsh"), ..inputs() }, &mut probe); - assert!(resolved.strict, "a refused -DshHome must be strict"); - assert_eq!(resolved.home_path(), None); - let problem = resolved.problem().expect("a refusal is due"); - assert!(problem.contains("-DshHome names"), "{problem}"); - let locked = crate::userpath::resolve("/locked/.dsh", None, None).unwrap(); - assert!(problem.contains(&locked.display().to_string()), "{problem}"); - // ...and it never falls through to a home the person did not ask for. - let owned = crate::appdata::owned_home(&crate::appdata::root_in(Path::new("/data"))); - assert!(!problem.contains(&owned.display().to_string()), "{problem}"); - } - - #[test] - fn every_rung_is_cleaned_before_it_is_probed() { - // A `~` is expanded the way the harness expands it, a relative path is - // resolved against the app's own directory, and `..` is folded - so what is - // probed, exported and recorded is one absolute, real path. - let mut probe = prober(&["/data/vncode", "/home/someone/harness"]); - let resolved = resolve_with( - &Inputs { flag: Some("~/harness"), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/home/someone/harness"))); - - let mut probe = prober(&["/data/vncode", "/cwd/here/home"]); - let resolved = resolve_with( - &Inputs { flag: Some("here/./home"), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.home_path(), Some(Path::new("/cwd/here/home"))); - - let mut probe = prober(&["/data/vncode", "/cwd/home"]); - let resolved = - resolve_with(&Inputs { flag: Some("sub/../home"), ..inputs() }, &mut probe); - assert_eq!(resolved.home_path(), Some(Path::new("/cwd/home"))); - } - - #[test] - fn a_path_that_cannot_be_cleaned_is_a_refusal_with_its_reason() { - // An empty value and a NUL are refused by name, and - for the flag the person - // typed - that refusal ENDS the run rather than quietly using another home. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = - resolve_with(&Inputs { flag: Some("bad\0path"), ..inputs() }, &mut probe); - assert!(resolved.strict); - let problem = resolved.problem().expect("a refusal is due"); - assert!(problem.contains("NUL"), "{problem}"); - // A blank flag is simply not a rung: it falls through like any absence. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with(&Inputs { flag: Some(" "), ..inputs() }, &mut probe); - assert_eq!(resolved.home_path(), Some(Path::new("/data/vncode/home"))); - assert!(!resolved.strict); - } - - #[test] - fn a_named_root_wins_and_the_tree_is_the_last_resort() { - // VNCODE_HOME is the app's own override. - let mut probe = prober(&["/named", "/named/home", "/data/vncode"]); - let resolved = resolve_with( - &Inputs { named_root: Some(" /named "), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.app_root_path(), Some(Path::new("/named"))); - assert_eq!(resolved.home_path(), Some(Path::new("/named/home"))); - - // A data root this account cannot write leaves the folder beside the tree, - // which is the one a workspace-scoped confinement always grants. - let mut probe = prober(&["/repo/.vncode", "/repo/.vncode/home"]); - let resolved = resolve_with(&inputs(), &mut probe); - assert_eq!(resolved.app_root_path(), Some(Path::new("/repo/.vncode"))); - assert_eq!(resolved.home_path(), Some(Path::new("/repo/.vncode/home"))); - assert_eq!(resolved.refused.len(), 1, "{:?}", resolved.refused); - } - - #[test] - fn a_portable_folder_uses_its_own_root_before_the_platform_one() { - // THE POINT OF THE RUNG. A folder that already holds a home - or that carries - // the marker - must be the root the next launch uses, even though the - // platform's data directory is perfectly writable. Otherwise the person's - // sessions and profile sit in one folder while every new run starts a second - // installation beside them. Both rungs are offered; the portable one is first. - let mut probe = prober(&["/repo/.vncode", "/repo/.vncode/home", "/data/vncode"]); - let resolved = resolve_with( - &Inputs { portable: Some(Path::new("/repo/.vncode")), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.app_root_path(), Some(Path::new("/repo/.vncode"))); - assert_eq!(resolved.app_root_origin, Some(Origin::PortableRoot)); - assert_eq!(resolved.home_path(), Some(Path::new("/repo/.vncode/home"))); - assert_eq!( - resolved.app_root_origin_label(), - "this folder, because it is a portable installation" - ); - // The platform root was never tried: nothing was refused on the way. - assert!(resolved.refused.is_empty(), "{:?}", resolved.refused); - } - - #[test] - fn a_named_root_still_beats_the_portable_one_and_a_locked_portable_root_falls_through() { - // An explicit VNCODE_HOME outranks the folder's own claim... - let mut probe = prober(&["/named", "/named/home", "/repo/.vncode"]); - let resolved = resolve_with( - &Inputs { - named_root: Some("/named"), - portable: Some(Path::new("/repo/.vncode")), - ..inputs() - }, - &mut probe, - ); - assert_eq!(resolved.app_root_path(), Some(Path::new("/named"))); - assert_eq!(resolved.app_root_origin, Some(Origin::NamedRoot)); - - // ...and a portable folder this account cannot write is refused like any other - // rung, with its reason, and the platform root is used instead. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with( - &Inputs { portable: Some(Path::new("/repo/.vncode")), ..inputs() }, - &mut probe, - ); - assert_eq!(resolved.app_root_path(), Some(Path::new("/data/vncode"))); - assert_eq!(resolved.app_root_origin, Some(Origin::PlatformRoot)); - assert_eq!(resolved.refused.len(), 1, "{:?}", resolved.refused); - assert!(resolved.refused[0].line().contains(".vncode"), "{:?}", resolved.refused); - } - - #[test] - fn the_root_ladder_is_named_root_then_portable_then_platform_then_tree() { - // A portable root that is NOT the tree's own - the API allows any path - keeps - // all four rungs in order. - let candidates = root_candidates(&Inputs { - named_root: Some("/named"), - portable: Some(Path::new("/elsewhere/.vncode")), - ..inputs() - }); - let origins: Vec = candidates.iter().map(|candidate| candidate.origin).collect(); - assert_eq!( - origins, - vec![Origin::NamedRoot, Origin::PortableRoot, Origin::PlatformRoot, Origin::TreeRoot], - "{origins:?}" - ); - assert!(!candidates.iter().any(|candidate| candidate.strict), "no root rung is strict"); - - // ...and when the portable root IS the tree's own, the last resort is not - // repeated: two rungs naming one path can only refuse it twice. - let candidates = root_candidates(&Inputs { - portable: Some(Path::new("/repo/.vncode")), - ..inputs() - }); - let origins: Vec = candidates.iter().map(|candidate| candidate.origin).collect(); - assert_eq!( - origins, - vec![Origin::PortableRoot, Origin::PlatformRoot], - "{origins:?}" - ); - } - - #[test] - fn nothing_writable_anywhere_is_a_named_failure_not_a_bare_start() { - let mut probe = prober(&[]); - let resolved = resolve_with(&inputs(), &mut probe); - assert_eq!(resolved.app_root_path(), None); - assert_eq!(resolved.home_path(), None); - assert_eq!(resolved.row().0, "unknown"); - let problem = resolved.problem().expect("a refusal is due"); - // Every candidate is named, with its own error. The paths are built the way - // the ladder builds them, so this reads the same on Windows as on POSIX. - let data_root = crate::appdata::root_in(Path::new("/data")); - let tree_root = crate::appdata::tree_root(Path::new("/repo")); - assert!(problem.contains(&data_root.display().to_string()), "{problem}"); - assert!(problem.contains(&tree_root.display().to_string()), "{problem}"); - assert!(problem.contains("access is denied"), "{problem}"); - assert!(problem.contains("Pass -DshHome"), "{problem}"); - } - - #[test] - fn a_refused_rung_is_carried_along_when_a_later_one_wins() { - // The panel shows what was refused, not only what was chosen: that is what - // makes "why did it do that" answerable. - let mut probe = prober(&["/data/vncode", "/data/vncode/home"]); - let resolved = resolve_with( - &Inputs { inherited: Some("/confined/.dsh"), ..inputs() }, - &mut probe, - ); - let selection = resolved.home.as_ref().unwrap(); - assert_eq!(selection.refused.len(), 1); - assert!(selection.refused[0].path.ends_with(".dsh")); - assert!(selection.refused[0].line().contains("was refused")); - // Built the way the ladder builds it, so this reads the same on Windows. - let expected = crate::appdata::owned_home(&crate::appdata::root_in(Path::new("/data"))); - assert_eq!(selection.row().0, expected.display().to_string()); - assert!(selection.row().1.contains("this app's own home")); - } - - #[test] - fn whether_the_app_created_the_home_travels_with_the_decision() { - // The panel says "I made this" or "I joined this", and only a directory this - // app created is ever hardened. - let mut probe = |path: &Path| { - Ok(Probed { path: path.to_path_buf(), created: path.ends_with("home") }) - }; - let resolved = resolve_with(&inputs(), &mut probe); - assert!(resolved.home_created(), "the app's own home is one it created"); - - let mut probe = |path: &Path| { - Ok(Probed { path: path.to_path_buf(), created: false }) - }; - let resolved = resolve_with( - &Inputs { inherited: Some("/parent/.dsh"), ..inputs() }, - &mut probe, - ); - assert!(!resolved.home_created(), "a joined home is not one the app created"); - } - - #[test] - fn home_candidates_keep_the_order_and_only_the_flag_is_strict() { - let candidates = home_candidates(&inputs(), Some(Path::new("/root"))); - let origins: Vec = candidates.iter().map(|candidate| candidate.origin).collect(); - assert_eq!(origins, vec![Origin::Owned], "{origins:?}"); - assert_eq!(candidates[0].path, PathBuf::from("/root").join("home")); - assert!(!candidates[0].strict); - - let all = home_candidates( - &Inputs { - flag: Some("/flag"), - remembered: Some(Path::new("/chosen")), - inherited: Some("/parent"), - ..inputs() - }, - Some(Path::new("/root")), - ); - assert_eq!(all.len(), 4, "{all:?}"); - assert!(all[0].strict, "only -DshHome is strict"); - assert!(!all[1].strict && !all[2].strict && !all[3].strict); - assert_eq!(all[1].origin, Origin::Remembered); - assert_eq!(all[3].path, PathBuf::from("/root").join("home")); - } - - #[test] - fn a_home_is_recognised_by_its_shape_not_by_its_name() { - let root = crate::scratch::dir("shape"); - std::fs::create_dir_all(&root).unwrap(); - assert!(!looks_like_a_harness_home(&root)); - std::fs::create_dir_all(root.join("sessions")).unwrap(); - assert!(looks_like_a_harness_home(&root), "sessions/ is the shape of a harness home"); - assert!(!looks_like_a_harness_home(&root.join("nowhere"))); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_default_home_appends_dsh_and_is_never_the_user_home() { - let user_home = Path::new("some-user-home"); - let resolved = default_dsh_home(user_home); - assert_eq!(resolved.file_name().and_then(|name| name.to_str()), Some(".dsh")); - assert_ne!(resolved, user_home, "the harness home is ~/.dsh, not ~"); - } - - #[test] - fn windows_prefers_userprofile_because_node_does() { - assert_eq!( - pick_home_variable(Some("C:\\Users\\me"), Some("C:\\elsewhere"), true), - Some("C:\\Users\\me") - ); - assert_eq!(pick_home_variable(None, Some("C:\\elsewhere"), true), Some("C:\\elsewhere")); - } - - #[test] - fn unix_prefers_home() { - assert_eq!(pick_home_variable(None, Some("/home/me"), false), Some("/home/me")); - assert_eq!( - pick_home_variable(Some("C:\\Users\\me"), Some("/home/me"), false), - Some("/home/me") - ); - } - - #[test] - fn blank_home_variables_do_not_count() { - assert_eq!(pick_home_variable(Some(""), None, true), None); - assert_eq!(pick_home_variable(Some(" "), None, true), None); - assert_eq!(pick_home_variable(None, None, false), None); - } -} \ No newline at end of file diff --git a/app/crates/vn-shell-core/src/keystate.rs b/app/crates/vn-shell-core/src/keystate.rs deleted file mode 100644 index f3ba1be..0000000 --- a/app/crates/vn-shell-core/src/keystate.rs +++ /dev/null @@ -1,796 +0,0 @@ -//! Whether a DeepSeek key is available to the harness, and which layer supplied -//! it - the line the shell's control panel shows before the server exists. -//! -//! Why this is a module of its own rather than a few lines in the binary: the -//! answer is a PARSE of two file formats plus four precedence rules, and this -//! repository pins every decision like that with `cargo test` instead of -//! trusting a reading of the code. Nothing here knows about windows, panes or a -//! UI toolkit; the one function that touches the filesystem is [`read`]. -//! -//! ## The layering is the harness's own, not an invention -//! -//! `@deepseek-ai/dsh-credentials-local` owns the real lookup, and its own header -//! states the order (highest first): -//! -//! ```text -//! inherited process environment read-only, wins DEEPSEEK_API_KEY=… dsh -//! > $DSH_HOME/.credentials.yaml provider-managed what Settings > Models writes -//! > /.env read-only fallback -//! > $DSH_HOME/.env read-only fallback -//! ``` -//! -//! The environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI secret or a -//! container `-e` is that run's explicit intent. This module answers "will the -//! harness find a key", so it has to walk the same order - a splash that said -//! "nothing loaded" while the environment supplied one would be wrong in the -//! direction that costs the reader a pointless trip to Settings. -//! -//! The invocation cwd is the SHELL's cwd: the harness is spawned as a child and -//! inherits it, so `/.env` is the same file for both. -//! -//! ## Only presence is reported -//! -//! No value leaves this module, and nothing in it has a field a value COULD -//! leave in. [`KeyState`] carries a `bool` and a [`Source`]; the panel and the -//! console are drawn from [`console_line`] and [`Source::label`], and -//! [`tests::a_real_shaped_key_never_reaches_a_line_this_shell_draws`] feeds a -//! real-looking key in and asserts it comes out of neither. That is the same rule -//! the launch token lives under: read in memory, never written down, never -//! echoed, never drawn. - -use std::path::{Path, PathBuf}; - -/// The credential reference the harness looks for by default -/// (`dsh-llm-deepseek`'s `DEFAULT_API_KEY_ENV`, and the ref -/// `dsh-client-ui-settings-plugins` writes for the Models page). -pub const KEY_REF: &str = "DEEPSEEK_API_KEY"; - -/// Basename of the harness home's credentials document -/// (`dsh-credentials-local`'s `CREDENTIALS_FILENAME`). -const CREDENTIALS_FILENAME: &str = ".credentials.yaml"; - -/// Which layer answered. Ordered as the harness orders them, so `Ord` on this -/// enum would be a precedence order - which is why it is only ever compared for -/// equality. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum Source { - /// An inherited `DEEPSEEK_API_KEY`, whatever put it there. - Environment, - /// `$DSH_HOME/.credentials.yaml`, the file the Models page writes. - CredentialsFile, - /// `.env` in the directory the launcher was started from. - ProjectEnv, - /// `.env` inside the harness home. - HomeEnv, -} - -impl Source { - /// Words for the splash line, phrased as the END of "loaded from …". - pub fn label(self) -> &'static str { - match self { - Source::Environment => "the environment", - Source::CredentialsFile => "the credentials file", - Source::ProjectEnv => "a .env beside the launcher", - Source::HomeEnv => "the harness home's .env", - } - } -} - -/// The answer: no key, or a key and where it came from. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct KeyState { - source: Option, -} - -impl KeyState { - pub fn loaded(&self) -> bool { - self.source.is_some() - } - - pub fn source(&self) -> Option { - self.source - } -} - -/// The pure core: decide from the four layers' TEXT, already read. -/// -/// `None` for a layer means the file does not exist (or could not be read), -/// which is not an error - "no key there" is the honest answer for all of them. -pub fn from_layers( - environment: Option<&str>, - credentials_file: Option<&str>, - project_env: Option<&str>, - home_env: Option<&str>, -) -> KeyState { - let source = if present(environment) { - Some(Source::Environment) - } else if present(credentials_file.and_then(|text| yaml_credential(text, KEY_REF))) { - Some(Source::CredentialsFile) - } else if present(project_env.and_then(|text| dotenv_value(text, KEY_REF))) { - Some(Source::ProjectEnv) - } else if present(home_env.and_then(|text| dotenv_value(text, KEY_REF))) { - Some(Source::HomeEnv) - } else { - None - }; - KeyState { source } -} - -/// Read the four layers for `home` and decide. Best-effort by design: a missing -/// or unreadable layer is simply a layer that answered nothing, because the only -/// thing worse than a splash without a key line is a shell that will not start. -pub fn read(home: Option<&Path>) -> KeyState { - let environment = std::env::var(KEY_REF).ok(); - let credentials_file = home - .map(|home| home.join(CREDENTIALS_FILENAME)) - .and_then(|path| std::fs::read_to_string(path).ok()); - let project_env = std::env::current_dir() - .ok() - .map(|cwd| cwd.join(".env")) - .and_then(|path| std::fs::read_to_string(path).ok()); - let home_env = home - .map(|home| home.join(".env")) - .and_then(|path| std::fs::read_to_string(path).ok()); - from_layers( - environment.as_deref(), - credentials_file.as_deref(), - project_env.as_deref(), - home_env.as_deref(), - ) -} - -/// One line for the console, which is the record a bug report can quote. -/// -/// It names the layer and never the value - the console is the thing people -/// paste into an issue, so it is the last place a key may appear. -pub fn console_line(state: &KeyState) -> String { - match state.source() { - Some(source) => format!("[vncode] DeepSeek key: loaded from {}", source.label()), - None => "[vncode] DeepSeek key: not found (checked the environment, the credentials file and .env) - add one in Settings > Models".to_string(), - } -} - -// --------------------------------------------------------------------------- -// The parsers -// --------------------------------------------------------------------------- - -/// A UTF-8 BOM would otherwise hide the file's FIRST line, and the credentials -/// document's first line can be its only one - a key reported missing because -/// an editor wrote a BOM is exactly the false negative this module exists to -/// avoid. -fn strip_bom(text: &str) -> &str { - text.strip_prefix('\u{feff}').unwrap_or(text) -} - -/// Is this layer's value a key? Absent, blank, quoted-blank and YAML's own -/// nulls all mean "no". -fn present(value: Option<&str>) -> bool { - let Some(value) = value else { - return false; - }; - let value = value.trim(); - let value = value - .strip_prefix('"') - .and_then(|rest| rest.strip_suffix('"')) - .or_else(|| { - value - .strip_prefix('\'') - .and_then(|rest| rest.strip_suffix('\'')) - }) - .unwrap_or(value) - .trim(); - !value.is_empty() && !matches!(value, "~" | "null" | "Null" | "NULL") -} - -/// Cut a YAML inline comment off an UNQUOTED scalar. -/// -/// YAML only starts a comment at a `#` that follows whitespace, and never -/// inside a quoted scalar - so a key containing `#` survives, and `sk-a # mine` -/// loses only the note. -fn without_yaml_comment(value: &str) -> &str { - let trimmed = value.trim_start(); - if trimmed.starts_with('"') || trimmed.starts_with('\'') { - return value; - } - match value.find(" #") { - Some(index) => &value[..index], - None => value, - } -} - -/// Split `name: value` at the FIRST colon - a value may contain colons of its -/// own, and a ref may contain `/` (`client-connection/browser-session`). -fn split_key(line: &str) -> Option<(&str, &str)> { - let (name, value) = line.split_once(':')?; - let name = name.trim_end(); - if name.is_empty() || name.contains(char::is_whitespace) { - return None; - } - Some((name, value)) -} - -/// The value of a credential ref in `.credentials.yaml`. -/// -/// The document's real shape, taken from `dsh-credentials-local` (which owns it) -/// and confirmed against a file the harness itself wrote: -/// -/// ```text -/// version: 1 -/// refs: <- the CredentialRef-to-string mapping -/// DEEPSEEK_API_KEY: sk-… <- ONE level in, not at the margin -/// records: -/// client-connection/browser-session: -/// kind: … -/// payload: -/// secret: … -/// ``` -/// -/// The FIRST version of this function looked for the key at column 0 only, on -/// the strength of the module's own prose ("a strict CredentialRef-to-string -/// mapping", which reads like a flat document). It compiled, and fourteen unit -/// tests written against that same wrong mental model passed - and then the -/// built shell reported "no key" on a machine whose key was sitting right there. -/// The lesson is the shape below, so it is pinned by -/// [`tests::the_real_document_shape_is_read`] with the real file's layout. -/// -/// A genuinely flat document is still accepted, because that prose describes one -/// and an older writer could have produced it. What is NOT accepted is the same -/// name anywhere else: `records:` holds `secret` fields, and a ref buried in a -/// record is not the ref the harness looks up. -fn yaml_credential<'a>(text: &'a str, key: &str) -> Option<&'a str> { - let mut section: Option<&str> = None; - for line in strip_bom(text).lines() { - let line = line.strip_suffix('\r').unwrap_or(line); - let trimmed = line.trim(); - if trimmed.is_empty() || trimmed.starts_with('#') { - continue; - } - let indented = line.len() != line.trim_start().len(); - if !indented { - // A top-level entry: either the next section, or - in the flat - // shape - the credential itself. - let (name, value) = match split_key(trimmed) { - Some(pair) => pair, - None => { - section = None; - continue; - } - }; - section = Some(name); - if name == key { - return Some(without_yaml_comment(value).trim()); - } - continue; - } - // Indented: an entry of whatever section is open, and only `refs:` holds - // credentials. - if section != Some("refs") { - continue; - } - if let Some((name, value)) = split_key(trimmed) { - if name == key { - return Some(without_yaml_comment(value).trim()); - } - } - } - None -} - -/// The value of `KEY=` in a dotenv file, which is not YAML: no indentation -/// rules, an optional `export`, spaces allowed around the `=`, and single or -/// double quotes. -fn dotenv_value<'a>(text: &'a str, key: &str) -> Option<&'a str> { - for line in strip_bom(text).lines() { - let line = line.strip_suffix('\r').unwrap_or(line); - let line = line.trim(); - if line.is_empty() || line.starts_with('#') { - continue; - } - let line = line.strip_prefix("export ").map(str::trim_start).unwrap_or(line); - let Some(rest) = line.strip_prefix(key) else { - continue; - }; - // Then only spaces, then `=`: this is what keeps `DEEPSEEK_API_KEY_OLD=` - // and `DEEPSEEK_API_KEYFILE=` from answering for this key. - let rest = rest.trim_start_matches([' ', '\t']); - let Some(value) = rest.strip_prefix('=') else { - continue; - }; - let value = value.trim(); - let cut = match value.find(" #") { - Some(index) if !value.starts_with('"') && !value.starts_with('\'') => &value[..index], - _ => value, - }; - return Some(cut.trim()); - } - None -} - -// --------------------------------------------------------------------------- -// Writing a key the person typed, and never reading one that is already there -// --------------------------------------------------------------------------- -/// The dotenv file inside a home that the harness reads a key from. -/// -/// `$DSH_HOME/.env` is a **documented layer** of the harness's own credential resolution, -/// not an invention of this app: `@deepseek-ai/dsh-credentials-local` resolves a reference -/// from `$DSH_HOME/.credentials.yaml` and then falls back to the invoking project's -/// `.env` and to this file. That is why the panel writes a key HERE and never into the -/// managed credentials document - the document is a strict `CredentialRef`-to-string YAML -/// mapping the harness refuses to boot on when it is malformed or readable beyond its -/// owner, and this app has no business rewriting it. A secret the person TYPES is ours to -/// place; a secret already stored is not ours to read. -pub const ENV_FILE: &str = ".env"; - -/// The line a key becomes in [`ENV_FILE`], quoted only when it has to be. -/// -/// Both readers strip a matching pair of quotes (`process.loadEnvFile` in Node, and -/// [`dotenv_value`] here), so quoting is the way a value carrying `#` or a space survives -/// intact. A value that cannot be written unambiguously is REFUSED with a sentence rather -/// than escaped into something the harness might read differently - the person can always -/// paste it into the harness's own Models page instead. -pub fn env_value(key: &str) -> Result { - let key = key.trim(); - if key.is_empty() { - return Err( - "there is no key to save - paste the value from the DeepSeek console".to_string(), - ); - } - if key.chars().any(char::is_control) { - return Err( - "the value contains a control character (a newline, a tab or a NUL), which a .env file cannot carry - paste only the key itself, or add it in Settings > Models" - .to_string(), - ); - } - let simple = !key.contains([' ', '\t', '#', '"', '\'', '\\']); - if simple { - return Ok(key.to_string()); - } - if !key.contains(['"', '\\']) { - return Ok(format!("\"{key}\"")); - } - Err( - "the value contains quotes or a backslash, which this file cannot carry without changing it - add the key in the harness's own Settings > Models instead" - .to_string(), - ) -} - -/// Whether a `.env` line assigns `key` - the same rule [`dotenv_value`] reads by, so the -/// writer and the reader cannot disagree about which line is the key's. -/// -/// `DEEPSEEK_API_KEY_OLD=` and `DEEPSEEK_API_KEYFILE=` are NOT the key's line. -fn is_key_line(line: &str, key: &str) -> bool { - let line = line.strip_suffix('\r').unwrap_or(line); - let line = line.trim(); - if line.is_empty() || line.starts_with('#') { - return false; - } - let line = line.strip_prefix("export ").map(str::trim_start).unwrap_or(line); - let Some(rest) = line.strip_prefix(key) else { - return false; - }; - rest.trim_start_matches([' ', '\t']).starts_with('=') -} - -/// **Write the key a person typed into `/.env`**, and return that file's path. -/// -/// Three rules, and each is a promise this app has already made elsewhere: -/// -/// 1. **Nothing is read back.** The value goes one way - from the typed field, through -/// this function, into the file. It is never parsed, never held in a [`KeyState`], -/// never drawn, never logged, and it is not returned: only the PATH comes back, which -/// is what the panel may print. -/// 2. **Every other line survives.** An existing `.env` may hold a proxy, a mirror or -/// another project's variables; only the `DEEPSEEK_API_KEY` line is replaced, in -/// place, and a file with no such line gets one appended. The file's own newline style -/// is kept. -/// 3. **It is written atomically and privately**: a temporary file beside it and a rename -/// (so a crash leaves the old file rather than half of a new one), `0600` on Unix -/// before the rename. The harness refuses to boot on a credentials document that is -/// group- or other-readable; a dotenv holding the same secret deserves no less. -/// -/// A home that cannot be written, or a value that cannot be carried, is refused with a -/// sentence that names the reason and NEVER the value. -pub fn write_env_key(home: &Path, key: &str) -> Result { - let value = env_value(key)?; - let target = home.join(ENV_FILE); - let existing = match std::fs::read_to_string(&target) { - Ok(text) => text, - Err(error) if error.kind() == std::io::ErrorKind::NotFound => String::new(), - Err(error) => { - return Err(format!( - "could not read {}: {error} - add the key in the harness's Settings > Models instead", - target.display() - )) - } - }; - - let newline = if existing.contains("\r\n") { "\r\n" } else { "\n" }; - let line = format!("{KEY_REF}={value}"); - let mut lines: Vec = existing - .split('\n') - .map(|line| line.strip_suffix('\r').unwrap_or(line).to_string()) - .collect(); - // `split` leaves a trailing empty element for text ending in a newline; it is put back - // by the join below, so a file that ended with one still does. - let replaced = lines.iter().position(|candidate| is_key_line(candidate, KEY_REF)); - match replaced { - Some(index) => lines[index] = line, - None => { - if lines.len() == 1 && lines[0].is_empty() { - lines = vec![line]; - } else { - if lines.last().is_some_and(|last| !last.is_empty()) { - lines.push(line); - } else { - // The file ends with its newline: the empty element IS that newline. - let last = lines.len().saturating_sub(1); - lines[last] = line; - } - } - } - } - // A dotenv file that ends mid-line is a trap for the next editor and for the next - // append, so what this writes always ends with exactly one newline - the file's own - // style, CRLF or LF. - let mut text = lines.join(newline); - if !text.is_empty() && !text.ends_with('\n') { - text.push_str(newline); - } - - let directory = home; - std::fs::create_dir_all(directory) - .map_err(|error| format!("could not create {}: {error}", directory.display()))?; - let temporary = home.join(format!("{ENV_FILE}.tmp-{}", std::process::id())); - std::fs::write(&temporary, text.as_bytes()).map_err(|error| { - format!("could not write {}: {error}", temporary.display()) - })?; - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt; - std::fs::set_permissions(&temporary, std::fs::Permissions::from_mode(0o600)) - .map_err(|error| format!("could not restrict {}: {error}", temporary.display()))?; - } - match std::fs::rename(&temporary, &target) { - Ok(()) => Ok(target), - Err(error) => { - let _ = std::fs::remove_file(&temporary); - Err(format!("could not replace {}: {error}", target.display())) - } - } -} - -// --------------------------------------------------------------------------- -// Tests -// --------------------------------------------------------------------------- -#[cfg(test)] -mod tests { - use super::*; - - /// A unique stand-in for a key, so a leak is unmistakable. - /// - /// It is deliberately NOT key-SHAPED. This repository is public and its own - /// `scripts/checks/check-no-secrets.mjs` fails the build on an `sk-`-shaped - /// literal anywhere - including in a test fixture, because a fixture that - /// looks like a live key is indistinguishable from one to a secret scanner - /// (and to a reader). The shaped case is exercised instead by - /// [`a_real_shaped_key_never_reaches_the_page`], which assembles its sample - /// at runtime so no literal exists in the file. - /// - /// The `.env` fixtures below follow the same rule: their values carry a `/`, - /// which keeps them out of the "ref followed by a credential" shape the guard - /// looks for. A bare `from-project` is exactly the length it would flag. - const SECRET: &str = "fixture/not/a/real/key/0001"; - - /// A scratch directory for the writer's tests, under the check's own root when there - /// is one (`VNCODE_TEST_DIR`), so a confined host - where `%TEMP%` is not writable - - /// still runs them. - fn scratch(name: &str) -> PathBuf { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - }; - let path = root.join(format!("vncode-keystate-{}-{name}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - std::fs::create_dir_all(&path).unwrap(); - path - } - - /// The layout a real `$DSH_HOME/.credentials.yaml` has: the ref is nested one - /// level inside `refs:`, and `records:` below it carries `secret` fields. - fn file(key: &str) -> String { - format!( - "version: 1\n\ - refs:\n \ - {key}: {SECRET}\n\ - records:\n \ - client-connection/browser-session:\n \ - kind: local\n \ - payload:\n \ - version: 1\n \ - secret: a-different-secret\n" - ) - } - - #[test] - fn the_real_document_shape_is_read() { - // Pinned byte-for-byte in shape against a document the harness wrote. - // The first cut of this module looked for the key at the margin and - // missed it here - the bug the built shell reported on a machine whose - // key was present. - let state = from_layers(None, Some(&file(KEY_REF)), None, None); - assert_eq!(state.source(), Some(Source::CredentialsFile)); - assert!(state.loaded()); - } - - #[test] - fn a_flat_document_is_still_read() { - // The module's prose describes a ref-to-string mapping, so a document - // with the ref at the margin must keep working too. - let text = format!("version: 1\n{KEY_REF}: {SECRET}\n"); - assert_eq!( - from_layers(None, Some(&text), None, None).source(), - Some(Source::CredentialsFile) - ); - } - - #[test] - fn a_ref_inside_a_record_is_not_a_credential() { - // `records:` is a different section; only `refs:` holds credentials. - let text = format!( - "version: 1\nrefs: {{}}\nrecords:\n some/record:\n {KEY_REF}: {SECRET}\n" - ); - assert!(!from_layers(None, Some(&text), None, None).loaded()); - } - - #[test] - fn an_empty_refs_block_is_not_a_key() { - let text = format!("version: 1\nrefs:\n {KEY_REF}:\nrecords:\n"); - assert!(!from_layers(None, Some(&text), None, None).loaded()); - } - - #[test] - fn the_environment_wins_over_every_file() { - let state = from_layers( - Some("from-env"), - Some(&file(KEY_REF)), - Some("DEEPSEEK_API_KEY=fixture/from-project"), - Some("DEEPSEEK_API_KEY=fixture/from-home"), - ); - assert_eq!(state.source(), Some(Source::Environment)); - } - - #[test] - fn the_credentials_document_is_next() { - let state = from_layers( - Some(" "), - Some(&file(KEY_REF)), - Some("DEEPSEEK_API_KEY=fixture/from-project"), - Some("DEEPSEEK_API_KEY=fixture/from-home"), - ); - assert_eq!(state.source(), Some(Source::CredentialsFile)); - assert!(state.loaded()); - } - - #[test] - fn the_env_files_are_the_fallbacks_in_order() { - assert_eq!( - from_layers( - None, - None, - Some("DEEPSEEK_API_KEY=fixture/from-project"), - Some("DEEPSEEK_API_KEY=fixture/from-home"), - ) - .source(), - Some(Source::ProjectEnv) - ); - assert_eq!( - from_layers(None, None, Some("# nothing here\n"), Some("DEEPSEEK_API_KEY=from-home")).source(), - Some(Source::HomeEnv) - ); - } - - #[test] - fn nothing_anywhere_is_not_loaded() { - let state = from_layers(None, None, None, None); - assert!(!state.loaded()); - assert_eq!(state.source(), None); - assert!(console_line(&state).contains("not found")); - } - - #[test] - fn a_declared_but_empty_key_is_not_a_key() { - for value in ["", " ", "\"\"", "''", "~", "null", "NULL"] { - let text = format!("version: 1\n{KEY_REF}: {value}\n"); - let state = from_layers(None, Some(&text), None, None); - assert!(!state.loaded(), "{value:?} must not count as a key"); - } - } - - #[test] - fn a_longer_name_does_not_answer_for_this_one() { - let text = format!("{KEY_REF}_OLD: {SECRET}\n"); - assert!(!from_layers(None, Some(&text), None, None).loaded()); - let dotenv = format!("{KEY_REF}FILE=/tmp/creds\n"); - assert!(!from_layers(None, None, Some(&dotenv), None).loaded()); - } - - #[test] - fn quotes_comments_bom_and_crlf_are_all_read_correctly() { - let quoted = format!("{KEY_REF}: \"{SECRET}\" # mine\n"); - assert!(from_layers(None, Some("ed), None, None).loaded()); - - let bommed = format!("\u{feff}{KEY_REF}: {SECRET}\n"); - assert!(from_layers(None, Some(&bommed), None, None).loaded()); - - let crlf = format!("version: 1\r\n{KEY_REF}: {SECRET}\r\n"); - assert!(from_layers(None, Some(&crlf), None, None).loaded()); - - let exported = format!("export {KEY_REF}={SECRET}\n"); - assert_eq!( - from_layers(None, None, Some(&exported), None).source(), - Some(Source::ProjectEnv) - ); - - let spaced = format!("{KEY_REF} = {SECRET}\n"); - assert!(from_layers(None, None, Some(&spaced), None).loaded()); - } - - #[test] - fn the_key_the_panel_writes_is_the_key_this_reader_finds() { - // THE ROUND TRIP, and the reason the panel writes this file at all: what it saves - // must be exactly what `keystate` (and the harness, which reads the same layer) - // resolves afterwards. A writer whose output its own reader misses would leave the - // panel saying "not found" about a key it had just stored. - let home = scratch("write-round-trip"); - std::fs::create_dir_all(&home).unwrap(); - let path = write_env_key(&home, " fixture/typed/key ").expect("a plain key is written"); - assert_eq!(path, home.join(ENV_FILE)); - assert_eq!( - std::fs::read_to_string(&path).unwrap(), - "DEEPSEEK_API_KEY=fixture/typed/key\n" - ); - assert!(read(Some(&home)).loaded(), "the reader must find what the writer wrote"); - assert_eq!(read(Some(&home)).source(), Some(Source::HomeEnv)); - let _ = std::fs::remove_dir_all(&home); - } - - #[test] - fn every_other_line_survives_and_the_key_is_never_duplicated() { - // A `.env` may hold a proxy, a mirror or another project's variables. Only the key - // line is touched, in place - and a second save replaces rather than appends. - let home = scratch("write-preserve"); - std::fs::create_dir_all(&home).unwrap(); - let path = home.join(ENV_FILE); - std::fs::write( - &path, - "# my notes\r\nHTTPS_PROXY=http://127.0.0.1:7890\r\nDEEPSEEK_API_KEY=fixture/old/key\r\nOTHER=1\r\n", - ) - .unwrap(); - write_env_key(&home, "fixture/new/key").unwrap(); - let text = std::fs::read_to_string(&path).unwrap(); - assert!(text.contains("# my notes"), "{text}"); - assert!(text.contains("HTTPS_PROXY=http://127.0.0.1:7890"), "{text}"); - assert!(text.contains("OTHER=1"), "{text}"); - assert!(text.contains("DEEPSEEK_API_KEY=fixture/new/key"), "{text}"); - assert!(!text.contains("fixture/old/key"), "the previous value must be gone: {text}"); - assert_eq!( - text.matches("DEEPSEEK_API_KEY=").count(), - 1, - "the key line must not be duplicated: {text}" - ); - // The file's own newline style is kept, CRLF and all. - assert!(text.contains("\r\n"), "{text}"); - // ...and a similar name is NOT the key's line. - std::fs::write(&path, "DEEPSEEK_API_KEYFILE=/tmp/creds\n").unwrap(); - write_env_key(&home, "fixture/another/key").unwrap(); - let text = std::fs::read_to_string(&path).unwrap(); - assert!(text.contains("DEEPSEEK_API_KEYFILE=/tmp/creds"), "{text}"); - assert!(text.contains("DEEPSEEK_API_KEY=fixture/another/key"), "{text}"); - let _ = std::fs::remove_dir_all(&home); - } - - #[test] - fn a_value_that_cannot_be_carried_is_refused_by_name_and_never_echoed() { - let home = scratch("write-refuse"); - std::fs::create_dir_all(&home).unwrap(); - // Blank, and a control character: refused with a sentence, and the value appears in - // neither the sentence nor the error. - let blank = write_env_key(&home, " ").unwrap_err(); - assert!(blank.contains("no key to save"), "{blank}"); - let multiline = write_env_key(&home, "fixture/one\nfixture/two").unwrap_err(); - assert!(multiline.contains("control character"), "{multiline}"); - assert!(!multiline.contains("fixture/one"), "an error carried the value: {multiline}"); - let quoted = write_env_key(&home, "fixture/\"quoted\"").unwrap_err(); - assert!(quoted.contains("Settings > Models"), "{quoted}"); - // Nothing was written by any of those. - assert!(!home.join(ENV_FILE).exists(), "a refused save must not create the file"); - let _ = std::fs::remove_dir_all(&home); - } - - #[test] - fn a_value_that_needs_quoting_gets_it_and_still_reads_back() { - // `#` starts a comment in a dotenv line, so a value carrying one is quoted - which - // Node's own `loadEnvFile` and this reader both strip. - assert_eq!(env_value("fixture/plain/key").unwrap(), "fixture/plain/key"); - assert_eq!(env_value("fixture/with#hash").unwrap(), "\"fixture/with#hash\""); - assert_eq!(env_value("fixture/with space").unwrap(), "\"fixture/with space\""); - let home = scratch("write-quoted"); - std::fs::create_dir_all(&home).unwrap(); - write_env_key(&home, "fixture/with#hash").unwrap(); - assert!(std::fs::read_to_string(home.join(ENV_FILE)) - .unwrap() - .contains("\"fixture/with#hash\"")); - let _ = std::fs::remove_dir_all(&home); - } - - #[test] - fn a_home_that_cannot_be_written_is_a_sentence_and_not_a_panic() { - let root = scratch("write-unwritable"); - std::fs::create_dir_all(&root).unwrap(); - // A home whose parent is a FILE can never be created on any platform. - let blocker = root.join("blocker"); - std::fs::write(&blocker, b"a file, not a directory").unwrap(); - let error = write_env_key(&blocker.join("home"), "fixture/key").unwrap_err(); - assert!(error.contains("could not"), "{error}"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_shell_draws_the_layer_and_never_the_value() { - let state = from_layers(None, Some(&file(KEY_REF)), None, None); - assert!(state.loaded()); - assert!( - !console_line(&state).contains(SECRET), - "the key leaked into the console line" - ); - assert!( - !format!("{state:?}").contains(SECRET), - "the key leaked into a debug line" - ); - assert_eq!(state.source().map(Source::label), Some("the credentials file")); - } - - /// The same claim, with a value shaped exactly like the real thing. - /// - /// Assembled at runtime so this public repository contains no key-shaped - /// literal - `check-no-secrets.mjs` enforces that, and a scanner cannot tell - /// a convincing fixture from a live key. - #[test] - fn a_real_shaped_key_never_reaches_a_line_this_shell_draws() { - let shaped = format!("sk-{}{}", "1234567890", "abcdefghijklmnopqrstuv"); - let text = format!("version: 1\nrefs:\n {KEY_REF}: {shaped}\n"); - let state = from_layers(None, Some(&text), None, None); - assert!(state.loaded(), "a shaped key must be recognised as one"); - let line = console_line(&state); - assert!(!line.contains(&shaped), "the key leaked into the console line"); - assert!(!line.contains("sk-"), "no fragment of the key may appear"); - // The panel's key row is drawn from exactly these two things and nothing - // else, so the row cannot carry more than this test allows. - let row = format!( - "loaded={} ({})", - state.loaded(), - state.source().map(Source::label).unwrap_or("none") - ); - assert!(!row.contains("sk-")); - assert!(row.contains("the credentials file")); - } - - #[test] - fn labels_are_stable() { - // The splash prints these; a typo here is a typo in the window. - assert_eq!(Source::Environment.label(), "the environment"); - assert_eq!(Source::CredentialsFile.label(), "the credentials file"); - assert_eq!(Source::ProjectEnv.label(), "a .env beside the launcher"); - assert_eq!(Source::HomeEnv.label(), "the harness home's .env"); - } - - #[test] - fn the_reader_uses_the_harness_own_names() { - // If either constant drifts from the harness, the indicator silently - // stops working - which is the failure mode nobody would notice. - assert_eq!(KEY_REF, "DEEPSEEK_API_KEY"); - assert_eq!(CREDENTIALS_FILENAME, ".credentials.yaml"); - let read_it: fn(Option<&Path>) -> KeyState = read; - assert!(!read_it(None).loaded() || std::env::var(KEY_REF).is_ok()); - } -} diff --git a/app/crates/vn-shell-core/src/launch.rs b/app/crates/vn-shell-core/src/launch.rs deleted file mode 100644 index 0fe2a6b..0000000 --- a/app/crates/vn-shell-core/src/launch.rs +++ /dev/null @@ -1,617 +0,0 @@ -//! What gets run: the pin, the vendored runtime, and the exact argv. -//! -//! This is where the failure that made the app look like it needed Administrator -//! was fixed, so the rules here are load-bearing rather than tidy: -//! -//! `npx` writes into an npm cache, and on the machine this was written on that -//! cache was owned by an elevated run, so starting the app produced `npm error -//! code EPERM` and npm's own message told the reader to run as Administrator - -//! which makes the ownership problem worse. Nothing about that is a defect in -//! this shell and it cannot be repaired from inside it: the fix is to stop -//! invoking npm to START an application. `scripts/tools/vendor.ps1` resolves the -//! pinned harness once, at BUILD time, into -//! -//! ```text -//! runtime//node/node[.exe] -//! runtime//harness/node_modules/@deepseek-ai/dsh/lib/bin.js -//! ``` -//! -//! and this shell launches that pair directly: no npm, no registry, no network -//! and no cache to be denied. The only path npm still appears on is the fallback -//! a source checkout takes when nobody has vendored the runtime yet. - -use std::ffi::OsString; -use std::path::{Path, PathBuf}; - -use crate::options::Options; - -/// The profile this shell starts, and the one every surface names. -/// -/// `dsh web` and `dsh --profile web` are the SAME profile: `web` is the alias the -/// pin's CLI documents, and it is the pack's one install target. It lives here, in -/// the pure crate, because three places need to agree about it - the supervisor's -/// launch, the prefs reader and the panel's "is the pack installed" row. -pub const PROFILE: &str = "web"; - -/// The package the pinned harness installs under, as `npx` spells it. -/// -/// One constant, because two places name it: the `npx` fallback's argv below, and -/// the launch line the panel and the log print. -pub const PACKAGE: &str = "@deepseek-ai/dsh"; - -/// The runtime identifier directory name, matching `scripts/tools/vendor.ps1`. -pub fn host_rid() -> &'static str { - if cfg!(target_os = "windows") { - if cfg!(target_arch = "aarch64") { - "win-arm64" - } else if cfg!(target_arch = "x86") { - "win-ia32" - } else { - "win-x64" - } - } else if cfg!(target_os = "macos") { - if cfg!(target_arch = "aarch64") { - "mac-arm64" - } else { - "mac-x64" - } - } else if cfg!(target_arch = "aarch64") { - "linux-arm64" - } else { - "linux-x64" - } -} - -/// How this launch will start the harness. -#[derive(Clone, Debug, PartialEq, Eq)] -pub enum Launch { - /// A vendored runtime: run this Node on this bin.js. No package manager. - Vendored { node: PathBuf, bin: PathBuf }, - /// The harness this machine ALREADY has, run with the Node on PATH. - /// - /// The pack's profile live-links `@deepseek-ai/dsh` out of the npm/npx cache, so - /// where the pack is installed the harness is already on disk - it is the - /// installation a browser tab is running right now. Starting it from here needs - /// no npm, no network and no writable cache, which matters because npm is the - /// one part of this path that can fail for reasons that have nothing to do with - /// this application: a cache an elevated run made unwritable, a machine where an - /// administrator has to be asked, a network that is not there. - Installed { node: PathBuf, bin: PathBuf }, - /// Nothing local, so fall back to `npx web`. - Npx, - /// The test seam: run this program instead of the harness. - /// - /// Reached only through `VNCODE_STUB_CLI` / `VNCODE_STUB_ARGS`, which the - /// shipped launchers never set. It exists so `scripts/checks/check-shell.mjs` - /// can drive the REAL supervisor - the ready-line watch, the refusals, the - /// token rule and Stop - without a harness on the machine, which is the - /// difference between a check that proves behaviour and a check that greps - /// source. `args` is the prefix, so the check can name an INTERPRETER and a - /// script (`node stub.mjs`), which is what makes the seam work on all three - /// platforms without an executable bit. - Stub { program: PathBuf, args: Vec }, -} - -impl Launch { - pub fn kind(&self) -> &'static str { - match self { - Launch::Vendored { .. } => "vendored runtime", - Launch::Installed { .. } => "the installation this machine already has", - Launch::Npx => "npx fallback", - Launch::Stub { .. } => "stub (test seam)", - } - } -} - -/// The program and argv, as data, so the launch decision is testable without -/// spawning anything. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Command { - pub program: OsString, - pub args: Vec, -} - -/// `npx.cmd` on Windows, `npx` elsewhere. -/// -/// std runs a batch file through `cmd.exe` itself, and the spec/flag values here -/// are plain enough that nothing in them can be read as a shell metacharacter. -pub fn npx_program() -> &'static str { - if cfg!(target_os = "windows") { - "npx.cmd" - } else { - "npx" - } -} - -/// The exact argv for a launch: `web --no-open --port N`, and for npx the -/// package spec in front of it. -pub fn program_and_args(launch: &Launch, version: &str, port: u16) -> Command { - let port = port.to_string(); - match launch { - // Both of these run a real Node on a real bin.js: one is the copy this - // application vendored, the other is the copy already on this machine. The - // argv is identical because the harness does not care which it is. - Launch::Vendored { node, bin } | Launch::Installed { node, bin } => Command { - program: node.clone().into_os_string(), - args: vec![ - bin.clone().into_os_string(), - "web".into(), - "--no-open".into(), - "--port".into(), - port.into(), - ], - }, - Launch::Npx => Command { - program: npx_program().into(), - args: vec![ - "--yes".into(), - format!("{PACKAGE}@{version}").into(), - "web".into(), - "--no-open".into(), - "--port".into(), - port.into(), - ], - }, - Launch::Stub { program, args } => { - let mut full = args.iter().map(OsString::from).collect::>(); - full.extend([ - OsString::from("web"), - OsString::from("--no-open"), - OsString::from("--port"), - OsString::from(port), - ]); - Command { program: program.clone().into_os_string(), args: full } - } - } -} - -/// Resolve the vendored runtime, if one is complete. -/// -/// Complete means all THREE pieces exist - the Node, the harness entry point and -/// the stamp. A half-copied runtime must not be chosen, because the shell would -/// then fail to start the harness and report a broken install rather than falling -/// back to the path that works. The stamp is what `scripts/tools/vendor.ps1` writes -/// LAST, after it has run the pair and watched it report a version, so its -/// presence is a claim this shell can trust. -pub fn vendored_runtime(root: &Path) -> Option { - let runtime = root.join("runtime").join(host_rid()); - let node_name = if cfg!(target_os = "windows") { "node.exe" } else { "node" }; - let node = runtime.join("node").join(node_name); - let bin = runtime - .join("harness") - .join("node_modules") - .join("@deepseek-ai") - .join("dsh") - .join("lib") - .join("bin.js"); - if !node.is_file() || !bin.is_file() || !runtime.join("VENDOR.json").is_file() { - return None; - } - Some(Launch::Vendored { node, bin }) -} - -/// The package name the harness installs under, and the entry point inside it. -fn harness_in(directory: &Path) -> Option { - let dsh = directory.join("@deepseek-ai").join("dsh"); - let bin = dsh.join("lib").join("bin.js"); - if !bin.is_file() { - return None; - } - Some(dsh) -} - -/// Every cache a previously installed harness might live in, **this project's own -/// first**. -/// -/// Measured on the machine this was written on: an app whose root, home, pack, sessions -/// and key were all inside a portable folder still started its harness out of -/// `%LOCALAPPDATA%\npm-cache\_npx\…` - the one directory that made "everything is in this -/// folder" untrue on every single Start. The folder's own cache is where the app's own -/// installs land (`env::choose_cache` hands it to every child as `npm_config_cache`), so -/// it is searched first; the checkout's `runtime/npm-cache` is next; and the machine's -/// shared cache is LAST, which is the order that keeps a portable folder portable while -/// still finding the harness a `run-web` on the same machine already installed. -pub fn harness_caches(app_root: Option<&Path>, root: Option<&Path>) -> Vec { - let mut caches = Vec::new(); - if let Some(app_root) = app_root { - caches.push(crate::appdata::npm_cache_dir(app_root)); - } - if let Some(root) = root { - caches.push(root.join("runtime").join("npm-cache")); - } - if let Some(machine) = crate::appdata::npx_cache_root() { - caches.push(machine); - } - caches.dedup(); - caches -} - -/// The `_npx` installations inside one cache, sorted so two runs on one machine make the -/// same choice. -fn npx_candidates(cache_root: &Path) -> Vec { - let mut found: Vec = std::fs::read_dir(cache_root.join("_npx")) - .into_iter() - .flatten() - .flatten() - .map(|entry| entry.path().join("node_modules")) - .filter(|path| path.is_dir()) - .collect(); - found.sort(); - found -} - -/// Every place a previously installed harness might be, best candidate first. -/// -/// The profile's own link is first because it is EXACTLY the installation a browser -/// tab runs: `$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh` is a junction into -/// the npm cache, so following it cannot pick a different harness than the one this -/// machine is already using. The `_npx` scans behind it are for a machine where the -/// profile has not been linked yet (or was reinstalled from elsewhere), and they run -/// over the caches in the order [`harness_caches`] gave them. -pub fn installed_candidates(home: Option<&Path>, caches: &[PathBuf]) -> Vec { - let mut candidates = Vec::new(); - if let Some(home) = home { - candidates.push(home.join("profiles").join("node_modules")); - } - for cache in caches { - candidates.extend(npx_candidates(cache)); - } - candidates -} - -/// The version a harness installation reports, if it says. -fn installed_version(dsh: &Path) -> Option { - let text = std::fs::read_to_string(dsh.join("package.json")).ok()?; - let json: serde_json::Value = serde_json::from_str(&text).ok()?; - json.get("version")?.as_str().map(str::to_string) -} - -/// The harness this machine already has, at the pinned version - and how to run it -/// without npm. -/// -/// `version` is the pin, and it is a REQUIREMENT rather than a preference: a machine -/// can have several harness installations in its cache (this one has four), and -/// starting the wrong one would be a shell that quietly runs a different harness -/// than `scripts\run-web.bat` does. An installation whose `package.json` names -/// another version is skipped, and the search continues. -pub fn installed_harness_in( - home: Option<&Path>, - caches: &[PathBuf], - version: &str, -) -> Option { - for directory in installed_candidates(home, caches) { - let Some(dsh) = harness_in(&directory) else { - continue; - }; - if installed_version(&dsh).as_deref() != Some(version) { - continue; - } - return Some(Launch::Installed { - // The Node on PATH: this is the machine's own installation, so it is the - // machine's own Node that runs it, exactly as an `npx` run would. - node: PathBuf::from(if cfg!(windows) { "node.exe" } else { "node" }), - bin: dsh.join("lib").join("bin.js"), - }); - } - None -} - -/// [`installed_harness_in`], against the caches this project owns - its own root's cache -/// first, then the checkout's, and the machine's shared one last. -pub fn installed_harness( - home: Option<&Path>, - app_root: Option<&Path>, - root: Option<&Path>, - version: &str, -) -> Option { - installed_harness_in(home, &harness_caches(app_root, root), version) -} - -/// The test seam, read from the environment. -/// -/// Environment variables rather than flags on purpose: they must not widen the -/// flag set the three launchers share, and nothing a user types can reach them by -/// accident. `VNCODE_STUB_CLI` names the program and `VNCODE_STUB_ARGS` is an -/// optional JSON array of arguments in front of the CLI's own (which is how the -/// check runs `node web --no-open --port N`). A path that does not -/// exist is ignored with a loud line, so a stale value in a shell profile cannot -/// make the app silently do nothing. -pub fn stub_from_env() -> Option<(PathBuf, Vec)> { - let value = std::env::var("VNCODE_STUB_CLI").ok()?; - let value = value.trim(); - if value.is_empty() { - return None; - } - let path = PathBuf::from(value); - if !path.is_file() { - eprintln!( - "[vncode] VNCODE_STUB_CLI names {} which is not a file; launching the real harness instead.", - path.display() - ); - return None; - } - let args = std::env::var("VNCODE_STUB_ARGS") - .ok() - .and_then(|raw| serde_json::from_str::>(&raw).ok()) - .unwrap_or_default(); - eprintln!( - "[vncode] TEST SEAM: running {} instead of the harness (VNCODE_STUB_CLI is set).", - path.display() - ); - Some((path, args)) -} - -/// Decide how to launch, best first. -/// -/// 1. The test seam, if a check set it. -/// 2. The VENDORED runtime - its own Node, checksum-verified, no npm anywhere. -/// 3. The harness this machine ALREADY has at the pin, run with the Node on PATH, -/// searched in THIS project's caches before the machine's own ([`harness_caches`]). -/// This is the rung that matters when npm itself is broken: no cache to write, -/// no network, no package manager. -/// 4. `npx`, the last resort. -pub fn choose_launch( - root: Option<&Path>, - app_root: Option<&Path>, - home: Option<&Path>, - version: &str, -) -> Launch { - if let Some((program, args)) = stub_from_env() { - return Launch::Stub { program, args }; - } - if let Some(vendored) = root.and_then(vendored_runtime) { - return vendored; - } - installed_harness(home, app_root, root, version).unwrap_or(Launch::Npx) -} - -// --------------------------------------------------------------------------- -// The repository root and the pin -// --------------------------------------------------------------------------- -/// Find the repository root by walking up from this executable looking for -/// `.dsh-version.json`. -/// -/// Walking beats counting directories: the build might be `target/release`, -/// `target/debug`, or a `CARGO_TARGET_DIR` somewhere else entirely, and all three -/// must land on the same root. With a workspace the binary lands one level -/// deeper, which is exactly why this walks rather than counts. -pub fn repo_root() -> Option { - let mut directory = std::env::current_exe().ok()?.parent()?.to_path_buf(); - for _ in 0..8 { - if directory.join(".dsh-version.json").is_file() { - return Some(directory); - } - directory = directory.parent()?.to_path_buf(); - } - None -} - -/// The pinned dsh version: the flag wins, then `.dsh-version.json`. -/// -/// There is deliberately NO built-in fallback. A stale hard-coded pin would mean a -/// shell that quietly runs a different harness than `scripts\run-web.bat`, so an -/// unreadable manifest is an error that names the file. -pub fn resolve_version(options: &Options) -> Result { - resolve_version_with(options, repo_root().as_deref()) -} - -/// The pure half of [`resolve_version`], so the pin rule is testable without a -/// checkout at a fixed path. -pub fn resolve_version_with(options: &Options, root: Option<&Path>) -> Result { - if let Some(version) = options.dsh_version.as_ref().filter(|value| !value.is_empty()) { - return Ok(version.clone()); - } - let root = root.ok_or_else(|| { - "could not find .dsh-version.json in this folder or any folder above it - run the shell from inside the vncode repository, or pass -DshVersion ".to_string() - })?; - let manifest = root.join(".dsh-version.json"); - let text = std::fs::read_to_string(&manifest) - .map_err(|error| format!("could not read {}: {error}", manifest.display()))?; - let json: serde_json::Value = serde_json::from_str(&text) - .map_err(|error| format!("{} is not valid JSON: {error}", manifest.display()))?; - json.get("dsh") - .and_then(|value| value.as_str()) - .map(|value| value.to_string()) - .ok_or_else(|| format!("{} has no \"dsh\" version pin", manifest.display())) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn strings(command: &Command) -> Vec { - command - .args - .iter() - .map(|value| value.to_string_lossy().to_string()) - .collect() - } - - #[test] - fn the_vendored_launch_runs_node_on_bin_js_with_the_same_flags_as_run_web() { - let launch = Launch::Vendored { - node: PathBuf::from("/rt/node/node"), - bin: PathBuf::from("/rt/harness/bin.js"), - }; - let command = program_and_args(&launch, "0.2.0-rc.2", 3080); - assert_eq!(command.program, OsString::from("/rt/node/node")); - assert_eq!( - strings(&command), - vec!["/rt/harness/bin.js", "web", "--no-open", "--port", "3080"] - ); - } - - #[test] - fn the_npx_fallback_carries_the_pin_and_the_same_flags() { - let command = program_and_args(&Launch::Npx, "0.2.0-rc.2", 3099); - assert_eq!(command.program, OsString::from(npx_program())); - assert_eq!( - strings(&command), - vec![ - "--yes", - "@deepseek-ai/dsh@0.2.0-rc.2", - "web", - "--no-open", - "--port", - "3099" - ] - ); - } - - #[test] - fn the_stub_seam_is_given_the_shapes_the_harness_would_see() { - // So a stub can behave like the CLI - including the ready line - without - // the check having to know which launch branch was taken. The prefix is - // what lets the seam name an interpreter, which is how it works on - // Windows without an executable bit. - let launch = Launch::Stub { - program: PathBuf::from("/usr/bin/node"), - args: vec!["/tmp/stub.mjs".to_string()], - }; - let command = program_and_args(&launch, "0.2.0-rc.2", 1234); - assert_eq!(command.program, OsString::from("/usr/bin/node")); - assert_eq!( - strings(&command), - vec!["/tmp/stub.mjs", "web", "--no-open", "--port", "1234"] - ); - } - - #[test] - fn a_half_vendored_runtime_is_not_chosen() { - // The stamp is written LAST by vendor.ps1, after it has run the pair, so - // a runtime without it is a runtime nobody has proved. - let root = crate::scratch::dir("half-vendored"); - let runtime = root.join("runtime").join(host_rid()); - std::fs::create_dir_all(runtime.join("node")).unwrap(); - std::fs::create_dir_all(runtime.join("harness").join("node_modules")).unwrap(); - let node_name = if cfg!(target_os = "windows") { "node.exe" } else { "node" }; - std::fs::write(runtime.join("node").join(node_name), b"x").unwrap(); - assert!(vendored_runtime(&root).is_none(), "an unproved runtime was chosen"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_pin_comes_from_the_flag_before_the_manifest() { - let options = Options { dsh_version: Some("9.9.9".into()), ..Options::default() }; - assert_eq!(resolve_version_with(&options, None).unwrap(), "9.9.9"); - } - - #[test] - fn an_unreadable_pin_is_an_error_that_names_the_file() { - let options = Options::default(); - let error = resolve_version_with(&options, None).unwrap_err(); - assert!(error.contains(".dsh-version.json"), "{error}"); - - let empty = crate::scratch::dir("pin"); - std::fs::create_dir_all(&empty).unwrap(); - let error = resolve_version_with(&options, Some(&empty)).unwrap_err(); - assert!(error.contains("could not read"), "{error}"); - let _ = std::fs::remove_dir_all(&empty); - } - - #[test] - fn the_pin_is_read_out_of_the_manifest_this_repository_ships() { - // The real manifest, found by walking up from the test binary - which is - // the same walk the shell does at run time, one directory deeper. - let root = repo_root().expect("the test binary is not inside a vncode checkout"); - let options = Options::default(); - let version = resolve_version_with(&options, Some(&root)).unwrap(); - assert!(!version.is_empty()); - assert!(version.starts_with("0."), "unexpected pin {version}"); - } - - // ----------------------------------------------------------------------- - // Which cache a harness is found in - // ----------------------------------------------------------------------- - - /// Put one `_npx//node_modules/@deepseek-ai/dsh` at `version` inside `cache`. - fn cache_at(cache: &Path, id: &str, version: &str) { - let dsh = cache.join("_npx").join(id).join("node_modules").join("@deepseek-ai").join("dsh"); - std::fs::create_dir_all(dsh.join("lib")).unwrap(); - std::fs::write(dsh.join("lib").join("bin.js"), b"// harness").unwrap(); - std::fs::write( - dsh.join("package.json"), - format!("{{\"name\":\"@deepseek-ai/dsh\",\"version\":\"{version}\"}}"), - ) - .unwrap(); - } - - #[test] - fn this_projects_own_cache_is_searched_before_the_machines_shared_one() { - // The measured complaint: everything of the person's was inside a portable - // folder, and the harness still came out of `%LOCALAPPDATA%\npm-cache` on every - // Start. The folder's own cache is where this app's own installs land, so it is - // the first place looked. - let root = crate::scratch::dir("cache-order"); - let _ = std::fs::remove_dir_all(&root); - let app_root = root.join("project-root"); - // The harness is in the ROOT'S OWN cache - where this app's installs land. - cache_at(&crate::appdata::npm_cache_dir(&app_root), "project", "0.2.0-rc.2"); - let checkout = root.join("checkout"); - - let caches = harness_caches(Some(&app_root), Some(&checkout)); - assert_eq!(caches[0], crate::appdata::npm_cache_dir(&app_root), "this app's own first"); - assert_eq!( - caches[1], - checkout.join("runtime").join("npm-cache"), - "then the checkout's own" - ); - // ...and the machine's shared cache is the LAST place, never the first. - assert_eq!(caches.last().cloned(), crate::appdata::npx_cache_root()); - - // The harness is found at the pin... - let launch = installed_harness_in(None, &caches, "0.2.0-rc.2").expect("a harness"); - match launch { - Launch::Installed { bin, .. } => assert!( - bin.starts_with(crate::appdata::npm_cache_dir(&app_root)), - "the wrong cache won: {}", - bin.display() - ), - other => panic!("{other:?}"), - } - // ...and a cache holding ANOTHER version is skipped rather than used. - assert!(installed_harness_in(None, &caches, "9.9.9").is_none()); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_profiles_own_link_still_comes_before_every_cache() { - // It is EXACTLY the installation a browser tab runs, so it outranks a cache scan - // even when both hold the pin. - let root = crate::scratch::dir("profile-link"); - let _ = std::fs::remove_dir_all(&root); - let cache = root.join("machine-cache"); - cache_at(&cache, "machine", "0.2.0-rc.2"); - let home = root.join("home"); - let linked = home - .join("profiles") - .join("node_modules") - .join("@deepseek-ai") - .join("dsh"); - std::fs::create_dir_all(linked.join("lib")).unwrap(); - std::fs::write(linked.join("lib").join("bin.js"), b"// linked").unwrap(); - std::fs::write( - linked.join("package.json"), - "{\"name\":\"@deepseek-ai/dsh\",\"version\":\"0.2.0-rc.2\"}", - ) - .unwrap(); - - let candidates = installed_candidates(Some(&home), &[cache]); - assert_eq!(candidates[0], home.join("profiles").join("node_modules")); - let launch = installed_harness_in(Some(&home), &[PathBuf::from("/nowhere")], "0.2.0-rc.2") - .expect("the profile's own link is a harness"); - match launch { - Launch::Installed { bin, .. } => assert!(bin.starts_with(&home), "{}", bin.display()), - other => panic!("{other:?}"), - } - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn with_no_app_root_the_machine_cache_is_still_reachable() { - // A build run from somewhere with no root of its own must not lose the rung. - let caches = harness_caches(None, Some(Path::new("/repo"))); - assert_eq!(caches[0], PathBuf::from("/repo").join("runtime").join("npm-cache")); - assert!(!caches.is_empty()); - } -} diff --git a/app/crates/vn-shell-core/src/lib.rs b/app/crates/vn-shell-core/src/lib.rs deleted file mode 100644 index c4ccbe7..0000000 --- a/app/crates/vn-shell-core/src/lib.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! The vncode shell's PURE half. -//! -//! Everything here is decided by `cargo test`, and nothing here opens a window, draws a -//! pixel, binds a port or owns a process. The split is the shell's whole safety argument: -//! the rules that keep the model API key inside (`keystate`) and the rules that decide -//! WHICH harness home this shell runs against (`home`, `appdata`, `userpath`) are testable -//! without a display, without a network and without a harness on disk. -//! -//! There is no web engine here and no window state. The page is the harness's, it is -//! served on loopback, and the browser that shows it is started by `scripts/run-web.*` - -//! which is also the only thing that ever reads a launch token. -//! -//! The modules that carry the load-bearing rules were MOVED here from the old -//! `app/src-tauri` tree rather than rewritten, comments and tests included: `readyline` -//! (the token, and its redaction), `keystate` (the four key layers, presence only) and - -//! as what is now `appdata` - the application-data root. A rewrite of any of them would be -//! a regression by definition, because each one is the record of a bug that was measured -//! on a real machine. - -pub mod appdata; -pub mod home; -pub mod keystate; -pub mod launch; -pub mod log; -pub mod options; -pub mod ports; -pub mod prefs; -pub mod profile; -pub mod readyline; -pub mod userpath; - -/// Where a test writes. Test-only, and overridable so the checks can run on a -/// host that denies the system temp directory. -#[cfg(test)] -mod scratch; diff --git a/app/crates/vn-shell-core/src/log.rs b/app/crates/vn-shell-core/src/log.rs deleted file mode 100644 index 60070e9..0000000 --- a/app/crates/vn-shell-core/src/log.rs +++ /dev/null @@ -1,171 +0,0 @@ -//! The shell's log: bounded, and redacted on the way in. -//! -//! Two rules, both from things that went wrong elsewhere in this pack: -//! -//! - a transcript that grows without a ceiling is a memory leak with a friendly -//! name, so this one is a ring with a cap and the oldest line leaves first; -//! - the harness's own output passes through [`crate::readyline::redact`] BEFORE -//! it is stored, so a line that carried the launch token cannot be sitting in -//! the panel when somebody screenshots it. Redacting at push rather than at -//! draw means there is no code path that can skip it. - -use std::collections::VecDeque; - -use crate::readyline::redact; - -/// How many lines the panel keeps. Enough for a start-up transcript, small enough -/// that the ring can never be the reason the app grows. -pub const DEFAULT_CAP: usize = 500; - -pub struct Log { - lines: VecDeque, - cap: usize, - /// How many lines have EVER been pushed, so a reader can follow the log - /// without losing its place when the ring drops the oldest line. - pushed: u64, -} - -impl Default for Log { - fn default() -> Self { - Log::new(DEFAULT_CAP) - } -} - -impl Log { - /// A cap of zero is a log that keeps nothing, which is legal but pointless - - /// it is clamped to one line so the type cannot be used as a silent discard. - pub fn new(cap: usize) -> Self { - Log { lines: VecDeque::new(), cap: cap.max(1), pushed: 0 } - } - - /// Store one line, redacted. The ONLY way in. - pub fn push(&mut self, line: &str) { - while self.lines.len() >= self.cap { - self.lines.pop_front(); - } - self.lines.push_back(redact(line)); - self.pushed += 1; - } - - /// A cursor for [`Log::since`]: hand this back later to get only what is new. - pub fn position(&self) -> u64 { - self.pushed - } - - /// Every line pushed at or after `position`, oldest first. - /// - /// A `position` that is older than the ring's own memory simply starts at the - /// oldest line still held: a reader that fell behind gets what is left rather - /// than an error, which is the right trade for a transcript. - pub fn since(&self, position: u64) -> Vec { - let oldest = self.pushed.saturating_sub(self.lines.len() as u64); - let skip = position.saturating_sub(oldest) as usize; - self.lines.iter().skip(skip).cloned().collect() - } - - pub fn len(&self) -> usize { - self.lines.len() - } - - pub fn is_empty(&self) -> bool { - self.lines.is_empty() - } - - pub fn cap(&self) -> usize { - self.cap - } - - pub fn lines(&self) -> impl Iterator { - self.lines.iter().map(String::as_str) - } - - /// The newest `count` lines, oldest first - the order a person reads them. - pub fn tail(&self, count: usize) -> Vec { - let skip = self.lines.len().saturating_sub(count); - self.lines.iter().skip(skip).cloned().collect() - } - - /// Everything, for the console or for a bug report. - pub fn joined(&self) -> String { - self.lines.iter().cloned().collect::>().join("\n") - } -} - -#[cfg(test)] -mod tests { - use super::*; - - fn token() -> String { - format!("{}{}", "cafebabe", "1122334455667788") - } - - #[test] - fn a_line_that_carried_the_token_is_stored_redacted() { - let mut log = Log::default(); - log.push(&format!("dsh web: http://127.0.0.1:3080/?token={}", token())); - let stored = log.joined(); - assert!(!stored.contains(&token()), "the token reached the log: {stored}"); - assert!(stored.contains("REDACTED"), "{stored}"); - // ...and it is still readable enough to be useful. - assert!(stored.contains("127.0.0.1:3080"), "{stored}"); - } - - #[test] - fn the_ring_drops_the_oldest_line_first() { - let mut log = Log::new(3); - for line in ["one", "two", "three", "four"] { - log.push(line); - } - assert_eq!(log.len(), 3); - assert_eq!(log.tail(10), vec!["two", "three", "four"]); - } - - #[test] - fn a_zero_cap_is_clamped_rather_than_silently_discarding_everything() { - let mut log = Log::new(0); - log.push("kept"); - assert_eq!(log.len(), 1); - assert_eq!(log.cap(), 1); - } - - #[test] - fn the_tail_is_the_newest_lines_in_reading_order() { - let mut log = Log::default(); - for index in 0..10 { - log.push(&format!("line {index}")); - } - assert_eq!(log.tail(2), vec!["line 8", "line 9"]); - assert_eq!(log.tail(0).len(), 0); - assert_eq!(log.tail(999).len(), 10); - } - - #[test] - fn a_reader_can_follow_the_log_without_losing_its_place() { - // This is what the headless mode and the panel's console use: a cursor - // rather than a tail, so a line cannot be printed twice or skipped. - let mut log = Log::default(); - log.push("one"); - let cursor = log.position(); - log.push("two"); - log.push("three"); - assert_eq!(log.since(cursor), vec!["two", "three"]); - // Reading again from the same cursor is idempotent... - assert_eq!(log.since(cursor), vec!["two", "three"]); - // ...and a cursor at the end yields nothing. - assert!(log.since(log.position()).is_empty()); - } - - #[test] - fn a_reader_that_fell_behind_gets_what_is_left_rather_than_an_error() { - let mut log = Log::new(2); - for index in 0..6 { - log.push(&format!("line {index}")); - } - // The ring holds line 4 and line 5; a cursor from the very beginning - // therefore starts at line 4. - assert_eq!(log.since(0), vec!["line 4", "line 5"]); - assert_eq!(log.since(5), vec!["line 5"]); - assert!(log.since(6).is_empty()); - assert_eq!(log.position(), 6); - } -} diff --git a/app/crates/vn-shell-core/src/options.rs b/app/crates/vn-shell-core/src/options.rs deleted file mode 100644 index 48ee55b..0000000 --- a/app/crates/vn-shell-core/src/options.rs +++ /dev/null @@ -1,282 +0,0 @@ -//! The flags and the verbs, mirroring `scripts\run-web.bat` / `scripts/run-web.sh`, -//! so the app and the launchers stay interchangeable. -//! -//! Both spellings of each flag are accepted (`-Port` and `--port`) and matching is -//! case-insensitive, because `-Port` is what the batch files document and `--port` is what -//! a shell user types. An unknown flag, and an unknown verb, are an ERROR that names what -//! was not understood: the things a typo turns into are the ones that decide which harness -//! home is used and which script is run. -//! -//! There is no `-Mode` any more, and its absence is the change this shell is made of: it -//! draws no window and no web view, so "panel or browser or embed" ceased to be a choice. -//! What is left is what it DOES - install, ask for the key, start the web launcher - and -//! each of those is a verb. - -use std::fmt; - -/// What this run is asked to do. -/// -/// `Start` is what no verb means: the whole path, from "is the pack installed" to "the -/// browser has the page". -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum Command { - /// Install the pack if the profile lacks it, ask for the key if there is none, then - /// run `scripts/run-web.*` in the foreground. - Start, - /// Run `scripts/setup/install.*` against the home in use. - Install, - /// Run the matching pair. - Uninstall, - /// Print the facts and start nothing. - Status, - /// Ask for the DeepSeek key and write it into `/.env`. - Key, -} - -impl Command { - pub fn name(self) -> &'static str { - match self { - Command::Start => "start", - Command::Install => "install", - Command::Uninstall => "uninstall", - Command::Status => "status", - Command::Key => "key", - } - } - - pub fn parse(value: &str) -> Result { - match value.to_ascii_lowercase().as_str() { - "start" | "run" => Ok(Command::Start), - "install" | "add" => Ok(Command::Install), - "uninstall" | "remove" => Ok(Command::Uninstall), - "status" | "info" => Ok(Command::Status), - "key" | "token" => Ok(Command::Key), - other => Err(format!( - "unknown command '{other}' - expected one of start, install, uninstall, status or key \ - (no command means start)" - )), - } - } -} - -impl fmt::Display for Command { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - formatter.write_str(self.name()) - } -} - -/// The flags this shell parses. -#[derive(Clone, Default, Debug, PartialEq, Eq)] -pub struct Options { - /// What to do; `None` is `Command::Start`. - pub command: Option, - /// Explicit port handed to the web launcher; 0 means "let the harness decide". - pub port: u16, - pub dsh_home: Option, - pub dsh_version: Option, - pub help: bool, - pub version: bool, -} - -impl Options { - /// The verb this run will perform. - pub fn command(&self) -> Command { - self.command.unwrap_or(Command::Start) - } -} - -/// Parse the flags and the one optional verb. -pub fn parse_args(args: impl Iterator) -> Result { - let mut options = Options::default(); - let mut args = args; - while let Some(argument) = args.next() { - let name = argument.to_ascii_lowercase(); - match name.as_str() { - "-port" | "--port" => { - let value = next_value(&mut args, "-Port")?; - options.port = value - .parse::() - .map_err(|_| format!("-Port expects a port number, got '{value}'"))?; - if options.port == 0 { - return Err("-Port expects a port number above zero".to_string()); - } - } - "-dshhome" | "--dshhome" => options.dsh_home = Some(next_value(&mut args, "-DshHome")?), - "-dshversion" | "--dshversion" => { - options.dsh_version = Some(next_value(&mut args, "-DshVersion")?) - } - "-help" | "--help" | "-h" | "/?" => options.help = true, - "-version" | "--version" | "-v" => options.version = true, - other if other.starts_with('-') || other.starts_with('/') => { - return Err(format!( - "unknown flag '{other}' - run `vncode -Help` for the accepted flags" - )) - } - verb => { - // ONE verb, and it goes first by convention - but a flag before it is - // ordinary (`vncode -DshHome C:\h start`), so the verb is taken wherever - // it appears rather than only at argv[0]. - let parsed = Command::parse(verb)?; - if options.command.is_some() { - return Err(format!( - "only one command may be given - this run already asked for '{}'", - options.command().name() - )); - } - options.command = Some(parsed); - } - } - } - Ok(options) -} - -fn next_value(args: &mut impl Iterator, flag: &str) -> Result { - args.next() - .ok_or_else(|| format!("{flag} needs a value after it")) -} - -/// The usage text. One string, so the verbs and flags this shell accepts live in exactly -/// one place and a check can drive the binary and read it back. -pub const USAGE: &str = "\ -Usage: vncode [start|install|uninstall|status|key] [flags] - - (no command) install the pack if this home lacks it, ask for the DeepSeek key - if there is none, then start the harness and open it - this runs - scripts/run-web.bat (Windows) or scripts/run-web.sh, in the - foreground, exactly as double-clicking that file does - start the same thing, spelled out - install run scripts/setup/install.* against the home in use - uninstall run scripts/setup/uninstall.* against it - status print the pin, the home and why it was chosen, the pack, the key - layer and where the launcher is; start nothing - key ask for the DeepSeek key and write it into /.env (0600) - - -Port hand this port to the web launcher instead of the harness default - -DshHome use this harness home instead of the one the app chose - (a leading ~ is expanded; a relative path is resolved here) - -DshVersion override the pinned dsh version from .dsh-version.json - -Help print this help - -Version print the version - -vncode is the app's front door, not a second harness: it decides the root, the key and -the pack, and then runs the SAME scripts a person would run. Launching only the web -needs none of this - scripts/run-web.bat or ./scripts/run-web.sh works on its own. - -The app owns a root ($VNCODE_HOME) and the harness home is /home inside it. This -command never draws the interface: the page opens in a browser it found."; - -pub fn print_usage() { - println!(); - println!("{USAGE}"); - println!(); -} - -pub fn print_version() { - println!("vncode {}", env!("CARGO_PKG_VERSION")); -} - -#[cfg(test)] -mod tests { - use super::*; - - fn args(list: &[&str]) -> std::vec::IntoIter { - list.iter() - .map(|value| value.to_string()) - .collect::>() - .into_iter() - } - - #[test] - fn the_flags_run_web_documents_are_accepted_in_both_spellings() { - let options = - parse_args(args(&["-Port", "3099", "-DshHome", "/tmp/h", "-DshVersion", "9.9.9"])) - .unwrap(); - assert_eq!(options.port, 3099); - assert_eq!(options.dsh_home.as_deref(), Some("/tmp/h")); - assert_eq!(options.dsh_version.as_deref(), Some("9.9.9")); - - let long = parse_args(args(&["--port", "3098", "--dshhome", "/tmp/g"])).unwrap(); - assert_eq!(long.port, 3098); - assert_eq!(long.dsh_home.as_deref(), Some("/tmp/g")); - } - - #[test] - fn no_command_is_start_and_every_command_parses() { - assert_eq!(parse_args(args(&[])).unwrap().command(), Command::Start); - assert_eq!(parse_args(args(&["start"])).unwrap().command(), Command::Start); - assert_eq!(parse_args(args(&["INSTALL"])).unwrap().command(), Command::Install); - assert_eq!(parse_args(args(&["uninstall"])).unwrap().command(), Command::Uninstall); - assert_eq!(parse_args(args(&["status"])).unwrap().command(), Command::Status); - assert_eq!(parse_args(args(&["key"])).unwrap().command(), Command::Key); - // A flag before the verb is ordinary, and the verb is found where it appears. - let options = parse_args(args(&["-DshHome", "/tmp/h", "install"])).unwrap(); - assert_eq!(options.command(), Command::Install); - assert_eq!(options.dsh_home.as_deref(), Some("/tmp/h")); - // Two verbs is one too many. - let error = parse_args(args(&["install", "status"])).unwrap_err(); - assert!(error.contains("only one command"), "{error}"); - let error = parse_args(args(&["sideways"])).unwrap_err(); - assert!(error.contains("unknown command 'sideways'"), "{error}"); - assert!(error.contains("start, install, uninstall, status or key"), "{error}"); - } - - #[test] - fn an_unknown_flag_is_refused_and_named() { - // The failure this prevents: a typo silently becoming a default, so the shell - // runs a different harness or a different port than the one asked for. - let error = parse_args(args(&["-Prot", "3099"])).unwrap_err(); - assert!(error.contains("-prot"), "{error}"); - assert!(error.contains("unknown flag"), "{error}"); - } - - #[test] - fn a_flag_that_needs_a_value_says_so() { - let error = parse_args(args(&["-DshHome"])).unwrap_err(); - assert!(error.contains("-DshHome needs a value"), "{error}"); - } - - #[test] - fn port_zero_is_refused_rather_than_meaning_a_random_port() { - assert!(parse_args(args(&["-Port", "0"])) - .unwrap_err() - .contains("above zero")); - assert!(parse_args(args(&["-Port", "seventy"])) - .unwrap_err() - .contains("port number")); - } - - #[test] - fn there_is_no_mode_flag_any_more_and_no_embedded_web_view() { - // The pane is gone. A `-Mode embed` that used to select it must FAIL, and the - // usage text must not advertise a surface this build does not have. - let error = parse_args(args(&["-Mode", "embed"])).unwrap_err(); - assert!(error.contains("unknown flag"), "{error}"); - for word in ["embed", "pane", "-Mode"] { - assert!(!USAGE.contains(word), "the usage text still mentions {word}"); - } - // ...and every verb and flag it DOES accept is named in it. - for word in ["install", "uninstall", "status", "key", "-Port", "-DshHome", "-Help"] { - assert!(USAGE.contains(word), "the usage text never mentions {word}"); - } - } - - #[test] - fn the_launchers_flags_are_not_silently_swallowed() { - // -NoPause/-NoTerminal/-NoBuild belong to the launcher scripts and are stripped - // there; reaching this parser means they were NOT stripped, and the shell must - // say so rather than run with a flag it ignored. - for flag in ["-NoPause", "-NoTerminal", "-NoBuild"] { - assert!(parse_args(args(&[flag])).is_err(), "{flag} was accepted"); - } - } - - #[test] - fn help_and_version_are_flags_not_verbs() { - assert!(parse_args(args(&["-Help"])).unwrap().help); - assert!(parse_args(args(&["--help"])).unwrap().help); - assert!(parse_args(args(&["-Version"])).unwrap().version); - assert!(parse_args(args(&["--version"])).unwrap().version); - // ...and asking for help is not asking for a verb. - assert_eq!(parse_args(args(&["-Help"])).unwrap().command(), Command::Start); - } -} diff --git a/app/crates/vn-shell-core/src/ports.rs b/app/crates/vn-shell-core/src/ports.rs deleted file mode 100644 index b4d20b4..0000000 --- a/app/crates/vn-shell-core/src/ports.rs +++ /dev/null @@ -1,118 +0,0 @@ -//! The port the harness is asked for, and the fact that a wrong guess here costs -//! the ORIGIN and nothing else. - -use std::net::TcpListener; - -use crate::options::Options; - -/// The port the harness listens on when it is given none - the same one a -/// `scripts\run-web.bat` tab opens on, and therefore the same ORIGIN. -/// -/// The app does **not** ask for it by default any more, and that is a measured -/// correction: it is the default every `dsh web` on the machine reaches for, so an app -/// instance that preferred it ended up sharing it with the harness the person was -/// already using - the tab the app opened was answered by the OTHER process, whose -/// launch token it did not have. `-Port 3080` is still one flag away for somebody who -/// wants the shared origin on purpose. -pub const DEFAULT_PORT: u16 = 3080; - -/// A free loopback port. -/// -/// Binding port 0 lets the operating system choose; the port is then released for -/// the harness to take. There is a hair of a race between the release and the -/// harness binding it, which is why `-Port` exists as the way out of it. -pub fn free_port() -> Option { - TcpListener::bind(("127.0.0.1", 0)) - .ok() - .and_then(|listener| listener.local_addr().ok()) - .map(|address| address.port()) -} - -/// Whether nothing holds this loopback port right now. -/// -/// The listener is closed again immediately, which leaves the same hair of a race -/// [`free_port`] has - and the same escape hatch. It is also the assertion Stop -/// makes after it kills the tree: docs/PLAN-egui-shell.md's M1 exit criterion is -/// that the port is free again, and this is how that is measured rather than -/// assumed. -pub fn port_is_free(port: u16) -> bool { - TcpListener::bind(("127.0.0.1", port)).is_ok() -} - -/// Whether nothing ANSWERS on this loopback port - asked by connecting, not by binding. -/// -/// The bind test above answers "may I have this port"; this one answers "is somebody -/// already there", and they are not the same question. Measured on the machine this was -/// written on: an app instance whose harness held `127.0.0.1:3080` while the browser the -/// user was chatting through held it too - one process had bound it, the other answered -/// on it, and the URL the app opened was answered by the WRONG harness, whose launch -/// token it did not have. A connect refuses to be fooled by that: if anything accepts -/// the connection, this port is not "free" whatever a bind says. -pub fn port_is_unanswered(port: u16) -> bool { - match std::net::TcpStream::connect_timeout( - &std::net::SocketAddr::from(([127, 0, 0, 1], port)), - std::time::Duration::from_millis(250), - ) { - // Something is listening: this port is somebody's. - Ok(stream) => { - drop(stream); - false - } - Err(_) => true, - } -} - -/// The port to ask the harness for: `-Port` when the person named one, else a free port -/// of its own - **never the shared default**. -/// -/// The app used to prefer `3080`, and that is how a tab ended up served by a different -/// harness than the one the app started (measured). A port of its own costs nothing -/// here, because the app opens the tab itself with the launch token in it: nobody has -/// to type an address, and nothing has to be remembered per origin. `-Port 3080` is -/// still the way to say "share the usual origin, I mean it". -pub fn choose_port(options: &Options) -> Option { - if options.port > 0 { - return Some(options.port); - } - free_port() -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn an_explicit_port_always_wins() { - // 3099 rather than the default, and no network is touched for it. - let options = Options { port: 3099, ..Options::default() }; - assert_eq!(choose_port(&options), Some(3099)); - } - - #[test] - fn a_port_something_answers_on_is_not_free_however_a_bind_answers() { - // The measured case: a harness holding 3080 while another process also answers - // on it. The connect probe refuses to call that free. - let listener = TcpListener::bind(("127.0.0.1", 0)).unwrap(); - let port = listener.local_addr().unwrap().port(); - assert!(!port_is_unanswered(port), "a listening port must read as somebody's"); - // ...and a port nothing listens on reads as nobody's. - drop(listener); - assert!(port_is_unanswered(port), "nothing is there once the listener is gone"); - } - - #[test] - fn with_no_flag_the_port_is_one_of_the_apps_own() { - // The shared default is never chosen on the app's own initiative, whether or not - // it happens to be free right now: that is the whole point of the change. - let options = Options::default(); - let chosen = choose_port(&options).expect("no port could be chosen at all"); - assert_ne!(chosen, DEFAULT_PORT, "the shared default was chosen without being asked for"); - assert!(port_is_free(chosen), "the port chosen is one something already holds"); - } - - #[test] - fn a_free_port_is_one_nothing_holds() { - let port = free_port().expect("the OS would not hand out a port"); - assert!(port_is_free(port), "the port just handed out reads as held"); - } -} diff --git a/app/crates/vn-shell-core/src/prefs.rs b/app/crates/vn-shell-core/src/prefs.rs deleted file mode 100644 index 7a77d3a..0000000 --- a/app/crates/vn-shell-core/src/prefs.rs +++ /dev/null @@ -1,197 +0,0 @@ -//! What the profile says about how it looks, read without a YAML dependency. -//! -//! The panel draws itself in the profile's own palette so the seam between the -//! native chrome and the rendered page is invisible rather than a dark frame -//! around a green page. The values it needs are in the profile's -//! `cordis.patch.yml`, which is a flat list of `- id: ` entries with a -//! `config:` block under each - so a scanner that tracks the CURRENT entry is -//! enough, and a YAML parser would be a dependency the shell does not otherwise -//! need. -//! -//! Reading is best-effort by design: a profile that has been edited by hand, or -//! one that does not exist yet, costs the shell its palette and nothing else. - -use std::collections::BTreeSet; -use std::path::{Path, PathBuf}; - -/// The subset of a profile's configuration the panel draws with. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -pub struct Preferences { - /// `ui-theme`'s `preference`: `light` or `dark`. - pub preference: Option, - /// `ui-state`'s `theme`: an extension palette's name (`hacker`, `nord`, …). - pub theme: Option, - /// `ui-state`'s `pageZoom`, in percent. The PAGE's zoom - the panel never - /// applies it to itself. - pub page_zoom: Option, -} - -impl Preferences { - /// The palette name the panel should wear. - /// - /// The extension theme wins over the base preference, because that is the - /// order the harness itself applies them in: a registered theme paints over - /// the base palette's `colorScheme`. - pub fn palette(&self) -> &str { - match self.theme.as_deref() { - Some(name) if !name.is_empty() => name, - _ => match self.preference.as_deref() { - Some("light") => "light", - _ => "dark", - }, - } - } -} - -/// Read the values out of a profile patch's TEXT. -pub fn parse(text: &str) -> Preferences { - let mut preferences = Preferences::default(); - let mut entry = String::new(); - for line in text.lines() { - let trimmed = line.trim(); - if let Some(rest) = trimmed.strip_prefix("- id:") { - entry = rest.trim().trim_matches('"').to_string(); - continue; - } - let Some((key, value)) = trimmed.split_once(':') else { - continue; - }; - let key = key.trim(); - let value = value.trim().trim_matches('"').trim_matches('\''); - if value.is_empty() { - continue; - } - match (entry.as_str(), key) { - ("ui-theme", "preference") => preferences.preference = Some(value.to_string()), - ("ui-state", "theme") => preferences.theme = Some(value.to_string()), - ("ui-state", "pageZoom") => preferences.page_zoom = value.parse::().ok(), - _ => {} - } - } - preferences -} - -/// Where a profile's patch layer lives. -pub fn patch_path(home: &Path, profile: &str) -> PathBuf { - home.join("profiles").join(profile).join("cordis.patch.yml") -} - -/// Read the profile's preferences, or the defaults if it cannot be read. -pub fn read(home: Option<&Path>, profile: &str) -> Preferences { - let Some(home) = home else { - return Preferences::default(); - }; - match std::fs::read_to_string(patch_path(home, profile)) { - Ok(text) => parse(&text), - Err(_) => Preferences::default(), - } -} - -/// The profiles this home has, sorted, so the panel can name them. -pub fn profile_names(home: Option<&Path>) -> Vec { - let Some(profiles) = home.map(|home| home.join("profiles")) else { - return Vec::new(); - }; - let Ok(entries) = std::fs::read_dir(profiles) else { - return Vec::new(); - }; - let mut names: BTreeSet = BTreeSet::new(); - for entry in entries.flatten() { - let name = entry.file_name().to_string_lossy().to_string(); - // `node_modules` is the installation fallback that lives beside the - // profiles, not a profile. - if name == "node_modules" || name.starts_with('.') { - continue; - } - if entry.path().is_dir() { - names.insert(name); - } - } - names.into_iter().collect() -} - -#[cfg(test)] -mod tests { - use super::*; - - /// The real shape: a top-level list of id-targeted entries, each with its own - /// `config:` block, and `ui-state`'s five fields beside the theme. - const PATCH: &str = "\ -# Your patch layer for this dsh profile -- id: ui-settings-general - name: \"@deepseek-ai/dsh-client-ui-settings-general\" - config: - welcomeNoticeVersion: 2026-09-28.1 -- id: ui-theme - name: \"@deepseek-ai/dsh-client-ui-theme\" - config: - preference: light -- id: agent-default-model - name: \"@deepseek-ai/dsh-agent-default-model\" - config: - provider: deepseek-official - model: deepseek-flash - reasoningEffort: high -- id: ui-state - name: \"dsh-ui-state\" - config: - pageZoom: 80 - dockHeight: 370 - sidebarWidth: 280 - rightbarWidth: 580 - theme: hacker -"; - - #[test] - fn the_real_patch_shape_is_read() { - let preferences = parse(PATCH); - assert_eq!(preferences.preference.as_deref(), Some("light")); - assert_eq!(preferences.theme.as_deref(), Some("hacker")); - assert_eq!(preferences.page_zoom, Some(80)); - // The extension theme is what the panel wears, and 80 is the PAGE's zoom. - assert_eq!(preferences.palette(), "hacker"); - } - - #[test] - fn a_key_in_another_entry_is_not_mistaken_for_this_one() { - // `theme:` under some other row must not become the panel's palette - - // this is the whole reason the scanner tracks the current entry. - let text = "- id: agent-default-model\n config:\n theme: deepseek-flash\n"; - assert_eq!(parse(text).theme, None); - // ...and `provider:`/`model:` never leak into the panel's fields either. - let text = "- id: agent-default-model\n config:\n pageZoom: 120\n"; - assert_eq!(parse(text).page_zoom, None); - } - - #[test] - fn a_missing_or_unreadable_patch_costs_the_palette_and_nothing_else() { - let preferences = read(None, "web"); - assert_eq!(preferences, Preferences::default()); - assert_eq!(preferences.palette(), "dark"); - - let text = "- id: ui-theme\n config:\n preference: light\n"; - assert_eq!(parse(text).palette(), "light"); - // An unparseable zoom is "no zoom recorded", never a panic and never 0. - let text = "- id: ui-state\n config:\n pageZoom: eighty\n"; - assert_eq!(parse(text).page_zoom, None); - } - - #[test] - fn the_patch_lives_under_the_profile_folder() { - let path = patch_path(Path::new("/home/u/.dsh"), "web"); - assert!(path.ends_with(Path::new("profiles").join("web").join("cordis.patch.yml"))); - } - - #[test] - fn profiles_are_listed_and_the_installation_fallback_is_not_one_of_them() { - let root = crate::scratch::dir("profiles"); - let profiles = root.join("profiles"); - std::fs::create_dir_all(profiles.join("web")).unwrap(); - std::fs::create_dir_all(profiles.join("desktop")).unwrap(); - std::fs::create_dir_all(profiles.join("node_modules")).unwrap(); - std::fs::write(profiles.join("not-a-profile.txt"), b"x").unwrap(); - assert_eq!(profile_names(Some(&root)), vec!["desktop", "web"]); - assert!(profile_names(None).is_empty()); - let _ = std::fs::remove_dir_all(&root); - } -} diff --git a/app/crates/vn-shell-core/src/profile.rs b/app/crates/vn-shell-core/src/profile.rs deleted file mode 100644 index 02fc131..0000000 --- a/app/crates/vn-shell-core/src/profile.rs +++ /dev/null @@ -1,79 +0,0 @@ -//! The web profile's manifest: one reader, so the panel and the runtime cannot -//! disagree about whether a home has this pack in it. -//! -//! The manifest is `/profiles//package.json` and the bundles live at -//! `dsh.profile.bundles`. Nothing here writes: this module only answers questions, and -//! everything it answers with comes from the file the HARNESS loads, not from a record -//! this app keeps. - -use std::path::Path; - -/// The bundle that marks this pack's presence in a profile. -/// -/// One of the first layers the installer adds, and the one the launcher has always asked -/// about: a profile that lists it is adorned (right bar, editor, themes), and a profile -/// that does not is the bare harness. -pub const PACK_MARKER: &str = "dsh-rightbar"; - -/// The bundles a profile lists, or `None` when there is no profile there at all. -pub fn bundles(home: &Path, profile: &str) -> Option> { - let manifest = home.join("profiles").join(profile).join("package.json"); - let text = std::fs::read_to_string(manifest).ok()?; - let json: serde_json::Value = serde_json::from_str(&text).ok()?; - let list = json.get("dsh")?.get("profile")?.get("bundles")?.as_array()?; - Some(list.iter().filter_map(|bundle| bundle.as_str().map(str::to_string)).collect()) -} - -/// Whether a profile lists this pack. -pub fn has_pack(bundles: &[String]) -> bool { - bundles.iter().any(|bundle| bundle == PACK_MARKER) -} - -/// The profile directory for a home, for a message that has to name it. -pub fn directory(home: &Path, profile: &str) -> std::path::PathBuf { - home.join("profiles").join(profile) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn scratch(name: &str) -> std::path::PathBuf { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => std::path::PathBuf::from(value), - _ => std::env::temp_dir(), - }; - let path = root.join(format!("vncode-profile-{}-{name}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - std::fs::create_dir_all(&path).unwrap(); - path - } - - #[test] - fn the_bundle_list_comes_from_the_file_the_harness_reads() { - let home = scratch("bundles"); - assert_eq!(bundles(&home, "web"), None, "no profile is not an empty profile"); - let directory = home.join("profiles").join("web"); - std::fs::create_dir_all(&directory).unwrap(); - std::fs::write( - directory.join("package.json"), - br#"{"dsh":{"profile":{"bundles":["@deepseek-ai/dsh-base","dsh-rightbar","dsh-editor"]}}}"#, - ) - .unwrap(); - let list = bundles(&home, "web").expect("the manifest is there"); - assert_eq!(list.len(), 3); - assert!(has_pack(&list)); - // A bare profile is a real answer, not a missing one. - std::fs::write( - directory.join("package.json"), - br#"{"dsh":{"profile":{"bundles":["@deepseek-ai/dsh-base"]}}}"#, - ) - .unwrap(); - let list = bundles(&home, "web").expect("the manifest is still there"); - assert!(!has_pack(&list), "a bare profile must not read as adorned"); - // ...and a file that is not JSON is missing rather than a guess. - std::fs::write(directory.join("package.json"), b"not json").unwrap(); - assert_eq!(bundles(&home, "web"), None); - let _ = std::fs::remove_dir_all(&home); - } -} diff --git a/app/crates/vn-shell-core/src/readyline.rs b/app/crates/vn-shell-core/src/readyline.rs deleted file mode 100644 index e85d9b6..0000000 --- a/app/crates/vn-shell-core/src/readyline.rs +++ /dev/null @@ -1,237 +0,0 @@ -//! The one line the harness prints, and the two rules that follow from it. -//! -//! Once its server is listening the harness writes a single line to stdout: -//! -//! ```text -//! dsh web: http://127.0.0.1:3080/?token= (LAN: http://:/?token=) -//! ``` -//! -//! That URL is the only way into the app, and its `token` is a LIVE CREDENTIAL -//! for the running process (it is what the server exchanges for the browser -//! session cookie). Two rules therefore hold here, exactly as they hold in the -//! Windows and POSIX halves of the browser launcher: -//! -//! 1. The token is read IN MEMORY. It is never written to a file, never echoed -//! (the line is printed [`redact`]ed) and never passed through a shell - the -//! URL reaches the webview as one value, never as a command string. -//! 2. A URL that does not name a loopback address is refused rather than opened -//! ([`is_loopback_host`]), because handing this credential to anything else -//! is the one mistake that cannot be walked back. -//! -//! Everything in this module is pure so it can be tested without a window, a -//! server or a network - `cargo test` is the check, and this is where the -//! launch-token rules are actually pinned. - -/// The mark the harness prefixes its ready line with. A line without it is -/// just output, however much it looks like a URL. -const READY_MARKER: &str = "dsh web:"; - -/// Strip ANSI escape sequences. -/// -/// The harness colourises its output, and a profile can colourise it further, -/// so the escape codes can sit INSIDE the URL (`.../?tok[0m[32men=`). -/// Both the ready-line parser and the console printer go through this, which is -/// why a coloured ready line is not a parsing failure. -pub fn strip_ansi(input: &str) -> String { - let mut out = String::with_capacity(input.len()); - let mut chars = input.chars().peekable(); - while let Some(ch) = chars.next() { - if ch != '\u{1b}' { - out.push(ch); - continue; - } - match chars.peek() { - // CSI: ESC [ ... , ended by any byte in the @-~ range. - Some('[') => { - chars.next(); - for candidate in chars.by_ref() { - if ('\u{40}'..='\u{7e}').contains(&candidate) { - break; - } - } - } - // OSC: ESC ] ... , ended by BEL or ST (ESC \). - Some(']') => { - chars.next(); - while let Some(candidate) = chars.next() { - if candidate == '\u{7}' { - break; - } - if candidate == '\u{1b}' && chars.peek() == Some(&'\\') { - chars.next(); - break; - } - } - } - // A bare escape, or an escape introducing a single-character - // sequence: drop the escape and let the next character stand. - _ => {} - } - } - out -} - -/// Pull the URL out of a ready line, or `None` when the line is not one. -/// -/// The FIRST URL on the line is the loopback one; the `(LAN: ...)` suffix that -/// may follow it is a second URL for another host and is deliberately not -/// returned. -pub fn extract_ready_url(line: &str) -> Option { - let clean = strip_ansi(line); - if !clean.contains(READY_MARKER) { - return None; - } - let start = clean.find("http://").or_else(|| clean.find("https://"))?; - let rest = &clean[start..]; - let end = rest - .find(|ch: char| ch.is_whitespace() || ch == '"' || ch == '\'') - .unwrap_or(rest.len()); - let url = rest[..end].trim_end_matches(['.', ',', ')', ']', '"', '\'']); - if url.len() <= "https://".len() { - return None; - } - Some(url.to_string()) -} - -/// Whether a host names this machine's own loopback interface. -/// -/// Both spellings of the IP addresses are accepted, with or without the -/// brackets a URL puts around an IPv6 literal, because the check is applied to -/// what the harness printed (a bare address) and to what the URL parser -/// produced (which may keep the brackets). -pub fn is_loopback_host(host: &str) -> bool { - let bare = host.trim().trim_start_matches('[').trim_end_matches(']'); - if bare.eq_ignore_ascii_case("localhost") { - return true; - } - bare.parse::() - .map(|address| address.is_loopback()) - .unwrap_or(false) -} - -/// Replace every `token=...` value with `REDACTED`, leaving the rest of the -/// line - including both URLs - intact. -/// -/// This is what makes it safe to print the harness's own output: the line stays -/// useful for diagnosing a failed start, and the credential in it does not -/// reach a console, a scrollback buffer or a screenshot of one. -pub fn redact(line: &str) -> String { - const NEEDLE: &str = "token="; - const MASK: &str = "token=REDACTED"; - if !line.contains(NEEDLE) { - return line.to_string(); - } - let mut out = String::with_capacity(line.len()); - let mut rest = line; - while let Some(at) = rest.find(NEEDLE) { - out.push_str(&rest[..at]); - out.push_str(MASK); - let after = &rest[at + NEEDLE.len()..]; - let end = after - .find(|ch: char| ch.is_whitespace() || ch == '&' || ch == ')' || ch == '"' || ch == '\'') - .unwrap_or(after.len()); - rest = &after[end..]; - } - out.push_str(rest); - out -} - -#[cfg(test)] -mod tests { - use super::*; - - /// The real shape of the line, as the harness prints it. - const READY: &str = "dsh web: http://127.0.0.1:3080/?token=s3cret-value (LAN: http://192.168.1.7:3080/?token=s3cret-value)"; - - #[test] - fn strip_ansi_removes_colour_codes() { - let coloured = "\u{1b}[32mdsh web:\u{1b}[0m \u{1b}[36mhttp://127.0.0.1:3080/\u{1b}[0m"; - assert_eq!(strip_ansi(coloured), "dsh web: http://127.0.0.1:3080/"); - } - - #[test] - fn strip_ansi_removes_an_osc_title() { - let titled = "\u{1b}]0;dsh\u{7}dsh web: http://127.0.0.1:3080/"; - assert_eq!(strip_ansi(titled), "dsh web: http://127.0.0.1:3080/"); - } - - #[test] - fn strip_ansi_leaves_plain_text_alone() { - assert_eq!(strip_ansi(READY), READY); - } - - #[test] - fn extract_ready_url_takes_the_loopback_url_not_the_lan_one() { - assert_eq!(extract_ready_url(READY).as_deref(), Some("http://127.0.0.1:3080/?token=s3cret-value")); - } - - #[test] - fn extract_ready_url_ignores_a_line_without_the_marker() { - assert_eq!(extract_ready_url("see http://127.0.0.1:3080/ for the app"), None); - } - - #[test] - fn extract_ready_url_ignores_a_marker_with_no_url() { - assert_eq!(extract_ready_url("dsh web: listening"), None); - } - - #[test] - fn extract_ready_url_works_through_colour_codes() { - let coloured = "\u{1b}[32mdsh web:\u{1b}[0m \u{1b}[36mhttp://127.0.0.1:41287/?token=abc\u{1b}[0m (LAN: http://10.0.0.4:41287/?token=abc)"; - assert_eq!(extract_ready_url(coloured).as_deref(), Some("http://127.0.0.1:41287/?token=abc")); - } - - #[test] - fn extract_ready_url_trims_a_trailing_paren() { - assert_eq!( - extract_ready_url("dsh web: http://127.0.0.1:3080/").as_deref(), - Some("http://127.0.0.1:3080/") - ); - assert_eq!( - extract_ready_url("dsh web: (http://127.0.0.1:3080/)").as_deref(), - Some("http://127.0.0.1:3080/") - ); - } - - #[test] - fn loopback_hosts_are_accepted() { - for host in ["127.0.0.1", "127.0.0.2", "127.1.2.3", "localhost", "LOCALHOST", "::1", "[::1]"] { - assert!(is_loopback_host(host), "{host} should be loopback"); - } - } - - #[test] - fn other_hosts_are_refused() { - for host in ["10.0.0.5", "192.168.1.7", "0.0.0.0", "example.com", "127.0.0.1.example.com", "", "tauri.localhost"] { - assert!(!is_loopback_host(host), "{host} should not be loopback"); - } - } - - #[test] - fn redact_hides_both_token_values() { - let redacted = redact(READY); - assert!(!redacted.contains("s3cret-value"), "the token survived redaction: {redacted}"); - assert_eq!(redacted.matches("token=REDACTED").count(), 2); - // The line stays diagnosable: the URLs are still there. - assert!(redacted.contains("http://127.0.0.1:3080/")); - assert!(redacted.contains("http://192.168.1.7:3080/")); - } - - #[test] - fn redact_stops_at_the_parameter_end() { - let line = "GET /?token=abc&x=1"; - assert_eq!(redact(line), "GET /?token=REDACTED&x=1"); - } - - #[test] - fn redact_leaves_a_line_without_a_token_alone() { - let line = "dsh web: starting"; - assert_eq!(redact(line), line); - } - - #[test] - fn redact_keeps_a_redacted_line_stable() { - let once = redact(READY); - assert_eq!(redact(&once), once); - } -} diff --git a/app/crates/vn-shell-core/src/scratch.rs b/app/crates/vn-shell-core/src/scratch.rs deleted file mode 100644 index 32353b5..0000000 --- a/app/crates/vn-shell-core/src/scratch.rs +++ /dev/null @@ -1,28 +0,0 @@ -//! Where a test writes when it needs a real file. -//! -//! `std::env::temp_dir()` is the default and the right answer on an ordinary -//! machine. It is not the right answer on a locked-down one: a sandbox that -//! denies `%TEMP%` (this repository's own checks are run inside one) turns every -//! test that touches a file into a failure about the HOST rather than about the -//! code, and a check that cannot run says nothing about the change under test. -//! -//! So the root is overridable: `VNCODE_TEST_DIR` is read first, and -//! `scripts/checks/check-shell.mjs` points it at a folder inside the checkout -//! before it runs `cargo test`. Nothing outside a test reads this. - -use std::path::PathBuf; - -/// The directory a test may create things in. -pub fn root() -> PathBuf { - match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - } -} - -/// A fresh, empty, per-process directory under [`root`]. -pub fn dir(name: &str) -> PathBuf { - let path = root().join(format!("vncode-{name}-{}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - path -} diff --git a/app/crates/vn-shell-core/src/userpath.rs b/app/crates/vn-shell-core/src/userpath.rs deleted file mode 100644 index 68486bf..0000000 --- a/app/crates/vn-shell-core/src/userpath.rs +++ /dev/null @@ -1,266 +0,0 @@ -//! What a person typed, turned into a path this app may actually use. -//! -//! `-DshHome`, `VNCODE_HOME` and a remembered home all arrive as TEXT, and a path -//! used without being cleaned is how an app writes somewhere it did not mean to - -//! or hands a child a path that means something different to the child than it did -//! to the parent. Four rules, applied in this order, and every one of them is a -//! `cargo test` case: -//! -//! 1. **A leading `~` is expanded against the user's home**, exactly as the harness -//! expands it in `resolveDshHome`. Measured cost of not doing it: `-DshHome ~/x` -//! became a directory literally named `~` in the current directory, which the app -//! then proved writable and reported as the home. -//! 2. **A relative path is resolved against the directory the app was started in**, -//! and the ABSOLUTE path is what gets exported, recorded and passed on - so the -//! harness and the installer cannot disagree about it because one of them changed -//! its working directory. -//! 3. **The path is normalised LEXICALLY**: `.` and `..` are folded without asking -//! the filesystem. Two spellings of one home must not look like two homes. -//! 4. **The Windows verbatim form is never produced or kept.** `fs::canonicalize` -//! answers `\\?\C:\…`, which breaks PowerShell, `cmd`, JSON consumers and some -//! Node APIs; [`canonical`] strips it back to `C:\…`. -//! -//! An empty path and a path containing a NUL are refused by name: neither can be -//! handed to a child, and a NUL in particular reaches `CreateProcess`/`execvp` as a -//! truncated string, which is the classic way a path check is bypassed. - -use std::path::{Component, Path, PathBuf}; - -/// Turn typed text into an absolute, lexically normalised path. -/// -/// `cwd` is where a relative path is resolved against - the app captures it once, so -/// the answer does not depend on when this is called. A `~` with no known user home -/// is an error rather than a guess. -pub fn resolve(typed: &str, cwd: Option<&Path>, user_home: Option<&Path>) -> Result { - let trimmed = typed.trim(); - if trimmed.is_empty() { - return Err("the path is empty".to_string()); - } - if trimmed.contains('\0') { - return Err("the path contains a NUL byte, which no process can be given".to_string()); - } - let expanded = expand_home(trimmed, user_home)?; - let absolute = if expanded.is_absolute() { - expanded - } else if expanded.has_root() { - // Rooted but without a prefix: on Windows `/tmp/x` and `\tmp\x` mean "on the - // current drive", so the drive comes from the directory the app started in - - // which is the only way this can be one absolute path rather than a path that - // means something different to each process that inherits it. - match cwd.and_then(|cwd| cwd.components().next()) { - Some(Component::Prefix(prefix)) => { - let mut joined = prefix.as_os_str().to_os_string(); - joined.push(expanded.as_os_str()); - PathBuf::from(joined) - } - // POSIX, or a working directory that is itself just a root: the path is - // already as absolute as this platform gets. - _ => expanded, - } - } else { - let cwd = cwd.ok_or_else(|| { - format!( - "'{trimmed}' is relative and this app could not read the directory it was started in" - ) - })?; - cwd.join(expanded) - }; - Ok(normalise(&absolute)) -} - -/// Expand a leading `~` (alone, or followed by a separator) against the user's home. -/// -/// The harness's own rule, so `-DshHome ~/harness` means the same thing to the app, -/// to the harness and to the installer. -pub fn expand_home(typed: &str, user_home: Option<&Path>) -> Result { - let rest = if typed == "~" { - Some("") - } else { - typed.strip_prefix("~/").or_else(|| typed.strip_prefix("~\\")) - }; - match rest { - Some("") => user_home - .map(Path::to_path_buf) - .ok_or_else(|| "the path is '~' and this app could not resolve the user's home".to_string()), - Some(rest) => { - let home = user_home.ok_or_else(|| { - "the path starts with '~' and this app could not resolve the user's home".to_string() - })?; - Ok(home.join(rest)) - } - None => Ok(PathBuf::from(typed)), - } -} - -/// Fold `.` and `..` without touching the filesystem. -/// -/// Lexical on purpose: resolving symlinks is [`canonical`]'s job, and a `..` that is -/// lexically foldable must not depend on whether the directory happens to exist yet. -pub fn normalise(path: &Path) -> PathBuf { - let path = strip_verbatim(path); - let mut out: Vec = Vec::new(); - for component in path.components() { - match component { - Component::CurDir => {} - Component::ParentDir => match out.last() { - // `a/b/..` is `a`. - Some(Component::Normal(_)) => { - out.pop(); - } - // `../a` keeps its `..`: there is nothing above it to fold. - Some(Component::ParentDir) | None => out.push(component), - // A `..` at a root is a no-op (`/..` is `/`). - _ => {} - }, - other => out.push(other), - } - } - let normalised: PathBuf = out.iter().collect(); - if normalised.as_os_str().is_empty() { - PathBuf::from(".") - } else { - normalised - } -} - -/// The real path, once it exists, with the Windows verbatim prefix removed. -/// -/// Falls back to the lexically normalised path when the filesystem cannot answer -/// (the directory does not exist yet, a permission the app does not have). The -/// fallback is not a failure: this app decides where to write by PROBING, and the -/// path it exports only has to be one the child can use. -pub fn canonical(path: &Path) -> PathBuf { - match std::fs::canonicalize(path) { - Ok(real) => strip_verbatim(&real), - Err(_) => normalise(path), - } -} - -/// Drop the Windows verbatim prefix: `\\?\C:\x` becomes `C:\x`, `\\?\UNC\s\v` -/// becomes `\\s\v`, and anything else is returned unchanged. -/// -/// Not cosmetic: the verbatim form is rejected by PowerShell in some positions, is -/// echoed into `cmd` as garbage, and is a different string to every consumer that -/// compares paths textually - including this pack's own checks. -pub fn strip_verbatim(path: &Path) -> PathBuf { - let text = path.to_string_lossy(); - if let Some(rest) = text.strip_prefix(r"\\?\UNC\") { - return PathBuf::from(format!(r"\\{rest}")); - } - if let Some(rest) = text.strip_prefix(r"\\?\") { - return PathBuf::from(rest); - } - path.to_path_buf() -} - -/// Whether a path is worth writing a probe into at all - the cheap refusals, before -/// the filesystem is asked anything. -pub fn is_plausible(path: &Path) -> bool { - !path.as_os_str().is_empty() && !path.to_string_lossy().contains('\0') -} - -#[cfg(test)] -mod tests { - use super::*; - - fn home() -> PathBuf { - if cfg!(windows) { - PathBuf::from(r"C:\Users\someone") - } else { - PathBuf::from("/home/someone") - } - } - - #[test] - fn a_tilde_is_expanded_exactly_where_the_harness_expands_it() { - let home = home(); - assert_eq!(resolve("~", None, Some(&home)).unwrap(), home); - assert_eq!(resolve("~/harness", None, Some(&home)).unwrap(), home.join("harness")); - // A `~` that is not the whole first component is an ordinary NAME, not an - // expansion: `~someone` is a directory somebody made, and it stays relative. - let cwd = home.join("work"); - let named = resolve("~someone/x", Some(&cwd), Some(&home)).unwrap(); - assert_eq!(named, cwd.join("~someone").join("x")); - // `~` with no resolvable home is refused rather than guessed. - assert!(resolve("~/x", None, None).is_err()); - assert!(resolve("~", None, None).is_err()); - } - - #[test] - fn a_rooted_path_without_a_drive_is_attached_to_the_current_drive() { - // Windows: `/tmp/x` is rooted on the CURRENT DRIVE, and it has to become one - // absolute path before it is exported - a child that inherits a bare - // `\tmp\x` resolves it against ITS own drive and working directory. - let cwd = if cfg!(windows) { PathBuf::from(r"C:\here") } else { PathBuf::from("/here") }; - let resolved = resolve("/tmp/x", Some(&cwd), None).unwrap(); - assert!(resolved.is_absolute(), "{}", resolved.display()); - let text = resolved.to_string_lossy().replace('\\', "/"); - assert!(text.ends_with("/tmp/x"), "{text}"); - if cfg!(windows) { - assert!(text.starts_with("C:/"), "the drive must come from the cwd: {text}"); - } - } - - #[test] - fn a_relative_path_is_resolved_against_the_directory_the_app_started_in() { - let cwd = if cfg!(windows) { PathBuf::from(r"C:\here") } else { PathBuf::from("/here") }; - let resolved = resolve("sub/home", Some(&cwd), None).unwrap(); - assert!(resolved.is_absolute(), "{}", resolved.display()); - assert_eq!(resolved, cwd.join("sub").join("home")); - // ...and with no cwd known, it is a refusal rather than a silent guess. - let error = resolve("sub/home", None, None).unwrap_err(); - assert!(error.contains("relative"), "{error}"); - } - - #[test] - fn dots_are_folded_without_touching_the_filesystem() { - let start = if cfg!(windows) { PathBuf::from(r"C:\a") } else { PathBuf::from("/a") }; - assert_eq!(normalise(&start.join("b").join("..")), start); - assert_eq!( - normalise(&start.join("b").join(".").join("c")), - start.join("b").join("c") - ); - // A `..` with nothing above it keeps its meaning. - let leading = normalise(Path::new("../a")); - assert!(leading.starts_with(".."), "{}", leading.display()); - // ...and an absolute `..` at the root is a no-op, not an escape. - let rooted = normalise(Path::new(if cfg!(windows) { r"C:\.." } else { "/.." })); - assert!(!rooted.to_string_lossy().contains(".."), "{}", rooted.display()); - } - - #[test] - fn the_windows_verbatim_form_is_stripped() { - // Whatever canonicalize answers on Windows must never reach a child: cmd, - // PowerShell, JSON consumers and this pack's own checks all disagree with it. - assert_eq!(strip_verbatim(Path::new(r"\\?\C:\x\y")), PathBuf::from(r"C:\x\y")); - assert_eq!(strip_verbatim(Path::new(r"\\?\UNC\server\share\x")), PathBuf::from(r"\\server\share\x")); - assert_eq!(strip_verbatim(Path::new("/plain/path")), PathBuf::from("/plain/path")); - // A real path that already exists canonicalizes to itself (never verbatim). - let here = std::env::current_dir().unwrap(); - let real = canonical(&here); - assert!(!real.to_string_lossy().starts_with(r"\\?\"), "{}", real.display()); - } - - #[test] - fn an_empty_path_and_a_nul_are_refused_by_name() { - let error = resolve(" ", None, None).unwrap_err(); - assert!(error.contains("empty"), "{error}"); - let error = resolve("a\0b", None, None).unwrap_err(); - assert!(error.contains("NUL"), "{error}"); - assert!(!is_plausible(Path::new(""))); - assert!(!is_plausible(Path::new("a\0b"))); - assert!(is_plausible(Path::new("/a"))); - } - - #[test] - fn canonical_of_something_that_does_not_exist_is_still_a_usable_path() { - let missing = if cfg!(windows) { - PathBuf::from(r"C:\definitely\not\here\at\all") - } else { - PathBuf::from("/definitely/not/here/at/all") - }; - let answer = canonical(&missing); - assert!(answer.is_absolute(), "{}", answer.display()); - assert!(!answer.to_string_lossy().contains("..")); - } -} diff --git a/app/crates/vn-shell-runtime/Cargo.toml b/app/crates/vn-shell-runtime/Cargo.toml deleted file mode 100644 index 3e07cee..0000000 --- a/app/crates/vn-shell-runtime/Cargo.toml +++ /dev/null @@ -1,12 +0,0 @@ -[package] -name = "vn-shell-runtime" -description = "The vncode shell's decided facts: the plan, the child environment and the runner behind the install and uninstall verbs." -version.workspace = true -edition.workspace = true -license.workspace = true -publish.workspace = true -rust-version.workspace = true - -[dependencies] -vn-shell-core.workspace = true -serde_json.workspace = true diff --git a/app/crates/vn-shell-runtime/src/console.rs b/app/crates/vn-shell-runtime/src/console.rs deleted file mode 100644 index aae989d..0000000 --- a/app/crates/vn-shell-runtime/src/console.rs +++ /dev/null @@ -1,99 +0,0 @@ -//! The one transcript. -//! -//! The supervisor writes the harness's output into it and the installer writes -//! its own output into it, so the panel has ONE log rather than two, and -//! redaction happens in exactly one place - on the way in, inside -//! `vn_shell_core::log::Log::push`. A second log would be a second chance to -//! forget that rule. - -use std::sync::Mutex; - -use vn_shell_core::log::Log; - -#[derive(Default)] -pub struct Console { - log: Mutex, -} - -impl Console { - pub fn new() -> Self { - Console::default() - } - - /// Store one line. The only way in, and it redacts. - pub fn push(&self, line: &str) { - match self.log.lock() { - Ok(mut log) => log.push(line), - Err(poisoned) => poisoned.into_inner().push(line), - } - } - - /// A cursor, for a reader that must not repeat or skip a line. - pub fn position(&self) -> u64 { - match self.log.lock() { - Ok(log) => log.position(), - Err(poisoned) => poisoned.into_inner().position(), - } - } - - pub fn since(&self, position: u64) -> Vec { - match self.log.lock() { - Ok(log) => log.since(position), - Err(poisoned) => poisoned.into_inner().since(position), - } - } - - pub fn tail(&self, count: usize) -> Vec { - match self.log.lock() { - Ok(log) => log.tail(count), - Err(poisoned) => poisoned.into_inner().tail(count), - } - } - - pub fn len(&self) -> usize { - match self.log.lock() { - Ok(log) => log.len(), - Err(poisoned) => poisoned.into_inner().len(), - } - } - - pub fn is_empty(&self) -> bool { - self.len() == 0 - } -} - -#[cfg(test)] -mod tests { - use super::*; - - fn token() -> String { - format!("{}{}", "feedface", "0011223344556677") - } - - #[test] - fn a_line_that_carried_the_token_is_stored_redacted() { - // The installer prints paths, and a path can carry a token only if - // something upstream did; this pins that the console is not the place it - // escapes from, whichever writer it came through. - let console = Console::new(); - console.push(&format!("dsh web: http://127.0.0.1:3080/?token={}", token())); - let stored = console.tail(10).join("\n"); - assert!(!stored.contains(&token()), "the token reached the console: {stored}"); - assert!(stored.contains("REDACTED"), "{stored}"); - } - - #[test] - fn two_writers_share_one_cursor() { - // The supervisor and the installer write here; a reader following the - // cursor sees each line once, in the order it was written. - let console = Console::new(); - let start = console.position(); - console.push("[vncode] from the supervisor"); - console.push("[vncode] from the installer"); - assert_eq!( - console.since(start), - vec!["[vncode] from the supervisor", "[vncode] from the installer"] - ); - assert!(console.since(console.position()).is_empty()); - } -} diff --git a/app/crates/vn-shell-runtime/src/env.rs b/app/crates/vn-shell-runtime/src/env.rs deleted file mode 100644 index d160974..0000000 --- a/app/crates/vn-shell-runtime/src/env.rs +++ /dev/null @@ -1,599 +0,0 @@ -//! The child's environment, composed rather than inherited. -//! -//! This is the rule that closes a whole family of bugs, and this codebase learned it -//! the hard way: the panel is started BY `scripts\run-desktop.bat`, so it inherits -//! that console layer's markers (`VNCODE_CONSOLE`, `VNCODE_ARGV`, …), and an entry -//! point that sees `VNCODE_CONSOLE` does not take its arguments from `%*` - measured, -//! because the first version of the Install button ran a full install while being -//! asked for help. Its first fix removed those variables from the installer's -//! environment only. M0 makes it ONE rule for every child this app starts: the -//! harness, the installer, and (for the browser) the OS itself. -//! -//! | variable | value | why | -//! |---|---|---| -//! | `DSH_HOME` | the chosen home, always | the child's home must be a fact, not an inference. The harness's own resolver is not consulted: it is TOLD | -//! | `npm_config_cache` | the cache chosen by write probe | an npm cache this account cannot write in fails the whole install with `EPERM`, and the advice that follows ("run as Administrator") is what created it | -//! | `PATH` | the vendored runtime's `node` directory first | anything the harness or a skill spawns resolves the same Node the harness runs on | -//! | `TMP`, `TEMP`, `TMPDIR` | `/tmp`, but **only** when the machine's own temp is not writable by a child | measured, from a real run's log: `dsh-spill-local: EPERM … mkdtemp 'C:\Users\…\AppData\Local\Temp\dsh-spill-XXXXXX'` - the child inherited a temp directory the confinement does not grant it, and the row that owned it did not activate. The machine's temp is left alone whenever it works, because it is the machine's | -//! | `VNCODE_HOME` | **removed** | the app's own word for its root. The harness knows `DSH_HOME` and nothing else; a second spelling would invite a plugin to depend on it - and an inherited one would leak this app's private layout into the child. A check reads this back out of the CHILD, which is how the leak was caught | -//! | `VNCODE_CONSOLE` and the six other console markers | removed | they belong to the launcher's console layer, not to a child of this app | -//! | `npm_config_cache` | removed when no cache was usable | "no writable cache was found" must mean npm uses its own default, not whatever the parent happened to export | -//! -//! What is NOT removed is everything the MACHINE owns: `PATH`, `HOME`, `TEMP`, -//! `SystemRoot`, the proxy variables. Clearing those and rebuilding them from scratch -//! is a much larger promise than composing the variables this app decides, and one -//! that breaks the harness in ways that are hard to diagnose. The rule this module -//! enforces is precise: **every variable this app owns is set or removed -//! deliberately, and the rest is the machine's** - plus one deliberate exception, the -//! `VNCODE_STUB_*` seam, which is read BY the child in a check, is never set by a -//! shipped launcher, and has `scripts/checks/check-shell.mjs` as its only author. -//! -//! The working directory is composed with them (`ChildEnv::apply` sets it): a child -//! that inherits whatever directory the app was launched from is a second, invisible -//! decision - and it is not academic, because `keystate` reads `.env` in the shell's -//! cwd BECAUSE the harness inherits it, so the value the panel reasons about and the -//! value the child is given have to be one value. - -use std::ffi::{OsStr, OsString}; -use std::path::{Path, PathBuf}; -use std::process::Command; - -use vn_shell_core::appdata::{self, CacheChoice}; -use vn_shell_core::launch::{self, Launch}; -use vn_shell_core::home; - -/// The variables the console layer uses to carry state between an entry point and -/// its relaunched self. None of them may reach a child of this app. -/// -/// Kept beside the composer rather than in the installer runner, because the harness -/// is started from the same shell that started the panel and inherits the same -/// markers. -pub const CONSOLE_VARIABLES: [&str; 7] = [ - "VNCODE_CONSOLE", - "VNCODE_ARGV", - "VNCODE_ARGS", - "VNCODE_PAUSE", - "VNCODE_NOPAUSE", - "VNCODE_QUIET", - "VNCODE_NO_WT", -]; - -/// What a child is given: the pairs set, the names removed, and where it runs. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -pub struct ChildEnv { - pairs: Vec<(OsString, OsString)>, - removed: Vec, - cwd: Option, -} - -impl ChildEnv { - pub fn pairs(&self) -> &[(OsString, OsString)] { - &self.pairs - } - - pub fn removed(&self) -> &[OsString] { - &self.removed - } - - pub fn cwd(&self) -> Option<&Path> { - self.cwd.as_deref() - } - - /// The value of a variable this composer set. - pub fn get(&self, name: &str) -> Option<&OsStr> { - self.pairs - .iter() - .find(|(key, _)| key.eq_ignore_ascii_case(name)) - .map(|(_, value)| value.as_os_str()) - } - - /// Put it on a command. - pub fn apply(&self, command: &mut Command) { - for (name, value) in &self.pairs { - command.env(name, value); - } - for name in &self.removed { - command.env_remove(name); - } - if let Some(cwd) = self.cwd.as_deref() { - command.current_dir(cwd); - } - } - - /// One line for the panel and the log - the composed facts, never a secret. - pub fn line(&self) -> String { - let mut parts: Vec = self - .pairs - .iter() - .map(|(name, value)| { - format!("{}={}", name.to_string_lossy(), value.to_string_lossy()) - }) - .collect(); - parts.push(format!("{} console markers removed", self.removed.len())); - if let Some(cwd) = self.cwd.as_deref() { - parts.push(format!("cwd={}", cwd.display())); - } - parts.join(" · ") - } - - /// The same composition, as a console SENTENCE rather than an inspector row. - /// - /// `PATH` is left out on purpose: the inherited path on an ordinary machine is a - /// thousand characters of somebody else's installers, and printing it on every run - /// buries the four variables this app actually decided. `status` prints the whole line - /// for anyone who wants it. - pub fn summary(&self) -> String { - let mut parts: Vec = self - .pairs - .iter() - .filter(|(name, _)| !name.eq_ignore_ascii_case("PATH")) - .map(|(name, value)| { - format!("{}={}", name.to_string_lossy(), value.to_string_lossy()) - }) - .collect(); - if self.pairs.iter().any(|(name, _)| name.eq_ignore_ascii_case("PATH")) { - parts.push("PATH=composed".to_string()); - } - parts.push(format!("{} console markers removed", self.removed.len())); - parts.join(" · ") - } -} - -/// Everything the composer needs, as plain values - so the composition is a `cargo -/// test` case and not a reading of the spawn site. -pub struct Facts<'a> { - pub launch: &'a Launch, - pub home: Option<&'a Path>, - pub cache: Option<&'a CacheChoice>, - /// A temp directory to hand the child INSTEAD of the machine's, when the - /// machine's is not writable by a child ([`choose_temp`]). - pub temp: Option<&'a Path>, - pub workspace: Option<&'a Path>, - /// The `PATH` this app inherited. Passed in rather than read here, so a test can - /// name one. - pub inherited_path: Option<&'a OsStr>, -} - -/// Compose a child's environment from the plan's facts. -pub fn compose(facts: &Facts<'_>) -> ChildEnv { - let mut pairs: Vec<(OsString, OsString)> = Vec::new(); - - // The home first, and always when there is one: the harness's own resolver must - // never be the thing that decides where this instance keeps its state. - if let Some(home) = facts.home { - pairs.push((OsString::from("DSH_HOME"), home.as_os_str().to_os_string())); - } - - // The vendored runtime's own Node goes in front of PATH, so a skill that runs - // `node` gets the one the harness is running on. - if let Launch::Vendored { node, .. } = facts.launch { - if let Some(directory) = node.parent() { - let mut value = OsString::from(directory.as_os_str()); - if let Some(inherited) = facts.inherited_path { - if !inherited.is_empty() { - value.push(if cfg!(windows) { ";" } else { ":" }); - value.push(inherited); - } - } - pairs.push((OsString::from("PATH"), value)); - } - } - - if let Some(cache) = facts.cache { - pairs.push((OsString::from("npm_config_cache"), cache.path.as_os_str().to_os_string())); - } - - // A temp directory the child can actually write in. All three spellings are set - // when one is given: the child is a Node program, and `os.tmpdir()` reads - // `TMPDIR`, then `TMP`, then `TEMP` - a child that found an unwritable one of - // those would fail exactly the way the spill store did. - if let Some(temp) = facts.temp { - for name in ["TMPDIR", "TMP", "TEMP"] { - pairs.push((OsString::from(name), temp.as_os_str().to_os_string())); - } - } - - // The app's own variables go, and so do the console layer's markers. `VNCODE_HOME` - // is the one that was measured leaking: setting `VNCODE_HOME` for the app left it - // in the child too, because an environment is inherited unless it is REMOVED - and - // a harness that can see this app's private layout is a harness one plugin away - // from depending on it. `check-shell.mjs` reads the child's own answer back. - let mut removed: Vec = vec![OsString::from("VNCODE_HOME")]; - removed.extend(CONSOLE_VARIABLES.iter().map(OsString::from)); - // No usable cache means npm's own default, not an inherited value pointing at the - // directory this app just refused. - if facts.cache.is_none() { - removed.push(OsString::from("npm_config_cache")); - } - - ChildEnv { pairs, removed, cwd: facts.workspace.map(Path::to_path_buf) } -} - -/// The cache this app will hand a child, chosen by writing where npm writes. -/// -/// `None` when no candidate was usable, which is reported rather than fatal: npm -/// then falls back to its own default, which may be the very directory this app -/// moved away from. -pub fn choose_cache( - app_root: Option<&Path>, - home: Option<&Path>, - repo_root: Option<&Path>, -) -> (Option, Option) { - let candidates = appdata::npm_cache_candidates(app_root, home, repo_root); - match appdata::choose_npm_cache(&candidates) { - Some(choice) => { - let warning = choice.warning.clone(); - (Some(choice), warning) - } - None => ( - None, - Some( - "no writable npm cache was found, so npm will use its own default - which may be the very directory this app moved away from".to_string(), - ), - ), - } -} - -/// The temp directory a child is given: the machine's when a child can write in it, -/// else `/tmp`, else nothing (with the reason). -/// -/// The probe is the operation itself, done in the directory the child would really -/// use. The machine's temp is preferred and left UNTOUCHED when it works - moving a -/// machine-wide directory on a hunch would put a build's scratch files somewhere -/// nobody expects. It is moved only for the measured case: a confinement that grants -/// this app its own root and denies `%TEMP%` to the process under it. -pub fn choose_temp( - app_root: Option<&Path>, - machine: Option, - probe: &mut impl FnMut(&Path) -> Result, -) -> (Option, Option) { - if let Some(machine) = machine.as_deref() { - if probe(machine).is_ok() { - return (None, None); - } - } - let Some(app_root) = app_root else { - return ( - None, - Some(format!( - "{} is not writable by this account and this app has no root of its own, so the child keeps a temp directory it may not be able to use", - machine - .as_deref() - .map(|path| path.display().to_string()) - .unwrap_or_else(|| "the machine's temp".to_string()) - )), - ); - }; - let owned = appdata::owned_temp(app_root); - match probe(&owned) { - Ok(_) => ( - Some(owned.clone()), - Some(format!( - "{} is not writable by a child of this app, so the child is given {} for temp instead (the harness's own scratch stores write there)", - machine - .as_deref() - .map(|path| path.display().to_string()) - .unwrap_or_else(|| "the machine's temp (unset)".to_string()), - owned.display() - )), - ), - Err(error) => ( - None, - Some(format!( - "neither the machine's temp nor {} can be written: {error}", - owned.display() - )), - ), - } -} - -/// The plan's own environment, for the harness. One place builds it, so a variable -/// cannot be set for the harness and forgotten for the installer. -pub fn for_plan(plan: &crate::Plan) -> ChildEnv { - compose(&Facts { - launch: &plan.launch, - home: plan.home.home_path(), - cache: plan.npm_cache.as_ref(), - temp: plan.temp.as_deref(), - workspace: plan.workspace.as_deref(), - inherited_path: std::env::var_os("PATH").as_deref(), - }) -} - -/// The home a child is told about, or the reason there is none. Kept here so the -/// harness and the installer cannot disagree. -pub fn home_or_problem(resolved: &home::Resolution) -> Result { - match resolved.home_path() { - Some(path) => Ok(path.to_path_buf()), - None => Err(resolved.problem().unwrap_or_else(|| { - "no harness home could be decided, so nothing can be started".to_string() - })), - } -} - -/// The `-DshHome ` pair an installer entry point accepts, both spellings being -/// the entry point's own. `None` when the home is the one this app chose for itself -/// only - which never happens: the father always names the home. -pub fn dsh_home_arguments(resolved: &home::Resolution) -> Vec { - match resolved.home_path() { - Some(path) => vec![OsString::from("-DshHome"), path.as_os_str().to_os_string()], - None => Vec::new(), - } -} - -/// The launch's own program directory, for the panel's environment row. -pub fn runtime_directory(launch: &Launch) -> Option { - match launch { - Launch::Vendored { node, .. } | Launch::Installed { node, .. } => { - node.parent().map(Path::to_path_buf) - } - Launch::Npx => None, - Launch::Stub { program, .. } => program.parent().map(Path::to_path_buf), - } -} - -/// The `npx` fallback's spec, so a caller can name it without re-deriving the pin. -pub fn npx_spec(version: &str) -> String { - format!("{}@{}", launch::PACKAGE, version) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn command_line(command: &Command) -> Vec<(String, Option)> { - command - .get_envs() - .map(|(name, value)| { - ( - name.to_string_lossy().to_string(), - value.map(|value| value.to_string_lossy().to_string()), - ) - }) - .collect() - } - - fn vendored() -> Launch { - Launch::Vendored { - node: PathBuf::from("/rt/win-x64/node/node.exe"), - bin: PathBuf::from("/rt/win-x64/harness/lib/bin.js"), - } - } - - #[test] - fn the_home_is_always_handed_over_and_the_apps_own_name_never_is() { - let launch = vendored(); - let cache = CacheChoice { path: PathBuf::from("/root/npm-cache"), warning: None }; - let composed = compose(&Facts { - launch: &launch, - home: Some(Path::new("/root/home")), - cache: Some(&cache), - temp: None, - workspace: Some(Path::new("/work")), - inherited_path: Some(OsStr::new("/usr/bin")), - }); - assert_eq!(composed.get("DSH_HOME"), Some(OsStr::new("/root/home"))); - assert_eq!(composed.get("npm_config_cache"), Some(OsStr::new("/root/npm-cache"))); - // The app's own word for its root is NOT exported: the harness knows - // DSH_HOME and nothing else. - assert_eq!(composed.get("VNCODE_HOME"), None); - assert_eq!(composed.cwd(), Some(Path::new("/work"))); - // ...and the vendored Node is in front of the inherited PATH. - let path = composed.get("PATH").expect("a vendored launch prepends its Node"); - assert!(path.to_string_lossy().starts_with("/rt/win-x64/node"), "{path:?}"); - assert!(path.to_string_lossy().contains("/usr/bin"), "{path:?}"); - } - - #[test] - fn the_console_markers_and_the_apps_own_variables_are_removed_for_every_child() { - let launch = Launch::Npx; - let composed = compose(&Facts { - launch: &launch, - home: Some(Path::new("/root/home")), - cache: None, - temp: None, - workspace: None, - inherited_path: None, - }); - let removed: Vec = - composed.removed().iter().map(|name| name.to_string_lossy().to_string()).collect(); - for name in CONSOLE_VARIABLES { - assert!(removed.iter().any(|removed| removed == name), "{name} was left in"); - } - // The app's own word for its root must not reach the child - measured: it did. - assert!(removed.iter().any(|name| name == "VNCODE_HOME"), "{removed:?}"); - // ...and with no usable cache, npm's own default is what is left rather than - // an inherited value pointing at the directory that was refused. - assert!(removed.iter().any(|name| name == "npm_config_cache"), "{removed:?}"); - - // The trap, on a real Command: the variables are REMOVED even though this - // process has them set. - let mut command = Command::new("node"); - composed.apply(&mut command); - let envs = command_line(&command); - for name in ["VNCODE_CONSOLE", "VNCODE_HOME", "npm_config_cache"] { - let entry = envs - .iter() - .find(|(key, _)| key.eq_ignore_ascii_case(name)) - .unwrap_or_else(|| panic!("{name} must be named, so it can be removed")); - assert!(entry.1.is_none(), "{name} would reach the child"); - } - assert_eq!( - envs.iter() - .find(|(name, _)| name == "DSH_HOME") - .and_then(|(_, value)| value.clone()) - .as_deref(), - Some("/root/home") - ); - } - - #[test] - fn a_non_vendored_launch_leaves_the_inherited_path_alone() { - let launch = Launch::Installed { - node: PathBuf::from("node.exe"), - bin: PathBuf::from("/cache/dsh/lib/bin.js"), - }; - let composed = compose(&Facts { - launch: &launch, - home: None, - cache: None, - temp: None, - workspace: None, - inherited_path: Some(OsStr::new("/usr/bin")), - }); - assert_eq!(composed.get("PATH"), None, "a PATH was composed from nothing"); - assert_eq!(composed.get("DSH_HOME"), None, "no home means no export"); - } - - #[test] - fn the_line_names_what_was_composed_and_never_a_secret() { - let launch = vendored(); - let composed = compose(&Facts { - launch: &launch, - home: Some(Path::new("/root/home")), - cache: None, - temp: None, - workspace: Some(Path::new("/work")), - inherited_path: None, - }); - let line = composed.line(); - assert!(line.contains("DSH_HOME=/root/home"), "{line}"); - assert!(line.contains("console markers removed"), "{line}"); - assert!(line.contains("cwd=/work"), "{line}"); - } - - #[test] - fn a_cache_is_chosen_by_writing_and_a_refusal_is_reported() { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - } - .join(format!("vncode-env-cache-{}", std::process::id())); - let _ = std::fs::remove_dir_all(&root); - // The app's own root, with a cache whose `_cacache` tree is a FILE: the root - // is writable and npm still cannot write, which is the measured failure this - // probe exists for. - let app_root = root.join("app-root"); - let broken = app_root.join("npm-cache"); - std::fs::create_dir_all(&broken).unwrap(); - std::fs::write(broken.join("_cacache"), b"a file, not a directory").unwrap(); - let home = root.join("home"); - std::fs::create_dir_all(&home).unwrap(); - let (cache, warning) = choose_cache(Some(&app_root), Some(&home), None); - let cache = cache.expect("the harness home is a usable cache"); - assert!(cache.path.starts_with(&home), "{}", cache.path.display()); - assert!(warning.is_some(), "the refused candidate must be reported"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_home_arguments_are_the_entry_points_own_spelling() { - let inputs = home::Inputs { - data_root: Some(Path::new("/data")), - ..home::Inputs::default() - }; - let resolved = home::resolve_with(&inputs, &mut |path| { - Ok(vn_shell_core::appdata::Probed { path: path.to_path_buf(), created: false }) - }); - let arguments = dsh_home_arguments(&resolved); - assert_eq!(arguments.len(), 2); - assert_eq!(arguments[0], OsString::from("-DshHome")); - // Built through the same join the ladder uses, so this reads the same on - // Windows as on POSIX. - let expected = vn_shell_core::appdata::owned_home(&vn_shell_core::appdata::root_in( - Path::new("/data"), - )); - assert_eq!(Path::new(&arguments[1]), expected); - assert_eq!(home_or_problem(&resolved).unwrap(), expected); - } - - #[test] - fn a_temp_directory_is_handed_over_only_when_one_was_chosen() { - let launch = vendored(); - // No temp chosen: the machine's is the child's, untouched. - let composed = compose(&Facts { - launch: &launch, - home: Some(Path::new("/root/home")), - cache: None, - temp: None, - workspace: None, - inherited_path: None, - }); - for name in ["TMPDIR", "TMP", "TEMP"] { - assert_eq!(composed.get(name), None, "{name} was set with nothing to set"); - } - // Chosen: all three spellings, because the child is a Node program and - // `os.tmpdir()` reads them in that order. - let composed = compose(&Facts { - launch: &launch, - home: Some(Path::new("/root/home")), - cache: None, - temp: Some(Path::new("/root/tmp")), - workspace: None, - inherited_path: None, - }); - for name in ["TMPDIR", "TMP", "TEMP"] { - assert_eq!(composed.get(name), Some(OsStr::new("/root/tmp")), "{name}"); - } - } - - #[test] - fn the_machines_temp_is_left_alone_when_a_child_can_write_in_it() { - let mut probe = |path: &Path| { - Ok(vn_shell_core::appdata::Probed { path: path.to_path_buf(), created: false }) - }; - let (temp, note) = choose_temp( - Some(Path::new("/root")), - Some(PathBuf::from("/machine/temp")), - &mut probe, - ); - assert_eq!(temp, None, "the machine's temp must not be moved on a hunch"); - assert_eq!(note, None); - } - - #[test] - fn a_temp_a_child_cannot_write_falls_to_the_apps_own_root_and_says_so() { - // The measured case: `%TEMP%` refuses the child while the app's own root is - // writable, and the harness's spill store dies on `mkdtemp` without this. - let mut probe = |path: &Path| { - if path == vn_shell_core::appdata::owned_temp(Path::new("/root")) { - Ok(vn_shell_core::appdata::Probed { - path: path.to_path_buf(), - created: true, - }) - } else { - Err("not writable: access is denied".to_string()) - } - }; - let (temp, note) = choose_temp( - Some(Path::new("/root")), - Some(PathBuf::from("/machine/temp")), - &mut probe, - ); - let owned = vn_shell_core::appdata::owned_temp(Path::new("/root")); - assert_eq!(temp.as_deref(), Some(owned.as_path())); - let note = note.expect("the move must be reported"); - assert!(note.contains("/machine/temp"), "{note}"); - // Built through the same join the app uses, so this reads the same on Windows. - assert!(note.contains(&owned.display().to_string()), "{note}"); - } - - #[test] - fn no_temp_anywhere_is_a_warning_rather_than_a_silent_inheritance() { - let mut probe = |_path: &Path| Err("not writable: access is denied".to_string()); - let (temp, note) = - choose_temp(Some(Path::new("/root")), Some(PathBuf::from("/machine/temp")), &mut probe); - assert_eq!(temp, None); - assert!(note.expect("a warning is due").contains("neither"), "the warning must say so"); - // ...and with no app root either, the warning still names what was tried. - let mut probe = |_path: &Path| Err("nope".to_string()); - let (temp, note) = choose_temp(None, Some(PathBuf::from("/machine/temp")), &mut probe); - assert_eq!(temp, None); - assert!(note.expect("a warning is due").contains("/machine/temp")); - } - - #[test] - fn the_npx_spec_carries_the_pin() { - assert_eq!(npx_spec("0.2.0-rc.2"), "@deepseek-ai/dsh@0.2.0-rc.2"); - } -} diff --git a/app/crates/vn-shell-runtime/src/lib.rs b/app/crates/vn-shell-runtime/src/lib.rs deleted file mode 100644 index 667a00a..0000000 --- a/app/crates/vn-shell-runtime/src/lib.rs +++ /dev/null @@ -1,325 +0,0 @@ -//! Everything that decides WHICH harness this app runs against, and nothing that owns a -//! process. -//! -//! The app is a front door, not a supervisor: it resolves the root, the home, the pin and -//! the child's environment, and then it runs `scripts/run-web.*` - the same file a person -//! double-clicks - in the foreground. So there is no worker thread, no status record and no -//! tree-killer here any more: Ctrl+C reaches the launcher because it is the process the -//! console already has, and the launcher owns the node child exactly as it does when it is -//! started by hand. -//! -//! What is left is the half a person cannot see and a check can: [`plan`], which answers -//! "which home, which pin, which cache, which temp" before anything is spawned. - -use std::path::{Path, PathBuf}; - -use vn_shell_core::{home, launch, options::Options, ports}; - -pub mod console; -pub mod env; -pub mod setup; - -pub use console::Console; -pub use env::ChildEnv; -pub use setup::{EntryPoints, Setup, SetupKind, SetupStatus}; - -// --------------------------------------------------------------------------- -// The plan: what a start will act on, decided before anything is spawned -// --------------------------------------------------------------------------- -/// Everything the app decided before it runs a script, and every fact it prints. -#[derive(Clone, Debug)] -pub struct Plan { - pub version: String, - pub launch: launch::Launch, - /// Where the app's root and the harness home are, and what had to be refused. - /// A ladder's answer rather than an inherited path. - pub home: home::Resolution, - /// The npm cache a child is given, chosen by writing where npm really writes. - pub npm_cache: Option, - /// A temp directory to hand the child instead of the machine's - set only when a - /// child cannot write in the machine's (`env::choose_temp`), which the harness's - /// own spill store proved it sometimes cannot. - pub temp: Option, - /// The directory the harness will run in, captured once. It is composed into - /// the child, because `keystate` reads `.env` in the shell's cwd BECAUSE the - /// harness inherits it - so one value has to serve both. - pub workspace: Option, - /// The checkout or distribution root, when one was found. Carried here so the - /// launch decision and the npm-cache choice see the same facts. - pub root: Option, - /// What [`ports::choose_port`] answers right now. A HINT: the harness really does - /// choose again, because a port that was free when this app looked may be held by - /// the time the launcher starts. - pub port_hint: Option, - /// Lines worth printing: a refused home, a missing pack, a cache that had to move. - pub notes: Vec, -} - -impl Plan { - /// The harness home, when the ladder decided one. - pub fn home_path(&self) -> Option<&Path> { - self.home.home_path() - } - - /// The app's own root. - pub fn app_root(&self) -> Option<&Path> { - self.home.app_root_path() - } - - /// The composed environment, as one line - the whole thing, `PATH` included. - pub fn env_line(&self) -> String { - env::for_plan(self).line() - } - - /// The same composition as a console sentence: the four variables this app decided, - /// and a marker count instead of the machine's thousand-character `PATH`. - pub fn env_summary(&self) -> String { - env::for_plan(self).summary() - } - - /// The app root's own words. - pub fn app_root_origin_label(&self) -> &'static str { - self.home.app_root_origin_label() - } - - /// One line naming what the launcher will actually run - never what was hoped for. - pub fn runtime_line(&self) -> String { - match &self.launch { - launch::Launch::Vendored { node, .. } => { - format!("vendored runtime ({})", node.display()) - } - launch::Launch::Installed { bin, .. } => { - format!("already installed here, no npm ({})", bin.display()) - } - launch::Launch::Npx => format!("npx --yes @deepseek-ai/dsh@{}", self.version), - launch::Launch::Stub { program, .. } => { - format!("TEST SEAM ({})", program.display()) - } - } - } -} - -/// Decide everything a start needs, without spawning anything. -/// -/// The ladders are resolved HERE, by writing where the harness will write, so the app can -/// say "this home was refused, this one is in use" the moment it opens rather than after a -/// three-minute wait for a ready line that cannot arrive. -/// -/// `remembered` is a home chosen by an earlier build of this app: it sits above the -/// inherited `DSH_HOME` and below `-DshHome`. -pub fn plan(options: &Options, remembered: Option<&Path>) -> Result { - let root = launch::repo_root(); - let version = launch::resolve_version(options)?; - // NOTHING OUTSIDE THIS APP'S OWN ROOT IS EVER THE HOME. A folder that carries - // everything it needs must not reach into a person's profile to start, and the two - // things a home outside it answered - a home with no pack, and a home with no key - - // are answered by this command (which installs the pack into the home in use) and by - // the key prompt. - let resolved = home::from_env(options.dsh_home.as_deref(), remembered); - let chosen = launch::choose_launch( - root.as_deref(), - resolved.app_root_path(), - resolved.home_path(), - &version, - ); - let mut notes = resolved.notes(); - // The preflight, as a NOTE here rather than a refusal: only an explicit `-DshHome` - // actually stops a run (see `home::Resolution::problem`). - if let Some(problem) = resolved.problem() { - notes.push(problem); - } - if let Some(note) = missing_pack_note(resolved.home_path(), launch::PROFILE) { - notes.push(note); - } - if root.is_none() && matches!(chosen, launch::Launch::Npx) { - notes.push( - "no .dsh-version.json was found above this binary, so the pin came from -DshVersion" - .to_string(), - ); - } - let (npm_cache, cache_note) = env::choose_cache( - resolved.app_root_path(), - resolved.home_path(), - root.as_deref(), - ); - if let Some(note) = cache_note { - notes.push(note); - } - let (temp, temp_note) = env::choose_temp( - resolved.app_root_path(), - vn_shell_core::appdata::machine_temp(), - &mut vn_shell_core::appdata::probe, - ); - if let Some(note) = temp_note { - notes.push(note); - } - Ok(Plan { - version, - launch: chosen, - home: resolved, - npm_cache, - temp, - workspace: std::env::current_dir().ok(), - root, - port_hint: ports::choose_port(options), - notes, - }) -} - -/// A friendly nudge, never a refusal - the harness runs fine without the pack, so a -/// profile that never had it installed still starts, just unadorned. This is the same -/// warning `run-web.ps1` prints, from the same source of truth: the web profile's own -/// bundle list. -/// -/// The words name a command the reader can actually run. They used to name a button on a -/// window this app no longer opens, which is the same mistake in a different costume. -pub fn missing_pack_note(home: Option<&Path>, profile: &str) -> Option { - let home = home?; - let profile_dir = home.join("profiles").join(profile); - let manifest = profile_dir.join("package.json"); - if !manifest.is_file() { - return Some(format!( - "there is no {profile} profile at {} yet, so the harness will come up unadorned. \ - `vncode install` puts this pack into THIS home first, and so does a plain \ - `vncode start`", - profile_dir.display() - )); - } - let installed = std::fs::read_to_string(&manifest) - .ok() - .and_then(|text| serde_json::from_str::(&text).ok()) - .and_then(|json| { - json.get("dsh")? - .get("profile")? - .get("bundles")? - .as_array() - .map(|bundles| bundles.iter().any(|bundle| bundle.as_str() == Some("dsh-rightbar"))) - }) - .unwrap_or(false); - if installed { - None - } else { - Some(format!( - "the {profile} profile at {} does not list this pack's bundles, so the harness \ - comes up unadorned (no right bar, no editor, no themes). `vncode install` adds \ - them to THIS home, and so does a plain `vncode start`", - profile_dir.display() - )) - } -} - -#[cfg(test)] -mod tests { - use super::*; - - /// A scratch directory for THIS crate's tests: `vn-shell-core`'s helper is - /// test-only and private to it, and a check may point both at one root. - fn scratch_dir(name: &str) -> PathBuf { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - }; - let path = root.join(format!("vncode-runtime-{}-{name}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - path - } - - #[test] - fn the_plan_names_what_will_run_rather_than_what_was_hoped_for() { - // -DshVersion makes the plan resolvable with no checkout at a known path, - // which is what lets this test run from anywhere. - let options = Options { dsh_version: Some("9.9.9".into()), ..Options::default() }; - let plan = plan(&options, None).expect("the plan must resolve with an explicit pin"); - assert_eq!(plan.version, "9.9.9"); - let line = plan.runtime_line(); - assert!( - line.contains("vendored") || line.contains("npx") || line.contains("TEST SEAM"), - "{line}" - ); - } - - #[test] - fn the_plan_always_names_a_home_and_an_app_root() { - // The ordinary case: a home this app can write is always found, so "the plan - // exists" and "there is a harness home" are the same statement. - let options = Options { dsh_version: Some("9.9.9".into()), ..Options::default() }; - let plan = plan(&options, None).expect("the plan must resolve with an explicit pin"); - let home = plan.home_path().expect("a home is always decided"); - let root = plan.app_root().expect("a root is always decided"); - // The home is EITHER an inherited `DSH_HOME` that was writable (the app joins the - // session that started it) OR the default inside the app's own root. Both are - // correct; what must never happen is a home that is neither. - let origin = plan.home.home.as_ref().unwrap().origin; - match origin { - vn_shell_core::home::Origin::Inherited | vn_shell_core::home::Origin::Flag => {} - _ => assert_eq!(home.parent(), Some(root), "the default home must sit in the root"), - } - // The composed environment names the home, and never the app's own word for - // its root - the harness knows `DSH_HOME` and nothing else. - let line = plan.env_line(); - assert!(line.contains("DSH_HOME="), "{line}"); - assert!(line.contains(&home.display().to_string()), "{line}"); - assert!(!line.contains("VNCODE_HOME="), "{line}"); - } - - #[test] - fn an_explicit_dshhome_that_cannot_be_written_is_a_problem_that_names_the_flag() { - // The failure this pins, measured on a machine whose app was started from inside a - // program that confines its children: the harness died on `EPERM ... cordis.yml` - // three minutes after Start, and the app could have known instantly. An inherited - // or default home falls through to one this app creates; only a `-DshHome` the - // person typed is a refusal, and the refusal names the flag. - let root = scratch_dir("home-problem"); - std::fs::create_dir_all(&root).unwrap(); - let blocker = root.join("blocker"); - std::fs::write(&blocker, b"a file, not a directory").unwrap(); - let impossible = blocker.join(".dsh"); - - let options = Options { - dsh_home: Some(impossible.display().to_string()), - dsh_version: Some("9.9.9".into()), - ..Options::default() - }; - let plan = plan(&options, None).expect("the plan itself still resolves"); - let problem = plan.home.problem().expect("an impossible -DshHome is a problem"); - assert!(problem.contains("-DshHome"), "{problem}"); - assert!(problem.contains("blocker"), "{problem}"); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn a_missing_profile_is_a_note_and_never_a_refusal() { - let root = scratch_dir("missing-pack"); - std::fs::create_dir_all(root.join("profiles").join("web")).unwrap(); - let note = missing_pack_note(Some(&root), "web").expect("a note is due"); - assert!(note.contains("no web profile"), "{note}"); - // The words point at a command the reader can run, and never at a button on a - // window this build no longer opens. - assert!(note.contains("vncode install"), "{note}"); - assert!(!note.contains("press"), "{note}"); - // A profile with the manifest but without the pack gets the other note. - std::fs::write( - root.join("profiles").join("web").join("package.json"), - br#"{"dsh":{"profile":{"bundles":["@deepseek-ai/dsh-base"]}}}"#, - ) - .unwrap(); - let note = missing_pack_note(Some(&root), "web").expect("a note is due"); - assert!(note.contains("does not list this pack's bundles"), "{note}"); - assert!(note.contains("unadorned"), "{note}"); - // A note is a console line: no markup is rendered here, so no markup is written. - for note in [ - missing_pack_note(Some(&root), "web").unwrap(), - missing_pack_note(Some(&root.join("nothing")), "web").unwrap(), - ] { - assert!(!note.contains("**"), "a note carries markdown emphasis: {note}"); - } - // ...and one that lists the pack gets nothing at all. - std::fs::write( - root.join("profiles").join("web").join("package.json"), - br#"{"dsh":{"profile":{"bundles":["dsh-rightbar"]}}}"#, - ) - .unwrap(); - assert_eq!(missing_pack_note(Some(&root), "web"), None); - let _ = std::fs::remove_dir_all(&root); - } -} diff --git a/app/crates/vn-shell-runtime/src/setup.rs b/app/crates/vn-shell-runtime/src/setup.rs deleted file mode 100644 index c530d75..0000000 --- a/app/crates/vn-shell-runtime/src/setup.rs +++ /dev/null @@ -1,647 +0,0 @@ -//! Running the pack's own installer from the panel. -//! -//! The panel's Install and Uninstall buttons do not reimplement installing. They -//! run the SAME entry points a person would click - `scripts/setup/install.bat` -//! on Windows, `scripts/setup/install.sh` elsewhere - through the same console -//! layer, with the same flags, and stream what they print into the panel's log. -//! One installer, two ways to reach it. -//! -//! ## The inherited-marker trap, which is why this file is not three lines -//! -//! `scripts/console/adapt.cmd` decides the console a run gets, and it marks the -//! run it has set up with `VNCODE_CONSOLE=1`. An entry point that sees that marker -//! does not set `VNCODE_ARGV` from `%*` (the child of a Windows Terminal relaunch -//! already has the arguments) and `adapt.cmd` returns immediately - so ANY -//! arguments a caller passed are dropped on the floor. -//! -//! That is fine for the paths it was designed for, and it is a trap for this one: -//! the panel is a process that `scripts/run-desktop.bat` started, so it INHERITS -//! the marker, and an Install button that did not clear it would run the installer -//! with no flags at all - measured on this machine, not imagined: the first -//! version of this button ran `install.bat -NoTerminal -NoPause -Help` and watched -//! it start a full install. Every console variable is therefore removed from the -//! child's environment, which puts the entry point back on its first-entry path -//! where `%*` is the truth. -//! -//! ## Why the entry point and not the worker -//! -//! `install.bat` is the file a person double-clicks, and it is the file that -//! knows how to pick a PowerShell (7 first, 5.1 second), how to translate the -//! help spellings PowerShell cannot bind, and how to add the implied `-Force`. The -//! panel calls that, not `install-all.ps1`, so there is one place where "how this -//! pack is installed" is decided. - -use std::path::{Path, PathBuf}; -use std::process::{Command, Stdio}; -use std::sync::atomic::{AtomicBool, Ordering}; -use std::sync::{Arc, Mutex}; -use std::thread; - -use crate::console::Console; -use crate::env::ChildEnv; - -/// Which way the pack is being moved. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum SetupKind { - Install, - Uninstall, -} - -impl SetupKind { - pub fn label(self) -> &'static str { - match self { - SetupKind::Install => "install", - SetupKind::Uninstall => "uninstall", - } - } -} - -/// Where the entry points are. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct EntryPoints { - pub install: PathBuf, - pub uninstall: PathBuf, -} - -impl EntryPoints { - pub fn for_kind(&self, kind: SetupKind) -> &Path { - match kind { - SetupKind::Install => &self.install, - SetupKind::Uninstall => &self.uninstall, - } - } -} - -/// The entry points under a checkout or distribution root, if they are there. -/// -/// A `None` is a fact the panel shows ("no installer beside this app") rather than -/// an error: the shell works in a folder that carries only `app/`, and someone who -/// moved the binary away from its tree has not broken anything by doing so. -pub fn locate(root: &Path) -> Option { - let directory = root.join("scripts").join("setup"); - let (install, uninstall) = if cfg!(windows) { - (directory.join("install.bat"), directory.join("uninstall.bat")) - } else { - (directory.join("install.sh"), directory.join("uninstall.sh")) - }; - if install.is_file() && uninstall.is_file() { - Some(EntryPoints { install, uninstall }) - } else { - None - } -} - -/// The variables the console layer uses to carry state between an entry point and -/// its relaunched self. Re-exported from `env`, where the one composer that removes -/// them now lives - the harness inherits the same markers, so the rule cannot belong -/// to this runner alone. -pub use crate::env::CONSOLE_VARIABLES; - -/// The command that runs an entry point the way the panel needs it. -/// -/// `-NoTerminal` keeps `adapt.cmd` from relaunching into a Windows Terminal window -/// nobody would see, and `-NoPause` keeps it from holding a window open that does -/// not exist. Both are the launcher's own flags, stripped by the entry point -/// before the worker is called. -/// -/// `env` is the SAME composed environment the harness is given (`crate::env`), and -/// `home_arguments` is `-DshHome `: the installer must target the -/// home this app decided on, not whatever the harness would default to. Both entry -/// points accept that spelling, and both fall back to `DSH_HOME` - which the -/// composer also sets - so an installer run by hand and a run from this panel -/// cannot end up in two different homes. -pub fn command_for( - entry: &Path, - extra: &[String], - env: &ChildEnv, - home_arguments: &[std::ffi::OsString], -) -> Command { - let mut command = if cfg!(windows) { - let mut command = Command::new("cmd"); - command.arg("/c").arg(entry); - command - } else { - let mut command = Command::new("sh"); - command.arg(entry); - command - }; - if cfg!(windows) { - command.arg("-NoTerminal"); - } - command.arg("-NoPause"); - command.args(home_arguments); - command.args(extra); - env.apply(&mut command); - command.stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::piped()); - command -} - -/// What a setup run is doing. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -pub struct SetupStatus { - pub kind: Option, - pub running: bool, - /// The exit code of the last run that finished. - pub exit: Option, - /// The last thing worth saying, in words that are safe to draw. - pub detail: Option, - /// **The last line the installer printed that is worth drawing**, while it runs. - /// - /// The panel's `pack` row shows this, and it is the answer to a real report: an - /// install that re-resolves the harness's dependency graph prints nothing for - /// minutes, so a row saying "installing…" and nothing else read as an app that had - /// stopped. The line is the installer's own - `- adding dsh-editor 0.1.0-alpha.13 - /// (first install)` - trimmed and bounded, never composed here. - pub last: Option, -} - -impl SetupStatus { - /// One line for the panel's row and for the log. - pub fn line(&self) -> String { - match (self.kind, self.running, self.exit) { - (Some(kind), true, _) => format!("[vncode] {}ing the pack...", kind.label()), - (Some(kind), false, Some(0)) => { - format!("[vncode] {} finished successfully", kind.label()) - } - (Some(kind), false, Some(code)) => { - format!("[vncode] {} FAILED (exit code {code})", kind.label()) - } - (Some(kind), false, None) => format!("[vncode] {} did not finish", kind.label()), - (None, _, _) => "[vncode] the pack has not been installed or removed from here".to_string(), - } - } - - pub fn succeeded(&self) -> bool { - !self.running && self.exit == Some(0) - } -} - -/// The runner: one run at a time, and one writer of the status. -pub struct Setup { - console: Arc, - status: Mutex, - worker: Mutex>>, - running: AtomicBool, -} - -impl Setup { - pub fn new(console: Arc) -> Self { - Setup { - console, - status: Mutex::new(SetupStatus::default()), - worker: Mutex::new(None), - running: AtomicBool::new(false), - } - } - - pub fn status(&self) -> SetupStatus { - match self.status.lock() { - Ok(status) => status.clone(), - Err(poisoned) => poisoned.into_inner().clone(), - } - } - - pub fn is_running(&self) -> bool { - self.running.load(Ordering::SeqCst) - } - - /// Start an install or an uninstall. - /// - /// Returns as soon as the worker is running, like `Supervisor::start`: the - /// panel follows the status, and the log carries the installer's own words. - /// `extra` is passed straight through to the entry point - the panel passes - /// nothing, and `check-shell.mjs` passes `-Help`, which installs nothing and - /// proves the whole path. `env` and `home_arguments` come from the plan, so the - /// installer targets the same home the harness will run against. - pub fn start( - self: &Arc, - kind: SetupKind, - entry: &Path, - extra: &[String], - env: &ChildEnv, - home_arguments: &[std::ffi::OsString], - ) -> Result<(), String> { - if self.is_running() { - return Err("a setup run is already in flight".to_string()); - } - if !entry.is_file() { - return Err(format!("{} is not there any more", entry.display())); - } - { - let mut status = self.status.lock().unwrap_or_else(|error| error.into_inner()); - *status = SetupStatus { - kind: Some(kind), - running: true, - exit: None, - detail: None, - last: None, - }; - } - self.running.store(true, Ordering::SeqCst); - let shell = Arc::clone(self); - let entry = entry.to_path_buf(); - let extra = extra.to_vec(); - let env = env.clone(); - let home_arguments = home_arguments.to_vec(); - let handle = - thread::spawn(move || run(shell, kind, &entry, &extra, &env, &home_arguments)); - let mut slot = self.worker.lock().unwrap_or_else(|error| error.into_inner()); - *slot = Some(handle); - Ok(()) - } - - /// Wait for a run in flight to finish. The panel never calls this (it would - /// freeze the window); the check does. - pub fn join(&self) { - let handle = self.worker.lock().unwrap_or_else(|error| error.into_inner()).take(); - if let Some(handle) = handle { - let _ = handle.join(); - } - } - - fn finish(&self, kind: SetupKind, exit: Option) { - { - let mut status = self.status.lock().unwrap_or_else(|error| error.into_inner()); - status.running = false; - status.exit = exit; - status.detail = Some(kind.label().to_string()); - } - self.running.store(false, Ordering::SeqCst); - } - - /// Remember the last line worth drawing while a run is in flight. - fn note(&self, line: String) { - let mut status = self.status.lock().unwrap_or_else(|error| error.into_inner()); - status.last = Some(line); - } -} - -/// How much of the installer's own line the panel's `pack` row keeps. -/// -/// One row, one line, no wrapping into a paragraph: a progress line that pushes the rest -/// of the row off the window is worse than a shortened one. -const PROGRESS_CHARS: usize = 72; - -/// **The one line out of an installer's output that says how far along it is**, if the -/// line is one - the installer's own progress wording, or pnpm's, and nothing else. -/// -/// Measured need: an install prints nothing for minutes while npm resolves the -/// harness's dependency graph, so "installing…" alone was indistinguishable from an app -/// that had stopped. A pure function, so what counts as progress is a `cargo test` case -/// rather than a guess made inside a reader thread. -fn progress_line(line: &str) -> Option { - let text = line.trim(); - if text.is_empty() { - return None; - } - let interesting = [ - "- adding", - "- added", - "- removing", - "- removed", - "- skills:", - "Progress:", - "Packages:", - ] - .iter() - .any(|prefix| text.starts_with(prefix)); - if !interesting { - return None; - } - Some(text.chars().take(PROGRESS_CHARS).collect()) -} - -/// The worker: spawn the entry point, stream both of its streams, record the exit. -fn run( - shell: Arc, - kind: SetupKind, - entry: &Path, - extra: &[String], - env: &ChildEnv, - home_arguments: &[std::ffi::OsString], -) { - let mut command = command_for(entry, extra, env, home_arguments); - let shown = format!( - "{} {} {}", - entry.display(), - if cfg!(windows) { "-NoTerminal -NoPause" } else { "-NoPause" }, - extra.join(" ") - ); - shell.console.push(&format!("[vncode] running {}", shown.trim())); - shell.console.push(&format!("[vncode] installer environment: {}", env.line())); - - let mut child = match command.spawn() { - Ok(child) => child, - Err(error) => { - shell.console.push(&format!("[vncode] could not run {}: {error}", entry.display())); - shell.finish(kind, None); - return; - } - }; - - // Both streams are drained for as long as the run lasts: a pipe nobody reads - // fills up and blocks the process writing to it, which for an installer that - // has a lot to say is a hang rather than a slow install. - let stdout = child.stdout.take(); - let stderr = child.stderr.take(); - let mut readers = Vec::new(); - for stream in [stdout.map(Stream::Out), stderr.map(Stream::Err)].into_iter().flatten() { - let console = Arc::clone(&shell.console); - // The status is shared with the reader threads so the panel can show HOW FAR - // ALONG the install is, not merely that one started. - let watcher = Arc::clone(&shell); - readers.push(thread::spawn(move || match stream { - Stream::Out(reader) => drain(console, Some(watcher), reader, false), - Stream::Err(reader) => drain(console, None, reader, true), - })); - } - - let exit = child.wait().ok().and_then(|status| status.code()); - for reader in readers { - let _ = reader.join(); - } - shell.console.push(&SetupStatus { - kind: Some(kind), - running: false, - exit, - detail: None, - last: None, - } - .line()); - shell.finish(kind, exit); -} - -enum Stream { - Out(std::process::ChildStdout), - Err(std::process::ChildStderr), -} - -fn drain( - console: Arc, - watcher: Option>, - reader: R, - is_error: bool, -) { - use std::io::{BufRead, BufReader}; - for line in BufReader::new(reader).lines().map_while(Result::ok) { - // The installer's own progress reaches the status as well as the log, so the - // pack row can say which bundle it is on. Only STDOUT: a warning on stderr is - // not progress, and the two streams interleave. - if let Some(watcher) = watcher.as_ref() { - if let Some(progress) = progress_line(&line) { - watcher.note(progress); - } - } - // The installer's own errors are kept distinguishable in one transcript, - // because "which stream said this" is the first question about a failure. - if is_error { - console.push(&format!("[stderr] {line}")); - } else { - console.push(&line); - } - } -} - -/// Split the arguments a headless command was given, the way a shell would. -/// -/// Whitespace separates, and **double quotes group** - so a path with a space in it -/// can be passed as one argument (`install -DshHome "C:\Users\me\My Home"`). The -/// quotes are not part of the argument. There are no escapes and no single quotes: -/// this exists so that a path with a space WORKS, not so that the shell can be -/// reimplemented, and a command line that needs more than that should be run -/// through the entry point directly. -pub fn split_args(line: &str) -> Vec { - let mut args = Vec::new(); - let mut current = String::new(); - let mut quoted = false; - let mut started = false; - for character in line.chars() { - match character { - '"' => { - quoted = !quoted; - // An empty quoted argument is an argument: `""` is one thing. - started = true; - } - c if c.is_whitespace() && !quoted => { - if started { - args.push(std::mem::take(&mut current)); - started = false; - } - } - c => { - current.push(c); - started = true; - } - } - } - if started { - args.push(current); - } - args -} - -#[cfg(test)] -mod tests { - use super::*; - - fn scratch(name: &str) -> PathBuf { - let root = match std::env::var_os("VNCODE_TEST_DIR") { - Some(value) if !value.is_empty() => PathBuf::from(value), - _ => std::env::temp_dir(), - }; - let path = root.join(format!("vncode-setup-{}-{name}", std::process::id())); - let _ = std::fs::remove_dir_all(&path); - path - } - - #[test] - fn arguments_split_on_whitespace_and_quotes_group() { - assert_eq!(split_args(""), Vec::::new()); - assert_eq!(split_args(" "), Vec::::new()); - assert_eq!(split_args("-Help"), vec!["-Help"]); - assert_eq!(split_args("-Force -Plugin pdf"), vec!["-Force", "-Plugin", "pdf"]); - // The case this exists for: a harness home with a space in it. Measured - - // the first version passed the quotes through, and PowerShell reported - // `Cannot find drive. A drive with the name '"C' does not exist.` - assert_eq!( - split_args(r#"-DshHome "C:\Users\me\My Home" -Force"#), - vec!["-DshHome", r"C:\Users\me\My Home", "-Force"] - ); - assert_eq!(split_args(r#"a "b c"d"#), vec!["a", "b cd"]); - assert_eq!(split_args(r#"empty "" here"#), vec!["empty", "", "here"]); - } - - #[test] - fn the_entry_points_are_found_where_the_tree_puts_them() { - let root = scratch("locate"); - let setup = root.join("scripts").join("setup"); - std::fs::create_dir_all(&setup).unwrap(); - // Nothing there yet: the panel must be able to say so rather than guess. - assert_eq!(locate(&root), None); - for name in ["install.bat", "install.sh", "uninstall.bat", "uninstall.sh"] { - std::fs::write(setup.join(name), b"rem fixture\n").unwrap(); - } - let found = locate(&root).expect("both entry points are there"); - let expected_extension = if cfg!(windows) { "bat" } else { "sh" }; - assert!(found.install.ends_with(format!("install.{expected_extension}"))); - assert!(found.uninstall.ends_with(format!("uninstall.{expected_extension}"))); - let _ = std::fs::remove_dir_all(&root); - } - - #[test] - fn the_child_environment_drops_every_console_variable() { - // The trap this pins: the panel is started by the console layer, so it - // inherits VNCODE_CONSOLE - and an entry point that sees it drops the - // arguments it was given. Measured on a machine where the first version of - // the Install button ran a full install while being asked for help. - unsafe { - for name in CONSOLE_VARIABLES { - std::env::set_var(name, "1"); - } - } - let env = composed(); - let command = command_for(Path::new("install.bat"), &["-Help".to_string()], &env, &[]); - let removed: Vec = command - .get_envs() - .filter(|(_, value)| value.is_none()) - .map(|(name, _)| name.to_string_lossy().to_string()) - .collect(); - unsafe { - for name in CONSOLE_VARIABLES { - std::env::remove_var(name); - } - } - for name in CONSOLE_VARIABLES { - assert!( - removed.iter().any(|removed| removed.eq_ignore_ascii_case(name)), - "{name} was left in the child's environment" - ); - } - // ...and the home the app decided reaches the installer as the entry - // point's own flag, because the harness would otherwise be installed into - // whatever home it defaults to. - let env = composed_home("/root/home"); - let command = command_for( - Path::new("install.bat"), - &[], - &env, - &[std::ffi::OsString::from("-DshHome"), std::ffi::OsString::from("/root/home")], - ); - let args: Vec = - command.get_args().map(|arg| arg.to_string_lossy().to_string()).collect(); - assert!(args.contains(&"-DshHome".to_string()), "{args:?}"); - assert!(args.contains(&"/root/home".to_string()), "{args:?}"); - assert_eq!( - command - .get_envs() - .find(|(name, _)| *name == "DSH_HOME") - .and_then(|(_, value)| value) - .map(|value| value.to_string_lossy().to_string()) - .as_deref(), - Some("/root/home") - ); - } - - /// The composer's own output, so these tests exercise the real thing. - fn composed() -> ChildEnv { - crate::env::compose(&crate::env::Facts { - launch: &vn_shell_core::launch::Launch::Npx, - home: None, - cache: None, - temp: None, - workspace: None, - inherited_path: None, - }) - } - - fn composed_home(home: &str) -> ChildEnv { - crate::env::compose(&crate::env::Facts { - launch: &vn_shell_core::launch::Launch::Npx, - home: Some(Path::new(home)), - cache: None, - temp: None, - workspace: None, - inherited_path: None, - }) - } - - #[test] - fn the_command_keeps_the_console_from_opening_a_window() { - let extras = vec!["-Help".to_string()]; - let command = command_for(Path::new("install.bat"), &extras, &composed(), &[]); - let args: Vec = command - .get_args() - .map(|arg| arg.to_string_lossy().to_string()) - .collect(); - assert!(args.iter().any(|arg| arg == "-NoPause"), "{args:?}"); - if cfg!(windows) { - assert!(args.iter().any(|arg| arg == "-NoTerminal"), "{args:?}"); - assert_eq!(args.first().map(String::as_str), Some("/c"), "{args:?}"); - } - assert!(args.iter().any(|arg| arg == "-Help"), "the caller's args must survive"); - } - - #[test] - fn the_status_says_what_happened_in_words() { - let running = - SetupStatus { kind: Some(SetupKind::Install), running: true, exit: None, detail: None, last: None }; - assert!(running.line().contains("installing"), "{}", running.line()); - let done = - SetupStatus { kind: Some(SetupKind::Install), running: false, exit: Some(0), detail: None, last: None }; - assert!(done.succeeded()); - assert!(done.line().contains("finished successfully"), "{}", done.line()); - let failed = - SetupStatus { kind: Some(SetupKind::Uninstall), running: false, exit: Some(1), detail: None, last: None }; - assert!(!failed.succeeded()); - assert!(failed.line().contains("FAILED (exit code 1)"), "{}", failed.line()); - assert!(SetupStatus::default().line().contains("has not been")); - } - - #[test] - fn only_the_installers_own_progress_lines_become_the_row() { - // The installer's own wording, and pnpm's progress - the two things that say - // "this is still moving". - assert_eq!( - progress_line(" - adding dsh-editor 0.1.0-alpha.13 (first install) ..."), - Some("- adding dsh-editor 0.1.0-alpha.13 (first install) ...".to_string()) - ); - assert_eq!( - progress_line("Progress: resolved 1234, reused 0, downloaded 12"), - Some("Progress: resolved 1234, reused 0, downloaded 12".to_string()) - ); - assert!(progress_line(" - added dsh-editor").is_some()); - // Everything else stays in the log, where a reader can read all of it. - assert_eq!(progress_line(""), None); - assert_eq!(progress_line(" "), None); - assert_eq!(progress_line("dsh: initialized profile web"), None); - assert_eq!(progress_line("npm warn deprecated inflight@1.0.6"), None); - // A line longer than the row is shortened rather than allowed to push the rest - // of the row out of the window. - let long = format!("- adding {}", "x".repeat(300)); - assert_eq!(progress_line(&long).unwrap().chars().count(), PROGRESS_CHARS); - } - - #[test] - fn the_runner_remembers_the_last_line_it_was_told() { - let console = Arc::new(Console::new()); - let setup = Setup::new(console); - assert_eq!(setup.status().last, None); - setup.note("- adding dsh-pdf 0.1.0-alpha.8".to_string()); - assert_eq!( - setup.status().last.as_deref(), - Some("- adding dsh-pdf 0.1.0-alpha.8") - ); - } - - #[test] - fn a_run_that_cannot_start_reports_rather_than_pretends() { - let console = Arc::new(Console::new()); - let setup = Arc::new(Setup::new(Arc::clone(&console))); - let missing = scratch("missing").join("install.bat"); - let error = setup - .start(SetupKind::Install, &missing, &[], &composed(), &[]) - .unwrap_err(); - assert!(error.contains("is not there any more"), "{error}"); - assert!(!setup.is_running()); - } -} diff --git a/app/crates/vn-shell/Cargo.toml b/app/crates/vn-shell/Cargo.toml deleted file mode 100644 index 18b9b14..0000000 --- a/app/crates/vn-shell/Cargo.toml +++ /dev/null @@ -1,21 +0,0 @@ -[package] -name = "vn-shell" -description = "The vncode binary: the front door that installs the pack, takes the key and runs the web launcher." -version.workspace = true -edition.workspace = true -license.workspace = true -publish.workspace = true -rust-version.workspace = true -# The distribution ships `vncode`, and every launcher and doc looks for that name. -# ONE name, and it is not the crate's. -[[bin]] -name = "vncode" -path = "src/main.rs" - -[features] -default = [] - -[dependencies] -vn-shell-core.workspace = true -vn-shell-runtime.workspace = true -rpassword.workspace = true diff --git a/app/crates/vn-shell/src/main.rs b/app/crates/vn-shell/src/main.rs deleted file mode 100644 index 36e6060..0000000 --- a/app/crates/vn-shell/src/main.rs +++ /dev/null @@ -1,357 +0,0 @@ -//! `vncode`: the front door, and nothing else. -//! -//! This binary draws no window and no web view. It decides four things - the root, the -//! home, the key and the pack - and then it runs the script a person would run: -//! `scripts/run-web.bat` on Windows, `scripts/run-web.sh` everywhere else, in the -//! foreground, with the composed environment and `-DshHome` so both halves agree about -//! which home is in use. -//! -//! ```text -//! vncode install if needed -> ask for the key if there is none -> run-web -//! vncode install scripts/setup/install.* against the home in use -//! vncode uninstall scripts/setup/uninstall.* against it -//! vncode status the facts, and nothing started -//! vncode key ask for the DeepSeek key, write it into /.env -//! vncode -Help the verbs and flags, without starting anything -//! ``` -//! -//! Two rules survive from the shell this replaces, because both are the record of a bug -//! measured on a real machine: -//! -//! 1. **A key is never printed.** The panel-era rule was "a layer NAME, never a value"; -//! the value now never leaves the prompt, is written to one file, and is not read back. -//! 2. **Every child's environment is composed, not inherited** (`vn_shell_runtime::env`), -//! because a variable that is merely unset is still inherited from whoever started this. - -use std::io::IsTerminal; -use std::path::{Path, PathBuf}; -use std::process::{Command as Process, Stdio}; - -use vn_shell_core::keystate::{self, KeyState}; -use vn_shell_core::options::{self, Command, Options}; -use vn_shell_core::{launch, ports, profile}; -use vn_shell_runtime as runtime; -use vn_shell_runtime::setup::{self, SetupKind}; -use vn_shell_runtime::Plan; - -/// The profile the launcher starts, and the one the pack is installed into. `dsh web` and -/// `dsh --profile web` are the same profile: this is the alias, not a second one. -const PROFILE: &str = launch::PROFILE; - -fn main() { - let options = match options::parse_args(std::env::args().skip(1)) { - Ok(options) => options, - Err(message) => { - eprintln!("[vncode] {message}"); - std::process::exit(1); - } - }; - if options.help { - options::print_usage(); - return; - } - if options.version { - options::print_version(); - return; - } - let code = match run(&options) { - Ok(code) => code, - Err(message) => { - eprintln!("[vncode] {message}"); - 1 - } - }; - std::process::exit(code); -} - -/// Resolve, report, then do the one thing that was asked for. -fn run(options: &Options) -> Result { - let plan = runtime::plan(options, None)?; - announce(&plan); - let environment = runtime::env::for_plan(&plan); - let home_arguments = runtime::env::dsh_home_arguments(&plan.home); - - match options.command() { - Command::Status => { - status(&plan); - Ok(0) - } - Command::Key => { - // A key is not required for the command to have done its job: a person who - // changes their mind gets a sentence and exit 0, not a failure. - ask_and_save_key(&plan)?; - Ok(0) - } - Command::Install => setup_run(SetupKind::Install, &plan, &environment, &home_arguments), - Command::Uninstall => setup_run(SetupKind::Uninstall, &plan, &environment, &home_arguments), - Command::Start => start(options, &plan, &environment, &home_arguments), - } -} - -/// The facts, once, in the same words `run-web` uses. -fn announce(plan: &Plan) { - println!("[vncode] pinned dsh version: {}", plan.version); - match plan.app_root() { - Some(root) => println!( - "[vncode] VNCODE_HOME: {} ({})", - root.display(), - plan.app_root_origin_label() - ), - None => println!("[vncode] VNCODE_HOME: none could be written"), - } - let (path, why) = plan.home.row(); - println!("[vncode] DSH_HOME: {path} ({why})"); - for refusal in &plan.home.refused { - println!("[vncode] refused: {}", refusal.line()); - } - println!("{}", keystate::console_line(&keystate::read(plan.home_path()))); - println!("[vncode] runtime: {}", plan.runtime_line()); - println!("[vncode] child environment: {}", plan.env_summary()); - for note in &plan.notes { - println!("[vncode] note: {note}"); - } -} - -/// The extra facts `status` adds: what is installed, and where the launcher is. -fn status(plan: &Plan) { - match plan.home_path() { - Some(home) => match profile::bundles(home, PROFILE) { - Some(bundles) => println!( - "[vncode] pack: {} ({} bundle(s) in the {PROFILE} profile)", - if profile::has_pack(&bundles) { "installed" } else { "NOT installed" }, - bundles.len() - ), - None => println!("[vncode] pack: no {PROFILE} profile in this home yet"), - }, - None => println!("[vncode] pack: no home was decided, so nothing can be installed"), - } - match launcher(plan) { - Ok(entry) => println!("[vncode] launcher: {}", entry.display()), - Err(message) => println!("[vncode] launcher: {message}"), - } - match plan.port_hint { - Some(port) => { - println!("[vncode] port: {port} (free now; start chooses again, -Port overrides)") - } - None => println!("[vncode] port: none free right now"), - } - match plan.root.as_deref() { - Some(root) => println!("[vncode] root: {}", root.display()), - None => println!("[vncode] root: none found above this binary"), - } - for (program, why) in [("node", "the harness needs it"), ("npx", "the launcher runs it")] { - match which(program) { - Some(path) => println!("[vncode] {program}: {}", path.display()), - None => println!("[vncode] {program}: NOT on PATH ({why})"), - } - } -} - -/// The whole path: the pack, then the key, then the launcher. -fn start( - options: &Options, - plan: &Plan, - environment: &runtime::ChildEnv, - home_arguments: &[std::ffi::OsString], -) -> Result { - // 1. THE PACK. Installed before anything runs, because the installer re-links the - // profile and must not run under a live harness - and nothing is running yet. - if !pack_is_installed(plan) { - println!("[vncode] this home does not list the pack's bundles - installing them first"); - let code = setup_run(SetupKind::Install, plan, environment, home_arguments)?; - if code != 0 { - return Err(format!( - "the pack installer failed (exit code {code}), so nothing was started" - )); - } - } - - // 2. THE KEY. Asked for only when there is none, and only at a terminal: an - // unattended run (a scheduler, a check) must not block on a prompt that nobody sees. - let key = keystate::read(plan.home_path()); - if key.source().is_none() { - println!("[vncode] no DeepSeek key was found for this home"); - ask_and_save_key(plan)?; - } - - // 3. THE LAUNCHER. The same file a person double-clicks, in the foreground: it runs - // the harness, watches for the URL line, opens the tab and takes Ctrl+C. - // - // **THE PORT IS THIS APP'S OWN, NEVER THE SHARED 3080**, and that is a measured rule - // rather than a preference: 3080 is what every `dsh web` on the machine reaches for, - // so a run that asks for it either collides (`EADDRINUSE` - measured by the first real - // run of this binary, on a machine whose harness was already answering there) or, worse, - // shares it with a process whose launch token this run does not have. A free port costs - // nothing because this app opens the tab itself with the token in it: nobody types an - // address and nothing is remembered per origin. `-Port 3080` is how to ask for the - // shared origin on purpose. - let port = match options.port { - 0 => ports::free_port().ok_or_else(|| { - "this machine would not hand out a free loopback port - pass -Port ".to_string() - })?, - asked => asked, - }; - let entry = launcher(plan)?; - let mut command = launcher_command(&entry); - command.args(home_arguments); - command.arg("-Port").arg(port.to_string()); - environment.apply(&mut command); - println!("[vncode] port: {port} (chosen by this app, never the shared 3080)"); - println!("[vncode] running {}", entry.display()); - println!("[vncode] keep this window open - the harness runs in it. Ctrl+C stops it."); - println!(); - let status = command - .status() - .map_err(|error| format!("could not run {}: {error}", entry.display()))?; - Ok(status.code().unwrap_or(1)) -} - -/// Whether the pack's bundles are in the profile the launcher will start. -fn pack_is_installed(plan: &Plan) -> bool { - plan.home_path() - .and_then(|home| profile::bundles(home, PROFILE)) - .map(|bundles| profile::has_pack(&bundles)) - .unwrap_or(false) -} - -/// Run one of the two setup entry points, with the child's own output going straight to -/// this console - the same thing a person sees when they run it themselves. -fn setup_run( - kind: SetupKind, - plan: &Plan, - environment: &runtime::ChildEnv, - home_arguments: &[std::ffi::OsString], -) -> Result { - let root = plan.root.as_deref().ok_or_else(|| { - "no checkout or distribution root was found above this binary, so there is no \ - scripts/setup to run" - .to_string() - })?; - let entries = setup::locate(root).ok_or_else(|| { - format!( - "no installer under {} - a release folder carries scripts/setup beside the binary", - root.join("scripts").join("setup").display() - ) - })?; - let entry = entries.for_kind(kind); - let mut command = setup::command_for(entry, &[], environment, home_arguments); - // `command_for` pipes both streams so a panel could draw them. There is no panel: - // this run's output is the console's, line for line, exactly as if it were typed. - command - .stdin(Stdio::inherit()) - .stdout(Stdio::inherit()) - .stderr(Stdio::inherit()); - println!("[vncode] {}: running {}", kind.label(), entry.display()); - let status = command - .status() - .map_err(|error| format!("could not run {}: {error}", entry.display()))?; - Ok(status.code().unwrap_or(1)) -} - -/// Ask for the DeepSeek key and write it into this home's `.env`. -/// -/// The value goes from the terminal into one file and nowhere else: it is not printed, it -/// is not logged, and it is not read back. The sentence names the FILE. -fn ask_and_save_key(plan: &Plan) -> Result<(), String> { - let home = plan.home_path().ok_or_else(|| { - "no harness home was decided, so there is nowhere to write a key".to_string() - })?; - if !std::io::stdin().is_terminal() { - println!( - "[vncode] stdin is not a terminal, so no key was asked for. Set {} in the \ - environment, or write it into {}", - keystate::KEY_REF, - home.join(keystate::ENV_FILE).display() - ); - return Ok(()); - } - println!( - "[vncode] paste your DeepSeek API key. It is written to {} and never printed.", - home.join(keystate::ENV_FILE).display() - ); - let value = rpassword::prompt_password(format!("{}: ", keystate::KEY_REF)) - .map_err(|error| format!("could not read the key: {error}"))?; - let value = value.trim(); - if value.is_empty() { - println!("[vncode] nothing was entered, so no key was written"); - return Ok(()); - } - let path = keystate::write_env_key(home, value)?; - println!("[vncode] wrote {} to {}", keystate::KEY_REF, path.display()); - Ok(()) -} - -/// The web launcher beside this tree: the ONE thing that starts node, watches the ready -/// line and opens the tab. -fn launcher(plan: &Plan) -> Result { - let root = plan.root.as_deref().ok_or_else(|| { - "no .dsh-version.json was found above this binary, so the web launcher beside it \ - cannot be found either - run vncode from its folder, or pass -DshHome and use \ - scripts/run-web.* directly" - .to_string() - })?; - let name = if cfg!(windows) { "run-web.bat" } else { "run-web.sh" }; - let path = root.join("scripts").join(name); - if !path.is_file() { - return Err(format!( - "{} is missing - this app starts the web launcher, and that file is what runs \ - the harness", - path.display() - )); - } - Ok(path) -} - -/// How the launcher is started. -/// -/// On Windows a `.bat` needs `cmd`, and two flags are the launcher's own: `-NoTerminal` -/// keeps the console layer from relaunching this run into a Windows Terminal window that -/// this process would not wait for (it would look like an instant, silent exit), and -/// `-NoPause` keeps it from holding a window open that already exists. On POSIX the -/// script takes no such flags. -fn launcher_command(entry: &Path) -> Process { - if cfg!(windows) { - let mut command = Process::new("cmd"); - command.arg("/c").arg(entry).arg("-NoTerminal").arg("-NoPause"); - command - } else { - let mut command = Process::new("sh"); - command.arg(entry); - command - } -} - -/// Where a program is, without running it - for `status` only. -fn which(program: &str) -> Option { - let extensions: Vec = if cfg!(windows) { - std::env::var("PATHEXT") - .unwrap_or_else(|_| ".COM;.EXE;.BAT;.CMD".to_string()) - .split(';') - .filter(|extension| !extension.is_empty()) - .map(|extension| extension.to_ascii_lowercase()) - .collect() - } else { - Vec::new() - }; - let path = std::env::var_os("PATH")?; - for directory in std::env::split_paths(&path) { - let direct = directory.join(program); - if direct.is_file() { - return Some(direct); - } - for extension in &extensions { - let candidate = directory.join(format!("{program}{extension}")); - if candidate.is_file() { - return Some(candidate); - } - } - } - None -} - -/// Kept honest by the type system rather than a comment: `KeyState` is only ever printed -/// through `console_line`, which names a layer and never a value. -#[allow(dead_code)] -fn key_line(state: &KeyState) -> String { - keystate::console_line(state) -} diff --git a/docs/BUILD.md b/docs/BUILD.md index 5a70f57..e4ce014 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -1,94 +1,77 @@ # Building vncode -Two verbs, deliberately separate: `scripts\run-desktop.bat` (or -`./scripts/run-desktop.sh`) is the developer loop - build the Rust app when it is missing -and run it from the checkout, where the package folders are already live-linked into the -profile; `scripts/checks/` is what says whether the change is sound. +**There is nothing to build.** The repository is pure Node/TypeScript/JavaScript: no +compiler, no build step, no native code, and zero npm dependencies in the packages it +ships. The harness is run through `npx` and the pack is loaded from this folder as a live +link, so a change is a file save. -## No JavaScript build step +That is the rule behind every other page here: a change is proved by RUNNING it, not by +compiling it, and the only toolchain any machine needs is **Node.js >= 22**. -There is no JavaScript/TypeScript build here; the packages are hand-written: +The one exception is a vendored engine: each keeps its own `vendor/build.mjs` and the +tracked hashes in its `lib/vendor/VERSION.json`. Regenerate those, never hand-edit them. -- `packages/*/lib/client.js` is the shipped browser bundle, loaded by the harness as a live - link - which is what makes a plugin edit visible on a reload. -- Vendored engines keep their own `vendor/build.mjs` and the tracked hashes in - `lib/vendor/VERSION.json`. Regenerate them, never hand-edit. -- `app/` is a **cargo workspace** of three crates, each with its own `cargo test`, and - `scripts/checks/` is the build gate: a build that fails a check is not a build. - -## The three entry points +## The two ways to run it | | what it does | |---|---| -| `scripts\run-web.bat` / `./scripts/run-web.sh` | starts the pinned harness and opens it in a browser tab. **The web half - it needs no `vncode` binary at all** | -| `scripts\run-desktop.bat` / `./scripts/run-desktop.sh` | builds `vncode` when there is none and runs it: install the pack if this home lacks it, ask for the key if there is none, then run the web launcher | -| `scripts\setup\install.bat` / `./scripts/setup/install.sh` | adds this folder's bundles to the `web` profile - and the same pair under `uninstall` takes them out again | - -There is no distributer, no self-contained folder and no vendored runtime any more. The -distribution is this repository plus (optionally) a built `vncode`, and the app installs -the pack itself by running the two `setup/` entry points above. - -## The app - -`cargo build --release --locked --manifest-path app/Cargo.toml` produces -`app/target/release/vncode` (~0.5 MB). No GUI toolkit, no web engine, no linker surprises: -the only dependencies are `serde_json` and `rpassword`, so nothing has to be installed -before a build and nothing has to be installed beside the binary. +| `install`, once, then `run-web` | the everyday path. `scripts\setup\install.bat` / `./scripts/setup/install.sh` adds this folder's bundles to the `web` profile, and `scripts\run-web.bat` / `./scripts/run-web.sh` starts the pinned harness with the pack and opens it | +| `npx --yes @deepseek-ai/dsh@ web` | the harness alone: no pack and no launcher. Useful for telling a plugin bug from a launcher one | -The size is a **budget, not a result**: `.github/workflows/ci.yml` fails the build over -6 MB, and `check-shell.mjs` fails over 12 MB. A dependency that draws a window - `eframe`, -`egui`, `wgpu`, `winit` - or a web view - `wry` and its three OS engines - is the only way -to get back over either line, and it is the change this project exists to prevent. +`run-web` never installs. It nags when the profile at the home in use does not list the +pack, and the installer is its own entry point. -## Runtime and launch path - -The app does not run node. It resolves the root, the home, the pin and the child's -environment, and then it runs `scripts/run-web.*` **in the foreground** - the same file a -person double-clicks, with `-DshHome ` so both halves agree, and with a -composed environment (`vn_shell_runtime::env`): `DSH_HOME` set, the console markers and -`VNCODE_HOME` removed, a writable npm cache and temp chosen by write probe. - -Everything about *which* harness runs lives in that launcher, not here: `npx --yes -@deepseek-ai/dsh@ web --no-open`, the ready line, the loopback check and the browser -hand-off (Chrome first, the OS opener as the floor). `scripts\run-web.bat` is therefore the -single source of truth for the harness command, and the app cannot disagree with it. - -## Signing, and Windows SmartScreen - -Authenticode covers the exact bytes of a file, so sign the binary you are about to publish -and nothing else: `signtool` on `app/target/release/vncode.exe`, with a certificate named -by the environment (never committed). Nothing in this repository signs anything, and there -is no build step that appends a payload to a binary - the app is one file as cargo produced -it. +## The three entry points -UAC is not a concern: nothing elevates and there is no installer. SmartScreen is: a -downloaded `.exe` warns until that file or publisher has reputation, and a self-signed -certificate fixes nothing for other people. Until a real certificate exists, the honest -thing is to say so in the release notes and publish `SHA256SUMS.txt` beside the binary, so -a reader who checks the hash is not relying on the warning being wrong. +| | what it does | +|---|---| +| `scripts\run-web.bat` | the Windows double-click entry: it forwards every flag to the worker beside it and holds the window open on a double-clicked failure | +| `scripts\run-web.ps1` | the Windows worker: the home ladder, `npx`, the ready line, the browser hand-off | +| `scripts/run-web.sh` | macOS / Linux: the whole job in one file, in POSIX `sh`, never PowerShell | -## CI +There are no other launchers and no forwarders. Both workers do the same work in the same +order: run `npx --yes @deepseek-ai/dsh@ web --no-open [--port ]`, watch stdout for +the `dsh web: ` ready line, refuse a URL that is not loopback, and open THAT url in +Google Chrome, falling back to the platform default browser. `-DefaultBrowser` skips +Chrome; `-NoBrowser` opens nothing. The harness runs in the foreground and Ctrl+C stops it. -`.github/workflows/ci.yml` runs clippy (`-D warnings`), the workspace tests, a release -build, the size budget and a smoke run - on all three OSes for a pull request, the Monday -schedule, a manual dispatch, and `release.yml`, which calls the same workflow as its gate. -**A push to `main` runs no CI at all** - that trigger is deliberately absent, so commits -and pushes are free and the checks that must not be skipped run at the boundaries. There is -no per-package JavaScript build to run in CI; the checks in `scripts/checks/` remain the -contract and are run by hand. +Install and uninstall are their own entry points one level down, in `scripts/setup/`: +`install.bat` / `install.sh` and `uninstall.bat` / `uninstall.sh`, with the workers +`install-all.*` / `uninstall-all.*` beside them. -## Checks +## How to check a change -Run the one that owns the area; a check that cannot run on this host skips loudly and exits -0. [scripts/checks/README.md](../scripts/checks/README.md) lists them all. +Run the check that owns the area. A check that cannot run on this host skips loudly and +exits 0, and [scripts/checks/README.md](../scripts/checks/README.md) lists them all. ```sh node scripts/checks/check-no-secrets.mjs # before anything is pushed node scripts/checks/check-scripts.mjs # the scripts layout, the console contract, the two workflows -node scripts/checks/check-node-routes.mjs # every Node route, the manifest, the patches +node scripts/checks/check-node-routes.mjs # every Node route, tool, the manifest, the patches node scripts/checks/check-client-bundles.mjs # every browser bundle, driven for real node scripts/checks/check-media-node.mjs # dsh-media's host half and its ffmpeg pin node scripts/checks/check-pdf-node.mjs # the five pdf tools and their routes node scripts/checks/check-skill-examples.mjs # every example in the shipped skills -node scripts/checks/check-shell.mjs # the app, driven: verbs, the bridge, the env ``` + +A plugin edit needs no restart: the host stat-polls each `client.js` every 500 ms and +republishes it, so a reload shows the change. A `lib/index.js` change (routes, tools) or a +row/profile change does need a host restart. + +## CI + +`.github/workflows/ci.yml` is ONE job on `ubuntu-latest` in a `node:22` container: it +installs `git`, which `check-no-secrets.mjs` reads the repository with, and runs +`check-no-secrets.mjs` and `check-scripts.mjs`. There is no compiler and no per-OS matrix, +because there is nothing to compile and the files are the same on every platform. + +It stays callable through `workflow_call` and runs at the boundaries only - a pull request, +a manual dispatch, and a release's gate. **A push to `main` starts no CI at all**, so +commits and pushes are free and the checks that must not be skipped run where they matter. + +## How a release is cut + +One artefact: `vncode-.zip`, a `git archive` of the repository at the tag. The zip +IS the distribution - the pack, the launchers and the docs - and there is no second +artefact and no ship list. [RELEASE.md](RELEASE.md) has the tag flow and what the gate +refuses. diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index 317a9fe..ff0fe73 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -1,15 +1,11 @@ # Compatibility The pack targets the harness line DeepSeek ships to the raw web install -(`npx @deepseek-ai/dsh web`). DSH Desktop is not supported: `app/` is a **front door** -to that same pinned `dsh web` (it installs nothing on its own and writes no profile -file - it runs `scripts/run-web.*`, the launcher a person would run). It is a small -Rust console program with no window and no web view: it decides the root and the -harness home, takes the key, installs the pack with the same entry point a person -clicks, and then hands over to the launcher, which owns the harness, the ready line -and the browser tab (Chrome first, every other browser reachable, the OS opener as -the floor). There is no embedded browser and therefore no per-OS web-engine -requirement: `wry` and its three engines left with the window. +(`npx @deepseek-ai/dsh web`), and one install target only: the **web profile**. There is no +desktop edition and no second edition to keep compatible - `scripts/run-web.*` runs that +same pinned `dsh web`, so the browser, the harness and the pack are the whole product. That +is also why there is no per-OS web-engine requirement to track: the page opens in the +person's own browser, which the launcher finds (Chrome first, the OS opener as the floor). ## Current pin @@ -19,7 +15,7 @@ requirement: `wry` and its three engines left with the window. | Forked from | the same `0.2.0-rc.2` line (`.dsh-version.json`'s `vendoredFrom`) | | Install target | the web profile only (`$DSH_HOME/profiles/web`; `$DSH_HOME` defaults to `~/.dsh`) | | Host platforms | Windows (PowerShell 5.1 or 7) and macOS / Linux (POSIX shell plus Node.js 22+ with npm/npx - never PowerShell) | -| The app | one Rust binary per OS, no system library, no runtime to install; CI builds and checks it on all three | +| Distribution | one artefact, `vncode-.zip` - the repository at the tag. Nothing is compiled, so nothing is per-OS | | Plugin code | plain JavaScript and OS-neutral; the only per-OS code is a launcher choosing the host command | ## What the pack ships, per bundle diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 269bb7a..fc82370 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -1,43 +1,36 @@ # Deploying vncode -What a distribution promises, the contract every launcher holds, and what it still depends -on outside itself. [PATHS.md](PATHS.md) is the location map, [RELEASE.md](RELEASE.md) how a -release is cut, [BUILD.md](BUILD.md) how the app is built. +What a distribution is, the contract every launcher holds, and what it still depends on +outside itself. [PATHS.md](PATHS.md) is the location map, [INSTALL.md](INSTALL.md) the +steps, [RELEASE.md](RELEASE.md) how a release is cut and [BUILD.md](BUILD.md) how it runs. -**A distribution is two artefacts, and they are independent.** +**A distribution is this repository.** There is no second thing to deploy beside it: the +pack, the launchers and the docs are the same files on every platform, they need Node.js +22+ with `npx` and nothing else, and there is nothing to build or ship. -| | | | -|---|---|---| -| **the web half** | this repository - the pack, the launchers, the console layer | runs with Node.js 22+ and nothing else. `scripts\run-web.bat` / `./scripts/run-web.sh` opens the browser interface on its own | -| **the app** | one small `vncode` per OS (~0.5 MB) | a front door: decide the home, take the key, install the pack, then run the web half | - -Neither needs the other. The app adds "one command to a working instance"; dropping it -beside the web half changes nothing about how the harness is launched, because the app -calls the same `scripts/run-web.*` and passes it `-DshHome`. - -## What the build gets right +## What the distribution gets right | | | |---|---| -| **The app installs the pack** | `vncode install` (and a plain `vncode start` over a home that lacks it) runs `scripts/setup/install.*` - the same entry point a person clicks - in the app's own console, with the composed environment and `-DshHome ` | -| **The app never draws the interface** | no `wry`, no WebView2 / WKWebView / WebKitGTK, no `egui`, no window. The page is the harness's and it opens in the browser the launcher found | -| **The web half stands alone** | `check-shell.mjs` runs `scripts/run-web.* -Help` with no binary involved, and it must answer | -| **`check-scripts.mjs` drives the entry points** | the layout, the console contract, `setup/install.bat -Help` and `setup/uninstall.bat -Help` (which install nothing), and the two release workflows | -| **`check-shell.mjs` drives the app** | the verbs, `-Mode embed` refused by name, and `start` against **stub scripts** in a throwaway tree: the installer is run because the home lacks the pack, the launcher is handed `-DshHome`, `-NoTerminal` and a composed environment, and the app's own root and the console markers are absent from the child | +| **One artefact** | `vncode-.zip`, a `git archive` of the repository at the tag. Unzip it and you have the whole distribution | +| **Nothing per OS** | nothing is compiled, so nothing can be compiled wrong for a host. The same zip runs on Windows, macOS and Linux | +| **The launcher is the interface** | `scripts\run-web.bat` / `./scripts/run-web.sh` runs the pinned harness, reads its ready line and opens that URL in Chrome. It needs no other file | +| **Install is its own entry point** | `scripts\setup\install.bat` / `install.sh` adds the bundles once, and `run-web` only nags when the profile lacks them - it never installs | +| **`check-scripts.mjs` drives the entry points** | the `scripts/` layout, the console contract every Windows entry point must hold, and each entry point's own `-Help` - `run-web.*` answers it without starting the harness, and the setup pair answers it without installing anything | ## The launcher contract | File | Host | Role | |---|---|---| -| `scripts\setup\install.bat` / `scripts/setup/install.sh` | both | add this folder's bundles to the web profile; no admin, ever | +| `scripts\setup\install.bat` / `scripts/setup/install.sh` | both | add this folder's bundles to the web profile, once; no admin, ever | | `scripts\setup\uninstall.bat` / `scripts/setup/uninstall.sh` | both | remove only what this pack added | -| `scripts\run-web.bat` / `scripts/run-web.sh` | both | start the pinned harness and open it in Chrome (default browser as fallback) | -| `scripts\run-desktop.bat` / `scripts/run-desktop.sh` | both | build `vncode` when there is none and run it; it decides nothing about the instance itself | +| `scripts\run-web.bat` / `scripts\run-web.ps1` | Windows | start the pinned harness and open it in Chrome (default browser as the fallback) | +| `scripts/run-web.sh` | macOS / Linux | the same, in POSIX `sh` | | `scripts\console\adapt.cmd` + `theme.ps1` / `theme.sh` | both | the shared console layer (see below) | | `scripts\tools\*` | maintainer only | the fork re-sync for the client bundles this pack vendors | Everything under `scripts/` that is not one of those entry points lives in a folder: -`setup/` (install and uninstall), `console/` (the shared layer), `tools/` +`setup/` (install, uninstall and their workers), `console/` (the shared layer), `tools/` (maintainer-only) and `checks/`. `check-scripts.mjs` fails on a stray file at the top level, because "what I run" and "what it uses" must be tellable apart at a glance. @@ -50,13 +43,11 @@ codes are `0` success, `1` own failure or usage error and `2` a missing prerequi POSIX halves mirror the behaviour in plain `/bin/sh`, never PowerShell, and nothing ever asks for elevation. -**One trap, and every child of the app clears it.** The console layer marks a run it has -set up with `VNCODE_CONSOLE=1`, and an entry point that sees the marker keeps the arguments -from the relaunched shell instead of its own `%*`. The app is started BY that layer, so it -inherits the marker: `vn_shell_runtime::env` removes it (and `VNCODE_HOME`) from the -environment of the installer **and** the launcher. Measured, not assumed - without it, -`install.bat -Help` ran a full install - and `check-shell.mjs` reads the child's own answer -back. +**One trap, and every entry point respects it.** The console layer marks a run it has set +up with `VNCODE_CONSOLE=1`, and an entry point that sees the marker keeps the arguments +from the relaunched shell instead of its own `%*`. That is why an entry point forwards +`%VNCODE_ARGS%` and never `%*`, and why `adapt.cmd` must not `setlocal`. Measured, not +assumed: without it, `install.bat -Help` ran a full install. ## What a distribution still depends on @@ -65,20 +56,19 @@ pack is not made self-contained by copying it: moving it does not move the insta `npm cache clean --force` (or another `npm_config_cache`) leaves every link dangling, and the cache grows about **223 MB per pin, per user**. Installing needs the network twice - `npx @deepseek-ai/dsh@` downloads that closure on first run, and the installer -bootstraps pnpm into `./tools` (about **13 MB**) because `dsh plugin add` spawns `pnpm` -from `PATH`. The target machine needs **Node.js 22+**, and Windows needs PowerShell, which -ships with it. +bootstraps pnpm into `./tools` with the npm that ships with Node.js, because +`dsh plugin add` runs pnpm underneath. The target machine needs **Node.js 22+**, and +Windows needs PowerShell, which ships with it. + +The launcher sets what it can of this. A portable folder points `npm_config_cache` at +`/.vncode/npm-cache` unless the caller set one, so neither the harness nor its cache +lands in the user's profile. -The app composes what it can of this. It picks an npm cache by writing where npm really -writes (`/_cacache/tmp`), hands the child a writable temp when the machine's is -refused, and puts the vendored runtime's `node` first on `PATH` when a folder carries one. +## Deferred -## Deferred and open +- Colour parity inside the POSIX workers' own messages. +- macOS double-click wrappers (`.command`). -- **Deferred**: colour parity inside the POSIX workers' own messages; macOS double-click - wrappers (`.command`); signing and notarization of the binaries. -- **Open**: whether the app should keep a cache of its own between runs; whether - `vncode open` (a second tab for a running instance) is worth the URL it would need. -- Nothing in `packages/` learns that a distribution exists, and optional host engines (a - TeX engine, poppler/mutool/Ghostscript and tesseract, ffmpeg) stay optional and degrade - in a sentence when absent. +Nothing in `packages/` learns that a distribution exists, and optional host engines (a TeX +engine, poppler/mutool/Ghostscript and tesseract, ffmpeg) stay optional and degrade in a +sentence when absent. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 80100ee..4d741d8 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -5,70 +5,36 @@ | **Install** | `scripts\setup\install.bat` | `./scripts/setup/install.sh` | | **Run** | `scripts\run-web.bat` | `./scripts/run-web.sh` | | **Remove** | `scripts\setup\uninstall.bat` | `./scripts/setup/uninstall.sh` | -| **The app** | `scripts\run-desktop.bat` | `./scripts/run-desktop.sh` | Double-click the `.bat` files on Windows; run the `.sh` files from anywhere (each resolves -the repository root from its own location). **The app can do the install for you**: its -`install` verb runs the same `setup/install.*` entry point with the same output, and its -plain `start` installs the pack first when the home in use does not list it. The two are -interchangeable, and neither needs an administrator. +the repository root from its own location). A fresh machine runs **install once, then +`run-web`** - the two are separate entry points on purpose, so starting the harness never +rewrites a profile. Neither needs an administrator. -**Launching only the web is a supported thing to do.** `scripts\run-web.bat` / -`./scripts/run-web.sh` is the whole browser experience and needs no `vncode` binary: the -app is a front door (key, install, then this same file), not a requirement. - -`scripts/` carries the entry points a person runs (`run-web.*`, `run-desktop.*`) at its top -level, and everything else in a folder: `setup/` (install and uninstall, with their -workers), `console/` (the shared console layer), `tools/` (maintainer-only) and `checks/`. -The repository root carries no `.bat` and no `.sh`. +`scripts/` carries the three entry points a person runs (`run-web.bat`, `run-web.ps1`, +`run-web.sh`) at its top level, and everything else in a folder: `setup/` (install and +uninstall, with their workers), `console/` (the shared console layer), `tools/` +(maintainer-only) and `checks/`. The repository root carries no `.bat` and no `.sh`. | | | |---|---| -| Requirements | **Node.js 22+** on every platform; **Windows** uses Windows PowerShell 5.1 (shipped) or PowerShell 7, **macOS / Linux** a POSIX shell and never PowerShell; `pnpm` is reused when the system copy is new enough, else bootstrapped into `./tools` | -| Install target | the **web profile** only, `$DSH_HOME/profiles/web` (`$DSH_HOME` = env var, else `~/.dsh`). `-Target web` and `-Target cli` both mean it; there is no desktop target. Overrides: `-DshHome `, `-ProfileName ` | -| State | model credentials in `$DSH_HOME/.credentials.yaml` or the home's `.env`; sessions, settings, attachments and the pack's own caches under the same home | - -## The app: `vncode` - -A small console program - no window, no embedded web view - that decides the root, the key -and the pack and then runs the web launcher. - -``` -vncode install the pack if this home lacks it, ask for the key if there - is none, then start the harness and open it (scripts\run-web.bat) -vncode start the same thing, spelled out -vncode install run scripts/setup/install.* against the home in use -vncode uninstall run scripts/setup/uninstall.* against it -vncode status the pin, the home and why it was chosen, the pack, the key layer, - where the launcher is; start nothing -vncode key ask for the DeepSeek key and write it into /.env (0600) -``` - -Flags: `-Port `, `-DshHome `, `-DshVersion `, `-Help`, `-Version`. The key is -asked for only when there is none and only at a terminal; a piped run never blocks on it. -`start` gives the launcher a free loopback port **of its own** - never the shared `3080`, -which is what every `dsh web` on the machine reaches for - and `-Port 3080` is how to ask -for the shared origin on purpose. - -**The app owns a root** (`$VNCODE_HOME`, default the platform's per-user data directory -plus `vncode`) and the harness home is `/home` inside it. A folder that carries -`.vncode/PORTABLE` - or already holds a home - is a portable installation and uses its own -`.vncode` instead, so everything travels with the folder. [PATHS.md](PATHS.md) is the map. +| Requirements | **Node.js 22+** on every platform, with `npx`. **Windows** runs the launcher on Windows PowerShell 5.1 (shipped) or PowerShell 7; **macOS / Linux** uses a POSIX shell and never PowerShell | +| Install target | the **web profile** only, `$DSH_HOME/profiles/web` (`$DSH_HOME` = env var, else the portable root below, else `~/.dsh`). Overrides: `-DshHome `, `-ProfileName ` | +| State | the DeepSeek key in `$DSH_HOME/.env` or `$DSH_HOME/.credentials.yaml`; sessions, settings, attachments and the pack's own caches under the same home | ## Launchers -On Windows each entry point calls the PowerShell worker beside it (`install.bat` -> -`install-all.ps1`, `uninstall.bat` -> `uninstall-all.ps1`, `run-web.bat` -> `run-web.ps1`), -and `run-desktop.bat` builds `vncode` when it is missing and then runs it. `run-desktop.sh` -is the same on macOS/Linux, in plain POSIX shell. The POSIX `.sh` files do the work -themselves and need Node.js with npm/npx only. Direct calls: `powershell -NoProfile --ExecutionPolicy Bypass -File scripts\setup\install-all.ps1 -Force` and `sh -scripts/setup/install-all.sh -Force` (the same with `uninstall-all.*` and `run-web.*`). +On Windows each entry point calls the worker beside it (`install.bat` -> +`install-all.ps1`, `uninstall.bat` -> `uninstall-all.ps1`, `run-web.bat` -> +`run-web.ps1`). The POSIX `.sh` files do the work themselves and need Node.js with +npm/npx only. Direct calls: `powershell -NoProfile -ExecutionPolicy Bypass -File +scripts\setup\install-all.ps1 -Force` and `sh scripts/setup/install-all.sh -Force` (the +same with `uninstall-all.*` and `run-web.*`). Flags on both halves: `-Force`, `-Plugin `, `-DshHome`, `-ProfileName`, -`-DshVersion`, `-Target web|cli`, `-NoPause`, and `-NoTerminal` on Windows; `-Help`, `-h`, -`--help` and `/?` print the usage. The `-all` in a worker's name means it installs **every -bundle the pack carries**; `-Plugin` narrows it to one. +`-DshVersion`, `-NoPause`, and `-NoTerminal` on Windows; `-Help`, `-h`, `--help` and `/?` +print the usage. The `-all` in a worker's name means it installs **every bundle the pack +carries**; `-Plugin` narrows it to one. The Windows entry points share `scripts\console\`: `adapt.cmd` relaunches into Windows Terminal when it exists and nothing is already inside one (`-NoTerminal` or @@ -79,35 +45,58 @@ policy: colour only on a real terminal, never in a redirected log, `NO_COLOR` al Exit codes: `0` success, `1` own failure or usage error, `2` a missing prerequisite (no PowerShell, no Node). Nothing asks for administrator rights. -**The app clears that layer's markers for every child it starts.** `adapt.cmd` marks a run -it has set up with `VNCODE_CONSOLE`, and an entry point that sees the marker takes its -arguments from the relaunched shell instead of `%*`. Because the app is started *by* that -layer, it inherits the marker - so it is removed from the launcher's and the installer's -environment. Measured, not assumed: without that, `install.bat -Help` ran a full install. +`adapt.cmd` marks a run it has set up with `VNCODE_CONSOLE`, and an entry point that sees +the marker takes its arguments from the relaunched shell rather than its own `%*` - which +is why an entry point forwards `%VNCODE_ARGS%` and never `%*`. Measured, not assumed: +without that rule, `install.bat -Help` ran a full install. + +## Which home a run uses + +Both workers implement the same ladder, in this order: + +| # | candidate | when it is used | +|---|---|---| +| 1 | `-DshHome ` | the person named it for this run | +| 2 | an inherited `DSH_HOME` | a harness session started this shell, and the run JOINS it | +| 3 | **`/.vncode/home`** | this folder is a **portable installation**: it carries the `PORTABLE` marker, or it already holds a `home` folder. The pack, the sessions and the key then need nothing in the user's profile | +| 4 | `~/.dsh` | the harness's own default, for a folder that is not portable | + +`run-web` prints the home it chose and **only nags** when the profile there does not list +the pack; it never installs. [PATHS.md](PATHS.md) is the full map. ## Running it `scripts\run-web.bat` / `./scripts/run-web.sh` starts the pinned harness with the browser hand-off attached. Flags: `-Port `, `-DshHome `, `-DshVersion `, `-NoBrowser` (server only), `-DefaultBrowser` (skip Chrome). It runs `npx --yes -@deepseek-ai/dsh@ web --no-open` (plus `--port `), streams the app's own output, -watches for the ready line `dsh web: http://127.0.0.1:/?token=` and -opens **that** URL in Google Chrome (`PATH`, the standard install folders, Windows' `App -Paths`, `/Applications/Google Chrome.app`, `google-chrome`/`chromium`), falling back to the -platform default browser. It stays in the foreground: Ctrl+C stops it and the terminal -prints the app's exit status. - -- **The launch token is a live credential.** It is read from the app's output in memory +@deepseek-ai/dsh@ web --no-open` (plus `--port `), streams the harness's own +output, watches for the ready line `dsh web: http://127.0.0.1:/?token=` +and opens **that** URL in Google Chrome - `PATH`, then the standard install folders, then +the `App Paths` registry on Windows; `open -a 'Google Chrome'` then +`google-chrome`/`chromium` on macOS and Linux - falling back to the platform default +browser. It stays in the foreground: Ctrl+C stops it and the terminal prints the harness's +exit status. + +- **The launch token is a live credential.** It is read from the harness's output in memory only - never written to a file, never echoed, never built into a command string; it reaches the browser as one argv element. Treat a screenshot or a pasted log of that pane like the session cookie itself. - **Only a loopback URL is opened.** A ready line naming anything but `127.0.0.1`, `::1` or `localhost` is refused and reported instead of opened. +## The DeepSeek key + +There is no key prompt: the harness resolves the key itself, in this order - `DEEPSEEK_API_KEY` +in the environment, then a `.env` beside where the launcher was started, then +`/.env`. Two ways to give it one: + +- in the harness UI, under **Settings > Models**; +- or by putting the line `DEEPSEEK_API_KEY=...` in `/.env`. + ## Manual path and uninstall -`npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add ` (with `pnpm` on -`PATH`) installs one bundle by hand, and `remove ` takes it out. +`npx --yes @deepseek-ai/dsh@ plugin --profile web add ` installs one bundle by +hand, and `remove ` takes it out. `scripts\setup\uninstall.bat` / `./scripts/setup/uninstall.sh` removes every bundle this pack added; both installers prune the retired names `dsh-files` and `dsh-focus` first. @@ -115,12 +104,10 @@ pack added; both installers prune the retired names `dsh-files` and `dsh-focus` | Symptom | What it means | |---|---| -| the run launcher says the port is in use | 3080 is taken; use that instance or pass `-Port 3099` | -| the harness dies with `EADDRINUSE 127.0.0.1:3080` | something already answers on 3080 - usually the harness this very session is open in. `vncode` picks a free port of its own, so this only happens when `-Port 3080` was asked for on purpose: drop the flag, or pass another port | -| `scripts\run-web.bat` flashes and closes, or no browser opens | run it from the repo root (the worker reads `.dsh-version.json` there) with `node`/`npx` on `PATH`; the URL is in the app's own output | -| `vncode` says the web launcher is missing | it starts `scripts/run-web.*`, so it must run from its folder: the git archive, or a folder that carries `scripts/` and `.dsh-version.json` beside the binary | -| the app came up in a home you did not expect | that is the ladder in [PATHS.md](PATHS.md): a `-DshHome` you typed is used or refused by name, a writable inherited `DSH_HOME` is joined, and otherwise the app creates `$VNCODE_HOME/home`. `vncode status` names the path, the reason, and every candidate it refused | -| the app's own data is somewhere you did not expect | `$VNCODE_HOME` names it. The default is the platform's per-user data directory plus `vncode`; `\.vncode` is used only when even that cannot be written (a workspace-scoped confinement) | -| no browser opens | the launcher's own log says which rung took the page, and the URL is printed either way, so it can be pasted into a browser by hand. `-DefaultBrowser` skips Chrome | -| `Permission denied` on a `.sh` | `chmod +x scripts/*.sh` | +| the launcher says the port is in use | 3080 is taken; use that instance or pass `-Port 3099` | +| the harness dies with `EADDRINUSE 127.0.0.1:3080` | something already answers on 3080 - usually the harness this very session is open in. Pass another port | +| `scripts\run-web.bat` flashes and closes, or no browser opens | run it from a folder that carries `scripts/` and `.dsh-version.json` with `node`/`npx` on `PATH`; the URL is in the harness's own output | +| a run started against a home you did not expect | that is the ladder above: a `-DshHome` you typed wins, an inherited `DSH_HOME` is joined, then the portable root, then `~/.dsh`. `run-web` prints the one it chose | +| `Permission denied` on a `.sh` | `chmod +x scripts/*.sh scripts/setup/*.sh` | +| the profile "does not list this pack" | run the installer once for that home: `scripts\setup\install.bat` / `./scripts/setup/install.sh`, with `-DshHome` if the home is not the default | | an edited plugin never appears after a refresh | it should: the host stat-polls every plugin's `client.js` (500 ms) and republishes it, so reload the page - and hard-reload if it still shows the old build, because the index ships no cache headers. A `lib/index.js` change (routes, tools) and any row/profile change DO need a host restart. `document.querySelector('[data-dsh-cmdbar-dock]').dataset.dshCmdbarVersion` names the build a page is running | diff --git a/docs/PATHS.md b/docs/PATHS.md index 042e92b..040e0c0 100644 --- a/docs/PATHS.md +++ b/docs/PATHS.md @@ -1,97 +1,44 @@ # Where vncode keeps things -Two roots, and the second one lives inside the first - and **one** of the first: the npm -cache and the home both live under the single root the ladder chose, so a root that cannot -be written never splits the app's memory in two. +**One root matters: the harness home.** The harness keeps all its user data in one folder, +with the same shape on all three operating systems and no `%APPDATA%`/XDG split, and this +pack writes nothing of its own outside it. The launcher resolves that folder, prints the one +it chose and points the harness at it; everything below is a consequence of that one rule. -## `$VNCODE_HOME` — the app's own root +## The repository root -The app creates it, proves it by writing, and it is the one directory a person can -move, back up or delete without touching a harness. The harness home is a folder -*inside* it, which is why the keys and the sessions live somewhere this app actually -controls: +The checkout is the distribution. It carries the pack (`packages/`), the launchers +(`scripts/`), the docs and one manifest: -```text -$VNCODE_HOME portable: \.vncode - ├── npm-cache/ the npx fallback's cache - and nothing else's - └── home/ DSH_HOME by default: everything that matters - ├── profiles/ sessions/ storages/ attachments/ skills/ - ├── .credentials.yaml the model key - ├── .env DEEPSEEK_API_KEY, when `vncode key` wrote one - └── dsh-pdf/ dsh-diagrams/ dsh-media/ the pack's caches -``` +| Path | What it is | +|---|---| +| `.dsh-version.json` | the pinned harness line (`dsh`) and the pack manifest; `check-node-routes.mjs` enforces that its versions match every `package.json` | +| `.vncode/` | gitignored, and used only when this folder is a portable installation: it holds that installation's `home/` and `npm-cache/` | +| `tools/pnpm/` | a pnpm the installer bootstrapped locally, when the system copy was too old for the profile | -The app writes **nothing else** here. It starts no browser and no engine, so there is no -profile for either: the page opens in the person's own browser, under their own profile, -exactly as `scripts\run-web.bat` does when it is run by hand. +## The harness home ladder -The root ladder, in order, each rung proved by writing: +Both `run-web` workers implement this identically, each rung before the next: | # | candidate | when it is used | |---|---|---| -| 1 | `VNCODE_HOME` | the environment named it | -| 2 | **`/.vncode`** | this folder is a **portable installation**: it carries the marker (`PORTABLE` - an empty file, written by hand or by an older build's `Keep everything in this folder`), **or** it already holds a home - the app has put this person's sessions there, and preferring the platform directory now would start a second installation beside them | -| 3 | platform data root + `vncode` | the default | -| 4 | `/.vncode` | the last resort, where even the data root cannot be written (a workspace-scoped confinement, which is what this repository's own checks run inside). It is gitignored | +| 1 | `-DshHome ` | the person named it for this run | +| 2 | an inherited `DSH_HOME` | a harness session started this shell, and the run JOINS that home, sharing its sessions and its key | +| 3 | **`/.vncode/home`** | this folder is a **portable installation**: it carries the `PORTABLE` marker (an empty file, written by hand), **or** it already has a `home` folder. The pack, the sessions and the key then need nothing in the user's profile | +| 4 | `~/.dsh` (`%USERPROFILE%\.dsh`) | the harness's own default, for a folder that is not portable | -| platform | the default root (rung 3) | -|---|---| -| Windows | `%LOCALAPPDATA%\vncode` | -| macOS | `~/Library/Application Support/vncode` | -| Linux | `$XDG_DATA_HOME/vncode`, else `~/.local/share/vncode` | - -`prefs.json` is read from the root this ladder chose, with the platform copy as a -**read-only fallback** for one migration: an earlier build wrote the file under the -platform root while the root in use was beside the checkout, so the home somebody chose -could not be read back and the first-run question returned on every launch. Every save -goes to the ladder's root. - -**Every path a person or a parent gives is cleaned before it is used** (`userpath.rs`): -a leading `~` is expanded the way the harness expands it, a relative path is resolved -against the directory the app was started in, `.` and `..` are folded lexically, a path -that is rooted without a drive (`/tmp/x` on Windows) is attached to the current drive, an -empty value or one containing a NUL is refused by name, and what is exported to a child is -the REAL path - with the Windows `\\?\` verbatim form stripped, because `cmd`, PowerShell, -JSON consumers and this pack's own checks all disagree with it. A directory the app -CREATED is hardened to `0700` on Unix (the home holds `.credentials.yaml`; the root holds -an npm cache that can hold registry credentials); a directory it merely JOINED is never -touched, which is why the write probe reports whether it created it. - -**Why the furniture is outside the home.** `-DshHome` may point the harness home at -`~/.dsh`, or at a folder shared with `scripts\run-web.bat`, and this app's own npm cache -must survive that - the argument [app/crates/vn-shell-core/src/appdata.rs](../app/crates/vn-shell-core/src/appdata.rs) -records for the cache, and it is the only thing left beside the home. +Rung 3 exists so a folder that carries everything else carries its home too: the pack, the +sessions and the key stay together, and a run started from anywhere in that folder finds the +same one. A portable run also points `npm_config_cache` at `/.vncode/npm-cache` unless +the caller set one, so the npx cache does not land in the user's profile either. +`check-scripts.mjs` reads both workers for the marker and the `home` folder, so the two +copies of the rule cannot drift. ## `$DSH_HOME` — the harness home -The harness keeps all its user data in one folder, with the same shape on all three -operating systems and no `%APPDATA%`/XDG split. The app hands it over explicitly, and -its own ladder decides which folder that is: - -| # | candidate | when it is used | -|---|---|---| -| 1 | `-DshHome ` | the person named it. **A refusal here ends the run** — an explicit instruction is never silently ignored | -| 2 | a home remembered by an older build (`prefs.json`) | it outranks an environment variable; if it has moved or gone, the ladder continues and says so. Nothing writes this file any more - the app has no chooser - so the rung exists to honour a choice somebody already made | -| 3 | an inherited `DSH_HOME` | it is writable: the app JOINS the home of the session that started it, sharing its sessions and its key | -| 4 | `/home` | **the default**, created and proved by the app | -A candidate is used only after a real write probe, and every refused candidate is -named in the log and by `vncode status`. - -**Nothing outside the app's own root is ever the home it runs against.** The harness's own -default (`~/.dsh`) was once row 4 here — a one-time courtesy, used while the app's own home -was still empty — and it is gone: a folder that carries everything it needs must not reach -into a person's profile to START. The two things that rung answered are answered here: Start -installs this pack into the home in use, and the key row asks for the key. That directory -survives as the READ-ONLY SOURCE of the first-run COPY, which brings a person's own -sessions and key into the folder and never runs against it. - -The same rule makes the first-run screen's source safe to offer: the harness's own -first-boot furniture (a composed `profiles/`, an empty `.credentials.yaml`, a `storages/`) -cannot make a home look used, and a home that IS used is never overwritten by a copy. - -For a harness started by **anything else** (`npx dsh web`, the CLI by hand), the harness's -own resolver is still what decides, highest precedence first — and it is -`@deepseek-ai/dsh-home-paths` (`resolveDshHome`) that decides it: +For a harness started by anything else (`npx dsh web`, the CLI by hand), the harness's own +resolver is what decides, highest precedence first - it is `@deepseek-ai/dsh-home-paths` +(`resolveDshHome`) that answers: | Precedence | Source | Windows | macOS / Linux | |---|---|---|---| @@ -99,30 +46,18 @@ own resolver is still what decides, highest precedence first — and it is | 2 | `$DSH_HOME` (empty or whitespace counts as unset) | as given | as given | | 3 | the default | `%USERPROFILE%\.dsh` | `$HOME/.dsh` | -The pack's OWN launcher, `scripts\run-web.bat` / `./scripts/run-web.sh`, resolves the home -before it starts anything, and it agrees with the app rather than with the default above: - -| # | candidate | when it is used | -|---|---|---| -| 1 | `-DshHome ` | the person named it for this run | -| 2 | an inherited `DSH_HOME` | a harness session started this shell, and the run JOINS it | -| 3 | **`/.vncode/home`** | this folder is a **portable installation**: it carries the `PORTABLE` marker, or it already holds a home. The pack, the sessions and the key then need nothing in the user's profile, and `run-web` starts the SAME home the panel does — two launchers pointing at two homes is how a pack ends up installed in one and missing in the other | -| 4 | `~/.dsh` (`%USERPROFILE%\.dsh`) | the harness's own default, for a folder that is not portable | - -It is Node's `homedir()`, so the Windows half is `%USERPROFILE%` and never -`%APPDATA%`, and a `~`/`~/` prefix in a configured path expands against it. A portable run -also points `npm_config_cache` at `/npm-cache` (unless the caller set one), so the -npx cache does not land in the user's profile either. The portable test is the same rule -`vn_shell_core::appdata::portable_root` applies, and `check-scripts.mjs` reads both -launcher workers for the marker and the `home` folder so the three copies cannot drift. +It is Node's `homedir()`, so the Windows half is `%USERPROFILE%` and never `%APPDATA%`, and +a `~`/`~/` prefix in a configured path expands against it. ## What lives under the harness home + | Path (relative to the home) | What it is | |---|---| | `sessions/` | one file per conversation (the durable transcript) | | `storages/` | `workspace.json` and session projection caches - host-side UI state | | `settings.yaml.imported` | the harness's legacy preference file, imported once and renamed; the pack's own state is not here | -| `.credentials.yaml` | the model API key | +| `.credentials.yaml` | the model API key, when the harness stored it there | +| `.env` | `DEEPSEEK_API_KEY=...`, the line the harness also reads | | `.anonymous-user-id` | one random id, created on first run | | `attachments/v1/files/…` | files pasted or attached into a conversation | | `skills/` | the pack's copied skills (`mermaid-diagrams`, `tikz-diagrams`, `diagram-design`, `pdf-analysis`, `ffmpeg-cli`, `ffprobe-cli`, `web-render` and SuperCollider's five), each under a `.vncode-` marker | @@ -133,44 +68,39 @@ launcher workers for the marker and the `home` folder so the three copies cannot | `dsh-media/bin/-/` | the provisioned ffmpeg/ffprobe copy and its `install.json` stamp - absent where ffmpeg is already on `PATH` | | `dsh-media/playable/.mp4` | the browser-playable remux/transcode cache, LRU at 8 GiB | -The pack's own trees are the last five, and they follow the harness's rule: a -plugin's state goes under the harness home and nowhere else. Three are caches with a -ceiling (512 MiB, 200 MiB, 8 GiB), and `dsh-media/bin` is the one **program** the -pack writes - only after the bytes match the SHA-256 it pins. **Adopt never copies -any of them**: they are reproducible, and the credentials file is the only thing -outside `sessions/`, `storages/`, `attachments/` and `skills/` that a person may -choose to bring across. +The pack's own trees are the last four, and they follow the harness's rule: a plugin's +state goes under the harness home and nowhere else. Three are caches with a ceiling +(512 MiB, 200 MiB, 8 GiB), and `dsh-media/bin` is the one **program** the pack writes - and +only after the bytes match the SHA-256 it pins. ## The profile is mostly links `$DSH_HOME/profiles/web/node_modules` holds one `link:` junction per bundle under -`packages/`, plus `.pnpm/` holding only `lock.yaml`; `pnpm-lock.yaml` contains -`link:` specs alone, with no registry resolution anywhere, and the base bundles -(`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`) resolve through the -installation fallback. **A profile install therefore needs no registry** - only the -installation closure and a pnpm to write the links. - -`$DSH_HOME/profiles/node_modules/` is a set of junctions (symlinks on macOS/Linux) -into the installation, rebuilt at every boot by `healProfilesModuleFallback` from an -anchor relative to the harness itself -(`const INSTALL_ANCHOR = fileURLToPath(new URL("../package.json", import.meta.url))`). -Wherever `@deepseek-ai/dsh` is run from *is* the installation, so vendoring the -harness into a distribution folder makes that folder the installation with no -harness change; today that anchor points into the npm cache below. - -## Outside both roots +`packages/`, plus `.pnpm/` holding only `lock.yaml`; `pnpm-lock.yaml` contains `link:` specs +alone, with no registry resolution anywhere, and the base bundles +(`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`) resolve through the installation +fallback. **A profile install therefore needs no registry** - only the installation closure +and a pnpm to write the links. + +`$DSH_HOME/profiles/node_modules/` is a set of junctions (symlinks on macOS/Linux) into the +installation, rebuilt at every boot by `healProfilesModuleFallback` from an anchor relative +to the harness itself (`const INSTALL_ANCHOR = fileURLToPath(new URL("../package.json", +import.meta.url))`). Wherever `@deepseek-ai/dsh` is run from *is* the installation, which is +why the anchor needs no configuration and today points into the npm cache below. + +## Outside the home | Location | Windows | macOS / Linux | Why | |---|---|---|---| -| the app's own npm cache | `\npm-cache` | `/npm-cache` | `npx` writes wherever `npm_config_cache` points, and a cache an ELEVATED run made unwritable is the measured `EPERM` that moved this out of the machine-wide directory | | npm / npx cache | `%LOCALAPPDATA%\npm-cache\_npx\` | `~/.npm/_npx/` | `npx` unpacks the installation here, and the profile's junctions point into it | +| a portable folder's cache | `\.vncode\npm-cache` | `/.vncode/npm-cache` | the cache follows a portable installation, so a run leaves the user's profile alone. An explicit `npm_config_cache` always wins | | pnpm store | `%LOCALAPPDATA%\pnpm\store\v3` | `~/Library/pnpm/store`, `~/.local/share/pnpm/store` | the store the profile was verified against (`node_modules/.modules.yaml`) | | pnpm itself | `/tools/pnpm/` | same | the installer bootstraps it when the system copy is too old | -Two are outside on purpose: the **Desktop** (resolved per request - Windows plain or +Two more are outside on purpose: the **Desktop** (resolved per request - Windows plain or OneDrive-redirected, `$XDG_DESKTOP_DIR`, the home folder last) for the `dsh-themes` -screenshot and `dsh-diagrams` exports, and **temp** (`os.tmpdir()`) for TikZ compiles -and `pdf_render`. +screenshot and `dsh-diagrams` exports, and **temp** (`os.tmpdir()`) for TikZ compiles and +`pdf_render`. ## Per OS, in one place @@ -179,9 +109,10 @@ and `pdf_render`. | npm cache root | `%LOCALAPPDATA%\npm-cache` | `~/.npm` | `~/.npm` | | pnpm store root | `%LOCALAPPDATA%\pnpm\store` | `~/Library/pnpm/store` | `~/.local/share/pnpm/store` | | link kind | directory junction | symlink | symlink | -| webview runtime | WebView2 | WKWebView | WebKitGTK 4.1 | +| the launcher's shell | PowerShell 5.1 or 7 (behind a `.bat` double-click) | POSIX `sh` | POSIX `sh` | ## The rule this page states -A distribution must be movable, and the only directories it may depend on outside -itself are the app's own root and the harness home - which is why the profile needs no -registry, and why `runtime/` is a distribution tree rather than a repository one. + +A distribution must be movable, and the only directories it may depend on outside itself are +the harness home and the npm cache. That is why the profile needs no registry, and why +unzipping a release anywhere is a working installation. diff --git a/docs/RELEASE.md b/docs/RELEASE.md index e2144c3..2c63a91 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -1,79 +1,68 @@ # Cutting a vncode release -A release is **two artefacts**, because the project is two things: - -| artefact | what it is | built | -|---|---|---| -| `vncode---.zip` / `.tar.gz` | the Rust app: the front door that installs the pack, takes the key and runs the web launcher. **One per OS** - the only per-OS artefact in the project | `release.yml`, one matrix leg each | -| `vncode-web-.tar.gz` | the node/JS half: `packages/`, `scripts/`, the pin and the docs. **The same bytes on every platform** | `release.yml`, once, on Linux | - -The web half is the product and it stands alone: `scripts/run-web.bat` / -`./scripts/run-web.sh` starts the harness and opens the tab with no `vncode` binary -anywhere on the machine. The app is a front door that calls it. That is why only the Rust -half is per-OS, and why one leg failing cannot withhold the other. +**A release is one artefact.** `vncode-.zip` is a `git archive` of the repository +at the tag, and it is the whole distribution: the pack, the launchers, the docs and the pin. +Nothing is compiled, so nothing is built per OS: unzipping the zip yields a working +installation on Windows, macOS and Linux alike, with no second archive and no ship list. ## What publishing a tag does `.github/workflows/release.yml`, on `v*` (or `workflow_dispatch` with an existing tag): -1. **gate** - calls `ci.yml`, the same workflow a pull request runs. Three OSes, clippy - with warnings denied, the tests, a release build, a 6 MB size ceiling, and a smoke run. - A red gate stops the release **before** a draft exists. -2. **prepare** - creates the Release as a **draft**. Nothing is visible while it is half - built. -3. **build** - the matrix: `windows-latest` (x86_64, static CRT so no redistributable is - needed), `ubuntu-22.04` (x86_64, for the glibc floor), `macos-latest` (arm64). Each leg - packages `vncode` + `README.md` + `LICENSE` and uploads it. -4. **web** - packs the pack, the launchers and the pin into `vncode-web-.tar.gz`, - after checking that `scripts/run-web.sh -Help` answers *with no app involved*. -5. **checksums** - waits for every upload, **re-downloads what was actually published**, - and writes `SHA256SUMS.txt`. A hash computed before the last upload is a lie. -6. **publish** - flips the draft. The release becomes visible only with every artefact and - its checksums attached. +1. **gate** - calls `ci.yml` through `workflow_call`, the same workflow a pull request + runs. One job, `ubuntu-latest`, a `node:22` container: `git` installed, then + `check-no-secrets.mjs` and `check-scripts.mjs`. A red gate stops the release **before** + anything is published. +2. **archive** - the tag itself is archived into `vncode-.zip` and attached. The + zip is the repository at the tag, not a file list somebody maintains, so it cannot fall + behind the tree. +3. **publish** - the release becomes visible with its one artefact attached. + +A tag is the only thing that publishes. There is no separate packaging step to remember, +and nothing that can fail for one platform while another succeeds. ## Cutting one by hand The workflow is the only ritual that ships. If it is unavailable, the same steps run locally: -```powershell +```sh git status --porcelain # expect: empty -Get-ChildItem scripts/checks/*.mjs | ForEach-Object { node $_.FullName } -cargo build --release --locked --manifest-path app/Cargo.toml +node scripts/checks/check-no-secrets.mjs +node scripts/checks/check-scripts.mjs ``` -**Smoke it as a user would.** From a checkout, on each OS: +**Smoke it as a user would.** From the checkout, on each OS: -```powershell -scripts\run-desktop.bat status # the pin, the home, the pack, the key, the launcher -scripts\run-desktop.bat # install if needed, key if needed, then run-web +```sh +./scripts/setup/install.sh # once, against the home in use +./scripts/run-web.sh # start the harness and open the tab ``` -`status` must name the home and the launcher and start nothing. `start` must reach a -served page in a browser, and Ctrl+C must stop it. On a machine with no pack installed, -the same run installs it first and says so. +The install must add the bundles and change nothing else. The run must reach a served page +in a browser, print the home it chose, and Ctrl+C must stop it. On Windows, the same two +steps with `scripts\setup\install.bat` and `scripts\run-web.bat`. Then tag and push; the workflow does the rest: -```powershell -$v = node -p "require('./package.json').version" +```sh +v=$(node -p "require('./package.json').version") git add -A; git commit -m "release: vncode $v" git tag -a "v$v" -m "vncode $v"; git push origin main "v$v" ``` -## What NOT to do - -- **Do not label a binary for an OS it was not built on.** A renamed `.exe` is not a macOS - or Linux binary; each leg runs on its own runner. -- **Do not publish the web half per platform.** It has no native modules of its own - one - artefact, three OSes, the same bytes. -- **Do not re-cut a tag** once an archive has been handed to somebody. -- **Do not attach an artefact after `checksums` has run** - `SHA256SUMS.txt` would no - longer describe the release. Re-run the workflow instead; it re-hashes what is there. +The zip is cut from the tag itself, so a dirty tree cannot leak into a release. -Signing is not wired up yet: an Authenticode or Developer ID certificate would cover the -exact bytes of each binary, and the honest interim is the `SHA256SUMS.txt` above plus a -note in the release notes (BUILD.md has the details). +## What NOT to do -[BUILD.md](BUILD.md) is the build itself; [DEPLOY.md](DEPLOY.md) is what a distribution -promises; [scripts/checks/README.md](../scripts/checks/README.md) lists every check. +- **Do not add a second artefact, for any platform.** The same files run everywhere, so a + second archive is only a second thing to keep in step. +- **Do not hand-edit or re-zip the archive.** It is `git archive` of the tag; a release that + does not match its tag is not the release. +- **Do not re-cut a tag** once its archive has been handed to somebody. +- **Do not attach an artefact after the release is published** - regenerate it from the tag + instead. + +[BUILD.md](BUILD.md) is how it runs and how a change is checked; [DEPLOY.md](DEPLOY.md) is +what a distribution promises; [scripts/checks/README.md](../scripts/checks/README.md) lists +every check. diff --git a/docs/RUST-PORT.md b/docs/RUST-PORT.md deleted file mode 100644 index 8c28635..0000000 --- a/docs/RUST-PORT.md +++ /dev/null @@ -1,204 +0,0 @@ -# RUST-PORT.md — vncode's core, ported from the harness line - -**Status: plan. No crate ships, no row is wired, `app/` is untouched.** - -vncode's core is Rust. The DeepSeek Harness is the *source* of that core, not a -dependency of it: the pinned line stays the behavioural reference, `port/` holds -the implementation, and what ships carries vncode's own name and brand. The -upstream license is MIT, so the derivation is allowed; its notice is preserved -and disclosed in `THIRD-PARTY-NOTICES.md`, and its marks are not ours to use. - -Everything below is measured from the installed `0.2.0-rc.2` line unless it says -otherwise, and every number is the reason a rule exists. - -## The question this document answers first - -*Can a pure-Rust vncode load the same JavaScript plugins as the harness?* - -**Not the same ones, and not the same way.** Not because Rust cannot host a -scripting engine, but because the harness is not a JavaScript application — it -is a **Node application that treats the Node platform as a capability**. Measured -from the installed tree: - -| Node built-in | Who needs it | What "porting it" actually means | -|---|---|---| -| `node:vm` | `dsh-cordis-host-runner` (a dynamic package's host half evaluates in a fresh realm), `dsh-workflow-ptc` (the workflow guest) | embed a JS engine with realm isolation and code-from-string | -| `node:sqlite` | `dsh-session-query-sqlite` (full-text session search; import deferred, opt-in in the web profile) | a SQL engine | -| `node:zlib` zstd | `dsh-session-persistence-jsonl` (`createZstdCompress`, `zstdDecompressSync`) | zstd in Rust is easy; Node's *streaming* semantics are the contract | -| `node:worker_threads` | session persistence, `dsh-app-boot`, `libreoffice-kit` | threads, transferables, environment data | -| `node:module` `stripTypeScriptTypes` | `dsh-ptc-runtime-node` | a TypeScript type stripper at runtime | -| `node:child_process`, `node:net`, `node:readline`, `node:os`, `node:fs` | ~40 packages | the platform itself | - -A Rust process that loads those packages must first *be* Node. Deno and Bun are -that project, they are person-decades old, and neither is a side quest. So the -goal is stated the only way it can be met. - -## Three paths, one decision - -The port is not one road with a fork further on. It is three different products, -and the choice happens now because it decides whether the packages in this -repository have a future. - -| Path | Container owned by | What you get | What it costs | Verdict | -|---|---|---|---|---| -| **A. Hosted core** | Node + Cordis (upstream) | every upstream package and every package in this pack keeps working; Rust wins land underneath | still ships Node and its startup | **start here** (P1–P6) | -| **B. Native host** | vncode | one binary, vncode's own protocol, vncode's own UI, no Node | upstream packages do not load; this pack's *surfaces* are rebuilt | **the destination** (P7, after a gate) | -| **C. Compatible native host** | vncode, reproducing Cordis + Typert | upstream's 288 packages and this pack run unmodified on a Rust host | reimplement the plugin container, scopes, effects, HMR, realms, patch layering, and the descriptor codegen pipeline in Rust | **not a plan** | - -Path C is the one people assume happens by itself ("port enough modules and one -day it's native"). It does not: A and B share the *crates*, not the *contract*. -C is a research bet, and it is the most expensive item in this document by an -order of magnitude. - -Path B is what makes the port finishable. As a fork with its own brand and its -own UI, vncode does not owe anyone wire compatibility — it owes its users a fast, -safe core. That is the freedom that turns a years-long faithful port into a -scoped product. - -## The boundary rule - -**Rust owns leaves behind seams. Rust never owns the container.** - -A thing may be ported when all three hold: - -1. it is reachable through exactly one seam (Service Definition / Provider / - Consumer, the shape `docs/architecture.md` describes upstream); -2. its inputs and outputs are JSON, bytes, files, or processes — no `Context`, - no scope, no effect unwinding; -3. a fixture can pin its behaviour, so the TS implementation and the Rust one can - be compared on the same input. - -Anything failing (1) or (2) stays TypeScript until path B replaces it wholesale. - -Never ported, under any path: the Cordis container (`plugins`, `services`, -`scopes`, `effects`, realm `isolate`, HMR), `plugin-manager` (pnpm orchestration), -the client bundles, the Typert *generator*, Electron, telemetry, translations. - -## Why "the TS tree keeps moving underneath you" only works with fixtures - -Porting behind a seam means upstream keeps shipping while you build. That is the -point, and it is also the failure mode: without a fixture suite you cannot tell a -win from a silent behaviour change, and the port starts lying. - -So the rule: **no crate is accepted until its fixture suite is green against the -pinned line.** `port/contracts/` pins the seam contract (the `.d.ts` files and -the subsystem page), `port/fixtures/` pins behaviour, both by version and sha. -Upgrades to the pinned line are deliberate events that re-run every fixture, not -a background drift. This is the only discipline that makes a 60-seam port -tractable for one person. - -## `port/` — the second workspace - -`port/` is a **separate cargo workspace** from `app/`, and it stays separate: - -- `app/Cargo.toml` is the front door: three crates, std + `serde_json` + - `rpassword`, a **6 MB** CI size ceiling. Nothing from `port/` is linked into - it, and `check-shell.mjs` keeps proving that. -- `port/` has its own lockfile, its own CI job (added at P3), and its own - dependency policy. A ported crate may use crates.io; the app may not. -- `target/` is already ignored at the repository root, so `port/target/` costs no - new `.gitignore` rule. - -The tree, and what may exist at each phase: - -``` -port/ - README.md now the folder's own rules - contracts/ P1 vendored .d.ts + seam notes, pinned by sha - fixtures/ P1 input + expected output captured from the pinned line - diff/ P1 the harness that runs TS vs Rust on one fixture set - Cargo.toml P2 the workspace (deliberately absent until then) - crates/ - vn-session/ P2 JSONL v0/v1 codec, generations, zstd, migrations - vn-proj/ P2 projection folds (turnBoundary, inbox, todo, stats) - vn-native/ P3 the ONE N-API surface (napi-rs cdylib) - vn-sandbox/ P4 landlock · appcontainer · seatbelt · policy resolution - vn-exec/ P4 subprocess, pty, job objects, ConfinedArgv - vn-fs/ P5 paths, realpath policy, atomic write, win32 semantics - vn-search/ P5 glob, grep, diff, patch, hash - vn-llm/ P6 transport, SSE, retry, token meter - vn-host/ P7 only the native binary — exists only if B is chosen - tools are NOT here: maintainer scripts stay in `scripts/tools/`. -``` - -## Phases, with a gate and a kill criterion each - -| # | Deliverable | Done when | Stop if | -|---|---|---|---| -| **P0** | instrumentation: boot-phase timings, session-load time on the longest real session, RSS, grep latency | the numbers exist as a page | no phase exceeds 10% of user-visible time → port for safety only, drop the performance claims | -| **P1** | `contracts/` + `fixtures/` + `diff/` | one seam's contract is pinned and the diff harness runs the TS implementation against itself | fixtures cannot be captured deterministically → fix that before writing Rust | -| **P2** | `vn-session` + `vn-proj`, **pure Rust, no binding** | every fixture green; load time measured against Node on the same files | the codec cannot express a generation/migration edge → the seam is wrong, re-read it | -| **P3** | `vn-native`: the first N-API surface, behind a row that is **disabled by default** | the four conditions below hold, and `run-web.*` on a machine without the addon is unchanged | a missing `.node` cannot fail open → do not wire it | -| **P4** | `vn-sandbox` + `vn-exec` | confinement is fail-closed and tested per platform; the C Landlock launcher's contract is met | Windows Job-object/AppContainer semantics cannot be made to fail closed → keep the TS path | -| **P5** | `vn-fs` + `vn-search` | path policy identical on NTFS (ADS, `\\?\`, junctions, case) as on POSIX | a path case cannot be pinned by fixture → do not ship that path form | -| **P6** | `vn-llm` transport (own the whole request) | streaming and cancellation measured, not asserted | per-chunk crossing erases the win → keep Node's HTTP | -| **P7** | `vn-host` — **a separate decision, not a scheduled phase** | path B is chosen, with its own UI and protocol | the answer to "who rebuilds every surface" is nobody → stay on A | - -## P3 — the four conditions before anything is wired - -Wiring Rust into the harness is the last step of a phase, never the first, and it -holds only while all four are true: - -1. **Lazy and fail-open.** A missing or failing `.node` falls back to the JS path. - A machine with no vncode must still run the web — this repository's rule 1, - and `check-shell.mjs` drives it. -2. **ESM-safe.** The harness is `"type": "module"` throughout; a CommonJS native - module is reached through `createRequire(import.meta.url)`. -3. **Coarse crossings.** Expose `readSession(dir) -> FoldedState`, never - `parseEvent`. Per-event or per-token crossings erase every win the port bought. -4. **Per-platform packaging.** Stable N-API, prebuilt, `optionalDependencies` — - the shape upstream already uses for its two C primitives - (`native/system`: `flock.c`, `main.c`, no build at install time). Consumer - installs must never compile. - -## What the port is expected to buy, ranked - -The order below is the port order, and each row names the measurement that keeps -it honest. - -| # | Port | Win | Risk | -|---|---|---|---| -| 1 | session log + projections | session load on long sessions; the format becomes the interop point between vncode and the harness | low — pure data | -| 2 | sandbox + exec | the only real *safety* win: fail-closed confinement, Job objects, ConPTY | medium — per-platform semantics | -| 3 | fs | security and correctness of every path the agent touches | medium — NTFS traps | -| 4 | search / diff / patch / hash | throughput on big trees, coarse calls | low | -| 5 | llm transport | streaming, backpressure, cancellation | medium — only whole-request | -| — | JSON-schema validation of tool args | *none worth taking*: the error text is model-facing, so changing it changes model behaviour | — | - -## What this does not buy - -Not turn latency. A turn is dominated by model time and tool spawns, not by JS -execution. The honest claim is **startup, memory, long-session load, search, and -enforceable confinement** — not "the agent is faster". A port justified by "the -agent will be quicker" would be justified wrongly. - -Not "safe because it is Rust". A rewrite adds new parsers and new path handling, -and those are where the bugs go. Confinement and path code are ported **first** -(P4, P5) precisely because they are the sensitive ones, and each lands with its -fixtures, not after them. - -## Cost, stated plainly - -Host-side TypeScript is **~11.7 MB ≈ 325k lines** (36 chars/line measured). A -faithful solo port at this repository's standard is years, and the pinned line -will break compatibility many times inside that window. That number is why the -plan is a ranked subset rather than a translation, and why path B — a smaller -product with its own scope — is the only version of "pure Rust" that finishes. - -## Open decisions (not decidable by an agent) - -1. **UI and protocol ownership.** Path B means vncode's own UI and its own wire. - That is the choice that makes the port finishable, and it is the one that - retires this pack's surfaces as they are. -2. **Windows-first or Linux-first** for P4. This repository's users are on - Windows; the confinement primitives are better documented on Linux. -3. **`AGENTS.md`.** `port/` is not yet in the layout section. Adding it there is - a rulebook change, so it waits for the owner's decision, not this document. - -## Non-goals - -- A Rust client UI. The browser keeps the UI, as this repository's rule 1 says. -- Wire compatibility with the upstream client. Optional, and it is what path C - costs. -- Vendoring the harness. `port/` is a derivation with its own versions; upstream's - source stays upstream's. diff --git a/package.json b/package.json index 4c1b591..5a55e6f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "vncode", - "version": "0.1.2", + "version": "0.1.3", "private": true, "description": "Personal plugin pack for DeepSeek Harness (Windows/MacOS/Linux). Installs into the raw web/CLI profile only (npx @deepseek-ai/dsh web).", "license": "AGPL-3.0-only", diff --git a/packages/dsh-themes/lib/client.js b/packages/dsh-themes/lib/client.js index 882c545..912ce3b 100644 --- a/packages/dsh-themes/lib/client.js +++ b/packages/dsh-themes/lib/client.js @@ -77,9 +77,8 @@ * magnifier button that drops a small menu holding the CURRENT level and two * entries, `Zoom in` and `Zoom out` - the same act as the browser's own * Ctrl+ / Ctrl- (and Ctrl+wheel) PAGE zoom, which is why the control exists: - * a Chrome tab has that keyboard gesture, and the native window the desktop - * launcher (`run-desktop.bat`, a Tauri shell over the very same `dsh web`) - * opens does not. + * a Chrome tab has that keyboard gesture, but nothing that shows the level in + * force, and the header control puts both in reach of the mouse. * * HOW IT ZOOMS. `zoom` on the document element - one inline declaration on * , removed again at 100% so a page nobody has zoomed is byte-for-byte @@ -1731,9 +1730,9 @@ html[data-dsh-screenshot] [role=tooltip]{visibility:hidden} MARK_ICON + '") center/contain no-repeat}', // The name: the pack's own product text, in the REPOSITORY'S OWN - // spelling - lowercase and hyphenated, the way the repo, the npm - // package and `run-desktop.bat` name it - not the title-case form the - // draw-strings used through alpha.13. + // spelling - lowercase and hyphenated, the way the repo and the npm + // package name it - not the title-case form the draw-strings used + // through alpha.13. 'html .hHd-Xa_root .hHd-Xa_brandName::before{content:"vncode"}', // ...wearing the CHAT TITLE's type, not the shipped brand name's. The // conversation's own title - the current crumb in the header strip this @@ -3318,11 +3317,10 @@ html[data-dsh-screenshot] [role=tooltip]{visibility:hidden} // The page-zoom control (alpha.15). // // WHAT IT IS FOR. A Chrome tab zooms the page itself with Ctrl+ / Ctrl- and - // Ctrl+wheel - the BROWSER's own page zoom, which no page can invoke. The - // native window the desktop launcher opens (`run-desktop.bat`, a Tauri shell - // over the very same `dsh web`) has no such gesture at all. So the pack - // draws the gesture: one magnifier button in the header that drops the level - // in force and the two steps, `+` and `-`. + // Ctrl+wheel - the BROWSER's own page zoom, which no page can invoke - and + // the keyboard gesture leaves no readout on the page. So the pack draws one: + // a magnifier button in the header that drops the level in force and the two + // steps, `+` and `-`. // // HOW A PAGE CAN ZOOM ITSELF. `zoom` on the document element. It is // engine-neutral CSS - Chromium and WebKit have carried it for years, diff --git a/port/README.md b/port/README.md deleted file mode 100644 index 3dd9a51..0000000 --- a/port/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# port/ — vncode's core in Rust - -The Rust side of vncode, ported from the pinned harness line. The plan, the -boundary rule and the phase gates live in [`docs/RUST-PORT.md`](../docs/RUST-PORT.md); -this page is only what is true about the folder. - -**Nothing here ships yet.** There is no `Cargo.toml` on purpose: `cargo` at this -directory does not become a second workspace until P2, and until then the folder -holds the plan's artifacts only. - -## Rules that hold here - -- **A separate workspace from `app/`.** `app/` is the front door — three crates, - std plus `serde_json` and `rpassword`, a 6 MB CI size ceiling. Nothing from - `port/` is linked into it, and a ported crate may use crates.io while the app - may not. -- **Contracts before code.** A crate is accepted only when `contracts/` pins the - seam it implements (the `.d.ts` and the subsystem page, by version and sha) and - `fixtures/` pins its behaviour. -- **Fixtures before faith.** `diff/` runs the TypeScript implementation and the - Rust one over the same inputs and diffs the output. A port without a green - fixture suite is a guess, and this folder does not keep guesses. -- **Leaves, never the container.** Rust implements providers behind seams. The - Cordis container, the plugin manager, the client bundles and the descriptor - generator are never ported here. -- **`target/` needs no ignore rule.** The repository root already ignores it. -- **No maintainer scripts.** Those stay in `scripts/tools/`; this folder holds - port artifacts and crates. - -## What exists - -| Path | State | -|---|---| -| `README.md` | this page | -| `contracts/` | P1 — not created yet | -| `fixtures/` | P1 — not created yet | -| `diff/` | P1 — not created yet | -| `Cargo.toml` | P2 — deliberately absent | - -The crate map, the ranked port order and the four conditions for ever wiring a -`.node` into the harness are all in [`docs/RUST-PORT.md`](../docs/RUST-PORT.md). diff --git a/scripts/checks/README.md b/scripts/checks/README.md index 54c7113..15092fe 100644 --- a/scripts/checks/README.md +++ b/scripts/checks/README.md @@ -2,10 +2,11 @@ Standalone verification for everything this pack ships. No check needs a running harness, none is part of the installers, and all of them are written in Node and -run the same way on Windows, macOS and Linux. Two assertions reach past Node on -purpose and skip loudly when the tool is missing: `check-shell.mjs` needs `cargo`, -and `check-client-bundles.mjs` drives the vendored-fork re-sync through PowerShell. -Run the one that owns the area you touched, before you claim a fix. +run the same way on Windows, macOS and Linux. A few reach past Node on purpose and +skip loudly when the tool is missing: `check-client-bundles.mjs` drives the +vendored-fork re-sync through PowerShell, `check-shader-examples.mjs` and +`check-browser-node.mjs` need a real browser, and `check-media-node.mjs` needs +ffmpeg. Run the one that owns the area you touched, before you claim a fix. ```sh node scripts/checks/check-no-secrets.mjs # before anything is pushed @@ -18,7 +19,6 @@ node scripts/checks/check-skill-examples.mjs # every fenced example in the sh node scripts/checks/check-shader-examples.mjs # every fenced GLSL in the shader skills, COMPILED node scripts/checks/check-media-examples.mjs # every media/PDF example, shaped and really RUN node scripts/checks/check-browser-node.mjs # dsh-browser: the host renderer and its policy -node scripts/checks/check-shell.mjs # the app, DRIVEN: verbs, the bridge, the child env DSH_CHECK_LAUNCH=1 node scripts/checks/check-node-routes.mjs # also opens a real directory picker ``` @@ -31,14 +31,13 @@ Windows PowerShell: `$env:DSH_CHECK_LAUNCH='1'; node scripts/checks/check-node-r | `check-no-secrets.mjs` | nothing credential-shaped would be staged by `git add -A`; the `.gitignore` credential rules are present; the scanner fires on a synthetic key, hides the value and stays quiet on clean text | | `check-client-bundles.mjs` | every browser half loads through the real module table (`window.__ModuleLoader__.load`), activates against a stub cordis context, and is rendered/driven with a **real React runtime**; the exported `__internals` pure halves are driven directly (e.g. the audio/image byte decode in every shape a carrier could use); and it runs `scripts/tools/sync-vendored.ps1 -Check`, so each generated fork is proved to be what its patch list still produces (a host with no PowerShell skips that one assertion loudly) | | `check-node-routes.mjs` | every Node route and tool of every host half, the git routes against a real repository, the skills registry, the manifest ⇄ `package.json` agreement, and the master's pack-wide row patches | -| `check-scripts.mjs` | the `scripts/` layout (`run-web.*` and `run-desktop.*` at the top, everything else in `console/`, `setup/`, `tools/`, `checks/`), the console contract every Windows entry point must hold, **`setup/install.bat -Help` and `setup/uninstall.bat -Help` really run** with the console variables cleared the way the app clears them (they must print their usage, exit 0, and change nothing), and that the two release workflows exist and name three OSes + a separate `vncode-web` artefact | +| `check-scripts.mjs` | the `scripts/` layout (`run-web.*` at the top, everything else in `console/`, `setup/`, `tools/`, `checks/`), the console contract every Windows entry point must hold, that both `run-web` workers join the folder's own home when it is portable, and the entry points **really run in their `-Help` form**: `run-web.* -Help` must print its usage without starting the harness, and `setup/install.bat -Help` / `setup/uninstall.bat -Help` must print theirs, exit 0 and change nothing. It also asserts the two workflows exist, `ci.yml` callable through `workflow_call` and `release.yml` gating on it and publishing one artefact | | `check-media-node.mjs` | `dsh-media`'s pin against a **synthetic archive** built and served over loopback (download, hash verification, mismatch refusal, atomic install, resolution order), plus the ffmpeg-dependent half, which skips loudly without ffmpeg | | `check-pdf-node.mjs` | the five `pdf_*` tools and the PDF routes against documents the check builds itself, including the engine's buffer semantics | | `check-skill-examples.mjs` | every fenced example in the shipped skills parses or compiles (Mermaid, TikZ) | | `check-shader-examples.mjs` | every fenced **GLSL** example in `dsh-shaders`' five skills is COMPILED by a real headless browser, with vertex shaders recognised and a deliberately-broken example marked `no-check`; skips loudly on a host with no browser | | `check-media-examples.mjs` | every media/PDF example is a well-formed tool call and, where this host can run one, actually runs | | `check-browser-node.mjs` | `dsh-browser`'s host half: the disposable sandboxed renderer and the fetch policy in front of it | -| `check-shell.mjs` | the app, **driven rather than read**: `-Version` and `-Help` answer; `-Mode embed` - the flag the deleted web view used to answer - is refused BY NAME; the binary is kept under a size ceiling a GUI stack cannot sneak past; and `start` is run against a **throwaway tree with stub scripts**, so the whole bridge is exercised without starting node: a home with no pack makes it run `scripts/setup/install.*` first, the launcher is handed `-DshHome` and, on Windows, `-NoTerminal`, both children's own environments are read back to prove `DSH_HOME` was composed and that the app's root and the console markers were REMOVED, no key file is written when there is no terminal to ask at, and `status` names the same home. It also proves `scripts/run-web.* -Help` answers with nothing but the web half present. Fixtures live under `.scratch/`, never in a temp directory the host may deny, and it runs `cargo test --workspace` with a scratch root it controls | ## The checks that live inside a package @@ -80,9 +79,9 @@ run was checked is always stated with how deeply: `t0-structure` (always), 4. **Never weaken a check to make a change fit.** Fix the code, or change the check deliberately and say why in the commit. -**CI does not run these.** They are run by hand, because most of them need a browser, a -SuperCollider, ffmpeg or TeX that a runner does not have. `.github/workflows/ci.yml` runs -what a runner *can* own - clippy with warnings denied, the workspace tests, a release build -and the size budget - and `release.yml` calls that same workflow as its gate, so a tag is -checked on all three OSes before anything is published. `check-scripts.mjs` asserts both -workflows exist, so a deleted release pipeline cannot come back silently either. +**CI runs two of them.** `.github/workflows/ci.yml` is one job on `ubuntu-latest` in a +`node:22` container - it installs `git` and runs `check-no-secrets.mjs` and +`check-scripts.mjs`, the two that need nothing a bare container lacks. The rest are run by +hand, because most of them need a browser, a SuperCollider, ffmpeg or a TeX engine that a +runner does not have; `release.yml` calls that same workflow as its gate, so a tag is +checked before anything is published. diff --git a/scripts/checks/check-no-secrets.mjs b/scripts/checks/check-no-secrets.mjs index 26c1c18..86850ed 100644 --- a/scripts/checks/check-no-secrets.mjs +++ b/scripts/checks/check-no-secrets.mjs @@ -128,13 +128,10 @@ export const RULES = [ * with the reason, so the check stays honest instead of being loosened for * everybody. Keep this list short and justified; an entry without a reason is a * bug, and "the check is inconvenient" is not a reason: change the fixture so it - * is not key-shaped instead (see `keystate.rs`, whose test value carries a `/` - * precisely so it cannot be confused with a credential). + * is not key-shaped instead - a value that carries a `/` or a word cannot be + * confused with a credential. * * Currently empty, and that is the goal. - * - * { file: 'app/crates/vn-shell-core/src/readyline.rs', rule: 'launch-token-in-url', - * reason: 'the redaction fixture; its token is under the 16-char threshold' } */ export const ALLOWLIST = [] diff --git a/scripts/checks/check-scripts.mjs b/scripts/checks/check-scripts.mjs index 0a12d19..ccd2b0e 100644 --- a/scripts/checks/check-scripts.mjs +++ b/scripts/checks/check-scripts.mjs @@ -10,25 +10,26 @@ // // What this proves: // -// 1. THE LAYOUT. `scripts/` holds the two entry points a person runs (run-web, -// run-desktop), each with the worker or twin it needs, and the three folders: -// `console/` (the shared console layer), `setup/` (install and uninstall) and -// `tools/` (maintainer-only). A file at the top level that is none of those is -// reported: the point of the layout is that a reader can tell "what I run" +// 1. THE LAYOUT. `scripts/` holds the ONE entry point a person runs, `run-web`, in its +// three host spellings: the .bat double-click wrapper, the .ps1 worker beside it, +// and the POSIX .sh that does the whole job itself. Beside them are the four +// folders: `console/` (the shared console layer), `setup/` (install and uninstall), +// `tools/` (maintainer-only) and `checks/`. A file at the top level that is none of +// those is reported: the point of the layout is that a reader can tell "what I run" // from "what it uses" at a glance. // 2. THE CONSOLE CONTRACT, still enforced because it is still load-bearing: every // Windows entry point guards `VNCODE_ARGV` against a relaunch, calls the ONE // console layer, forwards `VNCODE_ARGS` and never `%*`, and `adapt.cmd` does // not `setlocal` (its decisions must stay visible to its caller). -// 3. THE ENTRY POINTS REALLY RUN. `setup/install.bat -Help` and -// `setup/uninstall.bat -Help` are DRIVEN, with the console variables cleared -// exactly as the app clears them, and must print the worker's usage and exit -// 0. That is the whole path the panel's buttons take: locate, spawn through -// the console layer, and read an exit code - and `-Help` installs nothing. +// 3. THE ENTRY POINTS REALLY RUN. `run-web.bat -Help` (or `run-web.sh -Help` on a POSIX +// host), `setup/install.bat -Help` and `setup/uninstall.bat -Help` are DRIVEN, with +// the console variables cleared exactly as a fresh shell has them, and must print the +// script's own usage and exit 0. That covers both things a person does by hand - +// starting the harness and installing the pack - and `-Help` does neither. // 4. THE TWO WORKFLOWS. `.github/workflows/` must exist, and must do the one job CI is -// for here: `ci.yml` callable, `release.yml` building the Rust app on Windows, Linux -// and macOS and publishing the node/JS half as its own artefact. CI was deleted once -// on purpose; it is back for the release, and this is what keeps it honest. +// for here: `ci.yml` callable and running the pure-node checks in a Node container, +// `release.yml` publishing ONE artefact - a zip of this repository. CI was deleted +// once on purpose; it is back for the release, and this is what keeps it honest. // // Run: node scripts/checks/check-scripts.mjs // POSIX entry points are checked for shape only; driving them needs a POSIX host, @@ -55,13 +56,7 @@ const read = (relative) => { // --------------------------------------------------------------------------- // 1. The layout // --------------------------------------------------------------------------- -const TOP_LEVEL_FILES = [ - 'run-web.bat', - 'run-web.ps1', - 'run-web.sh', - 'run-desktop.bat', - 'run-desktop.sh', -] +const TOP_LEVEL_FILES = ['run-web.bat', 'run-web.ps1', 'run-web.sh'] const TOP_LEVEL_FOLDERS = ['checks', 'console', 'setup', 'tools'] function checkLayout() { @@ -85,7 +80,7 @@ function checkLayout() { for (const name of ['install-all.ps1', 'install-all.sh', 'uninstall-all.ps1', 'uninstall-all.sh']) { if (!fs.existsSync(path.join(scripts, 'setup', name))) fail(`scripts/setup/${name} is missing`) } - console.log('check-scripts: the layout - two entry points, four folders') + console.log('check-scripts: the layout - one entry point, four folders') } // --------------------------------------------------------------------------- @@ -118,7 +113,7 @@ function checkEntryPoint(relative) { } function checkConsoleContract() { - for (const name of ['run-web.bat', 'run-desktop.bat']) checkEntryPoint(`scripts/${name}`) + checkEntryPoint('scripts/run-web.bat') for (const name of ['install.bat', 'uninstall.bat']) checkEntryPoint(`scripts/setup/${name}`) const adapt = read('scripts/console/adapt.cmd') @@ -147,16 +142,15 @@ function checkConsoleContract() { // 2b. The portable root: ONE rule, in three places // --------------------------------------------------------------------------- /** - * `run-web` and `run-desktop` must start the SAME home. + * Both `run-web` workers must join the folder's own home when it is portable. * - * A folder that is a portable installation keeps everything inside itself, and the panel - * has always used it; `run-web` used `~/.dsh`, so on a real machine the panel reported 24 - * bundles while `run-web` started a different home. The rule is two facts - the `PORTABLE` - * marker, or a home already inside the root - and it is implemented three times (the - * shell's `appdata::portable_root` in Rust, and once per launcher worker), because a - * launcher cannot call into the app. Three copies of one rule drift unless something - * reads them, and this is that something: both workers must test the marker AND the - * `home` folder, and must send `DSH_HOME` into the root's own home. + * A folder that is a portable installation keeps everything inside itself - the pack, the + * sessions and the key - so nothing lands in the user's profile. The rule is two facts: + * the `PORTABLE` marker, or a home already inside the root. It is implemented twice, once + * per launcher worker, because the Windows half and the POSIX half cannot call into each + * other. Two copies of one rule drift unless something reads them, and this is that + * something: both workers must test the marker AND the `home` folder, and must export + * `DSH_HOME` into the root's own home. */ function checkPortableRootRule() { for (const relative of ['scripts/run-web.ps1', 'scripts/run-web.sh']) { @@ -240,17 +234,67 @@ function checkWindowsEntryPoints() { console.log('check-scripts: install.bat and uninstall.bat answer -Help without touching anything') } +// --------------------------------------------------------------------------- +// 3b. The launcher answers -Help without starting anything +// --------------------------------------------------------------------------- +/** + * `run-web` is the only entry point, and asking it a question must not spawn `npx`, bind a + * port or open a tab: the answer comes from the script's own argument parser. A launch + * nobody can check by hand on every host is a launch that breaks quietly. + * + * The Windows entry is driven through cmd as a double-click would drive it, with + * -NoTerminal so `adapt.cmd` does not hand the run to Windows Terminal (which would exit 0 + * having printed nothing); the POSIX twin is driven with `sh`, and says loudly when the + * host has none. + */ +function checkRunWebHelp() { + const windows = process.platform === 'win32' + const relative = windows ? 'scripts/run-web.bat' : 'scripts/run-web.sh' + const needle = windows ? 'Usage: scripts\\run-web.bat [flags]' : 'Usage: sh scripts/run-web.sh' + const run = windows + ? spawnSync('cmd', ['/c', path.join(scripts, 'run-web.bat'), '-NoTerminal', '-NoPause', '-Help'], { + cwd: repo, + encoding: 'utf8', + env: clearedEnvironment(), + // A -Help that starts the harness instead of answering would never exit, so the + // wait is bounded: the failure is then a timeout with a name, not a hung check. + timeout: 60000, + }) + : spawnSync('sh', [path.join(scripts, 'run-web.sh'), '-Help'], { + cwd: repo, + encoding: 'utf8', + env: clearedEnvironment(), + timeout: 60000, + }) + if (run.error) { + notes.push(`${relative} -Help could not be driven here (${run.error.code ?? run.error.message})`) + return + } + const output = `${run.stdout ?? ''}${run.stderr ?? ''}` + if (run.status !== 0) fail(`${relative} -Help exited ${run.status}`) + if (!output.includes(needle)) { + fail(`${relative} -Help did not print its usage (${needle}) - it started something else`) + } + // A help request that reached the harness would name the pin. It must not. + if (output.includes('Pinned dsh version')) { + fail(`${relative} -Help started the launcher instead of answering`) + } + console.log(`check-scripts: ${relative} answers -Help without starting the harness`) +} + // --------------------------------------------------------------------------- // 4. The two workflows, and what they promise // --------------------------------------------------------------------------- // CI was once deleted on purpose ("the checks are run by hand"). It is back for ONE job: -// building the Rust app on the three operating systems and attaching the artefacts to a -// tag. The assertion is inverted rather than dropped, because "CI exists" and "CI builds -// what we ship" are different claims and only the second is worth having. +// proving a tree that is about to be tagged, and attaching the zip a tag publishes. The +// assertion is inverted rather than dropped, because "CI exists" and "CI proves what we +// ship" are different claims and only the second is worth having. Half of this is +// negative on purpose: there is no compiler in this repository any more, so a workflow +// that reaches for one is exactly the change this is here to catch. function checkCi() { const workflows = path.join(repo, '.github', 'workflows') if (!fs.existsSync(workflows)) { - fail('.github/workflows is missing - the release builds the app for three OSes (docs/RELEASE.md)') + fail('.github/workflows is missing - the release gates on ci.yml and publishes the zip (docs/RELEASE.md)') return } const ci = path.join(workflows, 'ci.yml') @@ -263,21 +307,37 @@ function checkCi() { if (!text.includes('workflow_call')) { fail('ci.yml is not callable - release.yml must run the same checks rather than a copy') } + // The two checks a boundary run is for. A workflow that runs neither is a badge. + for (const check of ['check-no-secrets.mjs', 'check-scripts.mjs']) { + if (!text.includes(check)) fail(`ci.yml does not run ${check}`) + } + // One runtime, and the one the pack declares. The container is what makes "one runner + // covers every platform" true rather than assumed: there is nothing per-OS to build. + if (!/container:\s*node:22/.test(text)) { + fail('ci.yml does not run in a node:22 container, so the runtime it proves is not the one package.json declares') + } + if (/cargo|rustup|clippy/.test(text)) { + fail('ci.yml reaches for a Rust toolchain - this repository has no native code to build') + } } if (fs.existsSync(release)) { const text = fs.readFileSync(release, 'utf8') - // The three operating systems, by name: this is what "the release is built on three - // platforms" means, and a matrix that quietly lost one is a release that does not run. - for (const os of ['windows-latest', 'ubuntu-22.04', 'macos-latest']) { - if (!text.includes(os)) fail(`release.yml does not build on ${os}`) + if (!text.includes('uses: ./.github/workflows/ci.yml')) { + fail('release.yml does not gate on ci.yml') + } + // ONE artefact, and it is the repository itself: the pack, the launchers, the checks + // and the docs. A second, per-OS file is the shape this release replaced. + if (!text.includes('NAME="${STEM}-${VERSION}"')) { + fail('release.yml does not name the artefact -, so the release is not the repo itself') + } + if (!text.includes('git archive')) { + fail('release.yml does not build the archive with git archive, so the zip can drift from the tree') } - // The node/JS half is a SEPARATE artefact, built once: it is the same bytes on every - // platform, and `scripts/run-web.*` must keep working without the app. - if (!text.includes('vncode-web')) { - fail('release.yml does not publish the node/JS half as its own artefact') + if (/cargo|rustup|matrix\.target|vncode\.exe/.test(text)) { + fail('release.yml still builds or names a per-OS binary') } } - console.log('check-scripts: ci.yml and release.yml exist, and release.yml names three OSes') + console.log('check-scripts: ci.yml is a node:22 container, release.yml publishes the repo zip') } // --------------------------------------------------------------------------- @@ -285,6 +345,7 @@ checkLayout() checkConsoleContract() checkPortableRootRule() checkWindowsEntryPoints() +checkRunWebHelp() checkCi() console.log('check-scripts: the scripts tree, its console contract, and its entry points') diff --git a/scripts/checks/check-shell.mjs b/scripts/checks/check-shell.mjs deleted file mode 100644 index 1896e45..0000000 --- a/scripts/checks/check-shell.mjs +++ /dev/null @@ -1,327 +0,0 @@ -#!/usr/bin/env node -// check-shell.mjs - the native app, DRIVEN. -// -// What this proves, and why each one is here: -// -// 1. IT BUILDS, and it is small. `cargo build --release` in `app/` (skipped, loudly, -// when there is no cargo and no binary on this host), then a size ceiling a -// dependency that draws a window or a web view cannot sneak past. -// 2. IT ANSWERS. `-Version`, `-Help`, and the flag the deleted web view used to answer: -// `-Mode embed` must FAIL BY NAME. A flag that quietly means something else is the -// bug this whole revision exists to remove. -// 3. THE BRIDGE. `vncode start` is run against a THROWAWAY TREE: a `.dsh-version.json`, -// a copied binary, a home, and STUB scripts - `scripts/setup/install.*` and -// `scripts/run-web.*` that record what they were given and exit 0. So the app is -// driven end to end - install-when-missing, the key prompt declined at a pipe, the -// launcher handed the right flags - WITHOUT starting node, binding a port or -// opening a tab. -// 4. THE ENVIRONMENT IS COMPOSED, NOT INHERITED. Each stub reads `DSH_HOME`, -// `VNCODE_HOME` and the console markers out of its OWN environment and says what it -// saw, so an inherited home or a leaked `VNCODE_CONSOLE` is a failure here rather -// than a mystery on somebody's machine. That leak is not hypothetical: the old app's -// first Install button ran a full install while being asked for `-Help`. -// 5. NO KEY IS WRITTEN when there is no terminal to ask at, and no launch token reaches -// the console. -// 6. THE WEB HALF STANDS ALONE. `scripts/run-web.* -Help` answers with no app involved. -// -// Every fixture lives under `.scratch/` inside the repository. A check must not depend on -// a temp directory the host may deny - that is how a real bug once looked like a failure -// of the host - and `VNCODE_TEST_DIR` points the Rust tests at the same place. -// -// Run: node scripts/checks/check-shell.mjs - -import { spawnSync } from 'node:child_process' -import fs from 'node:fs' -import path from 'node:path' -import { fileURLToPath } from 'node:url' - -const here = path.dirname(fileURLToPath(import.meta.url)) -const repo = path.resolve(here, '..', '..') -const app = path.join(repo, 'app') -const scratch = path.join(repo, '.scratch') -const isWindows = process.platform === 'win32' - -const failures = [] -const notes = [] -const fail = (message) => failures.push(message) -const note = (message) => notes.push(message) - -const built = path.join(app, 'target', 'release', 'vncode' + (isWindows ? '.exe' : '')) - -// --------------------------------------------------------------------------- -// 1. It builds, and it is small -// --------------------------------------------------------------------------- -function build() { - if (!fs.existsSync(built)) { - const cargo = spawnSync('cargo', ['build', '--release', '--locked', '-p', 'vn-shell'], { - cwd: app, - encoding: 'utf8', - }) - if (cargo.error) { - note(`cargo could not run (${cargo.error.message}) - the binary checks are SKIPPED`) - return false - } - if (cargo.status !== 0) { - fail(`cargo build failed:\n${cargo.stdout}\n${cargo.stderr}`) - return false - } - } - const size = fs.statSync(built).size - note(`the binary is ${(size / 1024 / 1024).toFixed(2)} MB`) - // The release budget is 6 MB and CI owns it; this is the ceiling that catches the - // regression by SHAPE - a GUI stack or a web engine arriving as a dependency. - if (size > 12 * 1024 * 1024) { - fail(`the binary is ${(size / 1024 / 1024).toFixed(1)} MB - something with a GUI in it came back`) - } - return true -} - -// --------------------------------------------------------------------------- -// 2. It answers, and refuses what it no longer has -// --------------------------------------------------------------------------- -function runBinary(args, options = {}) { - const result = spawnSync(built, args, { - encoding: 'utf8', - cwd: options.cwd ?? repo, - env: options.env ?? process.env, - timeout: 120_000, - }) - return { - status: result.status, - stdout: result.stdout ?? '', - stderr: result.stderr ?? '', - error: result.error, - } -} - -function answers() { - const version = runBinary(['-Version']) - if (version.status !== 0 || !/\d+\.\d+\.\d+/.test(version.stdout)) { - fail(`-Version did not answer with a version: ${JSON.stringify(version.stdout)}`) - } - - const help = runBinary(['-Help']) - if (help.status !== 0) fail(`-Help exited ${help.status}`) - for (const word of ['install', 'uninstall', 'status', 'key', '-DshHome', '-Port']) { - if (!help.stdout.includes(word)) fail(`-Help never mentions ${word}`) - } - if (help.stdout.includes('embed')) { - fail('-Help advertises an embedded web view this build does not have') - } - - // The pane's mode. It must be a refusal that NAMES the flag: "we removed it" and "it - // silently does nothing now" are different promises. - const embed = runBinary(['-Mode', 'embed']) - if (embed.status === 0) fail('-Mode embed was accepted by a build with no web view') - if (!/unknown flag/i.test(embed.stderr)) { - fail(`-Mode embed was refused without naming the flag: ${JSON.stringify(embed.stderr)}`) - } -} - -// --------------------------------------------------------------------------- -// 3-5. The bridge, against stubs -// --------------------------------------------------------------------------- -/** A stub script: records what it was given, then exits 0. `up` walks to the tree root. */ -function stubScript(recordName, up) { - // `up` is `..` from `scripts/` and `../..` from `scripts/setup/`: the two stubs live at - // different depths, and a record written one level too high is a check that fails for - // its own bug rather than the app's. - if (isWindows) { - const parents = up.replace(/\//g, '\\') - return [ - '@echo off', - `echo args=%* > "%~dp0${parents}\\${recordName}"`, - `echo DSH_HOME=%DSH_HOME% >> "%~dp0${parents}\\${recordName}"`, - `echo VNCODE_HOME=[%VNCODE_HOME%] >> "%~dp0${parents}\\${recordName}"`, - `echo VNCODE_CONSOLE=[%VNCODE_CONSOLE%] >> "%~dp0${parents}\\${recordName}"`, - `echo TMP=[%TMP%] >> "%~dp0${parents}\\${recordName}"`, - 'exit /b 0', - '', - ].join('\r\n') - } - return [ - '#!/bin/sh', - `record="$(dirname "$0")/${up}/${recordName}"`, - '{', - ' echo "args=$*"', - ' echo "DSH_HOME=$DSH_HOME"', - ' echo "VNCODE_HOME=[$VNCODE_HOME]"', - ' echo "VNCODE_CONSOLE=[$VNCODE_CONSOLE]"', - ' echo "TMP=[$TMPDIR]"', - '} > "$record"', - 'exit 0', - '', - ].join('\n') -} - -function bridge() { - const root = path.join(scratch, `shell-bridge-${process.pid}`) - fs.rmSync(root, { recursive: true, force: true }) - fs.mkdirSync(path.join(root, 'bin'), { recursive: true }) - fs.mkdirSync(path.join(root, 'scripts', 'setup'), { recursive: true }) - fs.mkdirSync(path.join(root, 'data'), { recursive: true }) - - // The pin is what makes the tree a tree: `repo_root()` walks up from the binary for it. - fs.writeFileSync(path.join(root, '.dsh-version.json'), JSON.stringify({ dsh: '9.9.9' })) - fs.copyFileSync(built, path.join(root, 'bin', path.basename(built))) - - const setup = path.join(root, 'scripts', 'setup') - const ext = isWindows ? '.bat' : '.sh' - fs.writeFileSync(path.join(setup, 'install' + ext), stubScript('install-record.txt', '../..')) - fs.writeFileSync(path.join(setup, 'uninstall' + ext), stubScript('uninstall-record.txt', '../..')) - fs.writeFileSync( - path.join(root, 'scripts', 'run-web' + ext), - stubScript('runweb-record.txt', '..'), - ) - - const home = path.join(root, 'data', 'home') - const binary = path.join(root, 'bin', path.basename(built)) - // The seed of every "it printed the wrong thing" report: an inherited home and an - // inherited console marker. Neither may reach a child, and neither may be believed. - const env = { ...process.env, VNCODE_HOME: path.join(root, 'data'), VNCODE_CONSOLE: '1' } - env.VNCODE_ARGV = 'do-not-leak' - delete env.DSH_HOME - delete env.DEEPSEEK_API_KEY - - const run = (args) => - spawnSync(binary, args, { encoding: 'utf8', cwd: root, env, timeout: 180_000 }) - - // --- start, with nothing installed ------------------------------------- - const start = run(['start']) - if (start.error) { - fail(`start could not run: ${start.error.message}`) - return - } - if (start.status !== 0) { - fail(`vncode start exited ${start.status}\n${start.stdout}\n${start.stderr}`) - } - const printed = `${start.stdout}\n${start.stderr}` - if (/token=/i.test(printed)) fail('a launch token reached the console') - - const install = readRecord(root, 'install-record.txt') - if (!install) { - fail('vncode start did not run the installer for a home with no pack in it') - } else { - if (!install.includes('-DshHome')) fail(`the installer was not told the home: ${install}`) - if (!install.includes(home)) fail(`the installer was not told THIS home (${home}): ${install}`) - if (!install.includes('VNCODE_HOME=[]')) { - fail(`the app's own root leaked into the installer: ${install}`) - } - if (!install.includes('DSH_HOME=' + home)) { - fail(`the installer's DSH_HOME is not the chosen home: ${install}`) - } - if (!install.includes('VNCODE_CONSOLE=[]')) { - fail(`the launcher's console marker leaked into the installer: ${install}`) - } - } - - const runweb = readRecord(root, 'runweb-record.txt') - if (!runweb) { - fail('vncode start never ran the web launcher - the bridge is the whole point') - } else { - if (!runweb.includes('-DshHome')) fail(`the launcher was not told the home: ${runweb}`) - if (!runweb.includes(home)) fail(`the launcher was not told THIS home (${home}): ${runweb}`) - if (isWindows && !runweb.includes('-NoTerminal')) { - fail(`the launcher was not told -NoTerminal, so a relaunch would look like an instant exit: ${runweb}`) - } - if (!runweb.includes('DSH_HOME=' + home)) { - fail(`the launcher's DSH_HOME is not the chosen home: ${runweb}`) - } - if (!runweb.includes('VNCODE_HOME=[]')) { - fail(`the app's own root leaked into the launcher: ${runweb}`) - } - if (!runweb.includes('VNCODE_CONSOLE=[]')) { - fail(`the console marker leaked into the launcher: ${runweb}`) - } - // THE PORT IS THIS APP'S OWN. Asking the launcher for its default 3080 is the measured - // bug this assertion exists for: on a machine whose harness already answers on 3080 the - // child dies with `EADDRINUSE` (or, worse, shares an origin with a process whose launch - // token this run does not have). - const givenPort = /-Port\s+(\d+)/.exec(runweb) - if (!givenPort) { - fail(`the launcher was not handed a port of this app's own: ${runweb}`) - } else { - const port = Number(givenPort[1]) - if (port === 3080) { - fail('the app asked for the shared 3080 instead of a free port of its own') - } - if (port < 1 || port > 65535) { - fail(`the port handed to the launcher makes no sense: ${port}`) - } - } - } - - // --- the key is not asked for at a pipe, and nothing is written --------- - const envFile = path.join(home, '.env') - if (fs.existsSync(envFile)) { - fail(`a key file was written with no terminal to ask at: ${envFile}`) - } - if (!/not a terminal/.test(printed)) { - fail(`start did not say why it skipped the key prompt: ${printed}`) - } - - // --- status reports the same home, and starts nothing ------------------ - const status = run(['status']) - if (status.status !== 0) fail(`status exited ${status.status}`) - if (!status.stdout.includes(home)) { - fail(`status does not name the home in use (${home}):\n${status.stdout}`) - } - if (!/launcher:/.test(status.stdout)) fail('status does not name the launcher') - - fs.rmSync(root, { recursive: true, force: true }) - note('start, the installer and the launcher were driven against stub scripts') -} - -function readRecord(root, name) { - const file = path.join(root, name) - return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '' -} - -// --------------------------------------------------------------------------- -// 6. The web half stands alone -// --------------------------------------------------------------------------- -function webHalf() { - const script = path.join(repo, 'scripts', 'run-web' + (isWindows ? '.bat' : '.sh')) - if (!fs.existsSync(script)) { - fail(`${script} is missing - launching only the web is a supported thing to do`) - return - } - // THE CONSOLE MARKERS ARE CLEARED, and that is the whole point of running it here. - // `adapt.cmd` marks a run it has set up with `VNCODE_CONSOLE`, and an entry point that - // sees the marker takes its arguments from the relaunched shell instead of `%*` - so a - // check that inherited the marker would test a path no double-click ever takes. It was - // measured: with the marker inherited, `run-web.bat -Help` started a real harness. - const env = {} - for (const [name, value] of Object.entries(process.env)) { - if (!name.startsWith('VNCODE_')) env[name] = value - } - const result = isWindows - ? spawnSync('cmd', ['/c', script, '-Help'], { encoding: 'utf8', cwd: repo, env }) - : spawnSync('sh', [script, '-Help'], { encoding: 'utf8', cwd: repo, env }) - if (result.status !== 0) { - fail(`run-web -Help exited ${result.status}: ${result.stdout}${result.stderr}`) - return - } - if (!/Usage/i.test(`${result.stdout}${result.stderr}`)) { - fail('run-web -Help printed no usage') - } - note('scripts/run-web.* answers on its own, with no vncode binary involved') -} - -// --------------------------------------------------------------------------- -fs.mkdirSync(scratch, { recursive: true }) - -if (build()) { - answers() - bridge() - webHalf() -} - -console.log('check-shell: the native app, driven') -for (const line of notes) console.log(` - ${line}`) -if (failures.length) { - console.log(`\ncheck-shell: ${failures.length} problem(s).`) - for (const message of failures) console.log(` - ${message}`) - process.exit(1) -} -console.log('\ncheck-shell: OK') diff --git a/scripts/console/adapt.cmd b/scripts/console/adapt.cmd index c09736b..14173c1 100644 --- a/scripts/console/adapt.cmd +++ b/scripts/console/adapt.cmd @@ -5,9 +5,8 @@ rem in this repository. rem rem WHY THIS FILE EXISTS rem -------------------- -rem scripts\setup\install.bat, scripts\setup\uninstall.bat, scripts\run-web.bat, -rem scripts\run-desktop.bat and scripts\setup\*.bat all have to answer the -rem same five questions before they do any work: which +rem scripts\setup\install.bat, scripts\setup\uninstall.bat and scripts\run-web.bat +rem all have to answer the same five questions before they do any work: which rem window am I in, which PowerShell do I have, can this console show colour, rem should I hold the window open at the end, and what were my real arguments? rem Five batch files that each answered those themselves would drift, and the @@ -95,11 +94,11 @@ rem appears even inside a branch that is skipped (measured). rem rem One space is the defined value that fixes it: it holds no flag, so every test rem below reads it exactly as it reads a flagged run, and it is harmless wherever -rem it is forwarded - cmd and Rust both split argv on whitespace, so a lone space -rem never arrives as an argument (measured: scripts\run-desktop.bat with none -rem starts the shell normally). This file is the ONLY place that has to know, +rem it is forwarded - cmd and PowerShell both split argv on whitespace, so a lone +rem space never arrives as an argument (measured: a double-clicked run-web.bat +rem starts the harness normally). This file is the ONLY place that has to know, rem because it must NOT setlocal - its decisions stay visible to the caller by -rem design - so repairing both names here, once, covers all five entry points. +rem design - so repairing both names here, once, covers every entry point. rem check-scripts.mjs asserts this normalisation is still here. if not defined VNCODE_ARGV set "VNCODE_ARGV= " set "VNCODE_ARGS=%VNCODE_ARGV%" diff --git a/scripts/run-desktop.bat b/scripts/run-desktop.bat deleted file mode 100644 index 9e574c3..0000000 --- a/scripts/run-desktop.bat +++ /dev/null @@ -1,234 +0,0 @@ -@echo off -rem ============================================================ -rem vncode DESKTOP launcher - Windows (double-click friendly). -rem -rem The same harness scripts/run-web.bat shows in a Chrome tab, in a -rem native window instead. The shell does the work scripts/run-web.ps1 does -rem for the browser: it starts the pinned -rem "npx @deepseek-ai/dsh@ web --no-open" on a free loopback -rem port, watches for the "dsh web:" ready line and shows THAT url in -rem a WebView2 / WKWebView / WebKitGTK window. The launch token is a -rem live credential: it is read IN MEMORY in Rust, never written to a -rem file, never echoed (the ready line is printed with the token -rem redacted) and never handed to a shell. A URL that does not name a -rem loopback address is refused instead of opened. -rem -rem This is deliberately ONE file, unlike run-web.bat -> run-web.ps1: -rem the watching half is Rust here, so cmd never has to -rem read a running child's output, and there is no PowerShell worker -rem left to hold. The commands are the same either way - only the -rem window differs. -rem -rem WHERE IT RUNS FROM, AND WHY THAT IS CHECKED FIRST -rem ------------------------------------------------ -rem A DISTRIBUTION has the built shell in the folder ABOVE this one, so -rem it runs it and needs nothing else - not even Rust. A SOURCE CHECKOUT -rem has no built shell, so it builds one with cargo (a no-op while it is -rem current, because cargo's own freshness check IS the cache). -rem -rem The order is not a preference. Both kinds of folder have an app\ - -rem a distribution ships the shell's README there, a source checkout -rem ships the Rust source - so "is there a Cargo.toml?" cannot tell the -rem two apart. Only the presence of the built executable can, and -rem building inside a distribution would demand a Rust toolchain from -rem somebody who was only ever asked to click a file. -rem -rem Flags (forwarded to the shell; the same set as scripts/run-web.bat): -rem start (the default), install, uninstall, status or key -rem -Port listen on this port instead of a free one -rem -DshHome override DSH_HOME (default: $DSH_HOME, else ~/.dsh) -rem -DshVersion override the pinned dsh version from .dsh-version.json -rem -Help / -h / /? print the help and stop -rem Plus three this launcher owns and never forwards: -rem -NoBuild never run cargo; use the binary already built -rem -NoPause never hold this window open -rem -NoTerminal stay in this console; do not relaunch -rem -rem Requirements in a SOURCE CHECKOUT: the Rust toolchain -rem (https://rustup.rs) and Node.js >= 22 on PATH. The FIRST build -rem compiles the shell's dependencies and takes a few minutes. In a -rem DISTRIBUTION: nothing - the folder carries its own runtime. -rem -rem The console this runs in is decided in ONE place for every entry -rem point: console\adapt.cmd. This file lives in scripts\ beside that -rem shared layer and resolves everything else from `%~dp0..`. -rem ============================================================ -setlocal - -if not defined VNCODE_CONSOLE set "VNCODE_ARGV=%*" -call "%~dp0console\adapt.cmd" "%~f0" "vncode" -if errorlevel 10 exit /b 0 -if errorlevel 2 goto :nopowershell - -rem --- help, in every spelling ---------------------------------------------- -rem -Help is unambiguous wherever it appears; -h and /? are checked on the FIRST -rem argument only, so a -DshHome path containing "-h" cannot print help instead -rem of starting the app. -rem It is safe on the double-click path - where VNCODE_ARGS used to be -rem UNDEFINED and this very line aborted the whole file with "set was unexpected -rem at this time." - because console\adapt.cmd stores "no arguments" as ONE -rem SPACE, a defined value that holds no flag. The full account is there. -if not "%VNCODE_ARGS:-Help=%"=="%VNCODE_ARGS%" goto :help -set "VN_FIRST=" -for /f "tokens=1 delims= " %%A in ("%VNCODE_ARGS%") do set "VN_FIRST=%%A" -if /I "%VN_FIRST%"=="-h" goto :help -if /I "%VN_FIRST%"=="/?" goto :help - -rem --- the launcher's own flags must not reach the shell --------------------- -rem The Rust shell takes -Port/-DshHome/-DshVersion/-Mode and nothing else: an -rem unknown flag exits 1 with the flag named (deliberately, so a typo is never -rem ignored). These are ours, so they are removed before the hand-over. -set "VN_SHELL_ARGS=%VNCODE_ARGS%" -set "VN_SHELL_ARGS=%VN_SHELL_ARGS:-NoPause=%" -set "VN_SHELL_ARGS=%VN_SHELL_ARGS:-NoTerminal=%" -set "VN_NOBUILD=" -if not "%VNCODE_ARGS:-NoBuild=%"=="%VNCODE_ARGS%" set "VN_NOBUILD=1" -if not defined VN_NOBUILD goto :whichartefact -set "VN_SHELL_ARGS=%VN_SHELL_ARGS:-NoBuild=%" - -:whichartefact -rem --- which artefact runs --------------------------------------------------- -set "VN_BUILT=%~dp0..\vncode.exe" -if exist "%VN_BUILT%" goto :run - -set "VN_MANIFEST=%~dp0..\app\Cargo.toml" -if not exist "%VN_MANIFEST%" ( - echo [vncode] Neither vncode.exe nor app\Cargo.toml is in the - echo folder above this one, so there is no shell to run and no source to - echo build one from. - echo. - echo Run scripts\run-desktop.bat from a repository checkout, or from one of - echo the SOURCE distributions on the releases page - they carry app\. A - echo folder from an older release carries a prebuilt vncode.exe instead, and - echo if that is gone there is nothing here to run. - echo. - echo Neither is needed to USE vncode: run START-HERE.bat, or - echo scripts\run-web.bat, to start the same app in a browser tab. - goto :failed -) - -if defined VN_NOBUILD goto :afterbuild - -rem The source checkout's own artefact, resolved ONCE, so the build leg and the -rem failure leg below name the same file - and so the fallback at :buildfailed -rem has something to run. The workspace puts it under app\target, and the crate -rem is named for the FILE the distribution ships: vncode. -set "VN_APP=%~dp0..\app\target\release\vncode.exe" - -where cargo >nul 2>nul -if errorlevel 1 ( - echo [vncode] cargo was not found on PATH, so the desktop shell cannot - echo be built. Install the Rust toolchain from https://rustup.rs and run - echo this file again - or run it from a distribution folder, which carries - echo the shell already built and needs no Rust at all. - goto :failed -) - -echo [vncode] Building app in the folder above ^(cargo does nothing when it is current^)... -cargo build --release -p vn-shell --manifest-path "%VN_MANIFEST%" -if errorlevel 1 goto :buildfailed - -:afterbuild -rem -NoBuild LANDED HERE, before the line above ever ran, so resolve it again. -if not defined VN_APP set "VN_APP=%~dp0..\app\target\release\vncode.exe" -set "VN_BUILT=%VN_APP%" -if not exist "%VN_BUILT%" ( - echo [vncode] The build reported success but the program is not at - echo %VN_BUILT% - goto :failed -) - -:run -echo. -echo [vncode] Starting the desktop shell. Ctrl+C stops it. -echo. -"%VN_BUILT%" %VN_SHELL_ARGS% -set "VN_EXIT=%ERRORLEVEL%" -if "%VN_EXIT%"=="1" goto :failed -exit /b %VN_EXIT% - -:help -echo. -echo Usage: scripts\run-desktop.bat [command] [flags] -echo. -echo start install the pack if this home lacks it, ask for the key if -echo there is none, then start the harness and open it (the -echo default when no command is given) -echo install run scripts\setup\install.* against the home in use -echo uninstall run scripts\setup\uninstall.* against it -echo status print the pin, the home, the pack, the key and the launcher -echo key ask for the DeepSeek key and write it into ^\.env -echo. -echo -Port ^ hand this port to the web launcher -echo -DshHome ^ use this harness home (default: the one the app chose; -echo a leading ~ is expanded here) -echo -DshVersion ^ override the pinned dsh version from .dsh-version.json -echo -NoBuild never run cargo; use the binary already built -echo -NoPause never hold this window open -echo -NoTerminal stay in this console; do not relaunch -echo -Help print this help -echo -Version print the version -echo. -echo vncode is a front door, not a second harness: it decides the root, the key and -echo the pack, and then runs scripts\run-web.bat - the same file you would -echo double-click - in this console, same pin, same profile, same flags. There is -echo no window and no embedded web view: the interface is a web application and it -echo opens in the browser the launcher found (Google Chrome first). -echo. -echo Launching only the web needs none of this: scripts\run-web.bat works on its -echo own, and so does every script under scripts\setup. -echo. -echo This launcher builds the shell when there is none. From a source checkout that -echo needs the Rust toolchain (https://rustup.rs) and Node.js 22 or newer; from a -echo folder that carries a built vncode.exe it needs nothing. -echo. -echo macOS and Linux use ./scripts/run-desktop.sh, which does the same thing. -echo. -if "%VNCODE_PAUSE%"=="1" pause -exit /b 0 - -:buildfailed -rem A build can fail for one reason this launcher can do nothing about and the -rem reader can fix in one step: THE SHELL IT IS REPLACING IS STILL RUNNING. -rem Windows will not let cargo remove a program that is still mapped by a live -rem process, so `cargo build` stops at -rem failed to remove file ...\vncode.exe: Access is denied. (os error 5) -rem - and the launch used to end there, even though a perfectly good shell was -rem sitting on disk. Reported from the machine this was written on, where the -rem window was simply reopened from a second double-click. So: warn, name the -rem cause, and RUN the artefact that is already there. `-NoBuild` skips the build -rem entirely for the same reason. -echo. -echo [vncode] cargo build failed - see the errors above. -if not exist "%VN_APP%" goto :failed -echo. -echo [vncode] A shell is already built at -echo %VN_APP% -echo [vncode] Running that one. The usual reason a build stops here is that the -echo shell is still RUNNING: Windows will not let cargo replace a program that -echo is in use. Close the vncode window and run this file again to rebuild. -set "VN_BUILT=%VN_APP%" -goto :run - -:nopowershell -echo. -echo ============================================================ -echo vncode could not start. -echo ============================================================ -echo. -echo PowerShell was not found on PATH, and this launcher needs it to -echo set the console up. Windows PowerShell 5.1 ships with every -echo supported version of Windows; if it is missing, install -echo PowerShell 7 from https://aka.ms/powershell and run this again. -echo. -if "%VNCODE_PAUSE%"=="1" pause -exit /b 2 - -:failed -echo. -echo ============================================================ -echo vncode desktop FAILED - see the messages above. -echo ============================================================ -echo. -if "%VNCODE_PAUSE%"=="1" pause -exit /b 1 diff --git a/scripts/run-desktop.sh b/scripts/run-desktop.sh deleted file mode 100644 index 3642780..0000000 --- a/scripts/run-desktop.sh +++ /dev/null @@ -1,148 +0,0 @@ -#!/bin/sh -# ============================================================ -# vncode shell launcher - macOS / Linux. -# -# The POSIX half of `scripts\run-desktop.bat`: the same Rust shell, -# built and run on this host. The shell is a control panel - it opens -# idle, starts the pinned harness when you press Start, shows it in -# your browser, and ends the whole instance when you press Stop. -# -# THE PANE IS OPT-IN HERE. On Windows the launcher builds the shell WITH -# the pane, so the window has two tabs ("control panel" and "harness"); -# on this host that build compiles (given libwebkit2gtk) but wry's child -# view still needs a GTK loop pumped beside winit's, which is not -# written yet - so the default is the panel-only build and `-Pane` asks -# for the other one. A plain `cargo build --release` in app/ still -# builds no engine at all; the feature is chosen by THIS script, not by -# the crate's default. -# -# WHERE IT RUNS FROM, AND WHY THAT IS CHECKED FIRST -# ------------------------------------------------ -# A DISTRIBUTION has the built shell in the folder ABOVE this one, so -# it runs that and needs nothing else - not even Rust. A SOURCE -# CHECKOUT has no built shell, so it builds one with cargo (a no-op -# while it is current, because cargo's own freshness check IS the -# cache). Both kinds of folder have an `app/`, so "is there a -# Cargo.toml?" cannot tell them apart; only the built executable can, -# and building inside a distribution would demand a Rust toolchain from -# somebody who was only ever asked to run a program. -# -# POSIX shell only, and no PowerShell anywhere on this path: this needs -# the Rust toolchain (https://rustup.rs) in a checkout, and Node.js >= -# 22 for the harness it starts. -# -# Usage: -# ./scripts/run-desktop.sh [-Port ] [-DshHome ] [-DshVersion ] -# [-Mode ] [-NoBuild] [-Pane] -# ============================================================ -set -u - -case "$0" in - */*) script_dir=${0%/*} ;; - *) script_dir=. ;; -esac -# This script lives in scripts/, so the repository root is its PARENT folder. -script_dir=$(CDPATH= cd -- "$script_dir" && pwd) -repo_root=$(CDPATH= cd -- "$script_dir/.." && pwd) - -# The console contract - colour only on a terminal, NO_COLOR honoured, and the -# same words the Windows half prints - is defined ONCE for every POSIX entry -# point: console/theme.sh, the twin of console/theme.ps1. -. "$script_dir/console/theme.sh" - -# -NoPause means never hold the window open. The Windows half reads the same -# convention (VNCODE_PAUSE=0), so the flag behaves identically on both hosts. -case " $* " in *" -NoPause "*) VNCODE_PAUSE=0 ;; esac - -no_build=0 -pane=0 -# THE LAUNCHER'S OWN FLAGS ARE REMOVED HERE, not merely read: this script execs the -# shell with its arguments, and the shell refuses a flag it does not know by name. -# The loop rotates the list - shift one off the front, append it at the back unless -# it is ours - so a flag's value (-Port 3099) stays beside it and a path with a -# space survives untouched. -count=$# -index=0 -while [ "$index" -lt "$count" ]; do - argument=$1 - shift - case "$argument" in - -NoBuild|--no-build) no_build=1 ;; - # -NoPause was READ above, to set VNCODE_PAUSE for the console layer; it is - # dropped here so it cannot reach the shell, which refuses flags it does not know. - -NoPause) ;; - *) set -- "$@" "$argument" ;; - esac - index=$((index + 1)) -done - -usage() { - printf '%s\n' \ - 'Usage: sh scripts/run-desktop.sh [command] [-Port ] [-DshHome ] [-DshVersion ]' \ - ' [-NoBuild]' \ - '' \ - ' start install the pack if this home lacks it, ask for the key if' \ - ' there is none, then start the harness and open it (the' \ - ' default when no command is given)' \ - ' install run scripts/setup/install.sh against the home in use' \ - ' uninstall run scripts/setup/uninstall.sh against it' \ - ' status print the pin, the home, the pack, the key and the launcher' \ - ' key ask for the DeepSeek key and write it into /.env' \ - '' \ - ' -Port hand this port to the web launcher' \ - ' -DshHome use this harness home (default: the one the app chose;' \ - ' a leading ~ is expanded here)' \ - ' -DshVersion override the pinned dsh version from .dsh-version.json' \ - ' -NoBuild never run cargo; use the binary already built' \ - ' -NoPause never hold this window open' \ - ' -Help / -h / --help print this help' \ - ' -Version print the version' \ - '' \ - 'vncode is a front door, not a second harness: it decides the root, the key and' \ - 'the pack, and then runs scripts/run-web.sh - the same file you would run by' \ - 'hand - in this console. There is no window and no embedded web view: the' \ - 'interface is a web application and it opens in the browser the launcher found.' \ - '' \ - 'Launching only the web needs none of this: scripts/run-web.sh works on its own,' \ - 'and so does every script under scripts/setup.' \ - '' -} - -case "$*" in - *-Help*|*--help*|*" -h "*|*" -h"|" -h "*) - usage - exit 0 - ;; -esac - -# A distribution: the built shell sits in the folder above scripts/. -built="$repo_root/vncode" -if [ -x "$built" ]; then - exec "$built" "$@" -fi - -if [ "$no_build" = "1" ]; then - echo "[vncode] -NoBuild was given but there is no built shell at $built" >&2 - exit 1 -fi - -if ! command -v cargo >/dev/null 2>&1; then - echo "[vncode] cargo was not found on PATH, so the shell cannot be built." >&2 - echo " Install the Rust toolchain from https://rustup.rs and run this again -" >&2 - echo " or run ./scripts/run-web.sh, which needs only Node.js." >&2 - exit 2 -fi - -echo "[vncode] Building app/ (cargo does nothing when it is current)..." -if ! (cd "$repo_root/app" && cargo build --release -p vn-shell); then - echo "[vncode] cargo build failed - see the errors above." >&2 - # THE SHELL IT IS REPLACING MAY STILL BE RUNNING. Unix lets a build replace a - # running program's file, so this cannot fail the way Windows does - but a - # build that failed for another reason may still have left a usable binary. - if [ ! -x "$repo_root/app/target/release/vncode" ]; then - exit 1 - fi - echo "[vncode] A shell is already built at app/target/release/vncode - running that one." >&2 -fi - -exec "$repo_root/app/target/release/vncode" "$@" diff --git a/scripts/run-web.bat b/scripts/run-web.bat index e70a04a..68f88c9 100644 --- a/scripts/run-web.bat +++ b/scripts/run-web.bat @@ -10,11 +10,7 @@ rem "npx @deepseek-ai/dsh@ web --no-open", streams the app's rem output, reads the "dsh web:" line it prints once the server is rem listening and opens THAT url - launch token included - in rem Google Chrome, falling back to the default browser. The -rem harness runs in the FOREGROUND of this window: Ctrl+C stops it. -rem -rem The desktop window is the other half: scripts/run-desktop.bat starts -rem the very same harness and shows that same url in a native -rem window instead of a browser tab. +rem The harness runs in the FOREGROUND of this window: Ctrl+C stops it. rem rem Why the split: a .bat is what Windows double-clicks, and a .bat rem is also what carries no execution-policy question, while the diff --git a/scripts/run-web.ps1 b/scripts/run-web.ps1 index 11a52bb..f5d6071 100644 --- a/scripts/run-web.ps1 +++ b/scripts/run-web.ps1 @@ -284,27 +284,21 @@ Assert-Tool 'node' Assert-Tool 'npx' # --------------------------------------------------------------------------- -# WHICH HOME THIS RUN USES - one rule, shared with the app +# WHICH HOME THIS RUN USES - one rule, in both launchers # --------------------------------------------------------------------------- # Order, and each rung is a reason: # 1. -DshHome the person named it for this run; # 2. an inherited DSH_HOME a harness session that started this shell, which this run -# JOINS - the same rung the app's ladder has; +# JOINS; # 3. THE PORTABLE ROOT `/.vncode/home`, when this folder carries the `PORTABLE` # marker or already holds a home. A portable installation keeps # everything inside the folder, so the pack, the sessions and the -# key need nothing in the user's profile - and, just as -# important, `run-web` and `run-desktop` (the panel) then start -# the SAME home. Two launchers pointing at two homes is how a -# pack ends up installed in one and missing in the other, which -# was measured on a real machine: the panel reported 24 bundles -# while `run-web` started `~/.dsh`. +# key need nothing in the user's profile. # 4. ~/.dsh the harness's own default, for a folder that is not portable. # -# The portable test is the SAME rule `vn_shell_core::appdata::portable_root` applies - -# the marker, or a home already inside the root. Keep the two in step; a check reads this -# file and `run-web.sh` for the marker and the `home` folder so the rule cannot drift out -# of one of the three places unnoticed. +# The portable test is two facts - the marker, or a home already inside the root - and +# `run-web.sh` implements the same two. Keep them in step; a check reads both files for the +# marker and the `home` folder so the rule cannot drift out of one of them unnoticed. if ($DshHome) { $env:DSH_HOME = $DshHome Write-Step "DSH_HOME: $DshHome" @@ -319,10 +313,10 @@ if (-not $harnessHome) { if ((Test-Path (Join-Path $portableRoot 'PORTABLE')) -or (Test-Path (Join-Path $portableRoot 'home'))) { $harnessHome = Join-Path $portableRoot 'home' $env:DSH_HOME = $harnessHome - # The cache follows the home, for the same reason the app's does: npm writing into - # the user's shared cache is the one thing a portable folder still depended on, and - # a shared cache an elevated run made unwritable is a failure with nothing to do - # with this pack. An explicit npm_config_cache always wins. + # The cache follows the home: npm writing into the user's shared cache is the one + # thing a portable folder still depended on, and a shared cache an elevated run made + # unwritable is a failure with nothing to do with this pack. An explicit + # npm_config_cache always wins. if (-not $env:npm_config_cache) { $env:npm_config_cache = Join-Path $portableRoot 'npm-cache' } diff --git a/scripts/run-web.sh b/scripts/run-web.sh index adc6f22..bd5f2a2 100755 --- a/scripts/run-web.sh +++ b/scripts/run-web.sh @@ -242,23 +242,20 @@ if [ -n "$dsh_home_arg" ]; then step "DSH_HOME: $dsh_home_arg" fi -# WHICH HOME THIS RUN USES - one rule, shared with the app and with run-web.ps1. +# WHICH HOME THIS RUN USES - one rule, in both launchers. # # 1. -DshHome the person named it for this run; # 2. an inherited DSH_HOME a harness session that started this shell, which this run # JOINS; # 3. THE PORTABLE ROOT `/.vncode/home`, when this folder carries the `PORTABLE` # marker or already holds a home: a portable installation keeps the -# pack, the sessions and the key inside the folder, and `run-web` -# and the panel then start the SAME home. Two launchers pointing at -# two homes is how a pack ends up installed in one and missing in -# the other - measured: the panel reported 24 bundles while -# `run-web` started `~/.dsh`. +# pack, the sessions and the key inside the folder, so nothing lands +# in the user's profile. # 4. ~/.dsh the harness's own default, for a folder that is not portable. # -# The portable test is the SAME rule `vn_shell_core::appdata::portable_root` applies. Keep -# the three in step; a check reads this file and run-web.ps1 for the marker and the `home` -# folder so the rule cannot drift out of one of them unnoticed. +# The portable test is two facts - the marker, or a home already inside the root - and +# `run-web.ps1` implements the same two. Keep the two in step; a check reads both files for +# the marker and the `home` folder so the rule cannot drift out of one of them unnoticed. harness_home=${dsh_home_arg:-${DSH_HOME:-}} if [ -z "$harness_home" ]; then portable_root="$repo_root/.vncode" @@ -266,9 +263,8 @@ if [ -z "$harness_home" ]; then harness_home="$portable_root/home" DSH_HOME=$harness_home export DSH_HOME - # The cache follows the home, for the same reason the app's does: npm writing into - # the user's shared cache is the one thing a portable folder still depended on. An - # explicit npm_config_cache always wins. + # The cache follows the home: npm writing into the user's shared cache is the one + # thing a portable folder still depended on. An explicit npm_config_cache always wins. if [ -z "${npm_config_cache:-}" ]; then npm_config_cache="$portable_root/npm-cache" export npm_config_cache