diff --git a/docs/plans/2026-04-28-desktop-plugin-dependency-boundary-design.md b/docs/plans/2026-04-28-desktop-plugin-dependency-boundary-design.md new file mode 100644 index 00000000..b4f54a93 --- /dev/null +++ b/docs/plans/2026-04-28-desktop-plugin-dependency-boundary-design.md @@ -0,0 +1,77 @@ +# Desktop Plugin Dependency Boundary Design + +## Context + +Packaged desktop builds run AstrBot inside a bundled CPython runtime. Runtime plugin +dependencies are installed into `ASTRBOT_ROOT/data/site-packages` and are then +prepended to `sys.path` by AstrBot's pip installer. + +This allows plugin-only dependencies to work, but it also allows plugin installs to +shadow packages already used by the bundled backend runtime. Packages such as +`openai`, `pydantic`, `fastapi`, `numpy`, and PyObjC modules are unsafe to hot-reload +inside a running backend process. Installing Cua exposed this failure mode: pip +installed a second dependency set into plugin `site-packages`; the installer tried to +prefer those modules in-process, and the running OpenAI client later saw incompatible +class identities. + +## Goals + +- Keep packaged desktop plugin installs from replacing bundled core runtime modules. +- Preserve normal plugin dependency installation when dependencies are not core + runtime packages. +- Make the desktop bundle self-describing enough that runtime code can distinguish + bundled core dependencies from plugin dependencies. +- Favor explicit incompatibility or restart-required behavior over in-process module + replacement. + +## Non-Goals + +- Full per-plugin virtual environment isolation. +- Rewriting AstrBot's plugin manager. +- Guaranteeing that every PyPI package can coexist in the backend process. + +## Design + +The desktop backend build writes a `runtime-core-lock.json` file into +`resources/backend/app`. The lock captures distributions installed in the bundled +runtime, their versions, and top-level import modules. The launcher exposes this file +to the backend through `ASTRBOT_DESKTOP_CORE_LOCK_PATH`. + +When running in packaged desktop mode, AstrBot's pip installer reads the lock and uses +it for two protections: + +1. Add constraints for locked distributions so plugin pip installs cannot upgrade or + downgrade bundled runtime packages. +2. Avoid preferring locked top-level modules from `data/site-packages` after install. + +If pip cannot satisfy a plugin because it truly requires a different core dependency +version, installation fails with the existing dependency conflict path. This is +intentional: a clear install-time incompatibility is safer than corrupting the live +backend process. + +## Data Flow + +1. `scripts/backend/build-backend.mjs` installs backend requirements into the copied + runtime. +2. The build script runs a small Python helper against that runtime to enumerate + installed distributions. +3. The helper writes `app/runtime-core-lock.json`. +4. `launch_backend.py` sets `ASTRBOT_DESKTOP_CORE_LOCK_PATH` before running + `main.py`. +5. The packaged backend pip installer reads the lock while installing plugin + requirements and while attempting dependency preference. + +## Error Handling + +- If the lock cannot be generated during resource preparation, the backend build + fails. A packaged desktop runtime without this boundary is not considered safe. +- If the lock cannot be read at runtime, AstrBot falls back to existing behavior and + logs a warning. This keeps old custom launch setups from breaking. +- If a plugin conflicts with locked core dependencies, the install fails with a + dependency conflict message. + +## Testing + +- Script tests cover lock generation and launcher environment wiring. +- AstrBot pip installer tests cover adding lock constraints and skipping locked + modules during post-install preference. diff --git a/docs/plans/2026-04-28-desktop-plugin-dependency-boundary.md b/docs/plans/2026-04-28-desktop-plugin-dependency-boundary.md new file mode 100644 index 00000000..00d8a7c1 --- /dev/null +++ b/docs/plans/2026-04-28-desktop-plugin-dependency-boundary.md @@ -0,0 +1,132 @@ +# Desktop Plugin Dependency Boundary Implementation Plan + +**Goal:** Prevent packaged desktop plugin installs from replacing bundled backend runtime dependencies. + +**Architecture:** Generate a runtime core dependency lock during desktop backend packaging, expose it through an environment variable at launch, and teach AstrBot's packaged pip installer to constrain and skip locked core modules. This keeps plugin-only dependencies installable while preventing unsafe in-process replacement of backend dependencies. + +**Tech Stack:** Node.js resource preparation scripts, Python launcher/runtime code, AstrBot pip installer tests with pytest, Node `node:test`. + +--- + +### Task 1: Generate the Desktop Runtime Core Lock + +**Files:** +- Modify: `scripts/backend/build-backend.mjs` +- Create: `scripts/backend/templates/generate_runtime_core_lock.py` +- Test: `scripts/backend/runtime-core-lock.test.mjs` + +**Step 1: Write the failing test** + +Add a Node test that creates a fake runtime Python command, runs the lock generator entry point, and expects `runtime-core-lock.json` to be written under the backend app directory. + +**Step 2: Run test to verify it fails** + +Run: `node --test scripts/backend/runtime-core-lock.test.mjs` +Expected: FAIL because the helper/export does not exist yet. + +**Step 3: Write minimal implementation** + +Add a Python helper that uses `importlib.metadata.distributions()` to collect: +- distribution name +- distribution version +- `top_level.txt` modules when present + +Call it from `build-backend.mjs` after runtime dependency installation and before the manifest is written. + +**Step 4: Run test to verify it passes** + +Run: `node --test scripts/backend/runtime-core-lock.test.mjs` +Expected: PASS. + +### Task 2: Expose the Lock to the Packaged Backend + +**Files:** +- Modify: `scripts/backend/templates/launch_backend.py` +- Test: `scripts/prepare-resources/backend-runtime.test.mjs` or a focused launcher template test + +**Step 1: Write the failing test** + +Add a test that verifies the launcher template contains `ASTRBOT_DESKTOP_CORE_LOCK_PATH` and points it at `APP_DIR / "runtime-core-lock.json"` only when the file exists. + +**Step 2: Run test to verify it fails** + +Run: `pnpm run test:prepare-resources` +Expected: FAIL because the launcher does not set the env var yet. + +**Step 3: Write minimal implementation** + +Set `os.environ["ASTRBOT_DESKTOP_CORE_LOCK_PATH"]` in `launch_backend.py` before `runpy.run_path()` when the lock file exists. + +**Step 4: Run test to verify it passes** + +Run: `pnpm run test:prepare-resources` +Expected: PASS. + +### Task 3: Apply Lock Constraints in the Pip Installer + +**Files:** +- Modify: `vendor/AstrBot/astrbot/core/utils/core_constraints.py` +- Modify: `vendor/AstrBot/astrbot/core/utils/pip_installer.py` +- Test: `vendor/AstrBot/tests/test_pip_installer.py` + +**Step 1: Write the failing test** + +Add a test that sets `ASTRBOT_DESKTOP_CORE_LOCK_PATH` to a JSON lock containing `openai==2.32.0`, then verifies `PipInstaller.install(package_name="Cua")` adds `-c ` and the constraints include `openai==2.32.0`. + +**Step 2: Run test to verify it fails** + +Run: `cd vendor/AstrBot && uv run pytest tests/test_pip_installer.py:: -q` +Expected: FAIL because the lock is ignored. + +**Step 3: Write minimal implementation** + +Teach `CoreConstraintsProvider` to merge existing core metadata constraints with locked desktop runtime constraints in packaged mode. + +**Step 4: Run test to verify it passes** + +Run: `cd vendor/AstrBot && uv run pytest tests/test_pip_installer.py:: -q` +Expected: PASS. + +### Task 4: Skip Locked Modules During Post-Install Preference + +**Files:** +- Modify: `vendor/AstrBot/astrbot/core/utils/pip_installer.py` +- Test: `vendor/AstrBot/tests/test_pip_installer.py` + +**Step 1: Write the failing test** + +Add a test where candidate modules include `openai` and `cua_agent`, the lock marks `openai` as a core module, and `_ensure_plugin_dependencies_preferred` calls `_ensure_preferred_modules` only with `cua_agent`. + +**Step 2: Run test to verify it fails** + +Run: `cd vendor/AstrBot && uv run pytest tests/test_pip_installer.py:: -q` +Expected: FAIL because locked modules are still preferred. + +**Step 3: Write minimal implementation** + +Filter candidate modules using the lock's top-level module set before attempting `_prefer_module_from_site_packages`. + +**Step 4: Run test to verify it passes** + +Run: `cd vendor/AstrBot && uv run pytest tests/test_pip_installer.py:: -q` +Expected: PASS. + +### Task 5: Full Verification and PR + +**Files:** +- All touched files + +**Step 1: Run focused tests** + +Run: +- `pnpm run test:prepare-resources` +- `cd vendor/AstrBot && uv run pytest tests/test_pip_installer.py -q` + +**Step 2: Run repository tests if feasible** + +Run: +- `make test` + +**Step 3: Commit and open PR** + +Commit only intentional files, push `codex/desktop-plugin-dependency-lock`, and create a draft PR against `AstrBotDevs/AstrBot-desktop:main`. diff --git a/scripts/backend/build-backend.mjs b/scripts/backend/build-backend.mjs index d7776c29..6e5e9c45 100644 --- a/scripts/backend/build-backend.mjs +++ b/scripts/backend/build-backend.mjs @@ -19,6 +19,7 @@ import { pruneLinuxTkinterRuntime, } from './runtime-linux-compat-utils.mjs'; import { isWindowsArm64BundledRuntime } from './runtime-arch-utils.mjs'; +import { generateRuntimeCoreLock } from './runtime-core-lock.mjs'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const projectRoot = path.resolve(__dirname, '..', '..'); @@ -29,6 +30,7 @@ const outputDir = path.join(projectRoot, 'resources', 'backend'); const appDir = path.join(outputDir, 'app'); const runtimeDir = path.join(outputDir, 'python'); const manifestPath = path.join(outputDir, 'runtime-manifest.json'); +const runtimeCoreLockPath = path.join(appDir, 'runtime-core-lock.json'); const launcherPath = path.join(outputDir, 'launch_backend.py'); const launcherTemplatePath = path.join(__dirname, 'templates', 'launch_backend.py'); const importScannerScriptPath = path.join(__dirname, 'tools', 'scan_imports.py'); @@ -613,6 +615,10 @@ const main = () => { copyAppSources(resolvedSourceDir); const runtimePython = prepareRuntimeExecutable(runtimeSourceReal); installRuntimeDependencies(runtimePython); + generateRuntimeCoreLock({ + runtimePython, + outputPath: runtimeCoreLockPath, + }); pruneLinuxTkinterRuntime(runtimeDir); patchLinuxRuntimeRpaths(runtimeDir); writeLauncherScript(); diff --git a/scripts/backend/runtime-core-lock.mjs b/scripts/backend/runtime-core-lock.mjs new file mode 100644 index 00000000..c7ac4d34 --- /dev/null +++ b/scripts/backend/runtime-core-lock.mjs @@ -0,0 +1,68 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const generatorScriptPath = path.join(__dirname, 'tools', 'generate_runtime_core_lock.py'); +const formatGeneratorContext = (pythonPath) => + `(python: ${pythonPath ?? 'undefined'}, script: ${generatorScriptPath})`; + +export const generateRuntimeCoreLock = ({ runtimePython, outputPath }) => { + if (!runtimePython?.absolute) { + throw new Error( + `Missing runtime Python executable for runtime core lock generation ${formatGeneratorContext(runtimePython?.absolute)}.`, + ); + } + if (!outputPath) { + throw new Error( + `Missing output path for runtime core lock generation ${formatGeneratorContext(runtimePython.absolute)}.`, + ); + } + + const result = spawnSync( + runtimePython.absolute, + [generatorScriptPath, '--output', outputPath], + { + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + windowsHide: true, + }, + ); + + if (result.error) { + throw new Error( + `Failed to generate runtime core lock ${formatGeneratorContext(runtimePython.absolute)}: ${result.error.message}`, + ); + } + if (result.status !== 0) { + let detail; + if (result.signal) { + detail = `terminated by signal ${result.signal}`; + } else { + detail = result.stderr?.trim() || result.stdout?.trim() || `exit code ${result.status}`; + } + throw new Error( + `Runtime core lock generation failed ${formatGeneratorContext(runtimePython.absolute)}: ${detail}`, + ); + } + + { + const context = formatGeneratorContext(runtimePython.absolute); + const baseMessage = `Runtime core lock generator did not create valid ${outputPath} ${context}.`; + + if (!fs.existsSync(outputPath)) { + throw new Error(baseMessage); + } + + try { + const contents = fs.readFileSync(outputPath, 'utf8'); + if (!contents.trim()) { + throw new Error('empty runtime core lock output'); + } + JSON.parse(contents); + } catch { + throw new Error(baseMessage); + } + } +}; diff --git a/scripts/backend/runtime-core-lock.test.mjs b/scripts/backend/runtime-core-lock.test.mjs new file mode 100644 index 00000000..69a19ab5 --- /dev/null +++ b/scripts/backend/runtime-core-lock.test.mjs @@ -0,0 +1,337 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { readFile } from 'node:fs/promises'; +import { test } from 'node:test'; +import { fileURLToPath } from 'node:url'; + +import { generateRuntimeCoreLock } from './runtime-core-lock.mjs'; + +const resolvePython = () => process.env.PYTHON || (process.platform === 'win32' ? 'python' : 'python3'); +const launcherTemplatePath = fileURLToPath(new URL('./templates/launch_backend.py', import.meta.url)); +const generatorScriptPath = fileURLToPath(new URL('./tools/generate_runtime_core_lock.py', import.meta.url)); + +const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`; + +const createFakeRuntime = (fixtureRoot, jsSource) => { + const driverPath = path.join(fixtureRoot, 'fake-runtime.js'); + fs.writeFileSync(driverPath, jsSource, 'utf8'); + + if (process.platform === 'win32') { + const wrapperPath = path.join(fixtureRoot, 'fake-runtime.cmd'); + fs.writeFileSync(wrapperPath, `@echo off\r\n"${process.execPath}" "${driverPath}" %*\r\n`, 'utf8'); + return wrapperPath; + } + + const wrapperPath = path.join(fixtureRoot, 'fake-runtime'); + fs.writeFileSync( + wrapperPath, + `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(driverPath)} "$@"\n`, + 'utf8', + ); + fs.chmodSync(wrapperPath, 0o755); + return wrapperPath; +}; + +test('generateRuntimeCoreLock writes installed distribution metadata', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-')); + const outputPath = path.join(fixtureRoot, 'runtime-core-lock.json'); + + try { + generateRuntimeCoreLock({ + runtimePython: { absolute: resolvePython() }, + outputPath, + }); + + const lock = JSON.parse(fs.readFileSync(outputPath, 'utf8')); + + assert.equal(lock.version, 1); + assert.equal(Array.isArray(lock.distributions), true); + assert.ok(lock.distributions.length > 0); + assert.ok(lock.distributions.some((dist) => dist.name && dist.version)); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('backend build invokes runtime core lock generation before manifest output', async () => { + const buildBackendPath = new URL('./build-backend.mjs', import.meta.url); + const source = await readFile(buildBackendPath, 'utf8'); + + assert.match(source, /generateRuntimeCoreLock/); + assert.match(source, /runtime-core-lock\.json/); + assert.match(source, /generateRuntimeCoreLock\(\{\s*runtimePython/s); +}); + +test('backend launcher sets the runtime core lock path when the lock exists', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-launch-backend-')); + const appDir = path.join(fixtureRoot, 'app'); + const lockPath = path.join(appDir, 'runtime-core-lock.json'); + fs.mkdirSync(appDir, { recursive: true }); + fs.writeFileSync(lockPath, '{}'); + + const script = String.raw` +import importlib.util +import os +import sys +from pathlib import Path + +spec = importlib.util.spec_from_file_location("launch_backend", sys.argv[1]) +module = importlib.util.module_from_spec(spec) +assert spec.loader is not None +spec.loader.exec_module(module) + +module.APP_DIR = Path(sys.argv[2]) +os.environ.pop(module.RUNTIME_CORE_LOCK_ENV, None) +module.configure_runtime_core_lock_path() +print(os.environ.get(module.RUNTIME_CORE_LOCK_ENV, "")) +`; + + try { + const result = spawnSync(resolvePython(), ['-c', script, launcherTemplatePath, appDir], { + encoding: 'utf8', + }); + assert.equal(result.status, 0, result.stderr || result.stdout); + assert.equal(result.stdout.trim(), lockPath); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('backend launcher preserves an explicit runtime core lock override', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-launch-backend-override-')); + const appDir = path.join(fixtureRoot, 'app'); + const lockPath = path.join(appDir, 'runtime-core-lock.json'); + const overridePath = path.join(fixtureRoot, 'override-lock.json'); + fs.mkdirSync(appDir, { recursive: true }); + fs.writeFileSync(lockPath, '{}'); + + const script = String.raw` +import importlib.util +import os +import sys +from pathlib import Path + +spec = importlib.util.spec_from_file_location("launch_backend", sys.argv[1]) +module = importlib.util.module_from_spec(spec) +assert spec.loader is not None +spec.loader.exec_module(module) + +module.APP_DIR = Path(sys.argv[2]) +os.environ[module.RUNTIME_CORE_LOCK_ENV] = sys.argv[3] +module.configure_runtime_core_lock_path() +print(os.environ.get(module.RUNTIME_CORE_LOCK_ENV, "")) +`; + + try { + const result = spawnSync( + resolvePython(), + ['-c', script, launcherTemplatePath, appDir, overridePath], + { encoding: 'utf8' }, + ); + assert.equal(result.status, 0, result.stderr || result.stdout); + assert.equal(result.stdout.trim(), overridePath); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('generateRuntimeCoreLock creates the output file when parent directories are missing', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-nested-')); + const outputPath = path.join(fixtureRoot, 'nested', 'path', 'runtime-core-lock.json'); + + try { + generateRuntimeCoreLock({ + runtimePython: { absolute: resolvePython() }, + outputPath, + }); + + assert.equal(fs.existsSync(outputPath), true); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('generateRuntimeCoreLock reports generator context for missing runtime python', () => { + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: {}, + outputPath: '/tmp/runtime-core-lock.json', + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /Missing runtime Python executable/); + assert.match(error.message, /python: undefined/); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); +}); + +test('generateRuntimeCoreLock reports generator context for missing output path', () => { + const pythonPath = resolvePython(); + + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: { absolute: pythonPath }, + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /Missing output path/); + assert.match(error.message, new RegExp(`python: ${escapeRegExp(pythonPath)}`)); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); +}); + +test('generateRuntimeCoreLock reports generator context for process launch failures', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-launch-error-')); + const missingPythonPath = path.join(fixtureRoot, 'missing-python'); + + try { + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: { absolute: missingPythonPath }, + outputPath: path.join(fixtureRoot, 'runtime-core-lock.json'), + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /Failed to generate runtime core lock/); + assert.match(error.message, new RegExp(`python: ${escapeRegExp(missingPythonPath)}`)); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('generateRuntimeCoreLock reports generator context for non-zero exits', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-exit-error-')); + + try { + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: { absolute: process.execPath }, + outputPath: path.join(fixtureRoot, 'runtime-core-lock.json'), + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /Runtime core lock generation failed/); + assert.match(error.message, new RegExp(`python: ${escapeRegExp(process.execPath)}`)); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('generateRuntimeCoreLock reports signal-based termination clearly', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-signal-error-')); + const fakeRuntimePath = createFakeRuntime( + fixtureRoot, + `process.kill(process.pid, ${JSON.stringify(process.platform === 'win32' ? 'SIGTERM' : 'SIGTERM')});\n`, + ); + + try { + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: { absolute: fakeRuntimePath }, + outputPath: path.join(fixtureRoot, 'runtime-core-lock.json'), + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /Runtime core lock generation failed/); + assert.match(error.message, /terminated by signal SIGTERM/); + assert.doesNotMatch(error.message, /exit code null/); + assert.match(error.message, new RegExp(`python: ${escapeRegExp(fakeRuntimePath)}`)); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('generateRuntimeCoreLock rejects invalid generated lock content', () => { + const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'astrbot-runtime-core-lock-invalid-output-')); + const fakeRuntimePath = createFakeRuntime( + fixtureRoot, + ` +const fs = require('node:fs'); +const outputPath = process.argv[4]; +fs.mkdirSync(require('node:path').dirname(outputPath), { recursive: true }); +fs.writeFileSync(outputPath, 'not json', 'utf8'); +`, + ); + + try { + assert.throws( + () => + generateRuntimeCoreLock({ + runtimePython: { absolute: fakeRuntimePath }, + outputPath: path.join(fixtureRoot, 'runtime-core-lock.json'), + }), + (error) => { + assert.equal(error instanceof Error, true); + assert.match(error.message, /did not create valid/); + assert.match(error.message, new RegExp(escapeRegExp(path.join(fixtureRoot, 'runtime-core-lock.json')))); + assert.match(error.message, new RegExp(`python: ${escapeRegExp(fakeRuntimePath)}`)); + assert.match(error.message, new RegExp(`script: ${escapeRegExp(generatorScriptPath)}`)); + return true; + }, + ); + } finally { + fs.rmSync(fixtureRoot, { recursive: true, force: true }); + } +}); + +test('runtime core lock helper only suppresses missing top-level metadata', () => { + const script = String.raw` +import importlib.util +import sys + +spec = importlib.util.spec_from_file_location("runtime_core_lock_helper", sys.argv[1]) +module = importlib.util.module_from_spec(spec) +assert spec.loader is not None +spec.loader.exec_module(module) + +class MissingTopLevel: + def read_text(self, name): + raise FileNotFoundError + +class BrokenEncoding: + def read_text(self, name): + raise UnicodeDecodeError("utf-8", b"\x80", 0, 1, "invalid start byte") + +class UnexpectedFailure: + def read_text(self, name): + raise RuntimeError("boom") + +assert module._read_top_level_modules(MissingTopLevel()) == [] +assert module._read_top_level_modules(BrokenEncoding()) == [] + +try: + module._read_top_level_modules(UnexpectedFailure()) +except RuntimeError as exc: + assert str(exc) == "boom" +else: + raise AssertionError("RuntimeError was suppressed") +`; + + const result = spawnSync(resolvePython(), ['-c', script, generatorScriptPath], { encoding: 'utf8' }); + assert.equal(result.status, 0, result.stderr || result.stdout); +}); diff --git a/scripts/backend/templates/launch_backend.py b/scripts/backend/templates/launch_backend.py index 72a48f23..d0be3095 100644 --- a/scripts/backend/templates/launch_backend.py +++ b/scripts/backend/templates/launch_backend.py @@ -15,6 +15,7 @@ _WINDOWS_DLL_DIRECTORY_HANDLES: list[object] = [] # Keep this in sync with BACKEND_STARTUP_HEARTBEAT_PATH_ENV in src-tauri/src/app_constants.rs. STARTUP_HEARTBEAT_ENV = "ASTRBOT_BACKEND_STARTUP_HEARTBEAT_PATH" +RUNTIME_CORE_LOCK_ENV = "ASTRBOT_DESKTOP_CORE_LOCK_PATH" STARTUP_HEARTBEAT_INTERVAL_SECONDS = 2.0 STARTUP_HEARTBEAT_STOP_JOIN_TIMEOUT_SECONDS = 1.0 @@ -220,11 +221,18 @@ def on_exit() -> None: atexit.register(on_exit) +def configure_runtime_core_lock_path() -> None: + lock_path = APP_DIR / "runtime-core-lock.json" + if lock_path.is_file(): + os.environ.setdefault(RUNTIME_CORE_LOCK_ENV, str(lock_path)) + + def main() -> None: configure_stdio_utf8() configure_windows_dll_search_path() preload_windows_runtime_dlls() start_startup_heartbeat() + configure_runtime_core_lock_path() sys.path.insert(0, str(APP_DIR)) diff --git a/scripts/backend/tools/generate_runtime_core_lock.py b/scripts/backend/tools/generate_runtime_core_lock.py new file mode 100644 index 00000000..cf42efa2 --- /dev/null +++ b/scripts/backend/tools/generate_runtime_core_lock.py @@ -0,0 +1,66 @@ +from __future__ import annotations + +import argparse +import importlib.metadata as importlib_metadata +import json +from pathlib import Path + + +def _read_top_level_modules(distribution: importlib_metadata.Distribution) -> list[str]: + try: + text = distribution.read_text("top_level.txt") or "" + except (FileNotFoundError, KeyError, UnicodeError): + return [] + + modules: set[str] = set() + for line in text.splitlines(): + candidate = line.strip() + if candidate and not candidate.startswith("#"): + modules.add(candidate) + return sorted(modules) + + +def _distribution_record( + distribution: importlib_metadata.Distribution, +) -> dict[str, object] | None: + name = distribution.metadata.get("Name") + version = distribution.version + if not name or not version: + return None + + return { + "name": name, + "version": version, + "top_level_modules": _read_top_level_modules(distribution), + } + + +def build_lock() -> dict[str, object]: + records = [ + record + for distribution in importlib_metadata.distributions() + if (record := _distribution_record(distribution)) is not None + ] + records.sort(key=lambda record: str(record["name"]).lower()) + return { + "version": 1, + "distributions": records, + } + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--output", required=True) + args = parser.parse_args() + + output_path = Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + output_path.write_text( + json.dumps(build_lock(), ensure_ascii=False, indent=2, sort_keys=True) + "\n", + encoding="utf-8", + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())