@xpert-ai/plugin-spaces 0.0.0-stage → 0.3.0

package/dist/imports.d.ts

@@ -0,0 +1,83 @@
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { z } from 'zod/v3';
+import { SpaceAccess } from './access.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { type SpaceActor } from './domain.js';
+export declare const sourceSelection: z.ZodObject<{
+    bindingId: z.ZodString;
+    locator: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    bindingId: string;
+    locator: string;
+}, {
+    bindingId: string;
+    locator: string;
+}>;
+export declare const importSelection: z.ZodObject<{
+    bindingId: z.ZodString;
+    locator: z.ZodString;
+} & {
+    spaceId: z.ZodString;
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    requestId: z.ZodString;
+    expectedRevision: z.ZodString;
+    expectedHash: z.ZodString;
+    confirmed: z.ZodLiteral<true>;
+}, "strict", z.ZodTypeAny, {
+    spaceId: string;
+    parentId: string | null;
+    expectedHash: string;
+    expectedRevision: string;
+    requestId: string;
+    bindingId: string;
+    locator: string;
+    confirmed: true;
+}, {
+    spaceId: string;
+    expectedHash: string;
+    expectedRevision: string;
+    requestId: string;
+    bindingId: string;
+    locator: string;
+    confirmed: true;
+    parentId?: string | null | undefined;
+}>;
+/** Encode remote plain text as literal Markdown paragraphs, never executable HTML. Encode colons to prevent autolinks from consuming Markdown escapes. */
+export declare const literalMarkdown: (text: string) => string;
+export declare class SpaceImports {
+    private readonly access;
+    private readonly documents;
+    private readonly artifacts;
+    private readonly runtime;
+    constructor(access: SpaceAccess, documents: SpaceDocuments, artifacts: SpaceArtifacts, runtime: RuntimeCapabilityRegistry);
+    private context;
+    private api;
+    sources(actor: SpaceActor): Promise<{
+        items: import("@xpert-ai/plugin-sdk").ConnectorDocumentConnection[];
+    }>;
+    search(actor: SpaceActor, input: {
+        bindingId: string;
+        query: string;
+        cursor?: string;
+        pageSize: number;
+    }): Promise<{
+        items: import("@xpert-ai/plugin-sdk").ConnectorDocumentEntry[];
+        nextCursor: string | null;
+    }>;
+    preview(actor: SpaceActor, input: z.infer<typeof sourceSelection>): Promise<{
+        provider: string;
+        revision: string;
+        contentHash: string;
+        format: "text/plain";
+        content: string;
+        warnings: string[];
+        id: string;
+        title: string;
+        url: string | null;
+        type: "document";
+    }>;
+    apply(actor: SpaceActor, input: z.infer<typeof importSelection>): Promise<{
+        resourceId: string;
+    }>;
+}

package/dist/imports.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { BadRequestException, ConflictException, Inject, Injectable } from '@nestjs/common';
+import { ConnectorDocumentsRuntimeCapability, XPERT_RUNTIME_CAPABILITIES_TOKEN } from '@xpert-ai/plugin-sdk';
+import { z } from 'zod/v3';
+import { SpaceAccess } from './access.js';
+import { SpaceDocuments, contentHash, safeName } from './documents.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { Space } from './entities.js';
+import { denied, id, scoped } from './domain.js';
+export const sourceSelection = z.object({ bindingId: id, locator: z.string().trim().min(1).max(2000) }).strict();
+export const importSelection = sourceSelection.extend({ spaceId: id, parentId: id.nullable().default(null), requestId: id,
+    expectedRevision: z.string().min(1).max(200), expectedHash: z.string().regex(/^[a-f0-9]{64}$/u), confirmed: z.literal(true) }).strict();
+const missing = (error) => error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+/** Encode remote plain text as literal Markdown paragraphs, never executable HTML. Encode colons to prevent autolinks from consuming Markdown escapes. */
+export const literalMarkdown = (text) => text.replace(/\r\n?/gu, '\n').replace(/\u0000/gu, '')
+    .replace(/[&:\\`*_{}\[\]()#+.!<>|$~-]/gu, (char) => char === '&' || char === ':' ? `&#${char.codePointAt(0)};` : `\\${char}`).split('\n').join('\n\n');
+let SpaceImports = class SpaceImports {
+    access;
+    documents;
+    artifacts;
+    runtime;
+    constructor(access, documents, artifacts, runtime) {
+        this.access = access;
+        this.documents = documents;
+        this.artifacts = artifacts;
+        this.runtime = runtime;
+    }
+    context(actor) {
+        if (!actor.assistantId || !actor.projectId)
+            throw denied();
+        return { actor, assistantId: actor.assistantId, projectId: actor.projectId };
+    }
+    api() { return this.runtime.require(ConnectorDocumentsRuntimeCapability); }
+    async sources(actor) {
+        await this.access.project(actor, actor.projectId, 'write');
+        return this.api().sources(this.context(actor));
+    }
+    async search(actor, input) {
+        await this.access.project(actor, actor.projectId, 'write');
+        return this.api().search({ ...this.context(actor), ...input });
+    }
+    async preview(actor, input) {
+        const sources = await this.sources(actor), source = sources.items.find((entry) => entry.bindingId === input.bindingId && entry.available);
+        if (!source)
+            throw denied();
+        const snapshot = await this.api().read({ ...this.context(actor), ...input });
+        if (snapshot.format !== 'text/plain')
+            throw new BadRequestException('spaces.import_format_unsupported');
+        return { ...snapshot, provider: source.provider };
+    }
+    async apply(actor, input) {
+        if (!input.confirmed)
+            throw new BadRequestException('spaces.import_confirmation_required');
+        const context = this.context(actor);
+        const target = async () => {
+            const result = await this.access.resource(actor, input.parentId ?? input.spaceId, 'write');
+            if (result.space.id !== input.spaceId || result.space.projectId !== context.projectId || (result.item && result.item.kind !== 'folder'))
+                throw denied();
+            return result;
+        };
+        const { space } = await target();
+        // A stable request binds all preview/target fields, but stores no credentials or raw pasted URL.
+        const requestHash = contentHash(Buffer.from(JSON.stringify({ ...input, confirmed: undefined, requestId: undefined })));
+        const existing = await this.access.items.findOneBy({ id: input.requestId });
+        const check = (item) => {
+            if (item.tenantId !== actor.tenantId || item.organizationId !== actor.organizationId || item.spaceId !== input.spaceId ||
+                item.createdById !== actor.userId || item.deleted || item.importOrigin?.requestHash !== requestHash)
+                throw new ConflictException('spaces.import_request_conflict');
+        };
+        if (existing) {
+            check(existing);
+            // A completed copy is a project resource: remote revocation never deletes it or prevents retry receipts.
+            await this.access.resource(actor, existing.id, 'write');
+            if (existing.editorKey === 'markdown.tiptap')
+                return { resourceId: existing.id };
+        }
+        const snapshot = await this.preview(actor, input);
+        if (snapshot.revision !== input.expectedRevision || snapshot.contentHash !== input.expectedHash)
+            throw new ConflictException('spaces.import_source_changed');
+        const text = `# ${literalMarkdown(snapshot.title)}\n\n${literalMarkdown(snapshot.content)}\n`;
+        await this.documents.content().validateImport({ ...context, modelKey: 'markdown.tiptap', markdown: text });
+        const buffer = Buffer.from(text), hash = contentHash(buffer);
+        // Serialize with discovery/moves. Persist the intent outside the lock transaction so an interrupted
+        // file/register step resumes the same ID and CAS-protected file rather than creating another copy.
+        return this.access.items.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: space.id }, lock: { mode: 'pessimistic_write' } });
+            const destination = await target();
+            let item = await this.access.items.findOneBy({ id: input.requestId });
+            if (item) {
+                check(item);
+                if (item.editorKey === 'markdown.tiptap')
+                    return { resourceId: item.id };
+            }
+            else {
+                const prefix = destination.item?.filePath ? `${destination.item.filePath}/` : '';
+                item = await this.access.items.save(this.access.items.create({ ...scoped(actor), id: input.requestId, spaceId: space.id,
+                    parentId: input.parentId, createdById: actor.userId, kind: 'page', title: snapshot.title,
+                    filePath: `${prefix}${safeName(snapshot.title).slice(0, 100)}--${input.requestId}.md`, syncStatus: 'pending',
+                    importOrigin: { provider: snapshot.provider, documentId: snapshot.id, url: snapshot.url, revision: snapshot.revision,
+                        contentHash: snapshot.contentHash, format: snapshot.format, importedAt: new Date().toISOString(),
+                        warnings: snapshot.warnings, bindingId: input.bindingId, requestHash } }));
+            }
+            const fileScope = { actor, projectId: context.projectId, path: item.filePath };
+            const disk = await this.documents.api().read(fileScope).catch((error) => { if (missing(error))
+                return null; throw error; });
+            if (disk && disk.sha256 !== (item.fileHash ?? hash))
+                throw new ConflictException('spaces.file_conflict');
+            if (!disk) {
+                if (item.fileHash)
+                    throw new ConflictException('spaces.file_conflict');
+                await this.documents.api().write({ ...fileScope, buffer, expectedHash: null });
+            }
+            await this.access.items.update(item.id, { fileHash: disk?.sha256 ?? hash, syncStatus: 'ready' });
+            await this.documents.content().register({ ...context, resourceId: item.id, path: item.filePath, title: item.title,
+                modelKey: 'markdown.tiptap', source: { providerKey: 'spaces', resourceId: item.id } });
+            if (!item.artifactId)
+                await this.artifacts.initializePage(actor, item.id, item.title);
+            await this.access.items.update(item.id, { editorKey: 'markdown.tiptap' });
+            return { resourceId: item.id };
+        });
+    }
+};
+SpaceImports = __decorate([
+    Injectable(),
+    __param(3, Inject(XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceDocuments, SpaceArtifacts, Object])
+], SpaceImports);
+export { SpaceImports };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+import { type XpertPlugin } from '@xpert-ai/plugin-sdk';
+export declare class SpacesPlugin {
+}
+declare const plugin: XpertPlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,51 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { SpaceItemCatalog } from './item-catalog.js';
+import { SpaceCatalog } from './catalog.js';
+import { SpaceContentKnowledge } from './content-knowledge.js';
+import { SpaceImports } from './imports.js';
+import 'reflect-metadata';
+import { readFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { XpertServerPlugin } from '@xpert-ai/plugin-sdk';
+import { entities } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { SpacesResourceProvider } from './resource-provider.js';
+import { SpacesService } from './spaces.js';
+import { SpacePages } from './pages.js';
+import { SpaceAi } from './ai.js';
+import { SpacesView } from './view.js';
+import { SpaceEditors } from './editors.js';
+import { SpacesMiddleware } from './middleware.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { SpaceFiles } from './files.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpaceContent } from './content.js';
+import { SpaceReferences } from './references.js';
+import { SpaceSubpages } from './subpages.js';
+import { SpacesCapabilityProvider } from './capability.js';
+let SpacesPlugin = class SpacesPlugin {
+};
+SpacesPlugin = __decorate([
+    XpertServerPlugin({
+        imports: [TypeOrmModule.forFeature(entities)], entities,
+        providers: [SpaceItemCatalog, SpaceContentKnowledge, SpaceCatalog, SpacesCapabilityProvider, SpaceImports, SpaceReferences, SpaceSubpages, SpaceContent, SpaceAccess, SpaceKnowledge, SpaceDocuments, SpacesResourceProvider, SpacesService, SpacePages, SpaceAi, SpaceFiles, SpaceEditors, SpaceArtifacts, SpacesMiddleware, SpacesView]
+    })
+], SpacesPlugin);
+export { SpacesPlugin };
+const plugin = {
+    meta: {
+        name: manifest.name, version: manifest.version, author: 'XpertAI', level: manifest.xpert.plugin.level, artifactNamespace: manifest.xpert.plugin.artifactNamespace,
+        displayName: 'Spaces', description: 'Assistant collaboration capability for shared AI-maintained documents and artifacts',
+        category: 'middleware', targetApps: ['xpert'],
+        targetAppMeta: { xpert: { types: ['business-app', 'workbench-view', 'assistant-tool'], capabilities: ['spaces'], runtime: { middlewareProviders: ['spaces'], viewProviders: ['spaces.views'] } } }
+    },
+    register() { return { module: SpacesPlugin, global: true }; }
+};
+export default plugin;

package/dist/item-catalog.d.ts

@@ -0,0 +1,13 @@
+import type { ContentCatalogProvider } from '@xpert-ai/plugin-sdk';
+import { SpaceAccess } from './access.js';
+import { SpaceContentKnowledge } from './content-knowledge.js';
+/** Exposes native SpaceItems to the platform content catalog without copying content.
+ * Pages/files retain their identities, file paths and editing protocols. Creation
+ * uses the page/upload workflows; discovery rebuilds only derived catalog entries. */
+export declare class SpaceItemCatalog {
+    private readonly access;
+    private readonly knowledge;
+    constructor(access: SpaceAccess, knowledge: SpaceContentKnowledge);
+    readonly catalog: ContentCatalogProvider;
+    private describe;
+}

package/dist/item-catalog.js

@@ -0,0 +1,71 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable } from '@nestjs/common';
+import { In } from 'typeorm';
+import { SpaceAccess } from './access.js';
+import { scoped, denied } from './domain.js';
+import { SpaceContentKnowledge } from './content-knowledge.js';
+const models = {
+    page: { typeId: 'xpert.markdown', modelId: 'markdown.tiptap', schemaVersion: '1', editProtocol: { id: 'platform.text-document', version: '1' } },
+    file: { typeId: 'xpert.file', modelId: 'platform.file', schemaVersion: '1', editProtocol: { id: 'platform.file.cas', version: '1' } }
+};
+/** Exposes native SpaceItems to the platform content catalog without copying content.
+ * Pages/files retain their identities, file paths and editing protocols. Creation
+ * uses the page/upload workflows; discovery rebuilds only derived catalog entries. */
+let SpaceItemCatalog = class SpaceItemCatalog {
+    access;
+    knowledge;
+    constructor(access, knowledge) {
+        this.access = access;
+        this.knowledge = knowledge;
+    }
+    catalog = {
+        types: [
+            { ...models.page, creatable: false, title: { en_US: 'Pages', zh_Hans: '页面' }, implementationKey: 'spaces.page', implementationTitle: { en_US: 'Markdown', zh_Hans: 'Markdown' }, defaultEditorKey: 'markdown.tiptap' },
+            { ...models.file, creatable: false, title: { en_US: 'Files', zh_Hans: '文件' }, implementationKey: 'spaces.file', implementationTitle: { en_US: 'File', zh_Hans: '文件' }, defaultEditorKey: 'platform.file' }
+        ],
+        discover: async (input) => {
+            const space = await this.access.spaces.findOneBy({ ...scoped(input.actor), projectId: input.projectId, deleted: false });
+            if (!space)
+                return { resourceIds: [] };
+            await this.access.project({ ...input.actor, assistantId: input.assistantId }, input.projectId);
+            const offset = Number(input.cursor ?? 0);
+            if (!Number.isSafeInteger(offset) || offset < 0)
+                throw denied();
+            const items = await this.access.items.find({ where: { ...scoped(input.actor), spaceId: space.id, kind: In(['page', 'file', 'artifact']), deleted: false }, order: { id: 'ASC' }, skip: offset, take: 100 });
+            return { resourceIds: items.filter(item => item.filePath).map(item => item.id), ...(items.length === 100 ? { nextCursor: String(offset + 100) } : {}) };
+        },
+        describe: input => this.describe(input),
+        onResourceReconciled: async (input) => {
+            if (input.item.resourceRef.providerKey === 'spaces')
+                return;
+            const space = await this.access.spaces.findOneBy({ ...scoped(input.actor), projectId: input.projectId, deleted: false });
+            if (!space?.knowledgebaseId)
+                return;
+            const actor = { ...input.actor, projectId: input.projectId, assistantId: input.assistantId };
+            await this.access.project(actor, input.projectId, 'write');
+            await this.knowledge.refreshItem(actor, space, input.item);
+        },
+        create: async () => { throw denied(); }
+    };
+    async describe(input) {
+        const { item, space } = await this.access.resource({ ...input.actor, projectId: input.projectId, assistantId: input.assistantId }, input.sourceResourceId, 'read');
+        if (!item?.filePath || item.kind === 'folder')
+            throw denied();
+        return { ...(item.kind === 'page' ? models.page : models.file), projectId: space.projectId, title: item.title,
+            revision: `${item.version}:${item.projectedSequence}:${item.fileHash ?? ''}`, updatedAt: item.updatedAt.toISOString(),
+            deleted: item.deleted, source: { kind: 'file', path: item.filePath }, defaultEditorKey: item.editorKey ?? 'platform.file', allowedActions: [] };
+    }
+};
+SpaceItemCatalog = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceContentKnowledge])
+], SpaceItemCatalog);
+export { SpaceItemCatalog };

package/dist/knowledge.d.ts

@@ -0,0 +1,57 @@
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { SpaceContentKnowledge } from './content-knowledge.js';
+import { SpaceAccess } from './access.js';
+import { type SpaceActor } from './domain.js';
+import { Space, SpaceItem } from './entities.js';
+export declare class SpaceKnowledge {
+    private readonly access;
+    private readonly runtime;
+    private readonly content;
+    constructor(access: SpaceAccess, runtime: RuntimeCapabilityRegistry, content: SpaceContentKnowledge);
+    enable(actor: SpaceActor, spaceId: string): Promise<{
+        knowledgebaseId: string;
+    }>;
+    sync(actor: SpaceActor, space: Space, item: SpaceItem): Promise<void>;
+    refresh(actor: SpaceActor, spaceId: string): Promise<{
+        knowledgebaseId: string | null;
+        mode: string;
+        items: ({
+            itemId: string;
+            title: string;
+            status: string;
+            error: string | null;
+            document: null;
+        } | {
+            itemId: string;
+            title: string;
+            status: "pending" | "ready" | "failed" | "processing";
+            error: string | null;
+            document: import("@xpert-ai/plugin-sdk").KnowledgebaseDocumentRecord | null;
+        })[];
+    }>;
+    status(actor: SpaceActor, spaceId: string): Promise<{
+        knowledgebaseId: string | null;
+        mode: string;
+        items: ({
+            itemId: string;
+            title: string;
+            status: string;
+            error: string | null;
+            document: null;
+        } | {
+            itemId: string;
+            title: string;
+            status: "pending" | "ready" | "failed" | "processing";
+            error: string | null;
+            document: import("@xpert-ai/plugin-sdk").KnowledgebaseDocumentRecord | null;
+        })[];
+    }>;
+    search(actor: SpaceActor, spaceId: string, query: string): Promise<{
+        itemId: string;
+        title: string;
+        text: string;
+        filePath: string;
+        hash: string;
+    }[]>;
+    verify(actor: SpaceActor, itemId: string, hash: string, contentId?: string): Promise<boolean>;
+}

package/dist/knowledge.js

@@ -0,0 +1,172 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
+import { ProjectKnowledgeRuntimeCapability, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, ProjectFilesRuntimeCapability, XPERT_RUNTIME_CAPABILITIES_TOKEN } from '@xpert-ai/plugin-sdk';
+import { z } from 'zod/v3';
+import { KBDocumentStatusEnum } from '@xpert-ai/contracts';
+import { SpaceContentKnowledge } from './content-knowledge.js';
+import { SpaceAccess } from './access.js';
+import { denied, scoped } from './domain.js';
+const metadata = z.object({ spaceItemId: z.string().uuid(), spaceFileHash: z.string() }).passthrough();
+const documentMetadata = z.object({ documentId: z.string().uuid() }).passthrough();
+let SpaceKnowledge = class SpaceKnowledge {
+    access;
+    runtime;
+    content;
+    constructor(access, runtime, content) {
+        this.access = access;
+        this.runtime = runtime;
+        this.content = content;
+    }
+    async enable(actor, spaceId) {
+        const { space } = await this.access.resource(actor, spaceId, 'manage');
+        if (!space.projectId)
+            throw denied();
+        const result = await this.runtime.require(ProjectKnowledgeRuntimeCapability).ensureBinding({
+            actor, title: space.title, projectId: space.projectId
+        });
+        await this.access.spaces.update(space.id, { knowledgebaseId: result.knowledgebaseId });
+        return result;
+    }
+    async sync(actor, space, item) {
+        if (!space.knowledgebaseId || !space.projectId || item.kind === 'folder' || !item.filePath)
+            return;
+        try {
+            item = await this.access.items.findOneByOrFail({ ...scoped(actor), id: item.id, spaceId: space.id });
+            if (!item.filePath || item.kind === 'folder')
+                return;
+            const documents = this.runtime.require(KnowledgebaseDocumentsRuntimeCapability);
+            await this.access.project(actor, space.projectId, 'write');
+            if (item.deleted) {
+                if (item.knowledgeDocumentId)
+                    await documents.deleteDocuments({ knowledgebaseId: space.knowledgebaseId, documentIds: [item.knowledgeDocumentId] });
+                await this.access.items.update(item.id, { knowledgeDocumentId: null, indexedHash: null, indexStatus: 'pending', indexError: null });
+                return;
+            }
+            const source = await this.runtime.require(ProjectFilesRuntimeCapability).read({ actor, projectId: space.projectId, path: item.filePath });
+            // External changes must be reconciled before indexing a collaborative page.
+            // A superseded sync must never replace the index pointer of a newer edit.
+            if (item.fileHash !== source.sha256)
+                return;
+            if (item.indexedHash === source.sha256 && item.knowledgeDocumentId) {
+                const current = await documents.getDocumentStatus({ knowledgebaseId: space.knowledgebaseId, documentIds: [item.knowledgeDocumentId] });
+                if (current.documents[0]?.status === KBDocumentStatusEnum.ERROR)
+                    await documents.startProcessing({ knowledgebaseId: space.knowledgebaseId, documentIds: [item.knowledgeDocumentId] });
+                return;
+            }
+            const file = await documents.uploadFile({ knowledgebaseId: space.knowledgebaseId,
+                path: `${item.id}/${source.sha256}`, file: { buffer: source.buffer, originalname: item.filePath.split('/').pop() } });
+            const result = await documents.createDocuments({
+                knowledgebaseId: space.knowledgebaseId, idempotencyKey: `space:${item.id}:${source.sha256}`,
+                documents: [{ name: item.title, filePath: file.filePath, fileUrl: file.fileUrl, mimeType: file.mimeType?.split(';')[0], size: file.size,
+                        metadata: { spaceItemId: item.id, spaceFileHash: source.sha256, projectId: space.projectId, projectPath: item.filePath } }],
+                process: true
+            });
+            const created = result.documents[0];
+            if (!created)
+                throw new Error('spaces.index_document_missing');
+            const updated = await this.access.items.update({ id: item.id, deleted: false, fileHash: source.sha256 }, { knowledgeDocumentId: created.id, indexedHash: source.sha256, indexStatus: 'processing', indexError: null });
+            if (!updated.affected)
+                return;
+            if (item.knowledgeDocumentId && item.knowledgeDocumentId !== created.id)
+                await documents.deleteDocuments({ knowledgebaseId: space.knowledgebaseId, documentIds: [item.knowledgeDocumentId] });
+        }
+        catch (error) {
+            if (item.fileHash)
+                await this.access.items.update({ id: item.id, fileHash: item.fileHash, deleted: item.deleted }, { indexStatus: 'failed', indexError: error instanceof Error ? error.message.slice(0, 1000) : 'spaces.index_failed' });
+        }
+    }
+    async refresh(actor, spaceId) {
+        const { space } = await this.access.resource(actor, spaceId, 'write');
+        const items = await this.access.items.findBy({ ...scoped(actor), spaceId });
+        for (const item of items)
+            await this.sync(actor, space, item);
+        await this.content.refresh(actor, space);
+        return this.status(actor, spaceId);
+    }
+    async status(actor, spaceId) {
+        const { space } = await this.access.resource(actor, spaceId, 'read');
+        const items = await this.access.items.findBy({ ...scoped(actor), spaceId });
+        const documents = space.knowledgebaseId && items.some((item) => item.knowledgeDocumentId)
+            ? await this.runtime.require(KnowledgebaseDocumentsRuntimeCapability).getDocumentStatus({
+                knowledgebaseId: space.knowledgebaseId, documentIds: items.flatMap((item) => item.knowledgeDocumentId ? [item.knowledgeDocumentId] : [])
+            }) : { documents: [] };
+        for (const item of items) {
+            const document = documents.documents.find((doc) => doc.id === item.knowledgeDocumentId);
+            if (!document)
+                continue;
+            const status = document.status === KBDocumentStatusEnum.FINISH ? 'ready' : document.status === KBDocumentStatusEnum.ERROR ? 'failed' : 'processing';
+            const error = status === 'failed' ? document.processMsg ?? 'spaces.index_failed' : null;
+            if (item.indexStatus !== status || item.indexError !== error)
+                await this.access.items.update(item.id, { indexStatus: status, indexError: error });
+            item.indexStatus = status;
+            item.indexError = error;
+        }
+        return { knowledgebaseId: space.knowledgebaseId, mode: 'keyword', items: [...await this.content.status(actor, space), ...items.filter((item) => item.kind !== 'folder' && !item.deleted).map((item) => ({
+                    itemId: item.id, title: item.title, status: item.indexStatus, error: item.indexError,
+                    document: documents.documents.find((doc) => doc.id === item.knowledgeDocumentId) ?? null
+                }))] };
+    }
+    async search(actor, spaceId, query) {
+        const { space } = await this.access.resource(actor, spaceId, 'read');
+        if (!space.knowledgebaseId)
+            return [];
+        const result = await this.runtime.require(KnowledgebaseRuntimeCapability).search({
+            knowledgebaseIds: [space.knowledgebaseId], query, k: 20, source: 'spaces', retrieval: { mode: 'keyword' }
+        });
+        const matches = [];
+        for (const document of result.documents) {
+            const data = metadata.safeParse(document.metadata);
+            const source = documentMetadata.safeParse(document.metadata);
+            // Platform parsers retain documentId on chunks; custom import metadata lives on the document.
+            const indexedItem = source.success ? await this.access.items.findOneBy({
+                ...scoped(actor), spaceId, knowledgeDocumentId: source.data.documentId, deleted: false
+            }) : null;
+            const itemId = data.success ? data.data.spaceItemId : indexedItem?.id;
+            const hash = data.success ? data.data.spaceFileHash : indexedItem?.indexedHash;
+            if (!itemId || !hash)
+                continue;
+            let item;
+            try {
+                ({ item } = await this.access.resource(actor, itemId, 'read'));
+            }
+            catch (error) {
+                if (error instanceof ForbiddenException)
+                    continue;
+                throw error;
+            }
+            if (!item?.filePath || item.deleted || item.spaceId !== spaceId || !space.projectId)
+                continue;
+            const file = await this.runtime.require(ProjectFilesRuntimeCapability).read({ actor, projectId: space.projectId, path: item.filePath });
+            if (file.sha256 !== hash)
+                continue;
+            matches.push({ itemId: item.id, title: item.title, text: document.pageContent, filePath: item.filePath, hash });
+        }
+        return [...matches, ...await this.content.matches(actor, space, result.documents)];
+    }
+    async verify(actor, itemId, hash, contentId) {
+        if (contentId)
+            return this.content.verify(actor, contentId, hash);
+        const { item, space } = await this.access.resource(actor, itemId, 'read');
+        if (!item?.filePath || !space.projectId)
+            return false;
+        const file = await this.runtime.require(ProjectFilesRuntimeCapability).read({ actor, projectId: space.projectId, path: item.filePath });
+        return file.sha256 === hash;
+    }
+};
+SpaceKnowledge = __decorate([
+    Injectable(),
+    __param(1, Inject(XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [SpaceAccess, Object, SpaceContentKnowledge])
+], SpaceKnowledge);
+export { SpaceKnowledge };

package/dist/middleware.d.ts

@@ -0,0 +1,17 @@
+import { type IAgentMiddlewareStrategy, type IAgentMiddlewareContext, type AgentMiddleware } from '@xpert-ai/plugin-sdk';
+import type { TAgentMiddlewareMeta } from '@xpert-ai/contracts';
+import { SpaceContent } from './content.js';
+import { SpaceAccess } from './access.js';
+import { SpacePages } from './pages.js';
+import { SpaceAi } from './ai.js';
+import { SpacesService } from './spaces.js';
+export declare class SpacesMiddleware implements IAgentMiddlewareStrategy<Record<string, never>> {
+    private readonly content;
+    private readonly spaces;
+    private readonly pages;
+    private readonly ai;
+    private readonly access;
+    readonly meta: TAgentMiddlewareMeta;
+    constructor(content: SpaceContent, spaces: SpacesService, pages: SpacePages, ai: SpaceAi, access: SpaceAccess);
+    createMiddleware(_options: Record<string, never>, context: IAgentMiddlewareContext): AgentMiddleware;
+}