@tequila99/githuman 0.7.0 → 0.9.0

package/dist/server/repositories/notes.repo.js

@@ -0,0 +1,444 @@
+import { noteChildPath, noteParentPath } from "../../shared/notes/note-path.js";
+import { constants } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, link, mkdir, open, readdir, realpath, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { BadRequestError, NotFoundError } from "../errors/http.js";
+import { isSystemError } from "../utils/system-error.js";
+import { sha256Hex } from "../utils/hash.js";
+import { NoteConflictError, NoteExistsError } from "../errors/notes.js";
+import { noteAssetFormat } from "../../shared/notes/asset-formats.js";
+// Bound file reads before allocating document buffers.
+const MAX_BYTES = 1000000;
+export class NotesRepository {
+    root;
+    writes = new Map();
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    async path(path, markdown = true) {
+        if (!path ||
+            path.includes('\\') ||
+            path.includes('\0') ||
+            path.startsWith('/') ||
+            path
+                .split('/')
+                .some(part => !part || part === '.' || part === '..' || part.startsWith('.')) ||
+            (markdown && !path.toLowerCase().endsWith('.md'))) {
+            throw new BadRequestError('Invalid note path');
+        }
+        const target = resolve(this.root, path);
+        if (!target.startsWith(this.root + sep)) {
+            throw new BadRequestError('Path leaves the notes folder');
+        }
+        // Reject links inside the notes folder. The configured root and its parents may be links.
+        let current = this.root;
+        for (const part of target
+            .slice(this.root.length)
+            .split(sep)
+            .filter(Boolean)) {
+            current = join(current, part);
+            try {
+                if ((await lstat(current)).isSymbolicLink()) {
+                    throw new BadRequestError('Symbolic links are not supported in the notes path');
+                }
+            }
+            catch (error) {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        return target;
+    }
+    async read(path) {
+        const target = await this.path(path);
+        try {
+            const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile() || stat.size > MAX_BYTES) {
+                    throw new BadRequestError('Note must be a Markdown file under 1 MB');
+                }
+                const bytes = await file.readFile();
+                if (bytes.byteLength > MAX_BYTES) {
+                    throw new BadRequestError('Note exceeds 1 MB');
+                }
+                let text;
+                try {
+                    text = new TextDecoder('utf-8', {
+                        fatal: true,
+                        ignoreBOM: true
+                    }).decode(bytes);
+                }
+                catch {
+                    throw new BadRequestError('Note is not valid UTF-8');
+                }
+                return { path, text, version: sha256Hex(text) };
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT')) {
+                throw new NotFoundError('Note not found');
+            }
+            throw error;
+        }
+    }
+    async list() {
+        const result = [];
+        await this.path('probe.md');
+        const walk = async (dir, prefix) => {
+            const entries = (await readdir(dir, { withFileTypes: true })).filter(entry => !entry.name.startsWith('.') &&
+                !entry.isSymbolicLink() &&
+                entry.name !== 'node_modules' &&
+                (prefix || entry.name !== 'assets'));
+            for (const entry of entries.filter(item => item.isDirectory())) {
+                const path = prefix + entry.name;
+                await this.path(path, false);
+                result.push({ path, folder: true, signature: 'folder' });
+                await walk(join(dir, entry.name), path + '/');
+            }
+            const files = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith('.md'));
+            // Bound concurrent metadata reads while retaining path checks for each file.
+            for (let offset = 0; offset < files.length; offset += 16) {
+                const batch = await Promise.allSettled(files.slice(offset, offset + 16).map(async (entry) => {
+                    const path = prefix + entry.name;
+                    const target = await this.path(path);
+                    const stat = await lstat(target, { bigint: true });
+                    return {
+                        path,
+                        folder: false,
+                        signature: `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`
+                    };
+                }));
+                for (const item of batch) {
+                    if (item.status === 'rejected')
+                        throw item.reason;
+                    result.push(item.value);
+                }
+            }
+        };
+        await walk(this.root, '');
+        return result.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async serial(path, run) {
+        const prior = this.writes.get(path) ?? Promise.resolve();
+        const next = prior.catch(() => { }).then(run);
+        this.writes.set(path, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.writes.get(path) === next)
+                this.writes.delete(path);
+        }
+    }
+    async save(path, text, expected) {
+        return this.serial(path, async () => {
+            if (Buffer.byteLength(text) > MAX_BYTES) {
+                throw new BadRequestError('Note exceeds 1 MB');
+            }
+            const target = await this.path(path);
+            await mkdir(dirname(target), { recursive: true });
+            await this.path(path);
+            let current;
+            if (expected !== undefined) {
+                try {
+                    current = await this.read(path);
+                }
+                catch (error) {
+                    if (error instanceof NotFoundError)
+                        throw new NoteConflictError();
+                    throw error;
+                }
+                if (current.version !== expected)
+                    throw new NoteConflictError();
+                if (current.text === text)
+                    return current;
+                // Retain one previous version per note, without accumulating autosave history.
+                const backups = join(this.root, '.history');
+                await mkdir(backups, { recursive: true });
+                if ((await lstat(backups)).isSymbolicLink() ||
+                    !(await realpath(backups)).startsWith((await realpath(this.root)) + sep)) {
+                    throw new BadRequestError('Invalid backup folder');
+                }
+                const backupTemp = join(backups, '.backup-' + randomUUID());
+                try {
+                    await writeFile(backupTemp, current.text, { flag: 'wx', mode: 0o600 });
+                    await rename(backupTemp, join(backups, sha256Hex(path) + '.md'));
+                }
+                finally {
+                    await unlink(backupTemp).catch(error => {
+                        if (!isSystemError(error, 'ENOENT'))
+                            throw error;
+                    });
+                }
+            }
+            const temporary = join(dirname(target), '.note-' + randomUUID());
+            try {
+                const file = await open(temporary, 'wx', 0o600);
+                try {
+                    await file.writeFile(text);
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await this.path(path);
+                if (expected === undefined) {
+                    try {
+                        await link(temporary, target);
+                    }
+                    catch (error) {
+                        if (isSystemError(error, 'EEXIST'))
+                            throw new NoteExistsError();
+                        throw error;
+                    }
+                }
+                else {
+                    if ((await this.read(path)).version !== expected) {
+                        throw new NoteConflictError();
+                    }
+                    await rename(temporary, target);
+                }
+            }
+            finally {
+                await unlink(temporary).catch(error => {
+                    if (!isSystemError(error, 'ENOENT'))
+                        throw error;
+                });
+            }
+            return { path, text, version: sha256Hex(text) };
+        });
+    }
+    async saveAsset(bytes, extension) {
+        const staged = await this.stageAsset((async function* () {
+            yield bytes;
+        })(), extension, new AbortController().signal);
+        try {
+            return await staged.commit();
+        }
+        finally {
+            await staged.dispose();
+        }
+    }
+    async stageAsset(chunks, extension, signal) {
+        const format = noteAssetFormat(extension);
+        if (!format)
+            throw new BadRequestError('Unsupported attachment format');
+        const probe = await this.path('assets/probe.png', false);
+        await mkdir(dirname(probe), { recursive: true });
+        await this.path('assets/probe.png', false);
+        const temporary = join(dirname(probe), '.asset-' + randomUUID());
+        const dispose = async () => {
+            await unlink(temporary).catch(error => {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            });
+        };
+        try {
+            const file = await open(temporary, 'wx', 0o600);
+            const hash = createHash('sha256');
+            let bytes = 0;
+            try {
+                for await (const chunk of chunks) {
+                    signal.throwIfAborted();
+                    bytes += chunk.length;
+                    if (bytes > format.maxBytes) {
+                        throw new BadRequestError('Attachment exceeds its size limit');
+                    }
+                    hash.update(chunk);
+                    await file.writeFile(chunk);
+                }
+                if (!bytes)
+                    throw new BadRequestError('Empty attachment');
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            const id = hash.digest('hex') + '.' + extension;
+            return {
+                dispose,
+                commit: async () => {
+                    signal.throwIfAborted();
+                    const target = await this.path('assets/' + id, false);
+                    try {
+                        await link(temporary, target);
+                    }
+                    catch (error) {
+                        if (!isSystemError(error, 'EEXIST'))
+                            throw error;
+                    }
+                    return id;
+                }
+            };
+        }
+        catch (error) {
+            await dispose();
+            throw error;
+        }
+    }
+    async readAsset(id) {
+        const target = await this.path('assets/' + id, false);
+        try {
+            const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                const format = noteAssetFormat(id.split('.').at(-1));
+                if (!format ||
+                    !stat.isFile() ||
+                    !stat.size ||
+                    stat.size > format.maxBytes) {
+                    throw new BadRequestError('Invalid attachment');
+                }
+                return file.createReadStream({ autoClose: true, end: stat.size - 1 });
+            }
+            catch (error) {
+                await file.close();
+                throw error;
+            }
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT')) {
+                throw new NotFoundError('Attachment not found');
+            }
+            throw error;
+        }
+    }
+    async sameEntry(path, other) {
+        const a = await lstat(await this.path(path, false));
+        const b = await lstat(await this.path(other, false));
+        return a.dev === b.dev && a.ino === b.ino;
+    }
+    async exactEntry(path) {
+        const target = await this.path(path, false);
+        try {
+            return (await readdir(dirname(target))).includes(basename(target));
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT'))
+                return false;
+            throw error;
+        }
+    }
+    async exists(path) {
+        const target = await this.path(path, false);
+        try {
+            await lstat(target);
+            return true;
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT'))
+                return false;
+            throw error;
+        }
+    }
+    async moveEntry(path, destination, folder) {
+        const source = await this.path(path, !folder);
+        const target = await this.path(destination, !folder);
+        if (destination.split('/')[0] === 'assets' ||
+            path.split('/')[0] === 'assets') {
+            throw new BadRequestError('Cannot move attachments');
+        }
+        if (folder && destination.startsWith(path + '/')) {
+            throw new BadRequestError('Cannot move a folder into itself');
+        }
+        if (path === destination)
+            return;
+        if (await this.exists(destination))
+            throw new NoteExistsError();
+        const stat = await lstat(source);
+        if (folder ? !stat.isDirectory() : !stat.isFile()) {
+            throw new BadRequestError('Entry type changed');
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await this.path(destination, !folder);
+        if (folder) {
+            await rename(source, target);
+        }
+        else {
+            try {
+                await link(source, target);
+            }
+            catch (error) {
+                if (isSystemError(error, 'EEXIST'))
+                    throw new NoteExistsError();
+                throw error;
+            }
+            await unlink(source);
+        }
+    }
+    async renameEntry(path, name, folder) {
+        return this.serial('rename', async () => {
+            if (!name.trim() ||
+                name !== name.trim() ||
+                /[/\\\0]/.test(name) ||
+                name.startsWith('.')) {
+                throw new BadRequestError('Invalid entry name');
+            }
+            if (path.split('/')[0] === 'assets') {
+                throw new BadRequestError('Cannot rename attachments');
+            }
+            const targetPath = noteChildPath(noteParentPath(path), name);
+            if (targetPath.split('/')[0] === 'assets') {
+                throw new BadRequestError('Reserved folder name');
+            }
+            const source = await this.path(path, !folder);
+            const target = await this.path(targetPath, !folder);
+            let stat;
+            try {
+                stat = await lstat(source);
+            }
+            catch (error) {
+                if (isSystemError(error, 'ENOENT')) {
+                    throw new NotFoundError('Note entry not found');
+                }
+                throw error;
+            }
+            if (folder ? !stat.isDirectory() : !stat.isFile()) {
+                throw new BadRequestError('Entry type changed');
+            }
+            if (path === targetPath)
+                return targetPath;
+            try {
+                await lstat(target);
+                throw new NoteExistsError();
+            }
+            catch (error) {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            }
+            if (folder) {
+                await rename(source, target);
+            }
+            else {
+                try {
+                    await link(source, target);
+                }
+                catch (error) {
+                    if (isSystemError(error, 'EEXIST'))
+                        throw new NoteExistsError();
+                    throw error;
+                }
+                await unlink(source);
+            }
+            return targetPath;
+        });
+    }
+    async folder(path) {
+        const target = await this.path(path, false);
+        await mkdir(dirname(target), { recursive: true });
+        await this.path(path, false);
+        try {
+            await mkdir(target);
+        }
+        catch (error) {
+            if (isSystemError(error, 'EEXIST'))
+                throw new NoteExistsError();
+            throw error;
+        }
+    }
+}

package/dist/server/routes/agent.js

@@ -124,6 +124,7 @@ export async function agentRoutes(app, opts) {
         }
         session.assertCanPrompt();
         const blocks = await buildPromptBlocks(request.body, {
+            notes: opts.notes,
             db,
             repositoryPath,
             embeddedContext: session.supportsEmbeddedContext,

package/dist/server/routes/notes.js

@@ -0,0 +1,213 @@
+import { NotesExternalAssetsService } from "../services/notes-external-assets.service.js";
+import { InspectExternalAssetBody, PreviewExternalAssetBody, ImportExternalAssetBody, ExternalAssetInspectionSchema, ExternalAssetResultSchema } from "../../shared/notes/schemas.js";
+import multipart from '@fastify/multipart';
+import { MAX_NOTE_ASSET_BYTES } from "../../shared/notes/constants.js";
+import { noteAssetFormat } from "../../shared/notes/asset-formats.js";
+import { NoteRecordSchema, NoteIdQuery, NoteDescriptorSchema, NoteResolveBody, NoteResolutionSchema, NoteGraphSchema, ResolveIdentityBody, NoteMutationSchema, UploadNoteAssetBody, NoteAssetSchema, NoteAssetContentSchema, NoteAssetParams, NoteQuery, NoteSchema, NotesIndexSchema, CreateNoteBody, SaveNoteBody, RenameNoteBody, CreateFolderBody } from "../../shared/notes/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+import { BadRequestError } from "../errors/http.js";
+import { withRequestSignal } from "../utils/request-abort.js";
+import { createNotesOriginHook } from "../hooks/notes/same-origin.js";
+export async function notesRoutes(app, { service, loopbackBind = false, externalAssets = new NotesExternalAssetsService() }) {
+    await app.register(multipart, {
+        attachFieldsToBody: true,
+        limits: { fileSize: MAX_NOTE_ASSET_BYTES, files: 1, fields: 0, parts: 1 }
+    });
+    const typed = app.withTypeProvider();
+    app.addHook('onRequest', createNotesOriginHook({ loopbackBind }));
+    app.post('/api/notes/assets', {
+        preValidation: async (request) => {
+            if (!request.isMultipart()) {
+                throw new BadRequestError('Expected multipart/form-data');
+            }
+        },
+        schema: {
+            consumes: ['multipart/form-data'],
+            tags: ['notes'],
+            summary: 'Store a note image',
+            // The multipart validator rewrites file schemas during compilation.
+            body: structuredClone(UploadNoteAssetBody),
+            response: { 201: NoteAssetSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const asset = await service.uploadAsset(await request.body.file.toBuffer());
+        reply.code(201);
+        return asset;
+    });
+    typed.post('/api/notes/assets/inspect', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Inspect an external attachment',
+            body: InspectExternalAssetBody,
+            response: { 200: ExternalAssetInspectionSchema, ...ERROR_RESPONSES }
+        }
+    }, (request, reply) => withRequestSignal(reply, signal => externalAssets.inspect(request.body.url, signal)));
+    typed.post('/api/notes/assets/import', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Import an external attachment',
+            body: ImportExternalAssetBody,
+            response: { 200: ExternalAssetResultSchema, ...ERROR_RESPONSES }
+        }
+    }, (request, reply) => withRequestSignal(reply, signal => externalAssets.importAsset(request.body, signal, (chunks, extension, saveSignal) => service.importAsset(chunks, extension, saveSignal))));
+    // The typed provider rejects a binary payload for the content schema.
+    app.post('/api/notes/assets/preview', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Preview an external image',
+            body: PreviewExternalAssetBody,
+            response: { 200: NoteAssetContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const preview = await withRequestSignal(reply, signal => externalAssets.preview(request.body.url, signal));
+        reply
+            .header('Cache-Control', 'no-store')
+            .header('X-Content-Type-Options', 'nosniff')
+            .type(preview.mime);
+        return reply.send(preview.body);
+    });
+    app.get('/api/notes/assets/:id', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a stored note attachment',
+            params: NoteAssetParams,
+            response: { 200: NoteAssetContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const image = await service.readAsset(request.params.id);
+        const extension = request.params.id.split('.').at(-1);
+        const format = noteAssetFormat(extension);
+        if (!format)
+            throw new BadRequestError('Unsupported attachment format');
+        reply.type(format.mime);
+        reply.header('X-Content-Type-Options', 'nosniff');
+        return reply.send(image);
+    });
+    typed.get('/api/notes', {
+        schema: {
+            tags: ['notes'],
+            summary: 'List project notes',
+            response: { 200: NotesIndexSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.index());
+    typed.get('/api/notes/path', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve a current or historical note path',
+            querystring: NoteQuery,
+            response: { 200: NoteRecordSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.resolvePath(request.query.path));
+    typed.get('/api/notes/identity', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a stable note identity and backlinks',
+            querystring: NoteIdQuery,
+            response: { 200: NoteDescriptorSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.descriptor(request.query.id, request.query.storageId));
+    typed.get('/api/notes/by-id', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a note by stable identity',
+            querystring: NoteIdQuery,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.readId(request.query.id, request.query.storageId));
+    typed.get('/api/notes/graph', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read the graph of note relationships',
+            response: { 200: NoteGraphSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.identity.graph());
+    typed.post('/api/notes/resolve', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve an occurrence in the current note source',
+            body: NoteResolveBody,
+            response: { 200: NoteResolutionSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.resolve(request.body.sourceId, request.body.storageId, request.body.text, request.body.href, request.body.occurrence));
+    typed.post('/api/notes/identity/resolve', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve a restored or moved file identity',
+            body: ResolveIdentityBody,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        await service.identity.resolveIdentity(request.body.issueId, request.body.restore, request.body.candidateId);
+        reply.code(204).send(null);
+    });
+    typed.post('/api/notes/repair', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Retry pending link repairs',
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (_request, reply) => {
+        await service.identity.retry();
+        reply.code(204).send(null);
+    });
+    typed.get('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a note',
+            querystring: NoteQuery,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.read(request.query.path));
+    typed.post('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Create a note',
+            body: CreateNoteBody,
+            response: { 201: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const note = await service.save(request.body.path, request.body.text);
+        reply.code(201);
+        return note;
+    });
+    typed.patch('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Save a note if its version matches',
+            body: SaveNoteBody,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.save(request.body.path, request.body.text, request.body.version, request.body.id, request.body.storageId));
+    typed.post('/api/notes/delete', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Hide a note without removing its file',
+            body: NoteIdQuery,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        await service.delete(request.body.id, request.body.storageId);
+        reply.code(204).send(null);
+    });
+    typed.post('/api/notes/rename', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Rename a note or folder',
+            body: RenameNoteBody,
+            response: { 200: NoteMutationSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
+        return service.rename(request.body.path, request.body.name, request.body.folder, request.body.target, request.body.id, request.body.revision);
+    });
+    typed.post('/api/notes/folder', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Create a notes folder',
+            body: CreateFolderBody,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        await service.folder(request.body.path);
+        reply.code(204).send(null);
+    });
+}

package/dist/server/routes/terminal.js

@@ -45,8 +45,9 @@ export async function terminalRoutes(app, options) {
         },
         onRequest: requireTerminalOrigin,
         preValidation: async (request) => {
-            if (!tokens.consume(request.query.token, request.headers.origin ?? ''))
+            if (!tokens.consume(request.query.token, request.headers.origin ?? '')) {
                 throw new ForbiddenError('Terminal connection token is invalid or expired.');
+            }
         }
     }, socket => {
         const connection = attachTerminalSocket(socket, options.registry, {