Publishing and Versioning

# Authenticate (one-time)
noorle login --api-key YOUR_API_KEY

# Upload plugin
noorle plugin push

# With specific API key
noorle plugin push --api-key YOUR_API_KEY

# Push to specific account
noorle plugin push --account-id YOUR_ACCOUNT_ID

✓ Uploading plugin...
  Plugin ID: 550e8400-e29b-41d4-a716-446655440000
  Name: my-plugin
  Active Version: v1
  File Size: 245KB
  Tools: greet, add, multiply
  Uploaded: 2024-03-22 10:30:45 UTC

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-plugin",
  "description": "Does useful things",
  "namespace": "account:550e8400",
  "active_version": 1,
  "versions": [
    {
      "version_number": 1,
      "created_at": "2024-03-22T10:30:45Z",
      "tools": [
        {
          "name": "greet",
          "description": "Greet a person"
        },
        {
          "name": "add",
          "description": "Add two numbers"
        }
      ],
      "metadata": {
        "author": "Your Name",
        "license": "MIT",
        "tags": ["data-processing"]
      }
    }
  ]
}

my-plugin Capability
├── v1 (archived)     - Original version
├── v2 (archived)     - Improved version
└── v3 (active)       - Current active version

# Modify your code
# ... update src/tools.rs ...

# Build with new version
noorle plugin build

# Push new version
noorle plugin push

# Output shows version 2:
# ✓ Uploading plugin...
#   Active Version: v2

noorle plugin activate my-plugin --version 1

# Output:
# ✓ Activated version 1
# ✓ Active version: v1

noorle plugin info my-plugin

# Output:
# Plugin: my-plugin (ID: 550e8400)
#
# Active Version: v3
#
# Version History:
#   v3 (current, 2024-03-22T12:00:00Z)
#     - 3 tools
#     - Author: Your Name
#     - 234KB
#
#   v2 (archived, 2024-03-22T11:00:00Z)
#     - 3 tools
#     - 232KB
#
#   v1 (archived, 2024-03-22T10:00:00Z)
#     - 2 tools
#     - 220KB

# noorle.yaml
metadata:
  name: "my-plugin"
  version: "1.2.0"
  # ...

git tag -a v1.2.0 -m "Release 1.2.0: Add search capability"
git push origin v1.2.0

# Update your code with breaking changes
# ...

# Increment MAJOR in package version
# In Cargo.toml, package.json, etc.

noorle plugin push
# Creates v4 (breaking change from v3)

BREAKING CHANGES in v4:
- Renamed tool 'get_data' to 'fetch_data'
- Changed return type from string to JSON object
- Removed deprecated 'legacy_mode' parameter

Migration guide:
1. Replace get_data calls with fetch_data
2. Update code expecting string returns
3. Remove legacy_mode from configuration

# Checkout v2 branch
git checkout v2-maintenance

# Apply fix
git commit -m "Fix critical bug in v2"

# Build from v2 source
noorle plugin push

# Creates v2.1 (patch version)
# Users on v2 can upgrade to v2.1

noorle plugin activate my-plugin --version 2

# All agents/gateways immediately use v2
# v3 still available if you want to fix and re-activate

# Create agent pointing to v2 (stable)
noorle agent create my-agent --plugin-version 2

# Create staging agent for v3
noorle agent create my-agent-staging --plugin-version 3

# Test v3 in staging
# If successful, activate v3 globally
# If issues found, v2 remains for prod

noorle plugin deprecate my-plugin --version 1 \
  --sunset-date "2024-12-31" \
  --replacement-version 3

# Output:
# ✓ Version v1 marked deprecated
# ✓ Sunset date: 2024-12-31
# ✓ Users directed to upgrade to v3

noorle plugin retire my-plugin --version 1

# v1 no longer available
# Agents using v1 fail until upgraded to v2+

noorle plugin share my-plugin \
  --account-id OTHER_ACCOUNT_ID \
  --access read-only

# Other account can use but not modify

# Only allow v3
noorle plugin grant my-plugin \
  --version 3 \
  --account-id OTHER_ACCOUNT \
  --access execute

# Older versions hidden from other account

noorle plugin notes set my-plugin --version 3 \
  "Release 1.3.0

Improvements:
- Added search_items tool for faster queries
- Optimized memory usage (reduced from 512MB to 256MB)
- Fixed timezone handling bug

Breaking Changes:
- Renamed get_data to fetch_data
- Changed return type for batch operations

Migration:
See /learn/concepts/capabilities for more information"

# Version History

## v1.3.0 (2024-03-22)
- New: Added search_items tool
- Fix: Timezone bug in date handling
- Change: Optimized memory usage

## v1.2.1 (2024-03-15)
- Fix: Handle null values in input

## v1.2.0 (2024-03-10)
- New: Added batch processing
- Change: Updated dependencies

noorle plugin analytics my-plugin

# Output:
# Version Usage (last 30 days):
#   v3: 1,250 invocations (85%)
#   v2:   220 invocations (15%)
#   v1:     0 invocations (0%)
#
# Performance:
#   v3: avg 234ms, p99 1.2s
#   v2: avg 240ms, p99 1.3s
#
# Errors:
#   v3: 0.02% error rate
#   v2: 0.05% error rate

# Check version logs
noorle plugin logs my-plugin --version 3 --tail 100

# See recent invocations
noorle plugin history my-plugin --limit 50

# Get error details
noorle plugin errors my-plugin --since 1h