@nimbalyst/extension-sdk 0.2.0 → 0.2.2

package/dist/useCollaborativeEditor.js

@@ -55,11 +55,53 @@ function defaultIsEmpty(yDoc) {
     // A fully empty Y.Doc encodes to ~2 bytes (header only).
     return Y.encodeStateAsUpdate(yDoc).byteLength <= 2;
 }
+/**
+ * Normalize the config to a single internal shape. `codec` (preferred) takes
+ * its `isEmpty`/`seed` from the pure codec; the legacy shape keeps the
+ * hand-rolled `isEmpty`/`initializeFromContent`. Content is normalized to
+ * `string | Uint8Array` for the codec path (the host's `loadInitialContent`
+ * still yields `string | ArrayBuffer`).
+ */
+function resolveConfig(config) {
+    if ('codec' in config) {
+        const { codec, bind, onSeedOutcome } = config;
+        return {
+            bind,
+            isEmpty: (yDoc) => codec.isEmpty(yDoc),
+            seed: (yDoc, content) => codec.seedFromFile(yDoc, toCodecSource(content)),
+            onSeedOutcome,
+        };
+    }
+    return {
+        bind: config.createBinding,
+        isEmpty: config.isEmpty ?? defaultIsEmpty,
+        seed: config.initializeFromContent,
+        onSeedOutcome: config.onSeedOutcome,
+    };
+}
+function toCodecSource(content) {
+    return typeof content === 'string' ? content : new Uint8Array(content);
+}
+/**
+ * True when `content` can legitimately seed a first-open collaborative doc.
+ * Empty/whitespace content must never seed: the host returns '' when it has
+ * no bytes for the document (e.g. reopening an already-shared doc), and
+ * seeding from that writes a DEFAULT document into the shared room —
+ * clobbering the room's real content for every client. Exported for tests.
+ */
+export function hasSeedableContent(content) {
+    if (content == null)
+        return false;
+    if (typeof content === 'string')
+        return content.trim().length > 0;
+    return content.byteLength > 0;
+}
 export function useCollaborativeEditor(host, config) {
     const isCollaborative = !!host.collaboration;
     const [status, setStatus] = useState(host.collaboration?.getStatus() ?? 'disconnected');
     const [collaborators, setCollaborators] = useState(() => new Map());
     const [binding, setBinding] = useState(null);
+    const [seedError, setSeedError] = useState(null);
     // Keep config in a ref so the binding-creation effect doesn't tear down on
     // every render. Hosts pass fresh config objects each render, but the
     // intent is "wire once, keep until the host changes".
@@ -114,37 +156,86 @@ export function useCollaborativeEditor(host, config) {
                 return;
             if (collab.getStatus() !== 'connected')
                 return;
-            const cfg = configRef.current;
-            const isEmptyFn = cfg.isEmpty ?? defaultIsEmpty;
-            if (isEmptyFn(collab.yDoc)) {
+            const cfg = resolveConfig(configRef.current);
+            // NEVER seed when the transport skipped payloads it could not decode:
+            // the Y.Doc looking empty then means "content exists but is unreadable
+            // on this client", and seeding would write a default document over the
+            // real content for every client (the "Untitled map" clobber).
+            const undecoded = collab.hasUndecodedContent?.() === true;
+            if (!undecoded && cfg.isEmpty(collab.yDoc)) {
                 try {
                     const content = await collab.loadInitialContent();
                     if (cancelled)
                         return;
+                    // NEVER seed from empty content. A host that has no bytes for this
+                    // document (reopen of an already-shared doc: no in-memory share
+                    // payload, no file) returns ''/empty -- seeding from that writes a
+                    // default document into the shared room and clobbers whatever the
+                    // room's real content is for every client. Fall through to bind:
+                    // the room content (or a teammate's seed) will populate the doc.
+                    if (!hasSeedableContent(content)) {
+                        console.warn('[useCollaborativeEditor] Skipping first-open seed: host returned empty initial content.');
+                    }
                     // Re-check emptiness in case another client seeded while we were
                     // awaiting -- they would have raced through the WebSocket and
                     // applied their update during our await gap. Avoid double-seeding
                     // in that case; CRDT merge would otherwise insert duplicate
                     // content unless the seed is fully deterministic.
-                    if (isEmptyFn(collab.yDoc)) {
+                    else if (cfg.isEmpty(collab.yDoc)) {
                         collab.yDoc.transact(() => {
-                            cfg.initializeFromContent(collab.yDoc, content);
+                            cfg.seed(collab.yDoc, content);
                         }, COLLAB_INIT_ORIGIN);
+                        // Durability: the seed the user sees locally must reach the server
+                        // before this provider can tear down. flushWithAck resolves only
+                        // after a server-persisted ack; flushLocalState is the deprecated
+                        // fire-and-forget fallback for older hosts.
+                        const flushed = collab.flushWithAck
+                            ? await collab.flushWithAck()
+                            : (await collab.flushLocalState?.(), true);
+                        if (!flushed) {
+                            const err = new Error('Seed flush was not confirmed by the server before timeout; content may not have persisted.');
+                            console.warn('[useCollaborativeEditor]', err.message);
+                            setSeedError(err);
+                            collab.reportSeedOutcome?.({ ok: false, error: err });
+                            cfg.onSeedOutcome?.({ ok: false, error: err });
+                        }
+                        else {
+                            setSeedError(null);
+                            collab.reportSeedOutcome?.({ ok: true });
+                            cfg.onSeedOutcome?.({ ok: true });
+                        }
                     }
                 }
                 catch (err) {
                     console.error('[useCollaborativeEditor] Failed to load/seed initial content:', err);
+                    setSeedError(err);
+                    collab.reportSeedOutcome?.({ ok: false, error: err });
+                    cfg.onSeedOutcome?.({ ok: false, error: err });
                     // Continue with bind -- the doc may still be usable once another
                     // client seeds it.
                 }
             }
             if (cancelled)
                 return;
-            handle = cfg.createBinding({
+            const created = cfg.bind({
                 yDoc: collab.yDoc,
                 awareness: collab.awareness,
                 user: collab.user,
             });
+            const resolved = created instanceof Promise ? await created : created;
+            if (cancelled) {
+                // Effect unmounted while we were awaiting the extension's
+                // imperative API. Destroy the freshly-built handle so any
+                // observers/awareness subscriptions inside it get cleaned up.
+                try {
+                    resolved.destroy();
+                }
+                catch (err) {
+                    console.error('[useCollaborativeEditor] post-cancel destroy failed:', err);
+                }
+                return;
+            }
+            handle = resolved;
             setBinding(handle);
         };
         void tryStart();
@@ -161,5 +252,5 @@ export function useCollaborativeEditor(host, config) {
             setBinding(null);
         };
     }, [host]);
-    return { isCollaborative, status, collaborators, binding };
+    return { isCollaborative, status, collaborators, binding, seedError };
 }

package/dist/validate.browser.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationResult } from './validationTypes.js';
+export declare function validateExtensionBundle(_distPath: string, _bundleName?: string): Promise<ValidationResult>;
+export declare function printValidationResult(result: ValidationResult): void;
+export type { ValidationResult } from './validationTypes.js';
+//# sourceMappingURL=validate.browser.d.ts.map

package/dist/validate.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.browser.d.ts","sourceRoot":"","sources":["../src/validate.browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,SAAa,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE;AAED,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/validate.browser.js

@@ -0,0 +1,27 @@
+const BROWSER_VALIDATION_ERROR = 'validateExtensionBundle() is only available in Node.js build tooling. ' +
+    'Import it from a Vite config, build script, or other Node runtime.';
+export async function validateExtensionBundle(_distPath, _bundleName = 'index.js') {
+    return {
+        valid: false,
+        errors: [BROWSER_VALIDATION_ERROR],
+        warnings: [],
+    };
+}
+export function printValidationResult(result) {
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+        console.warn(BROWSER_VALIDATION_ERROR);
+        return;
+    }
+    if (result.errors.length > 0) {
+        console.error('Extension bundle validation errors:');
+        for (const error of result.errors) {
+            console.error(`  - ${error}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        console.warn('Extension bundle validation warnings:');
+        for (const warning of result.warnings) {
+            console.warn(`  - ${warning}`);
+        }
+    }
+}

package/dist/validate.d.ts

@@ -1,11 +1,5 @@
-export interface ValidationResult {
-    /** Whether the bundle passed validation */
-    valid: boolean;
-    /** Critical errors that will cause runtime failures */
-    errors: string[];
-    /** Warnings that may cause issues */
-    warnings: string[];
-}
+import type { ValidationResult } from './validationTypes.js';
+export type { ValidationResult } from './validationTypes.js';
 /**
  * Validates an extension bundle for common issues.
  *

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IAEf,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAkH3B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAsP3B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}

package/dist/validate.js

@@ -3,6 +3,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { validateAgentProviders, validateBackendModules, } from './manifestValidation.js';
 /**
  * Validates an extension bundle for common issues.
  *
@@ -94,6 +95,122 @@ export async function validateExtensionBundle(distPath, bundleName = 'index.js')
                     warnings.push(`manifest.json "styles" points to ${manifest.styles} but file does not exist`);
                 }
             }
+            // Validate backendModules if present. These run outside the renderer
+            // under a host-managed permission system; malformed declarations would
+            // either fail to load at runtime or, worse, declare unknown permission
+            // ids the consent prompt can't render. Catch both at build time.
+            const backendModulesIssues = validateBackendModules(manifest?.contributions?.backendModules);
+            for (const issue of backendModulesIssues) {
+                errors.push(issue.message);
+            }
+            // Also check the declared entry files exist on disk.
+            if (Array.isArray(manifest?.contributions?.backendModules)) {
+                for (const module of manifest.contributions.backendModules) {
+                    if (typeof module?.entry === 'string') {
+                        const entryPath = path.join(path.dirname(manifestPath), module.entry);
+                        if (!fs.existsSync(entryPath)) {
+                            errors.push(`backendModules[${module.id ?? '?'}].entry points to ${module.entry} but file does not exist`);
+                        }
+                    }
+                }
+            }
+            // Validate aiAgentProviders contributions: id/name/backendModuleId
+            // shape, uniqueness, model fields, toolFileLinks keys, and provider
+            // count cap. Cross-references contributions.backendModules so a typo
+            // in backendModuleId fails the build instead of erroring at runtime.
+            const agentProviderIssues = validateAgentProviders(manifest?.contributions?.aiAgentProviders, manifest?.contributions?.backendModules);
+            for (const issue of agentProviderIssues) {
+                if (issue.severity === 'warning') {
+                    warnings.push(issue.message);
+                }
+                else {
+                    errors.push(issue.message);
+                }
+            }
+            // For each agent provider, verify that the backend module it points at
+            // actually exports a usable entry point in the built bundle. The
+            // privileged host will either call `activate(context)` (the generic
+            // BackendModule contract) or `createAgentProvider(context)` (the
+            // agent-provider factory) -- catching missing exports here keeps a
+            // broken contribution from reaching the consent prompt.
+            if (Array.isArray(manifest?.contributions?.aiAgentProviders)) {
+                // Build a quick lookup so the per-provider check below can find the
+                // corresponding backend-module entry path without re-scanning the
+                // array each time.
+                const moduleEntries = new Map();
+                if (Array.isArray(manifest?.contributions?.backendModules)) {
+                    for (const moduleRaw of manifest.contributions.backendModules) {
+                        const id = moduleRaw?.id;
+                        const entry = moduleRaw?.entry;
+                        if (typeof id === 'string' && typeof entry === 'string') {
+                            moduleEntries.set(id, entry);
+                        }
+                    }
+                }
+                for (const providerRaw of manifest.contributions.aiAgentProviders) {
+                    const providerId = typeof providerRaw?.id === 'string' ? providerRaw.id : '?';
+                    const backendModuleId = typeof providerRaw?.backendModuleId === 'string'
+                        ? providerRaw.backendModuleId
+                        : undefined;
+                    if (!backendModuleId) {
+                        // Already reported by validateAgentProviders above; don't
+                        // duplicate the error here.
+                        continue;
+                    }
+                    const entryRel = moduleEntries.get(backendModuleId);
+                    if (!entryRel) {
+                        // Cross-reference error already reported by
+                        // validateAgentProviders; skip the bundle scan.
+                        continue;
+                    }
+                    const entryAbs = path.join(path.dirname(manifestPath), entryRel);
+                    if (!fs.existsSync(entryAbs)) {
+                        // The missing-file error is already raised by the backendModules
+                        // entry check above; don't pile on with a confusingly worded
+                        // duplicate. Skip the export scan.
+                        continue;
+                    }
+                    // We deliberately do a textual scan rather than executing the
+                    // module. The backend module is meant to run inside a privileged
+                    // worker; loading it inside the build script could trigger side
+                    // effects (open ports, spawn processes, write disk) that have no
+                    // business firing during `vite build`. A string check for the
+                    // known export shapes is enough to catch typos and forgotten
+                    // exports, which is the failure mode users actually hit.
+                    let entrySource;
+                    try {
+                        entrySource = fs.readFileSync(entryAbs, 'utf8');
+                    }
+                    catch (readErr) {
+                        errors.push(`aiAgentProviders[${providerId}].backendModuleId "${backendModuleId}" ` +
+                            `points at entry ${entryRel} which exists but could not be read (${String(readErr)}). ` +
+                            'The validator needs to scan the entry for an activate / createAgentProvider export.');
+                        continue;
+                    }
+                    // Look for either a top-level `export function activate` /
+                    // `export const activate` / `export { activate }`, or the same
+                    // shapes for `createAgentProvider`. Bundlers normalize these in
+                    // varied ways; the union of these patterns covers Vite, esbuild,
+                    // and tsc output. We do NOT match `exports.activate =` because
+                    // backend modules ship as ESM; CJS output would have been flagged
+                    // by the `require(` check earlier in this function anyway.
+                    const exportPatterns = [
+                        /export\s+(?:async\s+)?function\s+activate\b/,
+                        /export\s+(?:const|let|var)\s+activate\b/,
+                        /export\s*\{[^}]*\bactivate\b[^}]*\}/,
+                        /export\s+(?:async\s+)?function\s+createAgentProvider\b/,
+                        /export\s+(?:const|let|var)\s+createAgentProvider\b/,
+                        /export\s*\{[^}]*\bcreateAgentProvider\b[^}]*\}/,
+                    ];
+                    const hasExport = exportPatterns.some((p) => p.test(entrySource));
+                    if (!hasExport) {
+                        errors.push(`aiAgentProviders[${providerId}].backendModuleId "${backendModuleId}" ` +
+                            `resolves to ${entryRel}, but the entry file does not appear to export ` +
+                            'an `activate` or `createAgentProvider` function. The privileged host calls one ' +
+                            'of these to bring the provider online.');
+                    }
+                }
+            }
         }
         catch (e) {
             errors.push(`Failed to parse manifest.json: ${e}`);

package/dist/validationTypes.d.ts

@@ -0,0 +1,9 @@
+export interface ValidationResult {
+    /** Whether the bundle passed validation */
+    valid: boolean;
+    /** Critical errors that will cause runtime failures */
+    errors: string[];
+    /** Warnings that may cause issues */
+    warnings: string[];
+}
+//# sourceMappingURL=validationTypes.d.ts.map

package/dist/validationTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validationTypes.d.ts","sourceRoot":"","sources":["../src/validationTypes.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IAEf,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/validationTypes.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbalyst/extension-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SDK for building Nimbalyst extensions",
   "repository": {
     "type": "git",
@@ -13,6 +13,9 @@
   },
   "type": "module",
   "sideEffects": false,
+  "browser": {
+    "./dist/validate.js": "./dist/validate.browser.js"
+  },
   "nimbalyst": {
     "minAppVersion": "0.58.5"
   },
@@ -37,6 +40,10 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./file-tree": {
+      "types": "./dist/fileDirectoryTree.d.ts",
+      "import": "./dist/fileDirectoryTree.js"
     }
   },
   "files": [