rampway 0.2.1

package/build/src/types.d.ts

@@ -0,0 +1,290 @@
+export type TransportConfig = {
+    type: "local" | "ssh";
+    host?: string | undefined;
+    user?: string | undefined;
+    port?: number | undefined;
+    identityFile?: string | undefined;
+    sshOptions?: string[] | undefined;
+    extra?: Record<string, unknown> | undefined;
+};
+export type LinkedEntry = {
+    path: string;
+    required: boolean;
+};
+export type HealthCheckEntry = {
+    name?: string | undefined;
+    path?: string | undefined;
+    command?: string | undefined;
+};
+export type RuntimeConfig = {
+    type: string;
+    command?: string | undefined;
+    packageDir?: string | undefined;
+    config?: string | undefined;
+    daemonLogPath?: string | undefined;
+    daemonPidPath?: string | undefined;
+    daemonStartTimeoutMs?: number | undefined;
+    socketPath?: string | undefined;
+    versionPath?: string | undefined;
+};
+export type TaskEntry = {
+    name?: string | undefined;
+    command: string;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    optional?: boolean | undefined;
+    onlyIfChanged?: string[] | undefined;
+};
+export type TaskResult = {
+    name: string;
+    command: string;
+    optional?: boolean | undefined;
+    status: "passed" | "failed" | "skipped";
+    error?: string | undefined;
+    skipReason?: string | undefined;
+};
+export type StageConfig = {
+    application: string;
+    stageName: string;
+    repo?: string | undefined;
+    branch: string;
+    revision?: string | undefined;
+    deployTo: string;
+    strategy: "local-copy" | "remote-git" | "archive-upload";
+    transport: TransportConfig;
+    hosts?: {
+        host: string;
+        user?: string;
+        port?: number;
+        roles?: string[];
+    }[] | undefined;
+    keepReleases: number;
+    linkedFiles: LinkedEntry[];
+    linkedDirs: LinkedEntry[];
+    tasks: Record<string, TaskEntry[]>;
+    hooks: Record<string, TaskEntry[]>;
+    healthChecks: HealthCheckEntry[];
+    runtime: RuntimeConfig;
+};
+export type DeployPaths = {
+    deployTo: string;
+    releasesPath: string;
+    sharedPath: string;
+    currentPath: string;
+    lockPath: string;
+    statePath: string;
+    reportPath: string;
+    releasePath?: string | undefined;
+};
+export type DeployPlanStep = {
+    phase: string;
+    action: string;
+    name?: string | undefined;
+    detail: string;
+};
+export type DeployReport = {
+    application: string;
+    stage: string;
+    releaseId: string;
+    revision: string;
+    branch?: string | undefined;
+    deployedAt?: string | undefined;
+    event: string;
+    durationMs?: number | undefined;
+    previousRelease?: string | undefined;
+    healthChecks?: string | undefined;
+    runtime?: object | undefined;
+    cleanupRemoved?: string[] | undefined;
+};
+export type RollbackReport = {
+    application: string;
+    stage: string;
+    releaseId: string;
+    rolledBackAt: string;
+    previousRelease?: string | undefined;
+    event: string;
+};
+export type ReleasesReport = {
+    application: string;
+    stage: string;
+    current: string | null;
+    releases: string[];
+    releaseCount: number;
+    paths: {
+        releases: string;
+        current: string;
+    };
+};
+export type StatusReport = {
+    application: string;
+    stage: string;
+    deployTo: string;
+    current: string | null;
+    releases: string[];
+    releaseCount: number;
+    latestRelease: string | undefined;
+    paths: {
+        current: string;
+        releases: string;
+        shared: string;
+        lock: string;
+    };
+    runtime: {
+        type: string;
+    };
+};
+export type DoctorReport = {
+    ok: boolean;
+    configPath: string;
+    application: string;
+    stage: string;
+    deployTo: string;
+    transport: {
+        type: string;
+    };
+    strategy: string;
+    runtime: {
+        type: string;
+    };
+    linkedFiles: number;
+    linkedDirs: number;
+    taskGroups: number;
+    healthChecks: number;
+    warnings: string[];
+};
+export type ReleaseInfo = {
+    application: string;
+    stage: string;
+    releaseId: string;
+    revision: string;
+    branch: string;
+    deployedAt: string;
+    deployedBy: string;
+    host: string;
+    rampwayVersion: string;
+};
+export type LockInfo = {
+    owner: string;
+    host: string;
+    pid: number;
+    createdAt: string;
+};
+export type CommandOptions = {
+    config?: string | undefined;
+    source?: string | undefined;
+    revision?: string | undefined;
+    branch?: string | undefined;
+    yes?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    force?: boolean | undefined;
+    allowDirty?: boolean | undefined;
+    json?: boolean | undefined;
+    releaseId?: string | undefined;
+    to?: string | undefined;
+    releasePath?: string | undefined;
+    dir?: string | undefined;
+};
+export type CommandArgs = {
+    stageName: string;
+    options: CommandOptions;
+    commandContext?: Function | undefined;
+};
+export type Transport = {
+    mkdirp: (targetPath: string) => Promise<void>;
+    exists: (targetPath: string) => Promise<boolean>;
+    symlink: (target: string, linkPath: string, type?: string) => Promise<void>;
+    readlink: (linkPath: string) => Promise<string>;
+    rm: (targetPath: string) => Promise<void>;
+    rename: (from: string, to: string) => Promise<void>;
+    writeFile: (filePath: string, content: string) => Promise<void>;
+    readFile: (filePath: string) => Promise<string>;
+    list: (targetPath: string) => Promise<string[]>;
+    copyDir: (from: string, to: string) => Promise<void>;
+    run: (command: string, opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }) => Promise<{
+        code: number;
+        output: string;
+    }>;
+    stat?: ((targetPath: string) => Promise<{
+        isDirectory?: () => boolean;
+    } | undefined>) | undefined;
+};
+export type RuntimeAdapter = {
+    plan: () => string[];
+    deploy: (transport: Transport, opts: {
+        releasePath: string;
+        releaseId?: string;
+        revision?: string;
+        currentPath?: string;
+    }) => Promise<{
+        status: string;
+    }>;
+    status?: ((transport: Transport, opts: {
+        releasePath: string;
+    }) => Promise<{
+        output?: string;
+    }>) | undefined;
+    logs?: ((transport: Transport, opts: {
+        releasePath: string;
+    }) => Promise<{
+        output?: string;
+    }>) | undefined;
+    recover?: ((transport: Transport, opts: {
+        releasePath: string;
+        force?: boolean;
+    }) => Promise<{
+        output?: string;
+    }>) | undefined;
+    type?: string | undefined;
+};
+export type CommandPlan = {
+    command: string;
+    args: string[];
+    pipeTo?: CommandPlan | undefined;
+};
+export type DeployOptions = {
+    transport: Transport;
+    stage: StageConfig;
+    sourcePath?: string | undefined;
+    revision?: string | undefined;
+    branch?: string | undefined;
+    dryRun?: boolean | undefined;
+    releaseId?: string | undefined;
+    force?: boolean | undefined;
+};
+export type NodePackageInstallOptions = {
+    packageManager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    optional?: boolean | undefined;
+    production?: boolean | undefined;
+    clean?: boolean | undefined;
+    frozenLockfile?: boolean | undefined;
+};
+export type ConfigModule = {
+    config: object;
+    configPath: string;
+};
+export type RollbridgeRuntimeConfig = {
+    type: string;
+    command: string;
+    packageDir: string;
+    config?: string | undefined;
+    daemonLogPath?: string | undefined;
+    daemonPidPath?: string | undefined;
+    daemonStartTimeoutMs?: number | undefined;
+    socketPath?: string | undefined;
+    versionPath?: string | undefined;
+};
+export type SpawnResult = {
+    code: number;
+    output: string;
+};
+export type RegistryFactory = (config: RuntimeConfig) => RuntimeAdapter;
+export type InitResult = {
+    created: boolean;
+    path: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/build/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.js"],"names":[],"mappings":"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"}

package/build/src/types.js

@@ -0,0 +1,8 @@
+/**
+ * @file Shared JSDoc type definitions for Rampway.
+ *
+ * These are importable via bare-specifier `#types` and used across
+ * the codebase to provide type contracts for TypeScript JS checking.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/build/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.js"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/docs/config-reference.md

@@ -0,0 +1,264 @@
+# Config reference
+
+`rampway.config.mjs` is an ESM module that exports a default config object.
+
+## Top-level fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `application` | string | yes | Name of the application. Used in deploy metadata and reports. |
+| `stages` | object | yes | Map of stage names to stage configs. |
+
+## Stage fields
+
+Each stage under `stages` supports:
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `deployTo` | string | yes | — | Absolute path to the deploy root directory (e.g. `/home/dev/myapp`). |
+| `strategy` | string | no | Transport-dependent | Deploy strategy: `"local-copy"`, `"remote-git"`, or reserved `"archive-upload"`. Defaults to `"local-copy"` for local transport and `"remote-git"` for SSH transport. `archive-upload` is recognized but not yet deployable. |
+| `transport` | object | no | `{type: "ssh"}` | Transport configuration. See Transport below. |
+| `hosts` | array | no | `[]` | For SSH transport: list of hosts with `host`, `user`, and `roles`. |
+| `keepReleases` | number | no | `5` | Number of old releases to keep after cleanup. |
+| `linkedFiles` | array | no | `[]` | Files symlinked from `shared/` into each release. See Linked files below. |
+| `linkedDirs` | array | no | `[]` | Directories symlinked from `shared/` into each release. |
+| `tasks` | object | no | `{}` | Named task groups executed in order during deploy. See Tasks below. |
+| `hooks` | object | no | `{}` | Lifecycle-phase hooks executed at specific points in the deploy pipeline. See Hooks below. |
+| `runtime` | object | no | `{type: "none"}` | Runtime adapter config. See Runtime below. |
+| `healthChecks` | array | no | `[]` | Checks run after tasks and before publish. See Health checks below. |
+
+### Strategy: remote-git
+
+The `remote-git` strategy creates a temporary checkout directory on the deployment target, removes its `.git` directory, then atomically renames it into the release directory before publish. A branch deployment performs a shallow `git clone --branch`; a pinned revision initializes the temporary directory, adds the configured repository as `origin`, and shallow-fetches that revision. The target host needs `git` and repository access. Required fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `repo` | string | yes | Git repository URL (or local path). Used as the `origin` remote on the target. Avoid embedding credentials: plan and error output redact HTTPS URL user-info, but a credential helper or SSH deploy key is safer. |
+| `branch` | string | no | Branch to fetch and check out. Default: `"master"`. |
+| `revision` | string | no | Specific commit SHA to fetch and check out. When unset, the HEAD of `branch` is checked out. |
+
+```js
+strategy: "remote-git",
+repo: "git@github.com:org/repo.git",
+branch: "main"
+```
+
+## Transport
+
+### local
+
+No-op transport for test deployments on the same machine.
+
+```js
+transport: {type: "local"}
+```
+
+### ssh
+
+SSH transport using the local `ssh` client. Requires `hosts`.
+
+```js
+transport: {type: "ssh"},
+hosts: [{host: "server.example", user: "dev", roles: ["app", "web"]}]
+```
+
+## Linked files and directories
+
+Linked files and directories are symlinked from `shared/` into every release before tasks run.
+
+### linkedFiles
+
+Array of objects with `path` (required) and `required` (default `false`):
+
+```js
+linkedFiles: [
+  {path: ".env", required: true},
+  {path: "backend/src/config/secrets.js", required: false}
+]
+```
+
+Required files that don't exist in `shared/` cause the deploy to fail. Optional missing files are silently skipped.
+
+### linkedDirs
+
+Array of directory paths relative to the release root:
+
+```js
+linkedDirs: ["log", "tmp/pids", "tmp/cache", "storage"]
+```
+
+## Tasks
+
+Task groups are named objects in `tasks`. Each value is a string or an array of task entries. Task groups run in config order.
+
+### Task entries
+
+A task entry can be:
+
+- A **string**: the shell command to run.
+- An **object**: with `command` (required), plus optional `cwd`, `env`, `optional`, and `onlyIfChanged`.
+
+```js
+tasks: {
+  install: [
+    "echo installing packages",
+    {command: "npm ci --omit=dev", cwd: "backend", env: {NODE_ENV: "production"}},
+    {command: "warm cache", optional: true}
+  ],
+  migrate: ["NODE_ENV=production npm run db:migrate"]
+}
+```
+
+### Task helpers
+
+Import task helpers from `rampway/tasks`:
+
+```js
+import {npmInstall, pnpmInstall, yarnInstall, bunInstall} from "rampway/tasks"
+import {checkExpoWebArtifacts, velociousMigrate, onlyIfChanged} from "rampway/tasks"
+```
+
+#### npmInstall / pnpmInstall / yarnInstall / bunInstall
+
+Return a task entry with the install command for the given package manager.
+
+Options: `cwd`, `env`, `optional`, `production`, `clean` (npm), `frozenLockfile` (pnpm/yarn/bun).
+
+```js
+npmInstall({cwd: "backend", production: true})
+// → {command: "npm ci --omit=dev", cwd: "backend"}
+
+pnpmInstall({cwd: "app", production: true})
+// → {command: "pnpm install --frozen-lockfile --prod", cwd: "app"}
+```
+
+#### velociousMigrate
+
+Returns a task entry that runs `npx velocious db:migrate`.
+
+Options: `command` (override), `cwd`, `env`, `optional`.
+
+```js
+velociousMigrate({cwd: "backend", env: {NODE_ENV: "production"}})
+// → {command: "npx velocious db:migrate", cwd: "backend", env: {NODE_ENV: "production"}}
+```
+
+#### checkExpoWebArtifacts
+
+Returns a task entry that fails unless `index.html` exists in the Expo web build directory.
+
+Options: `dir` (default `"dist"`), `cwd`, `optional`.
+
+```js
+checkExpoWebArtifacts({dir: "app/dist"})
+// → {command: 'test -f "app/dist/index.html"'}
+```
+
+#### onlyIfChanged
+
+Wraps a task entry so it is skipped when none of the given paths have changed since the previous deploy. First deploys always run.
+
+```js
+onlyIfChanged(["backend"], npmInstall({cwd: "backend", production: true}))
+// → {command: "npm ci --omit=dev", cwd: "backend", onlyIfChanged: ["backend"]}
+```
+
+### Task execution model
+
+1. Task groups run in config order.
+2. Tasks within a group run in array order.
+3. Required task failures stop the deploy before publish.
+4. Optional task failures (`optional: true`) are recorded and the deploy continues.
+5. Tasks with `onlyIfChanged` are skipped when their paths haven't changed since the last deploy.
+6. Tasks with `cwd` resolve relative to the release root.
+
+## Hooks
+
+Hooks are lifecycle-phase callbacks that run commands at specific points during the deploy pipeline, outside the fixed task-group slot. Each hook phase accepts an array of task entries (strings or objects, same format as tasks).
+
+Hooks before the release directory is created cannot use `cwd` (since there is no release path to resolve against). Hooks after `after_source` run with the release directory as their working directory and support `cwd`, `env`, `optional`, and `onlyIfChanged` like regular task entries.
+
+| Phase | When it fires |
+|-------|--------------|
+| `before_deploy` | Before base directories are ensured |
+| `before_lock` | Before deploy lock acquisition |
+| `after_lock` | After deploy lock acquisition |
+| `before_source` | Before source code copy |
+| `after_source` | After source code is copied into the release directory |
+| `before_tasks` | Before task groups execute |
+| `after_tasks` | After task groups execute |
+| `before_runtime` | Before runtime adapter deploy |
+| `after_runtime` | After runtime adapter deploy |
+| `before_health` | Before health checks |
+| `after_health` | After health checks |
+| `before_publish` | Before `current` symlink is updated |
+| `after_publish` | After `current` symlink is updated |
+| `before_cleanup` | Before old release cleanup |
+| `after_cleanup` | After old release cleanup |
+
+Hook failures follow task failure semantics: required-hook failures stop the deploy, and optional-hook failures (`optional: true`) are recorded and the deploy continues. Failures after publish include recovery hints in the error message since `current` may have changed.
+
+```js
+hooks: {
+  before_deploy: ["echo 'deploy starting'"],
+  after_publish: [{command: "notify-slack.sh", optional: true, env: {CHANNEL: "deploys"}}],
+  before_cleanup: [npmInstall({cwd: "backend"})]
+}
+```
+
+Hooks and tasks can coexist. Tasks run at a fixed point (after shared links, before runtime). Hooks let you insert commands at any lifecycle phase without reordering task groups.
+
+## Runtime
+
+Configures how the deployed application is handed off to a process manager.
+
+### none
+
+No runtime — just deploy files.
+
+```js
+runtime: {type: "none"}
+```
+
+### rollbridge
+
+Rollbridge runtime adapter. Handles `deploy`, `validate`, `status`, `logs`, and `recover`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | yes | `"rollbridge"` |
+| `command` | string | no | Rollbridge CLI command. Default: `"npx rollbridge"`. |
+| `packageDir` | string | yes | Release-relative directory containing the Rollbridge package. |
+| `config` | string | no | Path to the Rollbridge config file. |
+| `healthPath` | string | no | HTTP health check path. Default: `"/health"`. |
+| `daemonLogPath` | string | no | Path to the daemon log file in shared storage. |
+| `daemonPidPath` | string | no | Path to the daemon PID file in shared storage. |
+| `socketPath` | string | no | Path to the Rollbridge Unix socket. |
+| `versionPath` | string | no | Path to a version file used for stale-daemon detection. |
+
+```js
+runtime: {
+  type: "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"
+}
+```
+
+## Health checks
+
+Each health check is an object with one of:
+
+- `path`: file to check exists, relative to the release root.
+- `command`: shell command; exits 0 = healthy.
+
+```js
+healthChecks: [
+  {name: "package", path: "package.json"},
+  {name: "migrations-table", command: "node -e 'require(\"velocious\")'"}
+]
+```