@entrinsik/vite-plugin-informer 2.5.0 → 2.6.0-beta.1

package/src/openapi-to-dts.js

@@ -0,0 +1,168 @@
+/**
+ * Generate TypeScript declarations for bound `target: app` dependencies from
+ * their published OpenAPI docs (GET /api/apps/<app>/openapi.json), so a
+ * consumer's server/ handlers get typed `context.<slot>.request()`
+ * autocomplete on the target app's routes, params, and response shapes.
+ *
+ * Pure — no I/O. `buildDeclarations({ slot: openapiDoc })` returns a `.d.ts` string.
+ */
+
+// A slot name → a PascalCase fragment safe to use in a TS identifier. Splits on
+// any non-alphanumeric run (so `a-b` and `a_b` both normalize the same way — the
+// caller disambiguates collisions), and guarantees the result starts with a
+// letter/underscore so a digit-leading slot (`2fa`) can't emit invalid TS.
+function pascalCase (s) {
+    const parts = String(s).split(/[^A-Za-z0-9]+/).filter(Boolean);
+    let id = parts.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+    if (!id) id = 'Slot';
+    if (!/^[A-Za-z_$]/.test(id)) id = '_' + id;
+    return id;
+}
+
+// A safe TS property key: bare identifier, or a quoted string otherwise.
+function tsKey (k) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+}
+
+// The JSON Schema subset an app declares → a TS type string.
+function jsonSchemaToTs (schema) {
+    if (!schema || typeof schema !== 'object') return 'any';
+    if (Array.isArray(schema.enum) && schema.enum.length) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
+    }
+    switch (schema.type) {
+        case 'string': return 'string';
+        case 'integer':
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'null': return 'null';
+        case 'array': return `${jsonSchemaToTs(schema.items || {})}[]`;
+        default:
+            if (schema.properties) return objectType(schema);
+            return schema.type === 'object' ? 'Record<string, any>' : 'any';
+    }
+}
+
+function objectType (schema) {
+    const props = schema.properties || {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const keys = Object.keys(props);
+    if (!keys.length) return 'Record<string, any>';
+    const fields = keys.map((k) => `${tsKey(k)}${required.has(k) ? '' : '?'}: ${jsonSchemaToTs(props[k])}`);
+    return `{ ${fields.join('; ')} }`;
+}
+
+// OpenAPI path (/issues/{key}) → the `url` literal used in request({ url }).
+// The consumer passes a leading-slash-free path; `{param}` segments become
+// `${string}` template holes so an interpolated url still type-checks.
+function urlType (path) {
+    const rel = path.replace(/^\//, '');
+    if (!rel.includes('{')) return JSON.stringify(rel);
+    return '`' + rel.replace(/\{[^}]+\}/g, '${string}') + '`';
+}
+
+function queryParamsType (op) {
+    const params = (op.parameters || []).filter((p) => p.in === 'query');
+    if (!params.length) return null;
+    const fields = params.map((p) => `${tsKey(p.name)}${p.required ? '' : '?'}: ${jsonSchemaToTs(p.schema || {})}`);
+    return { type: `{ ${fields.join('; ')} }`, required: params.some((p) => p.required) };
+}
+
+function jsonSchemaOf (container) {
+    return container && container.content && container.content['application/json']
+        ? container.content['application/json'].schema
+        : undefined;
+}
+
+function requestOverload (method, path, op) {
+    const parts = [`method: ${JSON.stringify(method.toUpperCase())}`, `url: ${urlType(path)}`];
+
+    const q = queryParamsType(op);
+    if (q) parts.push(`params${q.required ? '' : '?'}: ${q.type}`);
+
+    const bodySchema = jsonSchemaOf(op.requestBody);
+    if (bodySchema) parts.push(`data: ${jsonSchemaToTs(bodySchema)}`);
+
+    const respSchema = op.responses && op.responses['200'] ? jsonSchemaOf(op.responses['200']) : undefined;
+    const ret = respSchema ? jsonSchemaToTs(respSchema) : 'any';
+
+    const summary = op.summary || op.description;
+    const doc = summary ? `    /** ${String(summary).replace(/\*\//g, '*\\/')} */\n` : '';
+    return `${doc}    request(opts: { ${parts.join('; ')} }): Promise<${ret}>;`;
+}
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+function slotInterface (iface, spec) {
+    const overloads = [];
+    for (const [path, item] of Object.entries(spec.paths || {})) {
+        for (const method of HTTP_METHODS) {
+            if (item[method]) overloads.push(requestOverload(method, path, item[method]));
+        }
+    }
+    // Escape hatch, listed last so the typed overloads win when they match. The
+    // shape mirrors what the runtime driver actually reads — { method, url,
+    // params, data } — no `headers`, which the driver ignores (entity-type/app.js).
+    overloads.push('    /** Escape hatch — any method/url (bypasses the typed contract). */');
+    overloads.push('    request(opts: { method?: string; url: string; params?: Record<string, unknown>; data?: unknown }): Promise<any>;');
+
+    return [
+        `export interface ${iface} {`,
+        overloads.join('\n'),
+        '}'
+    ].join('\n');
+}
+
+/**
+ * @param {Record<string, object>} specsBySlot - { slotName: openapiDoc }
+ * @returns {string} a `.d.ts` document
+ */
+export function buildDeclarations (specsBySlot) {
+    const interfaces = [];
+    const slotFields = [];
+    const usedIfaces = new Set();
+    for (const [slot, spec] of Object.entries(specsBySlot)) {
+        // Distinct slots can normalize to the same PascalCase (e.g. `a-b`/`a_b`);
+        // suffix on collision so TS doesn't silently merge the two interfaces.
+        const base = pascalCase(slot) + 'Api';
+        let iface = base;
+        for (let n = 2; usedIfaces.has(iface); n++) iface = `${base}_${n}`;
+        usedIfaces.add(iface);
+
+        interfaces.push(slotInterface(iface, spec));
+        slotFields.push(`    ${tsKey(slot)}: ${iface};`);
+    }
+
+    return `// AUTO-GENERATED by vite-plugin-informer — do not edit.
+// Typed from bound \`target: app\` dependencies' OpenAPI docs; regenerated on \`npm run dev\`.
+//
+// Use in a server/ handler. The import path is relative to the handler file —
+// add one ../ per directory below server/ (e.g. server/issues/index.js → ../../):
+//   /** @param {import('../../.informer/app-deps').HandlerBag} bag */
+//   export async function GET(bag) { const { context } = bag; /* context.<slot>.request(...) */ }
+
+${interfaces.join('\n\n')}
+
+export interface AppDependencies {
+${slotFields.join('\n')}
+}
+
+export interface HandlerBag {
+    context: AppDependencies & Record<string, any>;
+    request: {
+        method: string;
+        path: string;
+        query: Record<string, string>;
+        body: any;
+        params: Record<string, string>;
+        roles: string[];
+        user: any;
+        headers: Record<string, string>;
+    };
+    query(sql: string, params?: unknown[]): Promise<any[]>;
+    [key: string]: any;
+}
+`;
+}
+
+export const _internal = { jsonSchemaToTs, urlType, queryParamsType, pascalCase };

package/src/publish.js

@@ -0,0 +1,103 @@
+import { mkdtemp, mkdir, copyFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileP = promisify(execFile);
+
+class PublishError extends Error {
+    constructor(status, body, url) {
+        super(`Marketplace publish failed: ${status}${body ? ` — ${body}` : ''}${url ? ` (${url})` : ''}`);
+        this.name = 'PublishError';
+        this.status = status;
+        this.body = body;
+        this.url = url;
+    }
+}
+
+export { PublishError };
+
+/**
+ * Stage the assembled files into a temp dir (preserving their library-relative
+ * layout) and tar.gz them. System `tar` keeps the archive format exactly what
+ * the server's node-tar expects; COPYFILE_DISABLE suppresses macOS AppleDouble
+ * (`._*`) junk from leaking into the archive.
+ *
+ * @param {Array<{abs: string, rel: string}>} files
+ * @returns {Promise<Buffer>}
+ */
+async function buildArchive(files) {
+    const stage = await mkdtemp(join(tmpdir(), 'informer-publish-'));
+    const archivePath = `${stage}.tgz`;
+    try {
+        for (const { abs, rel } of files) {
+            const dest = join(stage, rel);
+            await mkdir(dirname(dest), { recursive: true });
+            await copyFile(abs, dest);
+        }
+        await execFileP('tar', ['-czf', archivePath, '-C', stage, '.'], {
+            env: { ...process.env, COPYFILE_DISABLE: '1' }
+        });
+        return await readFile(archivePath);
+    } finally {
+        await rm(stage, { recursive: true, force: true });
+        await rm(archivePath, { force: true });
+    }
+}
+
+/**
+ * Publish an assembled app to the marketplace (License Manager `/packs/publish`).
+ *
+ * @param {Object} opts
+ * @param {string} opts.marketplaceUrl - base URL fronting the cloud-api
+ * @param {string} opts.token - vendor publish token (sent as Bearer)
+ * @param {Array<{abs: string, rel: string}>} opts.files - assembled app files
+ * @param {Object} opts.fields - publish metadata; non-string values are JSON-encoded
+ *   (the endpoint parses categories/requires/metadata as JSON strings)
+ * @param {{abs: string, filename: string}} [opts.icon] - optional listing icon
+ * @returns {Promise<Object>} the publish response
+ */
+export async function publish({ marketplaceUrl, token, files, fields, icon, screenshots = [] }) {
+    const archive = await buildArchive(files);
+
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null || value === '') continue;
+        form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
+    }
+    form.append(
+        'archive',
+        new Blob([archive], { type: 'application/gzip' }),
+        `${fields.slug}-${fields.version}.tgz`
+    );
+    if (icon) {
+        const iconBuffer = await readFile(icon.abs);
+        form.append('icon', new Blob([iconBuffer]), icon.filename);
+    }
+    // Listing screenshots — appended in order; the server records sortOrder by
+    // the order parts arrive.
+    for (const shot of screenshots) {
+        const buffer = await readFile(shot.abs);
+        form.append('screenshots', new Blob([buffer]), shot.filename);
+    }
+
+    const url = `${marketplaceUrl.replace(/\/+$/, '')}/packs/publish`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+        body: form
+    });
+
+    if (!res.ok) {
+        let body = '';
+        try {
+            body = await res.text();
+        } catch {
+            body = '';
+        }
+        throw new PublishError(res.status, body, url);
+    }
+
+    return await res.json();
+}

package/src/server-routes.js

@@ -5,6 +5,10 @@ import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDev
 
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
+// Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
+// hanging the handler.
+const FETCH_TIMEOUT_MS = 30000;
+
 // Strict base64 — see view-api.js for the rationale. Mirror kept identical
 // to keep dev and prod behavior aligned.
 const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -144,10 +148,17 @@ async function walkJsFiles(dir, basePath) {
  * Create Connect middleware for dev-mode server route execution.
  *
  * @param {Object} viteServer - Vite dev server instance
- * @param {{ serverOrigin: string, authHeader: string, devWorkspaceId: string|null, projectRoot: string }} opts
+ * @param {Object} opts
+ * @param {string} opts.serverOrigin - Informer server origin
+ * @param {string} opts.authHeader - Basic or Bearer auth header for /api calls
+ * @param {string|null} opts.devWorkspaceId - workspace datasource id for query()
+ * @param {string} opts.projectRoot - app project root
+ * @param {string[]} [opts.roles] - dev user roles surfaced on request.roles
+ * @param {Object} [opts.devBindings] - dev bindings for `target: app` deps
+ * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
  * @returns {Function} Connect middleware
  */
-export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles }) {
+export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, devBindings, appToken }) {
     const serverDir = join(projectRoot, 'server');
 
     // query() implementation — proxies to the workspace _sql endpoint
@@ -173,30 +184,65 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
     }
 
     // fetch() implementation — proxies API calls to the Informer server
-    async function apiFetch(path, opts = {}) {
+    async function fetchAs(auth, path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
         // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath);
         // reject non-canonical shapes here instead of silently accepting them.
         const apiPath = normalizeFetchPath(path);
         if (!apiPath) {
-            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` } };
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` }, contentType: 'application/json' };
         }
         const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
-            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
         };
 
-        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
             fetchOpts.body = JSON.stringify(opts.body);
         }
 
-        const resp = await globalThis.fetch(url, fetchOpts);
+        // Read the stream exactly once — `.json()` consumes/locks the body, so a
+        // `.text()` fallback would throw "Body is unusable" on any non-JSON
+        // response (auth-bounce HTML, proxy error page). Parse in memory
+        // instead — same as prod's unwrapInject.
+        let status, contentType, text;
+        try {
+            const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            status = resp.status;
+            contentType = resp.headers.get('content-type') || '';
+            text = await resp.text();
+        } catch (err) {
+            // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
+            // with the real reason on err.cause, or a TimeoutError). Return a
+            // synthetic 502 so the dependency layer names it (dep + url + cause)
+            // rather than a bare unhandled "fetch failed".
+            const reason = (err.cause && err.cause.message) || err.message;
+            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
+        }
         let body;
-        try { body = await resp.json(); } catch { body = await resp.text(); }
-        return { status: resp.status, body };
+        try { body = JSON.parse(text); } catch { body = text; }
+        return { status, body, contentType };
     }
 
+    async function apiFetch(path, opts = {}) {
+        return await fetchAs(authHeader, path, opts);
+    }
+
+    // Cross-app request() targets /api/apps/<id>/view/_/<path>, whose auth accepts
+    // only the token/session strategies — NOT basic auth. In API-key mode the
+    // INFORMER_API_KEY Bearer already satisfies that, so reuse it; under basic
+    // auth a separate API token (INFORMER_APP_TOKEN) is required, and without one
+    // the app proxy's request() throws a pointed error instead of a bare 401.
+    // appFetch also stamps x-informer-app-depth:1 so the target runs one hop deep
+    // and enforces the same one-hop guard it does in production.
+    const appAuth = appToken
+        ? `Bearer ${appToken}`
+        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
+    const appFetch = appAuth
+        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
+        : null;
+
     return async function serverRoutesMiddleware(req, res, next) {
         try {
             // The URL has already had /api/_server stripped by Vite's middleware.use()
@@ -307,7 +353,7 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
             // work locally. Loaded per request so edits to informer.yaml take
             // effect without a dev-server restart.
             const deps = await loadDependencies(projectRoot);
-            const context = buildDevContext({ deps, apiFetch });
+            const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
             const env = await loadAppEnv(projectRoot);
 
             // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).