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

package/dist/files.d.ts

@@ -0,0 +1,79 @@
+import type { SpaceActor } from './domain.js';
+import { type AgentMiddlewareRuntimeServiceApi } from '@xpert-ai/plugin-sdk';
+import { Repository } from 'typeorm';
+import { SpaceAccess } from './access.js';
+import { SpaceItem, SpaceFileVersion } from './entities.js';
+import { SpacePages } from './pages.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpacesService } from './spaces.js';
+export declare class SpaceFiles {
+    private readonly access;
+    private readonly pages;
+    private readonly spaces;
+    private readonly documents;
+    private readonly knowledge;
+    private readonly versions;
+    private readonly runtime;
+    constructor(access: SpaceAccess, pages: SpacePages, spaces: SpacesService, documents: SpaceDocuments, knowledge: SpaceKnowledge, versions: Repository<SpaceFileVersion>, runtime: AgentMiddlewareRuntimeServiceApi);
+    put(actor: SpaceActor, itemId: string, buffer: Buffer, fileName: string, mimeType: string, revisionId?: string | null, updateCurrent?: boolean): Promise<SpaceFileVersion>;
+    /** Opaque file protocol. Editor plugins own parsing; this resource owns snapshots and CAS. */
+    editorRead(actor: SpaceActor, itemId: string): Promise<{
+        buffer: Buffer<ArrayBufferLike>;
+        revision: string;
+    }>;
+    private editorRevision;
+    editorWrite(actor: SpaceActor, itemId: string, expectedRevision: string, buffer: Buffer): Promise<{
+        revision: string;
+    }>;
+    readBytes(actor: SpaceActor, versionId: string): Promise<Buffer<ArrayBufferLike>>;
+    upload(actor: SpaceActor, spaceId: string, parentId: string | null, fileName: string, mimeType: string, buffer: Buffer): Promise<{
+        item: SpaceItem;
+        version: SpaceFileVersion;
+    }>;
+    get(actor: SpaceActor, versionId: string): Promise<SpaceFileVersion>;
+    list(actor: SpaceActor, itemId: string): Promise<SpaceFileVersion[]>;
+    exportPage(actor: SpaceActor, itemId: string): Promise<{
+        fileVersionId: string;
+        revisionId: string;
+        sequence: number;
+        artifactId: string;
+        versionId: string;
+        url: string;
+    }>;
+    collect(actor: SpaceActor, spaceId: string, parentId: string | null, artifactId: string, versionId: string): Promise<SpaceItem>;
+    artifactBytes(actor: SpaceActor, artifactId: string, versionId: string): Promise<{
+        artifact: import("@xpert-ai/plugin-sdk").ArtifactRecord;
+        version: import("@xpert-ai/plugin-sdk").ArtifactVersionRecord;
+        buffer: Buffer<ArrayBufferLike>;
+    }>;
+    available(actor: SpaceActor, page: number): Promise<{
+        items: {
+            id: string;
+            title: string | null | undefined;
+            versions: import("@xpert-ai/plugin-sdk").ArtifactVersionRecord[];
+        }[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    current(actor: SpaceActor, itemId: string): Promise<{
+        reference: {
+            userId: string;
+            projectId: string;
+            catalog: "projects";
+            source: "platform.workspace.files";
+            filePath: string;
+            scopeId: string;
+            workspacePath: string;
+            tenantId: string;
+            organizationId: string;
+        };
+        fileName: string;
+        mimeType: string;
+    }>;
+    openArtifact(actor: SpaceActor, itemId: string): Promise<{
+        artifact: import("@xpert-ai/plugin-sdk").ArtifactRecord;
+        version: import("@xpert-ai/plugin-sdk").ArtifactVersionRecord;
+    }>;
+}

package/dist/files.js

@@ -0,0 +1,228 @@
+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 { InjectRepository } from '@nestjs/typeorm';
+import { ArtifactsRuntimeCapability, WorkspaceFilesRuntimeCapability, XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN } from '@xpert-ai/plugin-sdk';
+import { Repository } from 'typeorm';
+import { createHash, randomUUID } from 'node:crypto';
+import { SpaceAccess } from './access.js';
+import { Space, SpaceItem, SpaceFileVersion } from './entities.js';
+import { SpacePages } from './pages.js';
+import { SpaceDocuments, contentHash } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpacesService } from './spaces.js';
+import { denied, PLUGIN, scoped } from './domain.js';
+let SpaceFiles = class SpaceFiles {
+    access;
+    pages;
+    spaces;
+    documents;
+    knowledge;
+    versions;
+    runtime;
+    constructor(access, pages, spaces, documents, knowledge, versions, runtime) {
+        this.access = access;
+        this.pages = pages;
+        this.spaces = spaces;
+        this.documents = documents;
+        this.knowledge = knowledge;
+        this.versions = versions;
+        this.runtime = runtime;
+    }
+    async put(actor, itemId, buffer, fileName, mimeType, revisionId = null, updateCurrent = true) {
+        const access = await this.access.resource(actor, itemId, 'write');
+        if (!access.space.projectId || !access.item || buffer.byteLength > 25 * 1024 * 1024)
+            throw denied();
+        const safeName = fileName.replace(/[\\/\u0000-\u001f]/gu, '_').replace(/^\.+/u, '_').slice(0, 180) || 'file';
+        const versionId = randomUUID();
+        // Space is a Project extension; current files and snapshots share its volume and ACL.
+        const folder = `.space-history/${itemId}/${versionId}`;
+        const scope = { ...scoped(actor), userId: actor.userId, catalog: 'projects',
+            projectId: access.space.projectId, scopeId: access.space.projectId };
+        const files = this.runtime.createScopedApi(scope).capabilities?.get(WorkspaceFilesRuntimeCapability);
+        if (!files)
+            throw new Error('spaces.files_unavailable');
+        const uploaded = await files.uploadBuffer({ ...scope, buffer, originalName: safeName, fileName: safeName, folder, mimeType });
+        const reference = { ...scope, source: 'platform.workspace.files',
+            filePath: uploaded.filePath, workspacePath: uploaded.filePath, originalName: safeName, mimeType, size: buffer.byteLength };
+        const version = await this.versions.save(this.versions.create({ ...scoped(actor), id: versionId, itemId,
+            createdById: actor.userId, reference, revisionId, sha256: createHash('sha256').update(buffer).digest('hex') }));
+        if (updateCurrent) {
+            await this.documents.write(actor, itemId, buffer);
+            await this.access.items.update({ ...scoped(actor), id: itemId }, { file: reference, currentFileVersionId: version.id });
+            await this.knowledge.sync(actor, access.space, access.item);
+        }
+        return version;
+    }
+    /** Opaque file protocol. Editor plugins own parsing; this resource owns snapshots and CAS. */
+    async editorRead(actor, itemId) {
+        const { item, space } = await this.access.resource(actor, itemId, 'read');
+        if (!item?.editorKey || !item.currentFileVersionId)
+            throw denied();
+        const disk = await this.documents.read(actor, space, item);
+        if (!disk || disk.sha256 !== item.fileHash)
+            throw new ConflictException('spaces.version_conflict');
+        return { buffer: disk.buffer, revision: this.editorRevision(item) };
+    }
+    editorRevision(item) {
+        // Metadata changes (move/trash/restore) invalidate a previously opened file as well.
+        return `${item.version}:${item.currentFileVersionId}:${item.fileHash}`;
+    }
+    async editorWrite(actor, itemId, expectedRevision, buffer) {
+        const access = await this.access.resource(actor, itemId, 'write');
+        const result = await this.access.items.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: access.space.id }, lock: { mode: 'pessimistic_write' } });
+            const repo = manager.getRepository(SpaceItem);
+            const item = await repo.findOneOrFail({ where: { ...scoped(actor), id: itemId }, lock: { mode: 'pessimistic_write' } });
+            await this.access.resource(actor, itemId, 'write');
+            if (!item.editorKey || !item.currentFileVersionId || !item.filePath || item.deleted)
+                throw denied();
+            if (this.editorRevision(item) !== expectedRevision)
+                throw new ConflictException('spaces.version_conflict');
+            const disk = await this.documents.read(actor, access.space, item);
+            if (!disk || disk.sha256 !== item.fileHash)
+                throw new ConflictException('spaces.version_conflict');
+            const version = await this.put(actor, itemId, buffer, item.filePath.split('/').pop() ?? item.title, item.file?.mimeType ?? 'application/octet-stream', null, false);
+            // ProjectFiles performs a second atomic hash check against edits made outside this resource.
+            await this.documents.api().write({ ...this.documents.scope(actor, access.space), path: item.filePath,
+                buffer, expectedHash: item.fileHash });
+            const updated = { ...item, currentFileVersionId: version.id, file: version.reference,
+                fileHash: contentHash(buffer), version: item.version + 1, syncStatus: 'ready', syncError: null };
+            await repo.update(item.id, { currentFileVersionId: updated.currentFileVersionId, file: updated.file,
+                fileHash: updated.fileHash, version: updated.version, syncStatus: updated.syncStatus, syncError: null });
+            return { revision: this.editorRevision(updated) };
+        });
+        await this.knowledge.sync(actor, access.space, await this.access.items.findOneByOrFail({ ...scoped(actor), id: itemId }));
+        return result;
+    }
+    async readBytes(actor, versionId) {
+        const version = await this.get(actor, versionId);
+        const files = this.runtime.createScopedApi(actor).capabilities?.get(WorkspaceFilesRuntimeCapability);
+        if (!files)
+            throw new Error('spaces.files_unavailable');
+        return (await files.readBuffer(version.reference)).buffer;
+    }
+    async upload(actor, spaceId, parentId, fileName, mimeType, buffer) {
+        await this.access.resource(actor, parentId ?? spaceId, 'write');
+        if (buffer.byteLength > 25 * 1024 * 1024)
+            throw new Error('spaces.file_too_large');
+        const item = await this.spaces.createItem(actor, { spaceId, parentId, title: fileName.slice(0, 200), kind: 'file' });
+        try {
+            return { item, version: await this.put(actor, item.id, buffer, fileName, mimeType) };
+        }
+        catch (error) {
+            await this.access.items.update({ ...scoped(actor), id: item.id }, { deleted: true });
+            throw error;
+        }
+    }
+    async get(actor, versionId) {
+        const version = await this.versions.findOneByOrFail({ ...scoped(actor), id: versionId });
+        await this.access.resource(actor, version.itemId, 'read');
+        return version;
+    }
+    async list(actor, itemId) {
+        await this.access.resource(actor, itemId, 'read');
+        return this.versions.find({ where: { ...scoped(actor), itemId }, order: { createdAt: 'DESC' } });
+    }
+    async exportPage(actor, itemId) {
+        const revision = await this.pages.checkpoint(actor, itemId, 'Export');
+        const access = await this.access.resource(actor, itemId, 'write');
+        const file = await this.put(actor, itemId, Buffer.from(revision.markdown || '\n', 'utf8'), `${access.item?.title ?? 'Page'}.md`, 'text/markdown', revision.id);
+        const artifacts = this.runtime.createScopedApi(actor).capabilities?.get(ArtifactsRuntimeCapability);
+        if (!artifacts)
+            throw new Error('spaces.artifacts_unavailable');
+        const artifact = await artifacts.createArtifact({ source: { pluginName: PLUGIN, resourceType: 'space-item', resourceId: itemId },
+            authorizationProviderKey: 'spaces', scope: { projectId: access.space.projectId, userId: null }, kind: 'markdown', title: access.item?.title });
+        const version = await artifacts.ensureArtifactVersion({ artifactId: artifact.id, idempotencyKey: `revision:${revision.id}`,
+            workspaceFileRef: file.reference, mimeType: 'text/markdown', fileName: file.reference.originalName, sha256: file.sha256,
+            sourceVersionId: revision.id });
+        const link = await artifacts.createArtifactLink({ artifactId: artifact.id, artifactVersionId: version.version.id,
+            versionMode: 'version', access: { mode: 'organization_all' }, presentation: { disposition: 'attachment', allowDownload: true } });
+        return { fileVersionId: file.id, revisionId: revision.id, sequence: revision.sequence, artifactId: artifact.id, versionId: version.version.id, url: link.publicUrl };
+    }
+    async collect(actor, spaceId, parentId, artifactId, versionId) {
+        await this.access.resource(actor, parentId ?? spaceId, 'write');
+        const { artifact, version, buffer } = await this.artifactBytes(actor, artifactId, versionId);
+        const item = await this.spaces.createItem(actor, { spaceId, parentId, title: version.fileName ?? artifact.title ?? 'Artifact', kind: 'artifact', artifactId, artifactVersionId: versionId });
+        try {
+            await this.put(actor, item.id, buffer, version.fileName ?? item.title, version.mimeType ?? 'application/octet-stream');
+        }
+        catch (error) {
+            await this.access.items.update(item.id, { deleted: true });
+            throw error;
+        }
+        return item;
+    }
+    async artifactBytes(actor, artifactId, versionId) {
+        const artifacts = this.runtime.createScopedApi(actor).capabilities?.get(ArtifactsRuntimeCapability);
+        if (!artifacts)
+            throw new Error('spaces.artifacts_unavailable');
+        const artifact = await artifacts.getArtifact(artifactId);
+        const version = (await artifacts.listArtifactVersions({ artifactId })).find((version) => version.id === versionId);
+        if (!version)
+            throw denied();
+        if (!version.workspaceFileRef)
+            throw new BadRequestException('spaces.artifact_file_unavailable');
+        // Collection can read another authorized project; its own ACL is checked by both
+        // Artifacts and WorkspaceFiles. The destination Project must not replace that scope.
+        const files = this.runtime.createScopedApi({ ...scoped(actor), userId: actor.userId }).capabilities?.get(WorkspaceFilesRuntimeCapability);
+        if (!files)
+            throw new Error('spaces.files_unavailable');
+        const bytes = await files.readBuffer(version.workspaceFileRef);
+        return { artifact, version, buffer: bytes.buffer };
+    }
+    async available(actor, page) {
+        await this.access.project(actor);
+        const api = this.runtime.createScopedApi(actor).capabilities?.require(ArtifactsRuntimeCapability);
+        if (!api)
+            throw new Error('spaces.artifacts_unavailable');
+        const result = await api.listArtifacts({ page, pageSize: 40 });
+        return { ...result, items: await Promise.all(result.items.map(async (artifact) => ({
+                id: artifact.id, title: artifact.title, versions: (await api.listArtifactVersions({ artifactId: artifact.id })).filter((version) => version.workspaceFileRef)
+            }))) };
+    }
+    async current(actor, itemId) {
+        const { item, space } = await this.access.resource(actor, itemId, 'read');
+        if (!space.projectId || !item?.filePath || item.kind === 'folder')
+            throw denied();
+        return { reference: { ...scoped(actor), userId: actor.userId, projectId: space.projectId,
+                catalog: 'projects', source: 'platform.workspace.files', filePath: item.filePath,
+                scopeId: space.projectId, workspacePath: item.filePath }, fileName: item.filePath.split('/').pop() ?? item.title,
+            mimeType: item.kind === 'page' ? 'text/markdown' : item.file?.mimeType ?? 'application/octet-stream' };
+    }
+    async openArtifact(actor, itemId) {
+        const access = await this.access.resource(actor, itemId, 'read');
+        if (!access.item?.artifactId)
+            throw denied();
+        // A collection is a reference. It never expands access to the original Artifact.
+        const artifacts = this.runtime.createScopedApi(actor).capabilities?.get(ArtifactsRuntimeCapability);
+        if (!artifacts)
+            throw new Error('spaces.artifacts_unavailable');
+        const artifact = await artifacts.getArtifact(access.item.artifactId);
+        const versions = await artifacts.listArtifactVersions({ artifactId: artifact.id });
+        const version = versions.find((entry) => entry.id === access.item?.artifactVersionId);
+        if (!version)
+            throw denied();
+        return { artifact, version };
+    }
+};
+SpaceFiles = __decorate([
+    Injectable(),
+    __param(5, InjectRepository(SpaceFileVersion)),
+    __param(6, Inject(XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN)),
+    __metadata("design:paramtypes", [SpaceAccess, SpacePages, SpacesService,
+        SpaceDocuments,
+        SpaceKnowledge,
+        Repository, Object])
+], SpaceFiles);
+export { SpaceFiles };

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;
+    bindingId: string;
+    locator: string;
+    requestId: string;
+    expectedRevision: string;
+    confirmed: true;
+}, {
+    spaceId: string;
+    expectedHash: string;
+    bindingId: string;
+    locator: string;
+    requestId: string;
+    expectedRevision: 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,48 @@
+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 { 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: [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/knowledge.d.ts

@@ -0,0 +1,43 @@
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+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;
+    constructor(access: SpaceAccess, runtime: RuntimeCapabilityRegistry);
+    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: "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: "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): Promise<boolean>;
+}