@entrinsik/vite-plugin-informer 2.3.0 → 2.5.0-beta.0

package/bin/deploy.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { deploy } from '../src/deploy.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
 const baseUrl = process.env.INFORMER_URL;
 const apiKey = process.env.INFORMER_API_KEY;

package/bin/init.js

@@ -13,40 +13,66 @@ const cwd = process.cwd();
 function generateInformerYaml() {
     return `# Informer App Configuration
 # =========================
-# This file controls which Informer APIs your app can access and defines
-# custom roles for role-based UIs.
+# This file controls the data your app depends on and defines custom
+# roles for role-based UIs.
 #
-# Without an access section, all API access is blocked (secure by default).
+# Without dependencies: or access:, all API access is blocked (secure
+# by default).
 
 # ============================================================================
-# DATA ACCESS
+# DEPENDENCIES (preferred)
 # ============================================================================
-# The access section controls which APIs the app can call when shared.
+# Typed slots that the installer binds to actual resources at deploy
+# time. Each slot becomes a property on the handler context object —
+# call methods on it instead of building raw API URLs.
 #
-# access:
-#   datasets:
-#     - admin:sales-data             # Full dataset access
-#     - id: admin:orders             # With row-level security
-#       filter:
-#         region: $user.custom.region
+# Slot methods by target:
+#   dataset     → context.<slot>.search(esQuery)  /  context.<slot>.fields()
+#   query       → context.<slot>.execute(params)
+#   datasource  → context.<slot>.query(payload)
+#   integration → context.<slot>.request({ method, path, body })
 #
-#   queries:
-#     - admin:monthly-summary
+# defaultBinding must be a UUID (not a configId). Look up UUIDs via:
+#   GET /api/datasets-list      → for target: dataset
+#   GET /api/queries-list       → for target: query
+#   GET /api/datasources-list   → for target: datasource
+#   GET /api/integrations-list  → for target: integration
 #
-#   integrations:
-#     - salesforce
+# Example:
 #
-#   datasources:
-#     - postgres-main
+# dependencies:
+#   sales:
+#     target: dataset
+#     defaultBinding: 7d5a9b1e-0c83-4bde-9e2a-3a4b5c6d7e8f
+#   orders:
+#     target: dataset
+#     defaultBinding: 1f2e3d4c-5b6a-7980-1234-56789abcdef0
+#     options:
+#       filter:
+#         region: $user.custom.region    # Row-level security
+#   monthly_summary:
+#     target: query
+#     defaultBinding: 9a8b7c6d-5e4f-3a2b-1c0d-fedcba987654
+#   salesforce:
+#     target: integration                # No defaultBinding — installer picks
+#     options:
+#       headers:
+#         Authorization: Bearer $user.custom.sfToken
+
+dependencies: {}
+
+# ============================================================================
+# ACCESS (raw API allowlist — for paths that don't fit the typed-slot model)
+# ============================================================================
+# Use access.apis for endpoints not covered by dependencies: slots,
+# such as AI model routes or custom server endpoints.
 #
-#   apis:                            # Raw API paths (advanced)
+# access:
+#   apis:
+#     - POST /api/models/go_everyday/_object
+#     - POST /api/models/go_everyday/_chat
 #     - POST /api/custom/endpoint
 
-access:
-  datasets: []
-  queries: []
-  integrations: []
-
 # ============================================================================
 # ROLES (optional)
 # ============================================================================
@@ -111,7 +137,8 @@ async function init() {
     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');
+        console.error('Create one first with: npm create vite@latest . -- --template react');
+        console.error('(Use --template react-ts for TypeScript, or vanilla/vue/svelte/etc.)');
         process.exit(1);
     }
 
@@ -121,7 +148,8 @@ async function init() {
     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');
+        console.error('Create a Vite project first: npm create vite@latest . -- --template react');
+        console.error('(Use --template react-ts for TypeScript, or vanilla/vue/svelte/etc.)');
         process.exit(1);
     }
 
@@ -198,7 +226,7 @@ INFORMER_API_KEY=your-api-key
     const informerYamlPath = resolve(cwd, 'informer.yaml');
     if (!await exists(informerYamlPath)) {
         await writeFile(informerYamlPath, generateInformerYaml());
-        console.log('Created informer.yaml (configure API access and roles)');
+        console.log('Created informer.yaml (declare your data dependencies and roles)');
     }
 
     // 10. Add .env to .gitignore if not present
@@ -207,7 +235,7 @@ INFORMER_API_KEY=your-api-key
     console.log('\nSetup complete!\n');
     console.log('Next steps:');
     console.log('  1. Update .env with your Informer credentials');
-    console.log('  2. Update informer.yaml with the datasets/APIs your app needs');
+    console.log('  2. Declare your data dependencies in informer.yaml (see comments inside)');
     console.log('  3. Run: npm install');
     console.log('  4. Run: npm run dev');
     console.log('');

package/bin/publish.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { readFile, access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { collectAppFiles } from '../src/assemble.js';
+import { extractNotes } from '../src/changelog.js';
+import { publish } from '../src/publish.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
+
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
+
+// --- Target + auth. You already have API keys sorted — just point these at the
+//     License Manager that fronts the marketplace cloud-api. ---
+const marketplaceUrl = process.env.INFORMER_MARKETPLACE_URL;
+const token = process.env.INFORMER_PUBLISH_TOKEN || process.env.INFORMER_API_KEY;
+
+if (!marketplaceUrl || !token) {
+    console.error('Missing required environment variables.');
+    console.error('  INFORMER_MARKETPLACE_URL=https://<license-manager-host>/cloud-api');
+    console.error('  INFORMER_PUBLISH_TOKEN=lmpub_<vendor publish key>');
+    process.exit(1);
+}
+
+// --- App + listing metadata from package.json "informer" block ---
+const projectRoot = resolve('.');
+let pkg;
+try {
+    pkg = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'));
+} catch {
+    console.error('Could not read package.json in current directory.');
+    process.exit(1);
+}
+
+const inf = pkg.informer || {};
+const name = inf.name || pkg.name;
+const slug = inf.slug || defaultSlug(name);
+
+// Version: prefer the git tag (CI: GITHUB_REF_NAME=vX.Y.Z), then --version, then package.json.
+const version = argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME) || pkg.version;
+
+if (!name || !slug || !version) {
+    console.error('Need a name, slug, and version. Set package.json "informer.name"/"informer.slug" and tag a release (vX.Y.Z) or pass --version.');
+    process.exit(1);
+}
+
+// Release notes: the section for this version, else the cumulative Unreleased block.
+const changeNotes = await extractNotes(join(projectRoot, 'CHANGELOG.md'), version);
+
+// Provenance (GitHub Actions). All optional — best-effort audit trail.
+const sourceRepo = process.env.GITHUB_REPOSITORY || undefined;
+const sourceCommit = process.env.GITHUB_SHA || undefined;
+const ciRun = process.env.GITHUB_RUN_ID
+    ? `${process.env.GITHUB_SERVER_URL || 'https://github.com'}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+    : undefined;
+
+// Assemble the same file set a deploy produces.
+let files;
+try {
+    files = await collectAppFiles({ distDir: join(projectRoot, 'dist'), projectRoot });
+} catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+
+const icon = await resolveIcon(projectRoot, inf.icon);
+const channel = version.includes('-') ? 'beta' : 'stable';
+
+console.log(`Publishing ${name} v${version} (${channel}) — ${files.length} files${changeNotes ? '' : ' — no release notes found'}`);
+
+try {
+    const result = await publish({
+        marketplaceUrl,
+        token,
+        files,
+        icon,
+        fields: {
+            name,
+            slug,
+            version,
+            shortDescription: inf.shortDescription,
+            description: inf.description || pkg.description,
+            categories: inf.categories,
+            documentationUrl: inf.documentationUrl,
+            requires: inf.requires,
+            metadata: inf.metadata,
+            changeNotes,
+            sourceRepo,
+            sourceCommit,
+            ciRun
+        }
+    });
+    console.log(`Published ${slug} v${version} (${result.channel || channel}).`);
+} catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+
+// --- helpers ---
+
+function argValue(flag) {
+    const i = process.argv.indexOf(flag);
+    return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
+}
+
+function tagVersion(ref) {
+    return ref ? ref.replace(/^v/, '') : undefined;
+}
+
+function defaultSlug(value) {
+    if (!value) return undefined;
+    const base = value.startsWith('@') && value.includes('/') ? value.split('/')[1] : value;
+    return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+async function resolveIcon(root, configured) {
+    const candidates = [configured, 'favicon.svg', join('public', 'favicon.svg'), join('dist', 'favicon.svg')].filter(Boolean);
+    for (const rel of candidates) {
+        const abs = resolve(root, rel);
+        try {
+            await access(abs);
+            return { abs, filename: rel.split(/[/\\]/).pop() };
+        } catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+}

package/bin/workspace.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from '../src/client.js';
+import { loadEnv, envWritePath, parseModeArg } from '../src/env.js';
 import { init, migrate, reset } from '../src/workspace.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
-const command = process.argv[2];
+// Strip --mode <value> from argv before parsing the command
+const args = process.argv.slice(2).filter((arg, i, arr) => arg !== '--mode' && arr[i - 1] !== '--mode');
+const command = args[0];
 
 if (!command || !['init', 'migrate', 'reset'].includes(command)) {
-    console.error('Usage: informer-workspace <init|migrate|reset>');
+    console.error('Usage: informer-workspace <init|migrate|reset> [--mode <name>]');
     console.error('');
     console.error('Commands:');
     console.error('  init      Create a dev workspace datasource and run migrations');
     console.error('  migrate   Run pending migrations against the dev workspace');
     console.error('  reset     Drop all tables and re-run all migrations');
+    console.error('');
+    console.error('Options:');
+    console.error('  --mode <name>  Load .env.<name> (e.g. --mode test, --mode production)');
     process.exit(1);
 }
 
@@ -33,7 +39,7 @@ if (!baseUrl || (!apiKey && (!user || !pass))) {
 
 const api = createClient({ baseUrl, apiKey, user, pass });
 const migrationsDir = resolve('migrations');
-const envPath = resolve('.env');
+const envPath = envWritePath({ mode });
 
 try {
     if (command === 'init') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.3.0",
+    "version": "2.5.0-beta.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "repository": {
         "type": "git",
@@ -24,10 +24,12 @@
             "default": "./src/index.js"
         },
         "./deploy": "./src/deploy.js",
+        "./publish": "./src/publish.js",
         "./workspace": "./src/workspace.js"
     },
     "bin": {
         "informer-deploy": "./bin/deploy.js",
+        "informer-publish": "./bin/publish.js",
         "informer-init": "./bin/init.js",
         "informer-workspace": "./bin/workspace.js",
         "create-magic-report": "./bin/init.js"

package/src/agent-dev.js

@@ -2,6 +2,7 @@ import { readFile, readdir, stat, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
+import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 const parseYaml = yaml.parse;
 
 const MAX_STEPS = 20;
@@ -170,7 +171,12 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
     // fetch() — proxies API calls to the Informer server (same as server-routes.js)
     async function apiFetch(path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
-        const url = `${serverOrigin}/api/${path.replace(/^\/?(?:api\/)?/, '')}`;
+        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath).
+        const apiPath = normalizeFetchPath(path);
+        if (!apiPath) {
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` } };
+        }
+        const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
             headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
@@ -192,6 +198,33 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { ok: true };
     }
 
+    // notify/email — delivery is a console-logged no-op in dev, but required-field
+    // validation mirrors prod so a tool that passes here won't 500 in production.
+    const { notify, email } = buildDevMessaging('[agent-dev]');
+
+    // crypto helper — mirrors the prod sandbox crypto surface
+    const cryptoHelper = buildDevCrypto();
+
+    // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
+    const logCall = (level, message, data) => {
+        const msg = typeof message === 'string' ? message : JSON.stringify(message);
+        const args = [`[app-log] [${level}] ${msg}`];
+        if (data) args.push(data);
+        console.log(...args);
+    };
+    const log = Object.assign(
+        (message, data) => logCall('info', message, data),
+        {
+            debug: (message, data) => logCall('debug', message, data),
+            info: (message, data) => logCall('info', message, data),
+            warn: (message, data) => logCall('warn', message, data),
+            error: (message, data) => logCall('error', message, data)
+        }
+    );
+
+    // markdown helper — passthrough in dev (production uses `marked`)
+    const markdown = (text) => text;
+
     return async function agentDevMiddleware(req, res, next) {
         try {
             const parsed = parseUrl(req.url, true);
@@ -249,6 +282,14 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 const instructions = agentDef.instructions || '';
                 const agentToolNames = agentDef.tools || [];
 
+                // Build the typed dependency context + env the same way the
+                // server-routes dev middleware does, so tools using
+                // `context.<slot>.<method>(...)` and `env` work locally and match
+                // the prod sandbox bag.
+                const deps = await loadDependencies(projectRoot);
+                const context = buildDevContext({ deps, apiFetch });
+                const env = await loadAppEnv(projectRoot);
+
                 // Load tool handlers via ssrLoadModule
                 const localTools = await scanLocalTools(projectRoot);
                 const toolMap = new Map(localTools.map(t => [t.name, t]));
@@ -366,7 +407,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler(tc.input, { query, fetch: apiFetch, emit, context: triggerEvent });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, notify, email, crypto: cryptoHelper, markdown, log, env });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/assemble.js

@@ -0,0 +1,87 @@
+import { readdir, stat, access } from 'node:fs/promises';
+import { join, relative, posix } from 'node:path';
+
+/**
+ * The canonical set of files that make up a deployable Informer app library.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for what an app "is" on disk, shared by
+ * both `informer-deploy` (uploads each file to a live instance) and
+ * `informer-publish` (tars the same set for the marketplace). Keeping the
+ * enumeration in one place is what guarantees a published artifact is
+ * byte-identical to what a normal deploy produces.
+ *
+ * Layout rule: the Vite build output (`dist/`) lands at the library ROOT
+ * (index.html, assets/…), while the source trees keep their directory prefix
+ * (server/…, tools/…) — matching how an app's library is structured in Informer.
+ */
+const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
+const SOURCE_DIRS = ['migrations', 'tools', 'server', 'webhooks'];
+
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Recursively walk a directory, returning absolute file paths (not dirs). */
+async function walkDir(dir) {
+    const results = [];
+    const items = await readdir(dir);
+    for (const item of items) {
+        const full = join(dir, item);
+        const s = await stat(full);
+        if (s.isDirectory()) {
+            results.push(...await walkDir(full));
+        } else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+/** Normalise a path to forward slashes for use as a library/tar entry name. */
+function toLibraryPath(p) {
+    return posix.normalize(p.split('\\').join('/'));
+}
+
+/**
+ * Collect every file that belongs in the app library, each as { abs, rel },
+ * where `rel` is the path it should occupy in the library (and in the tar).
+ *
+ * @param {{ distDir: string, projectRoot: string }} opts
+ * @returns {Promise<Array<{ abs: string, rel: string }>>}
+ */
+export async function collectAppFiles({ distDir, projectRoot }) {
+    if (!await exists(distDir)) {
+        throw new Error(`Build output not found at "${distDir}" — run the build first.`);
+    }
+
+    const files = [];
+
+    // dist/** -> library root
+    for (const abs of await walkDir(distDir)) {
+        files.push({ abs, rel: toLibraryPath(relative(distDir, abs)) });
+    }
+
+    // root config files -> library root
+    for (const name of ROOT_CONFIG_FILES) {
+        const abs = join(projectRoot, name);
+        if (await exists(abs)) files.push({ abs, rel: name });
+    }
+
+    // source trees -> keep their prefix (server/…, migrations/…, tools/…, webhooks/…)
+    for (const dir of SOURCE_DIRS) {
+        const root = join(projectRoot, dir);
+        if (!await exists(root)) continue;
+        for (const abs of await walkDir(root)) {
+            files.push({ abs, rel: toLibraryPath(relative(projectRoot, abs)) });
+        }
+    }
+
+    return files;
+}
+
+export { ROOT_CONFIG_FILES, SOURCE_DIRS };

package/src/changelog.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Extract release notes for a version from a Keep-a-Changelog style CHANGELOG.md.
+ *
+ * Looks for the section header whose name matches `version` (e.g. `## [1.4.0]`,
+ * `## 1.4.0`, `## v1.4.0`); if absent, falls back to `## [Unreleased]`. Returns
+ * the section body trimmed, or '' if nothing matches / the file is missing.
+ *
+ * This is what makes the dual notes flow work: betas ship the cumulative
+ * `Unreleased` block, while a stable release promotes `Unreleased` to a
+ * versioned heading before tagging so its exact section is matched.
+ *
+ * @param {string} changelogPath
+ * @param {string} version
+ * @returns {Promise<string>}
+ */
+export async function extractNotes(changelogPath, version) {
+    let text;
+    try {
+        text = await readFile(changelogPath, 'utf8');
+    } catch {
+        return '';
+    }
+    return sectionBody(text, version) ?? sectionBody(text, 'Unreleased') ?? '';
+}
+
+/** Body of the first `## [name]` / `## name` section, up to the next `## `. */
+function sectionBody(text, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const header = new RegExp(`^##\\s+\\[?v?${escaped}\\]?.*$`, 'im');
+    const match = header.exec(text);
+    if (!match) return null;
+
+    const after = text.slice(match.index + match[0].length);
+    const next = after.search(/^##\s/m);
+    const body = (next === -1 ? after : after.slice(0, next)).trim();
+    return body || null;
+}