termdock 1.4.309 → 1.4.311

package/dist/server/architecture/routes.js

@@ -0,0 +1,117 @@
+import { Router } from 'express';
+import { pathValidator } from '../utils/pathValidator.js';
+import { ARCHITECTURE_FIELDS, ARCHITECTURE_FILE } from './document.js';
+import { ArchitectureConflict, ArchitectureStore } from './store.js';
+import { updateArchitectureField } from './fieldMutation.js';
+/** Mounted below /api/terminal, after its existing auth, CSRF and encrypted transport. */
+export function architectureRoutes() {
+    const router = Router();
+    router.use(async (req, res, next) => {
+        try {
+            const requested = req.method === 'GET' ? req.query.root : req.body?.root;
+            if (typeof requested !== 'string') {
+                res.status(400).json({ error: 'Project root is required' });
+                return;
+            }
+            const root = await (req.pathValidator ?? pathValidator).validateAsync(requested);
+            res.locals.architectureStore = new ArchitectureStore(root);
+            next();
+        }
+        catch (error) {
+            res.status(403).json({ error: error instanceof Error ? error.message : 'Project cannot be accessed' });
+        }
+    });
+    const store = (res) => res.locals.architectureStore;
+    router.get('/documents', async (_req, res, next) => { try {
+        res.json({ files: await store(res).list() });
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.get('/document', async (req, res, next) => { try {
+        res.json(await store(res).read(typeof req.query.file === 'string' ? req.query.file : ARCHITECTURE_FILE));
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.put('/document', async (req, res, next) => { try {
+        res.json(await store(res).save(req.body.file ?? ARCHITECTURE_FILE, req.body.document, req.body.revision));
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.get('/history', async (req, res, next) => { try {
+        res.json({ versions: await store(res).history(String(req.query.file ?? ARCHITECTURE_FILE)) });
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.get('/version', async (req, res, next) => { try {
+        res.json({ document: await store(res).historical(String(req.query.file), String(req.query.id)) });
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.get('/bundle', async (req, res, next) => {
+        try {
+            const file = String(req.query.file ?? ARCHITECTURE_FILE), storage = store(res);
+            const loaded = await storage.read(file);
+            if (!loaded.document) {
+                res.status(404).json({ error: 'Architecture document not found' });
+                return;
+            }
+            res.json(file === '.omm' ? await storage.exportOmmBundle() : await storage.exportOmmBundle(loaded.document));
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    router.put('/bundle', async (req, res, next) => { try {
+        await store(res).importOmmBundle(req.body.bundle, req.body.revision);
+        res.json(await store(res).read('.omm'));
+    }
+    catch (error) {
+        next(error);
+    } });
+    router.put('/field', async (req, res, next) => {
+        try {
+            const { file = ARCHITECTURE_FILE, perspective, node, field, value, revision } = req.body;
+            if (!ARCHITECTURE_FIELDS.includes(field) || typeof value !== 'string' || value.length > 100_000) {
+                res.status(400).json({ error: 'Invalid architecture field' });
+                return;
+            }
+            const storage = store(res);
+            if (file === '.omm') {
+                const loaded = await storage.read('.omm'), view = loaded.document?.perspectives.find(view => view.id === perspective);
+                const target = node ? view?.nodes.find(item => item.id === node) : view;
+                if (!view || !target) {
+                    res.status(404).json({ error: 'Architecture element not found' });
+                    return;
+                }
+                // Resolve opaque viewer IDs back to .omm paths through the store's stable IDs.
+                const { createHash } = await import('node:crypto');
+                const element = node ? ('documentPath' in target && typeof target.documentPath === 'string' && target.documentPath.startsWith(`${view.id}/`) && `e_${createHash('sha256').update(target.documentPath).digest('hex').slice(0, 20)}` === node ? target.documentPath : undefined) : view.id;
+                if (!element) {
+                    res.status(404).json({ error: 'Architecture element has no document yet' });
+                    return;
+                }
+                res.json(await storage.writeOmmField(element, field, value, revision));
+                return;
+            }
+            const loaded = await storage.read(file);
+            if (!loaded.document) {
+                res.status(404).json({ error: 'Architecture document not found' });
+                return;
+            }
+            const document = updateArchitectureField(loaded.document, perspective, node, field, value);
+            res.json(await storage.save(file, document, revision));
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    router.use((error, _req, res, _next) => {
+        res.status(error instanceof ArchitectureConflict ? 409 : 400).json({ error: error instanceof Error ? error.message : 'Architecture operation failed' });
+    });
+    return router;
+}

package/dist/server/architecture/store.js

@@ -0,0 +1,502 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import YAML from 'yaml';
+import { ARCHITECTURE_FIELDS, ARCHITECTURE_FILE, ARCHITECTURE_DIRECTORY, analysisFile, architectureScope, isArchitectureFile, isArchitectureSourcePath, parseArchitecture } from './document.js';
+import { parseFlowchart } from './flowchart.js';
+import { diffArchitecture } from './documentDiff.js';
+const runFile = promisify(execFile);
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const missing = (error) => error?.code === 'ENOENT';
+const safeName = (name) => /^[a-zA-Z][a-zA-Z0-9_-]{0,79}$/.test(name);
+const names = Object.fromEntries(ARCHITECTURE_FIELDS.map(field => [field, field === 'diagram' ? 'diagram.mmd' : `${field}.md`]));
+export class ArchitectureConflict extends Error {
+}
+/** Bound all document IO to real project directories; refuse symlinks in document trees. */
+export class ArchitectureStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async bounded(relative, create = false) {
+        if (!relative || relative.startsWith('/') || /[\\\x00-\x1f]/.test(relative) || relative.split('/').some(part => !part || part === '.' || part === '..'))
+            throw new Error('Unsafe architecture path');
+        const root = await fs.realpath(this.root);
+        let current = root;
+        const parts = relative.split('/');
+        for (let index = 0; index < parts.length; index++) {
+            current = path.join(current, parts[index]);
+            try {
+                const stat = await fs.lstat(current);
+                if (stat.isSymbolicLink())
+                    throw new Error('Architecture paths cannot contain symlinks');
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+                if (create && index < parts.length - 1)
+                    await fs.mkdir(current).catch(async (error) => { if (error.code !== 'EEXIST' || !(await fs.lstat(current)).isDirectory())
+                        throw error; });
+            }
+        }
+        return current;
+    }
+    async text(relative) {
+        const target = await this.bounded(relative);
+        try {
+            const stat = await fs.stat(target);
+            if (!stat.isFile() || stat.size > 5_000_000)
+                throw new Error('Architecture file exceeds the read limit');
+            return await fs.readFile(target, 'utf8');
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    async atomic(relative, content) {
+        const target = await this.bounded(relative, true), temp = `${target}.${randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(temp, content, { flag: 'wx', mode: 0o600 });
+            await fs.rename(temp, target);
+        }
+        finally {
+            await fs.rm(temp, { force: true });
+        }
+    }
+    async locked(operation) {
+        const lock = await this.bounded('.termdock/architecture.lock', true);
+        let handle;
+        const deadline = Date.now() + 10_000;
+        while (!handle) {
+            try {
+                handle = await fs.open(lock, 'wx', 0o600);
+                await handle.writeFile(JSON.stringify({ pid: process.pid, time: Date.now() }));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (Date.now() >= deadline)
+                    throw new ArchitectureConflict('Another architecture update is in progress');
+                try {
+                    const owner = JSON.parse(await fs.readFile(lock, 'utf8'));
+                    try {
+                        process.kill(owner.pid, 0);
+                    }
+                    catch (error) {
+                        if (error.code === 'ESRCH') {
+                            await fs.rm(lock, { force: true });
+                            continue;
+                        }
+                    }
+                }
+                catch { /* A newly created lock may not yet contain its owner. */ }
+                await new Promise(resolve => setTimeout(resolve, 30));
+            }
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await handle.close();
+            await fs.rm(lock, { force: true });
+        }
+    }
+    async list() {
+        const result = [];
+        if (await this.text(ARCHITECTURE_FILE))
+            result.push(ARCHITECTURE_FILE);
+        const folder = await this.bounded(ARCHITECTURE_DIRECTORY);
+        try {
+            for (const entry of await fs.readdir(folder, { withFileTypes: true }))
+                if (entry.isFile() && isArchitectureFile(`${ARCHITECTURE_DIRECTORY}/${entry.name}`))
+                    result.push(`${ARCHITECTURE_DIRECTORY}/${entry.name}`);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        try {
+            if ((await fs.readdir(await this.bounded('.omm'), { withFileTypes: true })).some(entry => entry.isDirectory() && safeName(entry.name)))
+                result.push('.omm');
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        return result.sort();
+    }
+    async read(file = ARCHITECTURE_FILE) {
+        if (!isArchitectureFile(file))
+            throw new Error('Invalid architecture document');
+        if (file === '.omm')
+            return this.readOmm();
+        const content = await this.text(file);
+        return { document: content ? parseArchitecture(content) : null, revision: content ? digest(content) : null };
+    }
+    async git() {
+        try {
+            const [{ stdout: gitCommit }, { stdout: gitBranch }] = await Promise.all([runFile('git', ['rev-parse', '--short', 'HEAD'], { cwd: this.root, timeout: 2000 }), runFile('git', ['branch', '--show-current'], { cwd: this.root, timeout: 2000 })]);
+            return { gitCommit: gitCommit.trim(), gitBranch: gitBranch.trim() };
+        }
+        catch {
+            return {};
+        }
+    }
+    historyDirectory(file) { return `.termdock/architecture-history/${digest(file).slice(0, 24)}`; }
+    async archive(file, previous) {
+        if (!previous.document)
+            return;
+        const folder = this.historyDirectory(file);
+        const id = `${Date.now()}-${randomUUID()}`;
+        await this.atomic(`${folder}/${id}.json`, JSON.stringify(previous.document, null, 2));
+        const entries = (await fs.readdir(await this.bounded(folder))).filter(name => /^\d+-[a-f0-9-]+\.json$/.test(name)).sort().reverse();
+        for (const old of entries.slice(30))
+            await fs.unlink(await this.bounded(`${folder}/${old}`));
+    }
+    async history(file) {
+        if (!isArchitectureFile(file))
+            throw new Error('Invalid architecture document');
+        const current = await this.read(file);
+        if (!current.document)
+            return [];
+        const folder = this.historyDirectory(file);
+        let entries;
+        try {
+            entries = (await fs.readdir(await this.bounded(folder))).filter(name => /^\d+-[a-f0-9-]+\.json$/.test(name)).sort().reverse().slice(0, 30);
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw error;
+        }
+        return Promise.all(entries.map(async (name) => {
+            const previous = parseArchitecture((await this.text(`${folder}/${name}`)));
+            return { id: name.slice(0, -5), savedAt: previous.generatedAt, changes: diffArchitecture(previous, current.document) };
+        }));
+    }
+    async historical(file, id) {
+        if (!isArchitectureFile(file) || !/^\d+-[a-f0-9-]+$/.test(id))
+            throw new Error('Invalid architecture version');
+        const content = await this.text(`${this.historyDirectory(file)}/${id}.json`);
+        if (!content)
+            throw new Error('Architecture version not found');
+        return parseArchitecture(content);
+    }
+    async save(file, input, expectedRevision) {
+        if (!isArchitectureFile(file) || file === '.omm')
+            throw new Error('Use field writes for .omm documents');
+        const document = parseArchitecture(JSON.stringify(input));
+        if (document.analysis && analysisFile(document.analysis) !== file)
+            throw new Error('Architecture scope does not match its file');
+        return this.locked(async () => {
+            const previous = await this.read(file);
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before saving');
+            const changes = diffArchitecture(previous.document, document);
+            if (previous.document && !changes.length && ['summary', 'analysis', 'details', 'origin'].every(key => JSON.stringify(previous.document[key]) === JSON.stringify(document[key])))
+                return previous;
+            await this.archive(file, previous);
+            const now = new Date().toISOString(), git = await this.git();
+            document.generatedAt = now;
+            document.meta = { ...previous.document?.meta, created: previous.document?.meta?.created ?? now, updated: now, updateCount: (previous.document?.meta?.updateCount ?? 0) + 1, ...git };
+            for (const view of document.perspectives) {
+                const oldView = previous.document?.perspectives.find(old => old.id === view.id);
+                view.meta = !oldView || changes.some(change => change.perspective === view.id) ? { created: oldView?.meta?.created ?? now, updated: now, updateCount: (oldView?.meta?.updateCount ?? 0) + 1, ...git, ...(oldView?.diagram ? { previousDiagram: oldView.diagram } : {}) } : oldView.meta;
+                for (const node of view.nodes) {
+                    const old = oldView?.nodes.find(old => old.id === node.id);
+                    if (!old || changes.some(change => change.perspective === view.id && change.node === node.id))
+                        node.meta = { created: old?.meta?.created ?? now, updated: now, updateCount: (old?.meta?.updateCount ?? 0) + 1, ...git, ...(old?.diagram ? { previousDiagram: old.diagram } : {}) };
+                    else
+                        node.meta = old.meta;
+                }
+            }
+            const content = JSON.stringify(document, null, 2);
+            await this.atomic(file, content);
+            return { document, revision: digest(content) };
+        });
+    }
+    ommPath(element) {
+        if (!element || element.split('/').length > 12 || !element.split('/').every(safeName))
+            throw new Error('Invalid .omm element path');
+        return `.omm/${element}`;
+    }
+    async ommElements() {
+        const result = [];
+        const walk = async (relative, depth) => {
+            if (depth > 12 || result.length > 2400)
+                throw new Error('.omm tree exceeds the architecture limit');
+            let entries;
+            try {
+                entries = await fs.readdir(await this.bounded(relative), { withFileTypes: true });
+            }
+            catch (error) {
+                if (missing(error))
+                    return;
+                throw error;
+            }
+            for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!safeName(entry.name))
+                    continue;
+                if (entry.isSymbolicLink())
+                    throw new Error('.omm tree cannot contain symlinks');
+                if (entry.isDirectory()) {
+                    const next = `${relative}/${entry.name}`;
+                    result.push(next.slice(5));
+                    await walk(next, depth + 1);
+                }
+            }
+        };
+        await walk('.omm', 0);
+        return result;
+    }
+    async readOmmFields(element) {
+        const base = this.ommPath(element), fields = {};
+        for (const field of ARCHITECTURE_FIELDS) {
+            const value = await this.text(`${base}/${names[field]}`);
+            if (value !== null)
+                fields[field] = value;
+        }
+        const raw = await this.text(`${base}/meta.yaml`);
+        if (!raw)
+            return fields;
+        const m = YAML.parse(raw, { maxAliasCount: 10 });
+        const meta = {};
+        for (const [from, to] of [['created', 'created'], ['updated', 'updated'], ['git_commit', 'gitCommit'], ['git_branch', 'gitBranch'], ['prev_diagram', 'previousDiagram']])
+            if (typeof m?.[from] === 'string')
+                meta[to] = m[from];
+        if (typeof m?.update_count === 'number' && Number.isSafeInteger(m.update_count) && m.update_count >= 0)
+            meta.updateCount = m.update_count;
+        return { ...fields, meta };
+    }
+    async validateOmmMerge(files) {
+        const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'termdock-omm-import-'));
+        try {
+            const stage = new ArchitectureStore(temporary), merged = { ...(await this.exportOmmBundle()).files, ...files };
+            for (const [name, value] of Object.entries(merged))
+                await stage.atomic(`.omm/${name}`, value);
+            const result = await stage.readOmm();
+            if (!result.document)
+                throw new Error('Bundle contains no architecture perspectives');
+        }
+        finally {
+            await fs.rm(temporary, { recursive: true, force: true });
+        }
+    }
+    async writeOmmField(element, field, content, expectedRevision) {
+        if (!ARCHITECTURE_FIELDS.includes(field) || typeof content !== 'string' || content.length > 100_000)
+            throw new Error('Invalid architecture field');
+        const base = this.ommPath(element);
+        if (field === 'diagram') {
+            const issues = parseFlowchart(content).issues.filter(issue => !issue.startsWith('Connection needs'));
+            if (issues.length)
+                throw new Error(issues.join('\n'));
+        }
+        return this.locked(async () => {
+            const previous = await this.readOmm();
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before saving');
+            const old = await this.readOmmFields(element);
+            if (old[field] === content)
+                return previous;
+            await this.validateOmmMerge({ [`${element}/${names[field]}`]: content });
+            await this.archive('.omm', previous);
+            const now = new Date().toISOString();
+            const git = await this.git();
+            // Field writes preserve the upstream file layout and metadata convention.
+            await this.atomic(`${base}/${names[field]}`, content);
+            const meta = { created: old.meta?.created ?? now, updated: now, update_count: (old.meta?.updateCount ?? 0) + 1,
+                last_field: field, git_commit: git.gitCommit, git_branch: git.gitBranch,
+                ...(field === 'diagram' && old.diagram ? { prev_diagram: old.diagram } : old.meta?.previousDiagram ? { prev_diagram: old.meta.previousDiagram } : {}) };
+            await this.atomic(`${base}/meta.yaml`, YAML.stringify(meta));
+            return this.readOmm();
+        });
+    }
+    async deleteOmmElement(element) { const target = this.ommPath(element); await this.locked(async () => { await this.archive('.omm', await this.readOmm()); await fs.rm(await this.bounded(target), { recursive: true, force: false }); }); }
+    async readOmm() {
+        const elements = await this.ommElements();
+        if (!elements.length)
+            return { document: null, revision: null };
+        const data = new Map();
+        let total = 0;
+        for (let offset = 0; offset < elements.length; offset += 16) {
+            for (const [element, fields] of await Promise.all(elements.slice(offset, offset + 16).map(async (element) => [element, await this.readOmmFields(element)]))) {
+                total += Buffer.byteLength(JSON.stringify(fields), 'utf8');
+                if (total > 5_000_000)
+                    throw new Error('.omm documentation exceeds the read limit');
+                data.set(element, fields);
+            }
+        }
+        const perspectives = [];
+        const uid = (element) => `e_${digest(element).slice(0, 20)}`;
+        const label = (value) => value.replace(/-/g, ' ').replace(/^\w/, ch => ch.toUpperCase());
+        const links = [];
+        for (const perspective of elements.filter(element => !element.includes('/'))) {
+            const fields = data.get(perspective);
+            const nodes = new Map(), edges = [];
+            const add = async (element, parentId, diagramLabel) => {
+                const old = nodes.get(element);
+                if (old)
+                    return old;
+                const entry = data.get(element) ?? {};
+                const lines = (diagramLabel ?? '').split('\n');
+                const files = [];
+                for (const line of lines.slice(1)) {
+                    const relative = line.trim();
+                    if (isArchitectureSourcePath(relative)) {
+                        try {
+                            if ((await fs.stat(await this.bounded(relative))).isFile())
+                                files.push({ path: relative });
+                        }
+                        catch { /* Documentation can reference a directory or a removed file. */ }
+                    }
+                }
+                const node = { id: uid(element), documentPath: element, title: lines[0]?.replace(/^@/, '') || label(element.split('/').pop()), summary: (entry.description ?? '').replace(/[#*`]/g, '').split(/\n\s*\n/)[0].slice(0, 600), files, ...entry, ...(parentId ? { parentId } : {}) };
+                nodes.set(element, node);
+                const graph = parseFlowchart(entry.diagram ?? '');
+                for (const child of graph.nodes) {
+                    const childElement = `${element}/${child.id}`, childNode = await add(childElement, node.id, child.label);
+                    childNode.role = child.role;
+                    if (child.ref)
+                        links.push({ node: childNode, target: child.ref });
+                }
+                for (const edge of graph.edges)
+                    edges.push({ from: uid(`${element}/${edge.from}`), to: uid(`${element}/${edge.to}`), label: edge.label });
+                // Include documented children even if an old diagram has not mentioned them yet.
+                for (const child of elements.filter(child => child.startsWith(`${element}/`) && child.slice(element.length + 1).indexOf('/') === -1))
+                    await add(child, node.id);
+                return node;
+            };
+            const graph = parseFlowchart(fields.diagram ?? '');
+            for (const child of graph.nodes) {
+                const node = await add(`${perspective}/${child.id}`, undefined, child.label);
+                node.role = child.role;
+                if (child.ref)
+                    links.push({ node, target: child.ref });
+            }
+            for (const child of elements.filter(child => child.startsWith(`${perspective}/`) && child.split('/').length === 2))
+                await add(child);
+            for (const edge of graph.edges)
+                edges.push({ from: uid(`${perspective}/${edge.from}`), to: uid(`${perspective}/${edge.to}`), label: edge.label });
+            if (!nodes.size)
+                nodes.set(perspective, { id: uid(perspective), title: label(perspective), summary: fields.description ?? '', files: [], ...fields });
+            perspectives.push({ id: perspective, title: label(perspective), summary: (fields.description ?? '').split(/\n\s*\n/)[0].slice(0, 600), nodes: [...nodes.values()], edges, ...fields });
+        }
+        for (const link of links)
+            if (perspectives.some(view => view.id === link.target))
+                link.node.references = [...(link.node.references ?? []), { perspective: link.target }];
+        const generatedAt = [...data.values()].map(value => value.meta?.updated).filter((value) => !!value && Number.isFinite(Date.parse(value))).sort().pop() ?? new Date(0).toISOString();
+        const document = parseArchitecture(JSON.stringify({ version: 1, origin: 'omm', generatedAt, summary: `${path.basename(this.root)} architecture`, perspectives }));
+        const config = await this.text('.omm/config.yaml');
+        return { document, revision: digest(JSON.stringify([...data]) + (config ?? '')) };
+    }
+    async config(language) {
+        const raw = await this.text('.omm/config.yaml');
+        const config = raw ? YAML.parse(raw, { maxAliasCount: 10 }) : { version: '0.1.0', language: 'en' };
+        if (!config || typeof config !== 'object' || Array.isArray(config))
+            throw new Error('Invalid .omm configuration');
+        if (language !== undefined) {
+            if (!/^[a-z]{2}(?:-[A-Z]{2})?$/.test(language))
+                throw new Error('Invalid language');
+            config.language = language;
+            await this.locked(() => this.atomic('.omm/config.yaml', YAML.stringify(config)));
+        }
+        return { language: typeof config?.language === 'string' ? config.language : 'en' };
+    }
+    async exportOmmBundle(document) {
+        const files = {};
+        if (!document) {
+            for (const element of await this.ommElements()) {
+                for (const name of [...Object.values(names), 'meta.yaml']) {
+                    const value = await this.text(`.omm/${element}/${name}`);
+                    if (value !== null)
+                        files[`${element}/${name}`] = value;
+                }
+            }
+            const config = await this.text('.omm/config.yaml');
+            if (config)
+                files['config.yaml'] = config;
+        }
+        else {
+            files['config.yaml'] = YAML.stringify({ version: '0.1.0' });
+            for (const view of document.perspectives) {
+                const elementPath = (node) => {
+                    const ids = [], visited = new Set();
+                    while (node) {
+                        if (visited.has(node.id))
+                            throw new Error('Cyclic architecture');
+                        visited.add(node.id);
+                        ids.unshift(node.id);
+                        node = view.nodes.find(parent => parent.id === node.parentId);
+                    }
+                    return [view.id, ...ids].join('/');
+                };
+                for (const item of [view, ...view.nodes]) {
+                    const node = item === view ? undefined : item, base = elementPath(node), scope = architectureScope(view, node?.id);
+                    for (const field of ARCHITECTURE_FIELDS) {
+                        const value = item[field] ?? (field === 'description' ? item.summary : undefined);
+                        if (value !== undefined && field !== 'diagram')
+                            files[`${base}/${names[field]}`] = value;
+                    }
+                    if (scope.nodes.length) {
+                        const label = (value) => value.replace(/["<>|`\\\r\n]/g, ' ');
+                        files[`${base}/diagram.mmd`] = ['graph LR', ...scope.nodes.map(child => `${child.id}["${child.references?.[0]?.perspective ? `@${child.references[0].perspective}` : label(child.title)}${child.files.length ? `\\n${child.files.map(file => file.path).join('\\n')}` : ''}"]`), ...scope.edges.map(edge => `${edge.from} -->|"${label(edge.label)}"| ${edge.to}`), ...scope.nodes.filter(child => child.role).map(child => `class ${child.id} ${child.role}`)].join('\n');
+                    }
+                    else if (item.diagram)
+                        files[`${base}/diagram.mmd`] = item.diagram;
+                    const meta = item.meta ?? { created: document.generatedAt, updated: document.generatedAt, updateCount: 0 };
+                    files[`${base}/meta.yaml`] = YAML.stringify({ created: meta.created, updated: meta.updated, update_count: meta.updateCount, git_commit: meta.gitCommit, git_branch: meta.gitBranch, prev_diagram: meta.previousDiagram });
+                }
+            }
+        }
+        if (Buffer.byteLength(JSON.stringify(files), 'utf8') > 5_000_000)
+            throw new Error('Export exceeds the architecture limit');
+        return { format: 'termdock-omm-bundle', version: 1, files };
+    }
+    async importOmmBundle(input, expectedRevision) {
+        const bundle = input;
+        if (bundle?.format !== 'termdock-omm-bundle' || bundle.version !== 1 || !bundle.files || typeof bundle.files !== 'object' || Array.isArray(bundle.files))
+            throw new Error('Invalid .omm bundle');
+        const files = Object.entries(bundle.files);
+        if (!files.length || files.length > 16_801 || Buffer.byteLength(JSON.stringify(input), 'utf8') > 5_000_000)
+            throw new Error('Invalid .omm bundle size');
+        for (const [name, value] of files) {
+            const parts = name.split('/'), filename = parts.pop();
+            if (!(name === 'config.yaml' || (parts.length > 0 && parts.length <= 12 && parts.every(safeName) && [...Object.values(names), 'meta.yaml'].includes(filename))) || typeof value !== 'string' || value.length > 100_000)
+                throw new Error(`Unsafe .omm bundle file: ${name}`);
+            await this.bounded(`.omm/${name}`);
+            if (filename?.endsWith('.yaml'))
+                YAML.parse(value, { maxAliasCount: 10 });
+        }
+        await this.locked(async () => {
+            const previous = await this.readOmm();
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before importing');
+            // Validate the merged tree in isolation before touching the project's documents.
+            await this.validateOmmMerge(Object.fromEntries(files));
+            await this.archive('.omm', previous);
+            // A bundle merges explicit files, preserving unrelated existing perspectives.
+            // Every destination is checked before the first write; no business files are touched.
+            const undo = [];
+            try {
+                for (const [name, value] of files) {
+                    undo.push([name, await this.text(`.omm/${name}`)]);
+                    await this.atomic(`.omm/${name}`, value);
+                }
+            }
+            catch (error) {
+                for (const [name, value] of undo.reverse()) {
+                    if (value === null)
+                        await fs.rm(await this.bounded(`.omm/${name}`), { force: true });
+                    else
+                        await this.atomic(`.omm/${name}`, value);
+                }
+                throw error;
+            }
+        });
+    }
+}

package/dist/server/cli.js

@@ -10,6 +10,10 @@ import { resolve } from 'path';
 // dotenv 不会覆盖已存在的环境变量，因此系统环境变量和命令行参数优先级最高
 loadDotenv({ path: resolve(os.homedir(), '.termdock', '.env'), quiet: true });
 loadDotenv({ path: resolve(process.cwd(), '.env'), quiet: true });
+if (['architecture', 'arch'].includes(process.argv[2] ?? '')) {
+    const { runArchitectureCli } = await import('./architecture/cli.js');
+    process.exit(await runArchitectureCli(process.argv.slice(3)));
+}
 // Federation commands run before normal server/terminal CLI initialization.
 if (process.argv.slice(2).some(arg => arg === '--federation-pairing' || arg === '--federation-relay')) {
     const { runFederationCli } = await import('./federation/cli.js');
@@ -199,6 +203,8 @@ Options:
   -h, --help         Show this help message
 
 Short commands:
+  architecture       Analyze, browse and edit recursive project architecture
+                     (see td architecture --help)
   agent-plugin [--json]
                      Explain how an Agent integrates itself. JSON mode is
                      machine-readable and intended for Agent consumption.
@@ -2112,7 +2118,7 @@ function runPluginInitJson() {
         collaboration: {
             capabilities: 'Optional routing hints shown beside this Agent in collaboration groups.',
             universalTransport: 'Every detected Agent receives durable inbox messages through its PTY and can use td collab when it has shell access.',
-            hooks: 'Hooks add busy/idle awareness so Termdock can defer delivery until a turn finishes; they are not required for collaboration.',
+            hooks: 'Hooks publish declared lifecycle/status events; collaboration does not wait for an idle phase and does not require hooks.',
         },
         security: {
             source: 'Only public HTTPS repository roots on approved Git hosts or explicit local paths are accepted; URL credentials are rejected.',

package/dist/server/entry.js

@@ -38,6 +38,7 @@ import { exitWithStartupFailure } from './utils/startupFailure.js';
 import { androidRecordings } from './android/recording.js';
 import { stopAllScrcpySessions } from './android/scrcpy.js';
 import filesystemRoutes from './routes/filesystem.js';
+import { architectureRoutes } from './architecture/routes.js';
 import authRoutes from './routes/auth.js';
 import notificationRoutes from './routes/notifications.js';
 import { createOnboardingRouter } from './routes/onboarding.js';
@@ -346,6 +347,7 @@ export function createApp(options = {}) {
     app.use('/api/terminal', terminalRoutes);
     // 文件系统路由（继承 /api/terminal 上的 auth + CSRF 保护）
     app.use('/api/terminal/fs', filesystemRoutes);
+    app.use('/api/terminal/architecture', architectureRoutes());
     // 本机 Android 设备桥接（adb/scrcpy）。经加密隧道时按业务 API 处理，
     // 仅全权服务授权可达；投屏 WS 在 federation runtime 中按 full-service 校验。
     app.use('/api/android', requireAuth({ bypass: isTrustedLocalCliRequest }));