@elaraai/e3-cloud-files 0.0.0-stage → 1.0.92

package/dist/src/check/index.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * `@elaraai/e3-cloud-files/check`: the checks a deploy of declarations and a
+ * bind run, and the keys, prefixes, globs and URLs they hold to, without the
+ * authoring (which needs `@elaraai/e3`): what the CLI and the platform
+ * import.
+ *
+ * @packageDocumentation
+ */
+export { checkFiles, checkBindings, readPackageInputs, shapeType, } from '../check.js';
+export { globMatcher, parseBucketUrl, keyProblem, prefixProblem, includeProblem } from '../paths.js';
+//# sourceMappingURL=index.js.map

package/dist/src/check/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/check/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EACL,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,SAAS,GAIV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC"}

package/dist/src/check.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Whether declarations fit a package, and bindings fit declarations.
+ *
+ * {@link checkFiles} is the one check every deploy of declarations runs, on a
+ * local repository and in the cloud: each mapping's input exists, is an
+ * input, and is of its shape's type, compared exactly. {@link checkBindings}
+ * is what a bind runs. {@link readPackageInputs} reads a package's inputs
+ * from its objects, through a reader: the store's on a server, a local
+ * repository's on a machine.
+ *
+ * @packageDocumentation
+ */
+import { type EastTypeValue } from '@elaraai/east';
+import { type FilesBinding, type FilesManifest, type FilesProblem, type FilesShape } from '@elaraai/e3-cloud-types';
+/** An input of a package. */
+export interface PackageInput {
+    /** Its type */
+    readonly type: EastTypeValue;
+    /** Whether anything may write it: inputs are writable; task outputs and records are not */
+    readonly writable: boolean;
+}
+/** Reads an object of a package's repository by hash. */
+export type ObjectReader = (hash: string) => Promise<Uint8Array>;
+/** The type a shape's input holds. */
+export declare function shapeType(shape: FilesShape): EastTypeValue;
+/**
+ * Reads a package's inputs, `.inputs.<name>`, from its objects.
+ *
+ * @param read - Reads an object by hash
+ * @param packageHash - The package object's hash
+ * @returns Each input, by name
+ */
+export declare function readPackageInputs(read: ObjectReader, packageHash: string): Promise<Map<string, PackageInput>>;
+/**
+ * The problems of declarations against a package, none when they fit. Each
+ * mapping's input must be an input of the package, of its shape's type.
+ *
+ * @param manifest - The declarations
+ * @param inputs - The package's inputs ({@link readPackageInputs})
+ * @returns Every problem
+ */
+export declare function checkFiles(manifest: FilesManifest, inputs: ReadonlyMap<string, PackageInput>): FilesProblem[];
+/** Where a binding may point: for a deployed workspace, the sources the deployment grants. */
+export interface BindingPolicy {
+    /** Whether the bindings are a local repository's, where `profile` and `latest` apply */
+    readonly local: boolean;
+    /** The buckets and prefixes the deployment grants, for a deployed workspace; any URL locally */
+    readonly granted?: readonly {
+        readonly bucket: string;
+        readonly prefixes: readonly string[];
+    }[];
+}
+/**
+ * The problems of bindings against declarations, none when they fit.
+ *
+ * @param manifest - The declarations
+ * @param bindings - The bindings
+ * @param policy - Where they may point
+ * @returns Every problem
+ */
+export declare function checkBindings(manifest: FilesManifest, bindings: readonly FilesBinding[], policy: BindingPolicy): FilesProblem[];
+//# sourceMappingURL=check.d.ts.map

package/dist/src/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoD,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAErG,OAAO,EAEL,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAC1E,MAAM,yBAAyB,CAAC;AAGjC,6BAA6B;AAC7B,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAIjE,sCAAsC;AACtC,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAU1D;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAWnH;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,YAAY,EAAE,CAgC7G;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACjG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,MAAM,EAAE,aAAa,GAAG,YAAY,EAAE,CAuB/H"}

package/dist/src/check.js

@@ -0,0 +1,140 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Whether declarations fit a package, and bindings fit declarations.
+ *
+ * {@link checkFiles} is the one check every deploy of declarations runs, on a
+ * local repository and in the cloud: each mapping's input exists, is an
+ * input, and is of its shape's type, compared exactly. {@link checkBindings}
+ * is what a bind runs. {@link readPackageInputs} reads a package's inputs
+ * from its objects, through a reader: the store's on a server, a local
+ * repository's on a machine.
+ *
+ * @packageDocumentation
+ */
+import { EastTypeType, equalFor, toEastTypeValue, variant } from '@elaraai/east';
+import { decodePackageObject } from '@elaraai/e3-types';
+import { FilesFileType, FilesFolderType, FilesListingType, } from '@elaraai/e3-cloud-types';
+import { includeProblem, keyProblem, parseBucketUrl, prefixProblem } from './paths.js';
+const typesEqual = equalFor(EastTypeType);
+/** The type a shape's input holds. */
+export function shapeType(shape) {
+    switch (shape.type) {
+        case 'file':
+        case 'latest':
+            return toEastTypeValue(FilesFileType);
+        case 'folder':
+            return toEastTypeValue(FilesFolderType);
+        case 'listing':
+            return toEastTypeValue(FilesListingType);
+    }
+}
+/**
+ * Reads a package's inputs, `.inputs.<name>`, from its objects.
+ *
+ * @param read - Reads an object by hash
+ * @param packageHash - The package object's hash
+ * @returns Each input, by name
+ */
+export async function readPackageInputs(read, packageHash) {
+    const pkg = decodePackageObject(await read(packageHash));
+    const inputs = new Map();
+    const root = pkg.data.structure;
+    if (root.type !== 'struct')
+        return inputs;
+    const tree = root.value.get('inputs');
+    if (tree === undefined || tree.type !== 'struct')
+        return inputs;
+    for (const [name, child] of tree.value) {
+        if (child.type === 'value')
+            inputs.set(name, { type: child.value.type, writable: child.value.writable });
+    }
+    return inputs;
+}
+/**
+ * The problems of declarations against a package, none when they fit. Each
+ * mapping's input must be an input of the package, of its shape's type.
+ *
+ * @param manifest - The declarations
+ * @param inputs - The package's inputs ({@link readPackageInputs})
+ * @returns Every problem
+ */
+export function checkFiles(manifest, inputs) {
+    const problems = [];
+    const seen = new Set();
+    const sources = new Set(manifest.sources);
+    for (const mapping of manifest.mappings) {
+        const { input, shape } = mapping;
+        if (seen.has(input))
+            problems.push(variant('duplicate_input', { input }));
+        seen.add(input);
+        if (!sources.has(mapping.source))
+            problems.push(variant('source_unknown', { source: mapping.source }));
+        // What the declarations alone get wrong, as a declaration would have refused it
+        if (shape.type === 'file') {
+            const reason = keyProblem(shape.value.key);
+            if (reason !== null)
+                problems.push(variant('invalid_key', { input, key: shape.value.key, reason }));
+        }
+        else {
+            const reason = prefixProblem(shape.value.prefix);
+            if (reason !== null)
+                problems.push(variant('invalid_key', { input, key: shape.value.prefix, reason }));
+            if (shape.value.include.type === 'some') {
+                const include = includeProblem(shape.value.include.value);
+                if (include !== null)
+                    problems.push(variant('invalid_include', { input, include: shape.value.include.value, reason: include }));
+            }
+        }
+        const expected = shapeType(shape);
+        const declared = inputs.get(input);
+        if (declared === undefined) {
+            problems.push(variant('input_missing', { input, expected }));
+        }
+        else if (!declared.writable) {
+            problems.push(variant('input_not_writable', { input }));
+        }
+        else if (!typesEqual(declared.type, expected)) {
+            problems.push(variant('input_type', { input, expected, actual: declared.type }));
+        }
+    }
+    return problems;
+}
+/**
+ * The problems of bindings against declarations, none when they fit.
+ *
+ * @param manifest - The declarations
+ * @param bindings - The bindings
+ * @param policy - Where they may point
+ * @returns Every problem
+ */
+export function checkBindings(manifest, bindings, policy) {
+    const problems = [];
+    const sources = new Set(manifest.sources);
+    for (const binding of bindings) {
+        const { source, url } = binding;
+        if (!sources.has(source))
+            problems.push(variant('source_unknown', { source }));
+        const location = parseBucketUrl(url);
+        if ('problem' in location) {
+            problems.push(variant('invalid_url', { source, url, reason: location.problem }));
+            continue;
+        }
+        if (!policy.local) {
+            if (binding.profile.type === 'some')
+                problems.push(variant('local_only', { source, option: 'profile' }));
+            if (binding.latest.type === 'some')
+                problems.push(variant('local_only', { source, option: 'latest' }));
+            const granted = (policy.granted ?? []).some((grant) => grant.bucket === location.bucket && grant.prefixes.some((prefix) => location.prefix.startsWith(prefix)));
+            if (!granted)
+                problems.push(variant('not_granted', { source, url }));
+        }
+        if (binding.latest.type === 'some' && binding.latest.value < 1n) {
+            problems.push(variant('invalid_url', { source, url, reason: 'keeps fewer than one file (latest)' }));
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=check.js.map

package/dist/src/check.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * `@elaraai/e3-cloud-files`: a solution's inputs that come from files in a
+ * bucket.
+ *
+ * - `Files.source(name)`: a source, which each workspace binds to a bucket
+ *   and a prefix; its `file`, `latest`, `folder` and `listing` declare the
+ *   inputs its files fill, each an ordinary `e3.input`.
+ * - `Files.manifest(sources)`: the declarations `e3-cloud files deploy`
+ *   deploys beside the package.
+ * - `checkFiles`, `checkBindings`, `readPackageInputs`: the checks a deploy
+ *   and a bind run.
+ *
+ * A file arrives as it is, a `Blob`; the solution decodes it in East. The
+ * sync is `@elaraai/e3-cloud-files/sync`; the East types are
+ * `@elaraai/e3-cloud-types`'s `Files*`.
+ *
+ * @packageDocumentation
+ */
+export { Files, FilesSource, FilesDeclarationError, type FilesInput, type FilesSelection } from './authoring.js';
+export { checkFiles, checkBindings, readPackageInputs, shapeType, type PackageInput, type ObjectReader, type BindingPolicy, } from './check.js';
+export { globMatcher, parseBucketUrl, keyProblem, prefixProblem, includeProblem, type BucketLocation } from './paths.js';
+export { FilesManifestType, FilesMappingType, FilesShapeType, FilesBindingType, FilesSyncReportType, FilesMappingReportType, FilesStatusType, FilesProblemType, FilesListingRowType, FilesFileType, FilesFolderType, FilesListingType, FILES_FILE_MAX_BYTES, FILES_FOLDER_ENTRY_MAX_BYTES, filesProblemText, type FilesManifest, type FilesMapping, type FilesShape, type FilesBinding, type FilesSyncReport, type FilesMappingReport, type FilesStatus, type FilesProblem, type FilesListingRow, } from '@elaraai/e3-cloud-types';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjH,OAAO,EACL,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * `@elaraai/e3-cloud-files`: a solution's inputs that come from files in a
+ * bucket.
+ *
+ * - `Files.source(name)`: a source, which each workspace binds to a bucket
+ *   and a prefix; its `file`, `latest`, `folder` and `listing` declare the
+ *   inputs its files fill, each an ordinary `e3.input`.
+ * - `Files.manifest(sources)`: the declarations `e3-cloud files deploy`
+ *   deploys beside the package.
+ * - `checkFiles`, `checkBindings`, `readPackageInputs`: the checks a deploy
+ *   and a bind run.
+ *
+ * A file arrives as it is, a `Blob`; the solution decodes it in East. The
+ * sync is `@elaraai/e3-cloud-files/sync`; the East types are
+ * `@elaraai/e3-cloud-types`'s `Files*`.
+ *
+ * @packageDocumentation
+ */
+export { Files, FilesSource, FilesDeclarationError } from './authoring.js';
+export { checkFiles, checkBindings, readPackageInputs, shapeType, } from './check.js';
+export { globMatcher, parseBucketUrl, keyProblem, prefixProblem, includeProblem } from './paths.js';
+export { FilesManifestType, FilesMappingType, FilesShapeType, FilesBindingType, FilesSyncReportType, FilesMappingReportType, FilesStatusType, FilesProblemType, FilesListingRowType, FilesFileType, FilesFolderType, FilesListingType, FILES_FILE_MAX_BYTES, FILES_FOLDER_ENTRY_MAX_BYTES, filesProblemText, } from '@elaraai/e3-cloud-types';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAwC,MAAM,gBAAgB,CAAC;AACjH,OAAO,EACL,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,SAAS,GAIV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAC;AACzH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,GAUjB,MAAM,yBAAyB,CAAC"}

package/dist/src/paths.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * The keys, prefixes and globs a mapping names, and the URLs a binding
+ * names: what makes each well-formed, and how a glob matches.
+ *
+ * A mapping's key or prefix is relative to where a workspace binds its
+ * source, so it never names a bucket and never begins with `/`. A prefix is
+ * a folder: empty for everything the binding holds, else ending with `/`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Why a key cannot name one file, or `null` when it can.
+ *
+ * @param key - The key, relative to the binding
+ * @returns The reason, completing "'<key>' …"
+ */
+export declare function keyProblem(key: string): string | null;
+/**
+ * Why a prefix cannot name a folder, or `null` when it can.
+ *
+ * @param prefix - The prefix, relative to the binding: `''`, or ending with `/`
+ * @returns The reason, completing "'<prefix>' …"
+ */
+export declare function prefixProblem(prefix: string): string | null;
+/**
+ * Why a glob cannot select files, or `null` when it can.
+ *
+ * @param include - The glob, over paths relative to the prefix
+ * @returns The reason, completing "include '<include>' …"
+ */
+export declare function includeProblem(include: string): string | null;
+/**
+ * A glob's matcher over paths relative to a prefix: `*` matches within one
+ * folder of the path, `**` across folders, `?` one character but `/`,
+ * `[abc]`, `[a-z]` and `[!abc]` one character of a set but `/`, and
+ * `{csv,json}` any of its alternatives, each a glob itself. Every other
+ * character matches itself. No glob matches every path.
+ *
+ * @param include - The glob, or `null` for every path
+ * @returns Whether a path matches
+ * @throws {Error} When the glob is malformed ({@link includeProblem} says how)
+ */
+export declare function globMatcher(include: string | null): (path: string) => boolean;
+/**
+ * Whether a glob matches only paths in the prefix's own folder, never in one
+ * under it: a listing of that folder alone holds every file it can match.
+ *
+ * @param include - The glob, or `null` for every path
+ * @returns Whether it names no `/` and no `**`
+ */
+export declare function matchesTopFolderOnly(include: string | null): boolean;
+/** A binding's URL, read: its bucket, and the prefix under it, `''` or ending with `/`. */
+export interface BucketLocation {
+    readonly bucket: string;
+    readonly prefix: string;
+}
+/**
+ * Reads a binding's URL, `s3://bucket/prefix/`.
+ *
+ * @param url - The URL
+ * @returns The bucket and the prefix, or the reason it is not one, completing "'<url>' …"
+ */
+export declare function parseBucketUrl(url: string): BucketLocation | {
+    readonly problem: string;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAsFD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpE;AAED,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAQzF"}

package/dist/src/paths.js

@@ -0,0 +1,205 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * The keys, prefixes and globs a mapping names, and the URLs a binding
+ * names: what makes each well-formed, and how a glob matches.
+ *
+ * A mapping's key or prefix is relative to where a workspace binds its
+ * source, so it never names a bucket and never begins with `/`. A prefix is
+ * a folder: empty for everything the binding holds, else ending with `/`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Why a key cannot name one file, or `null` when it can.
+ *
+ * @param key - The key, relative to the binding
+ * @returns The reason, completing "'<key>' …"
+ */
+export function keyProblem(key) {
+    if (key === '')
+        return 'is empty';
+    if (key.startsWith('/'))
+        return 'begins with /: a key is relative to where the workspace binds its source';
+    if (key.endsWith('/'))
+        return 'ends with /, which names a folder rather than a file';
+    return null;
+}
+/**
+ * Why a prefix cannot name a folder, or `null` when it can.
+ *
+ * @param prefix - The prefix, relative to the binding: `''`, or ending with `/`
+ * @returns The reason, completing "'<prefix>' …"
+ */
+export function prefixProblem(prefix) {
+    if (prefix.startsWith('/'))
+        return 'begins with /: a prefix is relative to where the workspace binds its source';
+    if (prefix !== '' && !prefix.endsWith('/'))
+        return "doesn't end with /: a prefix names a folder";
+    return null;
+}
+/** Why a glob is malformed, completing "include '<include>' …". */
+class GlobError extends Error {
+}
+/** A literal character, as a regular expression matches it. */
+function literal(c) {
+    return c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * A `[…]` class at `glob[at.i]`, as a regular expression: one character of a
+ * segment, never `/`. `[!…]` and `[^…]` match any character but those named;
+ * a `]` first in the class is one of its characters; `a-z` is a range.
+ */
+function characterClass(glob, at) {
+    let i = at.i + 1;
+    let negate = false;
+    if (glob[i] === '!' || glob[i] === '^') {
+        negate = true;
+        i += 1;
+    }
+    let body = '';
+    for (let first = true;; first = false, i += 1) {
+        const c = glob[i];
+        if (c === undefined)
+            throw new GlobError('has a [ it never closes');
+        if (c === ']' && !first)
+            break;
+        if (c === '/')
+            throw new GlobError('has a / in a [...] class, which matches one character within a folder');
+        body += c === '\\' || c === ']' || c === '[' || c === '^' ? `\\${c}` : c;
+    }
+    at.i = i + 1;
+    return negate ? `[^/${body}]` : `[${body}]`;
+}
+/**
+ * A glob's pattern from `glob[at.i]`, as a regular expression, up to its end,
+ * or, inside braces, up to the `,` or `}` that ends an alternative.
+ */
+function translate(glob, at, inBraces) {
+    let pattern = '';
+    while (at.i < glob.length) {
+        const c = glob[at.i];
+        if (inBraces && (c === ',' || c === '}'))
+            return pattern;
+        if (c === '*' && glob[at.i + 1] === '*') {
+            // `**/` matches zero or more whole folders; a bare `**`, anything
+            if (glob[at.i + 2] === '/') {
+                pattern += '(?:.*/)?';
+                at.i += 3;
+            }
+            else {
+                pattern += '.*';
+                at.i += 2;
+            }
+        }
+        else if (c === '*') {
+            pattern += '[^/]*';
+            at.i += 1;
+        }
+        else if (c === '?') {
+            pattern += '[^/]';
+            at.i += 1;
+        }
+        else if (c === '[') {
+            pattern += characterClass(glob, at);
+        }
+        else if (c === '{') {
+            at.i += 1;
+            const alternatives = [];
+            for (;;) {
+                alternatives.push(translate(glob, at, true));
+                const end = glob[at.i];
+                if (end === undefined)
+                    throw new GlobError('has a { it never closes');
+                at.i += 1;
+                if (end === '}')
+                    break;
+            }
+            pattern += `(?:${alternatives.join('|')})`;
+        }
+        else if (c === '}') {
+            throw new GlobError('has a } with no { before it');
+        }
+        else {
+            pattern += literal(c);
+            at.i += 1;
+        }
+    }
+    return pattern;
+}
+/** A glob, as the regular expression its matcher tests paths with. */
+function globRegex(include) {
+    return new RegExp(`^${translate(include, { i: 0 }, false)}$`, 'su');
+}
+/**
+ * Why a glob cannot select files, or `null` when it can.
+ *
+ * @param include - The glob, over paths relative to the prefix
+ * @returns The reason, completing "include '<include>' …"
+ */
+export function includeProblem(include) {
+    if (include === '')
+        return 'is empty';
+    if (include.startsWith('/'))
+        return 'begins with /: it matches paths relative to the prefix';
+    if (/\*{3,}/.test(include))
+        return 'has three or more * in a row';
+    try {
+        globRegex(include);
+    }
+    catch (err) {
+        if (err instanceof GlobError)
+            return err.message;
+        // A class whose range runs backwards (`[z-a]`) is no pattern at all
+        return 'has a [...] class no character can match';
+    }
+    return null;
+}
+/**
+ * A glob's matcher over paths relative to a prefix: `*` matches within one
+ * folder of the path, `**` across folders, `?` one character but `/`,
+ * `[abc]`, `[a-z]` and `[!abc]` one character of a set but `/`, and
+ * `{csv,json}` any of its alternatives, each a glob itself. Every other
+ * character matches itself. No glob matches every path.
+ *
+ * @param include - The glob, or `null` for every path
+ * @returns Whether a path matches
+ * @throws {Error} When the glob is malformed ({@link includeProblem} says how)
+ */
+export function globMatcher(include) {
+    if (include === null)
+        return () => true;
+    const regex = globRegex(include);
+    return (path) => regex.test(path);
+}
+/**
+ * Whether a glob matches only paths in the prefix's own folder, never in one
+ * under it: a listing of that folder alone holds every file it can match.
+ *
+ * @param include - The glob, or `null` for every path
+ * @returns Whether it names no `/` and no `**`
+ */
+export function matchesTopFolderOnly(include) {
+    return include !== null && !include.includes('/') && !include.includes('**');
+}
+/**
+ * Reads a binding's URL, `s3://bucket/prefix/`.
+ *
+ * @param url - The URL
+ * @returns The bucket and the prefix, or the reason it is not one, completing "'<url>' …"
+ */
+export function parseBucketUrl(url) {
+    const match = /^s3:\/\/([^/]+)(?:\/(.*))?$/su.exec(url);
+    if (match === null)
+        return { problem: 'is not an s3://bucket/prefix/ URL' };
+    const bucket = match[1];
+    if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/u.test(bucket))
+        return { problem: `names '${bucket}', which isn't a bucket's name` };
+    const prefix = match[2] ?? '';
+    if (prefix !== '' && !prefix.endsWith('/'))
+        return { problem: "doesn't end with /: a binding names a folder" };
+    return { bucket, prefix };
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/paths.js.map

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

package/dist/src/s3/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * `@elaraai/e3-cloud-files/s3`: the sync's reader of a bucket (`s3://`), one
+ * bound source read through a client the caller makes. The CLI makes it with
+ * the developer's own profile, the platform with a session scoped to the
+ * binding's bucket and prefix; both read through this.
+ *
+ * A listing is the bucket's, a page of 1,000 keys at a time, in key order;
+ * of a prefix's own folder alone (a delimiter), when the sync asks. An ETag is
+ * kept without the quotes the bucket wraps it in. One file's listing is a
+ * listing of its key alone, not a HEAD: a session that may list only under
+ * its binding's prefix is answered 403 for a HEAD of a key that isn't there,
+ * not 404. Credentials that may read the file but list nothing are asked by
+ * a HEAD instead, a 404 its absence. A file is read whole, at the version its listing gave (`If-Match`
+ * its ETag): at most 1 GiB for a `file` or `latest` input, 64 MiB for a
+ * folder's file. A file changed, archived, gone or closed to the reader since
+ * it was listed is refused (`FilesUnreadableError`), the sync going on with
+ * the rest; any other refusal is thrown.
+ *
+ * Needs `@aws-sdk/client-s3`, which a solution's own code never imports: the
+ * CLI and the platform do.
+ *
+ * @packageDocumentation
+ */
+import { type S3Client } from '@aws-sdk/client-s3';
+import { type FilesReader } from '../sync/engine.js';
+/** Where a binding's files are: a bucket, and the prefix every key is relative to. */
+export interface S3Location {
+    readonly bucket: string;
+    /** `''`, or ending with `/` */
+    readonly prefix: string;
+}
+/**
+ * The reader of one bound source in its bucket.
+ *
+ * @param client - The client to read with: its credentials and region are the caller's
+ * @param location - The bucket, and the prefix the binding names
+ * @returns The reader: its keys relative to the prefix
+ */
+export declare function s3FilesReader(client: S3Client, location: S3Location): FilesReader;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/s3/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/s3/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiF,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClI,OAAO,EAA0C,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7F,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAgCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,WAAW,CAgEjF"}