deskssh 0.0.1

package/packages/web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": false,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/packages/web/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'packages/*'

package/specs/001-core/plan.md

@@ -0,0 +1,246 @@
+# Technical plan — 001 Core
+
+**How** to build what [`spec.md`](./spec.md) describes, respecting
+[`constitution.md`](../constitution.md). The stack proposals are the recommended
+starting point, not dogma; open decisions are marked `[NEEDS DECISION]`.
+
+---
+
+## 1. Delivery model (one web app, two distributions)
+
+Decision of record: **agnostic core + web-first; a single web app delivered two
+ways — hosted, or self-hosted via npm. No native desktop wrapper.**
+
+Reasons:
+
+- The user wants "anyone to be able to access it on the network" → favors web.
+- The **browser cannot open raw SSH/TCP connections**, so the SSH session must live
+  in a **backend** (gateway). That forces, anyway, a core separable from the UI
+  (Art. 5).
+- The offline/LAN need is met by **self-hosting the same web app via npm** (run it
+  locally, open it in the browser), not by a native desktop build. Local users
+  install from npm; there is **no Tauri/Electron app**.
+
+Result: **a single logic base and one web UI**, distributed as **hosted** or
+**self-hosted (npm)**. **Confirmed (2026-06-25; native desktop dropped 2026-06-26).**
+
+```
+┌────────────────────────────┐        ┌───────────────────────────────┐
+│  Frontend (browser UI)     │  WS/   │  Backend (DeskSSH gateway)    │
+│  desktop shell + UI        │ <────> │  SSH sessions + API           │
+│  React + TS                │  HTTP  │  uses the CORE                │
+└────────────────────────────┘        │   ┌────────────────────────┐  │   SSH
+                                       │   │  core (agnostic)       │  │ <─────> Remote
+                                       │   │  adapters, parsers,    │  │  host
+                                       │   │  apps, sessions        │  │ (POSIX)
+                                       │   └────────────────────────┘  │
+                                       └───────────────────────────────┘
+```
+
+## 2. Layered architecture
+
+1. **`core`** (agnostic, no UI nor presentation network I/O):
+   - _Session manager_: abstraction over an SSH connection (run command, open PTY,
+     open SFTP).
+   - _OS adapters_: detection + family-specific commands (Art. 6).
+   - _Parsers_: turn command output into data structures; with fallback to raw
+     output (Art. 7).
+   - _Apps_: each app defines what data it requests and what commands it runs (file
+     manager, processes, services, monitor, editor, logs).
+   - _Transparency_: every executed command is logged/exposed (Art. 3).
+2. **`server`** (web gateway): keeps SSH sessions alive, authenticates the user,
+   exposes an API (HTTP for one-off actions, WebSocket for PTY and streams),
+   isolates sessions between users.
+3. **`web`** (frontend): desktop shell (windows, taskbar, launcher) and each app's
+   views. Talks to `server`, never to SSH directly.
+4. **Distribution**: the same `server` + `web` runs **hosted** or **self-hosted via
+   npm** (local/LAN). No separate native app.
+
+## 3. Proposed stack (v1)
+
+Core stack **confirmed (2026-06-26): TypeScript + Node + `ssh2` + React.** UI
+details (styling framework, icon set) still open — see §8. Alternatives noted.
+
+- **Language:** TypeScript across the stack → a single language lowers the
+  contribution barrier (Art. 9).
+- **Monorepo:** pnpm workspaces. Packages: `core`, `server`, `web` (and later
+  `desktop`).
+- **Backend (`server`):** Node.js + the `ssh2` SSH library (mature, supports exec,
+  PTY and SFTP) + WebSocket (`ws`). _Alternative:_ Rust (`russh`) for
+  security/performance, at the cost of a higher entry barrier → discarded for v1.
+- **Frontend (`web`):** React + TypeScript. Terminal with **`xterm.js`**.
+  Movable/resizable windows with a lightweight library (e.g. `react-rnd` style) or
+  custom components.
+  - _Styling/components:_ **Tailwind CSS + Radix UI via shadcn/ui** (all **MIT** —
+    AGPL-compatible). Tailwind for the custom desktop look; Radix primitives bring
+    built-in accessibility (focus, keyboard, ARIA), key for the accessibility-first
+    goal; shadcn/ui delivers them as in-repo, editable components.
+  - _Icon set:_ **Lucide** (`lucide-react`, **ISC** — AGPL-compatible, no
+    attribution), chosen for its clean, uniform stroke style fitting the
+    accessibility-first UI. (Considered: Tabler/Phosphor/Heroicons MIT, Material
+    Symbols Apache-2.0, Font Awesome Free CC BY; FA Pro proprietary — avoided.)
+- **Distribution:** published to **npm** so local/LAN users self-host the web app;
+  a hosted deployment serves internet-open servers. No native desktop build.
+
+## 4. Core design
+
+### Capability contract (adapter IR)
+
+The core defines a **capability contract**: a closed catalog of abstract, **typed**
+operations that apps invoke **without knowing which OS they run on**. It is the
+system's "intermediate language" (an _intermediate representation_, IR). Two pieces:
+
+1. **Contract (typed interface).** Each capability declares inputs and, above all, a
+   **normalized output**. Examples:
+   - `listDir(path) → FileEntry[]` — not text, but an array of
+     `{ name, type, size, mode, owner, mtime }`.
+   - `listProcesses() → Process[]`
+   - `readFile(path) → bytes` · `writeFile(path, bytes) → void`
+   - `serviceAction(name, action) → ServiceState`
+
+   The value is in the **output type**: if an app knows `listDir` returns a
+   `FileEntry[]`, it no longer cares how it was obtained nor on which platform.
+
+2. **Adapter manifests (declarative) + escape hatch.** Each platform implements the
+   contract. 80% of cases **declaratively** (command template + output normalization
+   spec); the hard 20% (busybox, PowerShell) with a **code hook**.
+
+**Rules that hold it together:**
+
+- Apps **never** parse raw output; they only consume contract types. Parsing and its
+  _fallback_ live in the adapter (reinforces Art. 7).
+- **Normalize at the source**: request structured output (`stat -c`, `ps -eo`,
+  `ConvertTo-Json`…) instead of parsing human format.
+- **Capability gaps**: if a platform doesn't support an operation (e.g. `chmod` on
+  Windows), the adapter declares it _unsupported_ and the UI degrades gracefully
+  instead of pretending.
+
+#### Non-interactive primitives > driving TUIs
+
+A corollary of the contract (and the answer to "how to emulate nano"): DeskSSH
+**does not drive remote interactive tools** (nano, vim, top…) by sending keystrokes
+over a PTY —it would be fragile and impossible to normalize—. It uses
+**non-interactive, structured primitives** and **emulates the experience on the
+client**:
+
+- **Editor** = `readFile` + `writeFile` + a custom GUI editor (no remote nano is
+  launched).
+- **Monitor** = `listProcesses`/`systemMetrics` by _polling_, not a live `top`.
+- The **only** deliberate exception is the **terminal** app, which does expose the
+  raw shell (there the user sees `bash`/`PowerShell`/`csh`).
+
+### OS adapters
+
+- The contract above exposes a **uniform interface** (`listDir`, `stat`,
+  `listProcesses`, `listServices`, `serviceAction`, `systemMetrics`, …).
+- Each **OS family** is an adapter implementing that contract, declaratively when
+  possible. **v1 covers only Debian/Ubuntu/Mint** (see host roadmap below).
+- Detection on connect (`/etc/os-release`, `uname`), with a generic POSIX fallback
+  adapter for not-yet-supported Unix-likes.
+- Prefer machine-readable output (`stat -c '%n|%s|%a|...'`, `ps -eo ...`, `--json`
+  flags where available) over parsing human format.
+
+#### Supported-host roadmap
+
+The tier number indicates **roadmap priority, NOT difficulty** (see the _Effort_
+column). Windows is prioritized for popularity despite being the most costly.
+
+| Tier       | Hosts                                                        | Effort   | Notes                                                                                                                               |
+| ---------- | ------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **1** (v1) | Debian / Ubuntu / Mint                                       | base     | POSIX + GNU coreutils + systemd                                                                                                     |
+| **2**      | Windows                                                      | **high** | Non-POSIX: its own PowerShell adapter family. Still agentless (PowerShell ships with the OS). Prioritized for popularity, not ease. |
+| **3**      | Rest of mainstream Linux (RHEL/Fedora/Rocky, Arch, openSUSE) | low      | Same paradigm as v1 (systemd + GNU); differ mainly in the package manager                                                           |
+| **4**      | macOS, FreeBSD                                               | medium   | BSD userland; init `launchd` (macOS) / `rc.d` (FreeBSD), not systemd                                                                |
+| **5**      | Alpine                                                       | medium   | `busybox` (trimmed flags), OpenRC, musl                                                                                             |
+
+> Constitution note: when Tier 2 arrives, the **"POSIX utilities" wording of Art. 2
+> will need generalizing** (still agentless, but no longer POSIX).
+
+### File opening: handlers and routes (FR-025)
+
+- **File-type handler registry:** each DeskSSH app declares which types it can open.
+  It is the basis of "Open" (default handler) and "Open with" (choose handler), and
+  the seed of extensibility for future apps.
+- **Two opening routes:**
+  - **(A) Render in DeskSSH:** the contract's `readFile` → painted by a GUI handler.
+    With a **size limit**/warning (Art. 8); no handler for the type → route B is
+    offered.
+  - **(B) _Handoff_ to the client:** download over **streaming SFTP** (don't load
+    into memory) to the user's local machine.
+- **Browser limitation (`[NEEDS DECISION]`):** DeskSSH always runs in a browser
+  (hosted or self-hosted), so "Open on the client" can only **download** (and inline
+  depending on type); it cannot force the OS's default app. Resolve as plain
+  download, inline-by-type, or both.
+
+### Parsers and resilience
+
+- Each parser receives output + exit code; on unexpected format it returns a
+  "degraded" result with the raw output (Art. 7), never throwing and breaking.
+
+### Transparency
+
+- Every execution goes through a single point that logs `{command, host, timestamp,
+exitCode}` and makes it queryable from the UI (FR-013, Art. 3).
+
+### Performance (Art. 8)
+
+- VFS listing cache with per-action invalidation.
+- Batching related commands into a single invocation when possible.
+- Optimistic UI on file operations, with reconciliation.
+
+## 5. Security (Art. 4)
+
+- The backend is the critical surface: gateway user authentication, strict per-user
+  session isolation, rate limiting.
+- Secrets: never in plain text nor in logs. **v1 does not persist** (ask each
+  session, in-memory only); an encrypted store (OS keychain / local encryption with
+  a derived key) is post-v1 (FR-005).
+- Destructive actions: mandatory confirmation at the app layer (FR-090).
+- SSH host key verification (avoid MITM); `known_hosts` policy.
+- Auditing: the transparency log also serves as an audit trail.
+
+## 6. Phases / milestones
+
+**v1 = focused cut, accessibility first.** v1 app set: connection/hosts, desktop
+shell, file manager, text editor, terminal and **system monitor**. Processes,
+services, log viewer and packages are **post-v1**.
+
+- **M0 — Scaffolding:** monorepo, empty packages, basic CI, license, contributing.
+- **M1 — Connection core:** SSH session (exec/PTY/SFTP) + OS detection +
+  Debian/Ubuntu adapter + capability-contract base. Demonstrable via tests/minimal
+  CLI.
+- **M2 — Shell + Terminal + File manager:** first usable desktop.
+- **M3 — Text editor + System monitor + transparency in the UI:** **completes v1.**
+- **── 🚀 v1 release ──**
+- **Post-v1 (admin apps):** Processes + Services + Log viewer + Packages.
+- **Post-v1 (hosts):** go down the tier roadmap (Windows → rest of Linux → …).
+- **Post-v1 (hosted):** a hosted web deployment for internet-open servers
+  (self-hosted npm is available from v1).
+
+## 7. Risks and mitigations
+
+| Risk                                       | Impact                | Mitigation                                          |
+| ------------------------------------------ | --------------------- | --------------------------------------------------- |
+| Command output varies by OS/locale/version | Fragile parsing       | Adapters + machine output + raw fallback (Art. 6/7) |
+| Latency from round trips                   | Slow UX               | Cache, batching, optimistic UI (Art. 8)             |
+| Backend = exposed SSH gateway              | High security risk    | Auth, isolation, host keys, auditing (§5)           |
+| App over-scope                             | v1 never ships        | Lock a minimal app subset per milestone             |
+| Coupling logic to the UI                   | Breaks future desktop | Strict agnostic core (Art. 5)                       |
+
+## 8. Decisions
+
+**Closed (2026-06-25):**
+
+- **Web-first** + agnostic core as the v1 architecture.
+- **License AGPL-3.0-or-later** (see `constitution.md` and `LICENSE`).
+- **User #1 = accessibility**; **focused v1** (app set in §6).
+
+**Closed (2026-06-26):**
+
+- **Core stack: TypeScript + Node + `ssh2` + React.**
+- **UI: Tailwind CSS + Radix UI (via shadcn/ui)** — all MIT.
+- **Icon set: Lucide** (ISC — AGPL-compatible, no attribution required).
+- **No native desktop app:** local/LAN use = self-hosted **npm** web app.
+- **v1 credentials: not persisted** — asked per session (FR-005).
+
+**Open:** product-level decisions tracked in spec §9 (`ssh-agent`, i18n scope).

package/specs/001-core/spec.md

@@ -0,0 +1,206 @@
+# Functional specification — 001 Core (base experience)
+
+Defines **what** DeskSSH does and **why**, without going into how it is implemented
+(that's in `plan.md`). Open decisions are marked `[NEEDS DECISION]` and listed at
+the end.
+
+Related: [`../constitution.md`](../constitution.md) · [`../glossary.md`](../glossary.md)
+
+---
+
+## 1. Problem
+
+Administering a Linux server with no graphical environment forces you to know the
+command line. Existing graphical alternatives:
+
+- **Remote desktop (VNC/RDP/X)**: requires an installed graphical environment and
+  consumes bandwidth transmitting pixels; unviable on headless servers.
+- **Web panels (Cockpit, Webmin)**: require installing and maintaining an agent on
+  the server, and offer a "web form" UX, not a desktop one.
+
+There is no tool that gives a **real desktop experience** over **any server with
+just SSH**, installing nothing and transmitting no pixels.
+
+## 2. Value proposition
+
+DeskSSH presents a **familiar desktop** (windows, file manager, terminal, monitor,
+editor, services) whose backend is **plain SSH**: every interaction is translated
+into commands executed on the host. No agents, no streaming, and with
+**transparency**: you can always see the command behind the click.
+
+## 3. Goals (v1)
+
+- G1. Connect to remote hosts over SSH (key or password) and manage them.
+- G2. Offer a desktop shell with windows and basic multitasking.
+- G3. Include an initial set of useful apps (see §6).
+- G4. Work **agentless** on common Linux servers.
+- G5. Make the equivalent command of each action visible (transparency).
+
+## 4. Non-goals (v1)
+
+- Desktop streaming or remote graphical applications (forbidden by the
+  constitution).
+- Windows, macOS, \*BSD and other Linux distros as remote host: **out of v1**,
+  planned in the host roadmap (Tier 2+, see `plan.md §4`).
+- Multi-user / real-time collaboration over the same session.
+- Fleet orchestration (managing many servers at once).
+- Third-party app/plugin store (the architecture will allow it, but not in v1).
+
+## 5. Personas and use cases
+
+> **v1 primary persona: "User with low CLI fluency".** v1 prioritizes
+> **accessibility**: safe, guided defaults, plain language, the terminal as a last
+> resort and transparency (Art. 3) presented in an _educational, on-demand_ way,
+> not as the protagonist. Other personas are served, but they do not steer the
+> design.
+
+- **⭐ User with a VPS but low CLI fluency (PRIMARY)** — manages their server with a
+  GUI without having to master the terminal. _"I want to manage my server without
+  the console intimidating me."_
+- **Sysadmin / DevOps** — manages VPSs and servers; wants speed and to see what
+  runs. _"I review services and logs without memorizing flags."_
+- **Developer** — deploys to a VPS; wants to manage files and processes
+  comfortably. _"I upload a build and restart the service without opening 3
+  terminals."_
+- **Person learning Linux** — command transparency teaches them. _"I see what
+  command each thing I click does."_
+
+### Main journey
+
+1. The user adds a host (address, user, authentication method).
+2. They connect; DeskSSH detects the OS and opens the **desktop**.
+3. They open the **file manager**, browse, copy a file (seeing the confirmation
+   and, optionally, the command).
+4. They open the **system monitor** and check CPU/memory/disk at a glance.
+   (Service/process management arrives _post-v1_.)
+5. They open a real **terminal** for something specific. They close the session.
+
+## 6. Functional requirements
+
+> **v1 app scope (focused cut):** Connection/hosts, Desktop shell, File manager,
+> Text editor, Terminal and **System monitor**. The apps marked _(post-v1)_ below
+> —Processes, Services, Log viewer, Packages— are specified here but implemented
+> after v1 (see `plan.md §6`).
+
+### Connection and hosts
+
+- **FR-001** Add, edit and remove hosts (name, address, port, user).
+- **FR-002** Authentication via: (a) **SSH private key** —the user provides the key
+  file (**PEM / OpenSSH / PKCS#8** formats), with **optional passphrase**—, and
+  (b) **password**. (Key protection/storage is governed by FR-005 and constitution
+  Art. 4.) `ssh-agent` support is **post-v1**.
+- **FR-003** Connect/disconnect; show session state (connecting, alive, dropped,
+  error).
+- **FR-004** Detect the host's OS family to choose the adapter (Art. 6).
+- **FR-005** Never persist secrets in plain text (Art. 4). **v1: do not persist
+  credentials** — entered per session and kept only in memory while connected; an
+  encrypted store (OS keychain / local encryption) may come post-v1.
+
+### Desktop shell
+
+- **FR-010** Show a desktop with movable/resizable windows and a taskbar.
+- **FR-011** App launcher ("start menu") to open the available apps.
+- **FR-012** Support multiple windows/apps open simultaneously over one session.
+- **FR-013** Visible indicator to inspect the command of the last action
+  (transparency, Art. 3).
+
+### App: File manager
+
+- **FR-020** Browse the remote directory tree with icons and details.
+- **FR-021** Create folder, rename, copy, move and delete (delete/overwrite require
+  confirmation, Art. 4).
+- **FR-022** View properties (size, permissions, owner, dates).
+- **FR-023** Upload and download files between the user's machine and the host.
+- **FR-024** Drag & drop in the file manager — **post-v1** (not in the focused v1
+  cut).
+- **FR-025** When opening a file, the user chooses between two **execution
+  locations**:
+  - **(A) In DeskSSH** — _Open_ (default DeskSSH app for that type) or _Open with_
+    (choose among DeskSSH apps/viewers). The file is read via `readFile` and
+    rendered in the GUI; **nothing runs on the remote** (Art. 10). Requires a
+    DeskSSH _handler_ for that type; if none, option (B) is offered.
+  - **(B) On the client** — _Open on the client_ (downloaded over SFTP, streaming,
+    to the **user's local machine** and opened with their OS's default program) or
+    _Download_ (just save locally).
+
+  Vocabulary note: **"the client" = the user's local machine** (their browser/OS in
+  the web model), not the DeskSSH server.
+  Since DeskSSH always runs in a browser (hosted or self-hosted npm), it cannot
+  force opening with the OS's default program. `[NEEDS DECISION]` does "Open on the
+  client" resolve as a **plain download**, as **inline opening** depending on type,
+  or both?
+
+### App: Terminal
+
+- **FR-030** Real interactive terminal (PTY over SSH) with resizing.
+- **FR-031** Reuse the already-connected host's SSH session.
+
+### App: Processes / Task manager _(post-v1)_
+
+- **FR-040** List processes (CPU/mem usage, PID, user, command).
+- **FR-041** Terminate a process (mandatory confirmation).
+
+### App: System monitor
+
+- **FR-050** Show CPU, memory, disk and uptime, with periodic refresh.
+
+### App: Service manager _(post-v1)_
+
+- **FR-060** List services (systemd first) and their state.
+- **FR-061** Start, stop and restart services (mandatory confirmation).
+- **FR-062** View a service's recent state/log.
+
+### App: Text editor
+
+- **FR-070** Open, edit and save remote text files.
+- **FR-071** Warn about unsaved edits on close.
+
+### App: Log viewer _(post-v1)_
+
+- **FR-080** View and follow (`tail -f`/`journalctl -f`) logs in streaming.
+
+### Cross-cutting
+
+- **FR-090** Every destructive action asks for explicit confirmation (Art. 4).
+- **FR-091** If parsing output fails, show the raw output without breaking the app
+  (Art. 7).
+- **FR-092** Show latency/state of in-flight network operations (Art. 8).
+
+## 7. Non-functional requirements
+
+- **NFR-Security** — Fully comply with Article 4 of the constitution.
+- **NFR-Portability** — v1 covers **Debian/Ubuntu/Mint** as remote host; support for
+  more OSes is added via adapters (Art. 6) following the **host roadmap**
+  (`plan.md §4`).
+- **NFR-Performance** — Common operations (list a folder, refresh the monitor)
+  perceptibly fluid at typical network latencies; minimize round trips.
+- **NFR-Resilience** — No parsing/network failure crashes the app (Art. 7).
+- **NFR-Accessibility / i18n** — Keyboard-navigable UI; **i18n-ready from day 1**
+  (all strings externalized) and **v1 ships EN + ES**.
+- **NFR-Openness** — Stack and dependencies 100% open source (Art. 9).
+
+## 8. Acceptance criteria (v1, high level)
+
+- A user can add a real Linux host, connect and open the desktop.
+- They can browse files, open a working terminal, view processes/services and edit a
+  file, all agentless.
+- Every destructive action asks for confirmation; no secret is stored in plain text.
+- A parsing failure on an "odd" host shows raw output without crashing.
+
+## 9. Open decisions `[NEEDS DECISION]`
+
+1. ~~Open source license~~ → **Resolved (2026-06-25): AGPL-3.0-or-later** (see
+   `constitution.md` and `LICENSE`).
+2. ~~Confirm web-first~~ → **Resolved: web-first** (2026-06-25), one web app
+   delivered hosted or self-hosted via npm; **no native desktop** (2026-06-26). See
+   `plan.md §1`.
+3. ~~`ssh-agent`~~ → **Resolved (2026-06-26): post-v1** (v1 = key PEM/passphrase +
+   password) (FR-002).
+4. ~~Credential store~~ → **Resolved (2026-06-26): v1 does not persist** (ask each
+   session); encrypted store post-v1 (FR-005).
+5. ~~Drag & drop~~ → **Resolved (2026-06-26): post-v1** (FR-024).
+6. ~~i18n scope~~ → **Resolved (2026-06-26): i18n-ready from day 1, v1 ships EN +
+   ES** (NFR-Accessibility/i18n).
+7. ~~v1 app set~~ → **Resolved (2026-06-25):** focused cut = Connection/hosts,
+   Shell, File manager, Editor, Terminal and System monitor; the rest _(post-v1)_
+   (see §6 and `plan.md §6`).

package/specs/001-core/tasks.md

@@ -0,0 +1,110 @@
+# Tasks — 001 Core
+
+> Breakdown of the work, derived from [`spec.md`](./spec.md) and
+> [`plan.md`](./plan.md). **No code is written for a task that doesn't exist here**
+> (see `CLAUDE.md`). Each task references the `FR-`/Article it serves.
+> Detailed since: 2026-06-26. M0–M1 are detailed; M2–M3 are outlined and broken
+> down when tackled.
+
+## Preconditions (definition phase) — DONE
+
+- [x] **web-first + agnostic core** confirmed (plan §1).
+- [x] **License** chosen — AGPL-3.0-or-later (spec §9.1).
+- [x] **Stack** confirmed — TS + Node + ssh2 + React, Tailwind + Radix (shadcn/ui),
+      Lucide, xterm.js (plan §3).
+- [x] **v1 app set** agreed — connection, shell, files, editor, terminal, monitor
+      (spec §9.7).
+- [x] Credentials (no persistence), ssh-agent (post-v1), drag&drop (post-v1), i18n
+      (EN+ES, ready day 1) resolved.
+
+> Only minor open item: browser behavior of "Open on the client" (FR-025) — decided
+> during M2 coding.
+
+---
+
+## M0 — Scaffolding
+
+Goal: an empty but coherent monorepo that builds, lints, tests and publishes.
+
+- [x] **M0.1** Initialize pnpm-workspace monorepo with packages `core`, `server`,
+      `web`. → plan §2
+- [x] **M0.2** Root TypeScript config (strict) shared across packages.
+- [x] **M0.3** Linting/formatting (ESLint + Prettier) and a `test` runner
+      (Vitest) wired at the root.
+- [x] **M0.4** Basic CI (GitHub Actions): install, lint, typecheck, test, build on
+      push/PR. → plan §6
+- [x] **M0.5** Add `CONTRIBUTING.md` (SDD flow, English-only repo, how to propose
+      via `specs/`). `LICENSE` already present. → Art. 9
+- [x] **M0.6** Minimal i18n scaffolding decision/setup so strings are externalized
+      from day 1 (EN + ES catalogs stub). → NFR-i18n
+- [ ] **M0.7** Publish `deskssh` `0.0.1` placeholder to npm (claims the name;
+      `AGPL-3.0-or-later`, public access). **Needs maintainer npm login.** → vision
+      (distribution)
+
+**M0 done when:** `pnpm install && pnpm -r build && pnpm -r test` pass in CI and the
+`deskssh` name is reserved on npm.
+
+---
+
+## M1 — Connection core
+
+Goal: the agnostic `core` can open an SSH session to a Debian/Ubuntu host, run typed
+capabilities through an adapter, and log every command. Demonstrable via tests +
+a minimal CLI (no web UI yet).
+
+### Session layer
+
+- [ ] **M1.1** `SshSession` over `ssh2`: connect with **private key (PEM/OpenSSH/
+      PKCS#8, optional passphrase)** and **password**; never persist secrets. → FR-002,
+      FR-005, Art. 4
+- [ ] **M1.2** Session lifecycle + state (connecting / alive / dropped / error) with
+      events. → FR-003
+- [ ] **M1.3** Channels: `exec` (run command), **PTY** (interactive shell), **SFTP**
+      (file ops); SFTP-missing → fall back to `exec`. → FR-030/031, Art. 7
+- [ ] **M1.4** SSH host key verification + `known_hosts` policy. → plan §5, Art. 4
+
+### Capability contract (IR)
+
+- [ ] **M1.5** Define the typed contract + core types (`FileEntry`, `Process`,
+      `ServiceState`, `SystemMetrics`, capability-unsupported result). → plan §4
+- [ ] **M1.6** Single **execution point**: every command flows through it and is
+      logged `{command, host, timestamp, exitCode}` (transparency + audit). → FR-013,
+      Art. 3
+- [ ] **M1.7** Parser harness: parse → typed result, with **raw-output fallback**
+      that never throws. → FR-091, Art. 7
+
+### Adapter layer
+
+- [ ] **M1.8** OS detection on connect (`/etc/os-release`, `uname`) + adapter
+      selection, with generic POSIX fallback. → FR-004, Art. 6
+- [ ] **M1.9** **Debian/Ubuntu adapter** (Tier 1) implementing the v1-needed
+      capabilities (`listDir`, `stat`, `readFile`, `writeFile`, `systemMetrics`),
+      preferring machine-readable output. → plan §4, Art. 6/10
+- [ ] **M1.10** Minimal CLI/harness to exercise the core against a real host
+      (manual and automated tests). → plan §6 ("demonstrable")
+
+**M1 done when:** connecting to a real Debian/Ubuntu host, listing a directory and
+reading system metrics return typed results, every command is in the transparency
+log, and a forced parse failure shows raw output without crashing.
+
+---
+
+## M2 — Shell + Terminal + File manager _(outline)_
+
+Desktop shell (windows, taskbar, launcher; FR-010/011/012), Terminal app
+(`xterm.js`, FR-030/031), File manager (browse/CRUD/properties/upload-download,
+FR-020..023), file-open routes + handler registry (FR-025), destructive-action
+confirmations (FR-090). Broken down at the start of M2.
+
+## M3 — Editor + System monitor + transparency UI _(outline)_ → completes v1
+
+Text editor via `readFile`/`writeFile` with unsaved-changes guard (FR-070/071),
+System monitor with periodic refresh (FR-050), transparency surfaced in the UI
+(FR-013), in-flight latency/state indicators (FR-092). Broken down at the start of
+M3. → **🚀 v1 release** after M3.
+
+## Post-v1 _(pointer)_
+
+Admin apps (Processes/Services/Logs/Packages), host tiers (Windows → rest of Linux →
+macOS/FreeBSD → Alpine), encrypted credential store, ssh-agent, drag & drop, hosted
+deployment. See `plan.md §6` and `vision.md`.