@tequila99/githuman 0.7.0 → 0.8.0

package/README.md

@@ -203,3 +203,42 @@ MIT, см. [LICENSE](LICENSE).
 Если платформенный бинарник PTY недоступен, терминал работает в ограниченном режиме с баннером: команды вводятся в поле под выводом, Ctrl+C прерывает команду, Ctrl+D закрывает shell. `vim`, `less` и другие интерактивные программы требуют PTY. В LAN терминал отключён. Переключатель исходных цветов отключает минимальный контраст для программ со своей палитрой.
 
 Для разработки на другом порту backend можно передать `GITHUMAN_DEV_API=http://localhost:3848` при запуске Quasar dev-сервера.
+
+## Проектные заметки
+
+Раздел **Notes** хранит Markdown-заметки в `.githuman/notes/` относительно
+каталога запуска приложения. Поддерживаются папки, визуальный редактор, полный
+исходник Markdown, редактируемые свойства YAML frontmatter и обычные относительные ссылки.
+Внутренние ссылки активируют заметку в текущем окне; внешние открываются в новой вкладке.
+Кнопка **Link to note** помогает выбрать заметку для ссылки; теги со счётчиками
+в дереве фильтруют список. Изменения автоматически сохраняются после паузы ввода.
+
+Другой каталог задаётся через `serve --notes-dir ./notes` или
+`GITHUMAN_NOTES_DIR`; относительный путь считается от каталога запуска.
+Такой каталог можно версионировать. Личное хранилище по умолчанию
+исключается локально через Git `info/exclude`; уже отслеживаемые файлы
+автоматически из индекса не удаляются.
+
+При внешнем изменении файла редактор сохраняет черновик и предлагает сравнить
+его с диском, загрузить дисковую версию или сохранить черновик отдельной
+заметкой. Резервная предыдущая версия каждого изменённого файла лежит в
+скрытом каталоге `.history` внутри хранилища; этот каталог не показывается
+в дереве. При альтернативном Git-хранилище исключите `.history/` из Git,
+если резервные копии не нужно публиковать.
+
+Визуальное редактирование может нормализовать оформление списков, таблиц
+и reference-ссылок. Открытие и переключение режимов без правок файл не
+перезаписывают. Если при открытии визуальный редактор теряет конструкции,
+приложение сохраняет исходный текст и переключается в Markdown. Вставленные PNG, JPEG, GIF и WebP (до 10 МБ) сохраняются в `assets/` внутри
+хранилища заметок и доступны в визуальном редакторе после перезапуска. Ссылки
+на вложения не зависят от хоста или порта сервиса. Внешние изображения
+остаются в исходном режиме. Размер заметки ограничен 1 МБ; символические ссылки в
+пути хранилища не поддерживаются. Черновик после аварии браузера пока
+не восстанавливается.
+
+Заметки имеют UUID в SQLite-каталоге; необязательный `githuman_id` в YAML помогает
+распознавать внешние перемещения. Back/Forward и история браузера возвращают между
+заметками. Rename в контекстном меню сохраняет ID и исправляет относительные ссылки;
+дополнительное поле папки позволяет переместить элемент. Отсутствующие файлы показывают
+заглушку; неоднозначные внешние изменения и незавершённые исправления доступны в Notes.
+Markdown-ссылки остаются переносимыми. [Правила идентичности, восстановления и API](docs/notes-identity.md).

package/dist/cli/config.js

@@ -53,6 +53,7 @@ export function parseServeArgs(argv) {
             host: { type: 'string' },
             open: { type: 'boolean', default: true },
             'no-open': { type: 'boolean', default: false },
+            'notes-dir': { type: 'string' },
             'db-prefix': { type: 'string' },
             'api-docs': { type: 'boolean', default: false }
         },
@@ -63,5 +64,16 @@ export function parseServeArgs(argv) {
     const open = values['no-open'] === true ? false : values.open !== false;
     const dbPrefix = resolveDbPrefix(typeof values['db-prefix'] === 'string' ? values['db-prefix'] : undefined);
     const apiDocs = values['api-docs'] === true;
-    return { port, host, open, dbPrefix, apiDocs };
+    return {
+        port,
+        host,
+        open,
+        dbPrefix,
+        apiDocs,
+        ...(typeof values['notes-dir'] === 'string'
+            ? { notesDir: values['notes-dir'] }
+            : process.env.GITHUMAN_NOTES_DIR
+                ? { notesDir: process.env.GITHUMAN_NOTES_DIR }
+                : {})
+    };
 }

package/dist/cli/server-runtime.js

@@ -61,9 +61,12 @@ export async function startServer(options) {
     const app = buildApp({
         staticRoot: resolveStaticRoot(),
         repositoryPath,
+        projectPath: process.cwd(),
+        notesDir: options.notesDir,
         db,
         watchFiles: true,
         apiDocs: options.apiDocs === true,
+        loopbackBind: isLoopbackHost(options.host),
         terminalEnabled: isLoopbackHost(options.host),
         // Agents can run commands, so they are only offered on a loopback bind.
         ...(isLoopbackHost(options.host)

package/dist/server/app.js

@@ -1,9 +1,13 @@
+import { watchNotes } from "./services/notes-watcher.service.js";
+import { notesRoutes } from "./routes/notes.js";
+import { NotesService } from "./services/notes.service.js";
 import { NotFoundError } from "./errors/http.js";
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import Fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
+import { ajvFilePlugin } from '@fastify/multipart';
 import fastifyWebsocket from '@fastify/websocket';
 import { terminalRoutes, TERMINAL_WEBSOCKET_OPTIONS } from "./routes/terminal.js";
 import { TerminalRegistry } from "./services/terminal/registry.js";
@@ -32,14 +36,26 @@ import { watchRepository } from "./services/file-watcher.service.js";
 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- documented workaround above
 const fastifySse = fastifySseImport;
 export function buildApp(options = {}) {
-    const app = Fastify({ logger: false, forceCloseConnections: true });
+    const app = Fastify({
+        logger: false,
+        forceCloseConnections: true,
+        ajv: {
+            plugins: [
+                ajv => {
+                    ajvFilePlugin(ajv);
+                    return ajv;
+                }
+            ]
+        }
+    });
     const repositoryPath = options.repositoryPath ?? process.cwd();
     const db = options.db ?? createTestDatabase();
     const eventBus = options.eventBus ?? createEventBus();
     // Windows includes a PTY binary, but the shell and process list are Unix-only.
     const terminalEnabled = options.terminalEnabled === true && terminalSupported();
-    if (terminalEnabled)
+    if (terminalEnabled) {
         app.register(fastifyWebsocket, TERMINAL_WEBSOCKET_OPTIONS);
+    }
     app.register(fastifySse);
     // The spec collects routes as they are added, so it comes before them.
     app.register(fastifySwagger, openApiOptions());
@@ -54,6 +70,21 @@ export function buildApp(options = {}) {
             mode: terminalEnabled ? ((await loadPty()) ? 'pty' : 'pipe') : null
         })
     });
+    const projectPath = options.projectPath ?? repositoryPath;
+    const notes = new NotesService(projectPath, resolve(projectPath, options.notesDir ?? '.githuman/notes'), options.notesDir === undefined, eventBus, db);
+    app.register(notesRoutes, {
+        service: notes,
+        loopbackBind: options.loopbackBind === true
+    });
+    app.addHook('onClose', async () => {
+        await notes.identity.close();
+    });
+    if (options.watchFiles) {
+        const watcher = watchNotes(notes, () => eventBus.publish({ type: 'notes:changed' }));
+        app.addHook('onClose', async () => {
+            watcher.close();
+        });
+    }
     app.register(diffRoutes, { repositoryPath });
     app.register(gitRoutes, { repositoryPath });
     app.register(reviewRoutes, { repositoryPath, db, eventBus });
@@ -63,7 +94,7 @@ export function buildApp(options = {}) {
         eventBus,
         instanceId: options.instanceId ?? randomUUID()
     });
-    if (terminalEnabled)
+    if (terminalEnabled) {
         app.register(terminalRoutes, {
             registry: options.terminalRegistry ??
                 new TerminalRegistry({
@@ -71,6 +102,7 @@ export function buildApp(options = {}) {
                     onLifecycle: event => app.log.info({ terminal: event }, 'Terminal lifecycle')
                 })
         });
+    }
     if (options.agentPresets) {
         app.register(agentRoutes, {
             registry: createSessionRegistry({

package/dist/server/config/agents.js

@@ -1,3 +1,4 @@
+import { isSystemError } from "../utils/system-error.js";
 import { readFileSync } from 'node:fs';
 import { Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
@@ -85,7 +86,7 @@ function readOverrides(overridesPath) {
         raw = readFileSync(overridesPath, 'utf-8');
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (isSystemError(error, 'ENOENT')) {
             return {};
         }
         throw error;

package/dist/server/config/openapi.js

@@ -17,6 +17,10 @@ export function openApiOptions() {
                 { name: 'git', description: 'Repository facts, files and index.' },
                 { name: 'reviews', description: 'Reviews and their export.' },
                 { name: 'comments', description: 'Comments of reviews.' },
+                {
+                    name: 'notes',
+                    description: 'Project Markdown notes, folders and conditional saves.'
+                },
                 { name: 'events', description: 'Server-sent change events.' },
                 { name: 'app', description: 'Server version and health.' },
                 {

package/dist/server/db/migrations.js

@@ -1,5 +1,60 @@
 export function applyMigrations(db) {
     db.exec(`
+    CREATE TABLE IF NOT EXISTS note_storages (
+      id TEXT PRIMARY KEY,
+      root TEXT NOT NULL UNIQUE
+    );
+    CREATE TABLE IF NOT EXISTS note_catalog (
+      storage_id TEXT NOT NULL REFERENCES note_storages(id),
+      id TEXT NOT NULL,
+      path TEXT NOT NULL,
+      presence TEXT NOT NULL,
+      version TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      path_changed_at TEXT NOT NULL,
+      redirect_id TEXT,
+      PRIMARY KEY(storage_id, id)
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS note_current_path ON note_catalog(storage_id, path) WHERE presence = 'present' AND redirect_id IS NULL;
+    CREATE TABLE IF NOT EXISTS note_path_history (
+      storage_id TEXT NOT NULL,
+      note_id TEXT NOT NULL,
+      old_path TEXT NOT NULL,
+      new_path TEXT NOT NULL,
+      changed_at TEXT NOT NULL,
+      operation_id TEXT NOT NULL,
+      FOREIGN KEY(storage_id, note_id) REFERENCES note_catalog(storage_id, id)
+    );
+    CREATE TABLE IF NOT EXISTS note_links (
+      storage_id TEXT NOT NULL,
+      source_id TEXT NOT NULL,
+      ordinal INTEGER NOT NULL,
+      target_id TEXT,
+      data TEXT NOT NULL,
+      FOREIGN KEY(storage_id, source_id) REFERENCES note_catalog(storage_id, id),
+      FOREIGN KEY(storage_id, target_id) REFERENCES note_catalog(storage_id, id),
+      PRIMARY KEY(storage_id, source_id, ordinal)
+    );
+    CREATE INDEX IF NOT EXISTS note_link_target ON note_links(storage_id, target_id);
+    CREATE TABLE IF NOT EXISTS note_issues (
+      storage_id TEXT NOT NULL REFERENCES note_storages(id),
+      id TEXT NOT NULL,
+      note_id TEXT,
+      candidate_id TEXT,
+      data TEXT NOT NULL,
+      PRIMARY KEY(storage_id, id),
+      FOREIGN KEY(storage_id,note_id) REFERENCES note_catalog(storage_id,id),
+      FOREIGN KEY(storage_id,candidate_id) REFERENCES note_catalog(storage_id,id)
+    );
+    CREATE TABLE IF NOT EXISTS note_issue_decisions (storage_id TEXT NOT NULL REFERENCES note_storages(id), id TEXT NOT NULL, PRIMARY KEY(storage_id,id));
+    CREATE TABLE IF NOT EXISTS note_operations (
+      storage_id TEXT NOT NULL REFERENCES note_storages(id),
+      id TEXT NOT NULL,
+      data TEXT NOT NULL,
+      PRIMARY KEY(storage_id, id)
+    );
+
     CREATE TABLE IF NOT EXISTS reviews (
       id TEXT PRIMARY KEY,
       repository_path TEXT NOT NULL,

package/dist/server/errors/notes.js

@@ -0,0 +1,3 @@
+import createError from '@fastify/error';
+export const NoteConflictError = createError('GHT_NOTE_CONFLICT', 'The note changed on disk. Keep your draft and compare it with the disk version.', 409);
+export const NoteExistsError = createError('GHT_NOTE_EXISTS', 'This path already exists.', 409);

package/dist/server/hooks/notes/same-origin.js

@@ -0,0 +1,37 @@
+import { isLoopbackHost } from "../../../shared/network/loopback.js";
+import { ForbiddenError } from "../../errors/http.js";
+// Returns false on any malformed value: an invalid URL means an invalid origin.
+function isSameOrigin(host, origin) {
+    if (!host)
+        return false;
+    try {
+        return new URL(origin).host === new URL(`http://${host}`).host;
+    }
+    catch {
+        return false;
+    }
+}
+function isLoopbackRequestHost(host) {
+    if (!host)
+        return false;
+    try {
+        return isLoopbackHost(new URL(`http://${host}`).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+// A loopback bind also needs a loopback Host. A rebound hostile domain sends
+// matching Origin and Host, so the match alone does not stop DNS rebinding.
+// ADR 0008 allows LAN access without a password, so other binds skip this check.
+export function createNotesOriginHook(options) {
+    return async function requireNotesOrigin(request) {
+        const { host, origin } = request.headers;
+        if (options.loopbackBind && !isLoopbackRequestHost(host)) {
+            throw new ForbiddenError('Notes only accept requests from this local server. Open the app via localhost.');
+        }
+        if (origin && !isSameOrigin(host, origin)) {
+            throw new ForbiddenError('Notes require the same origin as this server');
+        }
+    };
+}

package/dist/server/hooks/terminal/local-origin.js

@@ -20,6 +20,7 @@ function isTerminalOrigin(host, origin) {
     }
 }
 export async function requireTerminalOrigin(request) {
-    if (!isTerminalOrigin(request.headers.host, request.headers.origin))
+    if (!isTerminalOrigin(request.headers.host, request.headers.origin)) {
         throw new ForbiddenError('Terminal endpoints only accept requests from this local server. Open the app via localhost.');
+    }
 }

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

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+function toNote(row) {
+    return {
+        id: row.id,
+        path: row.path,
+        presence: row.presence,
+        version: row.version,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        redirectId: row.redirect_id
+    };
+}
+export class NotesCatalogRepository {
+    storageId;
+    db;
+    constructor(db, root) {
+        this.db = db;
+        const row = db
+            .prepare('SELECT id FROM note_storages WHERE root = ?')
+            .get(root);
+        this.storageId = row?.id ?? randomUUID();
+        if (!row) {
+            db.prepare('INSERT INTO note_storages(id,root) VALUES(?,?)').run(this.storageId, root);
+        }
+    }
+    transaction(run) {
+        this.db.exec('SAVEPOINT notes_catalog');
+        try {
+            const value = run();
+            this.db.exec('RELEASE notes_catalog');
+            return value;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK TO notes_catalog; RELEASE notes_catalog');
+            throw error;
+        }
+    }
+    all() {
+        return this.db
+            .prepare('SELECT * FROM note_catalog WHERE storage_id = ? ORDER BY path, id')
+            .all(this.storageId).map(toNote);
+    }
+    get(id) {
+        const row = this.db
+            .prepare('SELECT * FROM note_catalog WHERE storage_id = ? AND id = ?')
+            .get(this.storageId, id);
+        return row ? toNote(row) : undefined;
+    }
+    put(note) {
+        this.db
+            .prepare(`INSERT INTO note_catalog(storage_id,id,path,presence,version,created_at,updated_at,path_changed_at,redirect_id) VALUES(?,?,?,?,?,?,?,?,?)
+      ON CONFLICT(storage_id,id) DO UPDATE SET path=excluded.path,presence=excluded.presence,version=excluded.version,updated_at=excluded.updated_at,path_changed_at=CASE WHEN note_catalog.path != excluded.path THEN strftime('%Y-%m-%dT%H:%M:%fZ','now') ELSE note_catalog.path_changed_at END,redirect_id=excluded.redirect_id`)
+            .run(this.storageId, note.id, note.path, note.presence, note.version, note.createdAt, note.updatedAt, note.updatedAt, note.redirectId);
+    }
+    links(id) {
+        const rows = this.db
+            .prepare('SELECT data FROM note_links WHERE storage_id = ? AND source_id = ? ORDER BY ordinal')
+            .all(this.storageId, id);
+        return rows.map(row => JSON.parse(row.data));
+    }
+    setLinks(id, links) {
+        this.transaction(() => {
+            this.db
+                .prepare('DELETE FROM note_links WHERE storage_id = ? AND source_id = ?')
+                .run(this.storageId, id);
+            const stmt = this.db.prepare('INSERT INTO note_links(storage_id,source_id,ordinal,target_id,data) VALUES(?,?,?,?,?)');
+            links.forEach((link, ordinal) => stmt.run(this.storageId, id, ordinal, link.targetId, JSON.stringify(link)));
+        });
+    }
+    history(id, from, to, operationId) {
+        this.db
+            .prepare('INSERT INTO note_path_history VALUES(?,?,?,?,?,?)')
+            .run(this.storageId, id, from, to, new Date().toISOString(), operationId);
+    }
+    historical(path) {
+        const rows = this.db
+            .prepare('SELECT DISTINCT note_id FROM note_path_history WHERE storage_id = ? AND old_path = ?')
+            .all(this.storageId, path);
+        return rows.map(row => row.note_id);
+    }
+    issues() {
+        const rows = this.db
+            .prepare('SELECT data FROM note_issues WHERE storage_id = ? ORDER BY id')
+            .all(this.storageId);
+        return rows.map(row => JSON.parse(row.data));
+    }
+    issue(issue) {
+        if (this.db
+            .prepare('SELECT 1 FROM note_issue_decisions WHERE storage_id = ? AND id = ?')
+            .get(this.storageId, issue.id)) {
+            return;
+        }
+        this.db
+            .prepare('INSERT OR REPLACE INTO note_issues(storage_id,id,note_id,candidate_id,data) VALUES(?,?,?,?,?)')
+            .run(this.storageId, issue.id, issue.noteId, issue.candidateId, JSON.stringify(issue));
+    }
+    reopen(id) {
+        this.db
+            .prepare('DELETE FROM note_issue_decisions WHERE storage_id = ? AND id = ?')
+            .run(this.storageId, id);
+    }
+    dismiss(id, permanent = false) {
+        if (permanent) {
+            this.db
+                .prepare('INSERT OR IGNORE INTO note_issue_decisions VALUES(?,?)')
+                .run(this.storageId, id);
+        }
+        this.db
+            .prepare('DELETE FROM note_issues WHERE storage_id = ? AND id = ?')
+            .run(this.storageId, id);
+    }
+    operations() {
+        const rows = this.db
+            .prepare('SELECT data FROM note_operations WHERE storage_id = ? ORDER BY rowid')
+            .all(this.storageId);
+        return rows.map(row => JSON.parse(row.data));
+    }
+    operation(operation) {
+        this.db
+            .prepare('INSERT OR REPLACE INTO note_operations VALUES(?,?,?)')
+            .run(this.storageId, operation.id, JSON.stringify(operation));
+    }
+    finishOperation(id) {
+        this.db
+            .prepare('DELETE FROM note_operations WHERE storage_id = ? AND id = ?')
+            .run(this.storageId, id);
+    }
+}