@wp-playground/storage 3.0.22 → 3.0.31

package/lib/browser-fs.d.ts

@@ -0,0 +1,5 @@
+import type { MountDevice } from '@php-wasm/web';
+export declare function directoryHandleFromMountDevice(device: MountDevice): Promise<FileSystemDirectoryHandle>;
+export declare function opfsPathToDirectoryHandle(opfsPath: string): Promise<FileSystemDirectoryHandle>;
+export declare function directoryHandleToOpfsPath(directoryHandle: FileSystemDirectoryHandle): Promise<string>;
+export declare function clearContentsFromMountDevice(mountDevice: MountDevice): Promise<void>;

package/lib/changeset.d.ts

@@ -0,0 +1,62 @@
+import type { UniversalPHP } from '@php-wasm/universal';
+export type IterateFilesOptions = {
+    /**
+     * Should yield paths relative to the root directory?
+     * If false, all paths will be absolute.
+     */
+    relativePaths?: boolean;
+    /**
+     * The root directory that Playground paths start from.
+     */
+    playgroundRoot?: string;
+    /**
+     * A prefix to add to all paths.
+     * Only used if `relativePaths` is true.
+     */
+    pathPrefix?: string;
+    /**
+     * A list of paths to exclude from the results.
+     */
+    exceptPaths?: string[];
+};
+/**
+ * Iterates over all files in a Playground directory and its subdirectories.
+ *
+ * @param playground - The Playground/PHP instance.
+ * @param root - The root directory to start iterating from.
+ * @param options - Optional configuration.
+ * @returns All files found in the tree.
+ */
+export declare function iterateFiles(playground: UniversalPHP, root: string, { exceptPaths }?: IterateFilesOptions): AsyncGenerator<FileEntry>;
+export type FileEntry = {
+    path: string;
+    read: () => Promise<Uint8Array>;
+};
+/**
+ * Represents a set of changes to be applied to a data store.
+ */
+export type Changeset = {
+    /**
+     * Created files.
+     */
+    create: Map<string, Uint8Array>;
+    /**
+     * Updated files.
+     */
+    update: Map<string, Uint8Array>;
+    /**
+     * Deleted files.
+     */
+    delete: Set<string>;
+};
+/**
+ * Compares two sets of files and returns a changeset object that describes
+ * the differences between them.
+ *
+ * @param filesBefore - A map of file paths to Uint8Array objects representing the contents
+ *                      of the files before the changes.
+ * @param filesAfter - An async generator that yields FileEntry objects representing the files
+ *                     after the changes.
+ * @returns A changeset object that describes the differences between the two sets of files.
+ */
+export declare function changeset(filesBefore: Map<string, Uint8Array>, filesAfter: AsyncGenerator<FileEntry> | Iterable<FileEntry>): Promise<Changeset>;

package/lib/filesystems.d.ts

@@ -0,0 +1,211 @@
+import { StreamedFile } from '@php-wasm/stream-compression';
+import type { FileTree } from '@php-wasm/universal';
+import { ZipReader, BlobReader } from '@zip.js/zip.js';
+export interface ReadableFilesystemBackend {
+    read(path: string): Promise<StreamedFile>;
+}
+/**
+ * A readable filesystem that can also be traversed (list directories).
+ */
+export interface TraversableFilesystemBackend extends ReadableFilesystemBackend {
+    listFiles(path: string): Promise<string[]>;
+    isDir(path: string): Promise<boolean>;
+}
+/**
+ * Backend interface for writable filesystem operations.
+ * All paths passed to these methods are expected to be absolute paths.
+ */
+export interface WritableFilesystemBackend extends TraversableFilesystemBackend {
+    fileExists(absolutePath: string): Promise<boolean>;
+    writeFile(absolutePath: string, data: Uint8Array): Promise<void>;
+    mkdir(absolutePath: string, recursive?: boolean): Promise<void>;
+    rmdir(absolutePath: string, recursive: boolean): Promise<void>;
+    mv(absoluteSource: string, absoluteDestination: string): Promise<void>;
+    unlink(absolutePath: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Interface for a writable filesystem with EventTarget support.
+ * Used by UI components that need to react to filesystem changes.
+ */
+export interface AsyncWritableFilesystem extends EventTarget {
+    isDir(path: string): Promise<boolean>;
+    fileExists(path: string): Promise<boolean>;
+    read(path: string): Promise<{
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }>;
+    readFileAsText(path: string): Promise<string>;
+    listFiles(path: string): Promise<string[]>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mv(source: string, destination: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+/**
+ * Copy all files from source filesystem to destination filesystem.
+ * Clears the destination before copying.
+ */
+export declare function copyFilesystem(source: TraversableFilesystemBackend, destination: WritableFilesystemBackend): Promise<void>;
+/**
+ * Wraps a WritableFilesystemBackend with EventTarget support and convenience methods.
+ * Dispatches 'change' events on write operations.
+ */
+export declare class EventedFilesystem extends EventTarget implements AsyncWritableFilesystem {
+    private readonly encoder;
+    private readonly decoder;
+    readonly backend: WritableFilesystemBackend;
+    constructor(backend: WritableFilesystemBackend);
+    isDir(path: string): Promise<boolean>;
+    fileExists(path: string): Promise<boolean>;
+    read(path: string): Promise<StreamedFile>;
+    readFileAsText(path: string): Promise<string>;
+    listFiles(path: string): Promise<string[]>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mv(source: string, destination: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class InMemoryFilesystem implements ReadableFilesystemBackend {
+    private fileTree;
+    constructor(fileTree: FileTree);
+    read(path: string): Promise<StreamedFile>;
+    private getEntryAtPath;
+}
+export declare class ZipFilesystem implements ReadableFilesystemBackend {
+    private entries;
+    private zipReader;
+    static fromStream(stream: ReadableStream<Uint8Array>): ZipFilesystem;
+    static fromArrayBuffer(arrayBuffer: ArrayBuffer): ZipFilesystem;
+    constructor(zipReader: ZipReader<BlobReader>);
+    read(relativePath: string): Promise<StreamedFile>;
+    private getEntry;
+    private getEntries;
+}
+/**
+ * A Filesystem implementation that cascades through multiple filesystems
+ * and returns the first successful result.
+ *
+ * This is useful for creating a layered approach to file resolution,
+ * such as checking a local cache before fetching from a remote source.
+ */
+export declare class OverlayFilesystem implements ReadableFilesystemBackend {
+    private filesystems;
+    /**
+     * Creates a new OverlayFilesystem.
+     *
+     * @param filesystems An array of Filesystem instances to cascade through.
+     *                    The order determines the priority - earlier filesystems
+     *                    are checked first.
+     */
+    constructor(filesystems: ReadableFilesystemBackend[]);
+    /**
+     * Reads a file by trying each filesystem in order until one succeeds.
+     *
+     * @param path The path to the file to read.
+     * @returns A Promise that resolves to a StreamedFile from the first
+     *          filesystem that successfully resolves the path.
+     * @throws Error if all filesystems fail to resolve the path.
+     */
+    read(path: string): Promise<StreamedFile>;
+}
+export interface FetchFilesystemOptions {
+    corsProxy?: string;
+    baseUrl: string;
+}
+/**
+ * A Filesystem implementation that fetches files from URLs.
+ * It can optionally use a CORS proxy and resolve paths relative to a base URL.
+ */
+export declare class FetchFilesystem implements ReadableFilesystemBackend {
+    private baseUrl;
+    private options;
+    private isDataUrl;
+    constructor(options: FetchFilesystemOptions);
+    read(path: string): Promise<StreamedFile>;
+}
+/**
+ * A Filesystem implementation that uses the "fs" and "path" modules from Node.js
+ * to read files from the local file system.
+ *
+ * This is only available in a local environment.
+ */
+export declare class NodeJsFilesystem implements ReadableFilesystemBackend {
+    private fs;
+    private path;
+    private root;
+    constructor(root: string);
+    private ensureNodeModules;
+    read(filePath: string): Promise<StreamedFile>;
+}
+/**
+ * OPFS filesystem backend that operates directly on the Origin Private File System.
+ * Implements both ReadableFilesystemBackend (for BlueprintBundle) and
+ * WritableFilesystemBackend (for the editor).
+ */
+export declare class OpfsFilesystemBackend implements WritableFilesystemBackend {
+    private readonly opfsRoot;
+    constructor(opfsRoot: FileSystemDirectoryHandle);
+    /**
+     * Create a backend for a specific OPFS directory handle.
+     */
+    static fromDirectoryHandle(handle: FileSystemDirectoryHandle): OpfsFilesystemBackend;
+    /**
+     * Create a backend for a specific path in OPFS.
+     * The path will be created if `create` is true.
+     * @throws Error if OPFS is not available or path doesn't exist (when create=false)
+     */
+    static fromPath(path: string, create?: boolean): Promise<OpfsFilesystemBackend>;
+    clear(): Promise<void>;
+    read(path: string): Promise<StreamedFile>;
+    isDir(absolutePath: string): Promise<boolean>;
+    fileExists(absolutePath: string): Promise<boolean>;
+    listFiles(absolutePath: string): Promise<string[]>;
+    writeFile(absolutePath: string, data: Uint8Array): Promise<void>;
+    mkdir(absolutePath: string, recursive?: boolean): Promise<void>;
+    rmdir(absolutePath: string, recursive: boolean): Promise<void>;
+    mv(absoluteSource: string, absoluteDestination: string): Promise<void>;
+    unlink(absolutePath: string): Promise<void>;
+    private readFileAsBuffer;
+    private copyDir;
+}
+/**
+ * In-memory writable filesystem backend that stores files in a tree structure.
+ */
+export declare class InMemoryFilesystemBackend implements WritableFilesystemBackend {
+    private root;
+    constructor(initialFiles?: Record<string, Uint8Array>);
+    read(path: string): Promise<StreamedFile>;
+    isDir(absolutePath: string): Promise<boolean>;
+    fileExists(absolutePath: string): Promise<boolean>;
+    listFiles(absolutePath: string): Promise<string[]>;
+    writeFile(absolutePath: string, data: Uint8Array): Promise<void>;
+    mkdir(absolutePath: string, recursive?: boolean): Promise<void>;
+    rmdir(absolutePath: string, recursive: boolean): Promise<void>;
+    mv(absoluteSource: string, absoluteDestination: string): Promise<void>;
+    unlink(absolutePath: string): Promise<void>;
+    clear(): Promise<void>;
+    private writeFileSync;
+    private getNode;
+    private getDir;
+    private getFile;
+    /**
+     * Get parent directory, throwing if it doesn't exist.
+     */
+    private getParent;
+    /**
+     * Get parent directory, creating it if it doesn't exist.
+     */
+    private getOrCreateParent;
+    private ensureDir;
+}

package/lib/git-create-dotgit-directory.d.ts

@@ -0,0 +1,16 @@
+import type { SparseCheckoutObject } from './git-sparse-checkout';
+type GitDirectoryRefType = 'branch' | 'tag' | 'commit' | 'refname';
+/**
+ * Creates a complete .git directory structure with all necessary files.
+ * This includes HEAD, config, refs, objects, and the Git index.
+ */
+export declare function createDotGitDirectory({ repoUrl, commitHash, ref, refType, objects, fileOids, pathPrefix, }: {
+    repoUrl: string;
+    commitHash: string;
+    ref: string;
+    refType?: GitDirectoryRefType;
+    objects: SparseCheckoutObject[];
+    fileOids: Record<string, string>;
+    pathPrefix: string;
+}): Promise<Record<string, string | Uint8Array>>;
+export {};

package/lib/git-sparse-checkout.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Custom error class for git authentication failures.
+ */
+export declare class GitAuthenticationError extends Error {
+    repoUrl: string;
+    status: number;
+    constructor(repoUrl: string, status: number);
+}
+export type GitAdditionalHeaders = Record<string, string>;
+/**
+ * Downloads specific files from a git repository.
+ * It uses the git protocol over HTTP to fetch the files. It only uses
+ * three HTTP requests regardless of the number of paths requested.
+ *
+ * @param repoUrl The URL of the git repository.
+ * @param fullyQualifiedBranchName The full name of the branch to fetch from (e.g., 'refs/heads/main').
+ * @param filesPaths An array of all the file paths to fetch from the repository. Does **not** accept
+ *                   patterns, wildcards, directory paths. All files must be explicitly listed.
+ * @returns The requested files and packfiles required to recreate the Git objects locally.
+ */
+export type SparseCheckoutPackfile = {
+    name: string;
+    pack: Uint8Array;
+    index: Uint8Array;
+    promisor?: boolean;
+};
+export type SparseCheckoutObject = {
+    oid: string;
+    type: 'blob' | 'tree' | 'commit' | 'tag';
+    body: Uint8Array;
+};
+export type SparseCheckoutResult = {
+    files: Record<string, any>;
+    packfiles?: SparseCheckoutPackfile[];
+    objects?: SparseCheckoutObject[];
+    fileOids?: Record<string, string>;
+};
+export declare function sparseCheckout(repoUrl: string, commitHash: string, filesPaths: string[], options?: {
+    withObjects?: boolean;
+    additionalHeaders?: GitAdditionalHeaders;
+}): Promise<SparseCheckoutResult>;
+export type GitFileTreeFile = {
+    name: string;
+    type: 'file';
+};
+export type GitFileTreeFolder = {
+    name: string;
+    type: 'folder';
+    children: GitFileTree[];
+};
+export type GitFileTree = GitFileTreeFile | GitFileTreeFolder;
+/**
+ * A Git ref in a human-readable format. Could be a single string,
+ * e.g. 'main', 'v0.1.28', '1234567890abcdef1234567890abcdef12345678',
+ * could be a string and an explicit type, e.g. { value: 'main', type: 'branch' },
+ */
+export type GitRef = {
+    value: string;
+    type?: 'branch' | 'commit' | 'refname' | 'tag' | 'infer';
+};
+/**
+ * Lists all files in a git repository.
+ *
+ * See https://git-scm.com/book/en/v2/Git-Internals-Git-Objects for more information.
+ *
+ * @param repoUrl The URL of the git repository.
+ * @param commitHash The commit hash to fetch from.
+ * @returns A list of all files in the repository.
+ */
+export declare function listGitFiles(repoUrl: string, commitHash: string, additionalHeaders?: GitAdditionalHeaders): Promise<GitFileTree[]>;
+/**
+ * Resolves a ref description, e.g. a branch name, to a commit hash.
+ *
+ * @param repoUrl The URL of the git repository.
+ * @param ref The branch name or commit hash.
+ * @returns The commit hash.
+ */
+export declare function resolveCommitHash(repoUrl: string, ref: GitRef, additionalHeaders?: GitAdditionalHeaders): Promise<string>;
+/**
+ * Retrieves a list of refs from a git repository.
+ *
+ * See https://git-scm.com/book/en/v2/Git-Internals-Git-References for more information.
+ *
+ * @param repoUrl The URL of the git repository. For example: https://github.com/WordPress/gutenberg.git
+ * @param fullyQualifiedBranchPrefix The prefix of the refs to fetch. For example: refs/heads/my-feature-branch
+ * @returns A map of refs to their corresponding commit hashes.
+ */
+export declare function listGitRefs(repoUrl: string, fullyQualifiedBranchPrefix: string, additionalHeaders?: GitAdditionalHeaders): Promise<Record<string, string>>;

package/lib/github.d.ts

@@ -0,0 +1,47 @@
+import { Octokit } from 'octokit';
+import type { Changeset } from './changeset';
+export type GithubClient = ReturnType<typeof createClient>;
+export declare function createClient(githubToken: string): Octokit;
+export type Files = Record<string, Uint8Array>;
+export declare function filesListToObject(files: any[], root?: string): Files;
+export interface GetFilesProgress {
+    foundFiles: number;
+    downloadedFiles: number;
+}
+export interface GetFilesOptions {
+    onProgress?: ({ foundFiles, downloadedFiles }: GetFilesProgress) => void;
+    progress?: GetFilesProgress;
+}
+export declare function getFilesFromDirectory(octokit: GithubClient, owner: string, repo: string, ref: string, path: string, options?: GetFilesOptions): Promise<any[]>;
+/**
+ * Usage:
+ * > await getArtifact('wordpress', 'wordpress-develop', 5511, 'build.yml')
+ *
+ * To get the first artifact produced by the "build.yml" workflow running
+ * as a part of the PR 5511
+ *
+ * @returns
+ */
+export declare function getArtifact(octokit: GithubClient, owner: string, repo: string, pull_number: number, workflow_id: string): Promise<unknown>;
+export declare function mayPush(octokit: Octokit, owner: string, repo: string): Promise<boolean>;
+export declare function createOrUpdateBranch(octokit: Octokit, owner: string, repo: string, branch: string, newHead: string): Promise<void>;
+/**
+ * @param octokit
+ * @param owner
+ * @param repo
+ * @returns The owner of the forked repository
+ */
+export declare function fork(octokit: Octokit, owner: string, repo: string): Promise<string>;
+export declare function createCommit(octokit: Octokit, owner: string, repo: string, message: string, parentSha: string, treeSha: string): Promise<string>;
+export declare function createTree(octokit: Octokit, owner: string, repo: string, parentSha: string, changeset: Changeset): Promise<string | null>;
+export type GitHubTreeNode = {
+    path: string;
+    mode: '100644';
+} & ({
+    sha: string | null;
+} | {
+    content: string;
+});
+export declare function createTreeNodes(octokit: Octokit, owner: string, repo: string, parentSha: string, changeset: Changeset): Promise<GitHubTreeNode[]>;
+export declare function createTreeNode(octokit: Octokit, owner: string, repo: string, path: string, content: string | Uint8Array): Promise<GitHubTreeNode>;
+export declare function deleteFile(octokit: Octokit, owner: string, repo: string, parentSha: string, path: string): Promise<GitHubTreeNode | undefined>;

package/lib/paths.d.ts

@@ -0,0 +1,3 @@
+import type { GitFileTree } from './git-sparse-checkout';
+export declare function listDescendantFiles(files: GitFileTree[], selectedPath: string): string[];
+export declare function removePathPrefix(path: string, prefix: string): string;

package/lib/playground.d.ts

@@ -0,0 +1,4 @@
+export type GitHubFile = {
+    path: string;
+    content: Uint8Array;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-playground/storage",
-  "version": "3.0.22",
+  "version": "3.0.31",
   "description": "Bindings for storing WordPress Playground on different backends.",
   "repository": {
     "type": "git",
@@ -34,6 +34,7 @@
   },
   "license": "GPL-2.0-or-later",
   "type": "module",
+  "types": "index.d.ts",
   "dependencies": {
     "@zip.js/zip.js": "2.7.57",
     "async-lock": "^1.4.1",
@@ -48,25 +49,26 @@
     "pako": "^1.0.10",
     "pify": "^4.0.1",
     "readable-stream": "^3.4.0",
+    "selfsigned": "2.4.1",
     "sha.js": "^2.4.9",
     "simple-get": "^4.0.1",
     "wasm-feature-detect": "1.8.0",
     "ws": "8.18.3",
     "yargs": "17.7.2",
-    "@php-wasm/web": "3.0.22",
-    "@php-wasm/universal": "3.0.22",
-    "@php-wasm/util": "3.0.22",
-    "@php-wasm/stream-compression": "3.0.22"
+    "@php-wasm/web": "3.0.31",
+    "@php-wasm/universal": "3.0.31",
+    "@php-wasm/util": "3.0.31",
+    "@php-wasm/stream-compression": "3.0.31"
   },
-  "gitHead": "a624d1a97dc639e152d335e6a801b2fad7f6b594",
+  "gitHead": "e28b6d2a2e663abc3cbb8fce9a3c5cc8abaa5bbe",
   "packageManager": "npm@10.9.2",
   "overrides": {
     "rollup": "^4.34.6",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "typescript": "5.4.5",
-    "@playwright/test": "1.47.1",
-    "ws": "^8.18.0",
+    "@playwright/test": "1.55.1",
+    "ws": "8.18.3",
     "tmp": "0.2.5",
     "form-data": "^4.0.4"
   },