@owlmetry/cli 0.1.0

package/dist/skills/owlmetry-swift/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: owlmetry-swift
+version: 0.1.0
+description: >-
+  Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
+  event tracking, metrics, funnels, and A/B experiments. Use when
+  instrumenting a Swift or SwiftUI project with OwlMetry.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+## What is OwlMetry?
+
+OwlMetry is a self-hosted analytics platform. The Swift SDK captures events from iOS, iPadOS, and macOS apps and delivers them to the OwlMetry server. It handles buffering, gzip compression, offline queuing, session management, and network monitoring automatically — you just call logging methods and the SDK takes care of delivery.
+
+The SDK is a static `Owl` enum with no external dependencies. All calls are non-blocking (events are buffered and flushed in batches). A single `configure()` call initialises everything.
+
+## Version Check
+
+Run these checks silently. Only inform the user if updates are available.
+
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+2. **SDK version**: Read `Package.resolved` for the current resolved revision, then compare against `curl -sf https://api.github.com/repos/Jasonvdb/owlmetry/releases/latest | jq -r .tag_name`. If newer, inform the user.
+
+## Prerequisite
+
+You need an OwlMetry endpoint URL and a `client_key` (starts with `owl_client_...`) for an app with `platform: apple`.
+
+If the user doesn't have these yet, invoke `/owlmetry-cli` first to:
+1. Sign up or log in
+2. Create a project (if needed)
+3. Create an app with `--platform apple --bundle-id <bundle-id>`
+4. Note the `client_key` from the app creation response
+
+## Add Swift Package
+
+**Swift Package Manager (Package.swift):**
+```swift
+dependencies: [
+    .package(url: "https://github.com/Jasonvdb/owlmetry.git", branch: "main")
+]
+```
+Add to your target:
+```swift
+.target(name: "YourApp", dependencies: [
+    .product(name: "OwlMetry", package: "owlmetry")
+])
+```
+
+**Xcode:** File > Add Package Dependencies > enter `https://github.com/Jasonvdb/owlmetry.git`, select branch `main`, add `OwlMetry` to your target.
+
+**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+
+## Configure
+
+Configuration must happen once, before any other `Owl` calls — typically in your `@main` App init or AppDelegate `didFinishLaunching`. Each `configure()` call generates a fresh `session_id` (UUID) that groups all subsequent events together. This means each app launch gets its own session, making it easy to see everything a user did in a single sitting.
+
+```swift
+import OwlMetry
+
+@main
+struct MyApp: App {
+    init() {
+        do {
+            try Owl.configure(
+                endpoint: "https://ingest.owlmetry.com",
+                apiKey: "owl_client_..."
+            )
+        } catch {
+            print("OwlMetry configuration failed: \(error)")
+        }
+    }
+    // ...
+}
+```
+
+**Parameters:**
+- `endpoint: String` — server URL (required)
+- `apiKey: String` — client key, must start with `owl_client_` (required)
+- `flushOnBackground: Bool` — auto-flush when app backgrounds (default: `true`)
+- `compressionEnabled: Bool` — gzip request bodies (default: `true`)
+
+Auto-detects: bundle ID, debug mode (`#if DEBUG`). Auto-generates: session ID (fresh each launch).
+
+## Log Events
+
+Events are the core unit of data in OwlMetry. Use the four log levels to capture different kinds of information:
+
+- **`info`** — normal operations worth recording: screen views, user actions, feature usage, successful completions. This is your default level.
+- **`debug`** — verbose detail useful only during development: cache hits, state transitions, intermediate values. These are filtered out in production data mode.
+- **`warn`** — something unexpected that the app recovered from: slow responses, fallback paths taken, retries needed.
+- **`error`** — something failed: network errors, parse failures, missing data, caught exceptions.
+
+Choose **message strings** that are specific and searchable. Prefer `"Failed to load profile image"` over `"error"`. Use `screenName` to tie events to where they happened in the UI. Use `customAttributes` for structured data you'll want to filter or search on later.
+
+```swift
+Owl.info("User opened settings", screenName: "SettingsView")
+Owl.debug("Cache hit", screenName: "HomeView", customAttributes: ["key": "user_prefs"])
+Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200"])
+Owl.error("Failed to load profile", screenName: "ProfileView")
+```
+
+All logging methods share the same signature:
+```swift
+Owl.info(_ message: String, screenName: String? = nil, customAttributes: [String: String]? = nil)
+```
+
+Source file, function, and line are auto-captured.
+
+**Avoid logging PII** (emails, phone numbers, passwords) or high-frequency events (every frame, every scroll position). Focus on actions and outcomes.
+
+## User Identity
+
+Identity connects events to real users. Before `setUser()` is called, all events are tagged with an anonymous ID (`owl_anon_...`). After login, calling `setUser()` does two things:
+
+1. Tags all future events with the real user ID.
+2. Retroactively claims all previous anonymous events for that user (server-side), so you get a complete history.
+
+Call `setUser()` right after successful authentication. Call `clearUser()` on logout to revert to anonymous tracking.
+
+```swift
+// After login — claims all previous anonymous events
+Owl.setUser("user_123")
+
+// On logout — reverts to anonymous tracking
+Owl.clearUser()
+
+// On logout with fresh anonymous ID
+Owl.clearUser(newAnonymousId: true)
+```
+
+**Important:** The SDK automatically flushes buffered events before claiming identity.
+
+## Funnel Tracking
+
+Funnels measure how users progress through a multi-step flow (onboarding, checkout, activation) and where they drop off. The system has three parts:
+
+1. **Define** the funnel server-side (via CLI or API) with ordered steps and event filters.
+2. **Track** steps client-side with `Owl.track("step-name")` — each call emits an event with message `"track:step-name"`.
+3. **Query** analytics to see conversion rates and drop-off between steps.
+
+Choose step names that match the `event_filter` in your funnel definition. For example, if the step filter is `{"message": "track:welcome-screen"}`, then call `Owl.track("welcome-screen")`.
+
+Use `attributes` when you need to segment funnel analytics later (e.g., by signup method or referral source).
+
+```swift
+Owl.track("welcome-screen")
+Owl.track("create-account", attributes: ["method": "email"])
+Owl.track("complete-profile")
+Owl.track("first-post")
+```
+
+Each `track()` call emits an info-level event with message `"track:<stepName>"`. Define matching funnel definitions via `/owlmetry-cli`:
+```bash
+owlmetry funnels create --project <id> --name "Onboarding" --slug onboarding \
+  --steps '[{"name":"Welcome","event_filter":{"message":"track:welcome-screen"}},{"name":"Account","event_filter":{"message":"track:create-account"}},{"name":"Profile","event_filter":{"message":"track:complete-profile"}},{"name":"First Post","event_filter":{"message":"track:first-post"}}]' \
+  --format json
+```
+
+## Structured Metrics
+
+Use structured metrics instead of plain log events when you want aggregated statistics (averages, percentiles, error rates) rather than just a list of individual events. Metrics give you `p50`, `p95`, `p99` latencies, success/failure rates, and trend data over time.
+
+**Decision: lifecycle vs single-shot:**
+- **Lifecycle** — when you're measuring something with a duration (start → end). Examples: image upload, API call, video encoding, onboarding flow. The SDK auto-tracks `duration_ms`.
+- **Single-shot** — when you're recording a point-in-time value. Examples: app cold-start time, memory usage, items in cart at checkout.
+
+The metric definition must exist on the server **before** the SDK emits events for that slug. Create it via CLI first.
+
+### Lifecycle operations (start → complete/fail/cancel)
+
+```swift
+let op = Owl.startOperation("photo-upload", attributes: ["format": "heic"])
+
+// On success:
+op.complete(attributes: ["size_bytes": "524288"])
+
+// On failure:
+op.fail(error: "timeout", attributes: ["retry_count": "3"])
+
+// On cancellation:
+op.cancel(attributes: ["reason": "user_cancelled"])
+```
+
+`duration_ms` and `tracking_id` (UUID) are auto-added. Create the metric definition first:
+```bash
+owlmetry metrics create --project <id> --name "Photo Upload" --slug photo-upload --lifecycle --format json
+```
+
+### Single-shot measurements
+
+```swift
+Owl.recordMetric("app-cold-start", attributes: ["screen": "home"])
+```
+
+**Slug rules:** lowercase letters, numbers, hyphens only. Invalid slugs are auto-corrected with a console warning.
+
+## A/B Experiments
+
+OwlMetry provides lightweight client-side A/B testing. The flow is:
+
+1. **Assign a variant**: `getVariant("experiment-name", options: ["control", "variant-a"])` randomly picks a variant on first call.
+2. **Render conditionally**: use the returned variant string to show different UI.
+3. **Events are auto-tagged**: all subsequent events include the experiment assignment in their `experiments` field.
+4. **Analyse**: query funnel or metric data segmented by variant to compare performance.
+
+`getVariant()` persists the assignment in Keychain, so the same user always sees the same variant across launches. Use `setExperiment()` to force a specific variant (e.g., from a server-side feature flag system). Use `clearExperiments()` to reset all assignments (e.g., for testing).
+
+```swift
+// Random assignment on first call, persisted to Keychain thereafter
+let variant = Owl.getVariant("checkout-redesign", options: ["control", "variant-a", "variant-b"])
+
+// Force-set a variant (e.g., from server config)
+Owl.setExperiment("checkout-redesign", variant: "variant-a")
+
+// Clear all assignments
+Owl.clearExperiments()
+```
+
+- Assignments persist in Keychain (`com.owlmetry.experiments`).
+- All events automatically include an `experiments` field with current assignments.
+- Query funnel analytics segmented by variant via CLI: `owlmetry funnels query <slug> --project <id> --group-by experiment:checkout-redesign`
+
+## Instrumentation Strategy
+
+When instrumenting a new app, follow this priority:
+
+**Always instrument:**
+- App launch / cold start (`info` in `init()` or `didFinishLaunching`)
+- Key screen views (`info` with `screenName` in `onAppear`)
+- Authentication events (login, logout, signup)
+- Errors and failures (`error` in `catch` blocks, error handlers)
+- Core business actions (purchase, share, create, delete)
+
+**Instrument when relevant:**
+- Funnel steps for multi-step flows you want to optimize
+- Lifecycle metrics for operations where duration matters (uploads, loads, syncs)
+- A/B experiments when testing alternative UI or flows
+
+**Where to place calls:**
+- Screen views: `.onAppear` modifiers in SwiftUI, `viewDidAppear` in UIKit
+- User actions: button action handlers, gesture callbacks
+- Errors: `catch` blocks, `Result.failure` handlers
+- Metrics: wrap the async operation between `startOperation()` and `complete()`/`fail()`
+
+**What NOT to instrument:**
+- PII (emails, phone numbers, passwords, tokens)
+- Every UI interaction (every tap, every scroll)
+- High-frequency timer events
+- Sensitive business data (prices, payment details)
+
+## Lifecycle
+
+```swift
+// In your app's termination handler or ScenePhase .background
+await Owl.shutdown()
+```
+
+`flushOnBackground: true` (default) handles most cases automatically. Call `shutdown()` explicitly only if you need to guarantee delivery at a specific point.
+
+## Auto-Captured Data
+
+Every event automatically includes:
+- `session_id` — fresh UUID per `configure()` call
+- Device model, OS version, locale
+- `app_version`, `build_number` (from bundle)
+- `is_dev` — `true` in DEBUG builds
+- `_connection` — network type (wifi, cellular, ethernet, offline) via `NWPathMonitor`
+- `experiments` — current A/B experiment assignments
+- `environment` — specific runtime (ios, ipados, macos)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@owlmetry/cli",
+  "version": "0.1.0",
+  "description": "OwlMetry CLI — manage projects, apps, metrics, funnels, and events from the terminal. Includes AI skill files for agent-assisted development.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jasonvdb/owlmetry.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://owlmetry.com",
+  "bugs": "https://github.com/nicktechnolog/owlmetry/issues",
+  "keywords": [
+    "owlmetry",
+    "analytics",
+    "metrics",
+    "funnels",
+    "mobile",
+    "observability",
+    "cli",
+    "ai-skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "owlmetry": "dist/index.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:tsc": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@owlmetry/shared": "workspace:*",
+    "@types/node": "^25.4.0",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}