deskssh 0.0.1

package/README.md

@@ -0,0 +1,66 @@
+<h1 align="center">DeskSSH</h1>
+
+<p align="center">
+  <strong>A graphical desktop over plain SSH.</strong><br>
+  The GUI is synthesized on the client; every action is translated into commands
+  executed on the remote host. <em>It is not remote desktop.</em>
+</p>
+
+---
+
+## What is it?
+
+You connect via SSH to a server **with no graphical environment** and DeskSSH
+shows you a familiar desktop —file manager, terminal, system monitor, editor,
+service manager…—. Behind the scenes, every click runs the equivalent command
+(`ls`, `stat`, `mv`, `systemctl`, `ps`…) and the interface is built from its
+output.
+
+### What makes it different
+
+- **Not VNC/RDP/X.** No pixels travel: the GUI is generated locally.
+- **Agentless.** Installs nothing on the server; only needs SSH and standard POSIX
+  utilities.
+- **Transparent.** You can always see the command behind each action.
+- **100% open source.**
+
+## Origin and motivation
+
+DeskSSH started as a project in **ASP.NET with .NET 8**. As it grew, I felt
+overwhelmed by the sheer number of commands and cases the tool could end up
+covering. I began reviewing and improving the code with the help of AI, but ended
+up making a more radical decision: **restart the project from scratch**, also with
+AI, in order to:
+
+- use languages and technologies **more widely accepted by the community**, and
+- leverage **npm's ease of distribution** for simple adoption.
+
+This rewrite is developed with **Spec-Driven Development**: decisions are
+documented in `specs/` before any code is written.
+
+The reason for making it **open source** is simple: I want DeskSSH to become a
+**genuinely useful and popular** tool, built and improved by the community.
+
+## Status
+
+🚧 **In design.** The project is developed with **Spec-Driven Development**: right
+now only the specification exists; code comes later. Start with:
+
+- [`specs/vision.md`](specs/vision.md) — the why and the where-to (the vision).
+- [`specs/constitution.md`](specs/constitution.md) — the project's principles.
+- [`specs/001-core/spec.md`](specs/001-core/spec.md) — what DeskSSH does.
+- [`specs/001-core/plan.md`](specs/001-core/plan.md) — how it will be built.
+- [`specs/glossary.md`](specs/glossary.md) — the domain vocabulary.
+
+## How to contribute
+
+This project follows SDD: design discussions happen in `specs/` **before** they
+reach the code. To propose something, open the conversation on the relevant
+document. (Detailed contribution guide: pending — `M0`.)
+
+## License
+
+[**GNU AGPL-3.0-or-later**](LICENSE). Strong copyleft with a network clause: if you
+modify DeskSSH and offer it as a network-accessible service, you must publish your
+changes. Chosen so the project and all its improvements stay free. See
+[`specs/constitution.md`](specs/constitution.md), Article 9.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "deskssh",
+  "version": "0.0.1",
+  "private": false,
+  "description": "A graphical desktop over plain SSH — workspace root",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "scripts": {
+    "build": "pnpm -r build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.13.0",
+    "@typescript-eslint/parser": "^7.13.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.3.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "main": "index.js",
+  "dependencies": {
+    "eslint-scope": "^7.2.2",
+    "eslint-visitor-keys": "^3.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nestorrguez/DeskSSH.git"
+  },
+  "keywords": [
+    "ssh",
+    "desk",
+    "gui",
+    "client"
+  ],
+  "author": "Nestor Rodriguez",
+  "bugs": {
+    "url": "https://github.com/nestorrguez/DeskSSH/issues"
+  },
+  "homepage": "https://github.com/nestorrguez/DeskSSH#readme"
+}

package/packages/cli/README.md

@@ -0,0 +1,11 @@
+# DeskSSH
+
+**A graphical desktop over plain SSH.** The GUI is synthesized on the client and
+every action is translated into commands executed on the remote host. _Not remote
+desktop. Agentless._
+
+> ⚠️ **Early development — not yet functional.** This `0.0.1` reserves the package
+> name and provides the future `deskssh` launch command. Follow progress on GitHub.
+
+- Repository & docs: https://github.com/nestorrguez/DeskSSH
+- License: **AGPL-3.0-or-later**

package/packages/cli/bin/deskssh.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// DeskSSH CLI — placeholder for the self-hosted (npm) distribution.
+// DeskSSH is in early development and not yet functional; this entry exists to
+// reserve the package name and provide the future `deskssh` launch command.
+
+console.log(`DeskSSH 0.0.1 — early development, not yet functional.
+
+A graphical desktop over plain SSH: the GUI is synthesized client-side and
+every action maps to remote commands. Not remote desktop. Agentless.
+
+Follow progress: https://github.com/nestorrguez/DeskSSH
+`);

package/packages/cli/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "deskssh",
+  "version": "0.0.1",
+  "description": "A graphical desktop over plain SSH. Early development — not yet functional.",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "deskssh": "bin/deskssh.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "ssh",
+    "sftp",
+    "gui",
+    "desktop",
+    "sysadmin",
+    "devops",
+    "agentless"
+  ],
+  "homepage": "https://github.com/nestorrguez/DeskSSH",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nestorrguez/DeskSSH.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nestorrguez/DeskSSH/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "true"
+  }
+}

package/packages/core/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare const CORE_PACKAGE = "@deskssh/core";
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,YAAY,kBAAkB,CAAC"}

package/packages/core/dist/index.js

@@ -0,0 +1,6 @@
+// @deskssh/core — frontend-agnostic core.
+// SSH sessions, OS adapters and the capability contract live here (M1).
+// This file is the public surface of the package; it stays intentionally small
+// and re-exports the stable API as it lands.
+export const CORE_PACKAGE = '@deskssh/core';
+//# sourceMappingURL=index.js.map

package/packages/core/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,wEAAwE;AACxE,+EAA+E;AAC/E,6CAA6C;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC"}

package/packages/core/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@deskssh/core",
+  "version": "0.0.1",
+  "description": "DeskSSH frontend-agnostic core: SSH sessions, OS adapters, capability contract",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/packages/core/src/index.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { CORE_PACKAGE } from './index';
+
+describe('@deskssh/core', () => {
+  it('exposes its package name', () => {
+    expect(CORE_PACKAGE).toBe('@deskssh/core');
+  });
+});

package/packages/core/src/index.ts

@@ -0,0 +1,6 @@
+// @deskssh/core — frontend-agnostic core.
+// SSH sessions, OS adapters and the capability contract live here (M1).
+// This file is the public surface of the package; it stays intentionally small
+// and re-exports the stable API as it lands.
+
+export const CORE_PACKAGE = '@deskssh/core';

package/packages/core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts"]
+}

package/packages/server/dist/index.d.ts

@@ -0,0 +1,3 @@
+export declare const SERVER_PACKAGE = "@deskssh/server";
+export declare const CORE_DEPENDENCY = "@deskssh/core";
+//# sourceMappingURL=index.d.ts.map

package/packages/server/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,eAAO,MAAM,eAAe,kBAAe,CAAC"}

package/packages/server/dist/index.js

@@ -0,0 +1,7 @@
+// @deskssh/server — web gateway.
+// Holds live SSH sessions, authenticates the gateway user and exposes the API
+// (HTTP for one-off actions, WebSocket for PTY and streams). Built on @deskssh/core.
+import { CORE_PACKAGE } from '@deskssh/core';
+export const SERVER_PACKAGE = '@deskssh/server';
+export const CORE_DEPENDENCY = CORE_PACKAGE;
+//# sourceMappingURL=index.js.map

package/packages/server/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,8EAA8E;AAC9E,qFAAqF;AAErF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC"}

package/packages/server/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@deskssh/server",
+  "version": "0.0.1",
+  "description": "DeskSSH web gateway: keeps SSH sessions alive and exposes the API",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@deskssh/core": "workspace:*"
+  }
+}

package/packages/server/src/index.ts

@@ -0,0 +1,8 @@
+// @deskssh/server — web gateway.
+// Holds live SSH sessions, authenticates the gateway user and exposes the API
+// (HTTP for one-off actions, WebSocket for PTY and streams). Built on @deskssh/core.
+
+import { CORE_PACKAGE } from '@deskssh/core';
+
+export const SERVER_PACKAGE = '@deskssh/server';
+export const CORE_DEPENDENCY = CORE_PACKAGE;

package/packages/server/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts"],
+  "references": [{ "path": "../core" }]
+}