feat(layout): forest layout patch — apply targeted changes without pull

[Gawtier]

Summary

• Adds forest layout patch — a new command that sends a JSON-Patch array directly to an environment without requiring a pull first
• Removes add /folders/- from the whitelist (server rejects it with a business rule error; the correct path is /folders/<mainId>/children/-)

Motivation

The existing pull → diff → apply cycle always fetches the full layout before writing. For the forest-layout AI skill, this is unnecessary for pure creation: adding a workspace, a workflow shell, or a dashboard doesn't require knowing the current state. This command exposes the underlying PATCH /api/:domain endpoint directly.

Usage

# From a file
forest layout patch ops.json --env Production --team Operations

# From stdin
echo '{"layout":[{"op":"add","path":"/workspaces/-","value":{...}}]}' \
  | forest layout patch --env Production

# Dry-run (validate + display, no network call)
forest layout patch ops.json --env Production --dry-run

Input format — a JSON object keyed by domain:

{
  "layout":    [{ "op": "add",     "path": "/workspaces/-",                 "value": {...} }],
  "workflows": [{ "op": "replace", "path": "/workflows/<id>/isVisible",     "value": false }],
  "folders":   [{ "op": "add",     "path": "/folders/<mainId>/children/-",  "value": {...} }]
}

Behaviours

• Whitelist validation before any network call — catches bad paths early with a clear error
• Sequential atomic PATCHes per domain (layout → folders → workflows), consistent with apply
• Error scoped to the failing domain — explainApiError receives only the ops for the domain that failed, so path correlation is accurate
• TTY detection — clear usage error when stdin is interactive and no file is given
• --dry-run — prints ops without sending (scope resolution is also skipped)

/folders/- whitelist removal

Validated against the deployed server: add /folders/- is always rejected with "Cannot create a folder without adding it to the main folder". The correct path is /folders/<mainId>/children/-. Removing the entry from the whitelist surfaces this constraint as a client-side error before sending anything.

Testing

Validated live against BaaSDemo/Development:

• Collection scalar edits (displayName, icon, columns)
• Workspace creation with cross-referencing components (selectARecord + sourceWorkspaceComponentId)
• Workflow shell creation
• Sections replace
• Folder child add
• Segment add (premium scopes)
• Inbox add (premium inbox)
• Dashboard + chart add (premium multipleDashboards)
• Multi-domain patch (layout + workflows in one call)

Fixes PRD-592

Note

Add forest layout pull, diff, and apply commands for targeted layout patching

• Introduces three new CLI commands under forest layout: pull fetches the live rendering and writes a forest-layout.yml; diff shows what changes would be applied; apply computes a JSON-Patch plan and pushes it to the target environment/team without a full pull.
• Adds a BPMN compilation pipeline (workflow-bpmn.ts) that converts declarative workflow step graphs to BPMN XML, compares against stored S3 artifacts, and uploads only changed versions.
• Implements a rule-driven diff engine (diff.ts, patch-rules.ts) that produces validated, ordered JSON-Patch operations per domain (layout, folders, workflows) and pre-validates ops against a server whitelist.
• Adds scope resolution (scope-resolver.ts) with default-selection logic (development environment, Operations team) and a ScopeError for actionable failures.
• Adds YAML (de)serialization (yaml-file.ts) with a structured forest header and tolerant parsing, using the new yaml dependency.
• Risk: apply sends atomic per-domain PATCH requests to the server; a mid-run failure leaves domains applied up to the failure point with no rollback.

📊 Macroscope summarized 36db700. 15 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[linear-code]

PRD-592

PRD-555

[macroscopeapp]

🟢 Low layout/errors.ts:29

first.detail throws a TypeError when parsed.errors[0] is null or undefined, causing malformed API responses to crash the error handler instead of returning a detail string. Consider using optional chaining (first?.detail and first?.message) to fall back to JSON.stringify(body).

Suggested change

	return first.detail || first.message || JSON.stringify(body);
	return first?.detail || first?.message || JSON.stringify(body);

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/services/layout/errors.ts around line 29:

`first.detail` throws a `TypeError` when `parsed.errors[0]` is `null` or `undefined`, causing malformed API responses to crash the error handler instead of returning a detail string. Consider using optional chaining (`first?.detail` and `first?.message`) to fall back to `JSON.stringify(body)`.

Evidence trail:
src/services/layout/errors.ts lines 20-36 at REVIEWED_COMMIT: `extractDetail(body: unknown)` casts body to a typed shape without runtime validation. Line 26 checks `Array.isArray(parsed.errors) && parsed.errors.length > 0` but doesn't guard against nullish array elements. Line 27 `const first = parsed.errors[0]` can be null/undefined for inputs like `{errors: [null]}`. Line 29 `first.detail` would throw TypeError. The function is called from `toLayoutApiError` (line 47) with `body` sourced from HTTP response bodies (`superagentError.response?.body`), making the trigger condition reachable with malformed API responses.