npm - deskssh - Versions diffs - 0.0.1 → 0.0.2 - Mend

deskssh 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/README.md +8 -63
package/package.json +24 -38
package/.eslintrc.cjs +0 -21
package/.github/workflows/ci.yml +0 -40
package/.prettierignore +0 -5
package/.prettierrc.json +0 -6
package/CONTRIBUTING.md +0 -59
package/LICENSE +0 -661
package/packages/cli/README.md +0 -11
package/packages/cli/package.json +0 -37
package/packages/core/dist/index.d.ts +0 -2
package/packages/core/dist/index.d.ts.map +0 -1
package/packages/core/dist/index.js +0 -6
package/packages/core/dist/index.js.map +0 -1
package/packages/core/package.json +0 -22
package/packages/core/src/index.test.ts +0 -8
package/packages/core/src/index.ts +0 -6
package/packages/core/tsconfig.json +0 -9
package/packages/server/dist/index.d.ts +0 -3
package/packages/server/dist/index.d.ts.map +0 -1
package/packages/server/dist/index.js +0 -7
package/packages/server/dist/index.js.map +0 -1
package/packages/server/package.json +0 -19
package/packages/server/src/index.ts +0 -8
package/packages/server/tsconfig.json +0 -10
package/packages/web/dist/assets/index-DNUNZ8WK.js +0 -65
package/packages/web/dist/index.html +0 -12
package/packages/web/index.html +0 -12
package/packages/web/node_modules/.bin/browserslist +0 -17
package/packages/web/node_modules/.bin/vite +0 -17
package/packages/web/package.json +0 -27
package/packages/web/src/App.tsx +0 -17
package/packages/web/src/i18n/en.ts +0 -8
package/packages/web/src/i18n/es.ts +0 -7
package/packages/web/src/i18n/index.ts +0 -27
package/packages/web/src/main.tsx +0 -12
package/packages/web/tsconfig.json +0 -14
package/packages/web/vite.config.ts +0 -6
package/pnpm-workspace.yaml +0 -2
package/specs/001-core/plan.md +0 -246
package/specs/001-core/spec.md +0 -206
package/specs/001-core/tasks.md +0 -110
package/specs/constitution.md +0 -110
package/specs/glossary.md +0 -35
package/specs/vision.md +0 -145
package/tsconfig.base.json +0 -23
package/tsconfig.json +0 -4
package/vitest.config.ts +0 -7
/package/{packages/cli/bin → bin}/deskssh.js +0 -0

package/packages/web/dist/index.html DELETED Viewed

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>DeskSSH</title>
-    <script type="module" crossorigin src="/assets/index-DNUNZ8WK.js"></script>
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>

package/packages/web/index.html DELETED Viewed

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>DeskSSH</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

package/packages/web/node_modules/.bin/browserslist DELETED Viewed

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/browserslist@4.28.4/node_modules/browserslist/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/browserslist@4.28.4/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/browserslist@4.28.4/node_modules/browserslist/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/browserslist@4.28.4/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../../../../node_modules/.pnpm/browserslist@4.28.4/node_modules/browserslist/cli.js" "$@"
-else
-  exec node  "$basedir/../../../../node_modules/.pnpm/browserslist@4.28.4/node_modules/browserslist/cli.js" "$@"
-fi

package/packages/web/node_modules/.bin/vite DELETED Viewed

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules/vite/bin/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules/vite/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules/vite/bin/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules/vite/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/vite@5.4.21_@types+node@20.19.43/node_modules:/home/nestor/Proyectos/DeskSSH/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"
-else
-  exec node  "$basedir/../vite/bin/vite.js" "$@"
-fi

package/packages/web/package.json DELETED Viewed

@@ -1,27 +0,0 @@
-{
-  "name": "@deskssh/web",
-  "version": "0.0.1",
-  "description": "DeskSSH browser UI: the desktop shell and app views",
-  "license": "AGPL-3.0-or-later",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc --noEmit && vite build",
-    "preview": "vite preview",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
-  "dependencies": {
-    "@deskssh/core": "workspace:*",
-    "lucide-react": "^0.395.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.1",
-    "vite": "^5.3.1"
-  }
-}

package/packages/web/src/App.tsx DELETED Viewed

@@ -1,17 +0,0 @@
-import { useMemo } from 'react';
-import { TerminalSquare } from 'lucide-react';
-import { detectLocale, translate } from './i18n';
-export function App() {
-  const locale = useMemo(() => detectLocale(), []);
-  return (
-    <main>
-      <h1>
-        <TerminalSquare aria-hidden /> DeskSSH
-      </h1>
-      <p>{translate(locale, 'app.tagline')}</p>
-      <small>{translate(locale, 'app.status.scaffolding')}</small>
-    </main>
-  );
-}

package/packages/web/src/i18n/en.ts DELETED Viewed

@@ -1,8 +0,0 @@
-// English catalog (source of truth). Every user-facing string lives here so the
-// UI is i18n-ready from day 1 (constitution-aligned: EN + ES ship in v1).
-export const en = {
-  'app.tagline': 'A graphical desktop over plain SSH',
-  'app.status.scaffolding': 'Scaffolding — no functionality yet',
-} as const;
-export type MessageKey = keyof typeof en;

package/packages/web/src/i18n/es.ts DELETED Viewed

@@ -1,7 +0,0 @@
-import type { MessageKey } from './en';
-// Spanish catalog. Must cover every MessageKey (enforced by the Record type).
-export const es: Record<MessageKey, string> = {
-  'app.tagline': 'Un escritorio gráfico sobre SSH puro',
-  'app.status.scaffolding': 'Andamiaje — todavía sin funcionalidad',
-};

package/packages/web/src/i18n/index.ts DELETED Viewed

@@ -1,27 +0,0 @@
-import { en, type MessageKey } from './en';
-import { es } from './es';
-export type Locale = 'en' | 'es';
-const catalogs: Record<Locale, Record<MessageKey, string>> = { en, es };
-export const SUPPORTED_LOCALES: readonly Locale[] = ['en', 'es'];
-export const DEFAULT_LOCALE: Locale = 'en';
-/** Pick the best supported locale from the browser, falling back to English. */
-export function detectLocale(
-  preferred: readonly string[] = typeof navigator !== 'undefined' ? navigator.languages : [],
-): Locale {
-  for (const lang of preferred) {
-    const base = lang.toLowerCase().split('-')[0];
-    if (base && SUPPORTED_LOCALES.includes(base as Locale)) return base as Locale;
-  }
-  return DEFAULT_LOCALE;
-}
-/** Translate a key for a locale. Missing translations fall back to English. */
-export function translate(locale: Locale, key: MessageKey): string {
-  return catalogs[locale][key] ?? en[key];
-}
-export type { MessageKey };

package/packages/web/src/main.tsx DELETED Viewed

@@ -1,12 +0,0 @@
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { App } from './App';
-const container = document.getElementById('root');
-if (!container) throw new Error('Root element #root not found');
-createRoot(container).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-);

package/packages/web/tsconfig.json DELETED Viewed

@@ -1,14 +0,0 @@
-{
-  "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 DELETED Viewed

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

package/pnpm-workspace.yaml DELETED Viewed

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

package/specs/001-core/plan.md DELETED Viewed

@@ -1,246 +0,0 @@
-# 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 DELETED Viewed

@@ -1,206 +0,0 @@
-# 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`).