@api-now/cli 1.0.4

package/LICENSE.md

@@ -0,0 +1,15 @@
+# API Now Ecosystem License
+
+Copyright (c) 2025 API Now
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, publish, and distribute the Software **exclusively within the API Now ecosystem**.
+
+**Restrictions:**
+
+- The Software may not be used, copied, modified, merged, published, or distributed outside of the API Now ecosystem.
+- The Software may not be sublicensed, sold, or used as part of any product or service that is not part of the API Now ecosystem.
+- Any use of the Software outside the API Now ecosystem is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For questions about permitted use, please contact: <info@apinow.app>

package/README.md

@@ -0,0 +1,164 @@
+# API NOW! CLI
+
+The **API NOW! CLI** is a robust, cross-platform command-line tool designed to manage settings, handle authentication, organize directories/files, and publish assets directly to the Data Catalog from your terminal.
+
+---
+
+## Features
+
+- **OAuth2 Loopback Authentication**: Authenticate using your Google, GitHub, or LinkedIn accounts.
+- **Interactive Onboarding**: Guided setup prompts for first-time users to configure organization names and slugs (validated against reserved keywords/taken values).
+- **Default Organization Management**: List organizations and pin a default workspace ID.
+- **Metadata and Media Uploads**: Create, list, and read blueprints, domains, and multimedia assets.
+- **Data Catalog Publishing**: Publish schemas and datasets to the global/private catalog with automatic semantic versioning support.
+- **Developer Formatting Options**: Toggle outputs between human-friendly ASCII tables and machine-readable JSON.
+
+---
+
+## Installation
+
+Install the CLI globally from npm:
+
+```bash
+npm install -g @api-now/cli
+```
+
+Once installed, the CLI is available as the `apinow` command.
+
+---
+
+## Usage & Commands
+
+All commands support the following global options:
+- `--api-url <url>`: Override the target API Server URL (Default: `http://localhost:8080`). Note that the platform is actively under development and the final default URL will be set once the platform is officially released.
+- `--format <text|json>`: Define the output layout (Default: `text`).
+
+### 1. Configuration (`config`)
+Read and write persistent CLI configurations stored in the OS settings folder depending on the platform:
+- **Linux**: `~/.config/apinow-cli/config.json` (or respects `$XDG_CONFIG_HOME`)
+- **macOS**: `~/Library/Preferences/apinow-cli/config.json`
+- **Windows**: `%APPDATA%\apinow-cli\config.json`
+
+```bash
+# Get a configuration property (e.g. apiUrl, defaultOrg)
+apinow config get <key>
+
+# Set a configuration property
+apinow config set <key> <value>
+```
+
+### 2. Authentication (`auth`)
+Securely log in to the API platform using OAuth2.
+
+```bash
+# Log in using Google, GitHub, or LinkedIn
+apinow auth login <google|github|linkedin>
+
+# Verify current authentication status and user identity details
+apinow auth status
+
+# Log out and erase stored authentication tokens
+apinow auth logout
+```
+
+*Note: On your first login or checking status with no registered organization, an interactive step will automatically guide you through creating your first organization with live slug verification.*
+
+#### Personal Access Tokens (`auth tokens`)
+Generate and manage Personal Access Tokens (PATs) for programmatic access.
+
+```bash
+# List all personal access tokens
+apinow auth tokens list
+
+# Create a new personal access token
+apinow auth tokens create [--name <token_name>] [--expires-at <duration_or_timestamp>]
+
+Example:
+apinow auth tokens create --name "Test Token" --expires-at "30 days"
+
+# Delete a personal access token by its ID
+apinow auth tokens delete <token_id>
+```
+
+### 3. Organizations (`orgs`)
+Manage organization contexts.
+
+```bash
+# List all organizations you belong to
+apinow orgs list
+
+# Get the default configured organization
+apinow orgs get-default
+
+# Set default organization to avoid passing --org CLI parameters
+apinow orgs set-default <organization_id>
+```
+
+### 4. Files (`files`)
+Manage domain and API files in your organizations.
+
+```bash
+# List files with optional filters
+apinow files list --org <org_id> --parent <parent_id> --kind <domain|api>
+
+# Create file metadata and upload local media
+apinow files create --name "My Domain File" --kind "domain" --org <org_id> --parent <parent_id> --media ./path/to/schema.ts
+
+# Create file metadata and pipe media contents from STDIN
+echo '{"schema": "content"}' | apinow files create --name "My Piped File" --kind "api" --org <org_id> --stdin
+
+# Read file metadata (default) or media content (--media)
+apinow files read --id <file_id> --org <org_id> [--media]
+```
+
+### 5. Data Catalog (`catalog`)
+Publish and browse published catalog items.
+
+```bash
+# Publish a local data domain file to the catalog
+apinow catalog publish --file <file_id> --name "Catalog Name" --description "Catalog Description" --scope public --catalog-version 1.0.0
+
+# List all published data domains in the catalog
+apinow catalog list --scope <all|public|organization|private> [--key <domain_key>]
+```
+
+---
+
+## Development
+
+### Local Setup & Building
+1. Clone the repository and install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Build the package:
+   ```bash
+   npm run build
+   ```
+
+3. Run the CLI locally:
+   ```bash
+   # Run directly via tsx (Development)
+   npm run dev -- [command]
+
+   # Or execute the compiled build
+   node dist/index.js [command]
+   ```
+
+### Formatting and Linting
+To format the source code with Prettier:
+```bash
+npm run format
+```
+
+To run the ESLint static code analysis checks:
+```bash
+npm run lint
+```
+
+### Type Checking
+To run the TypeScript compiler in dry-run mode:
+```bash
+npm run typecheck
+```

package/dist/commands/auth.js

@@ -0,0 +1,314 @@
+import { Argument } from 'commander';
+import http from 'node:http';
+import open from 'open';
+import { config } from '../utils/config.js';
+import { getSdkClient, handleApiError } from '../utils/api.js';
+import { Formatter, style, debug } from '../utils/formatter.js';
+import { setupFirstOrganizationIfNeeded } from '../utils/org-setup.js';
+import { registerTokensCommands } from './tokens.js';
+/**
+ * Registers authentication management commands (login, status, logout) with the main Commander program.
+ *
+ * @param program - The root Commander program.
+ */
+export function registerAuthCommands(program) {
+    const authCmd = program.command('auth').description('Manage CLI authentication');
+    registerTokensCommands(authCmd);
+    authCmd
+        .command('login')
+        .description('Authenticate with the API platform using OAuth2 (google, github, or linkedin)')
+        .addArgument(new Argument('provider', 'Authentication provider').choices(['google', 'github', 'linkedin']))
+        .action(async (provider) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const allowedProviders = ['google', 'github', 'linkedin'];
+        if (!allowedProviders.includes(provider)) {
+            formatter.error({
+                message: `Invalid provider '${provider}'. Allowed: ${allowedProviders.join(', ')}`,
+            });
+            process.exit(1);
+        }
+        const apiUrl = config.resolved.apiUrl;
+        if (config.resolved.format !== 'json') {
+            console.log(`Starting authentication flow using provider '${provider}'...`);
+        }
+        try {
+            await runLoginServer(apiUrl, provider, formatter);
+            formatter.success('Successfully authenticated!');
+            const client = getSdkClient();
+            await setupFirstOrganizationIfNeeded(client, formatter);
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                formatter.error({ message: err.message });
+            }
+            else {
+                formatter.error({ message: 'Authentication failed.' });
+            }
+            process.exit(1);
+        }
+    });
+    authCmd
+        .command('logout')
+        .description('Log out and clear the stored token')
+        .action(() => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        config.clearConfigKey('token');
+        formatter.success('Logged out successfully.');
+    });
+    authCmd
+        .command('status')
+        .description('Check current authentication status')
+        .action(async () => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        if (!resolved.token) {
+            formatter.error({ message: 'Not logged in. Use `auth login <provider>` to authenticate.' });
+            process.exit(1);
+        }
+        try {
+            const client = getSdkClient();
+            const user = await client.users.me({ token: client.token });
+            if (resolved.format === 'json') {
+                formatter.object({ authenticated: true, user });
+            }
+            else {
+                console.log(style.green('✔ Authenticated successfully!'));
+                console.log(`User: ${user.name} (${user.email})`);
+                console.log(`Default Org: ${resolved.org || 'None'}`);
+            }
+            await setupFirstOrganizationIfNeeded(client, formatter);
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error({
+                message: 'Authentication token is invalid or expired.',
+                detail: apiErr.message,
+            });
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Spins up a temporary local HTTP server to receive the OAuth authentication token
+ * from the browser-based callback page.
+ *
+ * @param apiUrl - The target backend API server base URL.
+ * @param provider - The OAuth login provider.
+ * @param formatter - Output formatter.
+ * @returns A promise resolving to the retrieved authentication token.
+ */
+function runLoginServer(apiUrl, provider, formatter) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            if (req.method === 'GET' && req.url?.startsWith('/callback')) {
+                debug('auth', `Received request for callback: ${req.url}`);
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>API NOW! CLI Login</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 100vh;
+      margin: 0;
+      background: #121214;
+      color: #e1e1e6;
+    }
+    .card {
+      background: #202024;
+      padding: 2rem;
+      border-radius: 8px;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.5);
+      text-align: center;
+      max-width: 450px;
+      width: 100%;
+    }
+    h1 { color: #04d361; margin-top: 0; }
+    .status { font-weight: bold; margin: 1rem 0; line-height: 1.4; }
+    .diagnostics {
+      display: none;
+      text-align: left;
+      margin-top: 1.5rem;
+      padding: 1rem;
+      background: #2f2f33;
+      border-radius: 4px;
+      font-size: 0.8rem;
+      font-family: monospace;
+      white-space: pre-wrap;
+      word-break: break-all;
+      border-left: 4px solid #f75a68;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>API NOW!</h1>
+    <p class="status" id="status">Retrieving token from server...</p>
+    <div class="diagnostics" id="diagnostics">
+      <strong>Diagnostic Details:</strong>
+      <div id="diagnostics-content" style="margin-top: 0.5rem;"></div>
+    </div>
+  </div>
+  <script>
+    fetch('${apiUrl}/auth/token', { credentials: 'include' })
+      .then(r => {
+        if (!r.ok) {
+          throw new Error('Token request failed: ' + r.statusText + ' (status: ' + r.status + ')');
+        }
+        return r.json();
+      })
+      .then(data => {
+        console.log("[DEBUG] Parse response JSON:", data);
+        const token = data.token || data.data?.token || data.data;
+        if (!token) {
+          throw new Error('Token not found in API response structure');
+        }
+        
+        console.log("[DEBUG] POSTing token to local server callback...");
+        return fetch('/token', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token })
+        });
+      })
+      .then(r => {
+        if (!r.ok) {
+          throw new Error('Failed to save token in CLI server (status: ' + r.status + ')');
+        }
+        document.getElementById('status').innerText = 'Authentication successful! You can close this tab now.';
+        document.getElementById('status').style.color = '#04d361';
+      })
+      .catch(err => {
+        console.error("[ERROR]", err);
+        document.getElementById('status').innerText = 'Authentication failed.';
+        document.getElementById('status').style.color = '#f75a68';
+        
+        const diag = document.getElementById('diagnostics');
+        const content = document.getElementById('diagnostics-content');
+        diag.style.display = 'block';
+        content.innerText = 
+          'Error Message: ' + err.message + '\\n\\n' +
+          'Originating URL: ' + window.location.href + '\\n' +
+          'Target API URL: ${apiUrl}/auth/token\\n\\n' +
+          'TIP: If you get "Unauthorized (status: 401)", make sure that:\\n' +
+          '1. You completed the login flow on the browser window that opened.\\n' +
+          '2. The host of the page you are on (' + window.location.hostname + ') matches the host of the API (' + new URL('${apiUrl}').hostname + ') to satisfy SameSite cookie policy.\\n' +
+          '3. Check browser developer console (F12) for detailed CORS/Network errors.';
+        
+        fetch('/error', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ message: err.message })
+        }).catch(console.error);
+      });
+  </script>
+</body>
+</html>
+        `;
+                res.end(html);
+                return;
+            }
+            if (req.method === 'POST' && req.url === '/token') {
+                let body = '';
+                req.on('data', (chunk) => {
+                    body += chunk;
+                });
+                req.on('end', () => {
+                    try {
+                        const data = JSON.parse(body);
+                        if (data.token) {
+                            debug('auth', 'Storing retrieved token to CLI configuration...');
+                            config.writeProperty('token', data.token);
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ success: true }));
+                            resolve(data.token);
+                        }
+                        else {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Token missing' }));
+                            reject(new Error('Token missing from browser callback.'));
+                        }
+                    }
+                    catch (e) {
+                        if (e instanceof Error) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: e.message }));
+                            reject(new Error('Invalid body received: ' + e.message));
+                        }
+                        else {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Invalid body received' }));
+                            reject(new Error('Invalid body received'));
+                        }
+                    }
+                    finally {
+                        cleanup();
+                    }
+                });
+                return;
+            }
+            if (req.method === 'POST' && req.url === '/error') {
+                let body = '';
+                req.on('data', (chunk) => {
+                    body += chunk;
+                });
+                req.on('end', () => {
+                    try {
+                        const data = JSON.parse(body);
+                        debug('auth', `Received login error from browser callback: ${data.message}`);
+                        reject(new Error(data.message || 'Browser login failed'));
+                    }
+                    catch {
+                        reject(new Error('Browser login failed'));
+                    }
+                    finally {
+                        cleanup();
+                    }
+                });
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        });
+        const handleSigInt = () => {
+            cleanup();
+            process.exit(130);
+        };
+        process.on('SIGINT', handleSigInt);
+        process.on('SIGTERM', handleSigInt);
+        const timeout = setTimeout(() => {
+            reject(new Error('Authentication timed out.'));
+            cleanup();
+        }, 300000);
+        function cleanup() {
+            clearTimeout(timeout);
+            process.off('SIGINT', handleSigInt);
+            process.off('SIGTERM', handleSigInt);
+            server.close();
+        }
+        server.listen(0, '127.0.0.1', async () => {
+            const port = server.address().port;
+            // Smart hostname matching: resolve 127.0.0.1 vs localhost context dynamically to enable cookie transport
+            const apiHost = new URL(apiUrl).hostname;
+            const redirectHost = apiHost === 'localhost' ? 'localhost' : '127.0.0.1';
+            const loginUrl = `${apiUrl}/auth/${provider}/redirect?r=http://${redirectHost}:${port}/callback`;
+            debug('auth', `Ephemeral loopback server listening on http://127.0.0.1:${port}`);
+            debug('auth', `Browser callback origin configured to http://${redirectHost}:${port}`);
+            if (formatter.format !== 'json') {
+                console.log(`Opening browser to log in...`);
+                console.log(`If it doesn't open automatically, navigate to:\n  ${loginUrl}`);
+            }
+            try {
+                await open(loginUrl);
+            }
+            catch (_err) {
+                // Ignore open failure
+            }
+        });
+    });
+}