n8n-nodes-orbitpage 0.3.2 → 0.3.3

package/docs/guides/development-and-release.md

@@ -23,27 +23,47 @@ Git. The published npm package includes the built `dist/` output.
 
 ## Development setup
 
-Use Node.js 22.22 or newer for package development:
+Use Node.js 24 for the full development toolchain:
 
 ```bash
 npm ci
 npm run dev
 ```
 
+The package still supports Node.js 22.22 and CI checks both runtime versions.
+The workflow SDK's native `isolated-vm` dependency requires Node.js 24, so
+`npm ci --engine-strict` fails on Node.js 22. Passing the node's loading and
+behavioral tests on Node.js 22 does not validate that native expression engine.
+
+The development command links this checkout into an isolated n8n user folder,
+builds the package, watches TypeScript, and starts n8n with live reload. Use
+`npm run dev -- --external-n8n` with a separately managed n8n instance, or
+`--custom-user-folder <directory>` to select its user folder. An existing link
+to another checkout is rejected rather than overwritten.
+
 Useful commands:
 
 | Command | Purpose |
 | --- | --- |
 | `npm run lint` | Run the official n8n node lint rules |
-| `npm run build` | Build the package through `n8n-node` |
+| `npm run build` | Clean `dist`, compile TypeScript, and copy node assets and metadata |
 | `npm run load:check` | Load published node and credential classes in an isolated n8n-style runtime |
 | `npm run docs:generate` | Regenerate the operation matrix from the built typed catalog |
 | `npm run docs:check` | Fail if the checked-in operation matrix is stale |
 | `npm test` | Run the Vitest suite |
 | `npm run check` | Run lint, build, load, documentation, and test checks |
+| `npm run audit:runtime` | Check the dependency graph shipped to n8n installations |
 
 Run `npm run check` before opening a pull request.
 
+The lint configuration retains the official n8n Cloud-compatible community,
+credential, node, TypeScript, and import rules. Build and release preparation use
+Node.js, TypeScript, npm, and Git directly to avoid unrelated CLI scaffolding
+and AI dependencies. CI and publishing require a clean audit of the dependency
+graph shipped to n8n installations. Review the full development audit separately;
+upstream n8n tooling can temporarily report advisories that are not included in
+the published package.
+
 ## Architecture
 
 The package intentionally uses one programmatic action node. Although simple
@@ -135,14 +155,19 @@ Releases are maintainer-only:
 2. Confirm the intended release notes and semantic-version impact.
 3. Run `npm run check`.
 4. Inspect `npm pack --dry-run` for unexpected private or source files.
-5. Run `npm run release` locally. The official n8n CLI invokes `release-it` to
-   choose the version, update release metadata, commit, tag, push, and create the
-   GitHub release; it does not publish npm from the local machine.
+5. Commit the release notes with the intended version and date in `CHANGELOG.md`.
+   Run `npm run release -- patch` (or `minor` / `major`). The script requires a
+   clean `main`, the public origin and its upstream, fetches remote main, runs
+   the checks, and uses `npm version` to update both manifests, commit, and tag.
+   It atomically pushes main and the exact version tag. It never publishes npm
+   locally. If the push fails, inspect the local release commit/tag and remote
+   state before retrying the push; do not increment the version again.
 6. Confirm the pushed `X.Y.Z` tag exactly matches `package.json` and both version
    fields in `package-lock.json`.
 7. The GitHub Publish workflow verifies main ancestry, runs the complete package
-   check, inspects `npm pack --dry-run`, and invokes the official n8n release
-   command with npm authentication and GitHub OIDC provenance.
+   check and dependency audit, inspects `npm pack --dry-run`, and invokes
+   `npm publish --provenance` with npm authentication and GitHub OIDC provenance.
+   The prepublish guard requires this repository's matching tag workflow.
 8. After npm reports the new version, run the official community-package scan:
 
    ```bash

package/examples/README.md

@@ -46,6 +46,105 @@ This trigger is not an event log. If publication changes several times between
 polls, the workflow receives the latest observed state rather than every
 intermediate transition.
 
+## Release Guardian
+
+[`release-guardian.json`](release-guardian.json) checks each newly published
+page revision, emails an optional success report, and offers approval to restore
+the last revision previously verified by the workflow when the live check
+fails. It also retains an approval branch for private drafts deliberately
+created through an eligible API or ChatGPT write with publication disabled.
+
+- Minimum OrbitPage node version: `n8n-nodes-orbitpage@0.3.2`
+- Required scopes: `workspace:read`, `publication:read`, `publication:write`,
+  `backup:read`, and `backup:write`
+- Additional credential: Gmail OAuth2 for verification, approval, and failure
+  messages
+- Default behavior: `SEND_SUCCESS_EMAIL` is `YES`; `ENABLE_PUBLISH` is `NO`
+- Data changes: dashboard releases are only observed and checked. A private
+  draft is published only after approval and only when `ENABLE_PUBLISH=YES`;
+  rollback always requires separate approval
+
+After import, select the same OrbitPage credential on every OrbitPage node and
+a Gmail credential on every Gmail node. Replace the email address in
+**Configuration**, keep `ENABLE_PUBLISH=NO`, and run the manual trigger once.
+It checks the current public release and sends a success email when
+`SEND_SUCCESS_EMAIL=YES`. Activate the workflow, save a dashboard change, and
+expect the next polling execution to verify the new public revision. Set
+`ENABLE_PUBLISH=YES` only when the workflow must approve private API drafts.
+
+The comparison stores only a bounded projection of public-facing fields in n8n
+workflow static data after a successful production execution. The first run is
+therefore a baseline, and manual test executions may not persist it. Configure
+n8n execution-data retention according to the sensitivity of unpublished page
+content returned by the read nodes.
+
+The trigger polls once per minute. It sees only revisions saved to OrbitPage,
+never unsaved browser form state, and it receives the latest state rather than
+every transition between polls. Dashboard saves schedule publication
+automatically, so the Guardian validates them after publication rather than
+pretending it can intercept them. On its first successful check it establishes
+a baseline; rollback becomes available only after an earlier revision has been
+verified and remains in OrbitPage version history.
+
+## AI Page Copilot
+
+[`ai-page-copilot.json`](ai-page-copilot.json) provides a private n8n chat agent
+that can inspect an OrbitPage, explain its current state, prepare a validated AI
+edit, and publish only after reviewed approval.
+
+- Minimum OrbitPage node version: `n8n-nodes-orbitpage@0.3.2`
+- n8n requirement: n8n 2.x with AI Agent, Chat Trigger, Simple Memory, Chat
+  human review, and community-node tool usage available
+- Required OrbitPage scopes: `workspace:read`, `publication:read`,
+  `publication:write`, `ai:read`, and `ai:write`
+- Additional credential: one supported chat-model credential; the checked-in
+  example uses the OpenAI Chat Model with `gpt-5-mini` as a replaceable default
+- Data changes: read tools never change data, AI preview consumes allowance but
+  does not edit the page, and apply publishes only the exact reviewed preview
+
+After import, select the same dedicated OrbitPage credential on every OrbitPage
+tool and select the model credential. Keep **When Chat Message Received**
+private during setup. Publish the workflow, then test this sequence:
+
+1. Ask `What is currently on my OrbitPage?` and confirm the agent uses only
+   read tools.
+2. Ask for one harmless, reversible wording change.
+3. Confirm that Chat renders the proposal as Markdown with summary, changes,
+   reviewed revision, expiry, and **Approve and publish** / **Reject** buttons.
+4. Select **Approve and publish** without sending another chat message.
+5. Confirm the final Chat response contains publication evidence from
+   **Verify Published State**.
+
+The AI agent has no apply tool. A Code node extracts the server-issued opaque
+`previewToken` from the completed preview call, formats only the reviewable
+fields for Chat, and keeps the token out of the message. The deterministic
+approval branch passes that token to an ordinary OrbitPage action node with
+`publish: true` fixed by the workflow. The token can still be rejected when it
+expires or the underlying revision changes. Rejecting the Chat review bypasses
+the write node and reports that nothing changed.
+
+The agent calls **Preview AI Page Changes** at most once per user message. If
+OrbitPage returns an error or times out, it reports that failure without an
+automatic second attempt.
+
+Edit intent is sent to OrbitPage as a concise natural-language instruction
+instead of a field-by-field page dump. The agent returns its intermediate tool
+steps so **Prepare Chat Response** can recover the validated proposal and route
+the opaque token to the deterministic approval branch.
+
+The workflow intentionally provides no custom HTTP tool and no billing, domain,
+Shop, newsletter, team, media-delete, backup, or restore operations. Keep those
+capabilities outside this credential. If a self-hosted instance does not expose
+the generated **OrbitPage Tool** nodes, verify that its community-node AI-tool
+usage is enabled before changing the workflow.
+
+Simple Memory preserves ordinary conversation context, but approval and the
+preview token remain inside one waiting workflow execution and do not depend on
+memory. Use a supported database-backed memory only when the conversation must
+survive restarts or serve multiple workers. Configure n8n execution-data
+retention because full page drafts and AI proposals can appear in execution
+logs.
+
 ## Understand the output
 
 The action example returns the OrbitPage API response as one n8n item. The