skedyul 0.2.137 → 0.2.139

package/README.md

@@ -240,6 +240,341 @@ Both adapters expose `getHealthStatus()`, returning:
 - `runtime`: string label (`dedicated` or `serverless`).
 - `tools`: list of registered tool names.
 
+---
+
+# Skedyul CLI
+
+The Skedyul CLI (`skedyul`) is a powerful command-line interface for developing, testing, and debugging Skedyul integration apps locally.
+
+## Quick Start
+
+```bash
+# 1. Authenticate with Skedyul
+skedyul auth login
+
+# 2. Navigate to your app directory
+cd packages/skedyul-integrations/integrations/my-app
+
+# 3. Link to a workplace
+skedyul dev link --workplace my-clinic
+
+# 4. Start the local development server
+skedyul dev serve --workplace my-clinic
+```
+
+That's it! The CLI will:
+- Prompt for any missing environment variables (API keys, credentials)
+- Start an ngrok tunnel automatically
+- Register your local machine with Skedyul
+- Route tool calls from Skedyul to your local server
+
+## Installation
+
+The CLI is included with the `skedyul` package:
+
+```bash
+npm install skedyul
+# or
+pnpm add skedyul
+```
+
+Run commands with `npx skedyul` or install globally:
+
+```bash
+npm link  # In the skedyul-node package directory
+skedyul --help
+```
+
+## Commands
+
+### Authentication
+
+```bash
+# Log in via browser OAuth
+skedyul auth login
+
+# Check authentication status
+skedyul auth status
+
+# Log out
+skedyul auth logout
+```
+
+### Configuration
+
+```bash
+# Set global configuration
+skedyul config set <key> <value>
+
+# Get a config value
+skedyul config get <key>
+
+# List all configuration
+skedyul config list
+```
+
+**Available config keys:**
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `defaultServer` | Skedyul server URL | `https://admin.skedyul.it` |
+| `ngrokAuthtoken` | Your ngrok authtoken for tunneling | - |
+
+### Development Commands
+
+#### `skedyul dev link`
+
+Links your local app to a Skedyul workplace. This creates a personal `local-{username}` AppVersion for testing.
+
+```bash
+skedyul dev link --workplace <subdomain>
+
+# Example
+skedyul dev link --workplace demo-clinic
+```
+
+**What it does:**
+- Creates (or finds) a `local-{username}` AppVersion in the target workplace
+- Creates an AppInstallation for your app in that workplace
+- Saves link configuration to `.skedyul/links/{subdomain}.json`
+
+#### `skedyul dev unlink`
+
+Removes a workplace link.
+
+```bash
+skedyul dev unlink --workplace <subdomain>
+```
+
+#### `skedyul dev serve`
+
+Starts a local MCP server for testing your tools.
+
+```bash
+# Standalone mode (no Skedyul connection)
+skedyul dev serve
+
+# Connected to Skedyul (sidecar mode)
+skedyul dev serve --workplace <subdomain>
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--workplace, -w` | Workplace subdomain (enables sidecar mode) |
+| `--port, -p` | Port to listen on (default: 60000, auto-increments if busy) |
+| `--registry, -r` | Path to registry file (auto-detected) |
+| `--no-tunnel` | Don't start ngrok tunnel |
+| `--tunnel-url` | Use existing tunnel URL |
+| `--env, -e` | Set environment variable (e.g., `--env KEY=VALUE`) |
+| `--env-file` | Load env vars from file |
+
+**Sidecar Mode:**
+
+When you specify `--workplace`, the CLI:
+1. Loads your link configuration
+2. Prompts for any missing required environment variables
+3. Starts an ngrok tunnel (or uses `--tunnel-url`)
+4. Registers the tunnel URL with Skedyul
+5. Sends heartbeats to keep the connection alive
+6. Routes incoming tool calls to your local server
+
+```bash
+# Full example with custom port
+skedyul dev serve --workplace demo-clinic --port 8080
+
+# Use existing ngrok tunnel
+skedyul dev serve --workplace demo-clinic --tunnel-url https://abc123.ngrok.io
+```
+
+#### `skedyul dev invoke`
+
+Invoke a single tool for quick testing.
+
+```bash
+skedyul dev invoke <tool-name> [options]
+
+# Examples
+skedyul dev invoke appointment_types_list
+skedyul dev invoke clients_search --args '{"phone": "+1234567890"}'
+
+# With linked credentials
+skedyul dev invoke appointment_types_list --workplace demo-clinic
+```
+
+#### `skedyul dev tools`
+
+List all tools in your registry.
+
+```bash
+skedyul dev tools
+skedyul dev tools --registry ./dist/registry.js
+```
+
+#### `skedyul dev validate`
+
+Validate your `skedyul.config.ts` file.
+
+```bash
+skedyul dev validate
+```
+
+#### `skedyul dev diff`
+
+Preview what would change on deploy.
+
+```bash
+skedyul dev diff
+```
+
+## Configuration Files
+
+The CLI uses several configuration files:
+
+| File | Purpose |
+|------|---------|
+| `~/.skedyul/credentials.json` | Authentication tokens |
+| `~/.skedyul/config.json` | Global configuration (server URL, ngrok token) |
+| `.skedyul.local.json` | Local project overrides (e.g., local server URL) |
+| `.skedyul/links/{workplace}.json` | Per-workplace link configuration |
+| `.skedyul/env/{workplace}.env` | Per-workplace environment variables |
+
+### Local Development Override
+
+To use a local Skedyul server during development, create `.skedyul.local.json` in your project root:
+
+```json
+{
+  "serverUrl": "http://localhost:3000"
+}
+```
+
+## Environment Variables
+
+### Install Configuration
+
+Define required environment variables in your app's `config/install.config.ts`:
+
+```typescript
+import type { InstallConfig } from 'skedyul'
+
+const config: InstallConfig = {
+  env: {
+    API_KEY: {
+      label: 'API Key',
+      required: true,
+      visibility: 'encrypted',
+      description: 'Your API key for authentication',
+    },
+    BASE_URL: {
+      label: 'Server URL',
+      required: true,
+      visibility: 'visible',
+      placeholder: 'https://api.example.com',
+      description: 'Base URL for the API',
+    },
+  },
+}
+
+export default config
+```
+
+The CLI will automatically prompt for these when you run `skedyul dev serve --workplace <name>` if they're not already configured.
+
+### Visibility Options
+
+| Visibility | Behavior |
+|------------|----------|
+| `visible` | Shown in plain text |
+| `encrypted` | Hidden during input, masked in output |
+
+## Ngrok Integration
+
+The CLI uses ngrok to create public tunnels to your local server, allowing Skedyul to route requests to your machine.
+
+### Setup
+
+1. Get a free authtoken at [ngrok.com](https://dashboard.ngrok.com/get-started/your-authtoken)
+2. The CLI will prompt for it on first use, or set it manually:
+
+```bash
+skedyul config set ngrokAuthtoken <your-token>
+```
+
+### Session Limits
+
+ngrok's free tier allows 1 simultaneous session. If you see an error:
+
+```
+ngrok free tier only allows 1 simultaneous session.
+```
+
+**Solutions:**
+1. Kill other ngrok sessions: `pkill -f ngrok`
+2. Use an existing tunnel: `skedyul dev serve --workplace demo --tunnel-url https://existing.ngrok.io`
+3. Upgrade to a paid ngrok plan
+
+## Workflow Example
+
+### Setting Up a New Integration
+
+```bash
+# 1. Navigate to your app
+cd integrations/my-app
+
+# 2. Authenticate
+skedyul auth login
+
+# 3. Link to your test workplace
+skedyul dev link --workplace staging-clinic
+
+# 4. Start development server (will prompt for env vars)
+skedyul dev serve --workplace staging-clinic
+
+# Server starts...
+# ✓ Loaded 12 tools from registry
+# ✓ Tunnel active: https://abc123.ngrok.io
+# ✓ Registered with Skedyul
+# Listening on http://localhost:60000
+```
+
+### Testing Individual Tools
+
+```bash
+# Quick test without full server
+skedyul dev invoke appointment_types_list --workplace staging-clinic
+
+# With arguments
+skedyul dev invoke calendar_slots_availability_list \
+  --workplace staging-clinic \
+  --args '{"calendar_names": ["Room 1"], "dates": ["2024-01-15"]}'
+```
+
+## Troubleshooting
+
+### "Not linked to {workplace}"
+
+Run `skedyul dev link --workplace {workplace}` first.
+
+### "Authentication required"
+
+Run `skedyul auth login` to authenticate.
+
+### Port already in use
+
+The CLI auto-increments from port 60000 if busy. Or specify: `--port 8080`
+
+### ngrok authentication failed
+
+Set your authtoken: `skedyul config set ngrokAuthtoken <token>`
+
+### Environment variables not loading
+
+Check that your `config/install.config.ts` exports the env configuration properly. Use `--debug` flag for verbose output.
+
+---
+
 ## Development
 
 - `npm run build` compiles the TypeScript sources into `dist/`.

package/dist/.build-stamp

@@ -1 +1 @@
-1770183335160
+1770350396098

package/dist/cli/commands/auth/index.d.ts

@@ -0,0 +1 @@
+export declare function authCommand(args: string[]): Promise<void>;

package/dist/cli/commands/auth/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authCommand = authCommand;
+const login_1 = require("./login");
+const logout_1 = require("./logout");
+const status_1 = require("./status");
+function printUsage() {
+    console.log(`
+SKEDYUL AUTH - Authentication Commands
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Manage your Skedyul CLI authentication.
+
+USAGE
+  $ skedyul auth <command> [options]
+
+COMMANDS
+  login     Authenticate with Skedyul via browser OAuth
+  logout    Clear stored credentials
+  status    Show current authentication status and linked workplaces
+
+HOW AUTHENTICATION WORKS
+  1. Run 'skedyul auth login'
+  2. Browser opens to Skedyul login page
+  3. After login, you're redirected back to CLI
+  4. Credentials saved to ~/.skedyul/credentials.json
+
+  Your CLI token is used for:
+  • Linking projects to workplaces
+  • Getting scoped API tokens for tool testing
+  • Managing local development environments
+
+EXAMPLES
+  # Login to production Skedyul
+  $ skedyul auth login
+
+  # Login to a specific server
+  $ skedyul auth login --server http://localhost:3000
+
+  # Check authentication status
+  $ skedyul auth status
+
+  # Logout and clear credentials
+  $ skedyul auth logout
+
+SERVER CONFIGURATION
+  Default server: https://admin.skedyul.it
+
+  Override with:
+  • --server flag on any command
+  • .skedyul.local.json in project root:
+    { "serverUrl": "http://localhost:3000" }
+
+CREDENTIAL STORAGE
+  Credentials: ~/.skedyul/credentials.json
+  Config:      ~/.skedyul/config.json
+
+  Credentials are stored with restrictive permissions (600).
+`);
+}
+async function authCommand(args) {
+    const subCommand = args[0];
+    if (!subCommand || subCommand === '--help' || subCommand === '-h') {
+        printUsage();
+        return;
+    }
+    const subArgs = args.slice(1);
+    switch (subCommand) {
+        case 'login':
+            await (0, login_1.loginCommand)(subArgs);
+            break;
+        case 'logout':
+            await (0, logout_1.logoutCommand)(subArgs);
+            break;
+        case 'status':
+            await (0, status_1.statusCommand)(subArgs);
+            break;
+        default:
+            console.error(`Unknown auth command: ${subCommand}`);
+            console.error(`Run 'skedyul auth --help' for usage information.`);
+            process.exit(1);
+    }
+}

package/dist/cli/commands/auth/login.d.ts

@@ -0,0 +1 @@
+export declare function loginCommand(args: string[]): Promise<void>;

package/dist/cli/commands/auth/login.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loginCommand = loginCommand;
+const utils_1 = require("../../utils");
+const auth_1 = require("../../utils/auth");
+function printHelp() {
+    console.log(`
+skedyul auth login - Authenticate with Skedyul
+
+Usage:
+  skedyul auth login [options]
+
+Options:
+  --server, -s      Skedyul server URL (default: https://app.skedyul.com)
+  --help, -h        Show this help message
+
+Examples:
+  # Login to production Skedyul
+  skedyul auth login
+
+  # Login to a local Skedyul instance
+  skedyul auth login --server http://localhost:3000
+`);
+}
+async function loginCommand(args) {
+    const { flags } = (0, utils_1.parseArgs)(args);
+    if (flags.help || flags.h) {
+        printHelp();
+        return;
+    }
+    // Check if already logged in
+    const existingCredentials = (0, auth_1.getCredentials)();
+    if (existingCredentials) {
+        console.log(`Already logged in as ${existingCredentials.email}`);
+        console.log(`Server: ${existingCredentials.serverUrl}`);
+        console.log(`\nRun 'skedyul auth logout' to log out first.`);
+        return;
+    }
+    // Get server URL
+    const serverUrl = (0, auth_1.getServerUrl)((flags.server || flags.s));
+    console.log(`Authenticating with ${serverUrl}...\n`);
+    try {
+        const result = await (0, auth_1.startOAuthCallback)(serverUrl);
+        // Save credentials
+        (0, auth_1.saveCredentials)({
+            token: result.token,
+            userId: result.userId,
+            username: result.username,
+            email: result.email,
+            serverUrl,
+            expiresAt: result.expiresAt,
+            createdAt: new Date().toISOString(),
+        });
+        // Save server as default
+        (0, auth_1.saveConfig)({ defaultServer: serverUrl });
+        console.log(`\n✓ Logged in as ${result.email}`);
+        console.log(`  Username: ${result.username}`);
+        console.log(`  Server: ${serverUrl}`);
+        console.log(`  Credentials saved to ~/.skedyul/credentials.json`);
+    }
+    catch (error) {
+        console.error(`\nAuthentication failed: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/auth/logout.d.ts

@@ -0,0 +1 @@
+export declare function logoutCommand(args: string[]): Promise<void>;

package/dist/cli/commands/auth/logout.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logoutCommand = logoutCommand;
+const utils_1 = require("../../utils");
+const auth_1 = require("../../utils/auth");
+function printHelp() {
+    console.log(`
+skedyul auth logout - Log out from Skedyul
+
+Usage:
+  skedyul auth logout [options]
+
+Options:
+  --help, -h    Show this help message
+
+This command clears your stored credentials from ~/.skedyul/credentials.json
+`);
+}
+async function logoutCommand(args) {
+    const { flags } = (0, utils_1.parseArgs)(args);
+    if (flags.help || flags.h) {
+        printHelp();
+        return;
+    }
+    const credentials = (0, auth_1.getCredentials)();
+    if (!credentials) {
+        console.log('Not logged in.');
+        return;
+    }
+    (0, auth_1.clearCredentials)();
+    console.log(`✓ Logged out from ${credentials.email}`);
+    console.log(`  Credentials removed from ~/.skedyul/credentials.json`);
+}

package/dist/cli/commands/auth/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(args: string[]): Promise<void>;

package/dist/cli/commands/auth/status.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("../../utils");
+const auth_1 = require("../../utils/auth");
+function printHelp() {
+    console.log(`
+skedyul auth status - Show authentication status
+
+Usage:
+  skedyul auth status [options]
+
+Options:
+  --help, -h    Show this help message
+
+Shows:
+  - Current logged in user
+  - Server URL
+  - Token expiration
+  - Linked workplaces (from .skedyul/links/)
+`);
+}
+async function statusCommand(args) {
+    const { flags } = (0, utils_1.parseArgs)(args);
+    if (flags.help || flags.h) {
+        printHelp();
+        return;
+    }
+    const credentials = (0, auth_1.getCredentials)();
+    console.log('Skedyul CLI Status');
+    console.log('─'.repeat(40));
+    if (!credentials) {
+        console.log('\nAuthentication: Not logged in');
+        console.log(`\nRun 'skedyul auth login' to authenticate.`);
+        return;
+    }
+    console.log('\nAuthentication:');
+    console.log(`  Email: ${credentials.email}`);
+    console.log(`  Username: ${credentials.username}`);
+    console.log(`  Server: ${credentials.serverUrl}`);
+    if (credentials.expiresAt) {
+        const expiresAt = new Date(credentials.expiresAt);
+        const now = new Date();
+        if (expiresAt < now) {
+            console.log(`  Token: Expired`);
+        }
+        else {
+            const diffMs = expiresAt.getTime() - now.getTime();
+            const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+            const diffHours = Math.floor((diffMs % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+            console.log(`  Token: Valid (expires in ${diffDays}d ${diffHours}h)`);
+        }
+    }
+    else {
+        console.log(`  Token: Valid (no expiration)`);
+    }
+    // Check for linked workplaces in current project
+    const linksDir = path.join(process.cwd(), '.skedyul', 'links');
+    if (fs.existsSync(linksDir)) {
+        const linkFiles = fs.readdirSync(linksDir).filter((f) => f.endsWith('.json'));
+        if (linkFiles.length > 0) {
+            console.log('\nLinked Workplaces (this project):');
+            for (const file of linkFiles) {
+                const subdomain = file.replace('.json', '');
+                try {
+                    const content = fs.readFileSync(path.join(linksDir, file), 'utf-8');
+                    const link = JSON.parse(content);
+                    console.log(`  - ${subdomain} (${link.appHandle})`);
+                }
+                catch {
+                    console.log(`  - ${subdomain} (error reading link file)`);
+                }
+            }
+        }
+        else {
+            console.log('\nNo workplaces linked in this project.');
+        }
+    }
+    else {
+        console.log('\nNo workplaces linked in this project.');
+    }
+    console.log(`\nRun 'skedyul dev link --workplace <subdomain>' to link a workplace.`);
+}

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * skedyul config command
+ *
+ * Manage global CLI configuration.
+ *
+ * Usage:
+ *   skedyul config set <key> <value>  - Set a config value
+ *   skedyul config get <key>           - Get a config value
+ *   skedyul config list                - List all config values
+ */
+export declare function configCommand(args: string[]): Promise<void>;
+export { configCommand as config };