video_translate/docs/plans/2026-03-18-ubuntu-start-script.md

Ubuntu Start Script Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add Ubuntu development scripts that can start the app in the background and stop it later without requiring the caller to cd first.

Architecture: Keep Bash entrypoints in the repository root. start-dev.sh resolves the project directory, creates a run/ working area, launches npm run dev in a dedicated process group, and records the group leader PID and log path. stop.sh reads the recorded PID, stops the whole process group, and removes stale state.

Tech Stack: Bash, npm

---

Task 1: Add Ubuntu start and stop scripts

Files:

• Modify: E:\Downloads\ai-video-dubbing-&-translation\start-dev.sh
• Create: E:\Downloads\ai-video-dubbing-&-translation\stop.sh
• Create: E:\Downloads\ai-video-dubbing-&-translation\docs\plans\2026-03-18-ubuntu-start-script.md

Step 1: Define the verification target

Run: bash -n ./start-dev.sh Expected: exit code 0 after the script is updated

Run: bash -n ./stop.sh Expected: exit code 0 after the script is added

Step 2: Write the minimal implementation

Update start-dev.sh so it:

• uses #!/usr/bin/env bash
• enables set -euo pipefail
• resolves the script directory
• changes into that directory
• creates run/
• starts npm run dev in the background as its own process group
• writes the process id to run/dev.pid
• writes logs to run/dev.log
• refuses to start a second copy if the PID is still alive

Create stop.sh so it:

• resolves the script directory
• reads run/dev.pid
• sends TERM to the whole process group if it is running
• waits briefly and escalates to KILL only if needed
• removes stale run/dev.pid

Step 3: Run syntax verification

Run: bash -n ./start-dev.sh Expected: exit code 0 with no syntax errors

Run: bash -n ./stop.sh Expected: exit code 0 with no syntax errors

Step 4: Run an execution smoke check

Run: bash ./start-dev.sh Expected: npm starts the development server in the background and prints the PID/log location

Run: bash ./stop.sh Expected: the background dev process stops and the PID file is removed