@private.me/xbind 1.2.0

package/dist-standalone/cli/init.js

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * @module cli/init
+ * One-line CLI setup for XBind connections.
+ *
+ * Enables: npx xbind-init --invite <code>
+ *
+ * Flow:
+ * 1. Parse invite URL or code
+ * 2. Fetch invite details from registry server
+ * 3. Interactive prompts for: project name, runtime, TypeScript vs JavaScript
+ * 4. Generate project directory with template files
+ * 5. Install dependencies
+ * 6. Write .env file with XBIND_INVITE_CODE
+ * 7. Register with XBind registry (auto-accept flow)
+ * 8. Print success message with next steps
+ *
+ * @example
+ * ```bash
+ * npx xbind-init --invite https://xbind.to/invite/XBD-abc123
+ *
+ * # Prompts:
+ * # → Project name: my-xbind-app
+ * # → Runtime: node-typescript
+ * # Creating project...
+ * # Installing dependencies...
+ * # Registering with XBind...
+ * # ✅ Ready! Run: cd my-xbind-app && npm start
+ * ```
+ */
+import { parseArgs } from 'node:util';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { InviteService } from '../invite.js';
+// Get template directory path
+// In production, templates are at ../templates relative to dist/cli/init.js
+// We'll resolve this dynamically based on the package root
+function getTemplateDir() {
+    // Find package root by looking for package.json
+    let currentDir = __dirname;
+    while (currentDir !== '/') {
+        if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+            return path.join(currentDir, 'templates');
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    // Fallback: assume we're in dist/cli and templates are in package root
+    return path.join(__dirname, '../../templates');
+}
+const TEMPLATES = {
+    'node-typescript': {
+        name: 'Node.js + TypeScript',
+        description: 'Node.js with TypeScript, best for backend services',
+        packageManager: 'npm',
+        entryPoint: 'src/index.ts',
+        startCommand: 'npm run dev',
+    },
+    'node-javascript': {
+        name: 'Node.js + JavaScript',
+        description: 'Node.js with JavaScript, minimal setup',
+        packageManager: 'npm',
+        entryPoint: 'src/index.js',
+        startCommand: 'npm start',
+    },
+    'deno': {
+        name: 'Deno',
+        description: 'Modern TypeScript runtime',
+        packageManager: 'deno',
+        entryPoint: 'mod.ts',
+        startCommand: 'deno run --allow-net --allow-env --allow-read mod.ts',
+    },
+    'cloudflare-worker': {
+        name: 'Cloudflare Worker',
+        description: 'Edge runtime on Cloudflare',
+        packageManager: 'npm',
+        entryPoint: 'src/index.ts',
+        startCommand: 'npm run dev',
+    },
+    'vercel-function': {
+        name: 'Vercel Function',
+        description: 'Serverless function on Vercel',
+        packageManager: 'npm',
+        entryPoint: 'api/xbind.ts',
+        startCommand: 'npm run dev',
+    },
+};
+/**
+ * Spinner for progress indication.
+ */
+class Spinner {
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    currentFrame = 0;
+    intervalId;
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+    start() {
+        this.intervalId = setInterval(() => {
+            const frame = this.frames[this.currentFrame];
+            process.stdout.write(`\r${frame} ${this.message}`);
+            this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+        }, 80);
+    }
+    succeed(message) {
+        this.stop();
+        process.stdout.write(`\r✅ ${message ?? this.message}\n`);
+    }
+    fail(message) {
+        this.stop();
+        process.stdout.write(`\r❌ ${message ?? this.message}\n`);
+    }
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = undefined;
+        }
+    }
+}
+/**
+ * Parse invite code/URL to extract invite ID.
+ *
+ * @param inviteInput - Invite URL or code
+ * @returns Invite URL
+ */
+function normalizeInviteUrl(inviteInput, registryUrl) {
+    // If it's already a full URL, return as-is
+    if (inviteInput.startsWith('http://') || inviteInput.startsWith('https://')) {
+        return inviteInput;
+    }
+    // If it starts with XBD-, treat as code
+    if (inviteInput.startsWith('XBD-')) {
+        return `${registryUrl}/invite/${inviteInput}`;
+    }
+    // Otherwise, assume it's an ID
+    return `${registryUrl}/invite/${inviteInput}`;
+}
+/**
+ * Validate project name.
+ *
+ * @param name - Project name
+ * @returns true if valid
+ */
+function isValidProjectName(name) {
+    return /^[a-z0-9-_]+$/i.test(name) && name.length > 0 && name.length <= 100;
+}
+/**
+ * Prompt user for input.
+ *
+ * @param question - Question text
+ * @param defaultValue - Default value
+ * @returns User input
+ */
+async function prompt(question, defaultValue) {
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question(defaultValue ? `${question} (${defaultValue}): ` : `${question}: `);
+    rl.close();
+    return answer.trim() || defaultValue || '';
+}
+/**
+ * Prompt user to select from a list.
+ *
+ * @param question - Question text
+ * @param choices - Available choices
+ * @param defaultIndex - Default choice index
+ * @returns Selected choice
+ */
+async function select(question, choices, defaultIndex = 0) {
+    console.log(question);
+    choices.forEach((choice, i) => {
+        const prefix = i === defaultIndex ? '→' : ' ';
+        console.log(`  ${prefix} ${i + 1}. ${choice.label} - ${choice.description}`);
+    });
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question(`Select (1-${choices.length}): `);
+    rl.close();
+    const selectedIndex = parseInt(answer.trim(), 10) - 1;
+    if (selectedIndex >= 0 && selectedIndex < choices.length) {
+        return choices[selectedIndex]?.value ?? choices[defaultIndex]?.value ?? '';
+    }
+    return choices[defaultIndex]?.value ?? '';
+}
+/**
+ * Run shell command.
+ *
+ * @param command - Command to run
+ * @param args - Command arguments
+ * @param cwd - Working directory
+ * @returns Promise that resolves when command completes
+ */
+function runCommand(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, {
+            cwd,
+            stdio: 'ignore',
+            shell: true,
+        });
+        proc.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Command failed with code ${code ?? 'unknown'}`));
+            }
+        });
+        proc.on('error', reject);
+    });
+}
+/**
+ * Copy template files to project directory.
+ *
+ * @param templateName - Template name
+ * @param projectPath - Project directory path
+ * @param invite - Invite details
+ */
+async function copyTemplate(templateName, projectPath, invite) {
+    const templateDir = path.join(getTemplateDir(), templateName);
+    // Read all files in template directory
+    const files = await fs.promises.readdir(templateDir, { recursive: true, withFileTypes: true });
+    for (const file of files) {
+        if (file.isFile()) {
+            // Get the parent path from the file dirent
+            // Note: file.parentPath was added in Node.js 20.1.0, file.path is deprecated
+            const parentPath = file.parentPath || file.path || templateDir;
+            const relativePath = path.relative(templateDir, path.join(parentPath, file.name));
+            const sourcePath = path.join(templateDir, relativePath);
+            const destPath = path.join(projectPath, relativePath);
+            // Create directory if it doesn't exist
+            await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+            // Read template file
+            let content = await fs.promises.readFile(sourcePath, 'utf-8');
+            // Replace placeholders
+            if (invite) {
+                content = content.replace(/{{INVITE_URL}}/g, invite.url);
+                content = content.replace(/{{INVITE_ID}}/g, invite.id);
+                content = content.replace(/{{SERVICE_NAME}}/g, invite.from.name);
+                content = content.replace(/{{SERVICE_DID}}/g, invite.from.did);
+                content = content.replace(/{{SERVICE_ENDPOINT}}/g, invite.from.endpoint);
+            }
+            // Write to destination
+            await fs.promises.writeFile(destPath, content, 'utf-8');
+        }
+    }
+}
+/**
+ * Install dependencies.
+ *
+ * @param projectPath - Project directory
+ * @param packageManager - Package manager to use
+ */
+async function installDependencies(projectPath, packageManager) {
+    if (packageManager === 'npm') {
+        await runCommand('npm', ['install'], projectPath);
+    }
+    else if (packageManager === 'deno') {
+        // Deno doesn't need install, it auto-downloads
+    }
+    // 'none' for templates that don't need dependencies
+}
+/**
+ * Main init command.
+ *
+ * @param options - Init options
+ */
+export async function initCommand(options = {}) {
+    const registryUrl = options.registryUrl || 'https://xbind.to';
+    // Step 1: Get invite details
+    let invite;
+    let inviteUrl;
+    if (options.invite) {
+        inviteUrl = normalizeInviteUrl(options.invite, registryUrl);
+        const spinner = new Spinner('Fetching invite details...');
+        spinner.start();
+        try {
+            const inviteService = new InviteService({ inviteApiUrl: registryUrl });
+            const inviteResult = await inviteService.get(inviteUrl);
+            if (!inviteResult.ok) {
+                spinner.fail(`Failed to fetch invite: ${inviteResult.error.message}`);
+                if (inviteResult.error.hint) {
+                    console.error(`Hint: ${inviteResult.error.hint}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            invite = inviteResult.value;
+            spinner.succeed(`Connected to ${invite.from.name}`);
+        }
+        catch (error) {
+            spinner.fail('Failed to fetch invite details');
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Step 2: Prompt for project details (if not in --yes mode)
+    let projectName = options.name;
+    let runtime = options.runtime;
+    if (!options.yes) {
+        // Prompt for project name
+        if (!projectName) {
+            const suggestedName = invite ? `connect-${invite.from.name}` : 'my-xbind-app';
+            projectName = await prompt('Project name', suggestedName);
+        }
+        // Prompt for runtime
+        if (!runtime) {
+            runtime = (await select('\nSelect runtime:', Object.entries(TEMPLATES).map(([value, meta]) => ({
+                value,
+                label: meta.name,
+                description: meta.description,
+            })), 0));
+        }
+    }
+    else {
+        // In --yes mode, use defaults
+        projectName = projectName || 'my-xbind-app';
+        runtime = runtime || 'node-typescript';
+    }
+    // Validate project name (applies to both modes)
+    if (!isValidProjectName(projectName)) {
+        console.error('❌ Invalid project name. Use only letters, numbers, hyphens, and underscores.');
+        process.exitCode = 1;
+        return;
+    }
+    // Check if directory exists (applies to both modes)
+    const projectPath = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(projectPath)) {
+        console.error(`❌ Directory "${projectName}" already exists.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!runtime || !TEMPLATES[runtime]) {
+        console.error('❌ Invalid runtime selection.');
+        process.exitCode = 1;
+        return;
+    }
+    const template = TEMPLATES[runtime];
+    console.log(`\n📦 Creating ${template.name} project: ${projectName}`);
+    // Step 3: Create project directory
+    const createSpinner = new Spinner('Creating project structure...');
+    createSpinner.start();
+    try {
+        await fs.promises.mkdir(projectPath, { recursive: true });
+        await copyTemplate(runtime, projectPath, invite);
+        createSpinner.succeed('Project structure created');
+    }
+    catch (error) {
+        createSpinner.fail('Failed to create project structure');
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    // Step 4: Install dependencies
+    if (template.packageManager !== 'none' && process.env.NODE_ENV !== 'test') {
+        const installSpinner = new Spinner('Installing dependencies...');
+        installSpinner.start();
+        try {
+            await installDependencies(projectPath, template.packageManager);
+            installSpinner.succeed('Dependencies installed');
+        }
+        catch (error) {
+            installSpinner.fail('Failed to install dependencies');
+            console.error('You can install them manually later.');
+            // Don't exit, continue
+        }
+    }
+    // Step 5: Write .env file with invite code (if provided)
+    if (invite || inviteUrl) {
+        const finalInviteUrl = invite?.url || inviteUrl || '';
+        if (process.env.DEBUG_CLI) {
+            console.log('[DEBUG] Writing .env file:', { invite: !!invite, inviteUrl, finalInviteUrl, projectPath });
+        }
+        if (finalInviteUrl) {
+            await fs.promises.writeFile(path.join(projectPath, '.env'), `XBIND_INVITE_CODE=${finalInviteUrl}\n`, 'utf-8');
+        }
+    }
+    else if (process.env.DEBUG_CLI) {
+        console.log('[DEBUG] Not writing .env file:', { invite: !!invite, inviteUrl });
+    }
+    // Step 6: Print success message
+    console.log('\n✅ Ready!\n');
+    console.log('Next steps:');
+    console.log(`  cd ${projectName}`);
+    console.log(`  ${template.startCommand}`);
+    if (invite) {
+        console.log(`\n🔗 Connected to: ${invite.from.name}`);
+        console.log(`   DID: ${invite.from.did}`);
+    }
+    else {
+        console.log('\n💡 To connect to a service, get an invite code and update .env file.');
+    }
+}
+/**
+ * CLI entry point.
+ *
+ * @param argv - Command-line arguments
+ */
+export async function main(argv = process.argv.slice(2)) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            invite: { type: 'string', short: 'i' },
+            name: { type: 'string', short: 'n' },
+            runtime: { type: 'string', short: 'r' },
+            yes: { type: 'boolean', short: 'y' },
+            'registry-url': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        console.log(`
+XBind CLI - One-Line M2M Setup
+
+Usage:
+  npx xbind-init [options]
+
+Options:
+  -i, --invite <url>       Invite URL or code
+  -n, --name <name>        Project name
+  -r, --runtime <runtime>  Runtime template (node-typescript, node-javascript, deno, cloudflare-worker, vercel-function)
+  -y, --yes                Skip interactive prompts (use defaults)
+  --registry-url <url>     Custom registry URL (default: https://xbind.to)
+  -h, --help               Show this help message
+
+Examples:
+  npx xbind-init --invite https://xbind.to/invite/XBD-abc123
+  npx xbind-init --invite XBD-abc123 --name my-app --runtime node-typescript
+  npx xbind-init --yes
+    `.trim());
+        return;
+    }
+    await initCommand({
+        invite: values.invite,
+        name: values.name,
+        runtime: values.runtime,
+        yes: values.yes,
+        'registry-url': values['registry-url'],
+    });
+}
+// Auto-run if executed directly
+const isDirectRun = process.argv[1]?.endsWith('init.ts') || process.argv[1]?.endsWith('init.js');
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error('Fatal:', error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist-standalone/connect.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @module connect
+ * High-level connect() API for zero-config XBind connections.
+ *
+ * Enables: `const service = await connect('payments-service')`
+ *
+ * Combines:
+ * - Service discovery
+ * - Trust verification
+ * - Agent creation
+ * - Connection establishment
+ *
+ * @example
+ * ```ts
+ * import { connect } from '@private.me/xbind';
+ *
+ * // Connect by name (uses registry):
+ * const payments = await connect('payments-service');
+ *
+ * // Connect by domain (uses .well-known):
+ * const payments = await connect('payments.example.com');
+ *
+ * // Connect by URL (direct):
+ * const payments = await connect('https://api.payments.com/xbind');
+ *
+ * // Use the connection:
+ * await payments.send({
+ *   to: payments.did,
+ *   payload: { action: 'createCharge', amount: 100 },
+ *   scope: 'payments',
+ * });
+ * ```
+ */
+import { Result } from '@private.me/shared';
+import { Agent } from './agent.js';
+import { ServiceDiscovery } from './discovery.js';
+import type { ServiceInfo } from './discovery.js';
+import type { XailTransportAdapter } from './transport.js';
+/**
+ * Connect error codes.
+ */
+export declare enum ConnectErrorCode {
+    DISCOVERY_FAILED = "CONNECT_DISCOVERY_FAILED",
+    AGENT_CREATION_FAILED = "CONNECT_AGENT_CREATION_FAILED",
+    TRUST_VERIFICATION_FAILED = "CONNECT_TRUST_VERIFICATION_FAILED",
+    INVALID_SERVICE_INFO = "CONNECT_INVALID_SERVICE_INFO"
+}
+/**
+ * Connect error.
+ */
+export interface ConnectError {
+    code: ConnectErrorCode;
+    message: string;
+    hint?: string;
+    cause?: unknown;
+}
+/**
+ * Connect options.
+ */
+export interface ConnectOptions {
+    /** Custom discovery service (optional) */
+    discovery?: ServiceDiscovery;
+    /**
+     * Custom trust registry (optional).
+     *
+     * SAFETY: Uses `any` to support extended registry implementations with add() method.
+     * The base TrustRegistry interface uses register(), but some implementations
+     * may provide an add() convenience method.
+     */
+    registry?: any;
+    /** Custom transport adapter (optional) */
+    transport?: XailTransportAdapter;
+    /** Agent name (default: auto-generated) */
+    name?: string;
+    /** Enable split-channel by default (default: false) */
+    splitChannel?: boolean;
+    /** Enable Xchange mode (default: false) */
+    xchange?: boolean;
+    /** Enable post-quantum signatures (default: false) */
+    postQuantumSig?: boolean;
+    /** Agent endpoint URL where it can be reached (optional, for server agents) */
+    endpoint?: string;
+}
+/**
+ * Connection result.
+ */
+export interface Connection {
+    /** Agent instance */
+    agent: Agent;
+    /** Service info */
+    service: ServiceInfo;
+    /** DID of the service */
+    did: string;
+    /** Endpoint URL */
+    endpoint: string;
+}
+/**
+ * Connect to a service with zero configuration.
+ *
+ * @param nameOrUrl - Service name, domain, or URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * // Minimal:
+ * const connection = await connect('payments-service');
+ * if (connection.ok) {
+ *   await connection.value.agent.send({
+ *     to: connection.value.did,
+ *     payload: { action: 'test' },
+ *     scope: 'test',
+ *   });
+ * }
+ *
+ * // With options:
+ * const connection = await connect('payments-service', {
+ *   name: 'billing-service',
+ *   xchange: true, // Use faster Xchange mode
+ *   splitChannel: true, // Use split-channel by default
+ * });
+ * ```
+ */
+export declare function connect(nameOrUrl: string, options?: ConnectOptions): Promise<Result<Connection, ConnectError>>;
+/**
+ * Accept an invite and establish connection.
+ *
+ * @param inviteUrl - Invite URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * const connection = await acceptInvite('https://xbind.to/invite/abc123', {
+ *   name: 'my-service',
+ * });
+ *
+ * if (connection.ok) {
+ *   console.log('Connected to:', connection.value.service.name);
+ * }
+ * ```
+ */
+export declare function acceptInvite(inviteUrl: string, options?: ConnectOptions): Promise<Result<Connection, ConnectError>>;