@pencil-agent/nano-pencil 2.0.1 → 2.0.2

package/dist/extensions/builtin/browser/src/browser_harness/run.py

@@ -1,103 +1,103 @@
-"""Browser Harness CLI-compatible runner used by NanoPencil subprocess tools.
-
-[WHO]: Provides main() command dispatch, daemon auto-start, setup/doctor/update/reload flags, and snippet execution
-[FROM]: Depends on browser_harness.admin, browser_harness.helpers, urllib, os, and sys
-[TO]: Consumed by NanoPencil browser/browser_admin tools via python -m browser_harness.run
-[HERE]: extensions/builtin/browser/src/browser_harness/run.py within vendored Browser Harness package
-"""
-
-import os, sys, urllib.request
-
-# Windows default stdout encoding is cp1252, which can't encode the 🟢 marker
-# helpers prepend to tab titles (or anything else outside Latin-1). Force UTF-8
-# so `print(page_info())` doesn't UnicodeEncodeError on Windows. Issue #124(4).
-if hasattr(sys.stdout, "reconfigure"):
-    try: sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    except Exception: pass
-
-from .admin import (
-    _version,
-    NAME,
-    daemon_alive,
-    ensure_daemon,
-    list_cloud_profiles,
-    list_local_profiles,
-    print_update_banner,
-    restart_daemon,
-    run_doctor,
-    run_setup,
-    run_update,
-    start_remote_daemon,
-    stop_remote_daemon,
-    sync_local_profile,
-)
-from .helpers import *
-
-HELP = """Browser Harness
-
-Read SKILL.md for the default workflow and examples.
-
-Typical usage:
-  browser-harness -c '
-  ensure_real_tab()
-  print(page_info())
-  '
-
-Helpers are pre-imported. The daemon auto-starts and connects to the running browser.
-
-Commands:
-  browser-harness --version        print the installed version
-  browser-harness --doctor         diagnose install, daemon, and browser state
-  browser-harness --setup          interactively attach to your running browser
-  browser-harness --update [-y]    pull the latest version (agents: pass -y)
-  browser-harness --reload         stop the daemon so next call picks up code changes
-"""
-
-
-# Probe /json/version (not a bare TCP connect) so a non-Chrome process bound to
-# 9222/9223 doesn't masquerade as Chrome and skip the cloud bootstrap. Mirrors
-# daemon.py's fallback probe.
-def _local_chrome_listening():
-    for port in (9222, 9223):
-        try:
-            urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=0.3).close()
-            return True
-        except OSError: pass
-    return False
-
-
-def main():
-    args = sys.argv[1:]
-    if args and args[0] in {"-h", "--help"}:
-        print(HELP)
-        return
-    if args and args[0] == "--version":
-        print(_version() or "unknown")
-        return
-    if args and args[0] == "--doctor":
-        sys.exit(run_doctor())
-    if args and args[0] == "--setup":
-        sys.exit(run_setup())
-    if args and args[0] == "--update":
-        yes = any(a in {"-y", "--yes"} for a in args[1:])
-        sys.exit(run_update(yes=yes))
-    if args and args[0] == "--reload":
-        restart_daemon()
-        print("daemon stopped — will restart fresh on next call")
-        return
-    if args and args[0] == "--debug-clicks":
-        os.environ["BH_DEBUG_CLICKS"] = "1"
-        args = args[1:]
-    if not args or args[0] != "-c":
-        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
-    if len(args) < 2:
-        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
-    print_update_banner()
-    if not daemon_alive() and not _local_chrome_listening() and os.environ.get("BROWSER_USE_API_KEY"):
-        start_remote_daemon(NAME)
-    ensure_daemon()
-    exec(args[1], globals())
-
-
-if __name__ == "__main__":
-    main()
+"""Browser Harness CLI-compatible runner used by NanoPencil subprocess tools.
+
+[WHO]: Provides main() command dispatch, daemon auto-start, setup/doctor/update/reload flags, and snippet execution
+[FROM]: Depends on browser_harness.admin, browser_harness.helpers, urllib, os, and sys
+[TO]: Consumed by NanoPencil browser/browser_admin tools via python -m browser_harness.run
+[HERE]: extensions/builtin/browser/src/browser_harness/run.py within vendored Browser Harness package
+"""
+
+import os, sys, urllib.request
+
+# Windows default stdout encoding is cp1252, which can't encode the 🟢 marker
+# helpers prepend to tab titles (or anything else outside Latin-1). Force UTF-8
+# so `print(page_info())` doesn't UnicodeEncodeError on Windows. Issue #124(4).
+if hasattr(sys.stdout, "reconfigure"):
+    try: sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception: pass
+
+from .admin import (
+    _version,
+    NAME,
+    daemon_alive,
+    ensure_daemon,
+    list_cloud_profiles,
+    list_local_profiles,
+    print_update_banner,
+    restart_daemon,
+    run_doctor,
+    run_setup,
+    run_update,
+    start_remote_daemon,
+    stop_remote_daemon,
+    sync_local_profile,
+)
+from .helpers import *
+
+HELP = """Browser Harness
+
+Read SKILL.md for the default workflow and examples.
+
+Typical usage:
+  browser-harness -c '
+  ensure_real_tab()
+  print(page_info())
+  '
+
+Helpers are pre-imported. The daemon auto-starts and connects to the running browser.
+
+Commands:
+  browser-harness --version        print the installed version
+  browser-harness --doctor         diagnose install, daemon, and browser state
+  browser-harness --setup          interactively attach to your running browser
+  browser-harness --update [-y]    pull the latest version (agents: pass -y)
+  browser-harness --reload         stop the daemon so next call picks up code changes
+"""
+
+
+# Probe /json/version (not a bare TCP connect) so a non-Chrome process bound to
+# 9222/9223 doesn't masquerade as Chrome and skip the cloud bootstrap. Mirrors
+# daemon.py's fallback probe.
+def _local_chrome_listening():
+    for port in (9222, 9223):
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=0.3).close()
+            return True
+        except OSError: pass
+    return False
+
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in {"-h", "--help"}:
+        print(HELP)
+        return
+    if args and args[0] == "--version":
+        print(_version() or "unknown")
+        return
+    if args and args[0] == "--doctor":
+        sys.exit(run_doctor())
+    if args and args[0] == "--setup":
+        sys.exit(run_setup())
+    if args and args[0] == "--update":
+        yes = any(a in {"-y", "--yes"} for a in args[1:])
+        sys.exit(run_update(yes=yes))
+    if args and args[0] == "--reload":
+        restart_daemon()
+        print("daemon stopped — will restart fresh on next call")
+        return
+    if args and args[0] == "--debug-clicks":
+        os.environ["BH_DEBUG_CLICKS"] = "1"
+        args = args[1:]
+    if not args or args[0] != "-c":
+        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
+    if len(args) < 2:
+        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
+    print_update_banner()
+    if not daemon_alive() and not _local_chrome_listening() and os.environ.get("BROWSER_USE_API_KEY"):
+        start_remote_daemon(NAME)
+    ensure_daemon()
+    exec(args[1], globals())
+
+
+if __name__ == "__main__":
+    main()

package/dist/extensions/builtin/discipline/skills/brainstorming/SKILL.md

@@ -1,33 +1,33 @@
----
-name: brainstorming
-description: Use before creative or behavioral work when intent, scope, design choices, acceptance criteria, or trade-offs are not already explicit.
----
-
-# Brainstorming
-
-Turn an idea into an implementable design before writing code.
-
-## Gate
-
-Do not edit implementation files until the design is clear enough to state:
-
-- The user-visible goal
-- The constrained scope
-- The recommended approach and at least one rejected alternative
-- The main files or modules likely affected
-- Acceptance criteria and verification commands
-
-For small changes, the design can be short. The gate is clarity, not ceremony.
-
-## Process
-
-1. Explore current project context with read-only tools.
-2. Ask one high-value clarification question at a time only when the answer cannot be inferred safely.
-3. Present 2-3 viable approaches with trade-offs.
-4. Recommend one approach and explain why it fits the existing codebase.
-5. Get user approval before implementation when the change is broad, risky, or changes behavior.
-6. If the design will take multiple implementation steps, transition to `writing-plans`.
-
-## Output Standard
-
-Use evidence from the codebase. State assumptions explicitly. Keep the design actionable enough that another agent could implement it without rediscovering the architecture.
+---
+name: brainstorming
+description: Use before creative or behavioral work when intent, scope, design choices, acceptance criteria, or trade-offs are not already explicit.
+---
+
+# Brainstorming
+
+Turn an idea into an implementable design before writing code.
+
+## Gate
+
+Do not edit implementation files until the design is clear enough to state:
+
+- The user-visible goal
+- The constrained scope
+- The recommended approach and at least one rejected alternative
+- The main files or modules likely affected
+- Acceptance criteria and verification commands
+
+For small changes, the design can be short. The gate is clarity, not ceremony.
+
+## Process
+
+1. Explore current project context with read-only tools.
+2. Ask one high-value clarification question at a time only when the answer cannot be inferred safely.
+3. Present 2-3 viable approaches with trade-offs.
+4. Recommend one approach and explain why it fits the existing codebase.
+5. Get user approval before implementation when the change is broad, risky, or changes behavior.
+6. If the design will take multiple implementation steps, transition to `writing-plans`.
+
+## Output Standard
+
+Use evidence from the codebase. State assumptions explicitly. Keep the design actionable enough that another agent could implement it without rediscovering the architecture.

package/dist/extensions/builtin/discipline/skills/executing-plans/SKILL.md

@@ -1,25 +1,25 @@
----
-name: executing-plans
-description: Use when implementing an approved written plan in the current session.
----
-
-# Executing Plans
-
-Execute the approved plan task by task with verification checkpoints.
-
-## Process
-
-1. Read the plan completely.
-2. Check for contradictions, missing files, missing tests, or unsafe assumptions.
-3. Raise blockers before editing.
-4. For each task:
-   - Mark the task in progress.
-   - Follow the stated steps.
-   - Use `test-driven-development` for behavior changes.
-   - Run the specified verification.
-   - Mark the task complete only after evidence supports it.
-5. After all tasks, use `verification-before-completion`.
-
-## Stop Conditions
-
-Stop when a plan instruction is ambiguous enough to change behavior, a required dependency is missing, verification fails repeatedly, or the plan conflicts with current codebase evidence.
+---
+name: executing-plans
+description: Use when implementing an approved written plan in the current session.
+---
+
+# Executing Plans
+
+Execute the approved plan task by task with verification checkpoints.
+
+## Process
+
+1. Read the plan completely.
+2. Check for contradictions, missing files, missing tests, or unsafe assumptions.
+3. Raise blockers before editing.
+4. For each task:
+   - Mark the task in progress.
+   - Follow the stated steps.
+   - Use `test-driven-development` for behavior changes.
+   - Run the specified verification.
+   - Mark the task complete only after evidence supports it.
+5. After all tasks, use `verification-before-completion`.
+
+## Stop Conditions
+
+Stop when a plan instruction is ambiguous enough to change behavior, a required dependency is missing, verification fails repeatedly, or the plan conflicts with current codebase evidence.

package/dist/extensions/builtin/discipline/skills/finishing-development-branch/SKILL.md

@@ -1,25 +1,25 @@
----
-name: finishing-development-branch
-description: Use after implementation is complete and verified, when deciding how to merge, push, preserve, or discard branch work.
----
-
-# Finishing a Development Branch
-
-Complete branch work with evidence and a clear integration choice.
-
-## Process
-
-1. Run the verification that proves the completed work.
-2. Inspect git status and current branch.
-3. Detect whether the workspace is a normal checkout, linked worktree, or detached/headless workspace.
-4. Present concrete options:
-   - Merge locally
-   - Push and create a PR
-   - Keep branch/worktree as-is
-   - Discard work, with explicit confirmation
-5. Execute the chosen path.
-6. Re-run verification after merge when merging locally.
-
-## Safety
-
-Never discard work without typed confirmation. Never remove a worktree unless you can prove it was created for this workflow and is not owned by the harness.
+---
+name: finishing-development-branch
+description: Use after implementation is complete and verified, when deciding how to merge, push, preserve, or discard branch work.
+---
+
+# Finishing a Development Branch
+
+Complete branch work with evidence and a clear integration choice.
+
+## Process
+
+1. Run the verification that proves the completed work.
+2. Inspect git status and current branch.
+3. Detect whether the workspace is a normal checkout, linked worktree, or detached/headless workspace.
+4. Present concrete options:
+   - Merge locally
+   - Push and create a PR
+   - Keep branch/worktree as-is
+   - Discard work, with explicit confirmation
+5. Execute the chosen path.
+6. Re-run verification after merge when merging locally.
+
+## Safety
+
+Never discard work without typed confirmation. Never remove a worktree unless you can prove it was created for this workflow and is not owned by the harness.

package/dist/extensions/builtin/discipline/skills/receiving-code-review/SKILL.md

@@ -1,22 +1,22 @@
----
-name: receiving-code-review
-description: Use when applying human, agent, or external review feedback.
----
-
-# Receiving Code Review
-
-Treat review as technical input to verify, not a script to follow blindly.
-
-## Process
-
-1. Read all feedback before editing.
-2. Restate unclear items or ask for clarification.
-3. Verify each item against current codebase behavior.
-4. Accept technically valid feedback and implement one item at a time.
-5. Push back with evidence when feedback is incorrect, breaks existing behavior, or violates scope.
-6. Run focused verification after each substantive fix.
-7. Run broader verification before completion.
-
-## YAGNI Check
-
-If feedback asks for "proper" infrastructure, search for actual usage. If nothing uses the path, consider deleting or deferring rather than expanding unused surface area.
+---
+name: receiving-code-review
+description: Use when applying human, agent, or external review feedback.
+---
+
+# Receiving Code Review
+
+Treat review as technical input to verify, not a script to follow blindly.
+
+## Process
+
+1. Read all feedback before editing.
+2. Restate unclear items or ask for clarification.
+3. Verify each item against current codebase behavior.
+4. Accept technically valid feedback and implement one item at a time.
+5. Push back with evidence when feedback is incorrect, breaks existing behavior, or violates scope.
+6. Run focused verification after each substantive fix.
+7. Run broader verification before completion.
+
+## YAGNI Check
+
+If feedback asks for "proper" infrastructure, search for actual usage. If nothing uses the path, consider deleting or deferring rather than expanding unused surface area.

package/dist/extensions/builtin/discipline/skills/requesting-code-review/SKILL.md

@@ -1,31 +1,31 @@
----
-name: requesting-code-review
-description: Use after meaningful implementation tasks, before merging, or when a fresh review would reduce risk.
----
-
-# Requesting Code Review
-
-Ask for review with precise context and explicit requirements.
-
-## Review Packet
-
-Provide the reviewer:
-
-- Summary of the intended change
-- Requirements or plan being checked
-- Files changed
-- Base and head SHAs when available
-- Verification already run
-- Known risks or areas needing attention
-
-## Review Standard
-
-Ask the reviewer to lead with findings ordered by severity. Findings need file and line references, a concrete failure mode, and a suggested correction. Require distinction between:
-
-- Critical: must fix before proceeding
-- Important: should fix before merge
-- Minor: optional improvement
-
-## After Review
-
-Use `receiving-code-review` before applying feedback.
+---
+name: requesting-code-review
+description: Use after meaningful implementation tasks, before merging, or when a fresh review would reduce risk.
+---
+
+# Requesting Code Review
+
+Ask for review with precise context and explicit requirements.
+
+## Review Packet
+
+Provide the reviewer:
+
+- Summary of the intended change
+- Requirements or plan being checked
+- Files changed
+- Base and head SHAs when available
+- Verification already run
+- Known risks or areas needing attention
+
+## Review Standard
+
+Ask the reviewer to lead with findings ordered by severity. Findings need file and line references, a concrete failure mode, and a suggested correction. Require distinction between:
+
+- Critical: must fix before proceeding
+- Important: should fix before merge
+- Minor: optional improvement
+
+## After Review
+
+Use `receiving-code-review` before applying feedback.

package/dist/extensions/builtin/discipline/skills/systematic-debugging/SKILL.md

@@ -1,28 +1,28 @@
----
-name: systematic-debugging
-description: Use for any bug, test failure, build failure, performance issue, flaky behavior, or unexpected runtime result before proposing fixes.
----
-
-# Systematic Debugging
-
-Find the root cause before changing code.
-
-## Gate
-
-No fixes before root-cause investigation. A patch that only explains the symptom is not ready.
-
-## Process
-
-1. Read the exact error, stack trace, failing assertion, or observed behavior.
-2. Reproduce the issue or document why reproduction is not currently possible.
-3. Check recent changes and nearby working examples.
-4. Trace the bad value, state, or control flow backward to its source.
-5. Form one explicit hypothesis: "X causes Y because Z."
-6. Test the hypothesis with the smallest evidence-gathering action.
-7. Add a failing regression test or minimal reproduction before the fix when the codebase can support it.
-8. Implement one root-cause fix.
-9. Run focused verification, then broader regression checks as risk requires.
-
-## Stop Conditions
-
-Stop and re-analyze when a hypothesis fails. If three fix attempts fail or each fix reveals a new unrelated problem, question the architecture instead of stacking patches.
+---
+name: systematic-debugging
+description: Use for any bug, test failure, build failure, performance issue, flaky behavior, or unexpected runtime result before proposing fixes.
+---
+
+# Systematic Debugging
+
+Find the root cause before changing code.
+
+## Gate
+
+No fixes before root-cause investigation. A patch that only explains the symptom is not ready.
+
+## Process
+
+1. Read the exact error, stack trace, failing assertion, or observed behavior.
+2. Reproduce the issue or document why reproduction is not currently possible.
+3. Check recent changes and nearby working examples.
+4. Trace the bad value, state, or control flow backward to its source.
+5. Form one explicit hypothesis: "X causes Y because Z."
+6. Test the hypothesis with the smallest evidence-gathering action.
+7. Add a failing regression test or minimal reproduction before the fix when the codebase can support it.
+8. Implement one root-cause fix.
+9. Run focused verification, then broader regression checks as risk requires.
+
+## Stop Conditions
+
+Stop and re-analyze when a hypothesis fails. If three fix attempts fail or each fix reveals a new unrelated problem, question the architecture instead of stacking patches.

package/dist/extensions/builtin/discipline/skills/test-driven-development/SKILL.md

@@ -1,32 +1,32 @@
----
-name: test-driven-development
-description: Use when implementing features, bug fixes, refactors, or behavior changes before writing production code.
----
-
-# Test-Driven Development
-
-Use red, green, refactor for behavior changes.
-
-## Gate
-
-No production behavior change without first seeing a test fail for the intended reason, unless the user explicitly accepts an exception.
-
-## Cycle
-
-1. Write the smallest test that describes one desired behavior.
-2. Run it and verify it fails for the expected reason.
-3. Implement the minimum production code needed to pass.
-4. Run the focused test and verify it passes.
-5. Run nearby or broader tests appropriate to the blast radius.
-6. Refactor only after tests are green, then re-run verification.
-
-## Good Tests
-
-- Test observable behavior, not private implementation details.
-- Prefer real code paths over mocks unless isolation requires a mock.
-- Use names that describe the behavior being guaranteed.
-- Split tests when the name needs "and".
-
-## Exceptions
-
-Acceptable exceptions include pure documentation, generated artifacts, exploratory prototypes, and configuration-only changes. State the exception before proceeding.
+---
+name: test-driven-development
+description: Use when implementing features, bug fixes, refactors, or behavior changes before writing production code.
+---
+
+# Test-Driven Development
+
+Use red, green, refactor for behavior changes.
+
+## Gate
+
+No production behavior change without first seeing a test fail for the intended reason, unless the user explicitly accepts an exception.
+
+## Cycle
+
+1. Write the smallest test that describes one desired behavior.
+2. Run it and verify it fails for the expected reason.
+3. Implement the minimum production code needed to pass.
+4. Run the focused test and verify it passes.
+5. Run nearby or broader tests appropriate to the blast radius.
+6. Refactor only after tests are green, then re-run verification.
+
+## Good Tests
+
+- Test observable behavior, not private implementation details.
+- Prefer real code paths over mocks unless isolation requires a mock.
+- Use names that describe the behavior being guaranteed.
+- Split tests when the name needs "and".
+
+## Exceptions
+
+Acceptable exceptions include pure documentation, generated artifacts, exploratory prototypes, and configuration-only changes. State the exception before proceeding.

package/dist/extensions/builtin/discipline/skills/using-git-worktrees/SKILL.md

@@ -1,25 +1,25 @@
----
-name: using-git-worktrees
-description: Use before feature work that should be isolated from the current branch, or before executing a multi-step implementation plan.
----
-
-# Using Git Worktrees
-
-Prefer isolated workspaces for risky or multi-step changes.
-
-## Process
-
-1. Detect whether the current checkout is already a linked worktree:
-   - `git rev-parse --git-dir`
-   - `git rev-parse --git-common-dir`
-   - `git rev-parse --show-superproject-working-tree`
-2. If already isolated and not a submodule, continue there.
-3. If not isolated, ask before creating a worktree unless the user or plan already requested isolation.
-4. Prefer native workspace tools when available.
-5. If using `git worktree`, place project-local worktrees under `.worktrees/` when it is ignored.
-6. Run project setup only when dependencies are missing or stale.
-7. Establish a clean baseline with the relevant tests before changing behavior.
-
-## Safety
-
-Do not remove harness-owned worktrees. Do not proceed from a failing baseline without telling the user what failed and getting direction or investigating the failure.
+---
+name: using-git-worktrees
+description: Use before feature work that should be isolated from the current branch, or before executing a multi-step implementation plan.
+---
+
+# Using Git Worktrees
+
+Prefer isolated workspaces for risky or multi-step changes.
+
+## Process
+
+1. Detect whether the current checkout is already a linked worktree:
+   - `git rev-parse --git-dir`
+   - `git rev-parse --git-common-dir`
+   - `git rev-parse --show-superproject-working-tree`
+2. If already isolated and not a submodule, continue there.
+3. If not isolated, ask before creating a worktree unless the user or plan already requested isolation.
+4. Prefer native workspace tools when available.
+5. If using `git worktree`, place project-local worktrees under `.worktrees/` when it is ignored.
+6. Run project setup only when dependencies are missing or stale.
+7. Establish a clean baseline with the relevant tests before changing behavior.
+
+## Safety
+
+Do not remove harness-owned worktrees. Do not proceed from a failing baseline without telling the user what failed and getting direction or investigating the failure.