npm package: @robinpath/rightplace
Description: RightPlace integration — access projects, WordPress, WooCommerce, email, files, git, spreadsheets, stages, docs, automations, and more via rightplace-cli
Latest version: 0.1.3

# @robinpath/rightplace

> Access RightPlace desktop app data — projects, WordPress, WooCommerce, email, files, git, spreadsheets, stages, docs, automations, database, terminal, and more via the rightplace-cli HTTP API.

![Category](https://img.shields.io/badge/category-Productivity-blue) ![Functions](https://img.shields.io/badge/functions-130-green) ![Auth](https://img.shields.io/badge/auth-Auto--Discover-orange) ![License](https://img.shields.io/badge/license-MIT-brightgreen)

## Why use this module?

The `rightplace` module lets you:

- Get a full workspace overview (projects, resources, email accounts, stages, capabilities)
- Manage WordPress sites — posts, pages, plugins, themes, users, media, WooCommerce
- Read and send email, search contacts, manage mailboxes
- Work with files, git repositories, spreadsheets, and databases
- Track tasks on kanban boards (stages) with full CRUD
- Create and run RobinPath automations
- Manage documents — create, edit, search, organize
- Execute shell commands safely
- Search across all data types in one call
- Combine with any other RobinPath module (Slack, GitHub, CSV, etc.)

All 130 functions auto-discover a running rightplace-cli server. No credentials to configure.

## Installation

```bash
robinpath add @robinpath/rightplace
```

## Quick Start

**1. Start RightPlace** (desktop app or CLI)

```bash
rightplace-cli --port 7890
```

**2. Check connection**

```robinpath
rightplace.status into $s
log "Connected: " + $s.connected
log "Version: " + $s.version
```

**3. Get workspace context (call this FIRST)**

```robinpath
rightplace.context into $ctx
log $ctx.projects
log $ctx.capabilities
```

**4. Work with data**

```robinpath
# List projects
rightplace.projects into $list
for $p in $list
  log $p.name + " — " + $p.folder_path
endfor

# Read WordPress posts
rightplace.wpPosts "wp-resource-uuid" into $posts
for $post in $posts
  log $post.title
endfor

# Search everything
rightplace.search "invoice" into $results
log "Found " + length($results) + " results"
```

## Available Functions

### System (7)
| Function | Description |
|----------|-------------|
| `rightplace.status` | Check if CLI is running and reachable |
| `rightplace.context` | Full workspace summary — call FIRST |
| `rightplace.reconnect` | Clear cached connection, re-discover CLI |
| `rightplace.health` | Server health check |
| `rightplace.openapi` | Get OpenAPI 3.1 spec |
| `rightplace.metrics` | Server metrics |
| `rightplace.batch` | Execute multiple operations in one request |

### Projects & Tasks (6)
| Function | Description |
|----------|-------------|
| `rightplace.projects` | List all projects |
| `rightplace.getProject` | Get project with resources |
| `rightplace.createProject` | Create a new project |
| `rightplace.updateProject` | Update project name/description |
| `rightplace.tasks` | List tasks for a project |
| `rightplace.createTask` | Create a task |

### Spreadsheets (7)
| Function | Description |
|----------|-------------|
| `rightplace.sheets` | List sheets in a spreadsheet |
| `rightplace.grid` | Read cell data (A, B, C columns) |
| `rightplace.writeCells` | Write cells to spreadsheet |
| `rightplace.exportCsv` | Export sheet as CSV |
| `rightplace.createSheet` | Create a new sheet |
| `rightplace.renameSheet` | Rename a sheet |
| `rightplace.deleteSheet` | Delete a sheet |

### Email (10)
| Function | Description |
|----------|-------------|
| `rightplace.emailAccounts` | List email accounts |
| `rightplace.emailMailboxes` | List mailboxes (inbox, sent, etc.) |
| `rightplace.emailMessages` | List messages with filters |
| `rightplace.emailGetMessage` | Get full message with body |
| `rightplace.emailContacts` | List/search contacts |
| `rightplace.emailSearch` | Full-text search emails |
| `rightplace.emailSend` | Send email via SMTP |
| `rightplace.emailFlags` | Set read/flagged status |
| `rightplace.emailMove` | Move messages between mailboxes |
| `rightplace.emailDraft` | Save email draft |

### Files (5)
| Function | Description |
|----------|-------------|
| `rightplace.files` | List files in a resource |
| `rightplace.readFile` | Read file content |
| `rightplace.writeFile` | Write file content |
| `rightplace.deleteFile` | Delete file or directory |
| `rightplace.searchFiles` | Search by name or content |

### Git (9)
| Function | Description |
|----------|-------------|
| `rightplace.gitStatus` | Branch and changed files |
| `rightplace.gitLog` | Commit history |
| `rightplace.gitDiff` | View changes |
| `rightplace.gitBranches` | List branches |
| `rightplace.gitStage` | Stage files (git add) |
| `rightplace.gitCommit` | Create commit |
| `rightplace.gitBranch` | Create branch |
| `rightplace.gitCheckout` | Switch branch |
| `rightplace.gitFileContent` | Read file at specific ref |

### Stages / Kanban (6)
| Function | Description |
|----------|-------------|
| `rightplace.stages` | List all boards |
| `rightplace.getStage` | Get board with tasks |
| `rightplace.addStageTask` | Add task to board |
| `rightplace.updateStageTask` | Update task |
| `rightplace.deleteStageTask` | Delete task |
| `rightplace.createStage` | Create new board |

### WordPress Read (16)
| Function | Description |
|----------|-------------|
| `rightplace.wpStatus` | Connection status |
| `rightplace.wpContent` | List content by type |
| `rightplace.wpGetContent` | Get content item |
| `rightplace.wpSearch` | Search WP content |
| `rightplace.wpPosts` | List posts |
| `rightplace.wpGetPost` | Get single post |
| `rightplace.wpPages` | List pages |
| `rightplace.wpMedia` | List media |
| `rightplace.wpCategories` | List categories |
| `rightplace.wpTags` | List tags |
| `rightplace.wpUsers` | List users |
| `rightplace.wpThemes` | List themes |
| `rightplace.wpPlugins` | List plugins |
| `rightplace.wpFunctions` | List 130+ API functions |
| `rightplace.wpSystemInfo` | PHP, MySQL, memory info |
| `rightplace.wpSchema` | Post types, taxonomies |

### WordPress Write (17)
| Function | Description |
|----------|-------------|
| `rightplace.wpCoreApi` | Call any WP function |
| `rightplace.wpCreatePost` | Create post |
| `rightplace.wpUpdatePost` | Update post |
| `rightplace.wpCreatePage` | Create page |
| `rightplace.wpSideloadMedia` | Upload from URL |
| `rightplace.wpCreateCategory` | Create category |
| `rightplace.wpActivatePlugin` | Activate plugin |
| `rightplace.wpDeactivatePlugin` | Deactivate plugin |
| `rightplace.wpUpdatePlugin` | Update plugin |
| `rightplace.wpActivateTheme` | Switch theme |
| `rightplace.wpUpdateUser` | Update user |
| `rightplace.wpPasswordReset` | Password reset |
| `rightplace.wpExportCsv` | Export to CSV |
| `rightplace.wpExportJson` | Export to JSON |
| `rightplace.wpQuery` | Custom WP query |
| `rightplace.wpSync` | Trigger sync |
| `rightplace.wpRest` | Raw REST API call |

### WooCommerce (6)
| Function | Description |
|----------|-------------|
| `rightplace.wcProducts` | List products |
| `rightplace.wcGetProduct` | Get product |
| `rightplace.wcOrders` | List orders |
| `rightplace.wcGetOrder` | Get order |
| `rightplace.wcCustomers` | List customers |
| `rightplace.wcGetCustomer` | Get customer |

### More (21)
| Function | Description |
|----------|-------------|
| `rightplace.exec` | Execute shell command |
| `rightplace.query` | SQL SELECT query |
| `rightplace.dbExecute` | SQL mutation |
| `rightplace.search` | Search across all data |
| `rightplace.activities` | List activities |
| `rightplace.activitiesUnread` | Unread count |
| `rightplace.connections` | List connections |
| `rightplace.places` | List places |
| `rightplace.docsList` | List documents |
| `rightplace.docsGet` | Get document |
| `rightplace.docsCreate` | Create document |
| `rightplace.docsUpdate` | Update document |
| `rightplace.docsDelete` | Delete document |
| `rightplace.automationsList` | List automations |
| `rightplace.automationCreate` | Create automation |
| `rightplace.automationRun` | Run automation |
| `rightplace.listResources` | List resources |
| `rightplace.createResource` | Create resource |
| `rightplace.resourceTypes` | List resource types |
| ... | [See MODULE.md for all 128 functions](./MODULE.md) |

## Examples

### WordPress management

```robinpath
@desc "Check plugins and create a post"
do
  rightplace.wpPlugins "wp-uuid" into $plugins
  for $p in $plugins
    log $p.name + " — " + $p.status
  endfor

  rightplace.wpCreatePost "wp-uuid" {title: "New Post", status: "draft"} into $post
  log "Created: " + $post.id
enddo
```

### Email + WooCommerce

```robinpath
@desc "Morning summary"
do
  rightplace.emailMessages {limit: "5"} into $recent
  for $m in $recent
    log $m.from_address + ": " + $m.subject
  endfor

  rightplace.wcOrders "wp-uuid" {status: "processing"} into $orders
  log "Pending orders: " + length($orders)
enddo
```

### Git workflow

```robinpath
@desc "Branch, code, commit"
do
  rightplace.gitBranch "git-uuid" "feature/auth" true
  rightplace.gitStage "git-uuid" ["src/auth.rs"]
  rightplace.gitCommit "git-uuid" "feat: add auth module" into $c
  log "Committed: " + $c.hash
enddo
```

### Combine with Slack

```robinpath
@desc "Send WooCommerce orders to Slack"
do
  rightplace.wcOrders "wp-uuid" {status: "processing"} into $orders
  if length($orders) > 0
    $msg = "Pending orders: " + length($orders)
    slack.send "default" "#orders" $msg
  endif
enddo
```

### Spreadsheet to WordPress

```robinpath
@desc "Create posts from spreadsheet rows"
do
  rightplace.grid "spreadsheet-uuid" "Posts" into $data
  for $row in $data.rows
    $title = $row.cells.A.raw
    $content = $row.cells.B.raw
    if $title != "" and $title != "Title"
      rightplace.wpCreatePost "wp-uuid" {title: $title, content: $content, status: "draft"}
      log "Created: " + $title
    endif
  endfor
enddo
```

## Integration with RobinPath

```typescript
import { RobinPath } from "@robinpath/core";
import RightplaceModule from "@robinpath/rightplace";

const rp = new RobinPath();
rp.registerModule(RightplaceModule.name, RightplaceModule.functions);
rp.registerModuleMeta(RightplaceModule.name, RightplaceModule.functionMetadata);
rp.registerModuleInfo(RightplaceModule.name, RightplaceModule.moduleMetadata);

const result = await rp.executeScript(`
  rightplace.context into $ctx
  log $ctx.projects
`);
```

## How it works

```
RobinPath script → @robinpath/rightplace module → HTTP → rightplace-cli (Rust) → encrypted databases
```

The module auto-discovers rightplace-cli via `~/.rightplace/cli.json` (written on startup). No manual configuration. All security (encryption, auth, permissions, rate limiting) is handled by the CLI.

## Full API Reference

See [MODULE.md](./MODULE.md) for complete documentation of all 128 functions with parameters, return types, code examples, error handling, and recipes.

## Related Modules

- [`@robinpath/slack`](../slack) -- Send RightPlace notifications to Slack
- [`@robinpath/csv`](../csv) -- Parse and generate CSV from spreadsheet exports
- [`@robinpath/github`](../github) -- Combine RightPlace projects with GitHub repos
- [`@robinpath/discord`](../discord) -- Send notifications to Discord

## License

MIT