@relayfile/relay-helpers 0.4.6 → 0.4.8

package/dist/receipt.js

@@ -1,12 +1,103 @@
-/**
- * Normalize the writeback receipt into the `{ id, url }` shape the old typed
- * clients returned. Falls back to the draft path when the worker hasn't
- * written a receipt yet (fire-and-forget / timeout).
- */
+import { RelayfileWritebackPendingError, RelayfileWritebackTerminalError, } from '@relayfile/adapter-core/vfs-client';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function receiptIdentifier(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return String(value);
+    }
+    return nonEmptyString(value);
+}
+function hasReceiptEvidence(receipt) {
+    return (receiptIdentifier(receipt.created) !== undefined ||
+        receiptIdentifier(receipt.id) !== undefined ||
+        receiptIdentifier(receipt.externalId) !== undefined ||
+        receiptIdentifier(receipt.identifier) !== undefined ||
+        nonEmptyString(receipt.path) !== undefined ||
+        nonEmptyString(receipt.url) !== undefined ||
+        receiptIdentifier(receipt.ts) !== undefined ||
+        typeof receipt.merged === 'boolean' ||
+        nonEmptyString(receipt.merged) !== undefined ||
+        receiptIdentifier(receipt.sha) !== undefined ||
+        receipt.ok === true);
+}
+function createdFromError(error) {
+    if (error instanceof RelayfileWritebackPendingError) {
+        return { status: 'pending', id: error.path, url: '', path: error.path };
+    }
+    if (error instanceof RelayfileWritebackTerminalError) {
+        const path = nonEmptyString(error.path);
+        if (!path) {
+            throw error;
+        }
+        return {
+            status: 'dropped',
+            id: path,
+            url: '',
+            path,
+            reason: error.cause instanceof Error ? error.cause.message : `writeback_${error.status}`,
+        };
+    }
+    throw error;
+}
+function isPromiseLike(value) {
+    return isRecord(value) && typeof value.then === 'function';
+}
 export function created(result) {
+    if (isPromiseLike(result)) {
+        return Promise.resolve(result).then(created).catch(createdFromError);
+    }
+    if (!isRecord(result)) {
+        throw new TypeError('created() expected a writeback result object');
+    }
+    const path = nonEmptyString(result.path);
+    if (!path) {
+        throw new TypeError('created() expected a non-empty writeback result path');
+    }
+    const receipt = result.receipt;
+    if (receipt !== undefined && !isRecord(receipt)) {
+        throw new TypeError('created() expected receipt to be an object when present');
+    }
+    const status = result.deliveryStatus ?? (receipt ? 'confirmed' : 'pending');
+    if (status !== 'confirmed' && status !== 'pending' && status !== 'dropped') {
+        throw new TypeError(`created() received unknown writeback status "${String(status)}"`);
+    }
+    if (status === 'confirmed') {
+        if (!receipt) {
+            throw new TypeError('created() received confirmed status without a receipt');
+        }
+        if (!hasReceiptEvidence(receipt)) {
+            throw new TypeError('created() received a confirmed receipt without delivery evidence');
+        }
+        return {
+            status,
+            id: receiptIdentifier(receipt.created) ??
+                receiptIdentifier(receipt.id) ??
+                receiptIdentifier(receipt.externalId) ??
+                receiptIdentifier(receipt.identifier) ??
+                receiptIdentifier(receipt.sha) ??
+                receiptIdentifier(receipt.ts) ??
+                path,
+            url: nonEmptyString(receipt.url) ?? '',
+            path,
+            receipt,
+        };
+    }
+    if (status === 'pending') {
+        if (receipt) {
+            throw new TypeError('created() received pending status with a receipt');
+        }
+        return { status, id: path, url: '', path };
+    }
     return {
-        id: result.receipt?.created ?? result.receipt?.id ?? result.path,
-        url: result.receipt?.url ?? result.path
+        status,
+        id: path,
+        url: '',
+        path,
+        ...(receipt ? { receipt } : {}),
     };
 }
 //# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

@@ -1 +1 @@
-{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,MAAuB;IAC7C,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,MAAM,CAAC,IAAI;QAChE,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,MAAM,CAAC,IAAI;KACxC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"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"}

package/dist/receipt.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=receipt.test.d.ts.map

package/dist/receipt.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.test.d.ts","sourceRoot":"","sources":["../src/receipt.test.ts"],"names":[],"mappings":""}

package/dist/receipt.test.js

@@ -0,0 +1,301 @@
+import assert from 'node:assert/strict';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import nodePath from 'node:path';
+import test from 'node:test';
+import { RelayfileWritebackAdmissionTimeoutError, RelayfileWritebackTerminalError, } from '@relayfile/adapter-core/vfs-client';
+import { created, githubClient, linearClient, PreviewTransport, providerClient, } from './index.js';
+const issueCommentsPath = providerClient('github')['issue-comments'].path({
+    owner: 'o',
+    repo: 'r',
+    issueNumber: 1,
+});
+const path = `${issueCommentsPath}/issue-comments draft.json`;
+test('created preserves confirmed receipts and never substitutes a path for url', () => {
+    assert.deepEqual(created({
+        path,
+        absolutePath: path,
+        deliveryStatus: 'confirmed',
+        receipt: { created: 'comment-123', url: 'https://github.example/comments/123' },
+    }), {
+        status: 'confirmed',
+        id: 'comment-123',
+        url: 'https://github.example/comments/123',
+        path,
+        receipt: { created: 'comment-123', url: 'https://github.example/comments/123' },
+    });
+    const withoutUrl = created({
+        path,
+        absolutePath: path,
+        deliveryStatus: 'confirmed',
+        receipt: { externalId: 'comment-456' },
+    });
+    assert.equal(withoutUrl.status, 'confirmed');
+    assert.equal(withoutUrl.id, 'comment-456');
+    assert.equal(withoutUrl.url, '');
+    assert.notEqual(withoutUrl.url, path);
+});
+test('created infers confirmed for legacy transports that return a receipt', () => {
+    const result = created({
+        path,
+        absolutePath: path,
+        receipt: { id: 'legacy-123', url: 'https://linear.example/legacy-123' },
+    });
+    assert.equal(result.status, 'confirmed');
+    assert.equal(result.id, 'legacy-123');
+    assert.equal(result.url, 'https://linear.example/legacy-123');
+});
+test('created normalizes runtime numeric ids and uses sha or ts as primary receipt identifiers', () => {
+    const numeric = created({
+        path,
+        absolutePath: path,
+        deliveryStatus: 'confirmed',
+        receipt: { id: 123 },
+    });
+    assert.equal(numeric.status, 'confirmed');
+    assert.equal(numeric.id, '123');
+    for (const [receipt, expected] of [
+        [{ sha: 'commit-abc123' }, 'commit-abc123'],
+        [{ ts: '1781870464.800039' }, '1781870464.800039'],
+    ]) {
+        const result = created({ path, absolutePath: path, deliveryStatus: 'confirmed', receipt });
+        assert.equal(result.status, 'confirmed');
+        assert.equal(result.id, expected);
+        assert.notEqual(result.id, path);
+    }
+});
+test('created returns pending without throwing when a receipt is not yet visible', () => {
+    const explicit = created({ path, absolutePath: path, deliveryStatus: 'pending' });
+    const legacy = created({ path, absolutePath: path });
+    for (const result of [explicit, legacy]) {
+        assert.deepEqual(result, { status: 'pending', id: path, url: '', path });
+        assert.notEqual(result.url, path);
+    }
+});
+test('created preserves an authoritative dropped result without throwing', () => {
+    assert.deepEqual(created({ path, absolutePath: path, deliveryStatus: 'dropped' }), { status: 'dropped', id: path, url: '', path });
+    const diagnostic = { ok: false, reason: 'path_not_mounted' };
+    assert.deepEqual(created({ path, absolutePath: path, deliveryStatus: 'dropped', receipt: diagnostic }), { status: 'dropped', id: path, url: '', path, receipt: diagnostic });
+});
+test('created rejects malformed or unknown runtime transport results clearly', () => {
+    const malformed = [
+        null,
+        undefined,
+        'not-a-result',
+        {},
+        { path: '   ', absolutePath: path },
+        { path, absolutePath: path, receipt: 'not-a-receipt' },
+        { path, absolutePath: path, deliveryStatus: 'unknown' },
+        { path, absolutePath: path, deliveryStatus: 'confirmed' },
+        { path, absolutePath: path, receipt: {} },
+        { path, absolutePath: path, receipt: { provider: 'github' } },
+        { path, absolutePath: path, receipt: { id: Number.NaN } },
+        { path, absolutePath: path, deliveryStatus: 'pending', receipt: { id: 'contradiction' } },
+    ];
+    for (const value of malformed) {
+        assert.throws(() => created(value), TypeError);
+    }
+});
+class FixedResultTransport {
+    status;
+    writes = [];
+    constructor(status) {
+        this.status = status;
+    }
+    async read(_request) {
+        throw new Error('read not expected');
+    }
+    async list(_request) {
+        throw new Error('list not expected');
+    }
+    async write(request) {
+        this.writes.push(request);
+        return {
+            path: request.path,
+            absolutePath: request.path,
+            deliveryStatus: this.status,
+            ...(this.status === 'confirmed'
+                ? { receipt: { id: `${request.resource}-id`, url: `https://provider.example/${request.resource}-id` } }
+                : {}),
+        };
+    }
+}
+test('GitHub and Linear ergonomic create helpers preserve every transport status', async () => {
+    for (const status of ['confirmed', 'pending', 'dropped']) {
+        const transport = new FixedResultTransport(status);
+        const github = githubClient({ transport });
+        const linear = linearClient({ transport });
+        const results = await Promise.all([
+            github.comment({ owner: 'o', repo: 'r', number: 1 }, 'comment'),
+            github.createIssue({ owner: 'o', repo: 'r', title: 'issue', body: 'body' }),
+            github.createPullRequest({ owner: 'o', repo: 'r', title: 'pr', head: 'feature', base: 'main' }),
+            linear.agentActivity('session-1', { type: 'thought', body: 'working' }),
+            linear.respond('session-2', 'done'),
+            linear.acknowledge('session-3'),
+            linear.comment('issue-1', 'comment'),
+            linear.createIssue({ teamId: 'team-1', title: 'issue' }),
+            linear.createLabel({ name: 'label' }),
+        ]);
+        assert.equal(results.length, 9);
+        assert.equal(transport.writes.length, 9);
+        for (const result of results) {
+            assert.equal(result.status, status);
+            if (status === 'confirmed') {
+                assert.match(result.url, /^https:\/\/provider\.example\//u);
+            }
+            else {
+                assert.equal(result.url, '');
+                assert.equal(result.id, result.path);
+            }
+        }
+    }
+});
+test('mount-backed ergonomic helpers report both immediate and timed-out writes as pending', async () => {
+    for (const writebackTimeoutMs of [0, 20]) {
+        const root = await mkdtemp(nodePath.join(tmpdir(), 'relay-created-pending-'));
+        const result = await githubClient({
+            relayfileMountRoot: root,
+            writebackTimeoutMs,
+            writebackPollMs: 5,
+        }).comment({ owner: 'o', repo: 'r', number: 1 }, 'pending');
+        assert.equal(result.status, 'pending');
+        assert.equal(result.id, result.path);
+        assert.equal(result.url, '');
+    }
+});
+test('preview receipts flow through ergonomic helpers as confirmed', async () => {
+    const result = await linearClient({ transport: new PreviewTransport() })
+        .createIssue({ teamId: 'team-1', title: 'preview' });
+    assert.equal(result.status, 'confirmed');
+    assert.match(result.id, /^preview-linear-issues-/u);
+    assert.equal(result.url, '');
+});
+test('direct HTTP receipt timeout becomes pending instead of a retry-triggering throw', async () => {
+    const fetchImpl = async (input) => {
+        const url = String(input);
+        if (url.includes('/fs/file')) {
+            return Response.json({
+                opId: 'op_pending_created',
+                status: 'queued',
+                targetRevision: 'rev-1',
+                writeback: { provider: 'github', state: 'pending' },
+            });
+        }
+        if (url.includes('/ops/op_pending_created')) {
+            return Response.json({ opId: 'op_pending_created', status: 'running', attemptCount: 1 });
+        }
+        return Response.json({ code: 'not_found' }, { status: 404 });
+    };
+    const result = await githubClient({
+        relayfileBaseUrl: 'https://relayfile.example.test',
+        relayfileApiToken: 'token',
+        workspaceId: 'workspace-1',
+        fetchImpl,
+        writebackTimeoutMs: 20,
+        writebackPollMs: 5,
+    }).comment({ owner: 'o', repo: 'r', number: 1 }, 'pending');
+    assert.equal(result.status, 'pending');
+    assert.equal(result.path.startsWith(`${issueCommentsPath}/`), true);
+    assert.equal(result.url, '');
+});
+test('direct HTTP terminal operation evidence becomes dropped without retrying', async () => {
+    let opReads = 0;
+    const fetchImpl = async (input) => {
+        const url = String(input);
+        if (url.includes('/fs/file')) {
+            return Response.json({
+                opId: 'op_dropped_created',
+                status: 'queued',
+                targetRevision: 'rev-1',
+                writeback: { provider: 'linear', state: 'pending' },
+            });
+        }
+        if (url.includes('/ops/op_dropped_created')) {
+            opReads += 1;
+            return Response.json({
+                opId: 'op_dropped_created',
+                status: 'dead_lettered',
+                attemptCount: 1,
+                lastError: 'path is outside the mounted integration scope',
+            });
+        }
+        return Response.json({ code: 'not_found' }, { status: 404 });
+    };
+    const result = await linearClient({
+        relayfileBaseUrl: 'https://relayfile.example.test',
+        relayfileApiToken: 'token',
+        workspaceId: 'workspace-1',
+        fetchImpl,
+        writebackTimeoutMs: 100,
+        writebackPollMs: 5,
+    }).createIssue({ teamId: 'team-1', title: 'dropped' });
+    assert.equal(result.status, 'dropped');
+    assert.equal(opReads, 1);
+    assert.match(result.reason ?? '', /dead_lettered.*outside the mounted integration scope/u);
+    assert.equal(result.url, '');
+});
+test('ambiguous admission timeouts remain errors rather than false dropped certainty', async () => {
+    const admissionError = new RelayfileWritebackAdmissionTimeoutError({
+        provider: 'github',
+        operation: 'write.issue-comments',
+        path,
+        timeoutMs: 20,
+    });
+    const transport = {
+        read: async () => undefined,
+        list: async () => [],
+        write: async () => { throw admissionError; },
+    };
+    await assert.rejects(() => githubClient({ transport }).comment({ owner: 'o', repo: 'r', number: 1 }, 'ambiguous'), (error) => error === admissionError);
+});
+test('legacy pathless terminal errors remain constructible and are not misclassified as dropped', async () => {
+    const legacyError = new RelayfileWritebackTerminalError({
+        provider: 'github',
+        operation: 'write.issue-comments',
+        opId: 'op_legacy_terminal',
+        status: 'failed',
+        lastError: 'legacy caller has no path',
+    });
+    const transport = {
+        read: async () => undefined,
+        list: async () => [],
+        write: async () => { throw legacyError; },
+    };
+    assert.equal(legacyError.path, undefined);
+    await assert.rejects(() => githubClient({ transport }).comment({ owner: 'o', repo: 'r', number: 1 }, 'legacy'), (error) => error === legacyError);
+});
+function assertCreatedOverloads(result, pending) {
+    const sync = created(result);
+    const asyncResult = created(pending);
+    void sync;
+    void asyncResult;
+}
+void assertCreatedOverloads;
+function assertCreatedResultNarrowing(result) {
+    switch (result.status) {
+        case 'confirmed': {
+            const narrowed = result;
+            const url = narrowed.url;
+            return url;
+        }
+        case 'pending': {
+            const narrowed = result;
+            const url = narrowed.url;
+            return url;
+        }
+        case 'dropped': {
+            const narrowed = result;
+            const url = narrowed.url;
+            return url;
+        }
+        default: {
+            const exhaustive = result;
+            return exhaustive;
+        }
+    }
+}
+void assertCreatedResultNarrowing;
+// @ts-expect-error unknown statuses cannot enter the typed writeback contract
+const invalidStatus = { path, absolutePath: path, deliveryStatus: 'unknown' };
+void invalidStatus;
+//# sourceMappingURL=receipt.test.js.map

package/dist/receipt.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.test.js","sourceRoot":"","sources":["../src/receipt.test.ts"],"names":[],"mappings":"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"}

package/dist/relay-helpers.test.js

@@ -8,7 +8,7 @@ import { RelayfileWritebackPendingError, RelayfileWritebackReceiptError } from '
 import { WRITEBACK_PATH_CATALOG } from '@relayfile/adapter-core/writeback-paths';
 import { linearByUuidAliasPath } from '@relayfile/adapter-linear/path-mapper';
 import * as helpers from './index.js';
-import { githubClient, linearClient, notionClient, providerClient, relayClient, slackClient, telegramClient, telegramReceiptTs, } from './index.js';
+import { PreviewTransport, RelayWriteAuthorizationError, bindRelayWriteAuthorizer, githubClient, linearClient, notionClient, providerClient, relayClient, slackClient, telegramClient, telegramReceiptTs, } from './index.js';
 const clientExportName = (provider) => `${provider.replace(/-([a-z])/g, (_m, c) => c.toUpperCase())}Client`;
 /** Fire-and-forget client bound to a throwaway mount; no writeback worker runs. */
 async function mount() {
@@ -28,6 +28,39 @@ test('relayClient.path resolves catalog paths and write drops a collection draft
     const draft = await onlyJsonIn(path.join(root, 'linear/issues/ISS-1/comments'));
     assert.deepEqual(draft.body, { body: 'hi' });
 });
+test('final-write authorization redirects the native VFS fallback before filesystem mutation', async () => {
+    const { root, opts } = await mount();
+    const canonicalPreview = new PreviewTransport();
+    const restoreAuthorization = bindRelayWriteAuthorizer(() => ({
+        allowed: true,
+        transport: canonicalPreview,
+    }));
+    try {
+        await relayClient('linear', opts).write('comments', { issueId: 'ISS-redirect' }, { body: 'preview' });
+    }
+    finally {
+        restoreAuthorization();
+    }
+    assert.deepEqual(await readdir(root), []);
+    assert.equal(canonicalPreview.actions.length, 1);
+    assert.equal(canonicalPreview.actions[0]?.path.startsWith('/linear/issues/ISS-redirect/comments/'), true);
+});
+test('final-write denial rejects the native VFS fallback before filesystem mutation', async () => {
+    const { root, opts } = await mount();
+    let deniedActions = 0;
+    const restoreAuthorization = bindRelayWriteAuthorizer(() => {
+        deniedActions += 1;
+        return { allowed: false };
+    });
+    try {
+        await assert.rejects(() => relayClient('linear', opts).write('comments', { issueId: 'ISS-denied' }, { body: 'never written' }), RelayWriteAuthorizationError);
+    }
+    finally {
+        restoreAuthorization();
+    }
+    assert.equal(deniedActions, 1);
+    assert.deepEqual(await readdir(root), []);
+});
 test('relayClient.write writes item (.json) resources to the exact path', async () => {
     const { root, opts } = await mount();
     const gh = relayClient('github', opts);
@@ -362,6 +395,71 @@ test('src/generated/clients.ts is in sync with the catalog', async () => {
     const committed = await readFile(path.join(pkgRoot, 'src/generated/clients.ts'), 'utf8');
     assert.equal(committed, renderClients(), 'generated clients are stale — run `npm run gen -w @relayfile/relay-helpers`');
 });
+test('all helper write sites converge on the final-write authorization boundary', async () => {
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const srcRoot = path.join(pkgRoot, 'src');
+    const { findWriteBoundaryViolations, formatWriteBoundaryViolations } = await import(pathToFileURL(path.join(pkgRoot, 'scripts/verify-write-boundary.mjs')).href);
+    const violations = await findWriteBoundaryViolations({ sourceRoot: srcRoot });
+    assert.deepEqual(violations, [], `helper write paths bypass the final-write authorizer:\n${formatWriteBoundaryViolations(violations)}`);
+});
+test('write-boundary guard rejects nested renamed, bracket, destructured, aliased, and VFS canaries', async () => {
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const { findWriteBoundaryViolations } = await import(pathToFileURL(path.join(pkgRoot, 'scripts/verify-write-boundary.mjs')).href);
+    const canaryRoot = await mkdtemp(path.join(tmpdir(), 'relay-write-boundary-canary-'));
+    const nestedRoot = path.join(canaryRoot, 'future/nested');
+    await mkdir(nestedRoot, { recursive: true });
+    await writeFile(path.join(nestedRoot, 'bypass.ts'), `
+import { writeJsonFile as persist } from '@relayfile/adapter-core/vfs-client';
+
+interface Request {
+  provider: string;
+  resource: string;
+  parameters: Record<string, string>;
+  path: string;
+  body: unknown;
+}
+interface FutureTransport {
+  write(request: Request): Promise<unknown>;
+}
+
+export async function renamed(selectedTransport: FutureTransport, request: Request) {
+  await selectedTransport.write(request);
+  await selectedTransport['write'](request);
+  const { write: destructured } = selectedTransport;
+  await destructured(request);
+  const aliased = selectedTransport.write;
+  await aliased(request);
+  await persist(
+    {},
+    'future',
+    'write.future',
+    '/future/path.json',
+    request.body,
+  );
+}
+`);
+    const nestedAuthorizerPath = path.join(nestedRoot, 'write-authorizer.ts');
+    await writeFile(nestedAuthorizerPath, `
+interface Request {
+  provider: string;
+  resource: string;
+  parameters: Record<string, string>;
+  path: string;
+  body: unknown;
+}
+interface FutureTransport {
+  write(request: Request): Promise<unknown>;
+}
+
+export async function nestedAuthorizerBypass(transport: FutureTransport, request: Request) {
+  await transport.write(request);
+}
+`);
+    const violations = await findWriteBoundaryViolations({ sourceRoot: canaryRoot });
+    assert.ok(violations.filter((violation) => violation.kind === 'raw-transport-write').length >= 4, `expected every raw transport canary to fail: ${JSON.stringify(violations)}`);
+    assert.ok(violations.some((violation) => violation.kind.startsWith('native-vfs-write')), `expected multiline aliased VFS canary to fail: ${JSON.stringify(violations)}`);
+    assert.ok(violations.some((violation) => violation.kind === 'raw-transport-write' && violation.file === nestedAuthorizerPath), `expected nested write-authorizer.ts canary to fail: ${JSON.stringify(violations)}`);
+});
 test('a named resource-keyed client resolves and writes catalog paths', async () => {
     const { root, opts } = await mount();
     const notion = notionClient(opts);