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.
• Renderer runtime request queueing implemented (concurrent calls are serialized in manager).
• 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') via a queued worker runtime by default.
• Project preference pythonRuntimeMode added with Settings → Technology section.

Confirmed Deviations from Original Plan

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

1. Transform runtime is now configurable (project-level)

   • Default: webworker (worker-thread based Python runtime with queued requests).
   • Optional fallback: main-thread legacy execution mode.

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) Python runtime boundary (P0) — Implemented

• Worker model introduced for Blogmark transform execution with queued communication.
• Runtime mode made project-configurable via Settings → Technology (pythonRuntimeMode).
• Legacy main-thread mode retained as explicit fallback option.

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.