prizmkit 1.1.108 → 1.1.109

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md

@@ -10,9 +10,9 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 
 **Step 0 — Playwright CLI Readiness Check (BLOCKING — must pass before any browser action)**:
 
-0a. Check if `playwright-cli` is installed:
+0a. Check if `playwright-cli` is installed using the runtime helper:
 ```bash
-which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
 ```
 If output is `NOT_INSTALLED`, install it:
 ```bash
@@ -20,7 +20,7 @@ npm install -g @playwright/cli@latest
 ```
 Then verify installation succeeded:
 ```bash
-playwright-cli --version
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
 ```
 If installation fails, log the error in context-snapshot.md under `## Browser Verification: SKIPPED — playwright-cli installation failed` and proceed to the next phase. Do NOT attempt browser verification without playwright-cli.
 
@@ -32,43 +32,9 @@ Use this output to determine the correct commands for your verification steps. D
 
 0c. Check if playwright-cli skill is installed for the current AI platform:
 ```bash
-# Detect AI CLI platform
-CURRENT_PLATFORM=""
-if which claude >/dev/null 2>&1; then
-  CURRENT_PLATFORM="claude"
-  SKILL_DIR="$HOME/.claude/skills"
-elif which cbc >/dev/null 2>&1; then
-  CURRENT_PLATFORM="codebuddy"
-  SKILL_DIR="$HOME/.cbc/skills"
-else
-  # Try to detect from environment or config
-  CURRENT_PLATFORM="unknown"
-fi
-
-# Check if playwright-cli skill exists
-if [ -d "$SKILL_DIR/playwright-cli" ] || ls "$SKILL_DIR"/playwright* 2>/dev/null | grep -q .; then
-  echo "SKILL_EXISTS"
-else
-  echo "SKILL_MISSING"
-fi
-```
-If `SKILL_MISSING`:
-```bash
-# Install playwright-cli skills (defaults to claude platform)
-playwright-cli install --skills
-```
-If the current platform is NOT claude, move the installed skill files to the correct location:
-```bash
-# Skills are installed to claude's default location — move to current platform's skill dir
-if [ "$CURRENT_PLATFORM" != "claude" ] && [ "$CURRENT_PLATFORM" != "unknown" ]; then
-  CLAUDE_SKILL_DIR="$HOME/.claude/skills"
-  if [ -d "$CLAUDE_SKILL_DIR/playwright-cli" ]; then
-    mkdir -p "$SKILL_DIR"
-    cp -r "$CLAUDE_SKILL_DIR/playwright-cli" "$SKILL_DIR/"
-    echo "Moved playwright-cli skill from claude to $CURRENT_PLATFORM"
-  fi
-fi
+{{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
 ```
+If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to the path shown by the helper output for the current platform.
 
 0d. Read the installed playwright-cli skill for workflow guidance:
 After skill installation, read the skill's SKILL.md to understand recommended workflows and patterns. Use these patterns to construct your verification flow — do NOT invent your own patterns if the skill provides them.
@@ -78,31 +44,20 @@ After skill installation, read the skill's SKILL.md to understand recommended wo
 You know this project's tech stack. Detect and start the dev server yourself:
 
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
+2. Use the pre-detected port if available, otherwise determine the dev server port from project config. Do NOT hardcode or guess the port. Record it as `DEV_PORT` in your notes.
+3. Verify the port is available:
    ```bash
-   # Use pipeline-injected port if available, otherwise extract from package.json
-   DEV_PORT={{DEV_PORT}}
-   # If DEV_PORT is still a placeholder, detect at runtime:
-   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
-     if [ -z "$DEV_PORT" ]; then
-       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
-     fi
-     DEV_PORT=${DEV_PORT:-3000}
-   fi
-   echo "Detected DEV_PORT=$DEV_PORT"
+   {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
    ```
-3. Verify the port is available:
+4. Start the dev server with the runtime helper and capture a PID file:
    ```bash
-   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
    ```
-4. Start the dev server in background, capture PID:
+5. Wait for server to be ready:
    ```bash
-   <start-command> &
-   DEV_SERVER_PID=$!
+   {{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:{{DEV_PORT}} --timeout 30 --interval 2
    ```
-5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:{{DEV_PORT}}`
 7. If the page requires authentication, use playwright-cli to register a test user and log in first
 
 **Step 2 — Verification**:
@@ -122,15 +77,21 @@ Take a final screenshot for evidence: `playwright-cli screenshot`
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Close the playwright-cli browser: `playwright-cli close`
-2. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. Stop the dev server process using the PID file written in Step 1:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>
+   ```
+3. Verify port is released:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
+   ```
 
 **Step 4 — Reporting**:
 
 Append results to `context-snapshot.md`:
 ```
 ## Browser Verification
-URL: http://localhost:$DEV_PORT
+URL: http://localhost:<DEV_PORT>
 Dev Server Command: <actual command used>
 playwright-cli version: <version>
 Steps executed: [list of playwright-cli commands used]
@@ -142,4 +103,3 @@ Browser cleanup: confirmed
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
-

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-base.md

@@ -1,7 +1,7 @@
 ### Build Context Snapshot
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md
 ```
 
 If MISSING — build it now:

package/bundled/dev-pipeline/templates/sections/phase-critic-plan-full.md

@@ -2,7 +2,7 @@
 
 **Guard**: Verify critic agent file exists before spawning:
 ```bash
-ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists {{CRITIC_SUBAGENT_PATH}} --exists-marker CRITIC:READY --missing-marker CRITIC:MISSING
 ```
 If CRITIC:MISSING — skip this phase entirely and proceed. Log: "Critic agent not installed — skipping Plan Challenge."
 

package/bundled/dev-pipeline/templates/sections/phase-critic-plan.md

@@ -2,7 +2,7 @@
 
 **Guard**: Verify critic agent file exists before spawning:
 ```bash
-ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists {{CRITIC_SUBAGENT_PATH}} --exists-marker CRITIC:READY --missing-marker CRITIC:MISSING
 ```
 If CRITIC:MISSING — skip this phase entirely and proceed. Log: "Critic agent not installed — skipping Plan Challenge."
 

package/bundled/dev-pipeline/templates/sections/phase-plan-agent.md

@@ -1,7 +1,7 @@
 ### Plan & Tasks
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
 If missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:

package/bundled/dev-pipeline/templates/sections/phase-plan-lite.md

@@ -1,7 +1,7 @@
 ### Plan & Tasks
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`:

package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md

@@ -5,8 +5,8 @@
 Create a current-run marker immediately before invoking the skill:
 
 ```bash
-mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
-touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
+{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
 ```
 
 Run `/prizmkit-test` with the feature artifact directory:

package/bundled/dev-pipeline/templates/sections/phase-review-agent.md

@@ -9,7 +9,7 @@ The skill runs an internal review-fix loop (Reviewer Agent → filter → orches
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

package/bundled/dev-pipeline/templates/sections/phase-review-full.md

@@ -9,7 +9,7 @@ The skill runs an internal review-fix loop (Reviewer Agent → filter → orches
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -2,7 +2,7 @@
 
 Check existing artifacts first:
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 - Both (spec.md, plan.md) exist → **SKIP to CP-1**
@@ -12,11 +12,11 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
-2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+2. Detect source code directories from KEY_FILES and STRUCTURE sections in `root.prizm`; if root docs are unavailable, use the helper to list likely source files:
    ```bash
-   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   {{RUNTIME_HELPER_CMD}} artifact source-files . --json
    ```
-   Identify the top-level source directories from the results.
+   Identify the top-level source directories from the helper output.
 3. Scan the detected source directories for files related to this feature; read each one
 4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description (copy from Task Contract above, 2-3 lines only)
@@ -35,14 +35,15 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
-5. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
+5. Confirm: `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 **After Step A**: Use context-snapshot.md Section 4 File Manifest to guide targeted file reads. Do NOT scan directories or read unrelated files.
 
 **Step B — Planning Artifacts** (generate only missing files):
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
 - spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve uncertain requirements from the task description, existing code, and conservative existing-project patterns.

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -1,6 +1,6 @@
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
-- Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+- Run `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 
 

package/bundled/dev-pipeline/templates/sections/subagent-timeout-recovery.md

@@ -1,6 +1,6 @@
 ## Subagent Timeout Recovery
 
 If any agent times out:
-1. `ls .prizmkit/specs/{{FEATURE_SLUG}}/` — check what exists
+1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
 2. If `context-snapshot.md` exists: open recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and any Implementation Log/Review Notes from previous agents. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
 3. Max 2 retries per phase. After 2 failures, orchestrator completes the work directly and appends a Recovery Note to context-snapshot.md.

package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py

@@ -444,7 +444,8 @@ class TestScopedFeatureTestGate:
 
         rendered = "\n".join(content for _, content in sections)
         assert "prizmkit-test-gate.py" not in rendered
-        assert ".prizmkit-test-started" in rendered
+        assert "{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started" in rendered
+        assert "mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}" not in rendered
         assert "when present" not in rendered
         assert "Boundary Matrix" in rendered
         assert "Boundary Completion Gate" in rendered
@@ -474,7 +475,8 @@ class TestScopedFeatureTestGate:
         rendered = "\n".join(content for _, content in sections)
 
         assert "### Checkpoint Update Helper" in rendered
-        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" in rendered
+        assert "{{CHECKPOINT_PYTHON_CMD}}" in rendered
+        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" not in rendered
         assert "--checkpoint-path {{CHECKPOINT_PATH}}" in rendered
         assert "--step <step-id-or-skill-name>" in rendered
         assert "Do not hand-edit `workflow-checkpoint.json` directly." in rendered
@@ -1016,7 +1018,7 @@ def _write_feature_list(path, feature):
     path.write_text(json.dumps({"features": [feature], "global_context": {"language": "Python"}}), encoding="utf-8")
 
 
-def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=None, platform="claude"):
+def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=None, platform="claude", browser_interaction=None):
     project = tmp_path / "project"
     project.mkdir(parents=True)
     (project / ".prizmkit" / "plans").mkdir(parents=True)
@@ -1036,6 +1038,8 @@ def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=Non
         "acceptance_criteria": ["Prompts are clean"],
         "critic": critic,
     }
+    if browser_interaction is not None:
+        feature["browser_interaction"] = browser_interaction
     feature_list = project / ".prizmkit" / "plans" / "feature-list.json"
     _write_feature_list(feature_list, feature)
     output = project / "prompt.md"
@@ -1208,6 +1212,9 @@ class TestHeadlessPromptCleanupF033:
             if "Feature ID" in prompt:
                 assert "/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/123-prompt-cleanup/" in prompt
                 assert ".prizmkit-test-started" in prompt
+                assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+                assert "prizmkit-runtime-helper.py" in prompt
+            assert "python3 {{INIT_SCRIPT_PATH}}" not in prompt
 
     def test_legacy_feature_templates_are_clean_when_rendered(self, tmp_path):
         for template, mode in (("bootstrap-tier1.md", "lite"), ("bootstrap-tier2.md", "standard"), ("bootstrap-tier3.md", "full")):
@@ -1215,7 +1222,42 @@ class TestHeadlessPromptCleanupF033:
             for forbidden in HEADLESS_FORBIDDEN_PROMPT_STRINGS:
                 assert forbidden not in prompt
             assert "prizmkit-test-gate.py" not in prompt
+            assert "python3 {{INIT_SCRIPT_PATH}}" not in prompt
+            assert "which playwright-cli" not in prompt
+            assert "lsof -ti" not in prompt
+            assert "sed -nE" not in prompt
             assert ".prizmkit-test-started" in prompt
+            assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+            assert "prizmkit-runtime-helper.py" in prompt
+
+    def test_legacy_feature_templates_with_browser_blocks_are_shell_free(self, tmp_path):
+        forbidden = [
+            "python3 {{INIT_SCRIPT_PATH}}",
+            "which playwright-cli",
+            "which opencli",
+            "lsof -ti",
+            "sed -nE",
+            "SKILL_DIR",
+            "DEV_SERVER_PID",
+            "opencli doctor 2>/dev/null ||",
+            "echo \"=== playwright-cli ===\" &&",
+        ]
+        cases = [
+            ("bootstrap-tier1.md", "lite"),
+            ("bootstrap-tier2.md", "standard"),
+            ("bootstrap-tier3.md", "full"),
+        ]
+        for template, mode in cases:
+            prompt = _render_feature_prompt(
+                tmp_path / f"browser-{template}",
+                mode=mode,
+                critic=(mode != "lite"),
+                template=template,
+                browser_interaction={"tool": "auto", "verify_steps": ["Open the page"]},
+            )
+            assert "prizmkit-runtime-helper.py" in prompt
+            for snippet in forbidden:
+                assert snippet not in prompt
 
     def test_claude_config_wins_over_codex_directory_for_critic_path(self, tmp_path, monkeypatch):
         project = tmp_path / "mixed"

package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py

@@ -201,8 +201,9 @@ class TestExplicitProjectRoot:
         assert "{{" + REMOVED_MAX_LOG_ENV + "}}" not in replacements
         assert "{{" + REMOVED_MAX_LOG_HUMAN + "}}" not in replacements
         assert "### Checkpoint Update Helper" in replacements["{{CHECKPOINT_SYSTEM}}"]
-        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "{{CHECKPOINT_PYTHON_CMD}}" in replacements["{{CHECKPOINT_SYSTEM}}"]
         assert "pipeline progress mechanism" not in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "prizmkit-runtime-helper.py" in replacements["{{RUNTIME_HELPER_CMD}}"]
 
 
 # ---------------------------------------------------------------------------

package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py

@@ -129,8 +129,9 @@ class TestExplicitProjectRoot:
         assert not replacements["{{SESSION_STATUS_PATH}}"].startswith(str(execution_root.resolve()))
         assert replacements["{{DEV_SUBAGENT_PATH}}"].startswith(str(execution_root.resolve()))
         assert "### Checkpoint Update Helper" in replacements["{{CHECKPOINT_SYSTEM}}"]
-        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "{{CHECKPOINT_PYTHON_CMD}}" in replacements["{{CHECKPOINT_SYSTEM}}"]
         assert "pipeline progress mechanism" not in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "prizmkit-runtime-helper.py" in replacements["{{RUNTIME_HELPER_CMD}}"]
 
 
 class TestRefactorPromptMaxLogRemoval:

package/bundled/dev-pipeline/tests/test_runtime_helper.py

@@ -0,0 +1,211 @@
+"""Tests for the cross-platform prompt runtime helper CLI."""
+
+import json
+import os
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+HELPER_SCRIPT = PIPELINE_ROOT / "scripts" / "prizmkit-runtime-helper.py"
+CLI_PATH = PIPELINE_ROOT / "cli.py"
+
+if str(PIPELINE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PIPELINE_ROOT))
+
+
+def run_helper(*args, cwd=None):
+    return subprocess.run(
+        [sys.executable, str(HELPER_SCRIPT), *args],
+        cwd=cwd or REPO_ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+def first_line(result):
+    return result.stdout.splitlines()[0]
+
+
+class TestArtifactAndTextHelpers:
+    def test_exists_ensure_dir_touch_list_tree_and_source_files(self, tmp_path):
+        missing = run_helper("artifact", "exists", str(tmp_path / "missing"))
+        assert first_line(missing) == "MISSING"
+
+        ready = run_helper("artifact", "ensure-dir", str(tmp_path / "src"))
+        assert first_line(ready) == "DIR_READY"
+        touched = run_helper("artifact", "touch", str(tmp_path / "src" / "app.py"))
+        assert first_line(touched) == "TOUCHED"
+        (tmp_path / "src" / "README.md").write_text("hello helper\n", encoding="utf-8")
+        (tmp_path / "src" / "ignored.bin").write_bytes(b"\x00")
+
+        listing = run_helper("artifact", "list", str(tmp_path / "src"))
+        assert first_line(listing) == "LIST"
+        assert "file:README.md" in listing.stdout
+        assert "file:app.py" in listing.stdout
+
+        tree = run_helper("artifact", "tree", str(tmp_path), "--max-depth", "2")
+        assert first_line(tree) == "TREE"
+        assert "entry: src/" in tree.stdout
+        assert "entry: src/app.py" in tree.stdout
+
+        sources = run_helper("artifact", "source-files", str(tmp_path), "--ext", ".py", "--json")
+        payload = json.loads(sources.stdout)
+        assert payload["marker"] == "SOURCE_FILES"
+        assert payload["files"] == ["src/app.py"]
+
+    def test_text_search_count_and_contains_markers(self, tmp_path):
+        target = tmp_path / "notes.md"
+        target.write_text("alpha\nbeta alpha\n", encoding="utf-8")
+
+        search = run_helper("text", "search", str(tmp_path), "--pattern", "alpha")
+        assert first_line(search) == "FOUND"
+        assert "count: 2" in search.stdout
+
+        count = run_helper("text", "count", str(tmp_path), "--pattern", "alpha")
+        assert first_line(count) == "COUNT"
+        assert "count: 2" in count.stdout
+
+        contains = run_helper("text", "contains", str(target), "--pattern", "beta")
+        assert first_line(contains) == "GATE:PASS"
+        missing = run_helper("text", "contains", str(target), "--pattern", "gamma")
+        assert first_line(missing) == "GATE:MISSING"
+
+
+class TestPlatformExecutableAndPortHelpers:
+    def test_platform_detection_and_skill_lookup_follow_config(self, tmp_path, monkeypatch):
+        project = tmp_path / "project"
+        skill_dir = project / ".agents" / "skills" / "playwright-cli"
+        skill_dir.mkdir(parents=True)
+        (project / ".prizmkit").mkdir()
+        (project / ".prizmkit" / "config.json").write_text(
+            json.dumps({"platform": "codex", "ai_cli": "codex"}), encoding="utf-8"
+        )
+        monkeypatch.delenv("PRIZMKIT_PLATFORM", raising=False)
+
+        detect = run_helper("platform", "detect", "--project-root", str(project), "--json")
+        payload = json.loads(detect.stdout)
+        assert payload["marker"] == "CODEX"
+        assert payload["platform"] == "codex"
+        assert payload["source"] == "config:ai_cli"
+
+        skill = run_helper("platform", "skill", "playwright-cli", "--project-root", str(project), "--json")
+        payload = json.loads(skill.stdout)
+        assert payload["marker"] == "SKILL_EXISTS"
+        assert payload["platform"] == "codex"
+        assert payload["path"].endswith(".agents/skills/playwright-cli")
+
+    def test_codebuddy_cli_env_wins_over_filesystem_markers(self, tmp_path, monkeypatch):
+        from prizmkit_runtime.platform_detection import resolve_platform
+
+        project = tmp_path / "project"
+        (project / ".claude" / "agents").mkdir(parents=True)
+        monkeypatch.delenv("PRIZMKIT_PLATFORM", raising=False)
+        resolution = resolve_platform(project, env={"CODEBUDDY_CLI": "cbc"})
+
+        assert resolution.platform == "codebuddy"
+        assert resolution.source == "environment:CODEBUDDY_CLI"
+
+    def test_executable_check_and_version_use_shutil_and_direct_subprocess(self, tmp_path):
+        executable = tmp_path / "tool.py"
+        executable.write_text("#!/usr/bin/env python3\nprint('tool 1.2.3')\n", encoding="utf-8")
+        executable.chmod(0o755)
+        env_path = f"{tmp_path}{os.pathsep}{os.environ.get('PATH', '')}"
+
+        result = subprocess.run(
+            [sys.executable, str(HELPER_SCRIPT), "executable", "check", "tool.py"],
+            env={**os.environ, "PATH": env_path},
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert first_line(result) == "INSTALLED"
+
+        version = subprocess.run(
+            [sys.executable, str(HELPER_SCRIPT), "executable", "version", "tool.py", "--arg=--version"],
+            env={**os.environ, "PATH": env_path},
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert first_line(version) == "VERSION"
+        assert "version: tool 1.2.3" in version.stdout
+
+    def test_port_check_reports_free_and_in_use(self):
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.bind(("127.0.0.1", 0))
+        sock.listen(1)
+        port = sock.getsockname()[1]
+        try:
+            in_use = run_helper("port", "check", str(port))
+            assert first_line(in_use) == "PORT_IN_USE"
+        finally:
+            sock.close()
+        free = run_helper("port", "check", str(port))
+        assert first_line(free) == "PORT_FREE"
+
+
+class TestProcessAndEntrypointHelpers:
+    def test_process_start_status_and_cleanup(self, tmp_path):
+        sleeper = tmp_path / "sleep.py"
+        sleeper.write_text("import time\ntime.sleep(30)\n", encoding="utf-8")
+        pid_file = tmp_path / "server.pid"
+
+        start = run_helper(
+            "process",
+            "start",
+            "--pid-file",
+            str(pid_file),
+            "--",
+            sys.executable,
+            str(sleeper),
+        )
+        assert first_line(start) == "PROCESS_STARTED"
+        pid = int(pid_file.read_text(encoding="utf-8").strip())
+
+        status = run_helper("process", "status-pid", str(pid))
+        assert first_line(status) == "PROCESS_RUNNING"
+
+        cleanup = run_helper("process", "cleanup-pid", str(pid), "--grace-seconds", "0.2")
+        assert first_line(cleanup) in {"PROCESS_TERMINATED", "PROCESS_NOT_RUNNING"}
+
+    def test_cleanup_port_is_deterministic_without_lsof(self):
+        result = run_helper("process", "cleanup-port", "9")
+        assert first_line(result) in {"PORT_FREE", "UNSUPPORTED"}
+        assert "lsof" not in result.stdout.lower()
+
+    def test_canonical_cli_exposes_helper_group(self, tmp_path):
+        existing = tmp_path / "exists.txt"
+        existing.write_text("ok", encoding="utf-8")
+        result = subprocess.run(
+            [sys.executable, str(CLI_PATH), "helper", "artifact", "exists", str(existing)],
+            cwd=REPO_ROOT,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert result.returncode == 0
+        assert first_line(result) == "EXISTS"
+
+    def test_web_wait_ready_accepts_local_http_server(self, tmp_path):
+        server = tmp_path / "server.py"
+        server.write_text(
+            "from http.server import HTTPServer, BaseHTTPRequestHandler\n"
+            "class H(BaseHTTPRequestHandler):\n"
+            "    def do_GET(self):\n"
+            "        self.send_response(200); self.end_headers(); self.wfile.write(b'ok')\n"
+            "    def log_message(self, *args): pass\n"
+            "HTTPServer(('127.0.0.1', 0), H).serve_forever()\n",
+            encoding="utf-8",
+        )
+        # Use helper process start for coverage, then skip fixed URL because the
+        # child selects an ephemeral port that is not externally reported.
+        result = run_helper("web", "wait-ready", "--url", "http://127.0.0.1:9", "--timeout", "0.1", "--interval", "0.05")
+        assert first_line(result) == "NOT_READY"

package/bundled/dev-pipeline/tests/test_unified_cli.py

@@ -1904,6 +1904,9 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     (repo / ".prizmkit" / "manifest.json").write_text("{}", encoding="utf-8")
     (repo / ".prizmkit" / "dev-pipeline" / "scripts").mkdir(parents=True)
     (repo / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").write_text("# update", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime").mkdir(parents=True)
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "__init__.py").write_text("", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "runtime_helper.py").write_text("# helper", encoding="utf-8")
     (repo / ".prizmkit" / "dev-pipeline" / "run-feature.sh").write_text("retired", encoding="utf-8")
 
     runtime = worktree_runtime_context(
@@ -1922,6 +1925,8 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     assert (runtime.worktree_path / ".prizmkit" / "config.json").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "manifest.json").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "__init__.py").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "runtime_helper.py").is_file()
     assert not (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "run-feature.sh").exists()
 
     assert guarded_worktree_remove(runtime, delete_branch=False).ok

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.108",
+  "version": "1.1.109",
   "skills": {
     "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.108",
+  "version": "1.1.109",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {