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

package/dist/resource-provider.d.ts

@@ -0,0 +1,36 @@
+import { type ContentResourceEditor, type ContentResourceRequest, type ContentPrincipal, type ContentPageProvider, type ContentLocationProvider, type ContentPublicationObserver, type ContentReferenceProvider, type IContentResourceProvider } from '@xpert-ai/plugin-sdk';
+import { SpaceAccess } from './access.js';
+import { SpaceFiles } from './files.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpaceReferences } from './references.js';
+import { SpaceSubpages } from './subpages.js';
+export declare class SpacesResourceProvider implements IContentResourceProvider {
+    private readonly access;
+    private readonly documents;
+    private readonly knowledge;
+    private readonly subpages;
+    private readonly referenceService;
+    private readonly files;
+    readonly title = "Spaces";
+    constructor(access: SpaceAccess, documents: SpaceDocuments, knowledge: SpaceKnowledge, subpages: SpaceSubpages, referenceService: SpaceReferences, files: SpaceFiles);
+    readonly editor: ContentResourceEditor;
+    readonly references: ContentReferenceProvider;
+    readonly pages: ContentPageProvider;
+    readonly publication: ContentPublicationObserver;
+    readonly locations: ContentLocationProvider;
+    validateLocationChange(input: Parameters<NonNullable<ContentLocationProvider['validateLocationChange']>>[0]): Promise<void>;
+    onLocationPrepared(input: Parameters<NonNullable<ContentLocationProvider['onLocationPrepared']>>[0]): Promise<void>;
+    onLocationChanged(input: Parameters<NonNullable<ContentLocationProvider['onLocationChanged']>>[0]): Promise<void>;
+    onDocumentPublished(input: Parameters<NonNullable<ContentPublicationObserver['onDocumentPublished']>>[0]): Promise<void>;
+    authorize(input: ContentResourceRequest & {
+        principal: ContentPrincipal;
+    }): Promise<{
+        providerKey: string;
+        resourceId: string;
+        title: string;
+        role: "editor" | "manager" | "owner" | "member";
+        canWrite: boolean;
+        canManage: boolean;
+    }>;
+}

package/dist/resource-provider.js

@@ -0,0 +1,144 @@
+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 { ConflictException, Injectable } from '@nestjs/common';
+import { ContentResourceProvider } from '@xpert-ai/plugin-sdk';
+import { Space, SpaceItem } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { SpaceFiles } from './files.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { denied, scoped } from './domain.js';
+import { SpaceReferences } from './references.js';
+import { SpaceSubpages } from './subpages.js';
+let SpacesResourceProvider = class SpacesResourceProvider {
+    access;
+    documents;
+    knowledge;
+    subpages;
+    referenceService;
+    files;
+    title = 'Spaces';
+    constructor(access, documents, knowledge, subpages, referenceService, files) {
+        this.access = access;
+        this.documents = documents;
+        this.knowledge = knowledge;
+        this.subpages = subpages;
+        this.referenceService = referenceService;
+        this.files = files;
+    }
+    editor = {
+        describe: async (input) => {
+            const actor = { ...input.actor, projectId: input.projectId, assistantId: input.assistantId };
+            const { item, space } = await this.access.resource(actor, input.sourceResourceId, 'read');
+            if (!space.projectId || !item?.editorKey || !item.filePath || item.deleted)
+                throw denied();
+            return { editorKey: item.editorKey, projectId: space.projectId, path: item.filePath, title: item.title };
+        },
+        files: {
+            read: (input) => this.files.editorRead({ ...input.actor, projectId: input.projectId, assistantId: input.assistantId }, input.sourceResourceId),
+            write: (input) => this.files.editorWrite({ ...input.actor, projectId: input.projectId, assistantId: input.assistantId }, input.sourceResourceId, input.expectedRevision, input.buffer)
+        }
+    };
+    references = {
+        listReferences: (input) => this.referenceService.listReferences(input),
+        uploadReference: (input) => this.referenceService.uploadReference(input),
+        resolveReference: (input) => this.referenceService.resolveReference(input)
+    };
+    pages = {
+        pageHierarchy: (input) => this.subpages.hierarchy(input),
+        createChildPage: (input) => this.subpages.createChild(input)
+    };
+    publication = { onDocumentPublished: (input) => this.onDocumentPublished(input) };
+    locations = {
+        validateLocationChange: (input) => this.validateLocationChange(input),
+        onLocationPrepared: (input) => this.onLocationPrepared(input),
+        onLocationChanged: (input) => this.onLocationChanged(input)
+    };
+    async validateLocationChange(input) {
+        const actor = { ...input.actor, projectId: input.projectId, assistantId: input.assistantId };
+        const { item, space } = await this.access.resource(actor, input.source.resourceId, 'write', !input.deleted);
+        if (!item || space.projectId !== input.projectId || item.filePath !== input.path || item.version !== input.expectedSourceVersion)
+            throw new ConflictException('spaces.version_conflict');
+        if (item.deleted !== input.deleted)
+            await this.access.resource(actor, item.id, 'manage', !input.deleted);
+        const parent = await this.access.resource(actor, input.parentResourceId ?? item.spaceId, 'write');
+        if (parent.space.id !== item.spaceId || (parent.item && parent.item.kind !== 'folder'))
+            throw denied();
+        let cursor = parent.item;
+        while (cursor) {
+            if (cursor.id === item.id)
+                throw new ConflictException('spaces.tree_cycle');
+            cursor = cursor.parentId ? await this.access.items.findOneByOrFail({ ...scoped(actor), id: cursor.parentId }) : null;
+        }
+    }
+    async onLocationPrepared(input) {
+        await this.access.items.update({ ...scoped(input.actor), id: input.source.resourceId, version: input.expectedSourceVersion }, { syncStatus: 'pending', syncError: 'spaces.location_pending' });
+    }
+    async onLocationChanged(input) {
+        // Projection of a durable authorized operation: it must still finish if the initiating user leaves.
+        await this.access.items.manager.transaction(async (manager) => {
+            const repo = manager.getRepository(SpaceItem);
+            const item = await repo.findOneByOrFail({ ...scoped(input.actor), id: input.source.resourceId });
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(input.actor), id: item.spaceId, projectId: input.projectId }, lock: { mode: 'pessimistic_write' } });
+            const current = await repo.findOneByOrFail({ ...scoped(input.actor), id: item.id });
+            if (current.version === input.expectedSourceVersion + 1 && current.filePath === input.destination && current.deleted === input.deleted)
+                return;
+            if (current.version !== input.expectedSourceVersion || current.filePath !== input.path)
+                throw new ConflictException('spaces.version_conflict');
+            const descendants = await repo.findBy({ ...scoped(input.actor), spaceId: current.spaceId });
+            for (const child of descendants) {
+                if (!child.filePath?.startsWith(`${input.path}/`))
+                    continue;
+                child.filePath = input.destination + child.filePath.slice(input.path.length);
+                child.deleted = input.deleted;
+                child.version++;
+                await repo.save(child);
+            }
+            current.filePath = input.destination;
+            current.title = input.title;
+            current.parentId = input.parentResourceId;
+            current.deleted = input.deleted;
+            current.version++;
+            current.syncStatus = 'ready';
+            current.syncError = null;
+            await repo.save(current);
+        });
+    }
+    async onDocumentPublished(input) {
+        const actor = { ...input.actor, projectId: input.projectId };
+        const { item, space } = await this.access.resource(actor, input.sourceResourceId, 'write');
+        if (!item || item.deleted || space.projectId !== input.projectId || item.filePath !== input.path)
+            return;
+        const disk = await this.documents.read(actor, space, item);
+        if (!disk || disk.sha256 !== input.hash)
+            return;
+        await this.access.items.update(item.id, { fileHash: input.hash, projectedSequence: input.sequence,
+            markdown: disk.buffer.toString('utf8'), syncStatus: 'ready', syncError: null });
+        await this.knowledge.sync(actor, space, item);
+        const indexed = await this.access.items.findOneByOrFail({ ...scoped(actor), id: item.id });
+        if (indexed.indexStatus === 'failed')
+            throw new Error('spaces.index_retry_required');
+    }
+    async authorize(input) {
+        const resourceId = input.resourceId;
+        const result = await this.access.resolve(input.principal, resourceId, input.operation);
+        // Resource IDs identify items. File paths only constrain that item's Project location.
+        if (input.filePath && input.filePath !== result.item?.filePath)
+            throw denied();
+        return { providerKey: 'spaces', resourceId, title: result.item?.title ?? result.space.title,
+            role: result.role, canWrite: result.canWrite, canManage: result.canManage };
+    }
+};
+SpacesResourceProvider = __decorate([
+    Injectable(),
+    ContentResourceProvider('spaces'),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceDocuments, SpaceKnowledge, SpaceSubpages, SpaceReferences, SpaceFiles])
+], SpacesResourceProvider);
+export { SpacesResourceProvider };

package/dist/spaces.d.ts

@@ -0,0 +1,95 @@
+import type { SpaceActor } from './domain.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { Repository } from 'typeorm';
+import { z } from 'zod/v3';
+import { Space, SpaceItem } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+export declare const createItemSchema: z.ZodObject<{
+    spaceId: z.ZodString;
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    title: z.ZodString;
+    kind: z.ZodEnum<["folder", "page", "file", "artifact"]>;
+    artifactId: z.ZodOptional<z.ZodString>;
+    artifactVersionId: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "folder" | "page" | "file" | "artifact";
+    title: string;
+    spaceId: string;
+    parentId: string | null;
+    artifactId?: string | undefined;
+    artifactVersionId?: string | undefined;
+    content?: string | undefined;
+}, {
+    kind: "folder" | "page" | "file" | "artifact";
+    title: string;
+    spaceId: string;
+    parentId?: string | null | undefined;
+    artifactId?: string | undefined;
+    artifactVersionId?: string | undefined;
+    content?: string | undefined;
+}>;
+export declare const editItemSchema: z.ZodObject<{
+    itemId: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    title: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deleted: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    itemId: string;
+    expectedVersion: number;
+    title?: string | undefined;
+    deleted?: boolean | undefined;
+    parentId?: string | null | undefined;
+}, {
+    itemId: string;
+    expectedVersion: number;
+    title?: string | undefined;
+    deleted?: boolean | undefined;
+    parentId?: string | null | undefined;
+}>;
+export declare class SpacesService {
+    private readonly access;
+    private readonly artifacts;
+    private readonly documents;
+    private readonly knowledge;
+    private readonly spaces;
+    constructor(access: SpaceAccess, artifacts: SpaceArtifacts, documents: SpaceDocuments, knowledge: SpaceKnowledge, spaces: Repository<Space>);
+    /** One extension record per authorized Project, shared by all connected Assistants. */
+    workspace(actor: SpaceActor): Promise<{
+        title: string;
+        projectId: string;
+        knowledgebaseId: string | null;
+        ownerId: string;
+        visibility: "personal" | "team";
+        version: number;
+        deleted: boolean;
+        id: string;
+        tenantId: string;
+        organizationId: string;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    list(actor: SpaceActor): Promise<{
+        root: Space | SpaceItem;
+        role: "editor" | "manager" | "owner" | "member";
+        canWrite: boolean;
+        canManage: boolean;
+        items: (SpaceItem & {
+            role: string;
+        })[];
+    }>;
+    tree(actor: SpaceActor, resourceId: string, trash?: boolean): Promise<{
+        root: Space | SpaceItem;
+        role: "editor" | "manager" | "owner" | "member";
+        canWrite: boolean;
+        canManage: boolean;
+        items: (SpaceItem & {
+            role: string;
+        })[];
+    }>;
+    createItem(actor: SpaceActor, input: z.infer<typeof createItemSchema>): Promise<SpaceItem>;
+    editItem(actor: SpaceActor, input: z.infer<typeof editItemSchema>): Promise<SpaceItem>;
+}

package/dist/spaces.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 { SpaceArtifacts } from './artifacts.js';
+import { ConflictException, Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod/v3';
+import { Space, SpaceItem } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { denied, id, kindSchema, scoped, title } from './domain.js';
+import { isInternalSpacePath, SpaceDocuments } from './documents.js';
+import { SpaceKnowledge } from './knowledge.js';
+export const createItemSchema = z.object({ spaceId: id, parentId: id.nullable().default(null), title,
+    kind: kindSchema, artifactId: id.optional(), artifactVersionId: id.optional(), content: z.string().max(100000).optional() }).strict();
+export const editItemSchema = z.object({ itemId: id, expectedVersion: z.number().int().positive(),
+    title: title.optional(), parentId: id.nullable().optional(), deleted: z.boolean().optional() }).strict();
+let SpacesService = class SpacesService {
+    access;
+    artifacts;
+    documents;
+    knowledge;
+    spaces;
+    constructor(access, artifacts, documents, knowledge, spaces) {
+        this.access = access;
+        this.artifacts = artifacts;
+        this.documents = documents;
+        this.knowledge = knowledge;
+        this.spaces = spaces;
+    }
+    /** One extension record per authorized Project, shared by all connected Assistants. */
+    async workspace(actor) {
+        const project = await this.access.project(actor);
+        const where = { ...scoped(actor), projectId: project.projectId };
+        await this.spaces.createQueryBuilder().insert().values({ ...where,
+            title: project.name ?? 'Space', ownerId: actor.userId, visibility: 'team'
+        }).orIgnore().execute();
+        const space = await this.spaces.findOneByOrFail(where);
+        if (space.deleted)
+            throw denied();
+        return { ...space, title: project.name ?? space.title };
+    }
+    async list(actor) {
+        const space = await this.workspace(actor);
+        return this.tree(actor, space.id);
+    }
+    async tree(actor, resourceId, trash = false) {
+        const principal = await this.access.principal(actor);
+        const root = await this.access.resolve(principal, resourceId, trash ? 'manage' : 'read');
+        if (!trash)
+            await this.spaces.manager.transaction(async (manager) => {
+                await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: root.space.id }, lock: { mode: 'pessimistic_write' } });
+                await this.documents.discover(actor, root.space, root.canWrite);
+            });
+        const all = await this.access.items.find({ where: { ...scoped(actor), spaceId: root.space.id }, order: { createdAt: 'ASC' } });
+        const items = [];
+        const descendants = new Set([resourceId]);
+        // Traverse by identity, never by a path supplied by the client.
+        for (let round = 0; round <= all.length; round++) {
+            let changed = false;
+            for (const item of all)
+                if (!descendants.has(item.id) && (resourceId === root.space.id || (item.parentId && descendants.has(item.parentId)))) {
+                    descendants.add(item.id);
+                    changed = true;
+                }
+            if (!changed)
+                break;
+        }
+        for (const item of all) {
+            if (!descendants.has(item.id) || item.deleted !== trash ||
+                (!trash && item.filePath && isInternalSpacePath(item.filePath)))
+                continue;
+            try {
+                const result = await this.access.resolve(principal, item.id, 'read', trash);
+                items.push({ ...item, role: result.role, parentId: item.id === resourceId ? null : item.parentId });
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== 'spaces.access_denied')
+                    throw error;
+            }
+        }
+        return { root: root.item ?? root.space, role: root.role, canWrite: root.canWrite, canManage: root.canManage, items };
+    }
+    async createItem(actor, input) {
+        const access = await this.access.resource(actor, input.parentId ?? input.spaceId, 'write');
+        if (access.space.id !== input.spaceId || (access.item && access.item.kind !== 'folder'))
+            throw denied();
+        if (input.kind !== 'page' && input.content !== undefined)
+            throw denied();
+        const { content, ...fields } = input;
+        {
+            const item = await this.access.items.save(this.access.items.create({
+                ...scoped(actor), ...fields, id: randomUUID(), createdById: actor.userId
+            }));
+            try {
+                await this.documents.initialize(actor, access.space, item, input.kind === 'page' ? Buffer.from(content ?? '', 'utf8') : undefined);
+            }
+            catch (error) {
+                await this.access.items.update(item.id, { deleted: true });
+                if (error && typeof error === 'object' && 'code' in error && error.code === '23505')
+                    throw new ConflictException('spaces.file_name_conflict');
+                throw error;
+            }
+            if (input.kind === 'page') {
+                try {
+                    item.artifactId = await this.artifacts.initializePage(actor, item.id, item.title);
+                }
+                catch (error) {
+                    await this.access.items.update(item.id, { deleted: true });
+                    throw error;
+                }
+            }
+            return item;
+        }
+    }
+    async editItem(actor, input) {
+        const result = await this.access.resource(actor, input.itemId, input.deleted !== undefined ? 'manage' : 'write', input.deleted === false);
+        if (!result.item)
+            throw denied();
+        if (result.space.projectId && result.item.filePath) {
+            const source = result.item;
+            const sourcePath = result.item.filePath;
+            const descendants = await this.access.items.findBy({ ...scoped(actor), spaceId: result.space.id });
+            if (source.editorKey === 'markdown.tiptap' || descendants.some((item) => item.editorKey === 'markdown.tiptap' && item.filePath?.startsWith(`${source.filePath}/`))) {
+                const target = Object.assign(new SpaceItem(), source, { title: input.title ?? source.title,
+                    parentId: input.parentId === undefined ? source.parentId : input.parentId, deleted: input.deleted ?? source.deleted });
+                const destination = input.deleted === true ? `.space-trash/${source.id}/${sourcePath.split('/').pop()}` : await this.documents.path(actor, target);
+                await this.documents.content().move({ actor, assistantId: actor.assistantId, projectId: result.space.projectId,
+                    source: { providerKey: 'spaces', resourceId: source.id }, path: sourcePath, destination,
+                    title: target.title, parentResourceId: target.parentId, deleted: target.deleted, expectedSourceVersion: input.expectedVersion });
+                return this.access.items.findOneByOrFail({ ...scoped(actor), id: source.id });
+            }
+        }
+        let moved;
+        let changed;
+        let updated;
+        try {
+            updated = await this.spaces.manager.transaction(async (manager) => {
+                changed = [];
+                // A single Space lock prevents concurrent moves from introducing a cycle.
+                await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: result.space.id }, lock: { mode: 'pessimistic_write' } });
+                await this.access.resource(actor, input.itemId, input.deleted !== undefined ? 'manage' : 'write', input.deleted === false);
+                const repo = manager.getRepository(SpaceItem);
+                const item = await repo.findOneByOrFail({ ...scoped(actor), id: input.itemId });
+                const previousPath = item.filePath;
+                if (item.version !== input.expectedVersion)
+                    throw new ConflictException('spaces.version_conflict');
+                if (input.parentId !== undefined) {
+                    const parent = await this.access.resource(actor, input.parentId ?? item.spaceId, 'write');
+                    if (parent.space.id !== item.spaceId || (parent.item && parent.item.kind !== 'folder'))
+                        throw denied();
+                    let cursor = parent.item;
+                    while (cursor) {
+                        if (cursor.id === item.id)
+                            throw new ConflictException('spaces.tree_cycle');
+                        cursor = cursor.parentId ? await repo.findOneByOrFail({ ...scoped(actor), id: cursor.parentId }) : null;
+                    }
+                    item.parentId = input.parentId;
+                }
+                if (input.title !== undefined)
+                    item.title = input.title;
+                if (input.deleted !== undefined)
+                    item.deleted = input.deleted;
+                if (result.space.projectId && previousPath) {
+                    const targetPath = input.deleted === true ? `.space-trash/${item.id}/${previousPath.split('/').pop()}`
+                        : await this.documents.path(actor, item);
+                    if (targetPath !== previousPath) {
+                        await this.documents.api().move({ ...this.documents.scope(actor, result.space), path: previousPath, destination: targetPath });
+                        moved = { path: targetPath, destination: previousPath };
+                        const children = await repo.findBy({ ...scoped(actor), spaceId: item.spaceId });
+                        for (const child of children) {
+                            if (!child.filePath?.startsWith(`${previousPath}/`))
+                                continue;
+                            child.filePath = `${targetPath}${child.filePath.slice(previousPath.length)}`;
+                            if (input.deleted !== undefined)
+                                child.deleted = input.deleted;
+                            child.version++;
+                            await repo.save(child);
+                            changed.push(child);
+                        }
+                        item.filePath = targetPath;
+                    }
+                }
+                item.version++;
+                return repo.save(item);
+            });
+        }
+        catch (error) {
+            if (moved) {
+                try {
+                    await this.documents.api().move({ ...this.documents.scope(actor, result.space), ...moved });
+                }
+                catch {
+                    await this.access.items.update(input.itemId, { syncStatus: 'failed', syncError: 'spaces.move_recovery_required' });
+                }
+            }
+            throw error;
+        }
+        for (const item of [updated, ...changed]) {
+            if (item.editorKey === 'markdown.tiptap' && result.space.projectId && item.filePath) {
+                const scope = { actor, projectId: result.space.projectId, assistantId: actor.assistantId, resourceId: item.id };
+                if (input.deleted !== undefined)
+                    await this.documents.content().setDeleted({ ...scope, deleted: input.deleted });
+                if (!item.deleted)
+                    await this.documents.content().relocate({ ...scope, path: item.filePath, title: item.title });
+            }
+            await this.knowledge.sync(actor, result.space, item);
+        }
+        return updated;
+    }
+};
+SpacesService = __decorate([
+    Injectable(),
+    __param(4, InjectRepository(Space)),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceArtifacts, SpaceDocuments,
+        SpaceKnowledge, Repository])
+], SpacesService);
+export { SpacesService };

package/dist/subpages.d.ts

@@ -0,0 +1,24 @@
+import type { ContentSourceInput } from '@xpert-ai/plugin-sdk';
+import type { ContentPageHierarchy } from '@xpert-ai/contracts';
+import { SpaceAccess } from './access.js';
+import { SpaceDocuments } from './documents.js';
+import { SpaceArtifacts } from './artifacts.js';
+/** Logical hierarchy is metadata, never an ACL or a disguised file folder.
+ * Each create owns one stable resource/path. Retry resumes publication instead of duplicating a child.
+ * Parent rename/move/trash does not mutate independent child files; a restored parent reconnects them.
+ */
+export declare class SpaceSubpages {
+    private readonly access;
+    private readonly documents;
+    private readonly artifacts;
+    constructor(access: SpaceAccess, documents: SpaceDocuments, artifacts: SpaceArtifacts);
+    private actor;
+    private parent;
+    hierarchy(input: ContentSourceInput): Promise<ContentPageHierarchy>;
+    createChild(input: ContentSourceInput & {
+        title: string;
+        requestId: string;
+    }): Promise<{
+        documentId: string;
+    }>;
+}

package/dist/subpages.js

@@ -0,0 +1,118 @@
+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 { ConflictException, Injectable } from '@nestjs/common';
+import { z } from 'zod/v3';
+import { SpaceAccess } from './access.js';
+import { Space } from './entities.js';
+import { SpaceDocuments, contentHash, safeName } from './documents.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { denied, scoped } from './domain.js';
+const create = z.object({ requestId: z.string().uuid(), title: z.string().trim().min(1).max(180) });
+const missing = (error) => error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+const entry = (item) => ({ resourceId: item.id, title: item.title, path: item.filePath });
+/** Logical hierarchy is metadata, never an ACL or a disguised file folder.
+ * Each create owns one stable resource/path. Retry resumes publication instead of duplicating a child.
+ * Parent rename/move/trash does not mutate independent child files; a restored parent reconnects them.
+ */
+let SpaceSubpages = class SpaceSubpages {
+    access;
+    documents;
+    artifacts;
+    constructor(access, documents, artifacts) {
+        this.access = access;
+        this.documents = documents;
+        this.artifacts = artifacts;
+    }
+    actor(input) { return { ...input.actor, projectId: input.projectId, assistantId: input.assistantId }; }
+    async parent(input, write = false) {
+        const result = await this.access.resource(this.actor(input), input.sourceResourceId, write ? 'write' : 'read');
+        if (!result.item || result.item.kind !== 'page' || !result.item.filePath || result.space.projectId !== input.projectId)
+            throw denied();
+        return { ...result, item: result.item };
+    }
+    async hierarchy(input) {
+        const { item, space, canWrite } = await this.parent(input);
+        const actor = this.actor(input);
+        const visible = async (candidate) => {
+            if (!candidate || candidate.deleted || candidate.editorKey !== 'markdown.tiptap' || !candidate.filePath)
+                return null;
+            try {
+                await this.access.resource(actor, candidate.id, 'read');
+                return entry(candidate);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'spaces.access_denied')
+                    return null;
+                throw error;
+            }
+        };
+        const parent = item.parentPageId ? await visible(await this.access.items.findOneBy({ ...scoped(actor), spaceId: space.id, id: item.parentPageId })) : null;
+        const rows = await this.access.items.find({ where: { ...scoped(actor), spaceId: space.id, parentPageId: item.id, deleted: false },
+            order: { createdAt: 'ASC' }, take: 101 });
+        const children = (await Promise.all(rows.slice(0, 100).map(visible))).filter((value) => value !== null);
+        return { supported: true, canCreate: canWrite, parent, children, hasMore: rows.length > 100 };
+    }
+    async createChild(input) {
+        const request = create.parse(input), actor = this.actor(input);
+        const { space } = await this.parent(input, true);
+        // Use the same Space lock as folder moves/discovery. Only the lock uses this transaction;
+        // publication is a retryable saga and its intent must survive process failure.
+        return this.access.items.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: space.id }, lock: { mode: 'pessimistic_write' } });
+            const { item: parent } = await this.parent(input, true);
+            let item = await this.access.items.findOneBy({ id: request.requestId });
+            if (item && (item.tenantId !== actor.tenantId || item.organizationId !== actor.organizationId || item.spaceId !== space.id ||
+                item.parentPageId !== parent.id || item.childRequestTitle !== request.title || item.createdById !== actor.userId || item.deleted))
+                throw new ConflictException('spaces.child_request_conflict');
+            if (!item) {
+                // New IDs cannot make cycles. Bound depth so corrupt legacy metadata cannot loop forever.
+                // Count the child itself as level one, then count its ancestors.
+                let cursor = parent, depth = 1;
+                while (cursor) {
+                    if (++depth > 32 || cursor.id === request.requestId)
+                        throw new ConflictException('spaces.page_depth');
+                    cursor = cursor.parentPageId ? await this.access.items.findOneBy({ ...scoped(actor), spaceId: space.id, id: cursor.parentPageId }) : null;
+                }
+                const directory = parent.filePath.slice(0, parent.filePath.lastIndexOf('/') + 1);
+                // Resource suffix avoids collisions between equally named children and unrelated files.
+                const filePath = `${directory}${safeName(request.title).slice(0, 100)}--${request.requestId}.md`;
+                item = await this.access.items.save(this.access.items.create({ ...scoped(actor), id: request.requestId,
+                    spaceId: space.id, parentId: parent.parentId, parentPageId: parent.id, childRequestTitle: request.title,
+                    createdById: actor.userId, kind: 'page', title: request.title, filePath, syncStatus: 'pending' }));
+            }
+            if (item.editorKey === 'markdown.tiptap')
+                return { documentId: item.id };
+            const fileScope = { actor, projectId: input.projectId, path: item.filePath };
+            const markdown = `# ${request.title.replace(/[\\`*_{}\[\]()#+.!<>|$]/gu, '\\$&')}\n\n`;
+            const buffer = Buffer.from(markdown), hash = contentHash(buffer);
+            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({ actor, assistantId: input.assistantId, projectId: input.projectId,
+                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 { documentId: item.id };
+        });
+    }
+};
+SpaceSubpages = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceDocuments, SpaceArtifacts])
+], SpaceSubpages);
+export { SpaceSubpages };