@entrinsik/vite-plugin-informer 1.0.0

package/bin/deploy.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import dotenv from 'dotenv';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { deploy } from '../src/deploy.js';
+
+dotenv.config();
+
+const baseUrl = process.env.INFORMER_URL;
+const apiKey = process.env.INFORMER_API_KEY;
+const user = process.env.INFORMER_USER;
+const pass = process.env.INFORMER_PASS;
+
+if (!baseUrl || (!apiKey && (!user || !pass))) {
+    console.error('Missing required environment variables.');
+    console.error('Create a .env file with:');
+    console.error('  INFORMER_URL=http://localhost:3000');
+    console.error('  INFORMER_API_KEY=your-api-key');
+    console.error('Or use basic auth:');
+    console.error('  INFORMER_USER=admin');
+    console.error('  INFORMER_PASS=yourpassword');
+    process.exit(1);
+}
+
+// Read project metadata from package.json
+let slug;
+let displayName;
+let description;
+try {
+    const pkg = JSON.parse(await readFile(resolve('package.json'), 'utf8'));
+    slug = pkg.name;
+    // Strip scope prefix if present (e.g. @org/my-report -> my-report)
+    if (slug && slug.startsWith('@') && slug.includes('/')) {
+        slug = slug.split('/')[1];
+    }
+    // Read display name and description from informer config section
+    displayName = pkg.informer?.name;
+    description = pkg.informer?.description;
+} catch {
+    console.error('Could not read package.json in current directory.');
+    process.exit(1);
+}
+
+if (!slug) {
+    console.error('package.json must have a "name" field.');
+    process.exit(1);
+}
+
+const distDir = resolve('dist');
+
+try {
+    await deploy({ baseUrl, apiKey, user, pass, slug, distDir, name: displayName, description });
+} catch (err) {
+    console.error('Deploy failed:', err.message);
+    process.exit(1);
+}

package/bin/init.js

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, mkdir, cp, access, readdir } from 'node:fs/promises';
+import { resolve, dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cwd = process.cwd();
+
+/**
+ * Generate the default data-access.yaml content with helpful comments
+ */
+function generateDataAccessYaml() {
+    return `# Data Access Configuration
+# ========================
+# This file controls which Informer APIs your report can access.
+# Without this file, all API access is blocked (secure by default).
+#
+# Documentation: https://docs.entrinsik.com/informer/magic-reports/data-access
+
+# ============================================================================
+# DATASETS
+# ============================================================================
+# Grant access to dataset search and field metadata.
+# Each entry generates:
+#   - POST /api/datasets/{id}/_search
+#   - GET /api/datasets/{id}/fields
+#
+# Simple access (full dataset):
+#   datasets:
+#     - admin:sales-data
+#     - admin:customers
+#
+# With row-level security (filter injected server-side):
+#   datasets:
+#     - id: admin:orders
+#       filter:
+#         region: $user.custom.region      # User only sees their region
+#         sales_rep: $user.username        # User only sees their own records
+#
+datasets: []
+
+# ============================================================================
+# QUERIES
+# ============================================================================
+# Grant access to execute saved queries.
+# Each entry generates:
+#   - POST /api/queries/{id}/_execute
+#
+# Example:
+#   queries:
+#     - admin:daily-summary
+#     - admin:monthly-report
+#
+queries: []
+
+# ============================================================================
+# INTEGRATIONS
+# ============================================================================
+# Grant access to make requests through integrations (Salesforce, REST APIs, etc.)
+# Each entry generates:
+#   - POST /api/integrations/{id}/request
+#
+# Simple access:
+#   integrations:
+#     - salesforce
+#     - quickbooks
+#
+# With credential injection (headers/params expanded server-side, never exposed to JS):
+#   integrations:
+#     - id: partner-api
+#       headers:
+#         Authorization: Bearer $user.custom.partnerToken
+#         X-Client-ID: $tenant.id
+#       params:
+#         user_id: $user.custom.externalId
+#
+# With path restrictions (only allow specific endpoints):
+#   integrations:
+#     - id: salesforce
+#       paths:
+#         - /data/*/query
+#         - /data/*/sobjects/*
+#
+integrations: []
+
+# ============================================================================
+# DATASOURCES
+# ============================================================================
+# Grant access to run SQL queries against datasources.
+# Each entry generates:
+#   - POST /api/datasources/{id}/_query
+#
+# Example:
+#   datasources:
+#     - postgres-main
+#     - mysql-analytics
+#
+datasources: []
+
+# ============================================================================
+# LIBRARIES
+# ============================================================================
+# Grant access to read files from other libraries.
+# Each entry generates:
+#   - GET /api/libraries/{id}/contents/*
+#
+# Example:
+#   libraries:
+#     - admin:shared-assets
+#     - admin:common-templates
+#
+libraries: []
+
+# ============================================================================
+# RAW API ACCESS (Advanced)
+# ============================================================================
+# For edge cases not covered by resource types above.
+# Specify exact method and path.
+#
+# Example:
+#   apis:
+#     - POST /api/custom/endpoint
+#     - GET /api/special/resource
+#
+apis: []
+
+# ============================================================================
+# VARIABLE REFERENCE
+# ============================================================================
+# Variables are expanded server-side, keeping sensitive values secure.
+#
+# User variables:
+#   $user.username      - Login name
+#   $user.email         - Email address
+#   $user.displayName   - Full name (e.g., "John Smith")
+#   $user.custom.xxx    - Custom user field value
+#
+# Tenant variables:
+#   $tenant.id          - Tenant identifier
+#
+# Report variables:
+#   $report.id          - Report UUID
+#   $report.name        - Report display name
+#
+`;
+}
+
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Prompt user for input with a default value.
+ */
+function prompt(question, defaultValue) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+
+    const displayDefault = defaultValue ? ` (${defaultValue})` : '';
+
+    return new Promise(resolve => {
+        rl.question(`${question}${displayDefault}: `, answer => {
+            rl.close();
+            resolve(answer.trim() || defaultValue);
+        });
+    });
+}
+
+/**
+ * Convert slug to friendly name.
+ * "magic-quickbooks-report" -> "Magic Quickbooks Report"
+ */
+function slugToName(slug) {
+    return slug
+        .replace(/^@[^/]+\//, '') // Remove scope
+        .replace(/[-_]/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * Convert name to slug.
+ * "Magic Quickbooks Report" -> "magic-quickbooks-report"
+ */
+function nameToSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+
+async function init() {
+    console.log('Initializing Informer Magic Report project...\n');
+
+    // 1. Check for package.json
+    const pkgPath = resolve(cwd, 'package.json');
+    if (!await exists(pkgPath)) {
+        console.error('No package.json found. Run this in a Vite project directory.');
+        console.error('Create one first with: npm create vite@latest');
+        process.exit(1);
+    }
+
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+
+    // 2. Check for Vite
+    const hasVite = pkg.devDependencies?.vite || pkg.dependencies?.vite;
+    if (!hasVite) {
+        console.error('Vite not found in dependencies.');
+        console.error('Create a Vite project first: npm create vite@latest');
+        process.exit(1);
+    }
+
+    // 3. Get report info from user
+    const defaultSlug = (pkg.name || basename(cwd)).replace(/^@[^/]+\//, '');
+    const existingName = pkg.informer?.name;
+    const defaultName = existingName || slugToName(defaultSlug);
+
+    console.log('Configure your Magic Report:\n');
+
+    const reportName = await prompt('Report name', defaultName);
+    const reportSlug = await prompt('Report slug', nameToSlug(reportName) || defaultSlug);
+
+    console.log('');
+
+    // 4. Update package.json
+    if (!pkg.informer) pkg.informer = {};
+    pkg.informer.name = reportName;
+
+    // Update package name to match slug if it was the default
+    if (pkg.name === defaultSlug || !pkg.name) {
+        pkg.name = reportSlug;
+    }
+
+    // 5. Add plugin to dependencies if not present
+    if (!pkg.devDependencies) pkg.devDependencies = {};
+    if (!pkg.devDependencies['@entrinsik/vite-plugin-informer']) {
+        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = '^1.0.0';
+        console.log('Added @entrinsik/vite-plugin-informer to devDependencies');
+    }
+
+    // 6. Add deploy script if not present
+    if (!pkg.scripts) pkg.scripts = {};
+    if (!pkg.scripts.deploy) {
+        pkg.scripts.deploy = 'npm run build && informer-deploy';
+        console.log('Added "deploy" script to package.json');
+    }
+
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    console.log(`Configured report: "${reportName}" (slug: ${reportSlug})`);
+
+    // 7. Update vite.config
+    await updateViteConfig();
+
+    // 8. Create .env.example
+    const envExample = `# Informer connection settings
+INFORMER_URL=http://localhost:3000
+
+# Option 1: API Key (recommended)
+INFORMER_API_KEY=your-api-key
+
+# Option 2: Basic auth
+# INFORMER_USER=admin
+# INFORMER_PASS=yourpassword
+
+# Optional: defaults to current user
+# INFORMER_OWNER=admin
+`;
+
+    const envExamplePath = resolve(cwd, '.env.example');
+    if (!await exists(envExamplePath)) {
+        await writeFile(envExamplePath, envExample);
+        console.log('Created .env.example');
+    }
+
+    // Also create .env if it doesn't exist
+    const envPath = resolve(cwd, '.env');
+    if (!await exists(envPath)) {
+        await writeFile(envPath, envExample);
+        console.log('Created .env (update with your credentials)');
+    }
+
+    // 9. Create data-access.yaml if it doesn't exist
+    const dataAccessPath = resolve(cwd, 'data-access.yaml');
+    if (!await exists(dataAccessPath)) {
+        await writeFile(dataAccessPath, generateDataAccessYaml());
+        console.log('Created data-access.yaml (configure API access for your report)');
+    }
+
+    // 10. Copy Claude skill files
+    await copySkillFiles();
+
+    // 11. Add .env to .gitignore if not present
+    await updateGitignore();
+
+    console.log('\nSetup complete!\n');
+    console.log('Next steps:');
+    console.log('  1. Update .env with your Informer credentials');
+    console.log('  2. Update data-access.yaml with the datasets/APIs your report needs');
+    console.log('  3. Run: npm install');
+    console.log('  4. Run: npm run dev');
+    console.log('  5. Open a terminal and run: claude');
+    console.log('     The informer skill is available in .claude/skills/');
+    console.log('');
+}
+
+async function updateViteConfig() {
+    // Find vite config file
+    const configFiles = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts'];
+    let configPath = null;
+    let configContent = null;
+
+    for (const file of configFiles) {
+        const path = resolve(cwd, file);
+        if (await exists(path)) {
+            configPath = path;
+            configContent = await readFile(path, 'utf8');
+            break;
+        }
+    }
+
+    if (!configPath) {
+        // Create a basic vite.config.js
+        configPath = resolve(cwd, 'vite.config.js');
+        configContent = `import { defineConfig } from 'vite';
+import informer from '@entrinsik/vite-plugin-informer';
+
+export default defineConfig({
+    plugins: [informer()]
+});
+`;
+        await writeFile(configPath, configContent);
+        console.log('Created vite.config.js with informer plugin');
+        return;
+    }
+
+    // Check if plugin is already added
+    if (configContent.includes('vite-plugin-informer') || configContent.includes("informer()")) {
+        console.log('Informer plugin already in vite config');
+        return;
+    }
+
+    // Add import and plugin to existing config
+    const importLine = "import informer from '@entrinsik/vite-plugin-informer';\n";
+
+    // Add import after other imports
+    const lastImportMatch = configContent.match(/^import .+$/gm);
+    if (lastImportMatch) {
+        const lastImport = lastImportMatch[lastImportMatch.length - 1];
+        const lastImportIndex = configContent.lastIndexOf(lastImport) + lastImport.length;
+        configContent = configContent.slice(0, lastImportIndex) + '\n' + importLine + configContent.slice(lastImportIndex + 1);
+    } else {
+        configContent = importLine + configContent;
+    }
+
+    // Add to plugins array
+    const pluginsMatch = configContent.match(/plugins\s*:\s*\[/);
+    if (pluginsMatch) {
+        const insertIndex = pluginsMatch.index + pluginsMatch[0].length;
+        configContent = configContent.slice(0, insertIndex) + '\n        informer(),' + configContent.slice(insertIndex);
+    } else {
+        // No plugins array, need to add one - this is trickier
+        // For now, warn the user
+        console.log('Could not automatically add plugin to vite config.');
+        console.log('Please add manually:');
+        console.log("  import informer from '@entrinsik/vite-plugin-informer';");
+        console.log('  // Then add informer() to plugins array');
+        return;
+    }
+
+    await writeFile(configPath, configContent);
+    console.log(`Updated ${configPath.split('/').pop()} with informer plugin`);
+}
+
+async function copySkillFiles() {
+    const skillSrc = resolve(__dirname, '..', 'templates', 'skill');
+    const skillDest = resolve(cwd, '.claude', 'skills', 'informer');
+
+    // Create destination directory
+    await mkdir(skillDest, { recursive: true });
+
+    // Copy files recursively
+    await copyDir(skillSrc, skillDest);
+    console.log('Copied Claude skill files to .claude/skills/informer/');
+}
+
+async function copyDir(src, dest) {
+    const entries = await readdir(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            await mkdir(destPath, { recursive: true });
+            await copyDir(srcPath, destPath);
+        } else {
+            await cp(srcPath, destPath);
+        }
+    }
+}
+
+async function updateGitignore() {
+    const gitignorePath = resolve(cwd, '.gitignore');
+    let content = '';
+
+    if (await exists(gitignorePath)) {
+        content = await readFile(gitignorePath, 'utf8');
+    }
+
+    const additions = [];
+
+    if (!content.includes('.env')) {
+        additions.push('.env');
+    }
+
+    if (additions.length > 0) {
+        const newContent = content.trimEnd() + '\n\n# Informer\n' + additions.join('\n') + '\n';
+        await writeFile(gitignorePath, newContent);
+        console.log('Updated .gitignore');
+    }
+}
+
+init().catch(err => {
+    console.error('Init failed:', err.message);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@entrinsik/vite-plugin-informer",
+  "version": "1.0.0",
+  "description": "Vite plugin and publish tool for local Magic Report development",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./deploy": "./src/deploy.js"
+  },
+  "bin": {
+    "informer-deploy": "./bin/deploy.js",
+    "informer-init": "./bin/init.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "templates"
+  ],
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "UNLICENSED"
+}

package/src/client.js

@@ -0,0 +1,114 @@
+/**
+ * Informer API client using native fetch with Basic auth.
+ */
+
+class InformerApiError extends Error {
+    constructor(status, statusText, body, url) {
+        super(`Informer API ${status} ${statusText}${url ? ` (${url})` : ''}`);
+        this.name = 'InformerApiError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.url = url;
+    }
+}
+
+export { InformerApiError };
+
+const CHUNK_SIZE = 1024 * 1024; // 1MB
+
+/**
+ * Create an authenticated Informer API client.
+ * @param {{ baseUrl: string, apiKey?: string, user?: string, pass?: string }} options
+ * @returns {{ get, post, put, del, uploadChunked }}
+ */
+export function createClient({ baseUrl, apiKey, user, pass }) {
+    const auth = apiKey
+        ? 'Bearer ' + apiKey
+        : 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
+    const origin = baseUrl.replace(/\/+$/, '');
+
+    async function request(method, path, body) {
+        const url = `${origin}/api/${path}`;
+        const headers = {
+            Authorization: auth,
+            Accept: 'application/json'
+        };
+
+        const opts = { method, headers };
+
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            opts.body = JSON.stringify(body);
+        }
+
+        const res = await fetch(url, opts);
+
+        if (res.status === 404) return null;
+
+        if (!res.ok) {
+            let text;
+            try { text = await res.text(); } catch { text = ''; }
+            throw new InformerApiError(res.status, res.statusText, text, url);
+        }
+
+        const ct = res.headers.get('content-type') || '';
+        if (ct.includes('application/json') || ct.includes('hal+json')) {
+            return res.json();
+        }
+        return res.text();
+    }
+
+    /**
+     * Upload a file using chunked Flow.js protocol, then assemble into a report's library.
+     * @param {{ reportId: string, path: string, buffer: Buffer, filename: string }} opts
+     */
+    async function uploadChunked({ reportId, path, buffer, filename }) {
+        const totalChunks = Math.ceil(buffer.length / CHUNK_SIZE);
+        const uploadId = `publish-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+
+        // Upload each chunk via Flow.js protocol
+        for (let i = 1; i <= totalChunks; i++) {
+            const start = (i - 1) * CHUNK_SIZE;
+            const end = Math.min(start + CHUNK_SIZE, buffer.length);
+            const chunk = buffer.slice(start, end);
+
+            const formData = new FormData();
+            formData.append('file', new Blob([chunk]), filename);
+            formData.append('flowChunkNumber', String(i));
+            formData.append('flowChunkSize', String(CHUNK_SIZE));
+            formData.append('flowCurrentChunkSize', String(chunk.length));
+            formData.append('flowFilename', filename);
+            formData.append('flowIdentifier', uploadId);
+            formData.append('flowRelativePath', filename);
+            formData.append('flowTotalChunks', String(totalChunks));
+            formData.append('flowTotalSize', String(buffer.length));
+
+            const res = await fetch(`${origin}/api/upload/flow`, {
+                method: 'POST',
+                headers: { Authorization: auth },
+                body: formData
+            });
+
+            if (!res.ok) {
+                let text;
+                try { text = await res.text(); } catch { text = ''; }
+                throw new InformerApiError(res.status, res.statusText, text, `${origin}/api/upload/flow`);
+            }
+        }
+
+        // Assemble chunks into a file in the report's library at the specified path
+        await request('POST', `reports/${reportId}/_upload`, {
+            uploadId,
+            path
+        });
+    }
+
+    return {
+        get: (path) => request('GET', path),
+        post: (path, body) => request('POST', path, body),
+        put: (path, body) => request('PUT', path, body),
+        del: (path) => request('DELETE', path),
+        uploadChunked
+    };
+}