rampway 0.2.1

package/docs/migration-from-capistrano.md

@@ -0,0 +1,167 @@
+# Migrating from Capistrano to Rampway
+
+Rampway is a JS-native alternative to Capistrano for Node projects. This guide maps Capistrano concepts to their Rampway equivalents and walks through a migration.
+
+## Quick reference
+
+| Capistrano | Rampway |
+|------------|---------|
+| `config/deploy.rb` | `rampway.config.mjs` |
+| `config/deploy/production.rb` | stage config in `stages.production` |
+| `set :application, "myapp"` | `application: "myapp"` |
+| `set :deploy_to, "/path"` | `deployTo: "/path"` |
+| `set :keep_releases, 5` | `keepReleases: 5` |
+| `set :linked_files, [...]` | `linkedFiles: [...]` |
+| `set :linked_dirs, [...]` | `linkedDirs: [...]` |
+| `server "host", user: "...", roles: [...]` | `hosts: [{host, user, roles}]` |
+| `SSHKit` | `transport: {type: "ssh"}` |
+| `after/before` hooks | `tasks` run in config order, or use lifecycle `hooks` for phase-specific callbacks |
+| `deploy:starting` … `deploy:finished` | task groups + runtime deploy |
+| `cap production deploy` | `rampway deploy production` |
+| `cap production deploy:rollback` | `rampway rollback production` |
+| `current` symlink | same |
+| `releases/` directory | same |
+| `shared/` directory | same |
+| `REVISION` file | `REVISION` + `TRESTLE_RELEASE.json` |
+
+## Step-by-step migration
+
+### 1. Install Rampway
+
+Rampway is a dev dependency in your project:
+
+```bash
+npm install --save-dev rampway
+```
+
+Or run `rampway init` to scaffold a new config.
+
+### 2. Create the config
+
+Run `rampway init` or create `rampway.config.mjs` manually:
+
+```js
+export default {
+  application: "myapp",
+  stages: {
+    production: {
+      deployTo: "/home/dev/myapp",
+      strategy: "local-copy",
+      transport: {type: "ssh"},
+      hosts: [{host: "server.example", user: "dev", roles: ["app", "web"]}],
+      keepReleases: 5,
+    }
+  }
+}
+```
+
+### 3. Convert linked files and dirs
+
+Capistrano:
+
+```ruby
+set :linked_files, %w[.env backend/src/config/secrets.js]
+set :linked_dirs, %w[log tmp/pids tmp/cache storage]
+```
+
+Rampway:
+
+```js
+linkedFiles: [
+  {path: ".env", required: true},
+  {path: "backend/src/config/secrets.js"}
+],
+linkedDirs: ["log", "tmp/pids", "tmp/cache", "storage"],
+```
+
+Rampway linked files can be `required` (fail deploy if missing) or optional (silently skipped).
+
+### 4. Convert hooks to task groups
+
+Capistrano hooks run at specific points in the deploy lifecycle:
+
+```ruby
+after "deploy:published", "restart"
+```
+
+In Rampway, task groups run in config order within the deploy pipeline. No explicit before/after hooks — just order your task groups:
+
+```js
+tasks: {
+  install: [...],
+  migrate: [...],
+  build: [...]
+}
+```
+
+Task groups run after shared links are created, before the runtime handoff and publish. Use task helpers for common Node workflows:
+
+```js
+import {npmInstall, velociousMigrate, onlyIfChanged} from "rampway/tasks"
+
+tasks: {
+  install: [npmInstall({cwd: "backend", production: true})],
+  migrate: [velociousMigrate({cwd: "backend", env: {NODE_ENV: "production"}})]
+}
+```
+
+### 5. Convert process management
+
+Capistrano relies on SSH-based process management (puma, sidekiq, etc.) or custom tasks:
+
+```ruby
+namespace :deploy do
+  task :restart do
+    on roles(:app) do
+      execute :sudo, :systemctl, :restart, "myapp"
+    end
+  end
+end
+```
+
+In Rampway, process management is delegated to a runtime adapter. For Node projects, use Rollbridge:
+
+```js
+runtime: {
+  type: "rollbridge",
+  packageDir: "backend",
+  healthPath: "/health",
+  daemonLogPath: "/home/dev/myapp/shared/log/rollbridge.log",
+  daemonPidPath: "/home/dev/myapp/shared/tmp/pids/rollbridge.pid"
+}
+```
+
+Rollbridge handles zero-downtime restarts, health checks, and log access. Rampway orchestrates the release lifecycle; Rollbridge owns the process.
+
+For simple setups without a process manager, use `runtime: {type: "none"}` and handle process restarts yourself via task commands.
+
+### 6. Run the first deploy
+
+```bash
+# Validate
+rampway validate production
+
+# Plan (dry run)
+rampway plan production
+
+# Deploy
+rampway deploy production --yes
+```
+
+### 7. Verify and cleanup
+
+```bash
+rampway status production
+rampway releases production
+```
+
+After verifying the first deploy works, remove your old Capistrano config files.
+
+## Key differences
+
+- **No Ruby dependency.** Rampway runs on Node.js, matching your JS/TS stack.
+- **Task groups replace hooks.** Order task groups instead of registering `after`/`before` callbacks. For Capistrano-style lifecycle callbacks, use `hooks` with named phases like `before_publish` and `after_cleanup`.
+- **Runtime adapters replace process management tasks.** Rollbridge or a custom adapter handles zero-downtime handoff.
+- **ESM config.** `rampway.config.mjs` uses ES module syntax, not Ruby DSL.
+- **Health checks are built in.** Add `healthChecks` to verify deploy readiness before publishing.
+- **Path-change gating.** Use `onlyIfChanged()` to skip task groups when nothing changed in their paths.

package/docs/roadmap.md

@@ -0,0 +1,27 @@
+# Roadmap
+
+## Epic 1 — Project foundation
+
+- [x] Create GitHub repo and package scaffold
+- [x] Add CLI skeleton and command router
+- [x] Add config loader and validator
+- [x] Add test/lint setup
+- [x] Add README with product goals and MVP scope
+- [ ] Add TensorBuzz project/checks
+
+## Epic 2 — Release lifecycle
+
+- [x] Implement release directory model
+- [x] Implement deploy lock
+- [x] Implement linked files/dirs
+- [x] Implement release metadata
+- [x] Implement current symlink publish
+- [x] Implement cleanup old releases
+- [x] Implement rollback
+
+## Next
+
+1. Add SSH transport with OpenSSH command construction tests.
+2. Expand Rollbridge runtime execution/status/log wrappers.
+3. Add doctor/status diagnostics.
+4. Dogfood with Routergeist staging/local deploy target.

package/examples/local/rampway.config.mjs

@@ -0,0 +1,20 @@
+import path from "node:path"
+
+const deployTo = process.env.RAMPWAY_LOCAL_DEPLOY_TO ?? path.join(process.cwd(), ".rampway-local-target")
+
+export default {
+  application: "rampway-example",
+  stages: {
+    local: {
+      deployTo,
+      strategy: "local-copy",
+      transport: {type: "local"},
+      keepReleases: 2,
+      linkedFiles: [],
+      linkedDirs: ["log", "tmp/pids"],
+      tasks: {},
+      runtime: {type: "none"},
+      healthChecks: [{name: "package", path: "package.json"}]
+    }
+  }
+}

package/examples/monorepo/rampway.config.mjs

@@ -0,0 +1,73 @@
+import path from "node:path"
+import {npmInstall, velociousMigrate, checkExpoWebArtifacts, onlyIfChanged} from "../../src/tasks.js"
+
+const deployRoot = process.env.RAMPWAY_MONOREPO_DEPLOY_TO ?? path.join(process.cwd(), ".rampway-monorepo-target")
+
+export default {
+  application: "rampway-monorepo-example",
+  stages: {
+    local: {
+      deployTo: deployRoot,
+      strategy: "local-copy",
+      transport: {type: "local"},
+      keepReleases: 2,
+      linkedFiles: [],
+      linkedDirs: ["log", "tmp/pids"],
+      tasks: {
+        install: [
+          onlyIfChanged(["backend"], npmInstall({cwd: "backend", production: true})),
+          onlyIfChanged(["app"], npmInstall({cwd: "app"}))
+        ],
+        migrate: [
+          onlyIfChanged(["backend"], velociousMigrate({cwd: "backend", env: {NODE_ENV: "production"}}))
+        ],
+        build: [
+          "cd app && npm run web:export",
+          checkExpoWebArtifacts({dir: "app/dist"})
+        ]
+      },
+      runtime: {type: "none"},
+      healthChecks: [{name: "backend-package", path: "backend/package.json"}]
+    },
+    production: {
+      deployTo: "/home/dev/myapp",
+      strategy: "local-copy",
+      transport: {type: "ssh"},
+      hosts: [{host: "server.example", user: "dev", roles: ["app", "web"]}],
+      keepReleases: 5,
+      linkedFiles: [
+        {path: "backend/src/config/secrets.js", required: true},
+        {path: ".env", required: true}
+      ],
+      linkedDirs: ["log", "tmp/pids", "tmp/cache", "storage"],
+      tasks: {
+        install: [
+          onlyIfChanged(["backend"], npmInstall({cwd: "backend", production: true})),
+          onlyIfChanged(["app"], npmInstall({cwd: "app", production: true}))
+        ],
+        migrate: [
+          onlyIfChanged(["backend"], velociousMigrate({cwd: "backend", env: {NODE_ENV: "production"}}))
+        ],
+        build: [
+          "cd app && npm run web:export",
+          checkExpoWebArtifacts({dir: "app/dist"})
+        ]
+      },
+      runtime: {
+        type: "rollbridge",
+        command: "npx rollbridge",
+        packageDir: "backend",
+        config: "backend/config/rollbridge.production.mjs",
+        healthPath: "/health",
+        daemonLogPath: "/home/dev/myapp/shared/log/rollbridge.log",
+        daemonPidPath: "/home/dev/myapp/shared/tmp/pids/rollbridge.pid",
+        socketPath: "/tmp/rollbridge-myapp.sock",
+        versionPath: "/home/dev/myapp/shared/tmp/rollbridge-version"
+      },
+      healthChecks: [
+        {name: "backend-package", path: "backend/package.json"},
+        {name: "app-package", path: "app/package.json"}
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "rampway",
+  "version": "0.2.1",
+  "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
+  "type": "module",
+  "private": false,
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaspernj/rampway.git"
+  },
+  "homepage": "https://github.com/kaspernj/rampway#readme",
+  "bugs": {
+    "url": "https://github.com/kaspernj/rampway/issues"
+  },
+  "author": "Kasper Johansen",
+  "keywords": [
+    "deploy",
+    "deployment",
+    "capistrano",
+    "release",
+    "release-directory",
+    "rollback",
+    "monorepo",
+    "node",
+    "expo",
+    "velocious",
+    "rollbridge",
+    "zero-downtime"
+  ],
+  "bin": {
+    "rampway": "build/src/cli.js"
+  },
+  "main": "build/src/tasks.js",
+  "types": "build/src/tasks.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/src/tasks.d.ts",
+      "default": "./build/src/tasks.js"
+    },
+    "./tasks": {
+      "types": "./build/src/tasks.d.ts",
+      "default": "./build/src/tasks.js"
+    },
+    "./tasks.js": {
+      "types": "./build/src/tasks.d.ts",
+      "default": "./build/src/tasks.js"
+    },
+    "./test-helpers": {
+      "types": "./build/src/test-helpers.d.ts",
+      "default": "./build/src/test-helpers.js"
+    },
+    "./test-helpers.js": {
+      "types": "./build/src/test-helpers.d.ts",
+      "default": "./build/src/test-helpers.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#types": "./build/src/types.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "npm run build && node --test tests/**/*.test.js",
+    "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "clean": "node scripts/clean.js",
+    "compile": "tsc -b",
+    "postcompile": "node scripts/ensure-cli-executable.js",
+    "build": "npm run clean && npm run compile",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-jsdoc": "^61.5.0",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "build",
+    "examples",
+    "docs",
+    "README.md"
+  ]
+}