@take-out/scripts 0.4.2 → 0.4.3-1775767446169

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@take-out/scripts",
-  "version": "0.4.2",
+  "version": "0.4.3-1775767446169",
   "type": "module",
   "main": "./src/cmd.ts",
   "sideEffects": false,
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@take-out/helpers": "0.4.2",
-    "@take-out/run": "0.4.2",
+    "@take-out/helpers": "0.4.3-1775767446169",
+    "@take-out/run": "0.4.3-1775767446169",
     "picocolors": "^1.1.1"
   }
 }

package/src/helpers/deploy-lock.ts

@@ -2,9 +2,13 @@
  * deploy lock helper — prevents concurrent deploys with auto-expiry
  * shared across repos via @take-out/scripts/helpers/deploy-lock
  *
- * uses mkdir for atomic lock acquisition (no race window)
+ * uses mkdir for atomic lock acquisition (no race window).
+ * writes a meta.json inside the lock dir so stale locks can self-diagnose:
+ * when a deploy dies without releasing, the next deploy prints who left the
+ * lock (pid, host, git sha, CI run URL) instead of just a timestamp.
  */
 
+import os from 'node:os'
 import { run } from './run'
 
 const DEFAULT_LOCK_PATH = '/tmp/deploy.lock'
@@ -13,6 +17,56 @@ const DEFAULT_MAX_AGE_MIN = 15
 interface DeployLockOptions {
   path?: string
   maxAgeMin?: number
+  /**
+   * called before lock release on all exit paths: normal return, thrown
+   * error, and signal (SIGTERM/SIGINT/SIGHUP). use this to roll back
+   * partial state — e.g. restart a service that was stopped mid-deploy.
+   * cleanup errors are logged but do not prevent lock release.
+   */
+  cleanup?: () => Promise<void>
+}
+
+interface LockMeta {
+  pid: number
+  host: string
+  startedAt: string
+  gitSha: string
+  ciRunId: string
+  ciRunUrl: string
+  ciWorkflow: string
+  ciActor: string
+}
+
+function buildMeta(): LockMeta {
+  const repo = process.env.GITHUB_REPOSITORY || ''
+  const runId = process.env.GITHUB_RUN_ID || ''
+  const server = process.env.GITHUB_SERVER_URL || 'https://github.com'
+  const ciRunUrl = repo && runId ? `${server}/${repo}/actions/runs/${runId}` : ''
+  return {
+    pid: process.pid,
+    host: os.hostname(),
+    startedAt: new Date().toISOString(),
+    gitSha:
+      process.env.GIT_SHA || process.env.GITHUB_SHA || process.env.CI_COMMIT_SHA || '',
+    ciRunId: runId,
+    ciRunUrl,
+    ciWorkflow: process.env.GITHUB_WORKFLOW || '',
+    ciActor: process.env.GITHUB_ACTOR || '',
+  }
+}
+
+function toBase64(s: string): string {
+  return Buffer.from(s, 'utf-8').toString('base64')
+}
+
+async function sshBash(ssh: string, script: string, captureOutput = true) {
+  // base64-encode the script so we never have to escape quotes, $, backticks,
+  // newlines etc. at multiple layers (local bash → ssh → remote bash).
+  const b64 = toBase64(script)
+  return run(`${ssh} "echo ${b64} | base64 -d | bash"`, {
+    captureOutput,
+    silent: true,
+  })
 }
 
 export async function acquireDeployLock(
@@ -22,27 +76,83 @@ export async function acquireDeployLock(
   const lockPath = opts?.path || DEFAULT_LOCK_PATH
   const maxAge = opts?.maxAgeMin || DEFAULT_MAX_AGE_MIN
 
-  // mkdir is atomic — if two deploys race, only one succeeds
-  const lockCmd = [
-    // clean stale locks first
-    `find ${lockPath} -maxdepth 0 -mmin +${maxAge} -exec rm -rf {} \\; 2>/dev/null || true`,
-    // atomic acquire via mkdir (fails if dir already exists)
-    `mkdir ${lockPath} 2>/dev/null && echo "OK" || echo "LOCKED"`,
-  ].join('; ')
+  // atomic cleanup-and-acquire in one round-trip:
+  // 1. if a stale lock exists (older than maxAge), print its metadata so the
+  //    caller can log who left it behind, then rm it.
+  // 2. try mkdir — atomic; succeeds iff no concurrent deploy holds the lock.
+  const acquireScript = `
+set -u
+LOCK=${lockPath}
+MAXAGE=${maxAge}
+if [ -d "$LOCK" ]; then
+  if [ -n "$(find "$LOCK" -maxdepth 0 -mmin +$MAXAGE 2>/dev/null)" ]; then
+    echo "STALE_META_START"
+    cat "$LOCK/meta.json" 2>/dev/null || echo "(no metadata file)"
+    echo "STALE_META_END"
+    rm -rf "$LOCK"
+  fi
+fi
+if mkdir "$LOCK" 2>/dev/null; then
+  echo ACQUIRED
+else
+  echo LOCKED
+fi
+`
 
-  const { stdout } = await run(`${ssh} "${lockCmd}"`, {
-    captureOutput: true,
-    silent: true,
-  })
-  const result = stdout.trim()
+  const { stdout: acquireOut } = await sshBash(ssh, acquireScript)
+
+  // log any stale cleanup so the next deploy's logs show who left it
+  const staleMatch = acquireOut.match(/STALE_META_START\n([\s\S]*?)\nSTALE_META_END/)
+  if (staleMatch) {
+    console.warn(`deploy-lock: cleared stale lock (older than ${maxAge}m) left by:`)
+    for (const line of staleMatch[1].split('\n')) {
+      console.warn(`  ${line}`)
+    }
+  }
+
+  if (!acquireOut.trim().endsWith('ACQUIRED')) {
+    // read the live holder's metadata so the error tells the user exactly
+    // which deploy is blocking — not just "a lock file exists".
+    const diagScript = `
+LOCK=${lockPath}
+echo "meta.json:"
+cat "$LOCK/meta.json" 2>/dev/null || echo "  (no metadata)"
+echo "mtime:"
+stat -c "  %y" "$LOCK" 2>/dev/null || echo "  (unknown)"
+`
+    let heldBy = '(diagnostics unavailable)'
+    try {
+      const { stdout } = await sshBash(ssh, diagScript)
+      heldBy = stdout.trim() || heldBy
+    } catch {
+      // best-effort
+    }
 
-  if (result === 'LOCKED') {
     throw new Error(
-      `another deploy is in progress (${lockPath} exists on server). ` +
-        `if stale, it will auto-expire after ${maxAge} minutes, ` +
-        `or remove manually: ${ssh} "rm -rf ${lockPath}"`,
+      `another deploy is in progress (${lockPath} exists on server)\n` +
+        `  held by:\n${heldBy
+          .split('\n')
+          .map((l) => `    ${l}`)
+          .join('\n')}\n` +
+        `  will auto-expire after ${maxAge} minutes, or remove manually: ${ssh} "rm -rf ${lockPath}"`,
     )
   }
+
+  // write metadata inside the lock dir (best-effort; lock is already held
+  // so metadata failures are non-fatal — they only hurt future diagnostics).
+  const meta = buildMeta()
+  const metaJson = JSON.stringify(meta, null, 2)
+  const writeScript = `
+LOCK=${lockPath}
+cat > "$LOCK/meta.json" << 'DEPLOY_LOCK_META_EOF'
+${metaJson}
+DEPLOY_LOCK_META_EOF
+`
+  try {
+    await sshBash(ssh, writeScript, false)
+  } catch {
+    // non-fatal
+  }
 }
 
 export async function releaseDeployLock(
@@ -66,6 +176,10 @@ export async function releaseDeployLock(
  * signals, so a CI-cancelled deploy would leak the lock for 15 minutes and
  * block the next run. this helper installs signal handlers that release
  * before exit, then removes them once `fn` completes.
+ *
+ * if `opts.cleanup` is provided, it runs before lock release on every exit
+ * path. use it to roll back partial deploy state (e.g. restart a stopped
+ * service) so a mid-flight crash doesn't leave prod in a broken state.
  */
 export async function withDeployLock<T>(
   ssh: string,
@@ -75,20 +189,28 @@ export async function withDeployLock<T>(
   await acquireDeployLock(ssh, opts)
 
   let released = false
-  const release = async () => {
+  const runCleanupAndRelease = async () => {
     if (released) return
     released = true
+    if (opts?.cleanup) {
+      try {
+        await opts.cleanup()
+      } catch (err) {
+        console.warn('deploy-lock: cleanup threw (non-fatal):', err)
+      }
+    }
     await releaseDeployLock(ssh, opts)
   }
 
-  // signal handlers — fire-and-forget release with a safety timeout so the
-  // process always exits even if the ssh release hangs
+  // signal handlers — fire-and-forget cleanup+release with a safety timeout
+  // so the process always exits even if ssh hangs. the 15s budget covers
+  // user cleanup (e.g. restarting a service) plus the release rm call.
   const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT', 'SIGHUP']
   const handlers = new Map<NodeJS.Signals, () => void>()
   for (const sig of signals) {
     const handler = () => {
-      const done = release().catch(() => {})
-      const timeout = new Promise<void>((r) => setTimeout(r, 5_000))
+      const done = runCleanupAndRelease().catch(() => {})
+      const timeout = new Promise<void>((r) => setTimeout(r, 15_000))
       Promise.race([done, timeout]).finally(() => {
         process.exit(sig === 'SIGINT' ? 130 : 143)
       })
@@ -103,6 +225,6 @@ export async function withDeployLock<T>(
     for (const [sig, handler] of handlers) {
       process.off(sig, handler)
     }
-    await release()
+    await runCleanupAndRelease()
   }
 }

package/src/helpers/env-load.ts

@@ -9,9 +9,25 @@ export async function loadEnv(
   // loads env into process.env
   await vxrnLoadEnv(environment)
 
-  // import src/env.ts to get the env config applied (side effect: populates process.env)
-  const envModule = await import(join(process.cwd(), 'src/env.ts'))
-  const Environment = envModule.server || {}
+  const previousMode = process.env.TAKEOUT_ENV_MODE
+  if (environment === 'development' || environment === 'production') {
+    process.env.TAKEOUT_ENV_MODE = environment
+  } else {
+    delete process.env.TAKEOUT_ENV_MODE
+  }
+
+  let Environment: Record<string, string>
+  try {
+    // import src/env.ts to get the env config applied (side effect: populates process.env)
+    const envModule = await import(join(process.cwd(), 'src/env.ts'))
+    Environment = envModule.server || {}
+  } finally {
+    if (previousMode === undefined) {
+      delete process.env.TAKEOUT_ENV_MODE
+    } else {
+      process.env.TAKEOUT_ENV_MODE = previousMode
+    }
+  }
 
   // validate
   for (const key in Environment) {

package/src/helpers/get-test-env.ts

@@ -22,6 +22,10 @@ export async function getTestEnv() {
     ...serverEnvFallback,
     ...devEnv,
     CI: 'true',
+    // Child test processes may import src/env.ts directly. Keep them pinned to
+    // development mode even when the parent release flow started from
+    // production-flavored env.
+    TAKEOUT_ENV_MODE: 'development',
     ...(!process.env.DEBUG_BACKEND && {
       ZERO_LOG_LEVEL: 'warn',
     }),

package/src/update-changelog.ts

@@ -70,7 +70,23 @@ Instructions:
 
 Archiving old entries:
 - keep only 10 weeks in changelog.mdx
-- when over 10 weeks, move oldest entries to changelog-YYYY.mdx (by year, e.g. changelog-2025.mdx)
-- add a link at the bottom of changelog.mdx: "See [2025 changes](/docs/changelog-2025)" etc (use absolute path)
+- when over 10 weeks, move the oldest entries into an archive file named
+  changelog-YYYY.mdx, where YYYY is the year the archived WEEK is from
+  (not the current year). e.g. a "Week of January 27, 2026" entry belongs
+  in changelog-2026.mdx, not changelog-2025.mdx — even if 2025 already
+  exists as an archive. never mix years in the same archive file.
+- if the target archive file doesn't exist yet, create it with frontmatter:
+    ---
+    title: Changelog Archive — YYYY
+    description: Archived Takeout updates from YYYY
+    ---
+  and end the file with a link chain to the previous year's archive if
+  one exists, e.g. "See [2025 changes](/docs/changelog-2025) for earlier updates."
+- if the archive already exists, prepend the new weeks to the top
+  (after frontmatter), so it stays in reverse-chronological order
+- at the bottom of changelog.mdx, list links to every archive file that
+  exists, newest first, e.g.
+  "See [early 2026 changes](/docs/changelog-2026) and [2025 changes](/docs/changelog-2025) for previous updates."
+  (use absolute paths, update the list whenever a new archive file is created)
 `)
 })