@nimbalyst/extension-sdk 0.2.0 → 0.2.1

package/dist/manifestValidation.js

@@ -0,0 +1,475 @@
+/**
+ * Pure (no Node/Electron deps) validation helpers for manifest fields.
+ *
+ * Runs at both build time (via validate.ts, which reads manifest.json from
+ * disk) and runtime (when the host loads an extension and needs to refuse
+ * invalid contributions). Keep this file dependency-free so it can be bundled
+ * into either context without dragging in fs/path.
+ */
+import { MAX_BACKEND_MODULES_PER_EXTENSION } from './types/extension.js';
+/**
+ * Manifest validation rejects extensions declaring more than this many AI
+ * agent providers. Chosen by symmetry with
+ * {@link MAX_BACKEND_MODULES_PER_EXTENSION}: an extension that ships more than
+ * a handful of agent providers is almost certainly mis-modeled (split it into
+ * multiple extensions, or surface them as models on one provider). The cap
+ * also keeps the settings UI -- which lists each provider as its own row --
+ * from running away.
+ */
+export const MAX_AGENT_PROVIDERS_PER_EXTENSION = 4;
+const AGENT_PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Mirrors the host's permission registry. We duplicate the list here so
+ * extensions don't have to depend on Electron internals to validate locally.
+ * Adding a new id requires updating both this list AND
+ * `packages/electron/src/main/extensions/permissionRegistry.ts`.
+ */
+const KNOWN_PERMISSION_IDS = [
+    'workspace-files',
+    'nimbalyst-database-read',
+    'nimbalyst-database-write',
+    'secrets-read',
+    'mcp-server-register',
+];
+/**
+ * Permission ids that used to be in the catalog but never enforced anything
+ * meaningful at the backend boundary (ambient Node capabilities). Manifests
+ * that still reference them are accepted -- the validator silently drops the
+ * id from the effective list -- so we don't break older extensions during
+ * the catalog cleanup. Authors get a non-fatal warning issue back.
+ */
+const DEPRECATED_PERMISSION_IDS = [
+    'spawn-process',
+    'network-loopback',
+    'network-internet',
+    'filesystem',
+];
+const KNOWN_RUNTIMES = [
+    'utility-process',
+    'worker-thread',
+];
+const BACKEND_MODULE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Validate the `contributions.backendModules` array on a manifest.
+ * Returns the list of problems found - empty means valid.
+ *
+ * Callers decide whether to treat issues as fatal (host loader: refuse the
+ * extension) or as warnings (build-time validator: print and continue with
+ * non-zero exit).
+ */
+export function validateBackendModules(backendModules) {
+    if (backendModules === undefined) {
+        return [];
+    }
+    if (!Array.isArray(backendModules)) {
+        return [{ message: 'contributions.backendModules must be an array' }];
+    }
+    const issues = [];
+    if (backendModules.length > MAX_BACKEND_MODULES_PER_EXTENSION) {
+        issues.push({
+            message: `contributions.backendModules declares ${backendModules.length} modules; ` +
+                `the maximum is ${MAX_BACKEND_MODULES_PER_EXTENSION}. ` +
+                'Consolidate modules to keep the consent prompt manageable.',
+        });
+    }
+    const seenIds = new Set();
+    for (let i = 0; i < backendModules.length; i += 1) {
+        const raw = backendModules[i];
+        if (!raw || typeof raw !== 'object') {
+            issues.push({ message: `backendModules[${i}] must be an object` });
+            continue;
+        }
+        const module = raw;
+        const moduleLabel = typeof module.id === 'string' ? module.id : `index ${i}`;
+        if (typeof module.id !== 'string' || !BACKEND_MODULE_ID_PATTERN.test(module.id)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].id must be a lowercase string matching ` +
+                    `${BACKEND_MODULE_ID_PATTERN.source} (got ${JSON.stringify(module.id)})`,
+            });
+        }
+        else if (seenIds.has(module.id)) {
+            issues.push({
+                moduleId: module.id,
+                message: `backendModules contains duplicate id "${module.id}"`,
+            });
+        }
+        else {
+            seenIds.add(module.id);
+        }
+        if (typeof module.entry !== 'string' || module.entry.length === 0) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].entry must be a non-empty relative path string`,
+            });
+        }
+        else if (module.entry.startsWith('/') || module.entry.includes('..')) {
+            // Refuse absolute paths and parent-directory traversal so a module
+            // can't escape its extension root. The host resolves entry relative
+            // to the extension directory; only safe relative paths belong here.
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].entry must be a relative path within the extension root ` +
+                    `(no leading "/", no ".." segments)`,
+            });
+        }
+        if (!KNOWN_RUNTIMES.includes(module.runtime)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].runtime must be one of: ${KNOWN_RUNTIMES.join(', ')} ` +
+                    `(got ${JSON.stringify(module.runtime)})`,
+            });
+        }
+        if (module.permissions !== undefined && !Array.isArray(module.permissions)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].permissions must be an array of ` +
+                    `host-brokered capability ids (or omitted). The implicit "run native ` +
+                    `code" grant is conferred by enabling the module itself, not by an ` +
+                    `entry in this array.`,
+            });
+        }
+        else if (Array.isArray(module.permissions)) {
+            const uniquePermissions = new Set();
+            for (const permission of module.permissions) {
+                if (typeof permission !== 'string') {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains non-string entry`,
+                    });
+                    continue;
+                }
+                if (DEPRECATED_PERMISSION_IDS.includes(permission)) {
+                    // Older manifests still ship these. They never meaningfully gated
+                    // anything inside the backend runtime (ambient Node access), and
+                    // the catalog cleanup removed them. Warn the author and silently
+                    // drop the id from the effective list.
+                    issues.push({
+                        severity: 'warning',
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions includes deprecated id "${permission}". ` +
+                            `This id is unenforceable inside a Node backend (the module can require child_process/fs/net ` +
+                            `directly) and has been removed from the catalog. Granting the module is itself the consent ` +
+                            `to run native code; drop this id from your manifest.`,
+                    });
+                    continue;
+                }
+                if (!KNOWN_PERMISSION_IDS.includes(permission)) {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains unknown id "${permission}". ` +
+                            `Valid ids: ${KNOWN_PERMISSION_IDS.join(', ')}`,
+                    });
+                }
+                if (uniquePermissions.has(permission)) {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains duplicate "${permission}"`,
+                    });
+                }
+                uniquePermissions.add(permission);
+            }
+        }
+        const enablement = module.enablement;
+        if (!enablement || typeof enablement !== 'object') {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].enablement is required`,
+            });
+        }
+        else {
+            if (enablement.default !== 'disabled') {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.default must be "disabled". ` +
+                        'Privileged capabilities are always opt-in.',
+                });
+            }
+            if (enablement.promptOn !== 'firstUse') {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.promptOn must be "firstUse"`,
+                });
+            }
+            if (typeof enablement.purpose !== 'string' || enablement.purpose.trim().length === 0) {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.purpose must be a non-empty string. ` +
+                        'This is shown verbatim in the consent prompt - write it from the user\'s perspective.',
+                });
+            }
+            else if (enablement.purpose.length > 280) {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.purpose is too long (${enablement.purpose.length} chars). ` +
+                        'Keep it under 280 characters; long copy doesn\'t fit the consent prompt.',
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Convenience wrapper that throws if any fatal issues are found. Warnings
+ * (currently: deprecated permission ids) are surfaced via the issues array
+ * but never throw, so an extension that still references `spawn-process`
+ * keeps loading -- the host just drops the id when computing effective
+ * permissions.
+ *
+ * Use this in main-process load paths where invalid manifests should refuse
+ * the extension outright.
+ */
+export function assertBackendModulesValid(extensionId, backendModules) {
+    const issues = validateBackendModules(backendModules);
+    const fatal = issues.filter((i) => i.severity !== 'warning');
+    if (fatal.length === 0) {
+        return;
+    }
+    const lines = fatal.map((i) => i.moduleId ? `  - [${i.moduleId}] ${i.message}` : `  - ${i.message}`);
+    throw new Error(`Extension ${extensionId} has invalid backendModules declarations:\n${lines.join('\n')}`);
+}
+/**
+ * Filter a raw `permissions` array on a backend-module contribution down to
+ * the ids the host actually understands. Deprecated catalog ids
+ * (`spawn-process`, `network-loopback`, `network-internet`, `filesystem`)
+ * are dropped silently -- they never gated anything inside the backend
+ * runtime, so the host treats them as no-ops. Unknown ids are also dropped;
+ * `validateBackendModules` raises a separate error for those, so the loader
+ * will refuse the module before this is consulted in earnest.
+ */
+export function effectiveModulePermissions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (typeof entry !== 'string')
+            continue;
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        if (KNOWN_PERMISSION_IDS.includes(entry)) {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Extract the set of declared backend-module ids from a manifest's
+ * `contributions.backendModules` array. Used by
+ * {@link validateAgentProviders} so the `backendModuleId` cross-check does
+ * not need the caller to pre-compute the set.
+ *
+ * Returns an empty set if `backendModules` is missing or malformed. Exported
+ * so build tooling can reuse the same extraction logic when checking entry
+ * files against the declared modules.
+ */
+export function extractBackendModuleIds(backendModules) {
+    const ids = new Set();
+    if (!Array.isArray(backendModules))
+        return ids;
+    for (const raw of backendModules) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const id = raw.id;
+        if (typeof id === 'string' && id.length > 0) {
+            ids.add(id);
+        }
+    }
+    return ids;
+}
+/**
+ * Validate the `contributions.aiAgentProviders` array on a manifest.
+ *
+ * AI agent providers are surfaced in Nimbalyst's chat / agent UI as selectable
+ * providers (alongside built-in Claude Code, Claude, OpenAI, etc.). Each
+ * provider is implemented by a backend module that runs outside the renderer
+ * (so it can drive a CLI, hold long-lived processes, or speak a custom
+ * protocol). The contribution shape, in practice:
+ *
+ *   {
+ *     id: string,                       // unique within the extension
+ *     displayName: string,              // shown in the provider dropdown
+ *     backendModuleId: string,          // must match a declared backendModule
+ *     models?: Array<{ id, name, ... }> // models the provider advertises
+ *     toolFileLinks?: { [toolName]: ... } // optional UI hint table
+ *   }
+ *
+ * This validator checks the manifest-side wiring; it does not introspect the
+ * bundle. See {@link validateExtensionBundle} (Node-only) for the bundle-side
+ * check that the referenced backend module actually exports an
+ * `activate`/`createAgentProvider` function.
+ *
+ * Returns the list of problems found - empty means valid.
+ */
+export function validateAgentProviders(aiAgentProviders, backendModules) {
+    if (aiAgentProviders === undefined) {
+        return [];
+    }
+    if (!Array.isArray(aiAgentProviders)) {
+        return [
+            { message: 'contributions.aiAgentProviders must be an array' },
+        ];
+    }
+    const issues = [];
+    if (aiAgentProviders.length > MAX_AGENT_PROVIDERS_PER_EXTENSION) {
+        issues.push({
+            message: `contributions.aiAgentProviders declares ${aiAgentProviders.length} providers; ` +
+                `the maximum is ${MAX_AGENT_PROVIDERS_PER_EXTENSION}. ` +
+                'Split into multiple extensions, or surface variants as models on a single provider.',
+        });
+    }
+    const knownBackendModuleIds = extractBackendModuleIds(backendModules);
+    const seenProviderIds = new Set();
+    for (let i = 0; i < aiAgentProviders.length; i += 1) {
+        const raw = aiAgentProviders[i];
+        if (!raw || typeof raw !== 'object') {
+            issues.push({
+                message: `aiAgentProviders[${i}] must be an object`,
+            });
+            continue;
+        }
+        const provider = raw;
+        const providerLabel = typeof provider.id === 'string' && provider.id.length > 0
+            ? provider.id
+            : `index ${i}`;
+        // (b) id presence + shape + uniqueness within the extension.
+        if (typeof provider.id !== 'string' ||
+            !AGENT_PROVIDER_ID_PATTERN.test(provider.id)) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].id must be a lowercase string matching ` +
+                    `${AGENT_PROVIDER_ID_PATTERN.source} (got ${JSON.stringify(provider.id)})`,
+            });
+        }
+        else if (seenProviderIds.has(provider.id)) {
+            issues.push({
+                providerId: provider.id,
+                message: `aiAgentProviders contains duplicate id "${provider.id}"`,
+            });
+        }
+        else {
+            seenProviderIds.add(provider.id);
+        }
+        // displayName: non-empty string. Surfaced verbatim in the provider
+        // dropdown, so it has to be readable; not currently length-capped because
+        // we have no signal yet on what the UI tolerates. Matches the
+        // AiAgentProviderContribution type, which names this field `displayName`.
+        if (typeof provider.displayName !== 'string' || provider.displayName.trim().length === 0) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].displayName must be a non-empty string ` +
+                    '(shown verbatim in the provider dropdown).',
+            });
+        }
+        // (a) backendModuleId must reference a real backendModules[*].id.
+        if (typeof provider.backendModuleId !== 'string' ||
+            provider.backendModuleId.length === 0) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].backendModuleId must be a non-empty string ` +
+                    'referencing a backendModules[*].id declared on the same manifest.',
+            });
+        }
+        else if (!knownBackendModuleIds.has(provider.backendModuleId)) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].backendModuleId "${provider.backendModuleId}" ` +
+                    'does not match any contributions.backendModules[*].id. ' +
+                    'Agent providers must be implemented by a declared backend module on the same extension.',
+            });
+        }
+        // (c) models, if present, must be an array of { id, name }. These are
+        // the only required fields on the AiAgentProviderModel type; the host
+        // derives the provider from the contribution id, so models carry no
+        // per-entry provider field.
+        if (provider.models !== undefined) {
+            if (!Array.isArray(provider.models)) {
+                issues.push({
+                    providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                    message: `aiAgentProviders[${providerLabel}].models must be an array (or omitted).`,
+                });
+            }
+            else {
+                const seenModelIds = new Set();
+                for (let m = 0; m < provider.models.length; m += 1) {
+                    const rawModel = provider.models[m];
+                    const modelLabel = `models[${m}]`;
+                    if (!rawModel || typeof rawModel !== 'object') {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel} must be an object`,
+                        });
+                        continue;
+                    }
+                    const model = rawModel;
+                    if (typeof model.id !== 'string' ||
+                        model.id.trim().length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel}.id must be a non-empty string`,
+                        });
+                    }
+                    else if (seenModelIds.has(model.id)) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].models contains duplicate id "${model.id}"`,
+                        });
+                    }
+                    else {
+                        seenModelIds.add(model.id);
+                    }
+                    if (typeof model.name !== 'string' ||
+                        model.name.trim().length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel}.name must be a non-empty string`,
+                        });
+                    }
+                }
+            }
+        }
+        // (d) toolFileLinks, if present, must be a plain object whose keys are
+        // non-empty strings (tool names). We deliberately do NOT validate the
+        // values: the host-side schema for the link payload is still in flux,
+        // and rejecting unknown value shapes here would force every shape change
+        // through this SDK file. Keys are the only contract this validator
+        // pins.
+        if (provider.toolFileLinks !== undefined) {
+            if (typeof provider.toolFileLinks !== 'object' ||
+                provider.toolFileLinks === null ||
+                Array.isArray(provider.toolFileLinks)) {
+                issues.push({
+                    providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                    message: `aiAgentProviders[${providerLabel}].toolFileLinks must be a plain object ` +
+                        'mapping tool names to link descriptors (or omitted).',
+                });
+            }
+            else {
+                for (const key of Object.keys(provider.toolFileLinks)) {
+                    if (typeof key !== 'string' || key.length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].toolFileLinks contains an empty/invalid tool name key`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Convenience wrapper that throws if any fatal aiAgentProviders issues are
+ * found. Mirrors {@link assertBackendModulesValid}. Use this in main-process
+ * load paths where invalid manifests should refuse the extension outright.
+ */
+export function assertAgentProvidersValid(extensionId, aiAgentProviders, backendModules) {
+    const issues = validateAgentProviders(aiAgentProviders, backendModules);
+    const fatal = issues.filter((i) => i.severity !== 'warning');
+    if (fatal.length === 0) {
+        return;
+    }
+    const lines = fatal.map((i) => i.providerId ? `  - [${i.providerId}] ${i.message}` : `  - ${i.message}`);
+    throw new Error(`Extension ${extensionId} has invalid aiAgentProviders declarations:\n${lines.join('\n')}`);
+}

package/dist/types/collab.d.ts

@@ -0,0 +1,138 @@
+/**
+ * CollabCodec
+ *
+ * Per-extension Y.Doc content contract: the single, PURE thing an editor
+ * defines for collaboration. Pure functions `file bytes <-> Y.Doc shape` (no
+ * React, no host imports) so the same code seeds a live editor AND runs
+ * headlessly (Share-to-Team without the editor open, re-upload from local
+ * origin, plain-text projection for search/AI). It lets host features
+ * (re-upload, history, export, AI editing, search indexing, comments, backup,
+ * restore) operate on any extension's collaborative document without knowing
+ * its internal layout.
+ *
+ * Extensions register a codec via
+ * `context.services.collab.registerContentAdapter(...)` from their
+ * `activate()` function, and pass the SAME codec to
+ * `useCollaborativeEditor(host, { codec, bind })`. `isEmpty` / `seedFromFile`
+ * / `exportToFile` are therefore defined exactly ONCE, on the codec -- the
+ * live seed and the headless seed are provably the same code.
+ *
+ * Codecs run only client-side (main process, renderer, extensions). The collab
+ * Worker stays codec-agnostic and treats Y.Doc state as opaque ciphertext. The
+ * renderer registry is authoritative; the main-process registry is an optional
+ * cache (in-repo statics + text descriptors) and its absence degrades to
+ * client seeding, never a hard error.
+ *
+ * NOTE: This is the canonical definition. The host-internal
+ * `@nimbalyst/collab-adapters` registry re-imports this type --
+ * do not fork the interface there.
+ *
+ * @see CollabContentAdapter -- the former name, kept as a deprecated alias.
+ */
+import type { Doc } from 'yjs';
+export type CollabContentFileSource = string | Uint8Array;
+/**
+ * Serializable description of a CollabContentAdapter that lets the HOST
+ * replicate the adapter in another process (e.g. the Electron main process)
+ * WITHOUT loading the extension's code or doing a dynamic import. Only adapters
+ * built from a known host factory carry one. Today the single kind is `text`
+ * (a one-`Y.Text` document, produced by `createTextCollabContentAdapter`).
+ */
+export interface TextCollabAdapterDescriptor {
+    kind: 'text';
+    documentType: string;
+    fileExtensions: string[];
+    mimeType?: string;
+    textField: string;
+    layoutVersion: number;
+}
+export type CollabAdapterDescriptor = TextCollabAdapterDescriptor;
+export interface CollabCodecMigration {
+    from: number;
+    to: number;
+    run(yDoc: Doc): void;
+}
+/** @deprecated Renamed to {@link CollabCodecMigration}. */
+export type CollabContentAdapterMigration = CollabCodecMigration;
+export interface CollabCodec<TStructured = unknown> {
+    /** Identifies this codec; matches the shared doc's documentType. */
+    documentType: string;
+    /** File extensions this adapter is the on-disk codec for. Include
+     *  the leading dot (e.g. '.md', '.mockup.html'). The first entry is
+     *  used as the default by save-a-copy / export-to-file flows. */
+    fileExtensions: string[];
+    /** Optional MIME type used by save dialogs and asset uploads. */
+    mimeType?: string;
+    /** Layout schema version. Bump when the Y.Doc shape changes; pair
+     *  with `migrations` to migrate older docs forward before any
+     *  write op. */
+    layoutVersion: number;
+    /** Optional migrations from older layout versions. Run by the
+     *  registry before `applyFromFile` / `applyStructuredPatch` when
+     *  the Y.Doc's recorded layoutVersion is older than this adapter's
+     *  layoutVersion. */
+    migrations?: CollabCodecMigration[];
+    /** True iff the Y.Doc has no extension content yet. Used to gate
+     *  the initial-share seed flow. Shared by the live seed (the hook)
+     *  and every headless seed path, so they can never disagree. */
+    isEmpty(yDoc: Doc): boolean;
+    /** Seed an empty Y.Doc from on-disk file bytes/text. Initial share
+     *  only -- adapters can assume `isEmpty(yDoc) === true`. */
+    seedFromFile(yDoc: Doc, source: CollabContentFileSource): void;
+    /** Replace Y.Doc content with the supplied on-disk file content.
+     *  Must be safe to call on a populated Y.Doc. Default behaviour is
+     *  wipe-and-reseed inside a single Y.Doc transaction. Adapters
+     *  that want finer-grained history can override with a
+     *  diff-and-patch implementation. */
+    applyFromFile(yDoc: Doc, source: CollabContentFileSource): void;
+    /** Serialize the live Y.Doc back to the on-disk file format. */
+    exportToFile(yDoc: Doc): string | Uint8Array;
+    /** Plain-text projection for search, AI prompts, diffs, history
+     *  previews. Lossy is fine; this is not a round-trip channel. */
+    toPlainText(yDoc: Doc): string;
+    /** Optional: structured projection for AI tool-call edits and
+     *  comment anchoring. Shape is extension-defined. Paired with
+     *  `applyStructuredPatch`. */
+    toStructured?(yDoc: Doc): TStructured;
+    /** Optional: write structured edits back. Paired with
+     *  `toStructured`. AI-write surface is gated on the presence of
+     *  both this and `toStructured`. */
+    applyStructuredPatch?(yDoc: Doc, patch: unknown): void;
+    /** Optional: produce a snapshot for revision history. Defaults to
+     *  `Y.encodeStateAsUpdateV2(yDoc)`. Override if you need a denser
+     *  snapshot format. */
+    exportRevisionSnapshot?(yDoc: Doc): Uint8Array;
+    /** Optional: restore a revision snapshot. Defaults to
+     *  `Y.applyUpdateV2(yDoc, bytes)`. */
+    restoreRevisionSnapshot?(yDoc: Doc, bytes: Uint8Array): void;
+    /** Optional: a serializable descriptor the host can ship to another process
+     *  to rebuild this adapter without the extension's code. Set automatically by
+     *  host factories like `createTextCollabContentAdapter`; hand-written
+     *  adapters may leave it undefined (they stay process-local). */
+    serializableDescriptor?: CollabAdapterDescriptor;
+}
+/**
+ * @deprecated Renamed to {@link CollabCodec}. Same shape -- a codec is a pure
+ * `file bytes <-> Y.Doc shape` contract. Kept so existing extensions and the
+ * host-internal `@nimbalyst/collab-adapters` registry keep compiling.
+ */
+export type CollabContentAdapter<TStructured = unknown> = CollabCodec<TStructured>;
+/**
+ * The collab surface on the extension context. Extensions call into
+ * this from their `activate()` to register a collab codec for any
+ * document type they ship.
+ */
+export interface ExtensionCollabService {
+    /**
+     * Register a CollabCodec for one of the extension's document types.
+     * Returns a Disposable that unregisters on deactivation; the host also
+     * tracks the registration in `context.subscriptions` automatically.
+     *
+     * (Named `registerContentAdapter` for backwards compatibility; it accepts a
+     * {@link CollabCodec}.)
+     */
+    registerContentAdapter(codec: CollabCodec): {
+        dispose(): void;
+    };
+}
+//# sourceMappingURL=collab.d.ts.map

package/dist/types/collab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collab.d.ts","sourceRoot":"","sources":["../../src/types/collab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CACtB;AAED,2DAA2D;AAC3D,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAEjE,MAAM,WAAW,WAAW,CAAC,WAAW,GAAG,OAAO;IAChD,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IAErB;;qEAEiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;oBAEgB;IAChB,aAAa,EAAE,MAAM,CAAC;IAEtB;;;yBAGqB;IACrB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAEpC;;oEAEgE;IAChE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;IAE5B;gEAC4D;IAC5D,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAE/D;;;;yCAIqC;IACrC,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAEhE,gEAAgE;IAChE,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,UAAU,CAAC;IAE7C;qEACiE;IACjE,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC;IAE/B;;kCAE8B;IAC9B,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,WAAW,CAAC;IAEtC;;wCAEoC;IACpC,oBAAoB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD;;2BAEuB;IACvB,sBAAsB,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,CAAC;IAE/C;0CACsC;IACtC,uBAAuB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D;;;qEAGiE;IACjE,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,WAAW,GAAG,OAAO,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;CACjE"}

package/dist/types/collab.js

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