v0.4.8

nself v0.4.8 - Plugin System

Release Date: January 24, 2026 Status: Released

---

Overview

v0.4.8 "Plugin System" introduces a powerful extensibility framework for integrating third-party services:

• Plugin Architecture - Install, update, and manage plugins from a central registry
• Three Launch Plugins - Stripe, GitHub, and Shopify integrations ready to use
• Database Schemas - Each plugin creates prefixed tables for synced data
• Webhook Handlers - Real-time event processing with signature verification
• CLI Actions - Full command-line interface for managing plugin data

---

New Commands

nself plugin - Plugin Management

Manage third-party integrations with a unified plugin system:

# List available plugins
nself plugin list                      # All plugins
nself plugin list --installed          # Only installed
nself plugin list --category billing   # Filter by category

# Install and remove
nself plugin install stripe            # Install from registry
nself plugin install ./my-plugin       # Install local plugin
nself plugin remove stripe             # Remove plugin
nself plugin remove stripe --keep-data # Keep database tables

# Update
nself plugin update stripe             # Update specific plugin
nself plugin update --all              # Update all installed

# Status
nself plugin status                    # All plugins status
nself plugin status stripe             # Specific plugin health

Plugin Actions

Each plugin provides its own actions accessible via nself plugin <name> <action>:

# Stripe Plugin
nself plugin stripe sync               # Sync all data from Stripe
nself plugin stripe customers list     # List synced customers
nself plugin stripe subscriptions list # View subscriptions
nself plugin stripe invoices list      # View invoices
nself plugin stripe webhook list       # View webhook events

# GitHub Plugin
nself plugin github sync               # Sync repositories
nself plugin github repos list         # List repositories
nself plugin github issues list        # View issues
nself plugin github prs list           # View pull requests
nself plugin github workflows list     # View GitHub Actions runs

# Shopify Plugin
nself plugin shopify sync              # Sync store data
nself plugin shopify products list     # List products
nself plugin shopify orders list       # View orders
nself plugin shopify customers list    # View customers

---

Available Plugins

Stripe Plugin (Billing)

Sync payment processing data from Stripe:

Table	Description
stripe_customers	Customer records
stripe_products	Product catalog
stripe_prices	Pricing tiers
stripe_subscriptions	Active subscriptions
stripe_invoices	Invoice history
stripe_payment_intents	Payment attempts
stripe_payment_methods	Saved payment methods
stripe_webhook_events	Webhook event log

Configuration:

STRIPE_API_KEY=sk_test_PLACEHOLDER           # Required
STRIPE_WEBHOOK_SECRET=whsec_xxxxx      # For webhooks

GitHub Plugin (DevOps)

Sync repository and CI data from GitHub:

Table	Description
github_repositories	Repository metadata
github_issues	Issues with labels
github_pull_requests	PRs with merge info
github_commits	Commit history
github_releases	Release tags
github_workflow_runs	GitHub Actions runs
github_deployments	Deployment status
github_webhook_events	Webhook event log

Configuration:

GITHUB_TOKEN=ghp_xxxxx                 # Required (PAT)
GITHUB_WEBHOOK_SECRET=xxxxx            # For webhooks
GITHUB_ORG=myorg                       # Or GITHUB_REPOS=owner/repo

Shopify Plugin (E-commerce)

Sync store data from Shopify:

Table	Description
shopify_shops	Store metadata
shopify_products	Product catalog
shopify_variants	Product variants
shopify_collections	Collections
shopify_customers	Customer data
shopify_orders	Order history
shopify_order_items	Line items
shopify_inventory	Inventory levels
shopify_webhook_events	Webhook event log

Configuration:

SHOPIFY_STORE=your-store               # Required
SHOPIFY_ACCESS_TOKEN=shpat_xxxxx       # Required
SHOPIFY_WEBHOOK_SECRET=xxxxx           # For webhooks

---

Plugin Architecture

Directory Structure

Installed plugins are stored in ~/.nself/plugins/:

~/.nself/plugins/
├── _shared/                   # Shared utilities
│   ├── plugin-utils.sh
│   ├── schema-sync.sh
│   └── webhook-handler.sh
├── stripe/
│   ├── plugin.json            # Plugin manifest
│   ├── install.sh
│   ├── uninstall.sh
│   ├── schema/tables.sql
│   ├── actions/
│   │   ├── sync.sh
│   │   ├── customers.sh
│   │   └── webhook.sh
│   └── webhooks/
│       ├── handler.sh
│       └── events/
└── ...

Plugin Manifest (plugin.json)

{
  "name": "stripe",
  "version": "1.0.0",
  "description": "Stripe payment processing integration",
  "category": "billing",
  "minNselfVersion": "0.4.8",
  "envVars": {
    "required": ["STRIPE_API_KEY"],
    "optional": ["STRIPE_WEBHOOK_SECRET"]
  },
  "tables": ["stripe_customers", "stripe_products", ...],
  "webhooks": ["customer.created", "invoice.paid", ...],
  "actions": {
    "sync": "Sync all Stripe data",
    "customers": "Manage customers"
  }
}

Webhook Integration

Plugins receive webhooks at standardized endpoints:

https://your-domain.com/webhooks/stripe
https://your-domain.com/webhooks/github
https://your-domain.com/webhooks/shopify

All webhooks are verified using HMAC-SHA256 signatures before processing.

---

Plugin Registry

Two-Tier Architecture

nself uses a two-tier registry system for maximum reliability:

Primary: plugins.nself.org

• Cloudflare Worker-based API
• KV storage for caching
• Sub-second response times globally
• Automatic updates via GitHub Actions

Fallback: GitHub

• Raw file access from nself-plugins repo
• Used when primary is unavailable
• Stale cache as last resort

Registry Endpoints

https://plugins.nself.org/registry.json     # Full registry
https://plugins.nself.org/plugins/:name     # Plugin info
https://plugins.nself.org/plugins/:name/:v  # Specific version
https://plugins.nself.org/health            # Health check
https://plugins.nself.org/categories        # Category list

Registry Commands

# Refresh registry cache
nself plugin refresh

# Check for plugin updates
nself plugin updates

# Show registry metadata
nself plugin refresh --info

Local Caching

Registry data is cached locally:

• Cache TTL: 5 minutes (configurable via NSELF_REGISTRY_CACHE_TTL)
• Cache directory: ~/.nself/cache/plugins/
• Stale cache used when registry unavailable

---

Environment Variables

Plugin System Variables

Variable	Description	Default
NSELF_PLUGIN_DIR	Plugin installation directory	~/.nself/plugins
NSELF_PLUGIN_REGISTRY	Custom registry URL	Official registry

Per-Plugin Variables

See individual plugin documentation for required environment variables.

---

Shell Completion

Tab completion now supports plugin commands:

nself plugin <TAB>        # list, install, remove, update, status, stripe, github, shopify
nself plugin stripe <TAB> # sync, customers, subscriptions, invoices, webhook

Update completions:

nself completion install bash
nself completion install zsh

---

Breaking Changes

None. All existing commands remain functional.

---

Technical Details

Cross-Platform Compatibility

All plugin scripts are:

• Bash 3.2 compatible (works on macOS default)
• POSIX-compliant output (using printf, not echo -e)
• Platform-aware stat commands with proper detection

Database Operations

Plugins use the shared database utilities:

• plugin_db_query() - Execute SQL via Docker or local psql
• plugin_db_exec_file() - Execute SQL files
• plugin_table_exists() - Check for table existence

API Rate Limiting

Each plugin implements rate limiting:

• Stripe: 0.5s delay between requests
• GitHub: 0.1s delay (respects X-RateLimit headers)
• Shopify: 0.5s delay (2 req/sec limit)

---

Installation

# Update nself
nself update

# Verify version
nself version

# Install a plugin
nself plugin install stripe

---

Documentation

• Plugin Command Reference
• Plugin Overview
• Stripe Plugin
• GitHub Plugin
• Shopify Plugin

---

What's Next

• v0.4.9 - Extensive Polish & Testing
• v0.5.0 - Production Ready LTS + nself-admin v0.1

---

For detailed documentation on each command, see the Commands Reference.