@skyvexsoftware/stratos-sdk 0.1.10 → 0.1.12

package/README.md

@@ -42,7 +42,7 @@ my-plugin/
 │   │   ├── index.tsx     # UI entry (default export: React component)
 │   │   └── global.css    # Tailwind CSS
 │   └── background/       # Optional: main process module
-│       └── index.ts      # Exports onStart(ctx) and onStop()
+│       └── index.ts      # export default createPlugin({...})
 └── assets/
     ├── icon-light.svg    # Sidebar icon (dark theme)
     └── icon-dark.svg     # Sidebar icon (light theme)
@@ -77,7 +77,7 @@ The `vite` option accepts any Vite config to merge in (plugins, resolve, css, et
 
 ## Plugin Manifest
 
-`plugin.json` defines your plugin's metadata:
+`plugin.json` defines your plugin's metadata. Background modules don't need manifest configuration — the shell discovers them automatically if `background/index.js` exists in the built output.
 
 ```json
 {
@@ -87,7 +87,7 @@ The `vite` option accepts any Vite config to merge in (plugins, resolve, css, et
   "name": "My Plugin",
   "version": "0.1.0",
   "description": "A Stratos plugin",
-  "author": { "id": "my-org", "name": "My Organization" },
+  "author": { "id": "my-org", "name": "My Organisation" },
   "icon_light": "icon-light.svg",
   "icon_dark": "icon-dark.svg"
 }
@@ -110,7 +110,7 @@ function MyComponent() {
     pluginId,
     auth,        // { isAuthenticated, token, user }
     airline,     // { id, name, icao, logo_light, logo_dark }
-    config,      // { get(key, defaultValue) }
+    config,      // { get(key, defaultValue?) } — airline-scoped settings
     navigation,  // { navigateTo, navigateToPlugin, navigateToShell }
     toast,       // { success, error, info, warning }
     logger,      // { info, warn, error, debug }
@@ -120,84 +120,90 @@ function MyComponent() {
 
 Individual hooks are also available:
 
-| Hook                   | Returns              | Description                    |
-| ---------------------- | -------------------- | ------------------------------ |
-| `usePluginContext()`   | Full PluginUIContext | All services combined          |
-| `useShellAuth()`       | Auth state           | Authentication state and token |
-| `useShellConfig()`     | Config store         | Scoped configuration access    |
-| `useShellNavigation()` | Navigation helpers   | Route navigation utilities     |
-| `useShellToast()`      | Toast API            | Toast/notification functions   |
-| `usePluginLogger()`    | Logger               | Scoped renderer-side logger    |
+| Hook                   | Description                                    |
+| ---------------------- | ---------------------------------------------- |
+| `usePluginContext()`   | All shell services combined                    |
+| `useSimData()`         | Real-time simulator data (RAF-throttled)       |
+| `useFlightPhase()`     | Current flight phase with selector support     |
+| `useFlightEvents()`    | Flight event log with comment mutations        |
+| `useFlightManager()`   | Low-level flight lifecycle control             |
+| `useTrackingSession()` | High-level tracking state with derived fields  |
+| `useLandingAnalysis()` | Landing rate, bounces, and settled analysis    |
+| `useShellAuth()`       | Authentication state and token                 |
+| `useShellConfig()`     | Scoped configuration access                    |
+| `useShellNavigation()` | Route navigation utilities                     |
+| `useShellToast()`      | Toast/notification functions                   |
+| `usePluginLogger()`    | Scoped renderer-side logger                    |
 
 ### Background Module
 
-Optional main-process code with access to IPC, Express routes, SQLite, and more:
+Optional main-process code with access to IPC, Express routes, SQLite, and more. Must use the `createPlugin` helper (imported from the `/helpers` subpath) with a default export:
 
 ```ts
-import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+import { createPlugin } from "@skyvexsoftware/stratos-sdk/helpers";
 
 export default createPlugin({
   async onStart(ctx) {
-    // ctx.logger  — scoped logger
-    // ctx.config  — per-plugin config store
-    // ctx.ipc     — IPC handler registration
-    // ctx.auth    — read-only auth token access
-    // ctx.server  — Express router registration
+    // ctx.logger   — scoped logger
+    // ctx.config   — per-plugin config store (async)
+    // ctx.ipc      — IPC handler registration
+    // ctx.auth     — read-only auth token access (async)
+    // ctx.server   — Express router registration
     // ctx.database — SQLite database access
     ctx.logger.info("MyPlugin", "Started");
   },
-  async onStop() {
-    // cleanup
+  async onStop(ctx) {
+    ctx.logger.info("MyPlugin", "Stopped");
   },
 });
 ```
 
-### Routing
+Named exports are not supported — the shell requires the `createPlugin` default export pattern for type safety and validation.
 
-For multi-page plugins, use `PluginRouter`:
-
-```tsx
-import { PluginRouter } from "@skyvexsoftware/stratos-sdk";
+### UI Components
 
-const routes = [
-  { path: "home", component: HomePage },
-  { path: "settings", component: SettingsPage },
-  { path: "detail/:id", component: DetailPage },
-];
+Pre-styled shadcn/ui components that match the Stratos design system:
 
-export default function Plugin() {
-  return <PluginRouter routes={routes} defaultPath="home" />;
-}
+```tsx
+import { Button, Card, CardContent, Input, Dialog } from "@skyvexsoftware/stratos-sdk";
 ```
 
-For single-page plugins, just export the component directly.
+Available: Button, Card, Dialog, Input, Label, Select, Badge, Separator, Tabs, Tooltip, AlertDialog, RadioGroup, Slider, Switch, Textarea.
 
-### UI Components
+### Icons
 
-Pre-styled shadcn/ui components that match the Stratos design system:
+The full [Lucide](https://lucide.dev) icon set is available via `STRATOS_ICONS`:
 
 ```tsx
-import { Button, Card, CardContent, Input, Dialog } from "@skyvexsoftware/stratos-sdk";
+import { STRATOS_ICONS, STRATOS_ICON_NAMES } from "@skyvexsoftware/stratos-sdk";
+
+const Icon = STRATOS_ICONS["Helicopter"];
 ```
 
-Available: Button, Card, Dialog, Input, Label, Select, Badge, Separator, Tabs, Tooltip, AlertDialog, RadioGroup, Slider, Switch, Textarea.
+Or import icons directly from `lucide-react` in your plugin.
 
 ### Types
 
 ```ts
-import { FlightPhase, SimulatorType } from "@skyvexsoftware/stratos-sdk";
+import { FlightPhase, EventCategory } from "@skyvexsoftware/stratos-sdk";
 import type { FlightData, PluginManifest, PluginContext } from "@skyvexsoftware/stratos-sdk";
 ```
 
 ### Utilities
 
 ```ts
-import { cn } from "@skyvexsoftware/stratos-sdk";
-
 // Tailwind class merging
+import { cn } from "@skyvexsoftware/stratos-sdk";
 cn("bg-red-500", isActive && "text-white", className);
+
+// Unit conversion helpers
+import { weightFromLbs, formatAltitude } from "@skyvexsoftware/stratos-sdk/helpers";
 ```
 
-## License
+## Documentation
+
+Full documentation is available at [docs.skyvexsoftware.com](https://docs.skyvexsoftware.com).
+
+## Licence
 
 MIT

package/dist/bin/deploy.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * stratos-deploy — Bundle and upload a Stratos plugin.
+ *
+ * Zips dist/ into bundle.zip. If SKYVEX_API_TOKEN is set, uploads to the
+ * Skyvex API. Otherwise outputs the zip path for manual upload.
+ *
+ * Usage:
+ *   stratos-deploy          # from plugin root after pnpm build
+ *   pnpm bundle             # if package.json has "bundle": "pnpm build && stratos-deploy"
+ */
+export {};
+//# sourceMappingURL=deploy.d.ts.map

package/dist/bin/deploy.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * stratos-deploy — Bundle and upload a Stratos plugin.
+ *
+ * Zips dist/ into bundle.zip. If SKYVEX_API_TOKEN is set, uploads to the
+ * Skyvex API. Otherwise outputs the zip path for manual upload.
+ *
+ * Usage:
+ *   stratos-deploy          # from plugin root after pnpm build
+ *   pnpm bundle             # if package.json has "bundle": "pnpm build && stratos-deploy"
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import * as https from "https";
+import * as http from "http";
+const API_BASE = "https://skyvexsoftware.com/api/stratos";
+// ── Helpers ──────────────────────────────────────────────────────────
+function fatal(message) {
+    console.error(`\n  Error: ${message}\n`);
+    process.exit(1);
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} kB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+// ── Validation ───────────────────────────────────────────────────────
+function validateBuild(cwd) {
+    const distDir = path.join(cwd, "dist");
+    const manifestPath = path.join(distDir, "plugin.json");
+    if (!fs.existsSync(manifestPath)) {
+        fatal("No built plugin found. Run pnpm build first.");
+    }
+    const uiEntry = path.join(distDir, "ui", "index.js");
+    if (!fs.existsSync(uiEntry)) {
+        fatal("Build output incomplete — missing ui/index.js");
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    if (!manifest.id || !manifest.version) {
+        fatal("plugin.json missing required fields: id, version");
+    }
+    return {
+        id: manifest.id,
+        version: manifest.version,
+        name: manifest.name ?? manifest.id,
+    };
+}
+// ── Zip ──────────────────────────────────────────────────────────────
+function createBundle(cwd) {
+    const bundlePath = path.join(cwd, "bundle.zip");
+    // Remove stale bundle
+    if (fs.existsSync(bundlePath)) {
+        fs.unlinkSync(bundlePath);
+    }
+    try {
+        execSync("zip -r ../bundle.zip .", {
+            cwd: path.join(cwd, "dist"),
+            stdio: "pipe",
+        });
+    }
+    catch {
+        fatal("Failed to create bundle.zip. Ensure 'zip' is installed.");
+    }
+    return bundlePath;
+}
+// ── Upload ───────────────────────────────────────────────────────────
+function upload(pluginId, version, bundlePath, token) {
+    return new Promise((resolve) => {
+        const boundary = `----StratosDeploy${Date.now()}`;
+        const fileContent = fs.readFileSync(bundlePath);
+        const parts = [];
+        // Version field
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="version"\r\n\r\n${version}\r\n`));
+        // File field
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="bundle.zip"\r\nContent-Type: application/zip\r\n\r\n`));
+        parts.push(fileContent);
+        parts.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+        const body = Buffer.concat(parts);
+        const url = new URL(`${API_BASE}/plugins/${pluginId}/versions`);
+        const options = {
+            hostname: url.hostname,
+            port: url.port || 443,
+            path: url.pathname,
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": body.length,
+                Accept: "application/json",
+            },
+        };
+        const transport = url.protocol === "https:" ? https : http;
+        const req = transport.request(options, (res) => {
+            let data = "";
+            res.on("data", (chunk) => (data += chunk.toString()));
+            res.on("end", () => resolve({
+                ok: res.statusCode === 201,
+                status: res.statusCode ?? 0,
+                body: data,
+            }));
+        });
+        req.on("error", (err) => resolve({ ok: false, status: 0, body: err.message }));
+        req.write(body);
+        req.end();
+    });
+}
+// ── Main ─────────────────────────────────────────────────────────────
+async function main() {
+    const cwd = process.cwd();
+    const { id, version, name } = validateBuild(cwd);
+    const bundlePath = createBundle(cwd);
+    const bundleSize = fs.statSync(bundlePath).size;
+    console.log(`\n  ${name} v${version} — bundle.zip (${formatSize(bundleSize)})`);
+    const token = process.env.SKYVEX_API_TOKEN;
+    if (token) {
+        console.log("  Uploading to Skyvex...");
+        const result = await upload(id, version, bundlePath, token);
+        if (result.ok) {
+            console.log("  Published! Server is signing and publishing to CDN.\n");
+            fs.unlinkSync(bundlePath);
+        }
+        else if (result.status === 422) {
+            try {
+                const errors = JSON.parse(result.body);
+                const messages = errors.errors
+                    ? Object.values(errors.errors).flat().join(", ")
+                    : (errors.message ?? result.body);
+                fatal(`Validation failed: ${messages}`);
+            }
+            catch {
+                fatal(`Validation failed (${result.status}): ${result.body}`);
+            }
+        }
+        else if (result.status === 401) {
+            fatal("Authentication failed. Check your SKYVEX_API_TOKEN.");
+        }
+        else if (result.status === 403) {
+            fatal("Permission denied. You do not own this plugin.");
+        }
+        else {
+            fatal(`Upload failed (${result.status}): ${result.body}`);
+        }
+    }
+    else {
+        console.log("  No SKYVEX_API_TOKEN found.");
+        console.log("  Upload manually at https://skyvexsoftware.com");
+        console.log("  Or set SKYVEX_API_TOKEN to deploy from the CLI\n");
+    }
+}
+main();
+//# sourceMappingURL=deploy.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyvexsoftware/stratos-sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Plugin SDK for Stratos — types, hooks, and UI components",
   "author": {
     "name": "Skyvex Software",
@@ -45,6 +45,9 @@
       "import": "./dist/vite/plugin-config.js"
     }
   },
+  "bin": {
+    "stratos-deploy": "./dist/bin/deploy.js"
+  },
   "files": [
     "dist",
     "!dist/**/*.map"
@@ -72,11 +75,11 @@
     "@radix-ui/react-tabs": "^1.1.0",
     "@radix-ui/react-tooltip": "^1.1.0",
     "@tanstack/react-query": "^5.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
     "class-variance-authority": "^0.7.0",
     "lucide-react": ">=0.300.0",
     "react": "^19.0.0",
     "socket.io-client": "^4.0.0",
-    "@vitejs/plugin-react": "^5.0.0",
     "vite": "^7.0.0"
   },
   "dependencies": {
@@ -96,9 +99,9 @@
     "@radix-ui/react-tabs": "^1.1.8",
     "@radix-ui/react-tooltip": "^1.1.12",
     "@types/react": "^19.1.2",
-    "class-variance-authority": "^0.7.1",
-    "lucide-react": "^0.503.0",
     "@vitejs/plugin-react": "^5.1.4",
+    "class-variance-authority": "^0.7.1",
+    "lucide-react": "^0.577.0",
     "socket.io-client": "^4.8.3",
     "typescript": "^5.8.3",
     "vite": "^7.3.1"