d3ployer 0.0.4 → 0.0.6

package/README.md

@@ -33,11 +33,11 @@ export default defineConfig({
   ],
   tasks: {
     restart: async (ctx) => {
-      await ctx.runRemote('systemctl restart myapp');
+      await ctx.run('systemctl restart myapp');
     },
   },
   scenarios: {
-    deploy: ['upload', 'symlinks', 'depInstall', 'restart'],
+    deploy: ['upload', 'symlinks', 'dep:install', 'restart'],
   },
 });
 ```
@@ -69,18 +69,18 @@ If `<name>` matches a scenario, it runs all tasks in that scenario sequentially.
 
 Define target servers. Only `host` and `deployPath` are required.
 
-| Field           | Default              | Description                          |
-| --------------- | -------------------- | ------------------------------------ |
-| `host`          | (required)           | Server hostname or IP                |
-| `deployPath`    | (required)           | Remote path to deploy to             |
-| `port`          | `22`                 | SSH port                             |
-| `username`      | Current OS user      | SSH username                         |
-| `authMethod`    | `'agent'`            | `'agent'`, `'key'`, or `'password'`  |
-| `privateKey`    | -                    | Path to private key (for `'key'`)    |
-| `password`      | -                    | SSH password (for `'password'`)      |
-| `agent`         | `SSH_AUTH_SOCK`      | SSH agent socket path                |
-| `packageManager`| -                    | Override package manager per server  |
-| `initCmd`       | -                    | Command to run on connect            |
+| Field           | Default              | Description                              |
+| --------------- | -------------------- | ---------------------------------------- |
+| `host`          | (required)           | Server hostname or IP                    |
+| `deployPath`    | (required)           | Remote path to deploy to                 |
+| `port`          | `22`                 | SSH port                                 |
+| `username`      | Current OS user      | SSH username                             |
+| `authMethod`    | `'agent'`            | `'agent'`, `'key'`, or `'password'`      |
+| `privateKey`    | -                    | Path to private key (for `'key'`)        |
+| `password`      | -                    | SSH password (for `'password'`)          |
+| `agent`         | `SSH_AUTH_SOCK`      | SSH agent socket path                    |
+| `packageManager`| -                    | Override package manager config per server (or `false` to disable) |
+| `initCmd`       | -                    | Shell command to run before each remote command (e.g. `source ~/.nvm/nvm.sh`) |
 
 ### `files`
 
@@ -106,6 +106,25 @@ symlinks: [
 
 Relative paths are resolved against `deployPath`.
 
+### `packageManager`
+
+Configure dependency installation. Can be set globally and/or per server. Set to `false` to disable.
+
+```ts
+packageManager: {
+  manager: 'npm',       // 'npm' | 'yarn' | 'pnpm' (default: 'npm')
+  productionOnly: true, // install production deps only (default: true)
+}
+```
+
+### `pm2`
+
+Set to `false` to disable the built-in PM2 task. When enabled (default), the `pm2:setup` task auto-detects `pm2.config.*` files and runs `pm2 start`.
+
+### `dockerCompose`
+
+Set to `false` to disable the built-in Docker Compose task. When enabled (default), the `docker:setup` task auto-detects compose files and runs `docker compose up -d --build`.
+
 ### `tasks`
 
 Custom task functions receive a `TaskContext` and `Placeholders`:
@@ -113,17 +132,39 @@ Custom task functions receive a `TaskContext` and `Placeholders`:
 ```ts
 tasks: {
   migrate: async (ctx, ph) => {
-    await ctx.runRemote(`cd ${ph.deployPath} && npm run migrate`);
+    await ctx.run('npm run migrate');
   },
 }
 ```
 
+Tasks can also be defined as objects with skip logic and config:
+
+```ts
+tasks: {
+  myTask: {
+    name: 'My Task',
+    skip: async (ctx) => !someCondition ? 'Reason to skip' : false,
+    task: async (ctx, ph) => { /* ... */ },
+    config: { /* passed as ctx.taskConfig */ },
+  },
+}
+```
+
+Task keys are auto-converted from camelCase to colon:case (e.g. `depInstall` becomes `dep:install`).
+
 **TaskContext** provides:
-- `runRemote(cmd)` - execute a command on the remote server
-- `runLocal(cmd)` - execute a command locally
-- `server` - current server config
+- `run(cmd, options?)` - execute a command on the remote server (auto cd's to `deployPath`)
+- `test(cmd)` - execute a command on the remote server, returns `boolean`
+- `runLocal(cmd, options?)` - execute a command locally
+- `testLocal(cmd)` - execute a command locally, returns `boolean`
+- `server` - current server config (includes `name`)
 - `ssh` - SSH2Promise connection
 - `config` - full deployer config
+- `taskConfig` - per-task config from task definition
+
+**RunOptions** (for `run` and `runLocal`):
+- `printOutput` - print stdout/stderr (default: `true`)
+- `ignoreError` - don't throw on non-zero exit (default: `false`)
 
 **Placeholders** provide:
 - `serverName` - name of the current server
@@ -136,22 +177,44 @@ Named sequences of tasks:
 
 ```ts
 scenarios: {
-  deploy: ['upload', 'symlinks', 'depInstall', 'restart'],
+  deploy: ['upload', 'symlinks', 'dep:install', 'restart'],
+}
+```
+
+Or as objects with a custom name:
+
+```ts
+scenarios: {
+  deploy: {
+    name: 'Deploy',
+    tasks: ['upload', 'symlinks', 'dep:install', 'restart'],
+  },
 }
 ```
 
 ## Built-in tasks
 
-| Task         | Description                                    |
-| ------------ | ---------------------------------------------- |
-| `upload`     | Rsync files to the remote server               |
-| `symlinks`   | Create configured symlinks on the remote server |
-| `depInstall` | Run package manager install on the remote server|
+| Task               | Description                                              |
+| ------------------ | -------------------------------------------------------- |
+| `upload`           | Rsync files to the remote server                         |
+| `download`         | Rsync files from the remote server (uses task config)    |
+| `symlinks`         | Create configured symlinks on the remote server          |
+| `dep:install`      | Install dependencies via npm/yarn/pnpm                   |
+| `pm2:setup`        | Start/restart PM2 processes (auto-detects pm2.config.*)  |
+| `docker:setup`     | Run docker compose up (auto-detects compose files)       |
+| `clear:target`     | Remove the entire deploy path (with confirmation prompt) |
+| `print:deployment` | Print deployment info (date, files, disk usage)          |
+
+### Default `deploy` scenario
+
+The built-in `deploy` scenario runs: `upload` → `symlinks` → `dep:install` → `pm2:setup` → `docker:setup` → `print:deployment`
+
+Tasks with skip conditions will be automatically skipped when not applicable (e.g. `pm2:setup` skips if no PM2 config file exists).
 
 ## Requirements
 
 - Node.js (ESM)
-- `rsync` installed locally (for the `upload` task)
+- `rsync` installed locally (for the `upload`/`download` tasks)
 - SSH access to target servers
 
 ## License

package/dist/config.d.ts

@@ -1,2 +1,3 @@
 import type { DeployerConfig, DeployerConfigInput } from './def.js';
+export declare function camelToColonCase(str: string): string;
 export declare function defineConfig(input: DeployerConfigInput): DeployerConfig;

package/dist/config.js

@@ -11,37 +11,71 @@ function resolveServer(input) {
 }
 function normalizeTask(key, input) {
     if (typeof input === 'function') {
-        return { name: key, fn: input };
+        return {
+            name: key,
+            task: input,
+        };
     }
-    return { name: input.name, fn: input.task };
+    return {
+        name: input.name ?? key,
+        task: input.task,
+        skip: input.skip,
+        config: input.config,
+    };
 }
 function normalizeScenario(key, input) {
     if (Array.isArray(input)) {
-        return { name: key, tasks: input };
+        return {
+            name: key,
+            tasks: input,
+        };
     }
-    return { name: input.name, tasks: input.tasks };
+    return {
+        name: input.name,
+        tasks: input.tasks,
+    };
+}
+export function camelToColonCase(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, '$1:$2').toLowerCase();
 }
 export function defineConfig(input) {
     const servers = {};
     for (const [name, serverInput] of Object.entries(input.servers)) {
         servers[name] = resolveServer(serverInput);
     }
-    const tasks = { ...defaultTasks };
+    const tasks = {};
+    for (const [key, taskDef] of Object.entries(defaultTasks)) {
+        tasks[camelToColonCase(key)] = taskDef;
+    }
     if (input.tasks) {
         for (const [key, taskInput] of Object.entries(input.tasks)) {
-            tasks[key] = normalizeTask(key, taskInput);
+            tasks[camelToColonCase(key)] = normalizeTask(key, taskInput);
         }
     }
-    const scenarios = { ...defaultScenarios };
+    const scenarios = {};
+    for (const [key, scenarioDef] of Object.entries(defaultScenarios)) {
+        scenarios[camelToColonCase(key)] = {
+            ...scenarioDef,
+            tasks: scenarioDef.tasks.map(camelToColonCase),
+        };
+    }
     if (input.scenarios) {
         for (const [key, scenarioInput] of Object.entries(input.scenarios)) {
-            scenarios[key] = normalizeScenario(key, scenarioInput);
+            const normalized = normalizeScenario(key, scenarioInput);
+            scenarios[camelToColonCase(key)] = {
+                ...normalized,
+                tasks: normalized.tasks.map(camelToColonCase),
+            };
         }
     }
     return {
-        packageManager: 'npm',
         rootDir: '',
         ...input,
+        packageManager: {
+            manager: 'npm',
+            productionOnly: true,
+            ...input.packageManager,
+        },
         servers,
         tasks,
         scenarios,

package/dist/def.d.ts

@@ -1,5 +1,10 @@
 import type SSH2Promise from 'ssh2-promise';
 export type AuthMethod = 'key' | 'password' | 'agent';
+export type PackageManager = 'npm' | 'yarn' | 'pnpm';
+export type PackageManagerConfig = {
+    manager: PackageManager;
+    productionOnly?: boolean;
+};
 export interface ServerConfig {
     host: string;
     port: number;
@@ -9,7 +14,7 @@ export interface ServerConfig {
     password?: string;
     agent?: string;
     deployPath: string;
-    packageManager?: string;
+    packageManager?: PackageManagerConfig | false;
     initCmd?: string;
 }
 export type ServerConfigInput = Partial<ServerConfig> & Pick<ServerConfig, 'host' | 'deployPath'>;
@@ -47,15 +52,21 @@ export interface TaskContext {
     testLocal: (cmd: string) => Promise<boolean>;
     run: (cmd: string, options?: RunOptions) => Promise<ExecResult>;
     test: (cmd: string) => Promise<boolean>;
+    taskConfig?: any;
 }
 export type TaskFn = (ctx: TaskContext, ph: Placeholders) => Promise<void>;
+export type TaskSkipFn = (ctx: TaskContext, ph: Placeholders) => Promise<boolean | string> | boolean | string;
 export interface TaskDef {
     name: string;
-    fn: TaskFn;
+    task: TaskFn;
+    skip?: TaskSkipFn;
+    config?: any;
 }
 export type TaskInput = TaskFn | {
-    name: string;
+    name?: string;
     task: TaskFn;
+    skip?: TaskSkipFn;
+    config?: any;
 };
 export interface ScenarioDef {
     name: string;
@@ -68,9 +79,11 @@ export type ScenarioInput = string[] | {
 export interface DeployerConfig {
     rootDir: string;
     servers: Record<string, ServerConfig>;
-    packageManager?: string;
     files?: FilesConfig;
     symlinks?: SymlinkConfig[];
+    packageManager?: PackageManagerConfig | false;
+    pm2?: boolean;
+    dockerCompose?: boolean;
     tasks?: Record<string, TaskDef>;
     scenarios?: Record<string, ScenarioDef>;
 }

package/dist/defaultTasks.d.ts

@@ -1,3 +1,9 @@
-import type { ScenarioDef, TaskDef } from './def.js';
+import type { FilesConfig, ScenarioDef, ServerConfig, TaskDef, TaskFn, TaskSkipFn } from './def.js';
+export type RsyncOptions = {
+    delete?: boolean;
+};
+export declare function buildRsyncCommand(server: ServerConfig, source: string, dest: string, files: FilesConfig, options?: RsyncOptions): string;
+export declare const downloadSkip: TaskSkipFn;
+export declare const downloadTask: TaskFn;
 export declare const defaultTasks: Record<string, TaskDef>;
 export declare const defaultScenarios: Record<string, ScenarioDef>;

package/dist/defaultTasks.js

@@ -1,8 +1,13 @@
-import { Exception } from './utils/index.js';
+import confirm from '@inquirer/confirm';
 import chalk from 'chalk';
 import path from 'node:path';
-function buildRsyncCommand(server, source, dest, files) {
-    const args = ['rsync', '-avz', '--delete', '--progress=info2'];
+import { Exception } from './utils/index.js';
+export function buildRsyncCommand(server, source, dest, files, options = {}) {
+    const { delete: useDelete = true, } = options;
+    const args = ['rsync', '-avz', '--progress=info2'];
+    if (useDelete) {
+        args.push('--delete');
+    }
     // ssh shell
     const sshParts = ['ssh'];
     if (server.port && server.port !== 22) {
@@ -14,25 +19,28 @@ function buildRsyncCommand(server, source, dest, files) {
     sshParts.push('-o StrictHostKeyChecking=no');
     args.push('-e', `"${sshParts.join(' ')}"`);
     // include/exclude
+    if (files.exclude) {
+        for (const pattern of files.exclude) {
+            args.push(`--exclude=${pattern}`);
+        }
+    }
     if (files.include) {
         for (const pattern of files.include) {
             args.push(`--include=${pattern}`);
         }
         args.push('--exclude=*');
     }
-    if (files.exclude) {
-        for (const pattern of files.exclude) {
-            args.push(`--exclude=${pattern}`);
-        }
-    }
     args.push(source, dest);
     return args.join(' ');
 }
+const uploadSkip = (ctx) => {
+    const files = ctx.config.files;
+    return !files
+        ? 'No files configuration defined'
+        : false;
+};
 const uploadTask = async (ctx, ph) => {
     const files = ctx.config.files;
-    if (!files) {
-        return;
-    }
     const localBase = files.basePath?.startsWith('/')
         ? files.basePath
         : path.resolve(ctx.config.rootDir, files.basePath ?? '.');
@@ -40,14 +48,40 @@ const uploadTask = async (ctx, ph) => {
     const dest = `${ctx.server.username}@${ctx.server.host}:${remotePath}`;
     const source = localBase.endsWith('/') ? localBase : localBase + '/';
     await ctx.run(`mkdir -p ${remotePath}`);
-    const command = buildRsyncCommand(ctx.server, source, dest, files);
+    const command = buildRsyncCommand(ctx.server, source, dest, files, {
+        delete: true,
+    });
+    console.log(chalk.grey(command));
     await ctx.runLocal(command);
 };
+export const downloadSkip = (ctx) => {
+    const files = ctx.taskConfig;
+    return !files
+        ? 'No files configuration provided in task config'
+        : false;
+};
+export const downloadTask = async (ctx, ph) => {
+    const files = ctx.taskConfig;
+    const localBase = files.basePath?.startsWith('/')
+        ? files.basePath
+        : path.resolve(ctx.config.rootDir, files.basePath ?? '.');
+    const remotePath = ph.deployPath;
+    const source = `${ctx.server.username}@${ctx.server.host}:${remotePath}/`;
+    const dest = localBase.endsWith('/') ? localBase : localBase + '/';
+    const command = buildRsyncCommand(ctx.server, source, dest, files, {
+        delete: false,
+    });
+    console.log(chalk.grey(command));
+    await ctx.runLocal(command);
+};
+const symlinksSkip = (ctx) => {
+    const symlinks = ctx.config.symlinks;
+    return !symlinks || symlinks.length === 0
+        ? 'No symlinks defined in config'
+        : false;
+};
 const symlinksTask = async (ctx, ph) => {
     const symlinks = ctx.config.symlinks;
-    if (!symlinks || symlinks.length === 0) {
-        return;
-    }
     for (const link of symlinks) {
         const target = link.target.startsWith('/')
             ? link.target
@@ -58,22 +92,80 @@ const symlinksTask = async (ctx, ph) => {
         await ctx.run(`ln -sfn ${target} ${path}`);
     }
 };
+const depInstallSkip = (ctx) => {
+    if (ctx.server.packageManager !== undefined) {
+        return ctx.server.packageManager === false
+            ? 'Package manager disabled for server'
+            : false;
+    }
+    if (ctx.config.packageManager !== undefined) {
+        return ctx.config.packageManager === false
+            ? 'Package manager disabled in config'
+            : false;
+    }
+    return false;
+};
 const depInstallTask = async (ctx) => {
-    const pm = ctx.server.packageManager ?? ctx.config.packageManager ?? 'npm';
-    let cmd = `${pm}`;
-    if (pm === 'npm') {
-        cmd += ' install --production';
+    const config = {
+        manager: 'npm',
+        productionOnly: true,
+        ...ctx.config.packageManager,
+        ...ctx.server.packageManager,
+    };
+    let cmd = `${config.manager} install`;
+    if (config.productionOnly) {
+        if (config.manager === 'npm') {
+            cmd += ' --omit=dev';
+        }
+        else if (config.manager === 'yarn') {
+            cmd += ' --production';
+        }
+        else if (config.manager === 'pnpm') {
+            cmd += ' --prod';
+        }
+        else {
+            throw new Exception(`Unsupported package manager "${config.manager}"`, 1774823752134);
+        }
     }
-    else if (pm === 'yarn') {
-        cmd += ' install --production';
+    await ctx.run(cmd);
+};
+const pm2SetupSkip = async (ctx) => {
+    if (ctx.config.pm2 === false) {
+        return 'PM2 disabled';
     }
-    else if (pm === 'pnpm') {
-        cmd += ' install --prod';
+    const pm2ConfigExists = await ctx.test('test -f pm2.config.*');
+    if (!pm2ConfigExists) {
+        return 'PM2 config not found';
     }
-    else {
-        throw new Exception(`Unsupported package manager "${pm}"`, 1774823752134);
+    return false;
+};
+const pm2SetupTask = async (ctx) => {
+    await ctx.run('pm2 start pm2.config.* --update-env');
+    await ctx.run('pm2 save');
+};
+const dockerSetupSkip = async (ctx) => {
+    if (ctx.config.dockerCompose === false) {
+        return 'Docker Compose disabled';
     }
-    await ctx.run(cmd);
+    const composeExists = await ctx.test('test -f docker-compose.yml -o -f docker-compose.yaml -o -f compose.yml -o -f compose.yaml');
+    if (!composeExists) {
+        return 'Docker Compose config not found';
+    }
+    return false;
+};
+const dockerSetupTask = async (ctx) => {
+    await ctx.run('docker compose up -d --build --remove-orphans');
+};
+const clearTargetTask = async (ctx, ph) => {
+    const confirmed = await confirm({
+        message: chalk.red(`Remove entire deploy path ${ph.deployPath} on ${ctx.server.host}?`),
+        default: false,
+    });
+    if (!confirmed) {
+        console.log(chalk.yellow('Skipped clearing target'));
+        return;
+    }
+    await ctx.run(`rm -rf ${ph.deployPath}`);
 };
 const printDeploymentTask = async (ctx, ph) => {
     await ctx.run('date');
@@ -82,35 +174,44 @@ const printDeploymentTask = async (ctx, ph) => {
     console.log(chalk.cyan('Directory size'));
     await ctx.run('du -hd 1 .');
 };
-const pm2SetupTask = async (ctx) => {
-    const pm2ConfigExists = await ctx.test('test -f pm2.config.*');
-    if (!pm2ConfigExists) {
-        console.log(chalk.yellow('PM2 config not found, skipping setup'));
-        return;
-    }
-    await ctx.run('pm2 start pm2.config.* --update-env');
-    await ctx.run('pm2 save');
-};
 export const defaultTasks = {
+    clearTarget: {
+        name: 'Clear target',
+        task: clearTargetTask,
+    },
     upload: {
         name: 'Upload files',
-        fn: uploadTask,
+        skip: uploadSkip,
+        task: uploadTask,
+    },
+    download: {
+        name: 'Download files',
+        skip: downloadSkip,
+        task: downloadTask,
     },
     symlinks: {
         name: 'Create symlinks',
-        fn: symlinksTask,
+        skip: symlinksSkip,
+        task: symlinksTask,
     },
     depInstall: {
         name: 'Install dependencies',
-        fn: depInstallTask,
-    },
-    printDeployment: {
-        name: 'Print deployment info',
-        fn: printDeploymentTask,
+        skip: depInstallSkip,
+        task: depInstallTask,
     },
     pm2Setup: {
         name: 'PM2 setup',
-        fn: pm2SetupTask,
+        skip: pm2SetupSkip,
+        task: pm2SetupTask,
+    },
+    dockerSetup: {
+        name: 'Docker Compose setup',
+        skip: dockerSetupSkip,
+        task: dockerSetupTask,
+    },
+    printDeployment: {
+        name: 'Print deployment info',
+        task: printDeploymentTask,
     },
 };
 export const defaultScenarios = {
@@ -119,9 +220,10 @@ export const defaultScenarios = {
         tasks: [
             'upload',
             'symlinks',
-            'depInstall',
-            'pm2Setup',
-            'printDeployment',
+            'dep:install',
+            'pm2:setup',
+            'docker:setup',
+            'print:deployment',
         ],
     },
 };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export type { AuthMethod, DeployerConfig, DeployerConfigInput, FilesConfig, Placeholders, ScenarioDef, ScenarioInput, ServerConfig, ServerConfigInput, SymlinkConfig, TaskContext, TaskDef, TaskFn, TaskInput, } from './def.js';
+export type { AuthMethod, DeployerConfig, DeployerConfigInput, FilesConfig, Placeholders, ScenarioDef, ScenarioInput, ServerConfig, ServerConfigInput, SymlinkConfig, TaskContext, TaskDef, TaskFn, TaskInput, TaskSkipFn, } from './def.js';
 export { defineConfig } from './config.js';
 export { runScenario, runTask } from './runner.js';
 export { loadConfig, findConfigFile } from './configLoader.js';
+export { buildRsyncCommand, downloadSkip, downloadTask } from './defaultTasks.js';
+export type { RsyncOptions } from './defaultTasks.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { defineConfig } from './config.js';
 export { runScenario, runTask } from './runner.js';
 export { loadConfig, findConfigFile } from './configLoader.js';
+export { buildRsyncCommand, downloadSkip, downloadTask } from './defaultTasks.js';

package/dist/runner.js

@@ -193,7 +193,16 @@ function buildServerListr(serverName, server, config, tasks) {
         },
         ...tasks.map(([_key, taskDef]) => ({
             title: chalk.bgCyan.black(` ${taskDef.name} `),
-            task: async (ctx, task) => taskDef.fn(ctx.taskCtx, ctx.ph),
+            skip: taskDef.skip
+                ? (ctx) => {
+                    ctx.taskCtx.taskConfig = taskDef.config;
+                    return taskDef.skip(ctx.taskCtx, ctx.ph);
+                }
+                : undefined,
+            task: async (ctx) => {
+                ctx.taskCtx.taskConfig = taskDef.config;
+                return taskDef.task(ctx.taskCtx, ctx.ph);
+            },
             options: listrOptions,
         })),
         {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "d3ployer",
-    "version": "0.0.4",
+    "version": "0.0.6",
     "license": "MIT",
     "type": "module",
     "bin": {
@@ -25,6 +25,7 @@
         "prepare": "husky"
     },
     "dependencies": {
+        "@inquirer/confirm": "^6.0.10",
         "chalk": "^5.6.2",
         "commander": "^14.0.3",
         "listr2": "^10.2.1",