deskssh 0.0.1 → 0.0.2

package/specs/001-core/tasks.md

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

package/specs/constitution.md

@@ -1,110 +0,0 @@
-# DeskSSH Constitution
-
-**Non-negotiable** principles. Every spec, plan, task or line of code must respect
-them. If anything conflicts with the constitution, the constitution wins; changing
-it requires an explicit amendment in this document (with date and reason).
-
-Last revised: 2026-06-25.
-
----
-
-## Article 1 — No remote desktop (the premise)
-
-DeskSSH **does not transmit pixels** nor reuse the server's graphical environment.
-It is not VNC, RDP, X-forwarding, SPICE or similar. The interface is
-**synthesized on the client** from data obtained over SSH. Any proposal that
-violates this is out of scope, however useful it may seem.
-
-## Article 2 — Agentless
-
-DeskSSH **installs no software, agents or daemons** on the remote host. It assumes
-only:
-
-- a running SSH server, and
-- standard POSIX/Unix utilities already present (`sh`, `ls`, `stat`, `ps`, `df`, …).
-
-If a feature needs something non-standard, it must **degrade gracefully** (offer
-less, not fail) and never require changes on the server.
-
-## Article 3 — Command transparency
-
-The user can always **see the command** a GUI action is about to run (or has run).
-DeskSSH is an administration tool, not a black box: showing the command builds
-trust and, along the way, teaches the command line. Raw output must always be
-accessible.
-
-## Article 4 — Security is not optional
-
-- Secrets (passwords, passphrases, private keys) are never stored in plain text nor
-  appear in logs.
-- **Least privilege**: DeskSSH acts with the SSH user's permissions; it never
-  escalates privileges on its own.
-- In the web model, the backend is an **SSH gateway**: treated as a critical
-  component (authentication, session isolation, auditing).
-- Every destructive operation (delete, overwrite, kill processes, stop services)
-  requires **explicit user confirmation**.
-
-## Article 5 — Frontend-agnostic core
-
-The logic (SSH sessions, OS adapters, parsers, "app" definitions) lives in a **core
-independent of presentation**. This allows serving a web app and, with the same
-core, delivering it either hosted or self-hosted (npm). No business rule lives in
-UI components.
-
-## Article 6 — Portability through adapters
-
-Servers differ (Debian/Ubuntu, RHEL/Fedora, Arch, BSD; `bash`/`sh`; GNU vs BSD
-coreutils). The differences are isolated in an **adapter layer**. The rest of the
-system talks to a uniform interface and assumes no specific distro. Machine-
-readable output (`stat -c`, `ps -eo`, `--json` flags where available) is preferred
-over parsing human-formatted text.
-
-## Article 7 — Resilience and graceful degradation
-
-Server diversity makes parsing fail sometimes. A parsing failure must **never**
-crash the app: the raw output is shown and we move on. Every round trip may fail or
-be slow; the UI reflects this without freezing.
-
-## Article 8 — Latency-aware performance
-
-Every GUI action is, potentially, a network round trip. The design must **minimize
-round trips** (batching, listing caches, optimistic UI) and never assume zero
-latency.
-
-## Article 9 — 100% open source and contributor-friendly
-
-DeskSSH is and will remain fully open source under **AGPL-3.0-or-later**. AGPL
-(strong copyleft with a network clause) is chosen precisely because the project is
-web-first: it guarantees that any improvement, even when offered only as a
-network-accessible service, comes back to the community. A low barrier to entry for
-contributors is also prioritized: mainstream stack, documentation in `specs/`,
-explained and traceable decisions. No proprietary dependencies on the critical
-path, nor licenses incompatible with AGPL-3.0.
-
-## Article 10 — Non-interactive, structured primitives
-
-DeskSSH **does not drive remote interactive tools** (nano, vim, top, etc.) by
-sending them keystrokes over a PTY: it is fragile, version-dependent and impossible
-to normalize across platforms. Instead, every feature is built on **non-interactive,
-structured-output primitives** defined in the capability contract (e.g.
-`readFile`/`writeFile` instead of launching a remote editor), and the experience is
-**emulated on the client**. Asking for machine-readable output is always preferred
-over parsing human-formatted text.
-
-The **only deliberate exception** is the **terminal** app, which exposes the raw
-shell on purpose (where the user does see `bash`/`PowerShell`/`csh`).
-
-This article is the foundation that makes Article 6's portability viable: without
-structured output, the capability contract could not normalize across OSes.
-
----
-
-## Amendments
-
-- _(none yet)_
-
-## Closed decisions
-
-- **License: AGPL-3.0-or-later** (decided 2026-06-25). Closes the GPL's "network
-  loophole", consistent with the web-first model and the goal of keeping the
-  project 100% open. See Article 9 and the `LICENSE` file.

package/specs/glossary.md

@@ -1,35 +0,0 @@
-# DeskSSH Glossary
-
-Domain vocabulary. DeskSSH constantly translates between two worlds —the **desktop
-metaphor** and **system commands**— so a shared language avoids confusion.
-
-| Term                          | Definition                                                                                                           |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| **Host**                      | A remote server connected to via SSH. Has credentials, address, port and an associated OS adapter.                   |
-| **Session**                   | A live SSH connection to a host, able to run commands and open channels (PTY, SFTP).                                 |
-| **Core**                      | Frontend-agnostic logic: session management, adapters, parsers and app definitions.                                  |
-| **OS adapter**                | A module that knows the specifics of a system family (commands, flags, paths) and exposes a uniform interface.       |
-| **Desktop app**               | An "application" inside DeskSSH (file manager, terminal, monitor…). Each maps GUI actions to command sets.           |
-| **Action**                    | A user interaction (double click, drag, button) that resolves into one or more remote commands.                      |
-| **VFS (Virtual File System)** | The view of the remote filesystem that the client builds and caches from `ls`/`stat`/SFTP.                           |
-| **Desktop shell**             | The UI layer that draws windows, taskbar, launcher and icons. The "face" of DeskSSH.                                 |
-| **Command transparency**      | The ability to inspect the exact command behind each action (see Constitution, Art. 3).                              |
-| **Round trip**                | A request→execute→response cycle against the remote host. The unit of latency cost.                                  |
-| **Graceful degradation**      | Offering less functionality (not failing) when the remote doesn't support something.                                 |
-| **Backend / gateway**         | In the web model, the service that keeps SSH sessions alive and serves the UI. The browser never opens SSH directly. |
-
-## Metaphor ↔ command map (illustrative, not exhaustive)
-
-| Desktop action       | Equivalent command(s) (indicative)                    |
-| -------------------- | ----------------------------------------------------- |
-| Open folder          | `ls`, `stat -c` / SFTP `readdir`                      |
-| File properties      | `stat`, `file`, `getfacl`                             |
-| Copy / move / delete | `cp` / `mv` / `rm` (with confirmation)                |
-| Create folder        | `mkdir`                                               |
-| Open terminal        | PTY channel over SSH                                  |
-| Task manager         | `ps -eo`, `top -b -n1`, `kill`                        |
-| System monitor       | `free`, `df`, `uptime`, `cat /proc/...`               |
-| Service manager      | `systemctl list-units`, `systemctl start/stop/status` |
-| Log viewer           | `journalctl`, `tail -f` over a channel                |
-| Text editor          | read via SFTP/`cat`, save via SFTP                    |
-| Network connections  | `ss -tulpn`, `ip a`                                   |

package/specs/vision.md

@@ -1,145 +0,0 @@
-# DeskSSH Vision
-
-> The project's north: the _why_ and the _where-to_. More aspirational than
-> `spec.md`/`plan.md`, but consistent with `constitution.md`.
-> Last revised: 2026-06-26.
-
-## Purpose
-
-To make administering and using a Linux server over SSH **as accessible as a
-lifelong desktop**: installing nothing on the server, transmitting no pixels and
-losing no transparency. DeskSSH is the GUI for those whom the terminal intimidates
-— and the convenience for those it doesn't.
-
-## North star (the scenario we pursue)
-
-A company **stops paying** for expensive, slow, heavy remote-desktop systems.
-Instead it has a simple **headless SSH server** and gives its employees **DeskSSH**:
-they log in, work with a familiar interface and feel comfortable, without anyone
-needing to master the console. Adoption grows so much that third parties want to
-integrate — e.g. **OnlyOffice ships an extension** for DeskSSH and office documents
-are handled from there.
-
-That scenario sums up the project's three bets: **accessibility**, **trust
-(security)** and **ecosystem**.
-
-## Primary user
-
-A person with **low CLI fluency** (see `spec.md §5`). v1 prioritizes accessibility:
-safe, guided defaults, plain language, the terminal as a last resort and
-transparency (Art. 3) on demand, not as the protagonist.
-
-## v1 ambition
-
-A **focused, polished** cut —better small and round than large and half-baked—:
-connection/hosts, desktop shell, file manager, editor, terminal and system monitor
-(see `plan.md §6`). The "full desktop" is earned iteration by iteration, not all at
-once.
-
-## Success criteria
-
-What "popular and useful" means to us (in this order):
-
-1. **Real usage** — people and **teams actually using it** on their servers; visible
-   traction (npm downloads, active deployments). This is priority #1.
-2. **Ecosystem** — third parties contributing **apps/handlers and adapters**; the
-   emblematic case is an **OnlyOffice-style** integration for office documents.
-
-> `[TBD]` concrete metrics/deadlines (stars, number of users, date). For now success
-> is defined **qualitatively**, not by numbers.
-
-## Ecosystem and extensibility
-
-The OnlyOffice scenario **is not magic**: it is the extensibility already seeded in
-the architecture.
-
-- The **file-type handler registry** + "Open with" (FR-025) is the hook point: a
-  third party registers a handler for `.docx/.xlsx` that delegates to its engine
-  (e.g. an OnlyOffice Document Server).
-- The **capability contract** (IR) lets new **platforms** be added by filling in
-  manifests, not rewriting (see `plan.md §4`).
-- The **third-party app/plugin store** is out of v1, but the architecture is
-  designed **not to close the door** on it.
-
-> Honest reality-check: the "company without remote desktop" scenario raises the bar
-> on **gateway security** (multi-user, auth, isolation, auditing), which is already
-> the project's biggest risk (`plan.md §5, §7`). Trust is a **requirement, not an
-> extra**, for that vision.
-
-## Host roadmap (the reach ambition)
-
-To reach **Windows, macOS, \*BSD and a wide range of Linux distributions** as remote
-host, without the user noticing the difference (unless they open the terminal).
-Prioritized by **popularity**, not difficulty (see the tier matrix in `plan.md §4`).
-
-## Ideas under exploration
-
-> Seedbed: ideas captured **without commitment**. 💡 = from the author · 🔹 =
-> suggested for consideration. Those marked **→** could graduate to
-> `spec.md`/`plan.md`.
-
-### Desktop experience
-
-- 💡 **Mirror the remote desktop:** show the same desktop as the remote machine (its
-  `~/Desktop` folder); if it doesn't exist (headless server), use desktop
-  preferences **stored locally** per user/host.
-- 💡 **Streaming open:** open certain files via _streaming_ (partial SFTP reads)
-  without downloading them whole, with a **loading screen** and latency-aware UI
-  (Art. 8). **→** extends FR-025.
-- 💡 **"Everything from DeskSSH":** the user shouldn't need to fall back to the OS —
-  including **viewing installed apps and installing/uninstalling** per their
-  permissions (the Packages app, _post-v1_; privilege/`sudo`-sensitive, Art. 4).
-- 🔹 **Trash + undo:** delete moves to trash instead of a direct `rm`; a key safety
-  net for a non-technical user.
-- 🔹 **Global search** (files, apps, actions) and **favorites/shortcuts** to servers
-  and folders.
-- 🔹 **Learning mode:** show and explain the command behind each action (supports
-  Art. 3 in an educational way).
-- 🔹 **i18n** from early on (to be "popular" at global scale) and **real
-  accessibility** (keyboard, screen readers), consistent with the project's
-  inclusive spirit.
-
-### Integrations and extensions
-
-- 💡 **Office documents (OnlyOffice):** third-party handler for `.docx/.xlsx`
-  delegating to an OnlyOffice Document Server — the emblematic case of the north
-  star.
-- 💡 **VSCode-like code editor:** via **Monaco** (VSCode's editor) as a handler for
-  code files. _(Note: "VSCode Remote-SSH" is a different product; here we mean
-  embedding its editor.)_
-- 💡 **HTML/web view** ("Chromium" idea): a handler that previews `.html` and
-  similar. Since DeskSSH is a web app, **a sandboxed `<iframe>` is enough** to have a
-  "browser" (remote content = risk → isolate well).
-- 💡 **Chrome-like extension system:** clear rules, a **manifest**, an **extension
-  store** and third-party extensions (at least in the local version). **→** The
-  **permission/security model** is the hard core: an extension that runs SSH
-  commands is as powerful as the user; it needs declared permissions, isolation and
-  (for the store) review/signing.
-- 🔹 Other natural handler integrations: **Git**, **Docker/containers**,
-  **databases** — all as apps/extensions.
-
-### Distribution, community and sustainability
-
-- 💡 **Two usage forms** (almost architecture, **→** `plan.md`):
-  - **Hosted web:** an SSH client for servers with an open internet connection.
-  - **Local via npm:** for SSH servers **only reachable over LAN**; self-hosted. The
-    hosted web links to this installation.
-- 💡 **Repository system** for apps/extensions: one for the web version and a
-  freely-installable one for the local version.
-- 💡 **"How to build extensions" docs** and the **GitHub** page as the collaboration
-  hub.
-- 💡 **Donations** to sustain the project (GitHub Sponsors / OpenCollective).
-- 💡 **Community space** for users to propose their needs and ideas (feature requests
-  / discussions) — **instead of telemetry**, consistent with trust and the
-  open-source spirit.
-- 🔹 **Trust note:** a hosted instance that **relays SSH** to internet-exposed
-  servers is the scenario of **maximum security responsibility** and a juicy target;
-  many will prefer the local/LAN version. The two modes serve different trust
-  appetites.
-
-## Anti-vision (what we do NOT want to be)
-
-- **Not** a remote desktop / VNC / RDP (transmitting pixels).
-- **Not** an admin panel that requires installing an agent on the server.
-- **Not** a tool only for power users (that already exists).
-- **Not** a "half-everything": we prefer a few excellent apps.

package/tsconfig.base.json

@@ -1,23 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "composite": true,
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
-    "verbatimModuleSyntax": true
-  }
-}

package/tsconfig.json

@@ -1,4 +0,0 @@
-{
-  "files": [],
-  "references": [{ "path": "./packages/core" }, { "path": "./packages/server" }]
-}

package/vitest.config.ts

@@ -1,7 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    include: ['packages/*/src/**/*.{test,spec}.ts'],
-  },
-});