bDS/PYTHON_SCRIPTING.md

Python Scripting — Remaining Work (Implementation-First)

Last verified: 23 Feb 2026

This document is intentionally reduced to what is still left to implement. When plan and code differ, code is the source of truth.

Implemented (checked)

• Pyodide dependency integrated.
• Renderer worker runtime exists (pythonRuntime.worker.ts) with ready/error/stdout/run protocol.
• Runtime timeout watchdog + reset/recovery implemented in PythonRuntimeManager.
• ABI v1 schemas and validation for macro context/result implemented (abiV1.ts).
• Benchmark harness implemented (npm run bench:python-runtime -- <iterations>).
• Script persistence model implemented (scripts DB table + scripts/*.py files).
• Script metadata model implemented (kind, entrypoint, enabled, version, etc.).
• Main process script CRUD engine + IPC handlers implemented.
• Preload + shared API typings for scripts implemented.
• Renderer scripts UX implemented (sidebar list, editor, save, run, delete).
• Script syntax check + entrypoint discovery integrated in editor UX.
• Blogmark transform pipeline executes Python transform scripts (kind='transform').

Confirmed Deviations from Original Plan

These are current realities and should be treated as authoritative unless we explicitly decide to change them.

1. Transform script runtime location differs

   • Original plan: untrusted Python runs in renderer worker only.
   • Actual implementation: Blogmark transform scripts run in main process Pyodide (BlogmarkTransformService).

2. Render-time macro migration has not happened yet

   • Original plan: all render-time macros become Python-backed.
   • Actual implementation: render-time macros are still JS-based (PageRenderer.renderMacro and renderer macro registry/definitions).

3. Macro ABI exists but is not the production render path

   • ABI v1 + runtime manager support exist.
   • Main page generation path still uses existing JS macro rendering.

4. Scripts rebuild/meta-diff sync is still missing

   • Script CRUD works via app APIs.
   • No implemented project-wide “rebuild from files” parity for scripts/ equivalent to posts/media rebuild flows.

Remaining Work Only

1) Decide and enforce Python runtime boundary (P0)

• Decide if transform scripts should stay in main process or move to renderer worker.
• If staying in main process: add explicit timeout/kill/recovery safeguards equivalent to worker watchdog behavior.
• If moving to worker: route transform execution through typed IPC/worker bridge and remove main-process execution path.
• Document final security model in this file after decision.

2) Add scripts file-system rebuild/sync (P1)

• Implement rebuild/meta-diff style synchronization for scripts/ so external file edits are detected.
• Define conflict handling policy between DB metadata and script file frontmatter/body.
• Add tests for create/edit/delete performed outside app while app is closed/open.

3) Wire Python macros into render pipeline (P1)

• Add macro-to-script resolution (token/hook -> script id/slug).
• Execute Python macro scripts from the active render path.
• Reuse runtime cache keys across repeated macro invocations in generation loops.
• Add guardrails for timeout/error fallback during render.

4) Macro parity migration + cleanup (P2)

• Port built-in macros to Python scripts with parity fixtures.
• Keep fixtures/golden tests for parity verification.
• Remove legacy JS macro path only after parity is proven.

5) Default script seeding/versioning (P2)

• Bundle default scripts in repo/app resources.
• Seed missing defaults on project init/startup deterministically.
• Add versioned update strategy for default scripts.

6) Diagnostics and performance visibility (P3)

• Add macro execution counters (count, timeout/error counts, p50/p95) for real render path.
• Define regression thresholds based on benchmark trends.

Out of Scope Until Core Gaps Close

• AI assistant tooling exposure from Python scripts.
• General Python package/dependency policy expansion.
• Advanced bridge optimizations (only if metrics prove need).

Acceptance Gate Before Marking Python Scripting “Complete”

• Render-time macros run through Python script path in production generation flow.
• Scripts directory external changes are synchronized reliably.
• Runtime boundary decision implemented and protected by tests.
• Legacy JS macro path removed (or explicitly retained with documented rationale).
• npm test and npm run build pass.