Ty_Tech/Salon_Assistant
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement S7 operator connect helpers for SaaS and channels.

Browse Source 
Add dry-run-default connect dispatcher and per-integration scripts with gitignored local capability state, docs, and unit tests. Mutations require --apply and use nemohermes/openshell only.
This commit is contained in:
Ty
2026-07-27 13:32:42 -07:00
parent 76df8b7ab6
commit d6b74c42f6
17 changed files with 2229 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/INSTALL.md
+87 -2
View File
@@ -1,6 +1,6 @@
# Install
**Status:** Stages S0–S6 implemented. S7 pending.
**Status:** Stages S0–S7 implemented.
## Stages
@@ -14,7 +14,7 @@
| S4 | Host script | Sandbox verify (attach) or onboard (clean host) | ✅ Implemented |
| S5 | Host script | Policy overlays + skills sync via nemohermes | ✅ Implemented |
| S6 | Host script | Doctor green | ✅ Implemented |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ⏳ Pending |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ✅ Implemented |
## Platform commands (normative)
@@ -165,6 +165,91 @@ make install-s3-s5
- See [design/scenarios.md](../design/scenarios.md) (S1–S5) for operational scenarios.
- See [OPERATIONS.md](OPERATIONS.md) for day-2 operator commands.
## S7: Owner messaging + operator connect scripts
After install stages S0–S6 are complete, the operator connects the owner's SaaS
integrations and messaging channels.
**Safety model:** `--dry-run` is the default. Use `--apply` to perform mutations.
All mutations use `nemohermes` / `openshell`. No parallel control API.
### Connect dispatcher
```bash
./scripts/connect.sh --help
./scripts/connect.sh status
./scripts/connect.sh all --dry-run # preview all targets
./scripts/connect.sh all --apply # execute all targets
```
### Per-target connect
```bash
# Name / profile (sandbox identity)
./scripts/connect.sh name --dry-run
./scripts/connect.sh name --apply
# Messaging channels (WhatsApp, Email, Telegram)
./scripts/connect.sh channels --target whatsapp --dry-run
./scripts/connect.sh channels --target whatsapp --apply
./scripts/connect.sh channels --target telegram --apply
./scripts/connect.sh channels --target email --apply
# Square (remote MCP — read-only tools)
./scripts/connect.sh square --dry-run
./scripts/connect.sh square --apply
# QuickBooks Online (local MCP — read-only tools)
./scripts/connect.sh quickbooks --dry-run
./scripts/connect.sh quickbooks --apply
# Vagaro (REST + webhooks)
./scripts/connect.sh vagaro --dry-run
./scripts/connect.sh vagaro --apply
```
### Make targets
```bash
make connect # show connect help
make connect-status # show connection status
make connect-name # name / profile (--dry-run)
make connect-channels # channels (--dry-run)
make connect-square # Square (--dry-run)
make connect-quickbooks # QuickBooks (--dry-run)
make connect-vagaro # Vagaro (--dry-run)
make connect-all # all targets (--dry-run)
```
### Connection state
State is stored in `.local/capability_state.json` (gitignored). Status values:
| Status | Meaning |
|--------|---------|
| `connected` | Integration is active and verified |
| `skipped` | Operator or owner chose to skip |
| `later` | Planned for future setup |
| `error` | Connection attempt failed — needs attention |
| `offline` | Not yet connected — using fixtures |
### Capability report
After connecting, export a capability report compatible with the setup-education skill:
```bash
# Via the connect state library (source in a script)
source scripts/lib/connect_state.sh
export_capability_report > /tmp/capability_report.json
```
### Owner-safe messaging
The owner never receives terminal, Docker, or editor instructions. All connect
work is done by the operator using these scripts. The owner interacts with the
assistant through connected channels (WhatsApp, Email, Telegram) and completes
vendor browser steps (OAuth consent, BotFather, etc.) on their own devices.
## UAT host notes
This repository was tested on a live host with:
docs/SETUP_UX.md
+29 -9
View File
@@ -4,24 +4,44 @@
## Prerequisite
Install stages S0–S6 complete ([INSTALL.md](INSTALL.md)).
Install stages S0–S6 complete ([INSTALL.md](INSTALL.md)). S7 connect scripts available ([INSTALL.md § S7](INSTALL.md#s7-owner-messaging--operator-connect-scripts)).
## Flow
1. **Name the assistant** → profile/sandbox name.
2. **Profile intake** — business, timezone, hours, priorities, hard rules.
3. **Channels** — WhatsApp, Email, Telegram (connect / skip / later).
4. **Scheduling** — owner’s Vagaro and/or Square.
5. **Books** — owner’s QuickBooks Online.
6. **Expectations** — draft-only client send; no auto-publish; no inventing live data.
1. **Name the assistant** → profile/sandbox name.
2. **Profile intake** — business, timezone, hours, priorities, hard rules.
3. **Channels** — WhatsApp, Email, Telegram (connect / skip / later).
4. **Scheduling** — owner's Vagaro and/or Square.
5. **Books** — owner's QuickBooks Online.
6. **Expectations** — draft-only client send; no auto-publish; no inventing live data.
7. **Capability report** — plain language.
## Rules
- Owner never receives terminal/Docker/editor instructions.
- Secrets via operator `scripts/connect-*.sh` + OpenShell providers / NemoClaw channel flows.
- Owner never receives terminal/Docker/editor instructions.
- Secrets via operator `scripts/connect-*.sh` + OpenShell providers / NemoClaw channel flows.
- Agent explains vendor browser steps only.
## Operator connect scripts (S7)
After install, the operator runs connect scripts to wire the owner's SaaS:
```bash
# Preview all connections
./scripts/connect.sh all --dry-run
# Connect specific integrations
./scripts/connect.sh square --apply
./scripts/connect.sh channels --target whatsapp --apply
./scripts/connect.sh quickbooks --apply
./scripts/connect.sh vagaro --apply
# Check status
./scripts/connect.sh status
```
See [docs/INSTALL.md § S7](INSTALL.md#s7-owner-messaging--operator-connect-scripts) for full details.
## Related
[design/use-cases.md](../design/use-cases.md) family E · [design/mcp-integrations.md](../design/mcp-integrations.md)
docs/providers/channels.md
+42 -5
View File
@@ -1,10 +1,47 @@
# Owner channels (WhatsApp, Email, Telegram)
**Status:** Outline.
**Status:** Connect script implemented.
- MVP owner ↔ assistant channels: **WhatsApp, Email, Telegram**.
- Configured via **NemoClaw Hermes channel commands** (`nemohermes … channels add`, rebuild when required).
- Allowlists for who may talk to the bot.
- Owner never configures via host shell recipes in chat.
- MVP owner ↔ assistant channels: **WhatsApp, Email, Telegram**.
- Configured via **NemoClaw Hermes channel commands** (`nemohermes … channels add`, rebuild when required).
- Allowlists for who may talk to the bot.
- Owner never configures via host shell recipes in chat.
## Connect procedure
```bash
# Preview all channels (default)
./scripts/connect.sh channels --dry-run
# Connect a specific channel
./scripts/connect.sh channels --target whatsapp --apply
./scripts/connect.sh channels --target telegram --apply
./scripts/connect.sh channels --target email --apply
# Connect all channels
./scripts/connect.sh channels --apply
```
### What the script does
1. **Dry-run:** Shows steps for each channel without executing.
2. **Apply:**
- Prompts for channel-specific credentials.
- Calls `nemohermes <sandbox> channels add <channel>` with credentials.
- Records status in `.local/capability_state.json`.
### Channel-specific requirements
| Channel | Owner steps | Operator credentials |
|---------|-------------|---------------------|
| **WhatsApp** | Set up WhatsApp Business API in Meta developer console | Phone Number ID, Verify Token |
| **Email** | Provide email address for the assistant | Email address |
| **Telegram** | Create a bot via @BotFather on Telegram | Bot Token |
### Owner steps (browser only)
- **WhatsApp:** Set up WhatsApp Business API in the Meta developer console.
- **Email:** Provide the email address the assistant will respond to.
- **Telegram:** Create a bot via @BotFather on Telegram; BotFather returns a Bot Token.
See [design/use-cases.md](../../design/use-cases.md) family C · [docs/SETUP_UX.md](../SETUP_UX.md).
docs/providers/quickbooks.md
+56 -5
View File
@@ -1,8 +1,59 @@
# QuickBooks Online
**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
**Status:** Connect script implemented. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
- **Agent path:** local QBO MCP on Docker network with Hermes.
- **Allow:** P&L/reports, invoice/bill/vendor/customer read, company info.
- **Deny:** payment/bill_payment tools; write/update/delete off for MVP.
- **Connect:** operator `scripts/connect/connect-quickbooks.sh` (build).
- **Agent path:** local QBO MCP on Docker network with Hermes.
- **Allow:** P&L/reports, invoice/bill/vendor/customer read, company info.
- **Deny:** payment/bill_payment tools; write/update/delete off for MVP.
- **Connect:** operator `scripts/connect/connect-quickbooks.sh`.
## Connect procedure
```bash
# Preview (default)
./scripts/connect.sh quickbooks --dry-run
# Execute (prompts for credentials)
./scripts/connect.sh quickbooks --apply
```
### What the script does
1. **Dry-run:** Shows MCP image, container name, Docker network, allowed/denied tools.
2. **Apply:**
- Prompts for QBO Client ID, Client Secret, Access Token, Realm ID.
- Stores credentials via `openshell provider set qbo-*`.
- Registers MCP server type via `nemohermes config set`.
- Applies tool allowlist (read-only) and denylist (payment/write tools).
- Records status in `.local/capability_state.json`.
- Provides guidance for starting the MCP container.
### Owner steps (browser only)
1. Create a QBO application at [developer.intuit.com](https://developer.intuit.com).
2. Complete OAuth flow to obtain Client ID, Client Secret, and Access Token.
3. Note the Realm ID (company ID).
4. Provide credentials to the operator.
### Tool filters
| Allowed (read) | Denied |
|----------------|--------|
| `get_report` | `create_payment` |
| `search_invoice` | `bill_payment` |
| `get_invoice` | `create_invoice` |
| `search_bill` | `update_invoice` |
| `get_bill` | `delete_invoice` |
| `search_vendor` | `create_bill` |
| `get_vendor` | `update_bill` |
| `search_customer` | `delete_bill` |
| `get_customer` | |
| `get_company_info` | |
### MCP container
The QBO MCP server runs as a Docker container on the same network as Hermes:
- **Image:** `ghcr.io/intuit/quickbooks-online-mcp-server:latest`
- **Container:** `lumina-qbo-mcp`
- **Network:** `lumina-network`
docs/providers/square.md
+45 -5
View File
@@ -1,8 +1,48 @@
# Square
**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
**Status:** Connect script implemented. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
- **Agent path:** remote Square MCP.
- **Allow:** bookings, customers, catalog, inventory/location reads.
- **Deny:** payments, refunds, cards, checkout, payouts.
- **Connect:** operator `scripts/connect/connect-square.sh` (build) + owner browser OAuth.
- **Agent path:** remote Square MCP (`mcp.squareup.com`).
- **Allow:** bookings, customers, catalog, inventory/location reads.
- **Deny:** payments, refunds, cards, checkout, payouts.
- **Connect:** operator `scripts/connect/connect-square.sh` + owner browser OAuth.
## Connect procedure
```bash
# Preview (default)
./scripts/connect.sh square --dry-run
# Execute (prompts for access token)
./scripts/connect.sh square --apply
```
### What the script does
1. **Dry-run:** Shows MCP URL, allowed/denied tools, and step-by-step procedure.
2. **Apply:**
- Prompts for Square OAuth access token (read scope).
- Stores token via `openshell provider set square-access-token`.
- Registers MCP server URL via `nemohermes config set`.
- Applies tool allowlist (read-only) and denylist (payment tools).
- Records status in `.local/capability_state.json`.
### Owner steps (browser only)
1. Create a Square application at [developer.squareup.com](https://developer.squareup.com).
2. Generate an OAuth access token with read-only scope.
3. Provide the token to the operator.
### Tool filters
| Allowed (read) | Denied |
|----------------|--------|
| `bookings/list_bookings` | `payments/*` |
| `bookings/get_booking` | `refunds/*` |
| `customers/list_customers` | `cards/*` |
| `customers/get_customer` | `checkout/*` |
| `catalog/list_catalog` | `payouts/*` |
| `catalog/search_catalog_objects` | |
| `inventory/list_inventory` | |
| `locations/list_locations` | |
| `locations/get_location` | |
docs/providers/vagaro.md
+38 -5
View File
@@ -1,8 +1,41 @@
# Vagaro
**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
**Status:** Connect script implemented. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
- **No public MCP** — REST + webhooks.
- Appointments, clients, services, staff.
- No unofficial scrape.
- **Connect:** operator `scripts/connect/connect-vagaro.sh` (build).
- **No public MCP** — REST + webhooks.
- Appointments, clients, services, staff.
- No unofficial scrape.
- **Connect:** operator `scripts/connect/connect-vagaro.sh`.
## Connect procedure
```bash
# Preview (default)
./scripts/connect.sh vagaro --dry-run
# Execute (prompts for credentials)
./scripts/connect.sh vagaro --apply
```
### What the script does
1. **Dry-run:** Shows API base URL, webhook port, and step-by-step procedure.
2. **Apply:**
- Prompts for Vagaro API Key, API Secret, and optional Webhook Secret.
- Stores credentials via `openshell provider set vagaro-*`.
- Verifies API connectivity (best-effort curl to `/v1/me`).
- Records status in `.local/capability_state.json`.
- Provides webhook URL guidance.
### Owner steps (browser only)
1. Create a Vagaro developer account at [developer.vagaro.com](https://developer.vagaro.com).
2. Register an application to obtain API credentials.
3. Configure webhook URL in the Vagaro dashboard.
4. Provide credentials to the operator.
### API configuration
- **API Base:** `https://api.vagaro.com`
- **Webhook port:** `9876` (configurable via `LUMINA_VAGARO_WEBHOOK_PORT`)
- **Webhook URL:** `https://<your-host>:9876/vagaro/webhook`