Packaged CLI Script Runtime

Initial Debt

Issue 45 reported that global @punks/cli@2.2.1 failed during dp update and dp update --check --json while executing a temporary .agents/scripts/sync-subagents.mjs file. The command showed only the parent child_process.execFileSync failure and did not reach a usable update summary.

Why It Matters

dp update --check --json is the scaffold inspection path agents use before trusting generated agents, skills, hooks, and root guidance. If the packaged executable cannot run generated scaffold scripts, the update flow blocks before operators can inspect drift or follow the generated handoff.

Resolution

Generated scaffold scripts now run through a shared JavaScript runtime helper. The helper defaults to node, with DP_SCRIPT_RUNTIME as an override, so temporary scaffold scripts execute through a real script runtime instead of re-entering the packaged CLI entrypoint through process.execPath or Bun.execPath.

The same helper is used for:

• generated .agents/scripts/sync-subagents.mjs during scaffold output generation
• staged wiki scripts/sync-content.mjs during update alignment

Validation

• bun run --cwd apps/cli test src/update/run.test.ts --testNamePattern "host runtime"
• bun run --cwd apps/cli check-types
• bun run --cwd apps/cli check
• bun run --cwd apps/cli test src/update/run.test.ts
• bun run apps/cli/src/index.ts update --check --baseline bundled --json
• bun run --cwd apps/cli build
• git diff --check

The earlier skills/frameworks/react/react-doctor baseline asset mismatch is cleared: source update checks now reach normal managed scaffold drift, and bun run --cwd apps/cli test src/update/run.test.ts src/scaffold/run.test.ts passes. The built executable update check still fails in generated sync-subagents.mjs, so packaged executable validation remains separate from the React Doctor asset reconciliation.

Closeout

Resolved for issue 45 by adding a host-runtime regression test, routing scaffold script execution through the shared helper, and documenting the packaged CLI runtime contract. The backlog mirror was commented with validation evidence and left open until merge/release plus separate baseline asset reconciliation.