@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: "google-workspace-cli"
+description: "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits, execute 43 built-in recipes, and use 10 persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling."
+---
+
+# Google Workspace CLI
+
+Expert guidance and automation for Google Workspace administration using the open-source `gws` CLI. Covers installation, authentication, 18+ service APIs, 43 built-in recipes, and 10 persona bundles for role-based workflows.
+
+---
+
+## Quick Start
+
+### Check Installation
+
+```bash
+# Verify gws is installed and authenticated
+python3 scripts/gws_doctor.py
+```
+
+### Send an Email
+
+```bash
+gws gmail users.messages send me --to "team@company.com" \
+  --subject "Weekly Update" --body "Here's this week's summary..."
+```
+
+### List Drive Files
+
+```bash
+gws drive files list --json --limit 20 | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table
+```
+
+---
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g @anthropic/gws
+gws --version
+```
+
+### Cargo (from source)
+
+```bash
+cargo install gws-cli
+gws --version
+```
+
+### Pre-built Binaries
+
+Download from [github.com/googleworkspace/cli/releases](https://github.com/googleworkspace/cli/releases) for macOS, Linux, or Windows.
+
+### Verify Installation
+
+```bash
+python3 scripts/gws_doctor.py
+# Checks: PATH, version, auth status, service connectivity
+```
+
+---
+
+## Authentication
+
+### OAuth Setup (Interactive)
+
+```bash
+# Step 1: Create Google Cloud project and OAuth credentials
+python3 scripts/auth_setup_guide.py --guide oauth
+
+# Step 2: Run auth setup
+gws auth setup
+
+# Step 3: Validate
+gws auth status --json
+```
+
+### Service Account (Headless/CI)
+
+```bash
+# Generate setup instructions
+python3 scripts/auth_setup_guide.py --guide service-account
+
+# Configure with key file
+export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json
+export GWS_DELEGATED_USER=admin@company.com
+gws auth status
+```
+
+### Environment Variables
+
+```bash
+# Generate .env template
+python3 scripts/auth_setup_guide.py --generate-env
+```
+
+| Variable | Purpose |
+|----------|---------|
+| `GWS_CLIENT_ID` | OAuth client ID |
+| `GWS_CLIENT_SECRET` | OAuth client secret |
+| `GWS_TOKEN_PATH` | Custom token storage path |
+| `GWS_SERVICE_ACCOUNT_KEY` | Service account JSON key path |
+| `GWS_DELEGATED_USER` | User to impersonate (service accounts) |
+| `GWS_DEFAULT_FORMAT` | Default output format (json/ndjson/table) |
+
+### Validate Authentication
+
+```bash
+python3 scripts/auth_setup_guide.py --validate --json
+# Tests each service endpoint
+```
+
+---
+
+## Workflow 1: Gmail Automation
+
+**Goal:** Automate email operations — send, search, label, and filter management.
+
+### Send and Reply
+
+```bash
+# Send a new email
+gws gmail users.messages send me --to "client@example.com" \
+  --subject "Proposal" --body "Please find attached..." \
+  --attachment proposal.pdf
+
+# Reply to a thread
+gws gmail users.messages reply me --thread-id <THREAD_ID> \
+  --body "Thanks for your feedback..."
+
+# Forward a message
+gws gmail users.messages forward me --message-id <MSG_ID> \
+  --to "manager@company.com"
+```
+
+### Search and Filter
+
+```bash
+# Search emails
+gws gmail users.messages list me --query "from:client@example.com after:2025/01/01" --json \
+  | python3 scripts/output_analyzer.py --count
+
+# List labels
+gws gmail users.labels list me --json
+
+# Create a filter
+gws gmail users.settings.filters create me \
+  --criteria '{"from":"notifications@service.com"}' \
+  --action '{"addLabelIds":["Label_123"],"removeLabelIds":["INBOX"]}'
+```
+
+### Bulk Operations
+
+```bash
+# Archive all read emails older than 30 days
+gws gmail users.messages list me --query "is:read older_than:30d" --json \
+  | python3 scripts/output_analyzer.py --select "id" --format json \
+  | xargs -I {} gws gmail users.messages modify me {} --removeLabelIds INBOX
+```
+
+---
+
+## Workflow 2: Drive & Sheets
+
+**Goal:** Manage files, create spreadsheets, configure sharing, and export data.
+
+### File Operations
+
+```bash
+# List files
+gws drive files list --json --limit 50 \
+  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table
+
+# Upload a file
+gws drive files create --name "Q1 Report" --upload report.pdf \
+  --parents <FOLDER_ID>
+
+# Create a Google Sheet
+gws sheets spreadsheets create --title "Budget 2026" --json
+
+# Download/export
+gws drive files export <FILE_ID> --mime "application/pdf" --output report.pdf
+```
+
+### Sharing
+
+```bash
+# Share with user
+gws drive permissions create <FILE_ID> \
+  --type user --role writer --emailAddress "colleague@company.com"
+
+# Share with domain (view only)
+gws drive permissions create <FILE_ID> \
+  --type domain --role reader --domain "company.com"
+
+# List who has access
+gws drive permissions list <FILE_ID> --json
+```
+
+### Sheets Data
+
+```bash
+# Read a range
+gws sheets spreadsheets.values get <SHEET_ID> --range "Sheet1!A1:D10" --json
+
+# Write data
+gws sheets spreadsheets.values update <SHEET_ID> --range "Sheet1!A1" \
+  --values '[["Name","Score"],["Alice",95],["Bob",87]]'
+
+# Append rows
+gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \
+  --values '[["Charlie",92]]'
+```
+
+---
+
+## Workflow 3: Calendar & Meetings
+
+**Goal:** Schedule events, find available times, and generate standup reports.
+
+### Event Management
+
+```bash
+# Create an event
+gws calendar events insert primary \
+  --summary "Sprint Planning" \
+  --start "2026-03-15T10:00:00" --end "2026-03-15T11:00:00" \
+  --attendees "team@company.com" \
+  --location "Conference Room A"
+
+# List upcoming events
+gws calendar events list primary --timeMin "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --maxResults 10 --json
+
+# Quick event (natural language)
+gws helpers quick-event "Lunch with Sarah tomorrow at noon"
+```
+
+### Find Available Time
+
+```bash
+# Check free/busy for multiple people
+gws helpers find-time \
+  --attendees "alice@co.com,bob@co.com,charlie@co.com" \
+  --duration 60 --within "2026-03-15,2026-03-19" --json
+```
+
+### Standup Report
+
+```bash
+# Generate daily standup from calendar + tasks
+gws recipes standup-report --json \
+  | python3 scripts/output_analyzer.py --format table
+
+# Meeting prep (agenda + attendee info)
+gws recipes meeting-prep --event-id <EVENT_ID>
+```
+
+---
+
+## Workflow 4: Security Audit
+
+**Goal:** Audit Google Workspace security configuration and generate remediation commands.
+
+### Run Full Audit
+
+```bash
+# Full audit across all services
+python3 scripts/workspace_audit.py --json
+
+# Audit specific services
+python3 scripts/workspace_audit.py --services gmail,drive,calendar
+
+# Demo mode (no gws required)
+python3 scripts/workspace_audit.py --demo
+```
+
+### Audit Checks
+
+| Area | Check | Risk |
+|------|-------|------|
+| Drive | External sharing enabled | Data exfiltration |
+| Gmail | Auto-forwarding rules | Data exfiltration |
+| Gmail | DMARC/SPF/DKIM records | Email spoofing |
+| Calendar | Default sharing visibility | Information leak |
+| OAuth | Third-party app grants | Unauthorized access |
+| Admin | Super admin count | Privilege escalation |
+| Admin | 2-Step verification enforcement | Account takeover |
+
+### Review and Remediate
+
+```bash
+# Review findings
+python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \
+  --filter "status=FAIL" --select "area,check,remediation"
+
+# Execute remediation (example: restrict external sharing)
+gws drive about get --json  # Check current settings
+# Follow remediation commands from audit output
+```
+
+---
+
+## Python Tools
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `gws_doctor.py` | Pre-flight diagnostics | `python3 scripts/gws_doctor.py [--json] [--services gmail,drive]` |
+| `auth_setup_guide.py` | Guided auth setup | `python3 scripts/auth_setup_guide.py --guide oauth` |
+| `gws_recipe_runner.py` | Recipe catalog & runner | `python3 scripts/gws_recipe_runner.py --list [--persona pm]` |
+| `workspace_audit.py` | Security/config audit | `python3 scripts/workspace_audit.py [--json] [--demo]` |
+| `output_analyzer.py` | JSON/NDJSON analysis | `gws ... --json \| python3 scripts/output_analyzer.py --count` |
+
+All scripts are stdlib-only, support `--json` output, and include demo mode with embedded sample data.
+
+---
+
+## Best Practices
+
+### Security
+
+1. Use OAuth with minimal scopes — request only what each workflow needs
+2. Store tokens in the system keyring, never in plain text files
+3. Rotate service account keys every 90 days
+4. Audit third-party OAuth app grants quarterly
+5. Use `--dry-run` before bulk destructive operations
+
+### Automation
+
+1. Pipe `--json` output through `output_analyzer.py` for filtering and aggregation
+2. Use recipes for multi-step operations instead of chaining raw commands
+3. Select a persona bundle to scope recipes to your role
+4. Use NDJSON format (`--format ndjson`) for streaming large result sets
+5. Set `GWS_DEFAULT_FORMAT=json` in your shell profile for scripting
+
+### Performance
+
+1. Use `--fields` to request only needed fields (reduces payload size)
+2. Use `--limit` to cap results when browsing
+3. Use `--page-all` only when you need complete datasets
+4. Batch operations with recipes rather than individual API calls
+5. Cache frequently accessed data (e.g., label IDs, folder IDs) in variables
+
+---
+
+## Limitations
+
+| Constraint | Impact |
+|------------|--------|
+| OAuth tokens expire after 1 hour | Re-auth needed for long-running scripts |
+| API rate limits (per-user, per-service) | Bulk operations may hit 429 errors |
+| Scope requirements vary by service | Must request correct scopes during auth |
+| Pre-v1.0 CLI status | Breaking changes possible between releases |
+| Google Cloud project required | Free, but requires setup in Cloud Console |
+| Admin API needs admin privileges | Some audit checks require Workspace Admin role |
+
+### Required Scopes by Service
+
+```bash
+# List scopes for specific services
+python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets
+```
+
+| Service | Key Scopes |
+|---------|-----------|
+| Gmail | `gmail.modify`, `gmail.send`, `gmail.labels` |
+| Drive | `drive.file`, `drive.metadata.readonly` |
+| Sheets | `spreadsheets` |
+| Calendar | `calendar`, `calendar.events` |
+| Admin | `admin.directory.user.readonly`, `admin.directory.group` |
+| Tasks | `tasks` |

package/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md

@@ -0,0 +1,223 @@
+# Google Workspace CLI Persona Profiles
+
+10 role-based bundles that scope recipes and commands to your daily workflow.
+
+---
+
+## 1. Executive Assistant
+
+**Description:** Managing schedules, emails, and communications for executives.
+
+**Top Commands:**
+- `gws helpers morning-briefing` — Start the day with schedule + inbox overview
+- `gws helpers find-time` — Find available slots for meetings
+- `gws helpers meeting-prep --event-id <id>` — Prepare meeting agenda
+- `gws gmail users.messages send me` — Send emails on behalf
+- `gws helpers eod-wrap` — End of day summary
+
+**Recommended Recipes:** morning-briefing, today-schedule, find-time, send-email, reply-to-thread, meeting-prep, eod-wrap, quick-event, inbox-zero, standup-report
+
+**Daily Workflow:**
+1. Run `morning-briefing` at 8:00 AM
+2. Process inbox with `inbox-zero`
+3. Schedule meetings with `find-time` + `create-event`
+4. Prep for meetings with `meeting-prep`
+5. Close day with `eod-wrap`
+
+---
+
+## 2. Project Manager
+
+**Description:** Tracking tasks, meetings, and project deliverables.
+
+**Top Commands:**
+- `gws recipes standup-report` — Generate standup updates
+- `gws helpers find-time` — Schedule sprint ceremonies
+- `gws tasks tasks insert` — Create and assign tasks
+- `gws sheets spreadsheets.values get` — Read project trackers
+- `gws recipes project-status` — Aggregate project status
+
+**Recommended Recipes:** standup-report, create-event, find-time, task-create, task-progress, project-status, weekly-summary, share-folder, sheet-read, morning-briefing
+
+**Daily Workflow:**
+1. Run `standup-report` before standup
+2. Update project tracker via `sheet-write`
+3. Create action items with `task-create`
+4. Run `weekly-summary` on Fridays
+5. Share updates via `chat-message`
+
+---
+
+## 3. HR
+
+**Description:** Managing people, onboarding, and team communications.
+
+**Top Commands:**
+- `gws admin users list` — List all domain users
+- `gws admin users get <email>` — Look up employee details
+- `gws docs documents create` — Create onboarding docs
+- `gws drive permissions create` — Share folders with new hires
+- `gws people people.connections list` — Export contact directory
+
+**Recommended Recipes:** list-users, user-info, send-email, create-event, create-doc, share-folder, chat-message, list-groups, export-contacts, today-schedule
+
+**Daily Workflow:**
+1. Check new hire onboarding queue
+2. Create welcome docs with `create-doc`
+3. Set up 1:1s with `create-event`
+4. Share team folders with `share-folder`
+5. Send announcements via `send-email`
+
+---
+
+## 4. Sales
+
+**Description:** Managing client communications, proposals, and scheduling.
+
+**Top Commands:**
+- `gws gmail users.messages send me` — Send proposals and follow-ups
+- `gws gmail users.messages list me --query` — Search client conversations
+- `gws helpers find-time` — Schedule client meetings
+- `gws docs documents create` — Create proposals
+- `gws sheets spreadsheets.values update` — Update pipeline tracker
+
+**Recommended Recipes:** send-email, search-emails, create-event, find-time, create-doc, share-file, sheet-read, sheet-write, export-file, morning-briefing
+
+**Daily Workflow:**
+1. Run `morning-briefing` for meeting overview
+2. Search emails for client updates
+3. Update pipeline in Sheets
+4. Send proposals via `send-email` + `share-file`
+5. Schedule follow-ups with `create-event`
+
+---
+
+## 5. IT Admin
+
+**Description:** Managing Workspace configuration, security, and user administration.
+
+**Top Commands:**
+- `gws admin users list --domain` — Audit user accounts
+- `gws admin activities list login` — Monitor login activity
+- `gws admin groups list` — Manage groups
+- `python3 workspace_audit.py` — Run security audit
+- `gws drive files list --orderBy "quotaBytesUsed desc"` — Find storage hogs
+
+**Recommended Recipes:** list-users, list-groups, user-info, audit-logins, drive-activity, find-large-files, cleanup-trash, label-manager, filter-setup, share-folder
+
+**Daily Workflow:**
+1. Check `audit-logins` for suspicious activity
+2. Run `workspace_audit.py` weekly
+3. Process user provisioning requests
+4. Monitor storage with `find-large-files`
+5. Review group memberships
+
+---
+
+## 6. Developer
+
+**Description:** Using Workspace APIs for automation and data integration.
+
+**Top Commands:**
+- `gws sheets spreadsheets.values get` — Read config/data from Sheets
+- `gws sheets spreadsheets.values update` — Write results to Sheets
+- `gws drive files create --upload` — Upload build artifacts
+- `gws chat spaces.messages create` — Post deployment notifications
+- `gws tasks tasks insert` — Create tasks from CI/CD
+
+**Recommended Recipes:** sheet-read, sheet-write, sheet-append, upload-file, create-doc, chat-message, task-create, list-files, export-file, send-email
+
+**Daily Workflow:**
+1. Read config from Sheets API
+2. Run automated reports to Sheets
+3. Post updates to Chat spaces
+4. Upload artifacts to Drive
+5. Create tasks for bugs/issues
+
+---
+
+## 7. Marketing
+
+**Description:** Managing campaigns, content creation, and team coordination.
+
+**Top Commands:**
+- `gws docs documents create` — Draft blog posts and briefs
+- `gws drive files create --upload` — Upload creative assets
+- `gws sheets spreadsheets.values append` — Log campaign metrics
+- `gws gmail users.messages send me` — Send campaign emails
+- `gws chat spaces.messages create` — Coordinate with team
+
+**Recommended Recipes:** send-email, create-doc, share-file, upload-file, create-sheet, sheet-write, chat-message, create-event, email-stats, weekly-summary
+
+**Daily Workflow:**
+1. Check `email-stats` for campaign performance
+2. Create content in Docs
+3. Upload assets to shared Drive folders
+4. Update metrics in Sheets
+5. Coordinate launches via Chat
+
+---
+
+## 8. Finance
+
+**Description:** Managing spreadsheets, financial reports, and data analysis.
+
+**Top Commands:**
+- `gws sheets spreadsheets.values get` — Pull financial data
+- `gws sheets spreadsheets.values update` — Update forecasts
+- `gws sheets spreadsheets create` — Create new reports
+- `gws drive files export` — Export reports as PDF
+- `gws drive permissions create` — Share with auditors
+
+**Recommended Recipes:** sheet-read, sheet-write, sheet-append, create-sheet, export-file, share-file, send-email, find-large-files, drive-activity, weekly-summary
+
+**Daily Workflow:**
+1. Pull latest data into Sheets
+2. Update financial models
+3. Generate PDF reports with `export-file`
+4. Share reports with stakeholders
+5. Weekly summary for leadership
+
+---
+
+## 9. Legal
+
+**Description:** Managing documents, contracts, and compliance.
+
+**Top Commands:**
+- `gws docs documents create` — Draft contracts
+- `gws drive files export` — Export final versions as PDF
+- `gws drive permissions create` — Manage document access
+- `gws gmail users.messages list me --query` — Search for compliance emails
+- `gws admin activities list` — Audit trail for compliance
+
+**Recommended Recipes:** create-doc, share-file, export-file, search-emails, send-email, upload-file, list-files, drive-activity, audit-logins, find-large-files
+
+**Daily Workflow:**
+1. Draft and review documents
+2. Search email for contract references
+3. Export finalized docs as PDF
+4. Set precise sharing permissions
+5. Maintain audit trail
+
+---
+
+## 10. Customer Support
+
+**Description:** Managing customer communications and ticket tracking.
+
+**Top Commands:**
+- `gws gmail users.messages list me --query` — Search customer emails
+- `gws gmail users.messages reply me` — Reply to tickets
+- `gws gmail users.labels create` — Organize by ticket status
+- `gws tasks tasks insert` — Create follow-up tasks
+- `gws chat spaces.messages create` — Escalate to team
+
+**Recommended Recipes:** search-emails, send-email, reply-to-thread, label-manager, filter-setup, task-create, chat-message, unread-digest, inbox-zero, morning-briefing
+
+**Daily Workflow:**
+1. Run `morning-briefing` for ticket overview
+2. Process inbox with label-based triage
+3. Reply to open tickets
+4. Escalate via Chat for urgent issues
+5. Create follow-up tasks for pending items

package/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/workspace-config.json

@@ -0,0 +1,61 @@
+{
+  "_comment": "Google Workspace CLI automation config template. Copy and customize for your environment.",
+  "auth": {
+    "method": "oauth",
+    "client_id": "",
+    "client_secret": "",
+    "token_path": "~/.config/gws/token.json",
+    "service_account_key": "",
+    "delegated_user": ""
+  },
+  "defaults": {
+    "output_format": "json",
+    "pagination_limit": 100,
+    "timeout_ms": 30000,
+    "log_level": "warn"
+  },
+  "persona": "developer",
+  "scopes": [
+    "gmail.modify",
+    "gmail.send",
+    "drive.file",
+    "drive.metadata.readonly",
+    "spreadsheets",
+    "calendar",
+    "calendar.events",
+    "tasks"
+  ],
+  "scheduled_tasks": [
+    {
+      "name": "morning-briefing",
+      "recipe": "morning-briefing",
+      "schedule": "0 8 * * 1-5",
+      "output": "~/workspace-reports/morning-{date}.json"
+    },
+    {
+      "name": "eod-wrap",
+      "recipe": "eod-wrap",
+      "schedule": "0 17 * * 1-5",
+      "output": "~/workspace-reports/eod-{date}.json"
+    },
+    {
+      "name": "weekly-summary",
+      "recipe": "weekly-summary",
+      "schedule": "0 9 * * 5",
+      "output": "~/workspace-reports/weekly-{date}.json"
+    },
+    {
+      "name": "security-audit",
+      "command": "python3 scripts/workspace_audit.py --json",
+      "schedule": "0 10 * * 1",
+      "output": "~/workspace-reports/audit-{date}.json"
+    }
+  ],
+  "aliases": {
+    "inbox": "gws gmail users.messages list me --query 'is:inbox' --limit 20 --json",
+    "unread": "gws gmail users.messages list me --query 'is:unread' --limit 20 --json",
+    "files": "gws drive files list --limit 20 --json",
+    "events": "gws calendar events list primary --timeMin $(date -u +%Y-%m-%dT%H:%M:%SZ) --maxResults 10 --json",
+    "tasks": "gws tasks tasks list @default --json"
+  }
+}