@wyxos/zephyr 0.2.31 → 0.3.0

package/README.md

@@ -18,6 +18,12 @@ npx @wyxos/zephyr
 
 Navigate to your project directory and run:
 
+```bash
+npm run release
+```
+
+Or invoke Zephyr directly:
+
 ```bash
 zephyr
 ```
@@ -35,6 +41,11 @@ Common flags:
 zephyr --type node
 ```
 
+On a first run inside a project with `package.json`, Zephyr can:
+- add `.zephyr/` to `.gitignore`
+- add a `release` script that runs `npx @wyxos/zephyr@latest`
+- create global server config and per-project deployment config interactively
+
 Follow the interactive prompts to configure your deployment target:
 - Server name and IP address
 - Project path on the remote server
@@ -43,6 +54,48 @@ Follow the interactive prompts to configure your deployment target:
 
 Configuration is saved automatically for future deployments.
 
+## Scripts
+
+Zephyr exposes the following common project workflow:
+
+```bash
+npm run lint
+npm test
+npm run release
+```
+
+- `npm run lint` runs `eslint . --fix`, so it can rewrite tracked files when auto-fixes are available.
+- `npm test` runs the Vitest suite.
+- `npm run release` is the recommended project entrypoint once the release script has been installed.
+
+## Package API
+
+The package surface is intentionally small:
+
+```js
+import {
+  logProcessing,
+  logSuccess,
+  logWarning,
+  logError,
+  runCommand,
+  runCommandCapture,
+  writeToLogFile
+} from '@wyxos/zephyr'
+
+import {selectDeploymentTarget} from '@wyxos/zephyr/targets'
+
+import {
+  connectToServer,
+  executeRemoteCommand,
+  readRemoteFile,
+  downloadRemoteFile,
+  deleteRemoteFile
+} from '@wyxos/zephyr/ssh'
+```
+
+The root package does not expose the old interactive configuration helper bag; target selection now lives under `@wyxos/zephyr/targets`.
+
 ## Features
 
 - Automated Git operations (branch switching, commits, pushes)
@@ -62,7 +115,7 @@ Configuration is saved automatically for future deployments.
 Zephyr analyzes changed files and runs appropriate tasks:
 
 - **Always**: `git pull origin <branch>`
-- **Composer files changed** (`composer.json` / `composer.lock`): `composer update --no-dev --no-interaction --prefer-dist`
+- **Composer files changed** (`composer.json` / `composer.lock`): `composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader` (requires `composer.lock`)
 - **Migrations changed** (`database/migrations/*.php`): `php artisan migrate --force`
 - **Node dependency files changed** (`package.json` / `package-lock.json`, including nested): `npm install`
 - **Frontend files changed** (`.vue/.js/.ts/.tsx/.css/.scss/.less`): `npm run build`
@@ -131,4 +184,4 @@ The `.zephyr/` directory is automatically added to `.gitignore`.
 
 - Node.js 16+
 - Git
-- SSH access to target servers
+- SSH access to target servers

package/bin/zephyr.mjs

@@ -13,12 +13,14 @@ program
   .name('zephyr')
   .description('A streamlined deployment tool for web applications with intelligent Laravel project detection')
   .option('--type <type>', 'Release type (node|vue|packagist)')
+  .argument('[version]', 'Version or npm bump type (e.g. 1.2.3, patch, minor, major)')
 
 program.parse(process.argv)
 const options = program.opts()
+const versionArg = program.args[0] ?? null
 
 try {
-  await main(options.type ?? null)
+  await main(options.type ?? null, versionArg)
 } catch (error) {
   logError(error?.message || String(error))
   process.exitCode = 1

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@wyxos/zephyr",
-  "version": "0.2.31",
+  "version": "0.3.0",
   "description": "A streamlined deployment tool for web applications with intelligent Laravel project detection",
   "type": "module",
   "main": "./src/index.mjs",
+  "imports": {
+    "#src/*": "./src/*",
+    "#tests/*": "./tests/*"
+  },
   "exports": {
     ".": "./src/index.mjs",
+    "./targets": "./src/targets/index.mjs",
     "./ssh": "./src/ssh/index.mjs"
   },
   "bin": {
@@ -13,7 +18,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "lint": "eslint .",
+    "lint": "eslint . --fix",
     "release": "node bin/zephyr.mjs --type=node"
   },
   "keywords": [

package/src/application/configuration/app-details.mjs

@@ -0,0 +1,89 @@
+import path from 'node:path'
+import inquirer from 'inquirer'
+
+export function defaultProjectPath(currentDir) {
+    return `~/webapps/${path.basename(currentDir)}`
+}
+
+export async function listGitBranches({
+                                          currentDir,
+                                          runCommandCapture,
+                                          logWarning
+                                      } = {}) {
+    try {
+        const output = await runCommandCapture(
+            'git',
+            ['branch', '--format', '%(refname:short)'],
+            {cwd: currentDir}
+        )
+
+        const branches = output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+
+        return branches.length ? branches : ['master']
+    } catch (_error) {
+        logWarning?.('Unable to read git branches; defaulting to master.')
+        return ['master']
+    }
+}
+
+export async function promptAppDetails({
+                                           currentDir,
+                                           existing = {},
+                                           runPrompt,
+                                           listGitBranches,
+                                           resolveDefaultProjectPath = defaultProjectPath,
+                                           promptSshDetails
+                                       } = {}) {
+    const branches = await listGitBranches(currentDir)
+    const defaultBranch = existing.branch || (branches.includes('master') ? 'master' : branches[0])
+    const defaults = {
+        projectPath: existing.projectPath || resolveDefaultProjectPath(currentDir),
+        branch: defaultBranch
+    }
+
+    const answers = await runPrompt([
+        {
+            type: 'input',
+            name: 'projectPath',
+            message: 'Remote project path',
+            default: defaults.projectPath
+        },
+        {
+            type: 'list',
+            name: 'branchSelection',
+            message: 'Branch to deploy',
+            choices: [
+                ...branches.map((branch) => ({name: branch, value: branch})),
+                new inquirer.Separator(),
+                {name: 'Enter custom branch…', value: '__custom'}
+            ],
+            default: defaults.branch
+        }
+    ])
+
+    let branch = answers.branchSelection
+
+    if (branch === '__custom') {
+        const {customBranch} = await runPrompt([
+            {
+                type: 'input',
+                name: 'customBranch',
+                message: 'Custom branch name',
+                default: defaults.branch
+            }
+        ])
+
+        branch = customBranch.trim() || defaults.branch
+    }
+
+    const sshDetails = await promptSshDetails(currentDir, existing)
+
+    return {
+        projectPath: answers.projectPath.trim() || defaults.projectPath,
+        branch,
+        ...sshDetails
+    }
+}

package/src/application/configuration/app-selection.mjs

@@ -0,0 +1,87 @@
+import inquirer from 'inquirer'
+
+import {generateId} from '../../utils/id.mjs'
+import {saveProjectConfig} from '../../config/project.mjs'
+
+export async function selectApp({
+                                    projectConfig,
+                                    server,
+                                    currentDir,
+                                    runPrompt,
+                                    logWarning,
+                                    logProcessing,
+                                    logSuccess,
+                                    persistProjectConfig = saveProjectConfig,
+                                    createId = generateId,
+                                    promptAppDetails
+                                } = {}) {
+    const apps = projectConfig.apps ?? []
+    const matches = apps
+        .map((app, index) => ({app, index}))
+        .filter(({app}) => app.serverId === server.id || app.serverName === server.serverName)
+
+    if (matches.length === 0) {
+        if (apps.length > 0) {
+            const availableServers = [...new Set(apps.map((app) => app.serverName).filter(Boolean))]
+            if (availableServers.length > 0) {
+                logWarning?.(
+                    `No applications configured for server "${server.serverName}". Available servers: ${availableServers.join(', ')}`
+                )
+            }
+        }
+
+        logProcessing?.(`No applications are configured for ${server.serverName}. Creating one now.`)
+        const appDetails = await promptAppDetails(currentDir)
+        const appConfig = {
+            id: createId(),
+            serverId: server.id,
+            serverName: server.serverName,
+            ...appDetails
+        }
+
+        projectConfig.apps.push(appConfig)
+        await persistProjectConfig(currentDir, projectConfig)
+        logSuccess?.('Saved deployment configuration to .zephyr/config.json')
+        return appConfig
+    }
+
+    const choices = matches.map(({app}, matchIndex) => ({
+        name: `${app.projectPath} (${app.branch})`,
+        value: matchIndex
+    }))
+
+    choices.push(
+        new inquirer.Separator(),
+        {
+            name: '➕ Create a new application for this server',
+            value: 'create'
+        }
+    )
+
+    const {selection} = await runPrompt([
+        {
+            type: 'list',
+            name: 'selection',
+            message: `Select an application for ${server.serverName}`,
+            choices,
+            default: 0
+        }
+    ])
+
+    if (selection === 'create') {
+        const appDetails = await promptAppDetails(currentDir)
+        const appConfig = {
+            id: createId(),
+            serverId: server.id,
+            serverName: server.serverName,
+            ...appDetails
+        }
+
+        projectConfig.apps.push(appConfig)
+        await persistProjectConfig(currentDir, projectConfig)
+        logSuccess?.('Appended deployment configuration to .zephyr/config.json')
+        return appConfig
+    }
+
+    return matches[selection].app
+}

package/src/application/configuration/preset-selection.mjs

@@ -0,0 +1,59 @@
+import inquirer from 'inquirer'
+
+export async function selectPreset({
+                                       projectConfig,
+                                       servers,
+                                       runPrompt
+                                   } = {}) {
+    const presets = projectConfig.presets ?? []
+    const apps = projectConfig.apps ?? []
+
+    if (presets.length === 0) {
+        return null
+    }
+
+    const choices = presets.map((preset, index) => {
+        let displayName = preset.name
+
+        if (preset.appId) {
+            const app = apps.find((entry) => entry.id === preset.appId)
+            if (app) {
+                const server = servers.find((entry) => entry.id === app.serverId || entry.serverName === app.serverName)
+                const serverName = server?.serverName || 'unknown'
+                const branch = preset.branch || app.branch || 'unknown'
+                displayName = `${preset.name} (${serverName} → ${app.projectPath} [${branch}])`
+            }
+        } else if (preset.key) {
+            const keyParts = preset.key.split(':')
+            const serverName = keyParts[0]
+            const projectPath = keyParts[1]
+            const branch = preset.branch || (keyParts.length === 3 ? keyParts[2] : 'unknown')
+            displayName = `${preset.name} (${serverName} → ${projectPath} [${branch}])`
+        }
+
+        return {
+            name: displayName,
+            value: index
+        }
+    })
+
+    choices.push(
+        new inquirer.Separator(),
+        {
+            name: '➕ Create a new preset',
+            value: 'create'
+        }
+    )
+
+    const {selection} = await runPrompt([
+        {
+            type: 'list',
+            name: 'selection',
+            message: 'Select a preset',
+            choices,
+            default: 0
+        }
+    ])
+
+    return selection === 'create' ? 'create' : presets[selection]
+}

package/src/application/configuration/select-deployment-target.mjs

@@ -0,0 +1,165 @@
+import {writeStdoutLine} from '../../utils/output.mjs'
+import {loadServers} from '../../config/servers.mjs'
+import {loadProjectConfig, removePreset, saveProjectConfig} from '../../config/project.mjs'
+
+export async function selectDeploymentTarget(rootDir, {
+    configurationService,
+    runPrompt,
+    logProcessing,
+    logSuccess,
+    logWarning
+} = {}) {
+    const servers = await loadServers({logSuccess, logWarning})
+    const projectConfig = await loadProjectConfig(rootDir, servers, {logSuccess, logWarning})
+
+    let server = null
+    let appConfig = null
+    let isCreatingNewPreset = false
+
+    const preset = await configurationService.selectPreset(projectConfig, servers)
+
+    const removeInvalidPreset = async () => {
+        if (!preset || preset === 'create') {
+            return
+        }
+
+        const removedPreset = removePreset(projectConfig, preset)
+        if (!removedPreset) {
+            return
+        }
+
+        await saveProjectConfig(rootDir, projectConfig)
+        const presetLabel = removedPreset.name ? `"${removedPreset.name}"` : 'selected preset'
+        logWarning?.(`Removed ${presetLabel} from .zephyr/config.json because it is invalid.`)
+        isCreatingNewPreset = true
+    }
+
+    if (preset === 'create') {
+        isCreatingNewPreset = true
+        server = await configurationService.selectServer(servers)
+        appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+    } else if (preset) {
+        if (preset.appId) {
+            appConfig = projectConfig.apps?.find((app) => app.id === preset.appId)
+
+            if (!appConfig) {
+                logWarning?.('Preset references an application that no longer exists. Creating a new configuration instead.')
+                await removeInvalidPreset()
+                server = await configurationService.selectServer(servers)
+                appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+            } else {
+                server = servers.find((entry) => entry.id === appConfig.serverId || entry.serverName === appConfig.serverName)
+
+                if (!server) {
+                    logWarning?.('Preset references a server that no longer exists. Creating a new configuration instead.')
+                    await removeInvalidPreset()
+                    server = await configurationService.selectServer(servers)
+                    appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+                } else if (preset.branch && appConfig.branch !== preset.branch) {
+                    appConfig.branch = preset.branch
+                    await saveProjectConfig(rootDir, projectConfig)
+                    logSuccess?.(`Updated branch to ${preset.branch} from preset.`)
+                }
+            }
+        } else if (preset.key) {
+            const keyParts = preset.key.split(':')
+            const serverName = keyParts[0]
+            const projectPath = keyParts[1]
+            const presetBranch = preset.branch || (keyParts.length === 3 ? keyParts[2] : null)
+
+            server = servers.find((entry) => entry.serverName === serverName)
+
+            if (!server) {
+                logWarning?.(`Preset references server "${serverName}" which no longer exists. Creating a new configuration instead.`)
+                await removeInvalidPreset()
+                server = await configurationService.selectServer(servers)
+                appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+            } else {
+                appConfig = projectConfig.apps?.find(
+                    (app) => (app.serverId === server.id || app.serverName === serverName) && app.projectPath === projectPath
+                )
+
+                if (!appConfig) {
+                    logWarning?.('Preset references an application that no longer exists. Creating a new configuration instead.')
+                    await removeInvalidPreset()
+                    appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+                } else {
+                    preset.appId = appConfig.id
+                    if (presetBranch && appConfig.branch !== presetBranch) {
+                        appConfig.branch = presetBranch
+                    }
+                    preset.branch = appConfig.branch
+                    await saveProjectConfig(rootDir, projectConfig)
+                }
+            }
+        } else {
+            logWarning?.('Preset format is invalid. Creating a new configuration instead.')
+            await removeInvalidPreset()
+            server = await configurationService.selectServer(servers)
+            appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+        }
+    } else {
+        server = await configurationService.selectServer(servers)
+        appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
+    }
+
+    const updated = await configurationService.ensureSshDetails(appConfig, rootDir)
+
+    if (updated) {
+        await saveProjectConfig(rootDir, projectConfig)
+        logSuccess?.('Updated .zephyr/config.json with SSH details.')
+    }
+
+    const deploymentConfig = {
+        serverName: server.serverName,
+        serverIp: server.serverIp,
+        projectPath: appConfig.projectPath,
+        branch: appConfig.branch,
+        sshUser: appConfig.sshUser,
+        sshKey: appConfig.sshKey
+    }
+
+    logProcessing?.('\nSelected deployment target:')
+    writeStdoutLine(JSON.stringify(deploymentConfig, null, 2))
+
+    if (isCreatingNewPreset || !preset) {
+        const {presetName} = await runPrompt([
+            {
+                type: 'input',
+                name: 'presetName',
+                message: 'Enter a name for this preset (leave blank to skip)',
+                default: isCreatingNewPreset ? '' : undefined
+            }
+        ])
+
+        const trimmedName = presetName?.trim()
+
+        if (trimmedName && trimmedName.length > 0) {
+            const presets = projectConfig.presets ?? []
+            const appId = appConfig.id
+
+            if (!appId) {
+                logWarning?.('Cannot save preset: app configuration missing ID.')
+            } else {
+                const existingIndex = presets.findIndex((entry) => entry.appId === appId)
+
+                if (existingIndex >= 0) {
+                    presets[existingIndex].name = trimmedName
+                    presets[existingIndex].branch = deploymentConfig.branch
+                } else {
+                    presets.push({
+                        name: trimmedName,
+                        appId,
+                        branch: deploymentConfig.branch
+                    })
+                }
+
+                projectConfig.presets = presets
+                await saveProjectConfig(rootDir, projectConfig)
+                logSuccess?.(`Saved preset "${trimmedName}" to .zephyr/config.json`)
+            }
+        }
+    }
+
+    return {deploymentConfig, projectConfig}
+}

package/src/application/configuration/server-selection.mjs

@@ -0,0 +1,87 @@
+import inquirer from 'inquirer'
+
+import {generateId} from '../../utils/id.mjs'
+import {saveServers} from '../../config/servers.mjs'
+
+export async function promptServerDetails({
+                                              existingServers = [],
+                                              runPrompt,
+                                              createId = generateId
+                                          } = {}) {
+    const defaults = {
+        serverName: existingServers.length === 0 ? 'home' : `server-${existingServers.length + 1}`,
+        serverIp: '1.1.1.1'
+    }
+
+    const answers = await runPrompt([
+        {
+            type: 'input',
+            name: 'serverName',
+            message: 'Enter a server name',
+            default: defaults.serverName
+        },
+        {
+            type: 'input',
+            name: 'serverIp',
+            message: 'Enter the server IP address',
+            default: defaults.serverIp
+        }
+    ])
+
+    return {
+        id: createId(),
+        serverName: answers.serverName.trim() || defaults.serverName,
+        serverIp: answers.serverIp.trim() || defaults.serverIp
+    }
+}
+
+export async function selectServer({
+                                       servers,
+                                       runPrompt,
+                                       logProcessing,
+                                       logSuccess,
+                                       persistServers = saveServers,
+                                       promptServerDetails
+                                   } = {}) {
+    if (servers.length === 0) {
+        logProcessing?.('No servers are configured yet. Creating one now.')
+        const server = await promptServerDetails()
+        servers.push(server)
+        await persistServers(servers)
+        logSuccess?.('Saved server configuration to ~/.config/zephyr/servers.json')
+        return server
+    }
+
+    const choices = servers.map((server, index) => ({
+        name: `${server.serverName} (${server.serverIp})`,
+        value: index
+    }))
+
+    choices.push(
+        new inquirer.Separator(),
+        {
+            name: '➕ Create a new server',
+            value: 'create'
+        }
+    )
+
+    const {selection} = await runPrompt([
+        {
+            type: 'list',
+            name: 'selection',
+            message: 'Select a server',
+            choices,
+            default: 0
+        }
+    ])
+
+    if (selection === 'create') {
+        const server = await promptServerDetails(servers)
+        servers.push(server)
+        await persistServers(servers)
+        logSuccess?.('Appended server configuration to ~/.config/zephyr/servers.json')
+        return server
+    }
+
+    return servers[selection]
+}