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
fix(ui-server): auto-advance to a free port instead of crashing on a busy default
hugohe39c3751e86b5a
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 6b7b381c..dcb78e9d 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -300,7 +300,7 @@ Read references/strategist.md```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait```- 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.+ 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). If another project already holds 5050, the launcher **auto-advances to the next free port** (5051, …) and serves this project there — read the actual URL from the launch log and report that. 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):@@ -454,7 +454,7 @@ Read references/visual-styles/<locked-style>.md # aesthetic (spec_lock.md `vis```bashpython3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live```-- Start it immediately when Executor begins; `svg_output/` may be empty. Editor opens at `http://localhost:5050`; port conflict → `--port <other>` and report the actual URL.+- Start it immediately when Executor begins; `svg_output/` may be empty. Editor opens at `http://localhost:5050`; if another project already holds it, the launcher **auto-advances to the next free port** — read the actual URL from the launch log and report that.- Run it as a long-running side process/session; do not wait for it to exit before generating SVG pages. Do not wait for user confirmation after startup.- **Service must keep running** until one of: (a) the user clicks **Exit preview** in the browser, or (b) the user explicitly asks in chat to stop it. Generation continues even if the user closes the editor.- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/live-preview.md`](workflows/live-preview.md).diff --git a/skills/ppt-master/scripts/confirm_ui/server.py b/skills/ppt-master/scripts/confirm_ui/server.pyindex 27dbd654..5b5e4f1e 100644--- a/skills/ppt-master/scripts/confirm_ui/server.py+++ b/skills/ppt-master/scripts/confirm_ui/server.py@@ -52,6 +52,7 @@ if str(_SCRIPTS_DIR) not in sys.path:from server_common import ( # noqa: E402claim_lock as _claim_lock,+ find_free_port as _find_free_port,process_alive as _process_alive,read_lock as _read_lock,release_lock as _release_lock,@@ -387,12 +388,15 @@ def main(argv: Optional[list[str]] = None) -> int:log_path = confirm_dir / 'server.log'result_file = confirm_dir / RESULT_NAMEstarted_at = time.time()+ # Pick a free port up front (another project may hold the default) and+ # pass the concrete port to the child so the reported URL is accurate.+ port = _find_free_port(args.port)cmd = [sys.executable,str(Path(__file__).resolve()),str(project_path),'--port',- str(args.port),+ str(port),'--timeout',str(args.timeout),]@@ -413,7 +417,7 @@ def main(argv: Optional[list[str]] = None) -> int:creationflags=creationflags,**popen_kwargs,)- url = f'http://localhost:{args.port}'+ url = f'http://localhost:{port}'logger.info('started confirm UI in background: %s (pid=%s)', url, proc.pid)logger.info('log: %s', log_path)if args.wait:diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex e722261c..3df8d525 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -13,7 +13,7 @@ python3 scripts/confirm_ui/server.py <project_path> --timeout 0 # disable idlepython3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 cleanup (idempotent)```-- Binds `127.0.0.1:5050` by default and auto-opens the browser (suppress with `--no-browser`).+- Binds `127.0.0.1:5050` by default — or the next free port if another project already holds it (the launch log prints the actual URL) — and auto-opens the browser (suppress with `--no-browser`). `--port <other>` forces a specific port.- **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).- `--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.diff --git a/skills/ppt-master/scripts/server_common.py b/skills/ppt-master/scripts/server_common.pyindex 237642b1..6a6235ae 100644--- a/skills/ppt-master/scripts/server_common.py+++ b/skills/ppt-master/scripts/server_common.py@@ -9,7 +9,7 @@ cross-platform process-liveness check and the claim/read/release lock logic sothe two servers cannot drift apart.Usage:- from server_common import process_alive, read_lock, claim_lock, release_lock+ from server_common import process_alive, read_lock, claim_lock, release_lock, find_free_portDependencies:None (only uses standard library)@@ -17,10 +17,29 @@ Dependencies:import jsonimport os+import socketfrom pathlib import Pathfrom typing import Optional+def find_free_port(preferred: int, host: str = '127.0.0.1', span: int = 50) -> int:+ """Return ``preferred`` if it is bindable, else the next free port within+ ``span``. Lets a new project's UI server coexist with another project's+ server already holding the default port, instead of crashing on bind — each+ project ends up on its own port serving its own data. Falls back to+ ``preferred`` if the whole span is taken (let the caller's bind surface it).+ """+ for port in range(preferred, preferred + span):+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:+ probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)+ try:+ probe.bind((host, port))+ return port+ except OSError:+ continue+ return preferred++def process_alive(pid: int) -> bool:"""Return True if a process with this pid is reachable.diff --git a/skills/ppt-master/scripts/svg_editor/server.py b/skills/ppt-master/scripts/svg_editor/server.pyindex 646faa25..a83d026a 100644--- a/skills/ppt-master/scripts/svg_editor/server.py+++ b/skills/ppt-master/scripts/svg_editor/server.py@@ -57,6 +57,7 @@ if str(_ROOT_SCRIPTS_DIR) not in sys.path:from server_common import ( # noqa: E402claim_lock as _claim_lock,+ find_free_port as _find_free_port,process_alive as _process_alive,read_lock as _read_lock,release_lock as _release_lock,@@ -856,12 +857,17 @@ def main(argv: Optional[list[str]] = None) -> int:logger.error('%s is not a directory', svg_output)return 1+ # Pick a free port: another project's preview/confirm server may already+ # hold the default, so bind the next free one instead of crashing — each+ # project then serves its own data on its own port (no cross-project mix-up).+ port = _find_free_port(args.port)+# Per-project mutual exclusion. The major driver of orphaned servers is# --live mode (which used to disable idle timeout entirely) combined with# silent restarts; refusing duplicate launches catches the accumulation# at its source. Stale locks (dead pid) are overwritten by _claim_lock.lock_file = project_path / LOCK_FILE_NAME- existing = _claim_lock(lock_file, args.port)+ existing = _claim_lock(lock_file, port)if existing:existing_pid = existing.get('pid', '?')existing_port = existing.get('port', '?')@@ -903,7 +909,7 @@ def main(argv: Optional[list[str]] = None) -> int:lock_file=lock_file,)- url = f'http://localhost:{args.port}'+ url = f'http://localhost:{port}'if not args.no_browser:webbrowser.open(url)@@ -913,7 +919,7 @@ def main(argv: Optional[list[str]] = None) -> int:logger.info('project: %s', project_path)logger.info('svg_output: %s (%d slides)', svg_output, svg_count)logger.info('idle timeout: %ds (0 = disabled)', idle_timeout)- app.run(host='127.0.0.1', port=args.port, debug=False)+ app.run(host='127.0.0.1', port=port, debug=False)return 0diff --git a/skills/ppt-master/workflows/live-preview.md b/skills/ppt-master/workflows/live-preview.mdindex a61205ed..3182c46e 100644--- a/skills/ppt-master/workflows/live-preview.md+++ b/skills/ppt-master/workflows/live-preview.md@@ -41,7 +41,7 @@ The server binds `127.0.0.1:5050`, opens the browser on a local desktop, and edi- **Annotate** (changes that need AI judgement / re-layout): select an element → write the instruction → click **Add annotation** to stage it → click **Apply changes** to write annotation markers → return to the chat and say `apply my annotations` (or quote the browser prompt)- to skip the editor, just describe the change in chat-Do not wait for confirmation before launching — the user already asked for preview, so launching is the response. Port conflicts → `--port <other>` and report the new URL. Remote access → see the appendix.+Do not wait for confirmation before launching — the user already asked for preview, so launching is the response. If another project already holds the port, the launcher auto-advances to the next free one — report the actual URL from the launch log (`--port <other>` still forces a specific port). Remote access → see the appendix.---@@ -82,7 +82,7 @@ Triggered by the user signals listed in "When to Run".- **Unsaved-work guard**: staged direct edits and annotation changes (added or removed) live in server memory until **Apply changes**; closing the tab triggers the browser's native "leave site?" prompt while any are unapplied, since an idle timeout or process kill would drop them.- **Re-export is chat-driven**: applying changes updates `svg_output/` only. Refreshing the PPTX (finalize + svg_to_pptx) stays a chat step — the editor never runs the export pipeline.- **Stop conditions**: the service stops when the user clicks **Exit preview** in the browser, asks in chat to stop it, the idle timeout fires, or the process is killed externally.-- **Port**: default `5050`; override with `--port <other>`.+- **Port**: default `5050`, auto-advancing to the next free port when another project already holds it (report the actual URL from the launch log); force a specific port with `--port <other>`.- **Idle timeout**: plain mode `900s`, `--live` mode `7200s`; override with `--timeout <seconds>` (`0` disables).- **Single instance per project**: `<project_path>/.live_preview.lock` records the running pid + port. A second launch against the same project refuses to start and prints the existing URL; stale locks (dead pid) are overwritten on the next launch. Delete the file by hand only if the process is gone but the lock remains (rare — `kill -9` is the only common cause).- **Transient ids**: each element gets a temporary `_edit_N` id while the editor is running. On save, only annotated elements keep their id; unannotated `_edit_N` ids are stripped before write-back.