feat: add scope-based session management by hawkeyexl · Pull Request #150 · doc-detective/common

hawkeyexl · 2026-01-06T19:08:02Z

Summary

Added scope property to runShell, runCode, and type actions for persistent terminal/code sessions
Added waitUntil property to runShell and runCode for condition-based waiting on stdout/stderr patterns
Created new terminateScope action for process lifecycle management with SIGTERM/SIGKILL handling
All scope names validated with pattern: ^[a-zA-Z0-9_-]{1,64}$
Includes comprehensive examples and maintains backwards compatibility

Test Plan

All 318 tests passing
New examples validate successfully (scope, waitUntil, terminateScope)
Generated schemas properly built and published
Pattern validation consistent across all schemas
No breaking changes to existing functionality

Summary by CodeRabbit

New Features
- Added scoped process management enabling persistent terminal and code sessions across steps
- Added wait conditions for commands to control execution flow based on stdout/stderr patterns
- Added terminate scope operation to explicitly end named processes and sessions
- Enhanced drag-and-drop action support for complex UI interactions
- Enabled superpowers marketplace plugin for extended platform capabilities

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add scope property for persistent terminal sessions and waitUntil property for condition-based waiting on stdout/stderr output. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add scope property for persistent code execution sessions and waitUntil property for condition-based waiting on stdout/stderr. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add scope property to allow typing into scoped terminal or code sessions for interactive command support. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add new action to terminate named scopes and their processes. Supports both simple string and detailed object formats. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add terminateScope to the list of available step actions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Update generated schemas with scope, waitUntil, and terminateScope. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

coderabbitai · 2026-01-06T19:08:15Z

Walkthrough

This PR introduces session and scope management across the schema definitions by adding a scope property to command and action objects, enabling commands to target named execution contexts. It creates a new terminateScope operation for managing named scope lifecycles and adds configuration files for development settings and permissions.

Changes

Cohort / File(s)	Summary
Configuration Setup `.claude/settings.json`, `.claude/settings.local.json`	Enables superpowers plugin and configures permissions for bash commands, git operations, and skill-based actions.
Schema Processing Pipeline `src/schemas/dereferenceSchemas.js`	Adds `terminateScope_v3.schema.json` to the list of v3 schema files processed for dereferencing and distribution.
New terminateScope Schemas `src/schemas/src_schemas/terminateScope_v3.schema.json`, `src/schemas/output_schemas/terminateScope_v3.schema.json`	Introduces new schema defining the terminateScope operation with simple (string) and detailed (object) variants, including pattern validation for scope names.
Command Execution Schemas `src/schemas/src_schemas/runShell_v3.schema.json`, `src/schemas/src_schemas/runCode_v3.schema.json`, `src/schemas/output_schemas/runShell_v3.schema.json`, `src/schemas/output_schemas/runCode_v3.schema.json`	Adds `scope` property (alphanumeric with hyphens/underscores, 1-64 chars) and `waitUntil` object with stdio pattern matching for stdout/stderr to enable persistent session management and condition-based step completion.
Interactive Input Schemas `src/schemas/src_schemas/type_v3.schema.json`, `src/schemas/output_schemas/type_v3.schema.json`, `src/schemas/output_schemas/find_v3.schema.json`	Adds `scope` property to enable typing/input operations on scoped terminal or code sessions rather than the browser context.
Step Definition Schemas `src/schemas/src_schemas/step_v3.schema.json`, `src/schemas/output_schemas/step_v3.schema.json`	Introduces `scope` and `waitUntil` properties across various step actions; adds new `terminateScope` step operation with supporting component schemas and examples.
Comprehensive Test/Report Schemas `src/schemas/output_schemas/config_v3.schema.json`, `src/schemas/output_schemas/spec_v3.schema.json`, `src/schemas/output_schemas/report_v3.schema.json`, `src/schemas/output_schemas/test_v3.schema.json`	Systematically adds `scope` property to multiple command objects (runShell, runCode, httpRequest, screenshot, cookie operations, etc.); report and test schemas also introduce `waitUntil` conditions, `dragAndDrop` configurations, and extended action type support for granular session and process control.
Minor Formatting `src/schemas/output_schemas/endRecord_v3.schema.json`	Whitespace-only formatting changes; no semantic modifications.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Implement Heretto CMS uploader for screenshot synchronization #149: Modifies src/schemas/dereferenceSchemas.js to add sourceIntegration_v3.schema.json to the schema pipeline, following the same pattern as the main PR's addition of terminateScope_v3.schema.json.
Publish schemas to distribution directory #117: Updates the schema dereferencing and publishing pipeline in src/schemas/dereferenceSchemas.js for v3 schema distribution, directly related to the scope property pipeline modifications.
Refactor httpRequest_v3.schema.json: Simplify schema definitions and enhance header/body descriptions #118: Modifies HTTP request schema definitions, overlapping with the main PR's addition of scope properties to httpRequest-related command objects.

Poem

🐰 A scope for each session, a name for each task,
Commands now targeted, no more to unmask.
From dev-server humming to logs in their place,
Persistent and scoped, they'll finish the race!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title "feat: add scope-based session management" accurately summarizes the main change—introducing scope-based functionality for persistent terminal/code session management across multiple schema actions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI Agents

In @.claude/settings.local.json:
- Around line 1-18: The file .claude/settings.local.json is developer-specific
and should not be tracked; add ".claude/settings.local.json" to .gitignore, run
git rm --cached .claude/settings.local.json to stop tracking it, add a template
.claude/settings.local.json.example (or update docs) that shows the expected
permissions format for local overrides, and ensure any shared configuration
remains in .claude/settings.json.

In @src/schemas/output_schemas/test_v3.schema.json:
- Around line 6667-6799: The terminateScope schema's "scope" description lacks a
defined SIGTERM→SIGKILL grace period; update the "scope" property description
inside the terminateScope anyOf object (and its counterpart in the
components.schemas.object) to state the exact behavior: either document the
fixed duration (e.g., "process will receive SIGTERM, followed by SIGKILL after X
seconds"), or indicate it's configurable and name the config key (e.g.,
"controlled by <configName>"), or add an optional property (e.g., "gracePeriod"
with type integer and seconds) to the terminateScope object variant; ensure both
the inline object (properties.scope) and the components.schemas.object.scope
description are updated and examples adjusted if you add a new property.

🧹 Nitpick comments (11)

src/schemas/src_schemas/step_v3.schema.json (1)
294-309: Add an example for the new terminateScope action type.

The schema properly integrates the new terminateScope action into the step definition (lines 294-309). However, the examples array lacks a demonstration of how to use this new action type, which is inconsistent with the pattern for other action types like find, click, and httpRequest.

Consider adding an example in the examples array to demonstrate terminateScope usage:
🔎 Suggested example for terminateScope
     {
       "dragAndDrop": {
         "source": {
           "selector": "#sourceElement"
         },
         "target": {
           "selector": "#targetElement"
         }
       }
     }
+  ],
+  "terminateScope": "session_name"
+}
Or, if your terminateScope_v3.schema.json has multiple examples, you can use $ref like the other complex actions:
   {
     "dragAndDrop": {
       "source": {
         "selector": "#sourceElement"
       },
       "target": {
         "selector": "#targetElement"
       }
     }
+  },
+  {
+    "terminateScope": {
+      "$ref": "terminateScope_v3.schema.json#/examples/0"
+    }
   }
 ]
src/schemas/output_schemas/runCode_v3.schema.json (1)
117-120: Consider adding additionalProperties: false for stricter validation.

The runShell_v3.schema.json schema includes "additionalProperties": false on the detailed object (line 19 and 136), but runCode_v3.schema.json lacks this constraint. For consistency and to prevent typos from silently passing validation, consider adding this restriction.
🔎 Proposed fix
       }
     },
+    "additionalProperties": false,
     "title": "Run code (detailed)"
   }
 ],
src/schemas/output_schemas/config_v3.schema.json (2)
4605-4626: Consider requiring at least one condition in waitUntil.stdio.

The waitUntil.stdio object allows both stdout and stderr to be omitted, making waitUntil: { stdio: {} } valid but meaningless. Consider adding a minProperties: 1 constraint to stdio or documenting that at least one pattern should be specified.

This would need to be addressed in the source schema (likely runShell_v3.schema.json).
🔎 Suggested schema refinement
 "stdio": {
   "type": "object",
   "description": "Standard I/O stream conditions to wait for.",
   "additionalProperties": false,
+  "minProperties": 1,
   "properties": {
     "stdout": {
6936-6942: Consider adding a configurable gracePeriod property.

The description mentions "SIGTERM, followed by SIGKILL after a grace period" but there's no way to configure this duration. For processes that need more time to shut down gracefully (e.g., database connections, file flushes), a configurable grace period would be useful.
🔎 Example enhancement for detailed form
 "properties": {
   "scope": {
     "type": "string",
     "description": "Name of the scope to terminate. The associated process will receive SIGTERM, followed by SIGKILL after a grace period if still running.",
     "pattern": "^[a-zA-Z0-9_-]{1,64}$"
+  },
+  "gracePeriod": {
+    "type": "integer",
+    "description": "Time in milliseconds to wait after SIGTERM before sending SIGKILL. Defaults to 5000ms.",
+    "default": 5000,
+    "minimum": 0
   }
 },
src/schemas/output_schemas/step_v3.schema.json (3)

1213-1218: Scope support for type/typeKeys is consistent; just watch browser vs terminal semantics

The new scope fields on the detailed typeKeys objects (for find.type and the type step) are wired consistently and reuse the same validation pattern and description as the shell/code scopes. That looks solid and keeps the schema shapes aligned.

One subtle point: the schema allows combining scope with element‑targeting fields (selector, elementText, etc.), even though those are browser concepts while scope routes input to a terminal/code session. If the runtime treats scope as taking precedence and ignores DOM targeting in that case, it might be worth tightening behavior or at least documenting that precedence to avoid confusion, but this isn’t a blocker from a schema perspective.

Also applies to: 1324-1330, 1876-1881, 1988-1993, 4582-4587, 4694-4699, 4731-4735

3811-3841: runShell/runCode scope and waitUntil wiring looks good; consider validating non‑empty conditions

The additions of scope and waitUntil.stdio.{stdout,stderr} to both runShell and runCode are internally consistent (main and components.schemas.object branches match, examples exercise the new behavior, and the scope pattern is uniform).

Right now waitUntil can be an empty object, or waitUntil: { stdio: {} }, which effectively does nothing but still “looks” configured. If you want to catch misconfigurations early, you could add a small constraint (e.g., an anyOf requiring at least one of stdout/stderr when stdio is present, or at least one known key under waitUntil). That would tighten feedback for users without changing the core design.

Also applies to: 3927-3958, 4013-4039, 4199-4229, 4317-4347, 4386-4406

6068-6200: New terminateScope step is well‑shaped; ensure it stays in sync with terminateScope_v3

The terminateScope step block follows the existing pattern (Common + action object), supports both simple string and detailed object forms, and uses the same scope name pattern and description as the other scoped actions. Including $schema here also matches the self‑describing schema convention for linting. Based on learnings, this is aligned with how other v3 action schemas are structured.

To avoid future drift, it would be helpful to double‑check that src/schemas/output_schemas/terminateScope_v3.schema.json (and any generator templates) define the exact same anyOf/pattern/description, or to have them generated from a single source of truth.

src/schemas/output_schemas/spec_v3.schema.json (2)

5020-5041: Consider requiring at least one condition when waitUntil is specified.

The waitUntil structure allows empty objects (e.g., waitUntil: {} or waitUntil: { stdio: {} }), which would be valid but semantically meaningless. If the intent is that specifying waitUntil should always include at least one condition, consider adding validation.

For example, you could require at least one of stdout or stderr when stdio is present, or require stdio when waitUntil is present.

7361-7385: Consider removing redundant components.schemas duplication.

The components.schemas section (lines 7361-7385) duplicates the schema definitions already present in the anyOf array above. This duplication could lead to maintenance issues if the schemas diverge.

If this is auto-generated for OpenAPI compatibility or tooling purposes, you may safely ignore this observation. Otherwise, consider whether this duplication serves a necessary purpose.
src/schemas/output_schemas/report_v3.schema.json (2)
5038-5059: Consider requiring at least one stdio condition in waitUntil.

The waitUntil.stdio object allows both stdout and stderr to be optional, meaning waitUntil: { stdio: {} } is schema-valid but functionally meaningless. Consider adding a minProperties: 1 constraint to the stdio object or using a oneOf/anyOf to require at least one pattern.

This is a minor edge case and may be acceptable if validation is handled at runtime.
Suggested schema constraint
                                              "stdio": {
                                                "type": "object",
                                                "description": "Standard I/O stream conditions to wait for.",
                                                "additionalProperties": false,
+                                               "minProperties": 1,
                                                "properties": {
7379-7402: components.schemas section duplicates the anyOf definitions.

The terminateScope schema contains a components.schemas section (lines 7379-7402) that duplicates the type definitions already present in the anyOf array. This OpenAPI-style embedding is unusual for pure JSON Schema.

If this duplication is intentional for documentation tooling or external consumers, it's fine. Otherwise, consider removing it to reduce maintenance burden and file size.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8c9891d and 51f9925.

⛔ Files ignored due to path filters (11)

dist/schemas/config_v3.schema.json is excluded by !**/dist/**
dist/schemas/find_v3.schema.json is excluded by !**/dist/**
dist/schemas/report_v3.schema.json is excluded by !**/dist/**
dist/schemas/resolvedTests_v3.schema.json is excluded by !**/dist/**
dist/schemas/runCode_v3.schema.json is excluded by !**/dist/**
dist/schemas/runShell_v3.schema.json is excluded by !**/dist/**
dist/schemas/spec_v3.schema.json is excluded by !**/dist/**
dist/schemas/step_v3.schema.json is excluded by !**/dist/**
dist/schemas/terminateScope_v3.schema.json is excluded by !**/dist/**
dist/schemas/test_v3.schema.json is excluded by !**/dist/**
dist/schemas/type_v3.schema.json is excluded by !**/dist/**

📒 Files selected for processing (21)

.claude/settings.json
.claude/settings.local.json
src/schemas/dereferenceSchemas.js
src/schemas/output_schemas/config_v3.schema.json
src/schemas/output_schemas/endRecord_v3.schema.json
src/schemas/output_schemas/find_v3.schema.json
src/schemas/output_schemas/report_v3.schema.json
src/schemas/output_schemas/resolvedTests_v3.schema.json
src/schemas/output_schemas/runCode_v3.schema.json
src/schemas/output_schemas/runShell_v3.schema.json
src/schemas/output_schemas/spec_v3.schema.json
src/schemas/output_schemas/step_v3.schema.json
src/schemas/output_schemas/terminateScope_v3.schema.json
src/schemas/output_schemas/test_v3.schema.json
src/schemas/output_schemas/type_v3.schema.json
src/schemas/schemas.json
src/schemas/src_schemas/runCode_v3.schema.json
src/schemas/src_schemas/runShell_v3.schema.json
src/schemas/src_schemas/step_v3.schema.json
src/schemas/src_schemas/terminateScope_v3.schema.json
src/schemas/src_schemas/type_v3.schema.json

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{js,ts}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{js,ts}: Always clone objects using JSON.parse(JSON.stringify(object)) before validation to avoid mutations
validate() returns { valid, errors, object } and never throws; handle errors via return object
transformToSchemaKey() throws on incompatible schemas or invalid results; catch exceptions when calling this function
readFile() returns null on errors and logs warnings to console; do not assume errors throw exceptions
resolvePaths() throws on invalid object types or missing nested object types; validate inputs before calling
Do not assume validation mutates objects; always handle the returned validated object

Files:

src/schemas/dereferenceSchemas.js

src/**/*.js

📄 CodeRabbit inference engine (AGENTS.md)

Use escapeRegExp() helper when converting user strings to regex patterns in transformToSchemaKey()

Files:

src/schemas/dereferenceSchemas.js

src/schemas/src_schemas/*.json

📄 CodeRabbit inference engine (AGENTS.md)

src/schemas/src_schemas/*.json: Always include examples array in all schemas (required for test generation)
In source schemas, use relative $ref paths like "$ref": "context_v3.schema.json#/properties/example"

Files:

src/schemas/src_schemas/type_v3.schema.json
src/schemas/src_schemas/step_v3.schema.json
src/schemas/src_schemas/runShell_v3.schema.json
src/schemas/src_schemas/terminateScope_v3.schema.json
src/schemas/src_schemas/runCode_v3.schema.json

🧠 Learnings (12)

📚 Learning: 2025-08-22T20:01:21.087Z

Learnt from: hawkeyexl
Repo: doc-detective/common PR: 134
File: src/schemas/output_schemas/report_v3.schema.json:5695-5921
Timestamp: 2025-08-22T20:01:21.087Z
Learning: The report_v3.schema.json includes dragAndDrop via inclusion in the spec schema, which includes the test and step schemas, creating a chain of schema inclusions.

Applied to files:

src/schemas/output_schemas/report_v3.schema.json
src/schemas/dereferenceSchemas.js
src/schemas/src_schemas/step_v3.schema.json
src/schemas/output_schemas/spec_v3.schema.json
src/schemas/output_schemas/test_v3.schema.json

📚 Learning: 2025-05-29T16:54:47.192Z

Learnt from: hawkeyexl
Repo: doc-detective/common PR: 117
File: src/schemas/output_schemas/resolvedTests_v3.schema.json:24-30
Timestamp: 2025-05-29T16:54:47.192Z
Learning: In doc-detective/common schemas, `$schema` properties within object definitions are intentionally added to allow described JSON objects to be self-describing for linting purposes. This enables JSON linters and validators to automatically validate objects against the referenced schema. The version information is embedded in the filename using the pattern `<schema>_v3.schema.json`.

Applied to files:

src/schemas/output_schemas/report_v3.schema.json
src/schemas/dereferenceSchemas.js
src/schemas/src_schemas/type_v3.schema.json
src/schemas/src_schemas/step_v3.schema.json
src/schemas/output_schemas/type_v3.schema.json
src/schemas/src_schemas/runShell_v3.schema.json
src/schemas/src_schemas/terminateScope_v3.schema.json
src/schemas/output_schemas/config_v3.schema.json
src/schemas/output_schemas/endRecord_v3.schema.json
src/schemas/output_schemas/terminateScope_v3.schema.json
src/schemas/output_schemas/spec_v3.schema.json
src/schemas/output_schemas/test_v3.schema.json
src/schemas/output_schemas/runShell_v3.schema.json
src/schemas/output_schemas/runCode_v3.schema.json
src/schemas/output_schemas/step_v3.schema.json
src/schemas/src_schemas/runCode_v3.schema.json
src/schemas/output_schemas/find_v3.schema.json

📚 Learning: 2025-08-22T20:01:21.087Z

Learnt from: hawkeyexl
Repo: doc-detective/common PR: 134
File: src/schemas/output_schemas/report_v3.schema.json:5695-5921
Timestamp: 2025-08-22T20:01:21.087Z
Learning: In the doc-detective/common project, dragAndDrop schema doesn't need to be explicitly added to report_v3.schema.json because all schemas in schema.json are dynamically loaded and dragAndDrop is included through that mechanism.

Applied to files:

src/schemas/output_schemas/report_v3.schema.json