@pierre/storage 0.1.4 → 0.2.1

package/src/diff-commit.ts

@@ -0,0 +1,300 @@
+import { buildCommitResult, parseCommitPackError } from './commit-pack';
+import { RefUpdateError } from './errors';
+import type { CommitPackAckRaw } from './schemas';
+import { commitPackAckSchema } from './schemas';
+import {
+	base64Encode,
+	type ChunkSegment,
+	chunkify,
+	requiresDuplex,
+	toAsyncIterable,
+	toRequestBody,
+} from './stream-utils';
+import type {
+	CommitResult,
+	CommitSignature,
+	CreateCommitFromDiffOptions,
+	DiffSource,
+} from './types';
+
+interface DiffCommitMetadataPayload {
+	target_branch: string;
+	expected_head_sha?: string;
+	base_branch?: string;
+	commit_message: string;
+	ephemeral?: boolean;
+	ephemeral_base?: boolean;
+	author: {
+		name: string;
+		email: string;
+	};
+	committer?: {
+		name: string;
+		email: string;
+	};
+}
+
+interface DiffCommitTransportRequest {
+	authorization: string;
+	signal?: AbortSignal;
+	metadata: DiffCommitMetadataPayload;
+	diffChunks: AsyncIterable<ChunkSegment>;
+}
+
+interface DiffCommitTransport {
+	send(request: DiffCommitTransportRequest): Promise<CommitPackAckRaw>;
+}
+
+type NormalizedDiffCommitOptions = {
+	targetBranch: string;
+	commitMessage: string;
+	expectedHeadSha?: string;
+	baseBranch?: string;
+	ephemeral?: boolean;
+	ephemeralBase?: boolean;
+	author: CommitSignature;
+	committer?: CommitSignature;
+	signal?: AbortSignal;
+	ttl?: number;
+	initialDiff: DiffSource;
+};
+
+interface CommitFromDiffSendDeps {
+	options: CreateCommitFromDiffOptions;
+	getAuthToken: () => Promise<string>;
+	transport: DiffCommitTransport;
+}
+
+class DiffCommitExecutor {
+	private readonly options: NormalizedDiffCommitOptions;
+	private readonly getAuthToken: () => Promise<string>;
+	private readonly transport: DiffCommitTransport;
+	private readonly diffFactory: () => AsyncIterable<Uint8Array>;
+	private sent = false;
+
+	constructor(deps: CommitFromDiffSendDeps) {
+		this.options = normalizeDiffCommitOptions(deps.options);
+		this.getAuthToken = deps.getAuthToken;
+		this.transport = deps.transport;
+
+		const trimmedMessage = this.options.commitMessage?.trim();
+		const trimmedAuthorName = this.options.author?.name?.trim();
+		const trimmedAuthorEmail = this.options.author?.email?.trim();
+
+		if (!trimmedMessage) {
+			throw new Error('createCommitFromDiff commitMessage is required');
+		}
+		if (!trimmedAuthorName || !trimmedAuthorEmail) {
+			throw new Error('createCommitFromDiff author name and email are required');
+		}
+
+		this.options.commitMessage = trimmedMessage;
+		this.options.author = {
+			name: trimmedAuthorName,
+			email: trimmedAuthorEmail,
+		};
+
+		if (typeof this.options.expectedHeadSha === 'string') {
+			this.options.expectedHeadSha = this.options.expectedHeadSha.trim();
+		}
+		if (typeof this.options.baseBranch === 'string') {
+			const trimmedBase = this.options.baseBranch.trim();
+			if (trimmedBase === '') {
+				delete this.options.baseBranch;
+			} else {
+				if (trimmedBase.startsWith('refs/')) {
+					throw new Error('createCommitFromDiff baseBranch must not include refs/ prefix');
+				}
+				this.options.baseBranch = trimmedBase;
+			}
+		}
+		if (this.options.ephemeralBase && !this.options.baseBranch) {
+			throw new Error('createCommitFromDiff ephemeralBase requires baseBranch');
+		}
+
+		this.diffFactory = () => toAsyncIterable(this.options.initialDiff);
+	}
+
+	async send(): Promise<CommitResult> {
+		this.ensureNotSent();
+		this.sent = true;
+
+		const metadata = this.buildMetadata();
+		const diffIterable = chunkify(this.diffFactory());
+
+		const authorization = await this.getAuthToken();
+		const ack = await this.transport.send({
+			authorization,
+			signal: this.options.signal,
+			metadata,
+			diffChunks: diffIterable,
+		});
+
+		return buildCommitResult(ack);
+	}
+
+	private buildMetadata(): DiffCommitMetadataPayload {
+		const metadata: DiffCommitMetadataPayload = {
+			target_branch: this.options.targetBranch,
+			commit_message: this.options.commitMessage,
+			author: {
+				name: this.options.author.name,
+				email: this.options.author.email,
+			},
+		};
+
+		if (this.options.expectedHeadSha) {
+			metadata.expected_head_sha = this.options.expectedHeadSha;
+		}
+		if (this.options.baseBranch) {
+			metadata.base_branch = this.options.baseBranch;
+		}
+		if (this.options.committer) {
+			metadata.committer = {
+				name: this.options.committer.name,
+				email: this.options.committer.email,
+			};
+		}
+		if (this.options.ephemeral) {
+			metadata.ephemeral = true;
+		}
+		if (this.options.ephemeralBase) {
+			metadata.ephemeral_base = true;
+		}
+
+		return metadata;
+	}
+
+	private ensureNotSent(): void {
+		if (this.sent) {
+			throw new Error('createCommitFromDiff cannot be reused after send()');
+		}
+	}
+}
+
+export class FetchDiffCommitTransport implements DiffCommitTransport {
+	private readonly url: string;
+
+	constructor(config: { baseUrl: string; version: number }) {
+		const trimmedBase = config.baseUrl.replace(/\/+$/, '');
+		this.url = `${trimmedBase}/api/v${config.version}/repos/diff-commit`;
+	}
+
+	async send(request: DiffCommitTransportRequest): Promise<CommitPackAckRaw> {
+		const bodyIterable = buildMessageIterable(request.metadata, request.diffChunks);
+		const body = toRequestBody(bodyIterable);
+
+		const init: RequestInit = {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${request.authorization}`,
+				'Content-Type': 'application/x-ndjson',
+				Accept: 'application/json',
+			},
+			body: body as any,
+			signal: request.signal,
+		};
+
+		if (requiresDuplex(body)) {
+			(init as RequestInit & { duplex: 'half' }).duplex = 'half';
+		}
+
+		const response = await fetch(this.url, init);
+		if (!response.ok) {
+			const fallbackMessage = `createCommitFromDiff request failed (${response.status} ${response.statusText})`;
+			const { statusMessage, statusLabel, refUpdate } = await parseCommitPackError(
+				response,
+				fallbackMessage,
+			);
+			throw new RefUpdateError(statusMessage, {
+				status: statusLabel,
+				message: statusMessage,
+				refUpdate,
+			});
+		}
+
+		return commitPackAckSchema.parse(await response.json());
+	}
+}
+
+function buildMessageIterable(
+	metadata: DiffCommitMetadataPayload,
+	diffChunks: AsyncIterable<ChunkSegment>,
+): AsyncIterable<Uint8Array> {
+	const encoder = new TextEncoder();
+	return {
+		async *[Symbol.asyncIterator]() {
+			yield encoder.encode(`${JSON.stringify({ metadata })}\n`);
+			for await (const segment of diffChunks) {
+				const payload = {
+					diff_chunk: {
+						data: base64Encode(segment.chunk),
+						eof: segment.eof,
+					},
+				};
+				yield encoder.encode(`${JSON.stringify(payload)}\n`);
+			}
+		},
+	};
+}
+
+function normalizeDiffCommitOptions(
+	options: CreateCommitFromDiffOptions,
+): NormalizedDiffCommitOptions {
+	if (!options || typeof options !== 'object') {
+		throw new Error('createCommitFromDiff options are required');
+	}
+
+	if (options.diff === undefined || options.diff === null) {
+		throw new Error('createCommitFromDiff diff is required');
+	}
+
+	const targetBranch = normalizeBranchName(options.targetBranch);
+
+	let committer: CommitSignature | undefined;
+	if (options.committer) {
+		const name = options.committer.name?.trim();
+		const email = options.committer.email?.trim();
+		if (!name || !email) {
+			throw new Error('createCommitFromDiff committer name and email are required when provided');
+		}
+		committer = { name, email };
+	}
+
+	return {
+		targetBranch,
+		commitMessage: options.commitMessage,
+		expectedHeadSha: options.expectedHeadSha,
+		baseBranch: options.baseBranch,
+		ephemeral: options.ephemeral === true,
+		ephemeralBase: options.ephemeralBase === true,
+		author: options.author,
+		committer,
+		signal: options.signal,
+		ttl: options.ttl,
+		initialDiff: options.diff,
+	};
+}
+
+function normalizeBranchName(value: string | undefined): string {
+	const trimmed = value?.trim();
+	if (!trimmed) {
+		throw new Error('createCommitFromDiff targetBranch is required');
+	}
+	if (trimmed.startsWith('refs/heads/')) {
+		const branch = trimmed.slice('refs/heads/'.length).trim();
+		if (!branch) {
+			throw new Error('createCommitFromDiff targetBranch must include a branch name');
+		}
+		return branch;
+	}
+	if (trimmed.startsWith('refs/')) {
+		throw new Error('createCommitFromDiff targetBranch must not include refs/ prefix');
+	}
+	return trimmed;
+}
+
+export async function sendCommitFromDiff(deps: CommitFromDiffSendDeps): Promise<CommitResult> {
+	const executor = new DiffCommitExecutor(deps);
+	return executor.send();
+}

package/src/index.ts

@@ -7,6 +7,7 @@
 import { importPKCS8, SignJWT } from 'jose';
 import snakecaseKeys from 'snakecase-keys';
 import { createCommitBuilder, FetchCommitTransport, resolveCommitTtlSeconds } from './commit';
+import { FetchDiffCommitTransport, sendCommitFromDiff } from './diff-commit';
 import { RefUpdateError } from './errors';
 import { ApiFetcher } from './fetch';
 import type { RestoreCommitAckRaw } from './schemas';
@@ -23,6 +24,8 @@ import type {
 	BranchInfo,
 	CommitBuilder,
 	CommitInfo,
+	CommitResult,
+	CreateCommitFromDiffOptions,
 	CreateCommitOptions,
 	CreateRepoOptions,
 	DiffFileState,
@@ -357,6 +360,9 @@ class RepoImpl implements Repo {
 		if (options.ref) {
 			params.ref = options.ref;
 		}
+		if (typeof options.ephemeral === 'boolean') {
+			params.ephemeral = String(options.ephemeral);
+		}
 
 		// Return the raw fetch Response for streaming
 		return this.api.get({ path: 'repos/file', params }, jwt);
@@ -369,10 +375,17 @@ class RepoImpl implements Repo {
 			ttl,
 		});
 
-		const params: Record<string, string> | undefined = options?.ref
-			? { ref: options.ref }
-			: undefined;
-		const response = await this.api.get({ path: 'repos/files', params }, jwt);
+		const params: Record<string, string> = {};
+		if (options?.ref) {
+			params.ref = options.ref;
+		}
+		if (typeof options?.ephemeral === 'boolean') {
+			params.ephemeral = String(options.ephemeral);
+		}
+		const response = await this.api.get(
+			{ path: 'repos/files', params: Object.keys(params).length ? params : undefined },
+			jwt,
+		);
 
 		const raw = listFilesResponseSchema.parse(await response.json());
 		return { paths: raw.paths, ref: raw.ref };
@@ -605,6 +618,28 @@ class RepoImpl implements Repo {
 			transport,
 		});
 	}
+
+	async createCommitFromDiff(options: CreateCommitFromDiffOptions): Promise<CommitResult> {
+		const version = this.options.apiVersion ?? API_VERSION;
+		const baseUrl = this.options.apiBaseUrl ?? API_BASE_URL;
+		const transport = new FetchDiffCommitTransport({ baseUrl, version });
+		const ttl = resolveCommitTtlSeconds(options);
+		const requestOptions: CreateCommitFromDiffOptions = {
+			...options,
+			ttl,
+		};
+		const getAuthToken = () =>
+			this.generateJWT(this.id, {
+				permissions: ['git:write'],
+				ttl,
+			});
+
+		return sendCommitFromDiff({
+			options: requestOptions,
+			getAuthToken,
+			transport,
+		});
+	}
 }
 
 export class GitStorage {

package/src/stream-utils.ts

@@ -0,0 +1,255 @@
+import type { BlobLike, FileLike, ReadableStreamLike } from './types';
+
+type NodeBuffer = Uint8Array & { toString(encoding?: string): string };
+interface NodeBufferConstructor {
+	from(data: Uint8Array): NodeBuffer;
+	from(data: string, encoding?: string): NodeBuffer;
+	isBuffer(value: unknown): value is NodeBuffer;
+}
+
+const BufferCtor: NodeBufferConstructor | undefined = (
+	globalThis as { Buffer?: NodeBufferConstructor }
+).Buffer;
+
+export const MAX_CHUNK_BYTES = 4 * 1024 * 1024;
+
+export type ChunkSegment = {
+	chunk: Uint8Array;
+	eof: boolean;
+};
+
+export async function* chunkify(source: AsyncIterable<Uint8Array>): AsyncIterable<ChunkSegment> {
+	let pending: Uint8Array | null = null;
+	let produced = false;
+
+	for await (const value of source) {
+		const bytes = value;
+
+		if (pending && pending.byteLength === MAX_CHUNK_BYTES) {
+			yield { chunk: pending, eof: false };
+			produced = true;
+			pending = null;
+		}
+
+		const merged: Uint8Array = pending ? concatChunks(pending, bytes) : bytes;
+		pending = null;
+
+		let cursor: Uint8Array = merged;
+		while (cursor.byteLength > MAX_CHUNK_BYTES) {
+			const chunk: Uint8Array = cursor.slice(0, MAX_CHUNK_BYTES);
+			cursor = cursor.slice(MAX_CHUNK_BYTES);
+			yield { chunk, eof: false };
+			produced = true;
+		}
+
+		pending = cursor;
+	}
+
+	if (pending) {
+		yield { chunk: pending, eof: true };
+		produced = true;
+	}
+
+	if (!produced) {
+		yield { chunk: new Uint8Array(0), eof: true };
+	}
+}
+
+export async function* toAsyncIterable(
+	source:
+		| string
+		| Uint8Array
+		| ArrayBuffer
+		| BlobLike
+		| FileLike
+		| ReadableStreamLike<Uint8Array | ArrayBuffer | ArrayBufferView | string>
+		| AsyncIterable<Uint8Array | ArrayBuffer | ArrayBufferView | string>
+		| Iterable<Uint8Array | ArrayBuffer | ArrayBufferView | string>,
+): AsyncIterable<Uint8Array> {
+	if (typeof source === 'string') {
+		yield new TextEncoder().encode(source);
+		return;
+	}
+	if (source instanceof Uint8Array) {
+		yield source;
+		return;
+	}
+	if (source instanceof ArrayBuffer) {
+		yield new Uint8Array(source);
+		return;
+	}
+	if (ArrayBuffer.isView(source)) {
+		yield new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+		return;
+	}
+	if (isBlobLike(source)) {
+		const stream = source.stream();
+		if (isAsyncIterable(stream)) {
+			for await (const chunk of stream as AsyncIterable<unknown>) {
+				yield ensureUint8Array(chunk);
+			}
+			return;
+		}
+		if (isReadableStreamLike(stream)) {
+			yield* readReadableStream(stream);
+			return;
+		}
+	}
+	if (isReadableStreamLike(source)) {
+		yield* readReadableStream(source);
+		return;
+	}
+	if (isAsyncIterable(source)) {
+		for await (const chunk of source as AsyncIterable<unknown>) {
+			yield ensureUint8Array(chunk);
+		}
+		return;
+	}
+	if (isIterable(source)) {
+		for (const chunk of source as Iterable<unknown>) {
+			yield ensureUint8Array(chunk);
+		}
+		return;
+	}
+	throw new Error('Unsupported content source; expected binary data');
+}
+
+export function base64Encode(bytes: Uint8Array): string {
+	if (BufferCtor) {
+		return BufferCtor.from(bytes).toString('base64');
+	}
+	let binary = '';
+	for (let i = 0; i < bytes.byteLength; i++) {
+		binary += String.fromCharCode(bytes[i]);
+	}
+	const btoaFn = (globalThis as { btoa?: (data: string) => string }).btoa;
+	if (typeof btoaFn === 'function') {
+		return btoaFn(binary);
+	}
+	throw new Error('Base64 encoding is not supported in this environment');
+}
+
+export function requiresDuplex(body: unknown): boolean {
+	if (!body || typeof body !== 'object') {
+		return false;
+	}
+
+	if (typeof (body as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function') {
+		return true;
+	}
+
+	const readableStreamCtor = (
+		globalThis as {
+			ReadableStream?: new (...args: unknown[]) => unknown;
+		}
+	).ReadableStream;
+	if (readableStreamCtor && body instanceof readableStreamCtor) {
+		return true;
+	}
+
+	return false;
+}
+
+export function toRequestBody(iterable: AsyncIterable<Uint8Array>): unknown {
+	const readableStreamCtor = (
+		globalThis as { ReadableStream?: new (underlyingSource: unknown) => unknown }
+	).ReadableStream;
+	if (typeof readableStreamCtor === 'function') {
+		const iterator = iterable[Symbol.asyncIterator]();
+		return new readableStreamCtor({
+			async pull(controller: { enqueue(chunk: Uint8Array): void; close(): void }) {
+				const { value, done } = await iterator.next();
+				if (done) {
+					controller.close();
+					return;
+				}
+				controller.enqueue(value!);
+			},
+			async cancel(reason: unknown) {
+				if (typeof iterator.return === 'function') {
+					await iterator.return(reason);
+				}
+			},
+		});
+	}
+	return iterable;
+}
+
+async function* readReadableStream(stream: ReadableStreamLike<unknown>): AsyncIterable<Uint8Array> {
+	const reader = stream.getReader();
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) {
+				break;
+			}
+			if (value !== undefined) {
+				yield ensureUint8Array(value);
+			}
+		}
+	} finally {
+		reader.releaseLock?.();
+	}
+}
+
+function ensureUint8Array(value: unknown): Uint8Array {
+	if (value instanceof Uint8Array) {
+		return value;
+	}
+	if (value instanceof ArrayBuffer) {
+		return new Uint8Array(value);
+	}
+	if (ArrayBuffer.isView(value)) {
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	}
+	if (typeof value === 'string') {
+		return new TextEncoder().encode(value);
+	}
+	if (BufferCtor && BufferCtor.isBuffer(value)) {
+		return value as Uint8Array;
+	}
+	throw new Error('Unsupported chunk type; expected binary data');
+}
+
+function isBlobLike(value: unknown): value is BlobLike {
+	return (
+		typeof value === 'object' && value !== null && typeof (value as BlobLike).stream === 'function'
+	);
+}
+
+function isReadableStreamLike<T>(value: unknown): value is ReadableStreamLike<T> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as ReadableStreamLike<T>).getReader === 'function'
+	);
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Symbol.asyncIterator in (value as Record<string, unknown>)
+	);
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Symbol.iterator in (value as Record<string, unknown>)
+	);
+}
+
+function concatChunks(a: Uint8Array, b: Uint8Array): Uint8Array {
+	if (a.byteLength === 0) {
+		return b;
+	}
+	if (b.byteLength === 0) {
+		return a;
+	}
+	const merged = new Uint8Array(a.byteLength + b.byteLength);
+	merged.set(a, 0);
+	merged.set(b, a.byteLength);
+	return merged;
+}

package/src/types.ts

@@ -47,6 +47,7 @@ export interface Repo {
 	pullUpstream(options: PullUpstreamOptions): Promise<void>;
 	restoreCommit(options: RestoreCommitOptions): Promise<RestoreCommitResult>;
 	createCommit(options: CreateCommitOptions): CommitBuilder;
+	createCommitFromDiff(options: CreateCommitFromDiffOptions): Promise<CommitResult>;
 }
 
 export type ValidMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
@@ -88,6 +89,7 @@ export interface CreateRepoOptions extends GitStorageInvocationOptions {
 export interface GetFileOptions extends GitStorageInvocationOptions {
 	path: string;
 	ref?: string;
+	ephemeral?: boolean;
 }
 
 export interface PullUpstreamOptions extends GitStorageInvocationOptions {
@@ -97,6 +99,7 @@ export interface PullUpstreamOptions extends GitStorageInvocationOptions {
 // List Files API types
 export interface ListFilesOptions extends GitStorageInvocationOptions {
 	ref?: string;
+	ephemeral?: boolean;
 }
 
 export type ListFilesResponse = ListFilesResponseRaw;
@@ -228,6 +231,8 @@ interface CreateCommitBaseOptions extends GitStorageInvocationOptions {
 	commitMessage: string;
 	expectedHeadSha?: string;
 	baseBranch?: string;
+	ephemeral?: boolean;
+	ephemeralBase?: boolean;
 	author: CommitSignature;
 	committer?: CommitSignature;
 	signal?: AbortSignal;
@@ -312,6 +317,21 @@ export interface CommitBuilder {
 	send(): Promise<CommitResult>;
 }
 
+export type DiffSource = CommitFileSource;
+
+export interface CreateCommitFromDiffOptions extends GitStorageInvocationOptions {
+	targetBranch: string;
+	commitMessage: string;
+	diff: DiffSource;
+	expectedHeadSha?: string;
+	baseBranch?: string;
+	ephemeral?: boolean;
+	ephemeralBase?: boolean;
+	author: CommitSignature;
+	committer?: CommitSignature;
+	signal?: AbortSignal;
+}
+
 export interface RefUpdate {
 	branch: string;
 	oldSha: string;