@webjsdev/server 0.8.19 → 0.8.21

package/index.d.ts

@@ -312,6 +312,11 @@ export declare function resolveVendorImports(
 export declare function clearVendorCache(): void;
 /** Read a package's installed version from `node_modules`, or null. */
 export declare function getPackageVersion(pkgName: string, appDir: string): string | null;
+/** Read a package's installed `dependencies` + `peerDependencies` (hoist-aware), or null. */
+export declare function getPackageManifest(
+  pkgName: string,
+  appDir: string,
+): { dependencies: Record<string, string>; peerDependencies: Record<string, string> } | null;
 /** Resolve a list of `pkg@version` installs to importmap entries via a provider. */
 export declare function jspmGenerate(installs: string[], provider?: string): Promise<Record<string, string>>;
 /** Pin every (or the named) bare imports to `.webjs/vendor/importmap.json`. */
@@ -340,6 +345,14 @@ export declare function updatePinned(appDir: string, opts?: { from?: string }):
 export declare function readPinFile(
   appDir: string,
 ): Promise<{ imports: Record<string, string>; integrity?: Record<string, string>; provider?: string } | null>;
+/**
+ * Make the opt-in `webjs vendor pin` output committable. Heals an app's
+ * `.gitignore` when a `.webjs` exclusion would swallow the pins, and is a
+ * no-op when they are already committable. Called only from `vendor pin`.
+ */
+export declare function ensureVendorCommittable(
+  appDir: string,
+): Promise<{ ignored: boolean; patched: boolean; gitignorePath: string | null }>;
 /** Serve a downloaded `/__webjs/vendor/*` bundle file (`--download` mode). */
 export declare function serveDownloadedBundle(
   appDir: string,
@@ -349,6 +362,50 @@ export declare function serveDownloadedBundle(
 export declare const SUPPORTED_PROVIDERS: Set<string>;
 /** Normalize / validate a provider name. */
 export declare function normalizeProvider(name: string): string;
+/**
+ * Validate a produced importmap's pinned dependency graph for coherence
+ * (issue #450). For each resolved package, checks that the version pinned for
+ * every OTHER resolved package it depends on satisfies the declared range.
+ * Pure in `(imports, getManifest)`, so the same dep set yields the same verdict
+ * over a live importmap and a vendored one. Degrades to `unverified` when a
+ * manifest is unavailable.
+ */
+export declare function checkImportmapCoherence(
+  imports: Record<string, string>,
+  opts: {
+    getManifest: (
+      pkg: string,
+      version: string,
+    ) =>
+      | { dependencies?: Record<string, string>; peerDependencies?: Record<string, string> }
+      | null
+      | Promise<{ dependencies?: Record<string, string>; peerDependencies?: Record<string, string> } | null>;
+  },
+): Promise<{
+  conflicts: Array<{
+    pkg: string;
+    version: string;
+    dependsOn: string;
+    kind: 'dependency' | 'peerDependency';
+    requiredRange: string;
+    pinnedVersion: string;
+  }>;
+  unverified: Array<{ pkg: string; reason: string }>;
+  checked: number;
+}>;
+/** Extract `{ basePackage -> pinned version }` from an importmap's `imports` map. */
+export declare function extractPinnedVersions(
+  imports: Record<string, string>,
+): Map<string, string>;
+/**
+ * Does `version` satisfy the npm `range`? Pragmatic, dependency-free. Returns
+ * `null` for a range shape it cannot statically evaluate (the "could not
+ * verify" signal).
+ */
+export declare function satisfiesSemverRange(
+  version: string,
+  range: string,
+): boolean | null;
 
 // ---------------------------------------------------------------------------
 // module-graph.js
@@ -701,6 +758,43 @@ export interface ProviderConfig {
   [key: string]: unknown;
 }
 
+/**
+ * The augmentable session-user interface (#451), NextAuth/Auth.js style.
+ *
+ * It is EMPTY by default. An app declares the fields its `session`/`jwt`
+ * callbacks set (e.g. crisp sets `session.user.id = token.uid`) by augmenting
+ * it, which then types every `auth()` call globally with no cast and catches
+ * typos:
+ *
+ * ```ts
+ * declare module '@webjsdev/server' {
+ *   interface AuthUser {
+ *     id: string;
+ *     username: string;
+ *   }
+ * }
+ * ```
+ *
+ * Left un-augmented, `auth().user` falls back to `Record<string, unknown>` (see
+ * {@link ResolvedAuthUser}), so every pre-#451 app that reads `user.<field>`
+ * without declaring a shape keeps compiling unchanged. For per-instance typing
+ * instead of a global augmentation, parameterise the factory:
+ * `createAuth<MyUser>(...)`, whose `auth()` returns `{ user: MyUser }`.
+ */
+export interface AuthUser {}
+
+/**
+ * The resolved session-user shape used when `createAuth` is called WITHOUT an
+ * explicit type argument: the augmented {@link AuthUser} when an app declared
+ * one, else the open `Record<string, unknown>` (the pre-#451 default). The
+ * `keyof` probe is how the un-augmented empty interface degrades to the loose
+ * record so existing untyped code is unaffected, while an augmented interface
+ * gives precise, typo-catching fields.
+ */
+export type ResolvedAuthUser = keyof AuthUser extends never
+  ? Record<string, unknown>
+  : AuthUser;
+
 /** Auth configuration for `createAuth`. */
 export interface AuthConfig {
   providers: ProviderConfig[];
@@ -711,9 +805,15 @@ export interface AuthConfig {
   pages?: { signIn?: string; signOut?: string; error?: string };
 }
 
-/** The auth system created by `createAuth`. */
-export interface AuthInstance {
-  auth: (req?: Request) => Promise<{ user: Record<string, unknown> } | null>;
+/**
+ * The auth system created by `createAuth`. `TUser` is the resolved session-user
+ * shape; it defaults to {@link ResolvedAuthUser} (the augmented {@link AuthUser}
+ * if an app declared one, else `Record<string, unknown>`) so a module
+ * augmentation flows to every `auth()` call, and can be overridden per instance
+ * via `createAuth<MyUser>(...)`.
+ */
+export interface AuthInstance<TUser = ResolvedAuthUser> {
+  auth: (req?: Request) => Promise<{ user: TUser } | null>;
   signIn: (
     provider: string,
     data?: Record<string, unknown>,
@@ -723,8 +823,14 @@ export interface AuthInstance {
   handlers: { GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> };
 }
 
-/** Create the auth system. */
-export declare function createAuth(config: AuthConfig): AuthInstance;
+/**
+ * Create the auth system. Parameterise with the session-user shape
+ * (`createAuth<MyUser>(...)`) for per-instance typing, or augment the
+ * {@link AuthUser} interface for global typing; both make `auth().user` typed
+ * with no cast. Defaults to the open {@link AuthUser}, so existing untyped code
+ * keeps compiling unchanged.
+ */
+export declare function createAuth<TUser = ResolvedAuthUser>(config: AuthConfig): AuthInstance<TUser>;
 /** The credentials (email/password) provider. */
 export declare function Credentials(opts: Record<string, unknown>): ProviderConfig;
 /** The Google OAuth provider. */

package/index.js

@@ -21,6 +21,7 @@ export {
   resolveVendorImports,
   clearVendorCache,
   getPackageVersion,
+  getPackageManifest,
   jspmGenerate,
   pinAll,
   unpinPackage,
@@ -30,9 +31,13 @@ export {
   hasVendorPin,
   updatePinned,
   readPinFile,
+  ensureVendorCommittable,
   serveDownloadedBundle,
   SUPPORTED_PROVIDERS,
   normalizeProvider,
+  checkImportmapCoherence,
+  extractPinnedVersions,
+  satisfiesSemverRange,
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.19",
+  "version": "0.8.21",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/auth.js

@@ -192,6 +192,13 @@ export function GitHub(opts = {}) {
 
 /**
  * Create the auth system.
+ *
+ * The session-user shape is typed via the `@webjsdev/server` overlay: augment
+ * its `AuthUser` interface (NextAuth/Auth.js style) for global typing, or call
+ * `createAuth<MyUser>(...)` from TypeScript for per-instance typing. See #451
+ * and the auth recipe. This JSDoc keeps the loose runtime shape; the precise
+ * typing lives in `index.d.ts` (types-only, no runtime effect).
+ *
  * @param {AuthConfig} config
  * @returns {{
  *   auth: (req?: Request) => Promise<{ user: Record<string,unknown> }|null>,