parse-stack-next 5.5.4 → 5.5.6

data/docs/TEST_SERVER.md

@@ -1,271 +1,148 @@
 # Parse Stack Test Server Setup
 
-This document explains how to set up a local Parse Server for testing the parse-stack Ruby SDK.
+This document explains how to run the local, isolated Parse Server stack used
+to exercise the parse-stack-next Ruby SDK's integration suite.
+
+The stack is namespaced so it never collides with another Parse test system on
+the same machine: a dedicated Compose project, a private `29xxx` host-port
+block, dedicated container/volume names (`psnext-it-*`), loopback-only port
+binds by default, and a dedicated database.
 
 ## Quick Start
 
-### Option 1: Using Make (Recommended)
+### Option 1: Using Make
 
 ```bash
-# Start the test server
-make test-server-start
-
-# Test the connection
-make test-connection
-
-# Run integration tests
-make test-integration
-
-# Stop the test server
-make test-server-stop
+make test-server-start   # bring up the stack
+make test-connection     # verify connectivity
+make test-integration    # run the integration suite
+make test-server-stop    # tear the stack down
 ```
 
-### Option 2: Docker Compose
+### Option 2: Docker Compose directly
 
-1. **Start the test server:**
-   ```bash
-   docker-compose -f docker-compose.test.yml up -d
-   ```
+```bash
+# Start
+docker-compose -f scripts/docker/docker-compose.test.yml up -d
 
-2. **Test the connection:**
-   ```bash
-   ruby test_server_connection.rb
-   ```
+# Verify Parse Server is healthy
+curl http://localhost:29337/parse/health   # => {"status":"ok"}
 
-3. **Run integration tests:**
-   ```bash
-   PARSE_TEST_USE_DOCKER=true bundle exec rake test
-   ```
+# Run integration tests
+PARSE_TEST_USE_DOCKER=true bundle exec rake test:integration
 
-4. **Stop the test server:**
-   ```bash
-   docker-compose -f docker-compose.test.yml down
-   ```
+# Stop
+docker-compose -f scripts/docker/docker-compose.test.yml down
+```
 
-### Option 3: Use Your Own Parse Server
+### Option 3: Use your own Parse Server
 
-Set environment variables to point to your Parse Server:
+Point the suite at any Parse Server by exporting the client-side variables:
 
 ```bash
 export PARSE_TEST_SERVER_URL="http://your-server:1337/parse"
 export PARSE_TEST_APP_ID="your-app-id"
-export PARSE_TEST_API_KEY="your-rest-key"  
+export PARSE_TEST_API_KEY="your-rest-key"
 export PARSE_TEST_MASTER_KEY="your-master-key"
 ```
 
-## Services Included
-
-The Docker Compose setup provides:
-
-- **MongoDB** (port 27017): Database backend
-- **Parse Server** (port 1337): Main API server with custom startup script
-- **Parse Dashboard** (port 4040): Web interface for data management
-
-## Technical Implementation
-
-### Custom Parse Server Image
-
-The setup uses a custom Docker image built on top of `parseplatform/parse-server:8.2.3` that includes:
-
-- **Custom startup script** (`scripts/start-parse.sh`) that sets the `PARSE_SERVER_MASTER_KEY_IPS` environment variable
-- **IP restriction bypass** allowing requests from any IP address (`0.0.0.0/0,::/0`)
-- **Automatic environment variable setup** for proper master key authentication
-
-### Master Key Authentication
-
-The setup resolves Parse Server's IP restriction for master key usage by:
-
-1. Using a custom Docker image with an embedded startup script
-2. Setting `PARSE_SERVER_MASTER_KEY_IPS=0.0.0.0/0,::/0` to allow all IP addresses
-3. This enables schema operations and full master key functionality for testing
-
-### File Structure
-
-```
-parse-stack-next/
-├── scripts/
-│   ├── docker/
-│   │   ├── docker-compose.test.yml # Main Docker Compose configuration
-│   │   └── Dockerfile.parse       # Custom Parse Server image
-│   ├── start-parse.sh             # Startup script with environment setup
-│   └── test_server_connection.rb  # Connection test script
-├── config/
-│   └── parse-config.json    # Parse Server configuration (unused)
-├── test/
-│   ├── cloud/
-│   │   └── main.js         # Cloud Code for testing
-│   └── support/
-│       ├── test_server.rb   # Ruby test helper utilities
-│       └── docker_helper.rb # Docker container management
-└── .env.test              # Environment variable defaults
-```
-
-## Test Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PARSE_TEST_SERVER_URL` | `http://localhost:1337/parse` | Parse Server URL |
-| `PARSE_TEST_APP_ID` | `myAppId` | Application ID |
-| `PARSE_TEST_API_KEY` | `test-rest-key` | REST API Key |
-| `PARSE_TEST_MASTER_KEY` | `myMasterKey` | Master Key |
-| `PARSE_TEST_USE_DOCKER` | `false` | Auto-manage Docker containers |
-| `PARSE_TEST_AUTO_START` | `false` | Start containers automatically |
-| `PARSE_TEST_AUTO_STOP` | `false` | Stop containers on exit |
-
-### Using `.env.test`
-
-Copy and customize the test environment file:
-
-```bash
-cp .env.test .env.test.local
-# Edit .env.test.local with your settings
-```
-
-## Writing Integration Tests
-
-### Basic Setup
-
-```ruby
-require_relative 'test_helper_integration'
-
-class MyIntegrationTest < Minitest::Test
-  include ParseStackIntegrationTest
-  
-  def test_user_creation
-    with_parse_server do
-      user = create_test_user(username: 'testuser')
-      assert user.id.present?
-      assert_equal 'testuser', user.username
-    end
-  end
-end
-```
-
-### Test Helpers Available
-
-- `with_parse_server { }` - Skip test if server unavailable
-- `create_test_user(attributes)` - Create and track test user
-- `create_test_object(class_name, attributes)` - Create and track test object
-- `reset_database!` - Clear all non-system data
-- `@test_context.track(object)` - Track object for cleanup
-
-### Manual Server Management
-
-```ruby
-# In your tests or console
-require 'test/support/docker_helper'
-
-# Start containers
-Parse::Test::DockerHelper.start!
-
-# Check if running
-Parse::Test::DockerHelper.running?
-
-# View logs
-puts Parse::Test::DockerHelper.logs
-
-# Stop containers
-Parse::Test::DockerHelper.stop!
-```
-
-## Dashboard Access
-
-When using Docker Compose, you can access the Parse Dashboard at:
-- URL: http://localhost:4040
-- Username: `admin`
-- Password: `admin`
-
-## Cloud Code Testing
-
-Sample cloud functions are provided in `test/cloud/main.js`:
-
-```ruby
-# Test cloud functions
-result = Parse::CloudFunction.call('hello', name: 'World')
-assert_equal 'Hello World!', result
-```
+## Services and ports
+
+Every value has a baked-in default, so the stack is isolated even with no env
+file present. Host ports live in the `29xxx` block and bind to `127.0.0.1` by
+default.
+
+| Service         | Host port | Override            | Container             |
+|-----------------|-----------|---------------------|-----------------------|
+| Parse Server    | 29337     | `PARSE_HOST_PORT`   | `psnext-it-server`    |
+| MongoDB         | 29017     | `MONGO_HOST_PORT`   | `psnext-it-mongo`     |
+| Redis           | 29379     | `REDIS_HOST_PORT`   | `psnext-it-redis`     |
+| Parse Dashboard | 29040     | `DASHBOARD_HOST_PORT` | `psnext-it-dashboard` |
+
+- **`PSNEXT_PREFIX`** (default `psnext-it`) names the Compose project and every
+  container. Set it (e.g. `PSNEXT_PREFIX=psnext-ci`) to run a second, fully
+  separate copy.
+- **Versions**: Parse Server is pinned to `parseplatform/parse-server:9.9.0`
+  (see `scripts/docker/Dockerfile.parse`), MongoDB `mongo:8`, Redis
+  `redis:7-alpine`, Dashboard `parseplatform/parse-dashboard:9`.
+- **Database**: Parse uses `parse_stack_next_it`.
+
+## Credentials (compose defaults)
+
+| Setting     | Default             | Compose env             |
+|-------------|---------------------|-------------------------|
+| App ID      | `psnextItAppId`     | `PARSE_APP_ID`          |
+| Master key  | `psnextItMasterKey` | `PARSE_MASTER_KEY`      |
+| REST key    | `psnext-it-rest-key`| `PARSE_API_KEY`         |
+
+These defaults are intentionally non-secret — they only ever bind to loopback.
+Supply real values (and non-loopback binds) via your shell or a secret manager
+if you point the stack at anything shared.
+
+## Security posture (not an anti-pattern)
+
+The stack is hardened by construction, not opened up:
+
+- **Loopback binds by default** — `PARSE_BIND` / `MONGO_BIND` / `REDIS_BIND` /
+  `DASHBOARD_BIND` all default to `127.0.0.1`, so nothing is published on the
+  LAN unless you explicitly override a bind.
+- **Scoped master-key IPs** — Parse Server's `masterKeyIps` is set to loopback
+  plus the private Docker ranges
+  (`127.0.0.1/32,::1/128,172.16.0.0/12,192.168.0.0/16,10.0.0.0/8`) so the
+  Ruby suite and the Dashboard container can use the master key, but it is
+  **not** opened to `0.0.0.0/0`.
+- **Preflight guard** — a `preflight` service (`scripts/docker/preflight.sh`)
+  gates startup and refuses to bring the stack up on a non-loopback bind while
+  still using the default credentials, unless `ALLOW_INSECURE_BIND=1` or real
+  `PARSE_MASTER_KEY` / `MONGO_ROOT_PASSWORD` values are supplied.
+
+## Client-side test variables
+
+The Ruby suite reads these (all have `29xxx` / `psnext-it` defaults):
+
+| Variable                 | Purpose                              |
+|--------------------------|--------------------------------------|
+| `PARSE_TEST_SERVER_URL`  | Parse Server URL (`http://localhost:29337/parse`) |
+| `PARSE_TEST_APP_ID`      | Application ID                       |
+| `PARSE_TEST_API_KEY`     | REST API key                         |
+| `PARSE_TEST_MASTER_KEY`  | Master key                           |
+| `PARSE_TEST_MONGO_URI`   | Mongo URI for mongo-direct tests     |
+| `PARSE_TEST_REDIS_URL`   | Redis URL                            |
+| `PARSE_TEST_LIVE_QUERY_URL` | LiveQuery WebSocket URL           |
+| `PARSE_TEST_USE_DOCKER`  | Auto-manage the Docker stack         |
+
+`.env.test` is a committed reference listing the whole set;
+`set -a; source .env.test; set +a` loads them all at once. Nothing auto-loads
+it — the baked-in defaults apply otherwise.
+
+## Dashboard
+
+With the stack up, the Parse Dashboard is at <http://localhost:29040>.
 
 ## Troubleshooting
 
-### Docker Issues
-
 ```bash
-# Check container status
-docker-compose -f docker-compose.test.yml ps
-
-# View Parse Server logs
-docker logs parse-stack-test-server
-
-# Reset everything
-docker-compose -f docker-compose.test.yml down -v
-docker-compose -f docker-compose.test.yml up -d
-```
-
-### Master Key Authentication Issues
-
-If you see `Request using master key rejected as the request IP address ... is not set in Parse Server option 'masterKeyIps'`:
-
-1. **Verify the custom image is built**: 
-   ```bash
-   docker-compose -f docker-compose.test.yml build parse
-   ```
-
-2. **Check startup script execution**:
-   ```bash
-   docker logs parse-stack-test-server | grep "PARSE_SERVER_MASTER_KEY_IPS"
-   ```
-   Should show: `PARSE_SERVER_MASTER_KEY_IPS: 0.0.0.0/0,::/0`
+# Container status
+docker-compose -f scripts/docker/docker-compose.test.yml ps
 
-3. **Test master key directly**:
-   ```bash
-   curl -X GET \
-     -H "X-Parse-Application-Id: myAppId" \
-     -H "X-Parse-Master-Key: myMasterKey" \
-     http://localhost:1337/parse/schemas
-   ```
+# Parse Server logs
+docker logs psnext-it-server
 
-### Connection Issues
-
-```ruby
-# Test connectivity in console
-require 'test/support/test_server'
-Parse::Test::ServerHelper.setup
-Parse::Test::ServerHelper.server_available?
-```
-
-### Port Conflicts
-
-If ports 1337, 4040, or 27017 are in use, modify `docker-compose.test.yml`:
-
-```yaml
-services:
-  parse:
-    ports:
-      - "1338:1337"  # Use port 1338 instead
+# Full reset (clears volumes)
+docker-compose -f scripts/docker/docker-compose.test.yml down -v
+docker-compose -f scripts/docker/docker-compose.test.yml up -d
 ```
 
-Then update your environment variables accordingly.
-
-## Production vs Test Differences
-
-The test server configuration includes:
-- Relaxed security settings for testing
-- Auto-creation of classes
-- Verbose logging
-- Sample cloud code
-
-**Never use these settings in production!**
+### Master-key IP rejection
 
-## Status
+If you see `Request using master key rejected as the request IP address ... is
+not set in Parse Server option 'masterKeyIps'`, your client is reaching the
+server from an address outside the scoped `masterKeyIps` list above. Run the
+suite from the host (loopback) or from within the Docker network, rather than
+widening `masterKeyIps`.
 
-✅ **Working Setup**: This test server configuration has been verified to work with:
-- Parse Server 8.2.3
-- MongoDB 5.0  
-- Master key authentication for schema operations
-- Basic CRUD operations via REST API
-- Ruby Parse Stack SDK connection
-- Cloud Code execution
+### Port conflicts
 
-The setup successfully resolves Parse Server's IP restriction issues that typically prevent master key usage in Docker environments.
+Every host port is overridable via the `*_HOST_PORT` variables in the table
+above (and the matching `PARSE_TEST_*` client variable). Move both the compose
+side and the client side together so the containers and the suite agree.

data/docs/mcp_guide.md

@@ -3844,7 +3844,7 @@ Tenant scope is applied as a `$match` stage at the TOP-level pipeline only. Sub-
 2. **Refuse lookups from tenant-bound agents entirely** — application code rejects pipelines containing `$lookup` / `$graphLookup` / `$unionWith` when `agent.tenant_id` is set.
 3. **Mark joinable cross-tenant classes as `agent_hidden`** — the most permissive joining-class is unreachable to the agent.
 
-The proper fix (recursive scope injection into sub-pipelines) is tracked as a follow-up; see [SECURITY_GUIDE.md](../SECURITY_GUIDE.md) for the threat model and posture recommendations.
+The proper fix (recursive scope injection into sub-pipelines) is tracked as a follow-up; see [acl_clp_guide.md](./acl_clp_guide.md) and [SECURITY.md](../SECURITY.md) for the threat model and posture recommendations.
 
 ---
 

data/docs/mongodb_index_optimization_guide.md

@@ -645,8 +645,9 @@ explicit mappings are correct for production.
 - [mongodb_direct_guide.md](./mongodb_direct_guide.md) — the full
   direct-Mongo / index-management API reference (DSL spelling,
   writer URI, triple-gate, rake tasks)
-- [SECURITY_GUIDE.md](../SECURITY_GUIDE.md) — security posture around
-  the writer URI, role validation, audit trail
+- [acl_clp_guide.md](./acl_clp_guide.md) — security posture around
+  the writer URI, role validation, and ACL/CLP enforcement on the
+  mongo-direct path
 - MongoDB official: <https://www.mongodb.com/docs/manual/indexes/>
 - Parse Server source for auto-managed indexes:
   <https://github.com/parse-community/parse-server/blob/master/src/Adapters/Storage/Mongo/MongoStorageAdapter.js>

data/docs/usage_guide.md

@@ -626,6 +626,6 @@ end
 
 ## More Information
 
-- [CHANGELOG](./CHANGELOG.md) - Full feature history
+- [CHANGELOG](../CHANGELOG.md) - Full feature history
 - [GitHub Releases](https://github.com/neurosynq/parse-stack-next/releases) - Release notes
 - [Parse Server Docs](https://docs.parseplatform.org) - Parse Server documentation

data/docs/yard-template/default/fulldoc/html/css/common.css

@@ -438,17 +438,38 @@ input[name=q]::placeholder {
   margin-top: 1.4em;
 }
 
-#listing ul.alpha li.letter h2 {
+/* YARD emits the section letters as bare `<li class="letter">A</li>`
+ * (no inner h2), so style the li itself. */
+#listing ul.alpha li.letter {
   color: var(--accent);
-  border-bottom: 2px solid var(--accent);
-  display: inline-block;
-  padding: 0 .8em .2em 0;
+  font-weight: 650;
 }
 
 #listing ul li a {
   border-bottom: 1px dotted var(--border);
 }
 
+/* The "(Parse::Constraint)" origin annotations; stock #666 is too dim
+ * against the dark surfaces. */
+#listing ul small {
+  color: var(--fg-muted);
+}
+
+/* Stock style.css stripes index rows with hardcoded light grays
+ * (li.r1 #f0f0f0 / li.r2 #fafafa) that glow white in dark mode. */
+li.r1 { background: var(--bg-soft); }
+li.r2 { background: var(--bg); }
+
+/* File Listing pills at the top of _index.html. */
+.index_inline_list li,
+.index_inline_list li.r1,
+.index_inline_list li.r2 {
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  margin-right: 6px;
+}
+
 /* -------- inheritance / mixin lists -------- */
 
 dl.box {
@@ -892,9 +913,13 @@ h2.h2_sum,
 
 /* The collapse arrows in the class-tree iframe are a base64 PNG
  * sprite of dark glyphs on a transparent background — invisible
- * against our dark surface. CSS filter inverts them in place. */
-#full_list li a.toggle {
-  filter: invert(0.85) hue-rotate(180deg) brightness(1.6);
+ * against our dark surface. CSS filter inverts them in place.
+ * Dark mode only: in light mode the stock dark glyphs are correct,
+ * and inverting them would wash them out against the light rail. */
+@media (prefers-color-scheme: dark) {
+  #full_list li a.toggle {
+    filter: invert(0.85) hue-rotate(180deg) brightness(1.6);
+  }
 }
 
 /* ============================================================
@@ -928,11 +953,29 @@ h2.h2_sum,
   padding: 1px 6px !important;
 }
 
-/* But never on the code blocks themselves (the pre.code descendants). */
+/* But never on the code blocks themselves (the pre.code descendants).
+ * The scoped variants are required, not belt-and-braces: file pages
+ * (README + guides) compile fenced blocks to <pre><code class="ruby">,
+ * and with both rules !important the positive `#filecontents code`
+ * (0,1,0,1) would otherwise beat a bare `pre code` (0,0,0,2) — the
+ * inline-level <code> then draws its border on every wrapped line
+ * fragment, streaking the whole block. */
 pre code,
 pre tt,
 pre.code code,
-pre.code tt {
+pre.code tt,
+.docstring pre code,
+.docstring pre tt,
+.tags pre code,
+.tags pre tt,
+.summary pre code,
+.summary pre tt,
+#filecontents pre code,
+#filecontents pre tt,
+.discussion pre code,
+.discussion pre tt,
+.method_details pre code,
+.method_details pre tt {
   background: transparent !important;
   border: 0 !important;
   padding: 0 !important;

data/docs/yard-template/default/fulldoc/html/css/full_list.css

@@ -209,19 +209,43 @@ a:visited {
  * parse-stack-next overlay (sidebar / class-list iframe)
  * ============================================================ */
 
+/* Scheme-aware palette. Light is the default; the dark block below
+ * mirrors common.css's prefers-color-scheme handling. Keeping the
+ * overlay unconditional (as it originally was) made the rail
+ * unreadable in light mode: common.css paints #full_list with the
+ * light surface while these rules kept the near-white dark-mode
+ * text (its `#full_list li .item a` selector out-specifies
+ * common.css's `#full_list li a` regardless of load order). */
 :root {
-	--ps-bg:        #1E1F22;
-	--ps-bg-soft:   #2A2C30;
-	--ps-bg-hover:  #34373C;
-	--ps-fg:        #E6E8EB;
-	--ps-fg-muted:  #9CA3AF;
-	--ps-accent:    #E63946;
-	--ps-link:      #4FB8F4;
-	--ps-border:    #3A3D42;
+	--ps-bg:        #FFFFFF;
+	--ps-bg-soft:   #F8F9FA;
+	--ps-bg-hover:  #E8EAED;
+	--ps-fg:        #1F2328;
+	--ps-fg-muted:  #6B7280;
+	--ps-accent:    #B22234;
+	--ps-link:      #169CEE;
+	--ps-border:    #E5E7EB;
+	--ps-scroll-thumb: #C7CBD1;
+	--ps-header-shadow: 0 1px 3px rgba(0, 0, 0, .08);
 	--ps-font:      -apple-system, BlinkMacSystemFont, "Segoe UI", "Inter",
 	                Roboto, "Helvetica Neue", Arial, sans-serif;
 }
 
+@media (prefers-color-scheme: dark) {
+	:root {
+		--ps-bg:        #1E1F22;
+		--ps-bg-soft:   #2A2C30;
+		--ps-bg-hover:  #34373C;
+		--ps-fg:        #E6E8EB;
+		--ps-fg-muted:  #9CA3AF;
+		--ps-accent:    #E63946;
+		--ps-link:      #4FB8F4;
+		--ps-border:    #3A3D42;
+		--ps-scroll-thumb: #4a4d52;
+		--ps-header-shadow: 0 1px 3px rgba(0, 0, 0, .3);
+	}
+}
+
 body {
 	background: var(--ps-bg) !important;
 	color: var(--ps-fg);
@@ -238,7 +262,7 @@ h1 {
 .fixed_header {
 	background: var(--ps-bg-soft) !important;
 	border-bottom: 1px solid var(--ps-border);
-	box-shadow: 0 1px 3px rgba(0, 0, 0, .3);
+	box-shadow: var(--ps-header-shadow);
 }
 
 #search input,
@@ -299,7 +323,7 @@ h1 {
 
 ::-webkit-scrollbar          { width: 8px; height: 8px; }
 ::-webkit-scrollbar-track    { background: var(--ps-bg); }
-::-webkit-scrollbar-thumb    { background: #4a4d52; border-radius: 4px; }
+::-webkit-scrollbar-thumb    { background: var(--ps-scroll-thumb); border-radius: 4px; }
 ::-webkit-scrollbar-thumb:hover { background: var(--ps-link); }
 
 /* ============================================================
@@ -381,7 +405,10 @@ body > #content {
 }
 
 /* The collapse toggle PNG is a dark-on-transparent sprite; invert it
- * so the arrow shows on dark backgrounds. */
-#full_list li a.toggle {
-	filter: invert(0.85) hue-rotate(180deg) brightness(1.6);
+ * so the arrow shows on dark backgrounds. Dark mode only — in light
+ * mode the stock dark glyphs are already correct. */
+@media (prefers-color-scheme: dark) {
+	#full_list li a.toggle {
+		filter: invert(0.85) hue-rotate(180deg) brightness(1.6);
+	}
 }