@wyxos/zephyr 0.1.2 → 0.1.4

package/.github/copilot-instructions.md

@@ -0,0 +1,35 @@
+# Copilot Instructions
+
+## Project Snapshot
+- Command-line deployment tool (`bin/zephyr.mjs`) that delegates to `src/index.mjs` for all logic.
+- Node.js ESM project; keep imports as `import … from` and avoid CommonJS helpers.
+- Primary responsibilities: gather deployment config via prompts, ensure local git state, SSH into remote servers, run per-change maintenance tasks.
+
+## Configuration Model
+- Global servers live at `~/.config/zephyr/servers.json` (array of `{ serverName, serverIp }`).
+- Per-project apps live at `.zephyr/config.json` (apps array with `{ serverName, projectPath, branch, sshUser, sshKey }`).
+- `main()` now sequences: ensure `.zephyr/` ignored, load servers, pick/create one, load project config, pick/create app, ensure SSH details, run deployment.
+- When adding config logic, reuse helpers: `selectServer`, `promptServerDetails`, `selectApp`, `promptAppDetails`, `ensureProjectConfig`.
+
+## Deployment Flow Highlights
+- Always call `ensureLocalRepositoryState(branch)` before SSH. It:
+  - Verifies current branch, fast-forwards with `git pull --ff-only`, warns if ahead, commits + pushes uncommitted changes when needed.
+  - Prompts for commit message if dirty and pushes to `origin/<branch>`.
+- Remote execution happens via `runRemoteTasks(config)`; keep all SSH commands funneled through `executeRemote(label, command, options)` to inherit logging and error handling.
+- Laravel detection toggles extra tasks—Composer, migrations, npm install/build, cache clears, queue restarts—based on changed files from `git diff HEAD..origin/<branch>`.
+
+## Release Workflow
+- Automated publishing script at `publish.mjs` (`npm run release`):
+  - Checks clean working tree, fetches & fast-forwards branch, runs `npx vitest run`, bumps version via `npm version <type>`, pushes with tags, publishes (adds `--access public` for scoped packages).
+  - `npm pkg fix` may adjust `package.json`; commit results before running the release.
+
+## Testing & Tooling
+- Test suite: `npm test` (Vitest). Mocks for fs, child_process, inquirer, node-ssh are set up—extend them for new behaviors rather than shelling out.
+- Avoid long-running watchers in scripts; tests spawn Vitest in watch mode by default, so kill (`pkill -f vitest`) after scripted runs when necessary.
+
+## Conventions & Style
+- Logging helpers (`logProcessing`, `logSuccess`, `logWarning`, `logError`) centralize colored output—use them instead of `console.log` in new deployment logic.
+- Use async/await with `runCommand` / `runCommandCapture` for local shell ops; never `exec` directly.
+- Keep new prompts routed through `runPrompt`; it supports injection for tests.
+- Default to ASCII in files; comments only where logic is non-obvious.
+- Update Vitest cases in `tests/index.test.js` when altering prompts, config structure, or deployment steps; tests expect deterministic logging text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyxos/zephyr",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "scripts": {
     "test": "vitest",

package/publish.mjs

@@ -97,6 +97,18 @@ async function ensureUpToDateWithUpstream(branch, upstreamRef) {
     return
   }
 
+  const [remoteName, ...branchParts] = upstreamRef.split('/')
+  const remoteBranch = branchParts.join('/')
+
+  if (remoteName && remoteBranch) {
+    logStep(`Fetching latest updates from ${remoteName}/${remoteBranch}...`)
+    try {
+      await runCommand('git', ['fetch', remoteName, remoteBranch])
+    } catch (error) {
+      throw new Error(`Failed to fetch ${upstreamRef}: ${error.message}`)
+    }
+  }
+
   const aheadResult = await runCommand('git', ['rev-list', '--count', `${upstreamRef}..HEAD`], {
     capture: true
   })
@@ -108,6 +120,20 @@ async function ensureUpToDateWithUpstream(branch, upstreamRef) {
   const behind = Number.parseInt(behindResult.stdout || '0', 10)
 
   if (Number.isFinite(behind) && behind > 0) {
+    if (remoteName && remoteBranch) {
+      logStep(`Fast-forwarding ${branch} with ${upstreamRef}...`)
+
+      try {
+        await runCommand('git', ['pull', '--ff-only', remoteName, remoteBranch])
+      } catch (error) {
+        throw new Error(
+          `Unable to fast-forward ${branch} with ${upstreamRef}. Resolve conflicts manually, then rerun the release.\n${error.message}`
+        )
+      }
+
+      return ensureUpToDateWithUpstream(branch, upstreamRef)
+    }
+
     throw new Error(
       `Branch ${branch} is behind ${upstreamRef} by ${behind} commit${behind === 1 ? '' : 's'}. Pull or rebase first.`
     )

package/src/index.mjs

@@ -6,7 +6,10 @@ import chalk from 'chalk'
 import inquirer from 'inquirer'
 import { NodeSSH } from 'node-ssh'
 
-const RELEASE_FILE = 'release.json'
+const PROJECT_CONFIG_DIR = '.zephyr'
+const PROJECT_CONFIG_FILE = 'config.json'
+const GLOBAL_CONFIG_DIR = path.join(os.homedir(), '.config', 'zephyr')
+const SERVERS_FILE = path.join(GLOBAL_CONFIG_DIR, 'servers.json')
 
 const logProcessing = (message = '') => console.log(chalk.yellow(message))
 const logSuccess = (message = '') => console.log(chalk.green(message))
@@ -194,6 +197,33 @@ async function ensureLocalRepositoryState(targetBranch, rootDir = process.cwd())
   const initialStatus = await getGitStatus(rootDir)
   const hasPendingChanges = initialStatus.length > 0
 
+  const statusReport = await runCommandCapture('git', ['status', '--short', '--branch'], {
+    cwd: rootDir
+  })
+
+  const lines = statusReport.split(/\r?\n/)
+  const branchLine = lines[0] || ''
+  const aheadMatch = branchLine.match(/ahead (\d+)/)
+  const behindMatch = branchLine.match(/behind (\d+)/)
+  const aheadCount = aheadMatch ? parseInt(aheadMatch[1], 10) : 0
+  const behindCount = behindMatch ? parseInt(behindMatch[1], 10) : 0
+
+  if (aheadCount > 0) {
+    logWarning(`Local branch ${currentBranch} is ahead of upstream by ${aheadCount} commit${aheadCount === 1 ? '' : 's'}.`)
+  }
+
+  if (behindCount > 0) {
+    logProcessing(`Synchronizing local branch ${currentBranch} with its upstream...`)
+    try {
+      await runCommand('git', ['pull', '--ff-only'], { cwd: rootDir })
+      logSuccess('Local branch fast-forwarded with upstream changes.')
+    } catch (error) {
+      throw new Error(
+        `Unable to fast-forward ${currentBranch} with upstream changes. Resolve conflicts manually, then rerun the deployment.\n${error.message}`
+      )
+    }
+  }
+
   if (currentBranch !== targetBranch) {
     if (hasPendingChanges) {
       throw new Error(
@@ -245,6 +275,7 @@ async function ensureLocalRepositoryState(targetBranch, rootDir = process.cwd())
 
 async function ensureGitignoreEntry(rootDir) {
   const gitignorePath = path.join(rootDir, '.gitignore')
+  const targetEntry = `${PROJECT_CONFIG_DIR}/`
   let existingContent = ''
 
   try {
@@ -257,18 +288,18 @@ async function ensureGitignoreEntry(rootDir) {
 
   const hasEntry = existingContent
     .split(/\r?\n/)
-    .some((line) => line.trim() === RELEASE_FILE)
+    .some((line) => line.trim() === targetEntry)
 
   if (hasEntry) {
     return
   }
 
   const updatedContent = existingContent
-    ? `${existingContent.replace(/\s*$/, '')}\n${RELEASE_FILE}\n`
-    : `${RELEASE_FILE}\n`
+    ? `${existingContent.replace(/\s*$/, '')}\n${targetEntry}\n`
+    : `${targetEntry}\n`
 
   await fs.writeFile(gitignorePath, updatedContent)
-  logSuccess('Added release.json to .gitignore')
+  logSuccess('Added .zephyr/ to .gitignore')
 
   let isGitRepo = false
   try {
@@ -287,7 +318,7 @@ async function ensureGitignoreEntry(rootDir) {
 
   try {
     await runCommand('git', ['add', '.gitignore'], { cwd: rootDir })
-    await runCommand('git', ['commit', '-m', 'chore: ignore release config'], { cwd: rootDir })
+    await runCommand('git', ['commit', '-m', 'chore: ignore zephyr config'], { cwd: rootDir })
   } catch (error) {
     if (error.exitCode === 1) {
       logWarning('Git commit skipped: nothing to commit or pre-commit hook prevented commit.')
@@ -297,9 +328,13 @@ async function ensureGitignoreEntry(rootDir) {
   }
 }
 
-async function loadReleases(filePath) {
+async function ensureDirectory(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true })
+}
+
+async function loadServers() {
   try {
-    const raw = await fs.readFile(filePath, 'utf8')
+    const raw = await fs.readFile(SERVERS_FILE, 'utf8')
     const data = JSON.parse(raw)
     return Array.isArray(data) ? data : []
   } catch (error) {
@@ -307,14 +342,45 @@ async function loadReleases(filePath) {
       return []
     }
 
-    logWarning('Failed to read release.json, starting with an empty list.')
+    logWarning('Failed to read servers.json, starting with an empty list.')
     return []
   }
 }
 
-async function saveReleases(filePath, releases) {
-  const payload = JSON.stringify(releases, null, 2)
-  await fs.writeFile(filePath, `${payload}\n`)
+async function saveServers(servers) {
+  await ensureDirectory(GLOBAL_CONFIG_DIR)
+  const payload = JSON.stringify(servers, null, 2)
+  await fs.writeFile(SERVERS_FILE, `${payload}\n`)
+}
+
+function getProjectConfigPath(rootDir) {
+  return path.join(rootDir, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILE)
+}
+
+async function loadProjectConfig(rootDir) {
+  const configPath = getProjectConfigPath(rootDir)
+
+  try {
+    const raw = await fs.readFile(configPath, 'utf8')
+    const data = JSON.parse(raw)
+    return {
+      apps: Array.isArray(data?.apps) ? data.apps : []
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { apps: [] }
+    }
+
+    logWarning('Failed to read .zephyr/config.json, starting with an empty list of apps.')
+    return { apps: [] }
+  }
+}
+
+async function saveProjectConfig(rootDir, config) {
+  const configDir = path.join(rootDir, PROJECT_CONFIG_DIR)
+  await ensureDirectory(configDir)
+  const payload = JSON.stringify({ apps: config.apps ?? [] }, null, 2)
+  await fs.writeFile(path.join(configDir, PROJECT_CONFIG_FILE), `${payload}\n`)
 }
 
 function defaultProjectPath(currentDir) {
@@ -719,14 +785,10 @@ async function runRemoteTasks(config) {
   }
 }
 
-async function collectServerConfig(currentDir) {
-  const branches = await listGitBranches(currentDir)
-  const defaultBranch = branches.includes('master') ? 'master' : branches[0]
+async function promptServerDetails(existingServers = []) {
   const defaults = {
-    serverName: 'home',
-    serverIp: '1.1.1.1',
-    projectPath: defaultProjectPath(currentDir),
-    branch: defaultBranch
+    serverName: existingServers.length === 0 ? 'home' : `server-${existingServers.length + 1}`,
+    serverIp: '1.1.1.1'
   }
 
   const answers = await runPrompt([
@@ -739,19 +801,77 @@ async function collectServerConfig(currentDir) {
     {
       type: 'input',
       name: 'serverIp',
-      message: 'Server IP',
+      message: 'Server IP address',
       default: defaults.serverIp
-    },
+    }
+  ])
+
+  return {
+    serverName: answers.serverName.trim() || defaults.serverName,
+    serverIp: answers.serverIp.trim() || defaults.serverIp
+  }
+}
+
+async function selectServer(servers) {
+  if (servers.length === 0) {
+    logProcessing("No servers configured. Let's create one.")
+    const server = await promptServerDetails()
+    servers.push(server)
+    await saveServers(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: '➕ Register a new server',
+    value: 'create'
+  })
+
+  const { selection } = await runPrompt([
+    {
+      type: 'list',
+      name: 'selection',
+      message: 'Select server or register new',
+      choices,
+      default: 0
+    }
+  ])
+
+  if (selection === 'create') {
+    const server = await promptServerDetails(servers)
+    servers.push(server)
+    await saveServers(servers)
+    logSuccess('Appended server configuration to ~/.config/zephyr/servers.json')
+    return server
+  }
+
+  return servers[selection]
+}
+
+async function promptAppDetails(currentDir, existing = {}) {
+  const branches = await listGitBranches(currentDir)
+  const defaultBranch = existing.branch || (branches.includes('master') ? 'master' : branches[0])
+  const defaults = {
+    projectPath: existing.projectPath || defaultProjectPath(currentDir),
+    branch: defaultBranch
+  }
+
+  const answers = await runPrompt([
     {
       type: 'input',
       name: 'projectPath',
-      message: 'Project path',
+      message: 'Remote project path',
       default: defaults.projectPath
     },
     {
       type: 'list',
       name: 'branchSelection',
-      message: 'Branch',
+      message: 'Branch to deploy',
       choices: [
         ...branches.map((branch) => ({ name: branch, value: branch })),
         new inquirer.Separator(),
@@ -764,7 +884,7 @@ async function collectServerConfig(currentDir) {
   let branch = answers.branchSelection
 
   if (branch === '__custom') {
-    const { customBranch } = await inquirer.prompt([
+    const { customBranch } = await runPrompt([
       {
         type: 'input',
         name: 'customBranch',
@@ -776,25 +896,41 @@ async function collectServerConfig(currentDir) {
     branch = customBranch.trim() || defaults.branch
   }
 
-  const sshDetails = await promptSshDetails(currentDir)
+  const sshDetails = await promptSshDetails(currentDir, existing)
 
   return {
-    serverName: answers.serverName,
-    serverIp: answers.serverIp,
-    projectPath: answers.projectPath,
+    projectPath: answers.projectPath.trim() || defaults.projectPath,
     branch,
     ...sshDetails
   }
 }
 
-async function promptSelection(releases) {
-  const choices = releases.map((entry, index) => ({
-    name: `${entry.serverName} (${entry.serverIp})` || `Server ${index + 1}`,
+async function selectApp(projectConfig, server, currentDir) {
+  const apps = projectConfig.apps ?? []
+  const matches = apps
+    .map((app, index) => ({ app, index }))
+    .filter(({ app }) => app.serverName === server.serverName)
+
+  if (matches.length === 0) {
+    logProcessing(`No applications configured for ${server.serverName}. Let's create one.`)
+    const appDetails = await promptAppDetails(currentDir)
+    const appConfig = {
+      serverName: server.serverName,
+      ...appDetails
+    }
+    projectConfig.apps.push(appConfig)
+    await saveProjectConfig(currentDir, projectConfig)
+    logSuccess('Saved deployment configuration to .zephyr/config.json')
+    return appConfig
+  }
+
+  const choices = matches.map(({ app, index }) => ({
+    name: `${app.projectPath} (${app.branch})`,
     value: index
   }))
 
   choices.push(new inquirer.Separator(), {
-    name: '➕ Create new deployment target',
+    name: '➕ Configure new application for this server',
     value: 'create'
   })
 
@@ -802,55 +938,58 @@ async function promptSelection(releases) {
     {
       type: 'list',
       name: 'selection',
-      message: 'Select server or create new',
+      message: `Select application for ${server.serverName}`,
       choices,
       default: 0
     }
   ])
 
-  return selection
+  if (selection === 'create') {
+    const appDetails = await promptAppDetails(currentDir)
+    const appConfig = {
+      serverName: server.serverName,
+      ...appDetails
+    }
+    projectConfig.apps.push(appConfig)
+    await saveProjectConfig(currentDir, projectConfig)
+    logSuccess('Appended deployment configuration to .zephyr/config.json')
+    return appConfig
+  }
+
+  const chosen = projectConfig.apps[selection]
+  return chosen
 }
 
 async function main() {
   const rootDir = process.cwd()
-  const releasePath = path.join(rootDir, RELEASE_FILE)
 
   await ensureGitignoreEntry(rootDir)
 
-  const releases = await loadReleases(releasePath)
+  const servers = await loadServers()
+  const server = await selectServer(servers)
+  const projectConfig = await loadProjectConfig(rootDir)
+  const appConfig = await selectApp(projectConfig, server, rootDir)
 
-  if (releases.length === 0) {
-    logProcessing("No deployment targets found. Let's create one.")
-    const config = await collectServerConfig(rootDir)
-    releases.push(config)
-    await saveReleases(releasePath, releases)
-    logSuccess('Saved deployment configuration to release.json')
-    await runRemoteTasks(config)
-    return
-  }
+  const updated = await ensureSshDetails(appConfig, rootDir)
 
-  const selection = await promptSelection(releases)
-
-  if (selection === 'create') {
-    const config = await collectServerConfig(rootDir)
-    releases.push(config)
-    await saveReleases(releasePath, releases)
-    logSuccess('Appended new deployment configuration to release.json')
-    await runRemoteTasks(config)
-    return
+  if (updated) {
+    await saveProjectConfig(rootDir, projectConfig)
+    logSuccess('Updated .zephyr/config.json with SSH details.')
   }
 
-  const chosen = releases[selection]
-  const updated = await ensureSshDetails(chosen, rootDir)
-
-  if (updated) {
-    await saveReleases(releasePath, releases)
-    logSuccess('Updated release.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:')
-  console.log(JSON.stringify(chosen, null, 2))
+  console.log(JSON.stringify(deploymentConfig, null, 2))
 
-  await runRemoteTasks(chosen)
+  await runRemoteTasks(deploymentConfig)
 }
 
 export {
@@ -859,9 +998,14 @@ export {
   resolveRemotePath,
   isPrivateKeyFile,
   runRemoteTasks,
-  collectServerConfig,
+  promptServerDetails,
+  selectServer,
+  promptAppDetails,
+  selectApp,
   promptSshDetails,
   ensureSshDetails,
   ensureLocalRepositoryState,
+  loadServers,
+  loadProjectConfig,
   main
 }

package/tests/index.test.js

@@ -4,6 +4,7 @@ const mockReadFile = vi.fn()
 const mockReaddir = vi.fn()
 const mockAccess = vi.fn()
 const mockWriteFile = vi.fn()
+const mockMkdir = vi.fn()
 const mockExecCommand = vi.fn()
 const mockConnect = vi.fn()
 const mockDispose = vi.fn()
@@ -14,12 +15,14 @@ vi.mock('node:fs/promises', () => ({
     readFile: mockReadFile,
     readdir: mockReaddir,
     access: mockAccess,
-    writeFile: mockWriteFile
+    writeFile: mockWriteFile,
+    mkdir: mockMkdir
   },
   readFile: mockReadFile,
   readdir: mockReaddir,
   access: mockAccess,
-  writeFile: mockWriteFile
+  writeFile: mockWriteFile,
+  mkdir: mockMkdir
 }))
 
 const spawnQueue = []
@@ -90,11 +93,18 @@ vi.mock('node:child_process', () => ({
   }
 }))
 
-vi.mock('inquirer', () => ({
-  default: {
+vi.mock('inquirer', () => {
+  class Separator {}
+
+  return {
+    default: {
+      prompt: mockPrompt,
+      Separator
+    },
+    Separator,
     prompt: mockPrompt
   }
-}))
+})
 
 vi.mock('node-ssh', () => ({
   NodeSSH: vi.fn(() => ({
@@ -122,6 +132,7 @@ describe('zephyr deployment helpers', () => {
     mockReaddir.mockReset()
     mockAccess.mockReset()
     mockWriteFile.mockReset()
+  mockMkdir.mockReset()
     mockExecCommand.mockReset()
     mockConnect.mockReset()
     mockDispose.mockReset()
@@ -196,6 +207,52 @@ describe('zephyr deployment helpers', () => {
     })
   })
 
+  describe('configuration management', () => {
+    it('registers a new server when none exist', async () => {
+      mockPrompt.mockResolvedValueOnce({ serverName: 'production', serverIp: '203.0.113.10' })
+
+      const { selectServer } = await import('../src/index.mjs')
+
+      const servers = []
+      const server = await selectServer(servers)
+
+      expect(server).toEqual({ serverName: 'production', serverIp: '203.0.113.10' })
+      expect(servers).toHaveLength(1)
+      expect(mockMkdir).toHaveBeenCalledWith(expect.stringContaining('.config/zephyr'), { recursive: true })
+      const [writePath, payload] = mockWriteFile.mock.calls.at(-1)
+      expect(writePath).toContain('servers.json')
+      expect(payload).toContain('production')
+    })
+
+    it('creates a new application configuration when none exist for a server', async () => {
+      queueSpawnResponse({ stdout: 'main\n' })
+      mockPrompt
+        .mockResolvedValueOnce({ projectPath: '~/webapps/demo', branchSelection: 'main' })
+        .mockResolvedValueOnce({ sshUser: 'forge', sshKeySelection: '/home/local/.ssh/id_rsa' })
+      mockReaddir.mockResolvedValue([])
+
+      const { selectApp } = await import('../src/index.mjs')
+
+      const projectConfig = { apps: [] }
+      const server = { serverName: 'production', serverIp: '203.0.113.10' }
+
+      const app = await selectApp(projectConfig, server, process.cwd())
+
+      expect(app).toMatchObject({
+        serverName: 'production',
+        projectPath: '~/webapps/demo',
+        branch: 'main',
+        sshUser: 'forge',
+        sshKey: '/home/local/.ssh/id_rsa'
+      })
+      expect(projectConfig.apps).toHaveLength(1)
+      expect(mockMkdir).toHaveBeenCalledWith(expect.stringContaining('.zephyr'), { recursive: true })
+      const [writePath, payload] = mockWriteFile.mock.calls.at(-1)
+      expect(writePath).toContain('.zephyr/config.json')
+      expect(payload).toContain('~/webapps/demo')
+    })
+  })
+
   it('schedules Laravel tasks based on diff', async () => {
     queueSpawnResponse({ stdout: 'main\n' })
     queueSpawnResponse({ stdout: '' })