@netlify/spark-ui 1.31.0-alpha.5 → 1.31.0-alpha.7

package/packages/drop-core/detectBuild.ts

@@ -8,23 +8,16 @@ export type BuildReason =
   | 'functions-directory';
 
 export interface BuildDetection {
-  /** True when the dropped project needs a build step and can't be served as static files. */
+  /** The drop can't be served as static files. */
   buildRequired: boolean;
   /** The signal that decided it (first match wins), or null for a plain static drop. */
   reason: BuildReason | null;
 }
 
 /**
- * Dependencies whose presence implies a build even without an explicit `build`
- * script (e.g. a framework wired through its own CLI). Not exhaustive — the
- * `build` script check below catches the common case; this is the backstop.
- *
- * The value is the framework's default publish directory, or `null` where that
- * directory isn't a fixed string we can state with confidence — Nuxt, SvelteKit,
- * Remix and Angular all resolve it from an adapter or project name. `null` means
- * "a build is required, but don't guess a publish directory": see
- * `inferBuildSettings`, which only synthesises a `netlify.toml` when it knows
- * both halves of the answer.
+ * Frameworks that imply a build even without a `build` script, mapped to their
+ * default publish dir — `null` where it isn't a fixed string (Nuxt, SvelteKit,
+ * Remix, Angular resolve theirs), meaning "build required, don't guess".
  */
 const FRAMEWORK_DEPENDENCIES = new Map<string, string | null>([
   ['astro', 'dist'],
@@ -49,11 +42,7 @@ const FRAMEWORK_DEPENDENCIES = new Map<string, string | null>([
   ['@solidjs/start', null],
 ]);
 
-/**
- * A `netlify.toml` build config: a bare `[build]` table or any of its
- * sub-tables (`[build.environment]`, `[build.processing]`, …). Anchored to the
- * line start so a `[build]` mention inside a string/comment doesn't count.
- */
+// A [build] table or sub-table, line-anchored so a mention in a comment doesn't count.
 const NETLIFY_TOML_BUILD_SECTION = /^\s*\[build(\.[\w-]+)?\]/m;
 
 /** Zero-config functions directories — their presence alone requires bundling. */
@@ -61,7 +50,7 @@ const FUNCTIONS_DIR_PREFIXES = ['/netlify/functions/', '/netlify/edge-functions/
 
 const decoder = new TextDecoder();
 
-/** Find a file at the deploy root by its normalized path (leading slash). */
+/** Root paths are normalized with a leading slash. */
 function rootFile(files: ProcessedFile[], path: string): ProcessedFile | undefined {
   return files.find(f => f.path === path);
 }
@@ -90,23 +79,14 @@ function findFrameworkDependency(pkg: Record<string, unknown>): string | null {
   return null;
 }
 
-/** True if any dependency (prod or dev) is a known build-requiring framework. */
 function hasFrameworkDependency(pkg: Record<string, unknown>): boolean {
   return findFrameworkDependency(pkg) !== null;
 }
 
 /**
- * Decide whether a dropped project needs a build. Runs on the already-read,
- * root-normalized `ProcessedFile[]` (a dropped `.zip` is expanded and the common
- * root folder stripped upstream in `readFiles`), so build config sits at the
- * deploy root, e.g. `/netlify.toml`, `/package.json`.
- *
- * The anonymous drop API only performs static deploys, so a build-required
- * project can't go through it — the consumer redirects such drops to the
- * authenticated Drop page instead. This heuristic is deliberately lightweight
- * (no framework-detection dependency): it reads the two config files and looks
- * for the zero-config functions directories. A plain static site (HTML/CSS/JS,
- * no build config) returns `{ buildRequired: false }`.
+ * Does this drop need a build? Deliberately lightweight (two config files +
+ * the functions dirs; no framework-detection dependency). Input is
+ * root-normalized by `readFiles`, so config sits at `/netlify.toml` etc.
  */
 export function detectBuild(files: ProcessedFile[]): BuildDetection {
   const toml = rootFile(files, '/netlify.toml');
@@ -165,13 +145,8 @@ const LOCKFILE_PACKAGE_MANAGERS: ReadonlyArray<readonly [string, string]> = [
   ['/package-lock.json', 'npm'],
 ];
 
-/**
- * A bare `[build]` table header at the start of a line. Stricter than
- * `NETLIFY_TOML_BUILD_SECTION` on purpose: a config with only
- * `[build.environment]` carries no command or publish directory, so it still
- * needs a `[build]` table synthesised. (TOML permits defining a super-table
- * after its sub-tables, so appending one is valid.)
- */
+// Bare [build] only — stricter than the detection regex, since a config with
+// just [build.environment] still needs a [build] table synthesised.
 const NETLIFY_TOML_BUILD_TABLE = /^\s*\[build\]/m;
 
 function detectPackageManager(files: ProcessedFile[]): string {
@@ -182,20 +157,10 @@ function detectPackageManager(files: ProcessedFile[]): string {
 }
 
 /**
- * Infer the build command and publish directory for a build-required drop, so
- * `zipFiles` can write them into a `netlify.toml` that buildbot reads.
- *
- * Deliberately conservative: it returns settings **only** when both halves are
- * known — a `build` script (which gives the command) and a recognised framework
- * with a fixed default publish directory (which gives the output). Anything else
- * returns `null`, leaving the zip without a synthesised `[build]` table so
- * buildbot's own framework detection resolves the settings instead. That matters
- * because a `[build]` table with a command but no `publish` makes buildbot
- * publish the deploy root — shipping the project's *source* rather than its
- * built output, which is worse than not guessing at all.
- *
- * Returns `null` too when the drop already declares a `[build]` table: the
- * author's own config always wins.
+ * Build settings for the synthesised netlify.toml — only when BOTH halves are
+ * known (build script → command, known framework → publish). Guessing publish
+ * wrong ships source instead of output, so `null` beats a bad guess. An
+ * author-declared [build] table always wins (also `null`).
  */
 export function inferBuildSettings(files: ProcessedFile[]): InferredBuildSettings | null {
   const toml = rootFile(files, '/netlify.toml');

package/packages/drop-core/errors.test.ts

@@ -76,7 +76,9 @@ describe('humanizeDropError', () => {
     expect(humanizeDropError(new DeployFailedError('no index.html'))).toBe(
       'Your deploy failed: no index.html'
     );
-    expect(humanizeDropError(new DeployFailedError())).toBe('Your deploy failed. Please try again.');
+    expect(humanizeDropError(new DeployFailedError())).toBe(
+      'Your deploy failed. Please try again.'
+    );
   });
 
   it('reads a fetch TypeError as a connectivity problem', () => {

package/packages/drop-core/errors.ts

@@ -1,9 +1,6 @@
 /**
- * Thrown when the user drops or picks a single loose file that Drop can't turn
- * into a site on its own — anything that isn't a `.zip` (a site archive) or an
- * HTML page (served as index.html). A folder, multiple files, a zip, or a lone
- * HTML file are all fine; any other single file is rejected rather than
- * deployed as a one-asset site (matches react-ui).
+ * A single loose file that can't stand up a site — only a zip, folder,
+ * multiple files, or a lone HTML page may deploy (matches react-ui).
  */
 export class UnsupportedDropError extends Error {
   readonly code = 'unsupported-drop';
@@ -15,12 +12,8 @@ export class UnsupportedDropError extends Error {
 }
 
 /**
- * Thrown when an authenticated path (static or build) turns out to have no
- * usable session — the short-lived upload token came back empty, or the
- * session-cookie site create was refused, so nothing was created. For static
- * drops the flow falls back to the anonymous drop + claim; builds have no
- * anonymous equivalent, so the consumer's only recourse is to send the visitor
- * through login/signup and have them drop again.
+ * The pre-mutation "no session" signal: nothing was created yet, so static
+ * drops may fall back to the anonymous flow and build drops stash + hand off.
  */
 export class NotAuthenticatedError extends Error {
   readonly code = 'not-authenticated';
@@ -32,12 +25,8 @@ export class NotAuthenticatedError extends Error {
 }
 
 /**
- * Whether an error is the pre-mutation "no session" signal, however it
- * traveled. This package ships as both raw TypeScript (`./components`) and
- * compiled dist (`./preact`, `./drop-core`), so two copies of the class can
- * coexist in one app and defeat `instanceof` — the `code` brand is the
- * copy-proof fallback. Control flow that decides whether an anonymous retry
- * is safe must use this, never a bare `instanceof`.
+ * Copy-proof check for the "no session" error — `instanceof` misses class
+ * copies from the package's other entrypoint. Fallback gates must use this.
  */
 export function isNotAuthenticatedError(err: unknown): err is NotAuthenticatedError {
   if (err instanceof NotAuthenticatedError) return true;
@@ -71,12 +60,7 @@ export class BuildCreateError extends Error {
   }
 }
 
-/**
- * The build ran and ended in `error`/`rejected`. `reason` is the API's
- * `error_message` when there is one — it's the only part of a build failure that
- * says anything actionable (a failing build command, a missing dependency), so
- * it is surfaced to the user rather than swallowed.
- */
+/** The build ran and broke. `reason` carries the API's `error_message` — the only actionable part. */
 export class BuildFailedError extends Error {
   readonly code = 'build-failed';
 
@@ -96,10 +80,7 @@ export class BuildTimeoutError extends Error {
   }
 }
 
-/**
- * A static deploy ran and ended in `error`/`rejected`. Like a build failure,
- * the API's `error_message` is the actionable part, so it travels on the error.
- */
+/** A static deploy ran and ended in `error`/`rejected`; `reason` carries the API's `error_message`. */
 export class DeployFailedError extends Error {
   readonly code = 'deploy-failed';
 
@@ -152,9 +133,7 @@ export function humanizeDropError(err: unknown): string {
   }
   if (code === 'deploy-failed') {
     const reason = (err as DeployFailedError).reason;
-    return reason
-      ? `Your deploy failed: ${reason}`
-      : 'Your deploy failed. Please try again.';
+    return reason ? `Your deploy failed: ${reason}` : 'Your deploy failed. Please try again.';
   }
 
   if (code === 'build-timeout') {

package/packages/drop-core/fileTypes.ts

@@ -1,28 +1,14 @@
 /** What we report when the browser gives us no MIME type at all. */
 const UNKNOWN_TYPE = 'application/octet-stream';
 
-/**
- * Distinct types kept per event. Deduplication alone keeps this small for a real
- * site (a handful of types across hundreds of files); the cap is a backstop so an
- * unusual folder can't push an oversized property into the analytics payload.
- */
+// Cap on distinct types per event — a backstop against oversized analytics payloads.
 const MAX_TYPES = 20;
 
 /**
- * Distinct MIME types across a drop or file-picker selection, sorted so the same
- * selection always yields the same array.
- *
- * Read from the raw `File.type` at the drop boundary rather than from
- * `ProcessedFile`s: the MIME type only exists on the original `File`, and reading
- * can throw before any `ProcessedFile` does (an unsupported single file) — the
- * very case the file type is most worth knowing about.
- *
- * Browsers leave `File.type` empty for anything they don't recognise — a dragged
- * folder, an `.exe`, an extensionless file — so those collapse to
- * `application/octet-stream` and the property never carries an empty string.
- *
- * Call this synchronously inside the drop handler: a `DataTransfer` detaches once
- * the event turn ends.
+ * Distinct, sorted MIME types of a selection. Read at the drop boundary — the
+ * type only exists on the original File, and reading can throw before any
+ * ProcessedFile exists. Call synchronously in the drop handler: a DataTransfer
+ * detaches after the event turn.
  */
 export function getFileTypes(files: FileList | null | undefined): string[] {
   if (!files?.length) return [];

package/packages/drop-core/readFiles.ts

@@ -53,15 +53,11 @@ async function readDirEntry(entry: any): Promise<ProcessedFile[]> {
 }
 
 /**
- * Read a DataTransfer from a drop event into ProcessedFiles.
- *
- * NOTE: `webkitGetAsEntry()` must be called synchronously inside the drop
- * handler — the DataTransfer is detached once the event turn ends. The
- * component captures entries first (see `readDroppedEntries`) then calls the
- * async readers, so this function is safe to `await`.
+ * Read a drop's DataTransfer into ProcessedFiles. `webkitGetAsEntry()` runs
+ * synchronously before the first await — the DataTransfer detaches once the
+ * event turn ends.
  */
 export async function readDataTransfer(dt: DataTransfer): Promise<ProcessedFile[]> {
-  // single zip?
   const first = dt.files?.[0];
   if (dt.files.length === 1 && first && isZipName(first.name)) {
     return readZip(first);
@@ -164,11 +160,8 @@ export function hasMultipleHtmlFilesWithoutIndex(files: ProcessedFile[]): boolea
 }
 
 /**
- * When the set has no index.html but exactly one HTML file (a lone page
- * alongside its assets, or a single dropped file), rename that file to
- * index.html — keeping its directory — so it is served at the site root
- * instead of 404ing. Content and sha are untouched. Any other set (already has
- * an index, multiple HTML files, or no HTML) is returned unchanged.
+ * A lone non-index HTML page is renamed to index.html (same directory,
+ * content/sha untouched) so it serves instead of 404ing. Other sets unchanged.
  */
 export function renameSingleNonIndexHtmlToIndex(files: ProcessedFile[]): ProcessedFile[] {
   const name = getSingleNonIndexHtmlFileName(files);

package/packages/drop-core/types.ts

@@ -11,10 +11,8 @@ export interface ProcessedFile {
 export type Digest = Record<string, string>; // { "/index.html": "<sha1>" }
 
 /**
- * Response body of `POST /api/v1/drop`. Not a canonical Deploy resource —
- * it's a mixed shape carrying both the anonymous site and the initial deploy
- * so the client has everything it needs to upload, poll, and hand off to the
- * user in one round trip.
+ * Response of `POST /api/v1/drop` — a mixed site+deploy shape, everything the
+ * client needs to upload, poll, and hand off in one round trip.
  */
 export interface DropResponse {
   /** site id (UUID) — surfaced to callers so they can build claim links */

package/packages/drop-core/zip.ts

@@ -13,12 +13,7 @@ function escapeTomlString(value: string): string {
     .replace(/\t/g, '\\t');
 }
 
-/**
- * Render inferred settings as a `[build]` table. Only `command` and `publish`
- * are written: everything else (functions directory, plugins, node version)
- * is zero-config on Netlify's side and guessing at it would override detection
- * that is better informed than we are.
- */
+/** Renders a [build] table — command and publish only; everything else is zero-config server-side. */
 export function generateNetlifyToml({ command, publish }: InferredBuildSettings): string {
   return [
     '[build]',
@@ -31,22 +26,14 @@ export function generateNetlifyToml({ command, publish }: InferredBuildSettings)
 export interface ZipOptions {
   /** Filename given to the produced `File`. Shows up as the build's source archive. */
   name?: string;
-  /**
-   * Synthesise a `netlify.toml` `[build]` table from `inferBuildSettings` when the
-   * drop doesn't declare one (default `true`). Set `false` to upload the files
-   * exactly as dropped and let buildbot resolve every setting itself.
-   */
+  /** Synthesise a [build] table when the drop lacks one (default true); false uploads as-dropped. */
   synthesizeNetlifyToml?: boolean;
 }
 
 export interface ZipResult {
   /** The archive, ready to hand to `createBuildFromZip`. */
   file: File;
-  /**
-   * The settings written into `netlify.toml`, or `null` when the archive is a
-   * faithful copy of the drop — either because it already declared a `[build]`
-   * table, or because nothing could be inferred with confidence.
-   */
+  /** Settings written into netlify.toml, or null when the archive is a faithful copy. */
   buildSettings: InferredBuildSettings | null;
 }
 
@@ -58,20 +45,10 @@ function toBytes(content: ArrayBuffer): Uint8Array {
 }
 
 /**
- * Zip an already-read file set into the source archive that
- * `POST /sites/{id}/builds` expects.
- *
- * The input is the same root-normalized `ProcessedFile[]` the static deploy path
- * uses (see `readFiles`), so junk — dotfiles, `node_modules`, macOS metadata — is
- * already gone and paths sit at the deploy root. Output directories (`dist/`,
- * `build/`) are deliberately *not* stripped: buildbot regenerates them when
- * there's a build command, and a drop whose `netlify.toml` publishes a committed
- * directory without a command would break if we removed it.
- *
- * When the drop needs a build but declares no `[build]` table, an inferred one is
- * written in (appended to an existing `netlify.toml`, or created if there is
- * none) so buildbot doesn't publish the project's source. See
- * `inferBuildSettings` for how conservative that inference is.
+ * Zip a read file set into the archive `POST /sites/{id}/builds` expects.
+ * Junk is already gone (readFiles); dist/build are deliberately kept — a drop
+ * publishing a committed directory without a command would break without them.
+ * A [build] table is synthesised when missing (appended, so redirects survive).
  */
 export async function zipFiles(
   files: ProcessedFile[],