astro-dev-edit 0.11.0

package/src/client/unsplash-search.ts

@@ -0,0 +1,250 @@
+import type {
+  UnsplashErrorCode,
+  UnsplashOrientation,
+  UnsplashPhoto,
+  UnsplashSearchRequest,
+  UnsplashSearchResponse,
+} from '../shared/protocol.ts';
+
+/**
+ * The Unsplash pane's search logic, with **no DOM** — debouncing, paging, and
+ * the stale-response guarding that keeps a slow first request from overwriting
+ * a newer one's results.
+ *
+ * Extracted from the pane so it can be unit-tested: the client layer has almost
+ * no automated coverage, and "typing fast produces one request whose result is
+ * the one you see" is exactly the kind of rule that breaks silently. The timer
+ * functions are injected for the same reason.
+ *
+ * Stale-response guarding uses the monotonic-generation idiom from
+ * `classify-cache.ts`: a `seq` bumped per request, and a response applied only
+ * while it is still the newest one issued.
+ */
+
+export interface SearchError {
+  code: UnsplashErrorCode | 'unknown';
+  message: string;
+  /** Whether offering a Retry makes sense. A bad key or a disabled feature
+   *  needs a settings change, not another attempt at the same call. */
+  retryable: boolean;
+}
+
+export type SearchState =
+  /** Nothing asked for yet — a blank query never fetches. */
+  | { status: 'idle' }
+  | { status: 'loading'; query: string }
+  /** Results, possibly still growing via loadMore. */
+  | {
+      status: 'ready';
+      query: string;
+      photos: UnsplashPhoto[];
+      total: number;
+      totalPages: number;
+      page: number;
+      remaining?: number;
+      /** True while a loadMore is in flight, so the button can say so without
+       *  the grid dropping back to a loading state. */
+      loadingMore: boolean;
+      /** A *page* that failed. Reported here rather than as `status: 'error'`
+       *  because the results already on screen are still good — throwing them
+       *  away to show one error message would be the wrong trade. */
+      moreError?: SearchError;
+    }
+  /** A search that succeeded and matched nothing — distinct from `ready` with
+   *  an empty array, which the pane would render as a blank grid. */
+  | { status: 'empty'; query: string }
+  | { status: 'error'; query: string; error: SearchError };
+
+export interface SearchController {
+  state(): SearchState;
+  /** Type-ahead entry point: debounced, and a blank query resets to idle. */
+  setQuery(query: string): void;
+  /** Changing orientation re-runs the current query immediately — it is a
+   *  deliberate click, not a keystroke, so it should not wait out a debounce. */
+  setOrientation(orientation: UnsplashOrientation): void;
+  orientation(): UnsplashOrientation;
+  /** Append the next page. No-op unless there is one and nothing is in flight. */
+  loadMore(): void;
+  /** Re-run the current query now, bypassing the debounce. */
+  retry(): void;
+  /** Cancel any pending debounce; in-flight responses are ignored afterwards. */
+  dispose(): void;
+}
+
+export interface SearchControllerOptions {
+  /** Performs the request. Injected so tests need no network and no api.ts. */
+  search(req: UnsplashSearchRequest): Promise<UnsplashSearchResponse>;
+  /** Called on every state transition. */
+  onState(state: SearchState): void;
+  debounceMs?: number;
+  /** Timer injection, so tests drive time rather than wait for it. Matches the
+   *  single-handle debounce idiom in `hover.ts` — no new generic utility. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+  /** Maps a rejected `search` to a typed error. Injected because the mapping
+   *  lives in `api.ts` (which owns `UnsplashError`), and this module must stay
+   *  free of anything that touches the network. */
+  toError?: (err: unknown) => SearchError;
+}
+
+const DEFAULT_DEBOUNCE_MS = 350;
+
+function defaultToError(err: unknown): SearchError {
+  return {
+    code: 'unknown',
+    message: err instanceof Error ? err.message : 'Search failed.',
+    retryable: true,
+  };
+}
+
+export function createSearchController(opts: SearchControllerOptions): SearchController {
+  const debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  const toError = opts.toError ?? defaultToError;
+
+  let current: SearchState = { status: 'idle' };
+  let query = '';
+  let orientation: UnsplashOrientation = 'any';
+  let timer: unknown = null;
+  let disposed = false;
+  // Bumped for every request issued. A response is applied only while its own
+  // seq is still the newest — so a slow early request cannot overwrite a fast
+  // later one, and dispose() invalidates everything outstanding.
+  let seq = 0;
+
+  const emit = (next: SearchState): void => {
+    current = next;
+    opts.onState(next);
+  };
+
+  const cancelPending = (): void => {
+    if (timer !== null) {
+      clearTimer(timer);
+      timer = null;
+    }
+  };
+
+  /** Issue a request for page 1, replacing whatever is shown. */
+  const run = (): void => {
+    if (disposed) return;
+    const q = query.trim();
+    if (!q) {
+      emit({ status: 'idle' });
+      return;
+    }
+    const mine = ++seq;
+    const issuedOrientation = orientation;
+    emit({ status: 'loading', query: q });
+    opts.search({ query: q, page: 1, orientation: issuedOrientation }).then(
+      (res) => {
+        if (disposed || mine !== seq) return; // superseded
+        if (!res.photos.length) {
+          emit({ status: 'empty', query: q });
+          return;
+        }
+        emit({
+          status: 'ready',
+          query: q,
+          photos: res.photos,
+          total: res.total,
+          totalPages: res.totalPages,
+          page: res.page,
+          ...(res.remaining === undefined ? {} : { remaining: res.remaining }),
+          loadingMore: false,
+        });
+      },
+      (err: unknown) => {
+        if (disposed || mine !== seq) return;
+        emit({ status: 'error', query: q, error: toError(err) });
+      },
+    );
+  };
+
+  return {
+    state: () => current,
+
+    setQuery(next) {
+      query = next;
+      cancelPending();
+      if (disposed) return;
+      // A cleared box resets immediately — waiting out a debounce to show
+      // nothing would feel broken.
+      if (!next.trim()) {
+        seq++; // abandon anything outstanding
+        emit({ status: 'idle' });
+        return;
+      }
+      timer = setTimer(() => {
+        timer = null;
+        run();
+      }, debounceMs);
+    },
+
+    setOrientation(next) {
+      if (next === orientation) return;
+      orientation = next;
+      cancelPending();
+      run();
+    },
+
+    orientation: () => orientation,
+
+    loadMore() {
+      if (disposed) return;
+      const at = current;
+      if (at.status !== 'ready' || at.loadingMore) return;
+      if (at.page >= at.totalPages) return;
+
+      const mine = ++seq;
+      const issuedQuery = at.query;
+      const issuedOrientation = orientation;
+      const nextPage = at.page + 1;
+      emit({ ...at, loadingMore: true, moreError: undefined });
+
+      opts.search({ query: issuedQuery, page: nextPage, orientation: issuedOrientation }).then(
+        (res) => {
+          if (disposed || mine !== seq) return;
+          // Appending is only valid if nothing about the search changed while
+          // the page was in flight — otherwise these are results for a
+          // different question.
+          const now = current;
+          if (
+            now.status !== 'ready' ||
+            now.query !== issuedQuery ||
+            orientation !== issuedOrientation
+          ) {
+            return;
+          }
+          emit({
+            ...now,
+            photos: [...now.photos, ...res.photos],
+            page: res.page,
+            total: res.total,
+            totalPages: res.totalPages,
+            ...(res.remaining === undefined ? {} : { remaining: res.remaining }),
+            loadingMore: false,
+          });
+        },
+        (err: unknown) => {
+          if (disposed || mine !== seq) return;
+          const now = current;
+          if (now.status !== 'ready') return;
+          // The results already on screen survive; only the button reports.
+          emit({ ...now, loadingMore: false, moreError: toError(err) });
+        },
+      );
+    },
+
+    retry() {
+      cancelPending();
+      run();
+    },
+
+    dispose() {
+      disposed = true;
+      cancelPending();
+      seq++;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,299 @@
+import type { AstroIntegration } from 'astro';
+import { createRequire } from 'node:module';
+import { join, relative, resolve, sep } from 'node:path';
+import { UNSPLASH_DEFAULT_IMPORT_WIDTH } from './shared/unsplash.ts';
+import { createAnnotatePlugin } from './server/annotate.ts';
+import { createSchemaProvider } from './server/content-config.ts';
+import { createMiddleware } from './server/middleware.ts';
+import { createPrivateFilesPlugin } from './server/private-files.ts';
+import { createRouteManifest, type ResolvedRouteLike } from './server/route-manifest.ts';
+import {
+  createOptionsResolver,
+  DEFAULTS,
+  UNSPLASH_MAX_PER_PAGE,
+  type DevEditOptions,
+} from './server/options.ts';
+import { resolveUnsplashKey } from './server/settings.ts';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * astro-dev-edit — in-browser visual content editing for the local dev server.
+ *
+ * Click-to-edit for literal text and static img src/alt in .astro templates:
+ * the client confirms each target against the server-side AST classification,
+ * and commits patch the source file directly (verified, atomic).
+ *
+ * Dev-only. The integration registers nothing for builds, so it can never reach
+ * a production bundle. See spec §8.
+ *
+ * **The option vocabulary lives in `server/options.ts`,** not here — the
+ * Settings panel resolves options per request against the settings file, so the
+ * table that declares them has to sit where both the resolver and the routes can
+ * read it. This file passes what the project actually wrote to `devEdit()`
+ * through **unmerged**: `key in userOptions` is what tells the panel an option is
+ * config-owned, and collapsing it into `DEFAULTS` here would erase exactly that.
+ */
+
+export type { DevEditOptions, UnsplashOptions, ResolvedOptions } from './server/options.ts';
+export type { EntryEditorOptions, EntryFieldOverride } from './server/content-config.ts';
+
+/** The project's installed Astro major, resolved from the project root (the
+ *  integration's own tree has no astro). null when resolution fails. */
+function detectAstroMajor(projectRoot: string): number | null {
+  try {
+    const req = createRequire(join(projectRoot, 'package.json'));
+    const version = (req('astro/package.json') as { version: string }).version;
+    const major = Number.parseInt(version.split('.')[0]!, 10);
+    return Number.isNaN(major) ? null : major;
+  } catch {
+    return null;
+  }
+}
+
+export default function devEdit(userOptions: DevEditOptions = {}): AstroIntegration {
+  // Config-setup-time options only. Both are consumed before any dev server
+  // exists — `sourceAnnotations` registers a Vite plugin — so neither can come
+  // from the settings file, and both are reported to the panel as read-only.
+  // `enabled` is additionally config-only because storing `false` there would
+  // lock the user out of the UI that set it.
+  const enabled = userOptions.enabled ?? DEFAULTS.enabled;
+  const sourceAnnotations = userOptions.sourceAnnotations ?? DEFAULTS.sourceAnnotations;
+
+  // Captured in config:setup, consumed in server:setup. Only set when we're
+  // actually running in dev with the integration enabled.
+  let active = false;
+  let projectRoot = '';
+  let base = '/';
+  /** Astro's `publicDir`, root-relative and posix-shaped. The one directory a
+   *  build copies verbatim, so it is what decides both the URL an asset is
+   *  served at and whether that URL survives the build. Read from the config
+   *  rather than assumed to be `public`. */
+  let publicDir = 'public';
+  /** Astro's own route table, for "which file is this page written in". Replaced
+   *  wholesale on every `astro:routes:resolved` and read through a thunk, never
+   *  captured: the hook re-fires on any change under `srcDir`, so a page added
+   *  mid-session has to be visible without a restart. */
+  let resolvedRoutes: readonly ResolvedRouteLike[] = [];
+
+  return {
+    name: 'astro-dev-edit',
+    hooks: {
+      'astro:config:setup': ({ command, config, injectScript, logger, updateConfig }) => {
+        // Dev server only. Bail for `astro build` / `astro preview` so nothing
+        // ships to production. (spec §4.1, §8)
+        if (command !== 'dev') return;
+
+        // Ahead of the `enabled` bail on purpose: a project that turned the
+        // editor off still has `.astro-dev-edit.json` sitting in a directory
+        // Vite serves, so "disabled" must mean no editor, not no protection.
+        // Like `createAnnotatePlugin` below this is an ordering problem, but in
+        // the middleware stack rather than the transform one — see the header
+        // of `private-files.ts` for why `configureServer` is the only seam and
+        // `server.fs.deny` is not.
+        updateConfig({ vite: { plugins: [createPrivateFilesPlugin()] } });
+
+        if (!enabled) {
+          logger.info('disabled via options.enabled — skipping');
+          return;
+        }
+        active = true;
+        projectRoot = fileURLToPath(config.root);
+        // Not normalized by Astro's schema — 'docs', '/docs' and '/docs/' are
+        // all possible, and route-manifest.ts tolerates all three.
+        base = config.base ?? '/';
+        publicDir =
+          relative(projectRoot, fileURLToPath(config.publicDir)).split(sep).join('/') || 'public';
+
+        // Upload-directory preflight. Only warns about what the *config* says:
+        // the panel enforces the same two rules on the value it stores, and a
+        // startup warning about a value the user is about to change from the UI
+        // would be noise.
+        warnAboutUploadDirs(projectRoot, publicDir, userOptions, logger);
+
+        // The whole feature rides on `data-astro-source-file` / `-loc`
+        // attributes. On Astro 5/6 the compiler emits them (dev toolbar on);
+        // on Astro ≥7 the Rust compiler doesn't
+        // (withastro/compiler-rs#96), so we inject them ourselves with a
+        // pre-compiler Vite transform. Unresolvable version → inject too:
+        // double annotation is harmless (identical values, browsers keep the
+        // first), while missing annotation kills the feature.
+        const astroMajor = detectAstroMajor(projectRoot);
+        const selfAnnotate =
+          sourceAnnotations === 'force' ||
+          (sourceAnnotations === 'auto' && (astroMajor === null || astroMajor >= 7));
+        if (selfAnnotate) {
+          updateConfig({ vite: { plugins: [createAnnotatePlugin()] } });
+          logger.info(
+            `injecting data-astro-source-* annotations (` +
+              (sourceAnnotations === 'force'
+                ? 'sourceAnnotations: "force"'
+                : `Astro ${astroMajor ?? 'unknown'} — its compiler does not emit them`) +
+              ')',
+          );
+        }
+
+        // Without self-annotation, only the dev toolbar makes Astro emit the
+        // attributes. If it's off, hover highlight and click-to-edit silently
+        // find nothing. Fail loud rather than mysteriously do nothing.
+        const toolbarEnabled = config.devToolbar?.enabled ?? true;
+        if (!toolbarEnabled && !selfAnnotate) {
+          logger.warn(
+            'the Astro dev toolbar is DISABLED, so no data-astro-source-* ' +
+              'attributes are emitted. astro-dev-edit needs them to locate ' +
+              'editable elements and will find nothing. Re-enable the dev ' +
+              'toolbar (devToolbar.enabled) or set sourceAnnotations: "force".',
+          );
+        }
+
+        // Injected on every page. `overlay.ts` is compiled by Vite because the
+        // injected code imports it by absolute path. (spec §4.1)
+        const overlayUrl = new URL('./client/overlay.ts', import.meta.url);
+        injectScript('page', `import ${JSON.stringify(fileURLToPath(overlayUrl))};`);
+
+        logger.info('edit mode available — toggle it from the admin bar at the top of the page');
+      },
+
+      // Astro's answer to "which file is this route written in", which the DOM
+      // cannot give: component tags carry no source annotation. This fires on
+      // every add/unlink/change under srcDir, so the body is an assignment and
+      // nothing else — no logging, no work per fire. The `active` guard is what
+      // keeps the integration dev-only: it is set only by a dev config:setup.
+      'astro:routes:resolved': ({ routes }: { routes: readonly ResolvedRouteLike[] }) => {
+        if (!active) return;
+        resolvedRoutes = routes;
+      },
+
+      'astro:server:setup': ({ server, logger }) => {
+        if (!active) return;
+
+        // The one seam every route reads options through. Per-request, so an
+        // option changed in the Settings panel applies to the very next call.
+        const optionsResolver = createOptionsResolver({
+          root: projectRoot,
+          configOptions: userOptions,
+        });
+
+        // Vite dev middleware exposes the edit API under /__dev-edit/. (spec §4.3)
+        server.middlewares.use(
+          createMiddleware({
+            logger,
+            root: projectRoot,
+            publicDir,
+            optionsResolver,
+            // Always constructed: the entry editor can now be switched on from
+            // the panel, so a provider built only when it started enabled would
+            // leave the feature schema-less until the next restart. The routes
+            // check the live gate themselves.
+            schemaProvider: createSchemaProvider(server, projectRoot, async () => {
+              const { options } = await optionsResolver.resolve();
+              return options.entryEditor === false ? {} : options.entryEditor;
+            }),
+            // Always constructed, like schemaProvider: the array is simply
+            // empty until the routes hook has fired, and the route then answers
+            // an explicit refusal rather than guessing at a file.
+            routeManifest: createRouteManifest({
+              root: projectRoot,
+              base,
+              routes: () => resolvedRoutes,
+            }),
+            unsplash: {
+              // Thunks, not values: both the key and the sub-options resolve
+              // per request, so anything entered through the Settings panel
+              // takes effect without a dev-server restart and nothing depends
+              // on hook ordering.
+              resolve: async () => {
+                const { options } = await optionsResolver.resolve();
+                const configKey =
+                  options.unsplash === false ? undefined : options.unsplash.accessKey;
+                return resolveUnsplashKey(projectRoot, configKey);
+              },
+              appName: async () => {
+                const { options } = await optionsResolver.resolve();
+                const o = options.unsplash;
+                return (o === false ? '' : o.appName) || 'astro-dev-edit';
+              },
+              perPage: async () => {
+                const { options } = await optionsResolver.resolve();
+                const o = options.unsplash;
+                const raw = (o === false ? undefined : o.perPage) ?? 20;
+                return Math.min(Math.max(1, Math.trunc(raw)), UNSPLASH_MAX_PER_PAGE);
+              },
+              importWidth: async () => {
+                const { options } = await optionsResolver.resolve();
+                const o = options.unsplash;
+                // Already safelisted by the resolver; the fallback is only for
+                // the feature-off shape, which never reaches an import anyway.
+                return (o === false ? undefined : o.importWidth) ?? UNSPLASH_DEFAULT_IMPORT_WIDTH;
+              },
+              enabled: async () => {
+                const { options } = await optionsResolver.resolve();
+                return options.unsplash !== false;
+              },
+            },
+          }),
+        );
+
+        if (userOptions.unsplash) {
+          if (userOptions.unsplash.accessKey) {
+            logger.warn(
+              'unsplash.accessKey is set in your Astro config. That file is ' +
+                'committed and is read by `astro build`, so the key travels ' +
+                'with the repo — prefer UNSPLASH_ACCESS_KEY in .env.local, ' +
+                'which the overlay’s Settings panel writes for you.',
+            );
+          }
+          logger.info(
+            'Unsplash photo source enabled' +
+              (userOptions.unsplash.accessKey
+                ? ''
+                : ' — add an access key from the admin bar’s Settings panel'),
+          );
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Warn when a *configured* upload directory cannot work, at startup where the
+ * user will see it.
+ *
+ * Uploads become a literal `<img src>` in the source, so anything outside
+ * `public/` is served by Vite in dev but absent from a production build and the
+ * reference 404s once deployed. The mirror-image rule holds for `image()`
+ * fields: Astro imports those assets through Vite, and `public/` files are
+ * copied verbatim rather than importable, so a `public/` target fails the
+ * collection's own schema.
+ */
+function warnAboutUploadDirs(
+  projectRoot: string,
+  publicDir: string,
+  userOptions: DevEditOptions,
+  logger: { warn(message: string): void },
+): void {
+  const uploadDir = userOptions.uploadDir;
+  if (uploadDir !== undefined) {
+    const rel = relative(projectRoot, resolve(projectRoot, uploadDir));
+    const pub = relative(projectRoot, resolve(projectRoot, publicDir));
+    if (!(rel === pub || rel.startsWith(pub + sep))) {
+      logger.warn(
+        `uploadDir "${uploadDir}" is not under ${publicDir}/ — uploaded images ` +
+          'are served in dev but will 404 in a production build. Point uploadDir ' +
+          `at a folder under ${publicDir}/.`,
+      );
+    }
+  }
+
+  const imageUploadDir = userOptions.imageUploadDir;
+  if (imageUploadDir !== undefined) {
+    const rel = relative(projectRoot, resolve(projectRoot, imageUploadDir));
+    if (!(rel === 'src' || rel.startsWith('src' + sep))) {
+      logger.warn(
+        `imageUploadDir "${imageUploadDir}" is not under src/ — Astro cannot ` +
+          'import assets from there for an image() schema field, so uploads to ' +
+          'it will fail the collection schema. Point imageUploadDir at a folder ' +
+          'under src/.',
+      );
+    }
+  }
+}