@relayfile/core 0.1.0

package/dist/files.js

@@ -0,0 +1,240 @@
+/**
+ * File CRUD operations.
+ *
+ * Extract from workspace.ts:
+ *   - handleWriteFile → writeFile()
+ *   - handleReadFile → readFile()
+ *   - handleDeleteFile → deleteFile()
+ *   - normalizeIfMatchHeader → normalizeIfMatch()
+ *   - revision conflict detection
+ *   - content encoding normalization/validation
+ *   - provider inference from path
+ */
+import { normalizePath } from "./utils.js";
+import { normalizeSemantics } from "./semantics.js";
+// ---------------------------------------------------------------------------
+// Functions — agent-3: extract from workspace.ts
+// ---------------------------------------------------------------------------
+export function normalizeIfMatch(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return "";
+    }
+    if (trimmed === "*" || trimmed === "0") {
+        return trimmed;
+    }
+    const weak = trimmed.startsWith("W/") ? trimmed.slice(2).trim() : trimmed;
+    if (weak.startsWith('"') && weak.endsWith('"') && weak.length >= 2) {
+        return weak.slice(1, -1);
+    }
+    return weak;
+}
+// Re-export normalizePath so existing importers (e.g. webhooks.ts) are not broken.
+export { normalizePath };
+export function inferProvider(path) {
+    const normalized = normalizePath(path).slice(1);
+    const [provider = ""] = normalized.split("/", 1);
+    return provider.trim().toLowerCase();
+}
+export function writeFile(storage, req) {
+    if (!req.path.trim()) {
+        return { ok: false, error: "invalid_input" };
+    }
+    const path = normalizePath(req.path);
+    const ifMatch = normalizeIfMatch(req.ifMatch);
+    if (!ifMatch) {
+        return { ok: false, error: "missing_precondition" };
+    }
+    if (typeof req.content !== "string") {
+        return { ok: false, error: "invalid_input" };
+    }
+    const encoding = normalizeEncoding(req.encoding);
+    if (!encoding || !validateEncodedContent(req.content, encoding)) {
+        return { ok: false, error: "invalid_input" };
+    }
+    if (encodedSize(req.content, encoding) > MAX_FILE_BYTES) {
+        return { ok: false, error: "invalid_input" };
+    }
+    const existing = storage.getFile(path);
+    if (!existing && ifMatch !== "0" && ifMatch !== "*") {
+        return { ok: false, error: "not_found" };
+    }
+    if (existing && ifMatch !== "*" && ifMatch !== existing.revision) {
+        return {
+            ok: false,
+            error: {
+                type: "conflict",
+                expectedRevision: ifMatch,
+                currentRevision: existing.revision,
+            },
+        };
+    }
+    const revision = storage.nextRevision();
+    const now = new Date().toISOString();
+    const provider = existing?.provider || inferProvider(path);
+    const correlationId = req.correlationId ?? "";
+    const opId = storage.nextOperationId();
+    storage.putFile({
+        path,
+        revision,
+        contentType: req.contentType?.trim() || DEFAULT_CONTENT_TYPE,
+        content: req.content,
+        encoding,
+        provider,
+        lastEditedAt: now,
+        semantics: normalizeSemantics(req.semantics),
+    });
+    storage.putOperation({
+        opId,
+        path,
+        revision,
+        action: "file_upsert",
+        provider,
+        status: "pending",
+        attemptCount: 0,
+        lastError: null,
+        nextAttemptAt: null,
+        correlationId,
+    });
+    storage.appendEvent({
+        eventId: storage.nextEventId(),
+        type: existing ? "file.updated" : "file.created",
+        path,
+        revision,
+        origin: "agent_write",
+        provider,
+        correlationId,
+        timestamp: now,
+    });
+    storage.enqueueWriteback({
+        id: opId,
+        workspaceId: storage.getWorkspaceId(),
+        path,
+        revision,
+        correlationId,
+    });
+    return {
+        ok: true,
+        result: {
+            opId,
+            status: "queued",
+            targetRevision: revision,
+            writeback: {
+                provider,
+                state: "pending",
+            },
+        },
+    };
+}
+export function readFile(storage, path) {
+    if (!path.trim()) {
+        return null;
+    }
+    return storage.getFile(normalizePath(path));
+}
+export function deleteFile(storage, req) {
+    if (!req.path.trim()) {
+        return { ok: false, error: "invalid_input" };
+    }
+    const path = normalizePath(req.path);
+    const ifMatch = normalizeIfMatch(req.ifMatch);
+    if (!ifMatch) {
+        return { ok: false, error: "missing_precondition" };
+    }
+    const existing = storage.getFile(path);
+    if (!existing) {
+        return { ok: false, error: "not_found" };
+    }
+    if (ifMatch !== "*" && ifMatch !== existing.revision) {
+        return {
+            ok: false,
+            error: {
+                type: "conflict",
+                expectedRevision: ifMatch,
+                currentRevision: existing.revision,
+            },
+        };
+    }
+    const revision = storage.nextRevision();
+    const now = new Date().toISOString();
+    const correlationId = req.correlationId ?? "";
+    const opId = storage.nextOperationId();
+    storage.deleteFile(path);
+    storage.putOperation({
+        opId,
+        path,
+        revision,
+        action: "file_delete",
+        provider: existing.provider,
+        status: "pending",
+        attemptCount: 0,
+        lastError: null,
+        nextAttemptAt: null,
+        correlationId,
+    });
+    storage.appendEvent({
+        eventId: storage.nextEventId(),
+        type: "file.deleted",
+        path,
+        revision,
+        origin: "agent_write",
+        provider: existing.provider,
+        correlationId,
+        timestamp: now,
+    });
+    storage.enqueueWriteback({
+        id: opId,
+        workspaceId: storage.getWorkspaceId(),
+        path,
+        revision,
+        correlationId,
+    });
+    return {
+        ok: true,
+        result: {
+            opId,
+            status: "queued",
+            targetRevision: revision,
+            writeback: {
+                provider: existing.provider,
+                state: "pending",
+            },
+        },
+    };
+}
+export const DEFAULT_CONTENT_TYPE = "text/markdown";
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+function normalizeEncoding(value) {
+    const encoding = value?.trim().toLowerCase() ?? "";
+    if (!encoding || encoding === "utf-8" || encoding === "utf8") {
+        return "utf-8";
+    }
+    if (encoding === "base64") {
+        return "base64";
+    }
+    return null;
+}
+function validateEncodedContent(content, encoding) {
+    if (encoding !== "base64") {
+        return true;
+    }
+    try {
+        atob(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function encodedSize(content, encoding) {
+    if (encoding === "base64") {
+        try {
+            return Uint8Array.from(atob(content), (char) => char.charCodeAt(0))
+                .byteLength;
+        }
+        catch {
+            return content.length;
+        }
+    }
+    return new TextEncoder().encode(content).byteLength;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @relayfile/core — shared business logic for relayfile
+ *
+ * Pure functions. No I/O. No runtime dependencies.
+ * Storage is injected via the StorageAdapter interface.
+ */
+export type { StorageAdapter, FileRow, FileSemantics, EventRow, OperationRow, WritebackItem, EnvelopeRow, PaginationOptions, Paginated, EnvelopeQueryOptions, } from "./storage.js";
+export * from "./files.js";
+export * from "./acl.js";
+export * from "./semantics.js";
+export * from "./query.js";
+export * from "./tree.js";
+export * from "./events.js";
+export * from "./operations.js";
+export * from "./writeback.js";
+export * from "./webhooks.js";
+export * from "./export.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @relayfile/core — shared business logic for relayfile
+ *
+ * Pure functions. No I/O. No runtime dependencies.
+ * Storage is injected via the StorageAdapter interface.
+ */
+// Business logic modules (agent-3 will extract these from workspace.ts)
+export * from "./files.js";
+export * from "./acl.js";
+export * from "./semantics.js";
+export * from "./query.js";
+export * from "./tree.js";
+export * from "./events.js";
+export * from "./operations.js";
+export * from "./writeback.js";
+export * from "./webhooks.js";
+export * from "./export.js";

package/dist/operations.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Operation tracking state machine.
+ *
+ * Extract from workspace.ts:
+ *   - operation creation during writes
+ *   - status transitions: pending → running → succeeded/failed/dead_lettered
+ *   - operation listing with filters
+ *   - operation replay
+ */
+import type { StorageAdapter, OperationRow, Paginated, PaginationOptions } from "./storage.js";
+export type DispatchWriteback = (opId: string) => void;
+export declare function createOperation(storage: StorageAdapter, path: string, revision: string, action: string, provider: string, correlationId: string, dispatchWriteback?: DispatchWriteback): OperationRow;
+export declare function getOperation(storage: StorageAdapter, opId: string): OperationRow | null;
+export declare function listOperations(storage: StorageAdapter, options: PaginationOptions & {
+    status?: string;
+    action?: string;
+    provider?: string;
+}): Paginated<OperationRow>;
+export declare function acknowledgeOperation(storage: StorageAdapter, opId: string, success: boolean, errorMsg?: string): OperationRow | null;
+export declare function replayOperation(storage: StorageAdapter, opId: string, dispatchWriteback?: DispatchWriteback): OperationRow | null;

package/dist/operations.js

@@ -0,0 +1,94 @@
+/**
+ * Operation tracking state machine.
+ *
+ * Extract from workspace.ts:
+ *   - operation creation during writes
+ *   - status transitions: pending → running → succeeded/failed/dead_lettered
+ *   - operation listing with filters
+ *   - operation replay
+ */
+export function createOperation(storage, path, revision, action, provider, correlationId, dispatchWriteback) {
+    const op = {
+        opId: storage.nextOperationId(),
+        path: normalizePath(path),
+        revision,
+        action: action.trim() || "file_upsert",
+        provider: normalizeProvider(provider),
+        status: "pending",
+        attemptCount: 0,
+        lastError: null,
+        nextAttemptAt: null,
+        correlationId: correlationId || "",
+    };
+    storage.putOperation(op);
+    dispatchWriteback?.(op.opId);
+    return op;
+}
+export function getOperation(storage, opId) {
+    const normalized = opId.trim();
+    if (!normalized) {
+        return null;
+    }
+    return storage.getOperation(normalized);
+}
+export function listOperations(storage, options) {
+    const status = options.status?.trim() || undefined;
+    const action = options.action?.trim() || undefined;
+    const provider = normalizeProvider(options.provider);
+    return storage.listOperations({
+        status,
+        action,
+        provider: provider || undefined,
+        cursor: options.cursor || undefined,
+        limit: clampLimit(options.limit),
+    });
+}
+export function acknowledgeOperation(storage, opId, success, errorMsg) {
+    const op = getOperation(storage, opId);
+    if (!op) {
+        return null;
+    }
+    const updated = {
+        ...op,
+        status: success ? "succeeded" : "failed",
+        nextAttemptAt: null,
+        lastError: success ? null : normalizeError(errorMsg),
+    };
+    storage.putOperation(updated);
+    return updated;
+}
+export function replayOperation(storage, opId, dispatchWriteback) {
+    const op = getOperation(storage, opId);
+    if (!op || !isReplayableOperationStatus(op.status)) {
+        return null;
+    }
+    const updated = {
+        ...op,
+        status: "pending",
+        nextAttemptAt: null,
+        lastError: null,
+    };
+    storage.putOperation(updated);
+    dispatchWriteback?.(updated.opId);
+    return updated;
+}
+function clampLimit(limit) {
+    return Math.max(1, Math.min(limit ?? 100, 1000));
+}
+function normalizeProvider(provider) {
+    return provider?.trim().toLowerCase() ?? "";
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return "/";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : "/";
+}
+function normalizeError(errorMsg) {
+    return errorMsg?.trim() || "provider reported failure";
+}
+function isReplayableOperationStatus(status) {
+    return status === "failed" || status === "dead_lettered" || status === "canceled";
+}

package/dist/query.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File query and filtering engine.
+ *
+ * Extract from workspace.ts:
+ *   - handleQueryFiles() / queryFiles()
+ *   - property, relation, permission, comment, path prefix filters
+ *   - cursor pagination
+ */
+import type { StorageAdapter, Paginated, PaginationOptions } from "./storage.js";
+import { type TokenClaims } from "./acl.js";
+export interface QueryOptions extends PaginationOptions {
+    path?: string;
+    provider?: string;
+    properties?: Record<string, string>;
+    relation?: string;
+    permission?: string;
+    comment?: string;
+}
+export interface QueryResultItem {
+    path: string;
+    revision: string;
+    contentType: string;
+    provider: string;
+    lastEditedAt: string;
+    size: number;
+    properties?: Record<string, string>;
+    relations?: string[];
+    comments?: string[];
+}
+export declare function queryFiles(storage: StorageAdapter, options: QueryOptions, claims: TokenClaims | null): Paginated<QueryResultItem>;

package/dist/query.js

@@ -0,0 +1,138 @@
+/**
+ * File query and filtering engine.
+ *
+ * Extract from workspace.ts:
+ *   - handleQueryFiles() / queryFiles()
+ *   - property, relation, permission, comment, path prefix filters
+ *   - cursor pagination
+ */
+import { filePermissionAllows, resolveFilePermissions, } from "./acl.js";
+export function queryFiles(storage, options, claims) {
+    const base = normalizePath(options.path ?? "/");
+    const provider = normalizeProvider(options.provider);
+    const relation = options.relation?.trim() ?? "";
+    const permission = options.permission?.trim() ?? "";
+    const comment = options.comment?.trim() ?? "";
+    const limit = Math.max(1, Math.min(options.limit ?? 100, 1000));
+    const expectedProperties = normalizeProperties(options.properties);
+    const workspaceId = storage.getWorkspaceId();
+    let rows = storage
+        .listFiles()
+        .map(normalizeFileRow)
+        .filter((row) => row.path === base || isWithinBase(row.path, base))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    if (options.cursor) {
+        const index = rows.findIndex((row) => row.path === normalizePath(options.cursor ?? "/"));
+        if (index < 0) {
+            return { items: [], nextCursor: null };
+        }
+        rows = rows.slice(index + 1);
+    }
+    const items = [];
+    for (const row of rows) {
+        if (provider && normalizeProvider(row.provider) !== provider) {
+            continue;
+        }
+        const semantics = row.semantics;
+        if (relation && !stringSliceContains(semantics.relations, relation)) {
+            continue;
+        }
+        const effectivePermissions = resolveFilePermissions(storage, row.path, true);
+        if (permission && !stringSliceContainsExact(effectivePermissions, permission)) {
+            continue;
+        }
+        if (comment && !stringSliceContains(semantics.comments, comment)) {
+            continue;
+        }
+        if (!propertiesMatch(semantics.properties, expectedProperties)) {
+            continue;
+        }
+        if (!filePermissionAllows(effectivePermissions, workspaceId, claims)) {
+            continue;
+        }
+        items.push({
+            path: row.path,
+            revision: row.revision,
+            contentType: row.contentType,
+            provider: row.provider,
+            lastEditedAt: row.lastEditedAt,
+            size: encodedSize(row.content, row.encoding),
+            properties: semantics.properties,
+            relations: semantics.relations,
+            comments: semantics.comments,
+        });
+        if (items.length >= limit) {
+            break;
+        }
+    }
+    return {
+        items,
+        nextCursor: items.length >= limit ? (items[items.length - 1]?.path ?? null) : null,
+    };
+}
+function normalizeFileRow(row) {
+    return {
+        ...row,
+        path: normalizePath(row.path),
+        provider: normalizeProvider(row.provider),
+    };
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return "/";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : "/";
+}
+function normalizeProvider(provider) {
+    return provider?.trim().toLowerCase() ?? "";
+}
+function normalizeProperties(input) {
+    if (!input) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        const normalizedKey = key.trim();
+        if (!normalizedKey) {
+            continue;
+        }
+        out[normalizedKey] = String(value).trim();
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function stringSliceContains(values, needle) {
+    const normalizedNeedle = needle.trim();
+    if (!normalizedNeedle) {
+        return false;
+    }
+    return Boolean(values?.some((value) => value.trim() === normalizedNeedle));
+}
+function stringSliceContainsExact(values, needle) {
+    return stringSliceContains(values, needle);
+}
+function propertiesMatch(actual, expected) {
+    if (!expected || Object.keys(expected).length === 0) {
+        return true;
+    }
+    if (!actual) {
+        return false;
+    }
+    return Object.entries(expected).every(([key, value]) => actual[key] === value);
+}
+function isWithinBase(path, base) {
+    return base === "/" ? path.startsWith("/") : path.startsWith(`${base}/`);
+}
+function encodedSize(content, encoding) {
+    if (encoding === "base64") {
+        try {
+            return Uint8Array.from(atob(content), (char) => char.charCodeAt(0))
+                .byteLength;
+        }
+        catch {
+            return content.length;
+        }
+    }
+    return new TextEncoder().encode(content).byteLength;
+}

package/dist/semantics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Semantic metadata model.
+ *
+ * Extract from workspace.ts:
+ *   - normalizeSemantics()
+ *   - isZeroSemantics()
+ *   - semantic merge logic during file updates
+ */
+import type { FileSemantics } from "./storage.js";
+export declare function normalizeSemantics(semantics?: FileSemantics): FileSemantics;
+export declare function parseSemantics(raw?: string | null): FileSemantics;
+export declare function normalizeProperties(input?: Record<string, string>): Record<string, string> | undefined;
+export declare function normalizeStringArray(values?: string[]): string[] | undefined;
+export declare function isZeroSemantics(semantics: FileSemantics): boolean;
+export declare function mergeSemantics(existing: FileSemantics, incoming: FileSemantics): FileSemantics;

package/dist/semantics.js

@@ -0,0 +1,90 @@
+/**
+ * Semantic metadata model.
+ *
+ * Extract from workspace.ts:
+ *   - normalizeSemantics()
+ *   - isZeroSemantics()
+ *   - semantic merge logic during file updates
+ */
+const MAX_ARRAY_ENTRIES = 100;
+const MAX_PROPERTIES_ENTRIES = 100;
+export function normalizeSemantics(semantics) {
+    return {
+        properties: normalizeProperties(semantics?.properties),
+        relations: normalizeStringArray(semantics?.relations),
+        permissions: normalizeStringArray(semantics?.permissions),
+        comments: normalizeStringArray(semantics?.comments),
+    };
+}
+export function parseSemantics(raw) {
+    if (!raw) {
+        return normalizeSemantics();
+    }
+    try {
+        return normalizeSemantics(JSON.parse(raw));
+    }
+    catch {
+        return normalizeSemantics();
+    }
+}
+export function normalizeProperties(input) {
+    if (!input) {
+        return undefined;
+    }
+    const out = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(input)) {
+        if (count >= MAX_PROPERTIES_ENTRIES)
+            break;
+        const normalizedKey = key.trim();
+        if (!normalizedKey) {
+            continue;
+        }
+        out[normalizedKey] = String(value).trim();
+        count++;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export function normalizeStringArray(values) {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    const normalized = Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+    normalized.sort((a, b) => a.localeCompare(b));
+    const limited = normalized.length > MAX_ARRAY_ENTRIES
+        ? normalized.slice(0, MAX_ARRAY_ENTRIES)
+        : normalized;
+    return limited.length > 0 ? limited : undefined;
+}
+export function isZeroSemantics(semantics) {
+    const normalized = normalizeSemantics(semantics);
+    return (!normalized.properties &&
+        !normalized.relations &&
+        !normalized.permissions &&
+        !normalized.comments);
+}
+export function mergeSemantics(existing, incoming) {
+    const a = normalizeSemantics(existing);
+    const b = normalizeSemantics(incoming);
+    return {
+        properties: mergeProperties(a.properties, b.properties),
+        relations: mergeStringArrays(a.relations, b.relations),
+        permissions: mergeStringArrays(a.permissions, b.permissions),
+        comments: mergeStringArrays(a.comments, b.comments),
+    };
+}
+function mergeProperties(existing, incoming) {
+    if (!existing && !incoming)
+        return undefined;
+    if (!existing)
+        return incoming;
+    if (!incoming)
+        return existing;
+    const merged = { ...existing, ...incoming };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function mergeStringArrays(existing, incoming) {
+    if (!existing && !incoming)
+        return undefined;
+    return normalizeStringArray([...(existing ?? []), ...(incoming ?? [])]);
+}