AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
feat(confirm-ui): share port 5050 with live preview + mandatory Step 4 shutdown
hugohe37014eeba884c
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex f53dd692..3d48530b 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -296,9 +296,14 @@ Read references/strategist.md```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait```- Page opens at `http://localhost:4040`; port conflict → `--port <other>` and report the actual URL. When the user clicks **Confirm**, the command exits 0 and Step 4 reads `result.json` immediately; do not require a second chat confirmation. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host, browser never confirms in time), do **NOT** troubleshoot. The detached page stays open, so a slow user may confirm after the wait returns — therefore **on any non-zero exit, re-check `<project_path>/confirm_ui/result.json` once (a fresh `status: confirmed`) before** dropping to the chat-summary fallback below.+ Page opens at `http://localhost:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4, freeing the port). Port conflict → `--port <other>` and report the actual URL. When the user clicks **Confirm**, the command exits 0 and Step 4 reads `result.json` immediately; do not require a second chat confirmation. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host, browser never confirms in time), do **NOT** troubleshoot. The detached page stays open, so a slow user may confirm after the wait returns — therefore **on any non-zero exit, re-check `<project_path>/confirm_ui/result.json` once (a fresh `status: confirmed`) before** dropping to the chat-summary fallback below.3. **Always also print the eight recommendations as a short summary in chat, with the URL.** This keeps the chat fallback valid whether or not the browser opened. If the page never appears, the user simply confirms or edits in chat as before.4. This is the ⛔ BLOCKING wait. Preferred page path: the `--wait` command returns after the page writes a fresh `<project_path>/confirm_ui/result.json`; immediately read that file and use its values. On a non-zero exit, re-check `result.json` once (per step 2) — a fresh `status: confirmed` still wins. Chat fallback path: only if no fresh result exists (page didn't open, wait timed out with no confirmation, or the user replies in chat with edits) take the chat values directly. Either path converges. A confirmed `result.json` is an explicit user choice: `generation_mode: "split"` means split mode was chosen; `refine_spec: true` means the refine-spec workflow was chosen.+5. **Close the confirm page (Mandatory cleanup — every path).** Once you have the confirmed values (page **or** chat), shut the confirm server down before leaving Step 4 so it cannot keep holding port 5050 (which Step 6 live preview reuses):+ ```bash+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown+ ```+ This is **idempotent and required regardless of whether Confirm was clicked**: clicking Confirm already shuts the page down (this is then a no-op), but the chat-fallback path leaves the page running — without this cleanup it would block the live preview launch. Run it after reading the confirmation and before proceeding to Step 5.**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate):diff --git a/skills/ppt-master/scripts/confirm_ui/server.py b/skills/ppt-master/scripts/confirm_ui/server.pyindex e3f7a9fc..59a1040b 100644--- a/skills/ppt-master/scripts/confirm_ui/server.py+++ b/skills/ppt-master/scripts/confirm_ui/server.py@@ -20,7 +20,7 @@ Usage:Examples:python3 scripts/confirm_ui/server.py projects/my-project- python3 scripts/confirm_ui/server.py projects/my-project --port 4041+ python3 scripts/confirm_ui/server.py projects/my-project --port 5051python3 scripts/confirm_ui/server.py projects/my-project --no-browserpython3 scripts/confirm_ui/server.py projects/my-project --daemon --wait@@ -38,6 +38,7 @@ import subprocessimport sysimport threadingimport time+import urllib.requestimport webbrowserfrom pathlib import Pathfrom typing import Optional@@ -68,7 +69,11 @@ CONFIRM_DIR_NAME = 'confirm_ui'RECOMMENDATIONS_NAME = 'recommendations.json'RESULT_NAME = 'result.json'-DEFAULT_PORT = 4040+# Shares port 5050 with the live preview server (svg_editor/server.py). The two+# never run at once: confirm is Step 4 and shuts down on confirm (or idle),+# freeing the port before live preview starts at Step 6. One port = one forward+# rule for the whole pipeline. They still keep separate processes and locks.+DEFAULT_PORT = 5050# Default --wait budget, kept just under the 600s Bash-tool ceiling so the# parent (waiting) command returns before the calling harness kills it. The@@ -115,6 +120,51 @@ def _wait_for_result(time.sleep(0.5)+def _shutdown_existing(lock_file: Path) -> int:+ """Stop a confirm server left running for this project (idempotent).++ Step 4 always calls this on exit so the page never lingers on the shared+ port 5050 — whether the user clicked **Confirm** (the page already shut the+ server down) or replied in chat instead (the server is still up). Tries a+ graceful ``/api/shutdown`` first, falls back to killing the recorded pid,+ then clears the lock. A no-op when nothing is running.+ """+ existing = _read_lock(lock_file)+ if not existing:+ logger.info('no confirm server running — nothing to stop')+ return 0+ pid = int(existing.get('pid', 0) or 0)+ port = existing.get('port')+ if not _process_alive(pid):+ _release_lock(lock_file)+ logger.info('confirm server already stopped; cleared stale lock')+ return 0+ # Graceful first: the server flushes and releases its own lock.+ if port:+ try:+ req = urllib.request.Request(+ f'http://127.0.0.1:{port}/api/shutdown',+ data=b'{"reason": "step4-cleanup"}',+ headers={'Content-Type': 'application/json'},+ method='POST',+ )+ urllib.request.urlopen(req, timeout=3)+ except OSError:+ pass # server may already be exiting; fall through to the kill path+ for _ in range(20): # up to ~2s for the graceful exit to land+ if not _process_alive(pid):+ break+ time.sleep(0.1)+ if _process_alive(pid):+ try:+ os.kill(pid, signal.SIGTERM)+ except OSError:+ pass+ _release_lock(lock_file)+ logger.info('confirm server stopped (pid=%s)', pid)+ return 0++# --- app --------------------------------------------------------------------def create_app(@@ -235,6 +285,12 @@ def build_parser() -> argparse.ArgumentParser:'--timeout', type=int, default=900,help='Server idle timeout in seconds (default: 900; 0 = disabled)',)+ parser.add_argument(+ '--shutdown', action='store_true',+ help='Stop a confirm server left running for this project, then exit '+ '(idempotent). Run at the end of Step 4 so the page never lingers '+ 'on the shared port before live preview starts.',+ )return parser@@ -253,6 +309,11 @@ def main(argv: Optional[list[str]] = None) -> int:logger.error('%s is not a directory', project_path)return 1+ # Step 4 cleanup: stop any lingering confirm server and exit. Independent of+ # recommendations.json (the page may never have been confirmed).+ if args.shutdown:+ return _shutdown_existing(project_path / LOCK_FILE_NAME)+rec_file = project_path / CONFIRM_DIR_NAME / RECOMMENDATIONS_NAMEif not rec_file.exists():logger.error(diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex 908beedc..01a4ae9d 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -7,17 +7,19 @@```bashpython3 scripts/confirm_ui/server.py <project_path> --daemon --waitpython3 scripts/confirm_ui/server.py <project_path> --daemon-python3 scripts/confirm_ui/server.py <project_path> --daemon --port 4041+python3 scripts/confirm_ui/server.py <project_path> --daemon --port 5051python3 scripts/confirm_ui/server.py <project_path> --no-browserpython3 scripts/confirm_ui/server.py <project_path> --timeout 0 # disable idle auto-shutdown+python3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 cleanup (idempotent)```-- Binds `127.0.0.1:4040` by default and auto-opens the browser (suppress with `--no-browser`).+- Binds `127.0.0.1:5050` by default and auto-opens the browser (suppress with `--no-browser`).+- **Shares port 5050 with the live preview server** (`svg_editor/server.py`). The two never run at once: confirm is Step 4, live preview is Step 6, and Step 4 always shuts this server down on exit (see `--shutdown`) so the port is free. One port = one forward rule for the whole pipeline. They still keep **separate processes and locks** (`.confirm_ui.lock` vs `.live_preview.lock`).- `--daemon` starts the Flask process in the background; add `--wait` in the main pipeline so the parent command returns only after the page writes a fresh `result.json`. The `--wait` budget defaults to **590 s** (`--wait-timeout`), kept under the typical 600 s tool ceiling — run the launch with a long tool timeout (≈600000 ms). On timeout the parent returns non-zero but the detached server keeps running, so the caller must re-check `result.json` once before the chat fallback (a slow user may confirm just after the wait returns).-- Refuses to start unless `<project_path>/confirm_ui/recommendations.json` exists.+- `--shutdown` stops a confirm server left running for this project and exits — **idempotent** (a no-op when nothing is running). Tries a graceful `/api/shutdown`, falls back to killing the recorded pid, then clears the lock. SKILL.md Step 4 runs this on every path (page-confirm or chat-fallback) so the page never lingers on the shared port before live preview starts.+- Refuses to start unless `<project_path>/confirm_ui/recommendations.json` exists (except `--shutdown`, which needs no recommendations).- Per-project lock at `<project_path>/.confirm_ui.lock` — duplicate launches are refused; stale locks (dead pid) are overwritten.- Idle auto-shutdown after 900 s by default; `/api/shutdown` exits gracefully and releases the lock.-- Independent of the live preview server (`svg_editor/server.py`, port 5050) in process, lock, and content model.Dependency:@@ -132,7 +134,7 @@ Both files live under `<project_path>/confirm_ui/`.- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage custom values must be concrete prose plans, not the literal string `"custom"`. The AI interprets custom text against the canonical references.- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` is `ai` or a custom image plan that may include generated images.-- After the user clicks **Confirm**, the page saves `result.json` and shuts the server down (auto-close). In the default `--daemon --wait` flow, the waiting command returns and the AI reads `result.json` immediately; no second chat confirmation is required. Chat confirmation remains the fallback when the page cannot be used.+- After the user clicks **Confirm**, the page saves `result.json` and shuts the server down (auto-close). In the default `--daemon --wait` flow, the waiting command returns and the AI reads `result.json` immediately; no second chat confirmation is required. Chat confirmation remains the fallback when the page cannot be used. Either way, Step 4 ends with a `--shutdown` cleanup so a never-confirmed page cannot keep holding port 5050 ahead of the Step 6 live preview.## Scope