fengming 0.3.10 → 0.3.11

package/scripts/preinstall-package-manager-warning.mjs

@@ -1,64 +0,0 @@
-import { pathToFileURL } from "node:url";
-
-const allowedLifecyclePackageManagers = new Set(["pnpm", "npm", "yarn", "bun"]);
-
-function normalizeEnvValue(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizeLifecyclePackageManagerName(value) {
-  const normalized = normalizeEnvValue(value).toLowerCase();
-  if (!/^[a-z0-9][a-z0-9._-]*$/u.test(normalized)) {
-    return null;
-  }
-  return allowedLifecyclePackageManagers.has(normalized) ? normalized : null;
-}
-
-export function detectLifecyclePackageManager(env = process.env) {
-  const userAgent = normalizeEnvValue(env.npm_config_user_agent);
-  const userAgentMatch = /^([A-Za-z0-9._-]+)\//u.exec(userAgent);
-  if (userAgentMatch) {
-    return normalizeLifecyclePackageManagerName(userAgentMatch[1]);
-  }
-
-  const execPath = normalizeEnvValue(env.npm_execpath).toLowerCase();
-  if (execPath.includes("pnpm")) {
-    return "pnpm";
-  }
-  if (execPath.includes("npm")) {
-    return "npm";
-  }
-  if (execPath.includes("yarn")) {
-    return "yarn";
-  }
-  if (execPath.includes("bun")) {
-    return "bun";
-  }
-
-  return null;
-}
-
-export function createPackageManagerWarningMessage(packageManager) {
-  if (!packageManager || packageManager === "pnpm") {
-    return null;
-  }
-
-  return [
-    `[fengming] warning: detected ${packageManager} for install lifecycle.`,
-    "[fengming] this repo works best with pnpm; npm-compatible installs are slower and much larger here.",
-    "[fengming] prefer: corepack pnpm install",
-  ].join("\n");
-}
-
-export function warnIfNonPnpmLifecycle(env = process.env, warn = console.warn) {
-  const message = createPackageManagerWarningMessage(detectLifecyclePackageManager(env));
-  if (!message) {
-    return false;
-  }
-  warn(message);
-  return true;
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-  warnIfNonPnpmLifecycle();
-}

package/scripts/prepare-git-hooks.mjs

@@ -1,72 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const scriptDir = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_PACKAGE_ROOT = join(scriptDir, "..");
-
-function getMissingGitReason(error) {
-  if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-    return "missing-git";
-  }
-  return null;
-}
-
-function runGit(spawn, gitBin, args, cwd, stdio) {
-  return spawn(gitBin, args, {
-    cwd,
-    encoding: "utf8",
-    stdio,
-  });
-}
-
-export function configurePrepareGitHooks(params = {}) {
-  const cwd = params.cwd ?? DEFAULT_PACKAGE_ROOT;
-  const exists = params.existsSync ?? existsSync;
-  const gitBin = params.gitBin ?? "git";
-  const spawn = params.spawnSync ?? spawnSync;
-  const warn = params.warn ?? console.warn;
-
-  if (!exists(join(cwd, "git-hooks"))) {
-    return { configured: false, reason: "missing-hooks-dir" };
-  }
-
-  const worktree = runGit(
-    spawn,
-    gitBin,
-    ["rev-parse", "--is-inside-work-tree"],
-    cwd,
-    ["ignore", "pipe", "ignore"],
-  );
-  const missingGitReason = getMissingGitReason(worktree.error);
-  if (missingGitReason) {
-    return { configured: false, reason: missingGitReason };
-  }
-  if (worktree.status !== 0 || String(worktree.stdout ?? "").trim() !== "true") {
-    return { configured: false, reason: "not-worktree" };
-  }
-
-  const configured = runGit(
-    spawn,
-    gitBin,
-    ["config", "core.hooksPath", "git-hooks"],
-    cwd,
-    ["ignore", "ignore", "pipe"],
-  );
-  const configMissingGitReason = getMissingGitReason(configured.error);
-  if (configMissingGitReason) {
-    return { configured: false, reason: configMissingGitReason };
-  }
-  if (configured.status !== 0) {
-    const stderr = String(configured.stderr ?? "").trim();
-    warn(`[prepare] could not configure git hooks${stderr ? `: ${stderr}` : ""}`);
-    return { configured: false, reason: "config-failed" };
-  }
-
-  return { configured: true, reason: "configured" };
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-  configurePrepareGitHooks();
-}

package/scripts/windows-cmd-helpers.mjs

@@ -1,22 +0,0 @@
-const WINDOWS_UNSAFE_CMD_CHARS_RE = /[&|<>%\r\n]/;
-
-export function resolvePathEnvKey(env) {
-  return Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
-}
-
-function escapeForCmdExe(arg) {
-  if (WINDOWS_UNSAFE_CMD_CHARS_RE.test(arg)) {
-    throw new Error(`unsafe Windows cmd.exe argument detected: ${JSON.stringify(arg)}`);
-  }
-  const escaped = arg.replace(/\^/g, "^^");
-  if (!escaped.includes(" ") && !escaped.includes('"')) {
-    return escaped;
-  }
-  return `"${escaped.replace(/"/g, '""')}"`;
-}
-
-export function buildCmdExeCommandLine(command, args) {
-  const escapedCommand = escapeForCmdExe(command);
-  const commandLine = [escapedCommand, ...args.map(escapeForCmdExe)].join(" ");
-  return escapedCommand.startsWith('"') ? `"${commandLine}"` : commandLine;
-}

package/skills/batch/SKILL.md

@@ -1,118 +0,0 @@
----
-name: batch
-description: Orchestrate large-scale changes across a codebase in parallel. Researches the codebase, decomposes the work into independent units, and presents a plan before executing. Use when the user needs to apply a systematic change to many files, migrate patterns, or refactor at scale.
-when_to_use: "User asks to apply a change across the entire codebase, migrate from one pattern to another, refactor a type/function/import everywhere, or make a systematic change that touches many files. Trigger phrases: batch, migrate, replace everywhere, refactor across the codebase, change all instances of, convert every file to. Requires a git repository."
----
-
-# Batch
-
-Orchestrate a large, multi-file change by decomposing it into independent units that can be executed in parallel.
-
-## How batch works
-
-1. **Research**: Search the codebase to understand the full scope of the change
-2. **Decompose**: Break the work into 5-30 independent units that don't depend on each other
-3. **Present a plan**: Show the user the decomposition and wait for approval before proceeding
-4. **Execute**: Spawn subagents (one per unit) that each implement their part independently
-5. **Report**: Summarize results — units succeeded, failed, or need attention
-
-Each unit must be self-contained: unit A should not depend on the output of unit B. If two changes touch the same file, they are one unit.
-
-## Step 1: Research the scope
-
-Before proposing any decomposition, understand the target:
-
-1. Search for the pattern to be changed: use `grep` / `Select-String` to find all occurrences
-2. Count affected files and estimate lines per file
-3. Identify structural boundaries: packages, modules, directories that can serve as unit boundaries
-4. Check for interdependencies: imports, shared types, configuration files that span boundaries
-5. Report: "Found X occurrences across Y files in Z modules"
-
-## Step 2: Decompose into units
-
-Divide the work into independent units. Good unit boundaries:
-
-- By package/directory: each package is a unit if its changes are self-contained
-- By file type: migration of one type of file that doesn't affect others
-- By concern: types, implementation, tests can be separate units if they don't overlap
-
-Each unit should have:
-
-- A clear description of what to change
-- A specific list of files to modify
-- A success criterion (what must be true when done)
-- No dependency on another unit's results
-
-Present the plan:
-
-```
-## Batch Plan: <description>
-
-Scope: X occurrences across Y files in Z modules
-Strategy: decompose by <boundary type>
-
-### Units (N independent units)
-
-1. **<unit-name>** — <description>
-   Files: file1.ts, file2.ts (X lines)
-   Success: <criterion>
-
-2. **<unit-name>** — <description>
-   Files: file3.ts, file4.ts (Y lines)
-   Success: <criterion>
-
-...
-
-Execute when approved.
-```
-
-Wait for explicit user approval. Do not proceed to execution until the user confirms.
-
-## Step 3: Execute units in parallel
-
-After approval, spawn one subagent per unit using `sessions_spawn`. Each subagent gets:
-
-- A focused task description based on the unit
-- The specific files to modify
-- The success criterion
-
-Configure subagents with:
-- `runtime: "subagent"`
-- `mode: "run"`
-- A timeout appropriate to the unit's size
-
-```
-sessions_spawn:
-  task: "Implement unit <N>: <description>. Files: <list>. Success: <criterion>."
-  runtime: "subagent"
-  mode: "run"
-```
-
-## Step 4: Report results
-
-After all subagents complete:
-
-1. Check each subagent's output for correctness
-2. Run the project's type checker to verify cross-unit consistency
-3. Report a summary:
-
-```
-## Batch Results
-
-### Completed (N)
-- unit-1: <brief result>
-- unit-2: <brief result>
-
-### Needs attention (M)
-- unit-3: <what went wrong and what to do>
-
-Type check: passed / failed with N errors
-```
-
-## Constraints
-
-- The change must be in a git repository (for safety and rollback)
-- Units must be truly independent — if two units touch the same file, merge them
-- Don't proceed to execution until the user explicitly approves the plan
-- If the user passes `--dry-run`, only research and present the plan, do not execute
-- Each subagent only modifies its assigned files

package/skills/code-review/SKILL.md

@@ -1,107 +0,0 @@
----
-name: code-review
-description: Review the current diff for correctness bugs, security vulnerabilities, and cleanup opportunities (reuse, simplification, efficiency). Use when the user asks for a code review, checks a diff, wants to audit a change, or passes /code-review.
-when_to_use: "User asks to review code, check a diff, audit a change, find bugs, or simplify code. Trigger phrases: code review, review this, check my changes, find bugs in this diff, is this correct, simplify this code, can this be cleaner. Automatically activate when user mentions reviewing pull requests or uncommitted changes."
----
-
-# Code Review
-
-Review code changes for correctness bugs, security vulnerabilities, and cleanup opportunities. When passed `--fix`, apply findings to the working tree. When passed `--comment`, post findings as inline GitHub PR comments.
-
-## Step 1: Determine the scope
-
-Identify what to review. In priority order:
-
-1. If a target is passed as an argument, review that commit/branch/PR/file
-2. Otherwise, review uncommitted changes: run `git diff` for unstaged changes and `git diff --cached` for staged changes
-3. If `--comment` is passed and there is an open PR on the current branch (detected via `gh pr view`), use the PR diff
-
-If the diff is empty, say so and stop — nothing to review.
-
-For the target argument:
-- A commit hash: run `git show <hash>`
-- A branch name: run `git diff main...<branch>` (or the repo's default branch)
-- A file path: read the file and its git history
-
-## Step 2: Choose the effort level
-
-The user can specify an effort level as the first argument:
-
-- **low**: Quick scan for obvious correctness bugs only. Surface-level logic errors, missing null checks, inverted conditions.
-- **medium** (default): Standard review. Correctness bugs plus simplification opportunities.
-- **high**: Thorough review. All of the above plus deeper analysis for edge cases, error handling gaps, and security issues.
-- **xhigh**: Very thorough. Like high but with more detailed analysis and reasoning.
-- **max**: Maximum single-agent effort. Exhaustive analysis of every line in the diff.
-
-Adapt the depth of reasoning to the level. Higher levels should produce more findings and more detailed explanations.
-
-## Step 3: Review the diff
-
-Read every line of the diff. For each change, check:
-
-### Correctness bugs (highest priority)
-
-- Logic errors: wrong conditions, off-by-one errors, inverted booleans, incorrect operator precedence
-- Missing null/undefined/empty checks that could cause runtime crashes
-- Race conditions: shared mutable state without synchronization, async operations without proper await ordering
-- Error handling gaps: swallowed exceptions, missing try/catch around fallible operations, unhandled promise rejections
-- Incorrect API usage: wrong parameter types, wrong argument order, misunderstanding of library contracts
-- Breaking changes to public interfaces: changed function signatures, removed exports, altered return types
-- Type mismatches: places where the actual type won't match the expected type at runtime
-
-### Security vulnerabilities
-
-- Injection risks: unsanitized input used in shell commands, SQL queries, HTML/JS output
-- Hardcoded secrets: API keys, tokens, passwords, private keys in source code
-- Path traversal: user input used to construct file paths without validation
-- Missing authentication or authorization checks in new endpoints or handlers
-- Unsafe deserialization: `eval()`, `Function()`, unsafe JSON parsing patterns
-- Information exposure: sensitive data logged, included in error messages, or returned in API responses
-
-### Simplification and cleanup
-
-- Dead code: unreachable branches, unused variables, functions that are never called
-- Duplication: logic repeated across the diff that should be extracted
-- Overly complex expressions: deeply nested ternaries, conditions that can be simplified
-- Unnecessary abstraction: wrapper functions that add no value, over-engineered patterns
-- Misleading names: variables or functions whose names don't match what they actually do
-- Missing or outdated comments for non-obvious logic
-
-For each finding, cite the specific file path and line number from the diff.
-
-## Step 4: Present the review
-
-Group findings by severity:
-
-```
-## Code Review
-
-### Critical (bugs and security)
-- **`src/auth/login.ts:42`**: <description of the problem and why it matters>
-  Fix: <concrete, specific fix — not just a suggestion>
-
-### Improvement (simplification, cleanup, efficiency)
-- **`src/utils/format.ts:15`**: <description>
-  Suggestion: <concrete improvement>
-```
-
-If no issues are found, say: `No issues found.` Do not invent problems that don't exist.
-
-## Step 5: Apply fixes (if --fix)
-
-If `--fix` is passed as an argument, apply the fixes from the review. For each finding:
-
-1. Use the `edit` tool to make the change described in the fix
-2. After all fixes are applied, report a summary: "Applied N fixes to M files"
-
-If `--comment` is passed, instead use `gh pr review` with `--comment` to post findings as inline PR review comments. Only use this if the `gh` CLI is installed and available.
-
-## Guidelines
-
-- Be specific: cite exact file paths and line numbers
-- Explain WHY something is a bug, not just that it looks wrong
-- For each finding, provide a concrete fix that would resolve it
-- Do not flag personal style preferences as bugs
-- Skip trivial formatting issues that a linter would catch
-- If the diff is very large, prioritize the most impactful findings first
-- When uncertain whether something is a real problem, note your uncertainty rather than asserting

package/skills/debug/SKILL.md

@@ -1,83 +0,0 @@
----
-name: debug
-description: Enable debug logging for the current session and troubleshoot runtime issues, build errors, crashes, and unexpected behavior. Use when the user encounters a problem, sees an error, or asks to debug something.
-when_to_use: "User reports an error message, stack trace, crash, hang, incorrect output, build failure, or type error. Trigger phrases: debug this, why isn't this working, I got an error, it crashed, fix this error, what's wrong with, diagnose, troubleshoot. Also activate when the user explicitly runs /debug."
----
-
-# Debug
-
-Diagnose and troubleshoot runtime issues, build errors, and unexpected behavior by enabling debug logging and systematically isolating the root cause.
-
-## Step 1: Reproduce the issue
-
-The first goal is to reproduce the problem reliably:
-
-1. Identify the exact command, input, or action that triggers the issue
-2. Run the command yourself to capture the full error output — include the complete stack trace if there is one
-3. Note the environment: operating system, tool versions, working directory, relevant environment variables
-4. Confirm the issue happens consistently (not a one-time fluke)
-
-If the issue is intermittent, note that and try to identify conditions that make it more likely.
-
-## Step 2: Isolate
-
-Narrow down the cause by eliminating variables one at a time:
-
-1. **Recent changes**: Run `git log --oneline -10` and `git diff HEAD~1` to see what changed recently
-2. **Environment check**: Verify the issue occurs with different Node versions, operating systems, or configurations
-3. **Minimal reproduction**: Strip away unrelated code, inputs, or configuration until you have the smallest possible scenario that still triggers the problem
-4. **Dependency check**: Verify installed dependency versions with `npm ls <package>` or equivalent
-5. **Configuration check**: Read the project's configuration files for errors, conflicts, or missing settings
-
-## Step 3: Diagnose
-
-Use these techniques in order of least to most invasive:
-
-1. **Read the error carefully**: Start from the top of the stack trace and work down. The first frame is often the most informative.
-2. **Binary search**: If the bug appeared after a set of changes, use git to bisect: check out intermediate commits to find which change introduced it
-3. **Add temporary logging**: Insert log statements at key decision points to trace the actual execution path
-4. **Check documentation**: Verify the failing API, function, or module is being called correctly
-5. **Compare with working state**: Look at a previous known-good version of the same code
-6. **Search for similar issues**: Check the project's issue tracker, Stack Overflow, or the library's documentation for similar problems
-
-## Step 4: Identify the root cause
-
-Once you've found the cause, explain it clearly:
-
-1. What exactly is wrong (the specific line or configuration)
-2. Why it fails (the mechanism — not just "it's broken")
-3. What the correct behavior should be
-4. Any assumptions that were violated
-
-## Step 5: Fix and verify
-
-1. Propose the fix: show the exact code change or configuration change needed
-2. Apply the fix using the appropriate tool (edit for file changes, exec for configuration)
-3. Verify the fix by reproducing the original scenario:
-   - Run the same command that triggered the error
-   - Confirm no error occurs
-   - Check that the output is correct
-4. Look for similar patterns in the codebase that might have the same root cause
-
-## Step 6: Report
-
-Summarize the debugging session:
-
-```
-## Debug: <brief description>
-
-- **Error**: <error message>
-- **Root cause**: <what was wrong, at file:line>
-- **Fix**: <what was changed>
-- **Verified**: <how you confirmed it works>
-```
-
-## Guidelines
-
-- Always include the full error message and stack trace in your analysis
-- Don't guess — if you're not sure, say so and investigate further
-- Start with the simplest explanations: typo, wrong version, missing dependency, wrong working directory
-- When fixing, explain WHY the fix works, not just what it changes
-- If a fix might have side effects elsewhere, call them out explicitly
-- For build errors: run the build command again after fixing to confirm zero errors
-- For runtime errors: run the exact scenario that triggered the error to confirm it's resolved

package/skills/loop/SKILL.md

@@ -1,118 +0,0 @@
----
-name: loop
-description: Run a prompt on a repeating schedule, either at a fixed interval or self-paced between iterations. Use for periodic checks, watch tasks, ongoing monitoring, or any task that should repeat until a condition is met.
-when_to_use: "User asks to run something every X minutes/hours/days, keep checking until a condition is met, watch for changes, monitor something, or repeat a prompt. Trigger phrases: loop this, repeat, keep checking, every N minutes, run on a schedule, watch for, monitor until, poll this. Use /loop with a description of what to do and how often."
----
-
-# Loop
-
-Execute a prompt repeatedly, either at a fixed interval (cron-based) or self-paced (run, wait, run again), until a stop condition is met.
-
-## Step 1: Parse the request
-
-Determine what to run and when, using the arguments passed to `/loop`:
-
-```
-/loop every 2 minutes: check the deploy status at https://example.com/health
-/loop: run the tests and fix any failures, stop when all pass
-/loop every 1 hour: pull latest changes and verify the build
-```
-
-Extract:
-- **Interval**: how often to run (e.g., "every 2 minutes", "every hour", "daily at 9am")
-- **Self-paced**: if no interval is given, run the task, wait for it to finish, then decide whether to run again
-- **Stop condition**: when to stop the loop (explicit condition, or default to 1 hour max unless user specifies otherwise)
-- **Task**: what to actually do each iteration
-
-## Step 2: Set up the loop
-
-### Timed intervals
-
-If a fixed interval is specified, use `cron` to create the recurring job:
-
-```
-cron add:
-  schedule: { kind: "every", everyMs: <interval in milliseconds> }
-  payload: { kind: "agentTurn", message: "<task description>" }
-  sessionTarget: "isolated"
-```
-
-Calculate `everyMs` from the user's specification:
-- "every 5 minutes" → 300000
-- "every 1 hour" → 3600000
-- "every 30 seconds" → 30000
-
-For cron expressions (e.g., "every day at 9am"):
-```
-cron add:
-  schedule: { kind: "cron", expr: "0 9 * * *", tz: "Asia/Shanghai" }
-  payload: { kind: "agentTurn", message: "<task description>" }
-  sessionTarget: "isolated"
-```
-
-### Self-paced loops
-
-If no interval is given, run the loop inline:
-
-1. Execute the task in the current session
-2. Report the result
-3. Decide: has the stop condition been met?
-   - If yes: report success and stop
-   - If no: wait a brief moment, then go back to step 1
-
-## Step 3: Execute each iteration
-
-For each iteration of the loop, whether cron-based or self-paced:
-
-1. **Execute the task**: Run the command, check, or action the user specified
-2. **Check the result**: Did it succeed? Is the condition met?
-3. **Report concisely**: One line per iteration is ideal — don't flood the conversation
-4. **Decide whether to continue**: Has the stop condition been met?
-
-Example iteration outputs:
-
-```
-[Loop · 14:03] Deploy status: building... 
-[Loop · 14:05] Deploy status: deploying...
-[Loop · 14:08] Deploy status: ✅ live at https://example.com
-Loop stopped: deploy successful.
-```
-
-## Step 4: Handle errors
-
-If an iteration fails:
-
-1. Report the error briefly
-2. Decide whether to retry or stop:
-   - **Retry**: if the error is likely transient (network timeout, temporary unavailability)
-   - **Stop**: if the error is persistent (incorrect credentials, resource not found, build errors)
-3. If retrying, wait at least 30 seconds before the next attempt
-4. If the same error occurs 3 consecutive times, stop the loop and report
-
-## Step 5: Stop the loop
-
-The loop stops when:
-
-1. **Success**: the condition is met (deploy complete, file changed, test passes)
-2. **User cancel**: the user explicitly asks to stop
-3. **Fatal error**: an unrecoverable error occurs
-4. **Timeout**: the loop has run for the maximum duration (default: 1 hour, unless the user specifies otherwise)
-5. **Max iterations**: if an iteration limit was specified, stop after that many iterations
-
-When stopping, always report why:
-
-```
-Loop stopped after 6 iterations (12 minutes). Condition met: all tests passing.
-```
-
-## Common loop patterns
-
-**Build watch**: `git fetch && git log origin/main..HEAD --oneline` to check if new commits changed build status
-
-**Deploy check**: `curl -s https://deploy.example.com/status` to poll deployment endpoint
-
-**CI monitor**: `gh pr checks` to see if PR checks have completed
-
-**File watch**: `git diff --name-only` to detect new changes in the working tree
-
-**Health check**: `curl -s -o /dev/null -w "%{http_code}" <url>` to verify endpoint responds with 200

package/skills/run/SKILL.md

@@ -1,79 +0,0 @@
----
-name: run
-description: Launch and drive the application to see a change working. Infers the launch method from the project type (CLI, server, TUI, browser), README, package.json, or Makefile. Use after making code changes to verify them in a running app.
-when_to_use: "User wants to run the app, start the server, see the change in action, launch the project, or test their changes in a running instance. Trigger phrases: run it, start the app, launch this, let me see it working, run the server, fire it up, show me. Activate automatically after code changes when user wants to see results."
----
-
-# Run
-
-Launch the application and drive it to confirm your changes work in a live environment.
-
-## Step 1: Detect the project type
-
-Determine how to launch this project. Check in this order:
-
-1. **README.md**: Look for "Getting Started", "Running", "Development", or "Quick Start" sections that describe how to launch
-2. **package.json**: Check the `scripts` field — look for `start`, `dev`, `serve`, `run`, or other launch-like scripts
-3. **Makefile**: Check for `run`, `start`, `dev`, or `serve` targets
-4. **Inference**: Based on the project's nature:
-   - **CLI tool**: Find the main entry point (usually `bin` field in package.json, or an `index.js`/`main.py`/`main.go` at the root or in `src/`)
-   - **Web server**: Look for Express, Fastify, Koa, Flask, Django, Rails, etc. — find the entry file and suggested launch command
-   - **TUI app**: Check for terminal UI frameworks (Ink, blessed, charmbracelet, etc.) and their standard launch methods
-   - **Browser-driven app**: For web apps with a UI, open the dev server URL in a browser
-   - **Static site**: Run the build, then the dev server or static server
-   - **Library/package**: Find the test suite entry point — the "run" for a library is its tests
-
-## Step 2: Launch the app
-
-1. **Determine the launch command**: Use what you found in Step 1
-2. **Run it**: Use `exec` with the appropriate command
-3. **Check for errors**: If launch fails, read the error output and try to fix common issues:
-   - Missing environment variables (`.env` file doesn't exist, wrong values)
-   - Missing dependencies (run `npm install` / `pip install` / `go mod download` first)
-   - Port conflict (pick a different port)
-   - Build step required (run the build command first)
-4. **Adjust and retry**: If the first attempt fails, try the next most likely launch method
-
-## Step 3: Drive the app
-
-Once the app is running, interact with it to verify behavior:
-
-**For CLI tools**: Run it with common arguments and check the output:
-```
-exec: node dist/cli.js --help
-exec: node dist/cli.js <command> <args>
-```
-
-**For web servers**: Make HTTP requests to verify endpoints:
-```
-exec: curl -s http://localhost:3000/health
-exec: curl -s http://localhost:3000/api/endpoint
-```
-
-**For browser apps**: Use `browser` tools to open the URL and interact:
-```
-browser navigate: http://localhost:3000
-browser snapshot: capture the page state
-```
-
-**For TUIs**: The app runs interactively — verify it starts without errors and displays correctly.
-
-## Step 4: Report
-
-After running, summarize:
-
-```
-## Run: <project>
-
-Launch: `npm start` (or whatever worked)
-Result: ✅ running at http://localhost:3000 (or ✅ output correct, or ❌ failed)
-Output: <key output or errors>
-```
-
-## Guidelines
-
-- Clean up after yourself: stop servers and other processes after verifying, unless the user asked to keep them running
-- If the app requires setup steps before running (npm install, pip install, build), do those first
-- For web servers, use a random available port if the default is taken, and tell the user which port
-- If the project is a library with no runnable entry point, run the test suite instead
-- If launch fails after 3 attempts with different approaches, report what you tried and ask for guidance