@tequila99/githuman 0.11.0 → 0.12.0

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

@@ -0,0 +1,283 @@
+import { canonicalJson } from "../../shared/utils/canonical-json.js";
+import { normalizeArtifact } from "../../shared/artifacts/normalize.js";
+import { withTransaction } from "../db/transaction.js";
+import { isSqliteBusyError } from "../db/sqlite-error.js";
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { artifactBusyError, ArtifactConflictError, ArtifactIntegrityError } from "../errors/artifacts.js";
+export class ArtifactCatalogRepository {
+    onMetadata;
+    storeId;
+    db;
+    constructor(db, root, namespace) {
+        this.db = db;
+        this.storeId = this.transaction(() => {
+            const found = db
+                .prepare('SELECT id FROM artifact_stores WHERE canonical_root=? AND db_namespace=?')
+                .get(root, namespace);
+            if (found)
+                return found.id;
+            // A stopped backup keeps its identity when restored with its database.
+            const main = db.prepare('PRAGMA database_list').all().find(database => database.name === 'main');
+            if (main?.file === join(root, '.githuman', `${namespace}reviews.db`)) {
+                const stores = db
+                    .prepare('SELECT id FROM artifact_stores WHERE db_namespace=?')
+                    .all(namespace);
+                if (stores.length > 1) {
+                    throw new ArtifactConflictError('Ambiguous restored artifact store.');
+                }
+                if (stores[0])
+                    return stores[0].id;
+            }
+            const id = randomUUID();
+            db.prepare('INSERT INTO artifact_stores VALUES(?,?,?,1)').run(id, root, namespace);
+            db.prepare('INSERT INTO artifact_store_epochs VALUES(?,0)').run(id);
+            return id;
+        });
+    }
+    transaction(run) {
+        return this.runTransaction(run, 'immediate');
+    }
+    readSnapshot(run) {
+        return this.runTransaction(run, 'deferred');
+    }
+    runTransaction(run, mode) {
+        try {
+            return withTransaction(this.db, run, { mode });
+        }
+        catch (error) {
+            if (isSqliteBusyError(error)) {
+                throw artifactBusyError('Artifact database is busy. Retry the operation.');
+            }
+            throw error;
+        }
+    }
+    epoch() {
+        const row = this.db
+            .prepare('SELECT store_epoch FROM artifact_store_epochs WHERE store_id=?')
+            .get(this.storeId);
+        return row?.store_epoch ?? 0;
+    }
+    validationEpoch() {
+        return this.db
+            .prepare('SELECT COALESCE(MAX(seq),0) epoch FROM artifact_store_changes WHERE store_id=? AND validation_relevant=1')
+            .get(this.storeId).epoch;
+    }
+    get(id) {
+        const row = this.db
+            .prepare('SELECT snapshot_json FROM artifact_current WHERE store_id=? AND artifact_id=?')
+            .get(this.storeId, id);
+        return row
+            ? normalizeArtifact(JSON.parse(row.snapshot_json))
+            : undefined;
+    }
+    list(limit, after) {
+        const rows = this.db
+            .prepare(`SELECT c.snapshot_json FROM artifact_current c
+      JOIN artifacts a ON a.store_id=c.store_id AND a.id=c.artifact_id
+      WHERE c.store_id=? AND (? IS NULL OR (a.created_at,a.id)>(?,?))
+      ORDER BY a.created_at,a.id LIMIT ?`)
+            .all(this.storeId, after?.id ?? null, after?.createdAt ?? '', after?.id ?? '', limit);
+        return rows.map(row => normalizeArtifact(JSON.parse(row.snapshot_json)));
+    }
+    eventSequence() {
+        return this.db
+            .prepare('SELECT COALESCE(MAX(seq),0) seq FROM artifact_events WHERE store_id=?')
+            .get(this.storeId).seq;
+    }
+    assertExportHistory(id, snapshotSeq) {
+        const missing = this.db
+            .prepare(`SELECT e.seq FROM artifact_events e
+      LEFT JOIN artifact_metadata_versions v
+      ON v.store_id=e.store_id AND v.artifact_id=e.artifact_id AND v.version=json_extract(e.data_json,'$.afterVersion')
+      WHERE e.store_id=? AND e.artifact_id=? AND e.seq<=? AND v.version IS NULL LIMIT 1`)
+            .get(this.storeId, id, snapshotSeq);
+        if (missing) {
+            throw new ArtifactIntegrityError('Artifact history version is missing.');
+        }
+    }
+    exportHistory(id, afterSeq, snapshotSeq, limit) {
+        const rows = this.db
+            .prepare(`SELECT e.seq,e.data_json,v.snapshot_json
+      FROM artifact_events e LEFT JOIN artifact_metadata_versions v
+      ON v.store_id=e.store_id AND v.artifact_id=e.artifact_id AND v.version=json_extract(e.data_json,'$.afterVersion')
+      WHERE e.store_id=? AND e.artifact_id=? AND e.seq>? AND e.seq<=?
+      ORDER BY e.seq LIMIT ?`)
+            .all(this.storeId, id, afterSeq, snapshotSeq, limit);
+        return rows.map(row => {
+            if (row.snapshot_json === null) {
+                throw new ArtifactIntegrityError('Artifact history version is missing.');
+            }
+            return {
+                ...JSON.parse(row.data_json),
+                seq: row.seq,
+                snapshot: normalizeArtifact(JSON.parse(row.snapshot_json))
+            };
+        });
+    }
+    history(id, afterSeq, limit) {
+        const rows = this.db
+            .prepare('SELECT seq,data_json FROM artifact_events WHERE store_id=? AND artifact_id=? AND seq>? ORDER BY seq LIMIT ?')
+            .all(this.storeId, id, afterSeq, limit);
+        return rows.map(row => ({
+            ...JSON.parse(row.data_json),
+            seq: row.seq
+        }));
+    }
+    operation(requestId) {
+        const row = this.db
+            .prepare(`SELECT o.*, (SELECT state FROM artifact_operation_events e
+      WHERE e.store_id=o.store_id AND e.request_id=o.request_id ORDER BY e.seq DESC LIMIT 1) state
+      FROM artifact_operations o WHERE o.store_id=? AND o.request_id=?`)
+            .get(this.storeId, requestId);
+        return row
+            ? {
+                requestId: row.request_id,
+                kind: row.kind,
+                payloadHash: row.payload_hash,
+                artifactId: row.artifact_id,
+                data: JSON.parse(row.data_json),
+                state: row.state
+            }
+            : undefined;
+    }
+    operations(includeCommitted = true) {
+        const rows = this.db
+            .prepare(`SELECT request_id FROM artifact_operations o WHERE store_id=? AND kind=? AND (? OR (SELECT state FROM artifact_operation_events e WHERE e.store_id=o.store_id AND e.request_id=o.request_id ORDER BY e.seq DESC LIMIT 1) IN ('pending','awaiting_retry')) ORDER BY rowid`)
+            .all(this.storeId, 'create', Number(includeCommitted));
+        return rows.map(row => this.operation(row.request_id));
+    }
+    reserve(operation, now) {
+        this.db
+            .prepare('INSERT INTO artifact_operations VALUES(?,?,?,?,?,?)')
+            .run(this.storeId, operation.requestId, operation.kind, operation.payloadHash, operation.artifactId, JSON.stringify(operation.data));
+        this.transition(operation.requestId, 'pending', now);
+    }
+    transition(requestId, state, now) {
+        this.db
+            .prepare('INSERT INTO artifact_operation_events(store_id,request_id,state,created_at) VALUES(?,?,?,?)')
+            .run(this.storeId, requestId, state, now);
+    }
+    claim(requestId, owner, now, ttl) {
+        const lease = this.db
+            .prepare('SELECT owner,expires_at FROM artifact_operation_leases WHERE store_id=? AND request_id=?')
+            .get(this.storeId, requestId);
+        if (lease && lease.owner !== owner && lease.expires_at > now) {
+            throw new ArtifactConflictError('Artifact operation is in progress.');
+        }
+        this.db
+            .prepare(`INSERT INTO artifact_operation_leases VALUES(?,?,?,?)
+      ON CONFLICT(store_id,request_id) DO UPDATE SET owner=excluded.owner,expires_at=excluded.expires_at`)
+            .run(this.storeId, requestId, owner, now + ttl);
+    }
+    assertOwner(requestId, owner, now) {
+        const row = this.db
+            .prepare('SELECT owner,expires_at FROM artifact_operation_leases WHERE store_id=? AND request_id=?')
+            .get(this.storeId, requestId);
+        if (!row || row.owner !== owner || row.expires_at <= now) {
+            throw new ArtifactConflictError('Artifact operation lease expired.');
+        }
+    }
+    release(requestId, owner) {
+        this.db
+            .prepare('DELETE FROM artifact_operation_leases WHERE store_id=? AND request_id=? AND owner=?')
+            .run(this.storeId, requestId, owner);
+    }
+    insertArtifact(data) {
+        const a = data.artifact;
+        this.db
+            .prepare('INSERT INTO artifacts VALUES(?,?,?,?,?,?,?)')
+            .run(this.storeId, a.id, data.fileName, a.sha256, a.bytes, a.bodyStartLine, a.createdAt);
+    }
+    appendMetadata(artifact, requestId, actor, action) {
+        const previous = this.get(artifact.id);
+        const event = {
+            storeId: this.storeId,
+            artifactId: artifact.id,
+            requestId,
+            actor,
+            action,
+            beforeVersion: artifact.metadataVersion === 1 ? null : artifact.metadataVersion - 1,
+            afterVersion: artifact.metadataVersion,
+            createdAt: artifact.metadataUpdatedAt,
+            metadata: {
+                title: artifact.title,
+                ...(artifact.sourcePath === undefined
+                    ? {}
+                    : { sourcePath: artifact.sourcePath }),
+                tags: artifact.tags,
+                typeId: artifact.typeId,
+                taskIds: artifact.taskIds,
+                relations: artifact.relations
+            }
+        };
+        const snapshot = JSON.stringify(artifact);
+        this.db
+            .prepare('INSERT INTO artifact_metadata_versions VALUES(?,?,?,?,?)')
+            .run(this.storeId, artifact.id, artifact.metadataVersion, requestId, snapshot);
+        this.db
+            .prepare('INSERT INTO artifact_events(store_id,artifact_id,request_id,data_json) VALUES(?,?,?,?)')
+            .run(this.storeId, artifact.id, requestId, JSON.stringify(event));
+        this.db
+            .prepare(`INSERT INTO artifact_current VALUES(?,?,?,?) ON CONFLICT(store_id,artifact_id)
+      DO UPDATE SET version=excluded.version,snapshot_json=excluded.snapshot_json`)
+            .run(this.storeId, artifact.id, artifact.metadataVersion, snapshot);
+        const relevant = previous
+            ? canonicalJson([
+                previous.status,
+                previous.typeId,
+                previous.taskIds,
+                previous.relations,
+                previous.revisionOf
+            ]) !==
+                canonicalJson([
+                    artifact.status,
+                    artifact.typeId,
+                    artifact.taskIds,
+                    artifact.relations,
+                    artifact.revisionOf
+                ])
+            : artifact.status !== 'draft' ||
+                artifact.taskIds.length > 0 ||
+                artifact.relations.length > 0 ||
+                artifact.revisionOf.length > 0;
+        this.recordChange('artifact', artifact.id, requestId, relevant);
+        this.onMetadata?.(artifact);
+    }
+    recordChange(kind, id, requestId, validationRelevant = true) {
+        const inserted = this.db
+            .prepare('INSERT INTO artifact_store_changes(store_id,entity_kind,entity_id,request_id,validation_relevant) VALUES(?,?,?,?,?)')
+            .run(this.storeId, kind, id, requestId, Number(validationRelevant));
+        this.db
+            .prepare('UPDATE artifact_store_epochs SET store_epoch=? WHERE store_id=?')
+            .run(Number(inserted.lastInsertRowid), this.storeId);
+    }
+    supersededArtifactIds() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT artifact_id FROM artifact_metadata_versions
+        WHERE store_id=? AND json_extract(snapshot_json, '$.status')='superseded'`)
+            .all(this.storeId);
+        return new Set(rows.map(row => row.artifact_id));
+    }
+    all() {
+        return this.db
+            .prepare('SELECT snapshot_json FROM artifact_current WHERE store_id=? ORDER BY artifact_id')
+            .all(this.storeId).map(row => normalizeArtifact(JSON.parse(row.snapshot_json)));
+    }
+    rebuild() {
+        this.transaction(() => {
+            this.db
+                .prepare('DELETE FROM artifact_current WHERE store_id=?')
+                .run(this.storeId);
+            this.db
+                .prepare(`INSERT INTO artifact_current SELECT v.store_id,v.artifact_id,v.version,v.snapshot_json
+        FROM artifact_metadata_versions v WHERE v.store_id=? AND v.version=(SELECT MAX(n.version)
+        FROM artifact_metadata_versions n WHERE n.store_id=v.store_id AND n.artifact_id=v.artifact_id)`)
+                .run(this.storeId);
+            this.db
+                .prepare(`INSERT INTO artifact_store_epochs VALUES(?,(SELECT COALESCE(MAX(seq),0) FROM artifact_store_changes WHERE store_id=?))
+        ON CONFLICT(store_id) DO UPDATE SET store_epoch=excluded.store_epoch`)
+                .run(this.storeId, this.storeId);
+        });
+    }
+}

package/dist/server/repositories/artifact-files.repo.js

@@ -0,0 +1,181 @@
+import { constants, closeSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isSafePrefixedFilename } from "../../shared/utils/is-safe-prefixed-filename.js";
+import { isValidFilenamePrefix } from "../../shared/utils/is-valid-filename-prefix.js";
+import { MAX_ARTIFACT_BYTES } from "../../shared/artifacts/constants.js";
+import { ArtifactInputError, ArtifactIntegrityError } from "../errors/artifacts.js";
+import { hasErrorCode } from "../utils/system-error.js";
+import { sha256Hex } from "../utils/hash.js";
+import { resolveWithinRepo } from "../services/git.service.js";
+export class ArtifactFilesRepository {
+    repositoryPath;
+    root;
+    prefix;
+    constructor(repositoryPath, prefix) {
+        if (!isValidFilenamePrefix(prefix)) {
+            throw new ArtifactInputError('Invalid artifact filename prefix.');
+        }
+        this.repositoryPath = realpathSync(repositoryPath);
+        this.prefix = prefix;
+        this.root = resolveWithinRepo(this.repositoryPath, '.githuman/artifacts');
+    }
+    directory(create) {
+        for (const path of [join(this.repositoryPath, '.githuman'), this.root]) {
+            try {
+                if (create) {
+                    try {
+                        mkdirSync(path, { mode: 0o700 });
+                        this.syncDirectory(join(path, '..'));
+                    }
+                    catch (error) {
+                        if (!hasErrorCode(error, 'EEXIST'))
+                            throw error;
+                    }
+                }
+                const info = lstatSync(path);
+                if (info.isSymbolicLink() ||
+                    !info.isDirectory() ||
+                    realpathSync(path) !== path) {
+                    throw new ArtifactIntegrityError('Artifact storage directory is not a regular directory.');
+                }
+            }
+            catch (error) {
+                if (hasErrorCode(error, 'ENOENT'))
+                    return false;
+                throw error;
+            }
+        }
+        return true;
+    }
+    path(name) {
+        if (!isSafePrefixedFilename(name, this.prefix)) {
+            throw new ArtifactInputError('Invalid artifact file name.');
+        }
+        return resolveWithinRepo(this.repositoryPath, `.githuman/artifacts/${name}`);
+    }
+    read(name) {
+        if (!this.directory(false))
+            return undefined;
+        const path = this.path(name);
+        let fd;
+        try {
+            if (lstatSync(path).isSymbolicLink()) {
+                throw new ArtifactIntegrityError('Symbolic artifact files are not supported.');
+            }
+            fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            if (hasErrorCode(error, 'ELOOP')) {
+                throw new ArtifactIntegrityError('Symbolic artifact files are not supported.');
+            }
+            throw error;
+        }
+        try {
+            const stat = fstatSync(fd);
+            if (!stat.isFile() || stat.size > MAX_ARTIFACT_BYTES) {
+                throw new ArtifactIntegrityError('Artifact file has an invalid size or type.');
+            }
+            const buffer = Buffer.alloc(stat.size + 1);
+            let count = 0;
+            while (count < buffer.length) {
+                const bytes = readSync(fd, buffer, count, buffer.length - count, count);
+                if (!bytes)
+                    break;
+                count += bytes;
+            }
+            if (count !== stat.size) {
+                throw new ArtifactIntegrityError('Artifact file changed during reading.');
+            }
+            return buffer.subarray(0, count);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    verify(name, hash, bytes) {
+        const content = this.read(name);
+        if (!content || content.length !== bytes || sha256Hex(content) !== hash) {
+            throw new ArtifactIntegrityError('Artifact file is missing or its hash does not match.');
+        }
+        return content;
+    }
+    writeTemp(name, content) {
+        this.directory(true);
+        const fd = openSync(this.path(name), constants.O_WRONLY |
+            constants.O_CREAT |
+            constants.O_EXCL |
+            constants.O_NOFOLLOW, 0o600);
+        try {
+            writeFileSync(fd, content);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.syncDirectory();
+    }
+    publish(temp, name, hash, bytes) {
+        this.verify(temp, hash, bytes);
+        this.syncFile(temp);
+        try {
+            linkSync(this.path(temp), this.path(name));
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EEXIST'))
+                throw error;
+            this.verify(name, hash, bytes);
+        }
+        this.syncDirectory();
+    }
+    removeTemp(name) {
+        if (!name.endsWith('.tmp')) {
+            throw new ArtifactInputError('Only an operation temporary file may be removed.');
+        }
+        if (!this.directory(false))
+            return;
+        const path = this.path(name);
+        try {
+            if (lstatSync(path).isSymbolicLink()) {
+                throw new ArtifactIntegrityError('Symbolic artifact files are not supported.');
+            }
+            unlinkSync(path);
+            this.syncDirectory();
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+        }
+    }
+    names() {
+        return this.directory(false)
+            ? readdirSync(this.root).filter(name => name.startsWith(this.prefix))
+            : [];
+    }
+    syncFile(name) {
+        this.directory(false);
+        // Windows needs a writable handle to flush file contents.
+        const fd = openSync(this.path(name), constants.O_RDWR | constants.O_NOFOLLOW);
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        // Recovery can find a link created before the previous directory flush.
+        this.syncDirectory();
+    }
+    syncDirectory(path = this.root) {
+        // Windows does not support opening directories for fsync through this API.
+        if (process.platform === 'win32')
+            return;
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}

package/dist/server/repositories/artifact-graph.repo.js

@@ -0,0 +1,50 @@
+import { ArtifactIntegrityError } from "../errors/artifacts.js";
+export class ArtifactGraphRepository {
+    db;
+    catalog;
+    constructor(db, catalog) {
+        this.db = db;
+        this.catalog = catalog;
+    }
+    appendLineage(artifact) {
+        const parent = artifact.revisionOf?.[0];
+        if (parent) {
+            this.db
+                .prepare('INSERT INTO artifact_revision_parents VALUES(?,?,?)')
+                .run(this.catalog.storeId, artifact.id, parent);
+        }
+    }
+    ancestors(id) {
+        const result = [];
+        const visited = new Set([id]);
+        let child = id;
+        for (;;) {
+            const row = this.db
+                .prepare('SELECT parent_id FROM artifact_revision_parents WHERE store_id=? AND child_id=?')
+                .get(this.catalog.storeId, child);
+            if (!row)
+                return result;
+            if (visited.has(row.parent_id)) {
+                throw new ArtifactIntegrityError('Artifact lineage contains a cycle.');
+            }
+            visited.add(row.parent_id);
+            result.push(row.parent_id);
+            child = row.parent_id;
+        }
+    }
+    edges(id, direction, kind) {
+        return this.catalog
+            .all()
+            .flatMap(artifact => artifact.relations
+            .filter(relation => (direction === 'incoming'
+            ? relation.targetId === id
+            : artifact.id === id) &&
+            (!kind || relation.kind === kind))
+            .map(relation => ({
+            sourceId: artifact.id,
+            targetId: relation.targetId,
+            kind: relation.kind
+        })))
+            .sort((a, b) => `${a.kind}:${a.sourceId}:${a.targetId}`.localeCompare(`${b.kind}:${b.sourceId}:${b.targetId}`));
+    }
+}