ras-stack 0.15.0 → 0.17.0

package/README.md

@@ -100,6 +100,26 @@ Applications still own their auth clients, authorization, file-route declaration
 
 Only enable `trustForwardedHeaders` behind a proxy that replaces incoming forwarded headers. Otherwise a client could choose the origin used by the check.
 
+Infrastructure boundaries can keep approved client output separate from private causes:
+
+```ts
+import { InfrastructureError, infrastructureDiagnostic, infrastructureFailure } from 'ras-stack/server'
+
+throw new InfrastructureError('smtp_unavailable', 'email is temporarily unavailable', {
+  cause: transportError,
+  retryable: true,
+})
+
+const publicFailure = infrastructureFailure(error, {
+  code: 'internal_error',
+  message: 'something went wrong',
+  retryable: false,
+})
+logger.error(infrastructureDiagnostic(error), 'infrastructure request failed')
+```
+
+Only `InfrastructureError.publicMessage` is treated as approved for clients. Unknown failures use the caller's fallback; diagnostics are for application-owned logging and telemetry, never response serialization.
+
 Browser auth flows can share failure classification and pending/error state without sharing forms or navigation:
 
 ```tsx
@@ -235,6 +255,20 @@ await startTusUpload(upload)
 
 Applications retain ownership of email templates, missing-email behavior, upload metadata, authorization, quotas, and completion processing.
 
+Production server assets can be declared in `ras-stack.assets.json` instead of appended shell copy chains:
+
+```json
+{
+  "outputDirectory": ".output/server",
+  "assets": [
+    { "source": "drizzle", "destination": "drizzle" },
+    { "source": "drizzle-postgres", "destination": "drizzle-postgres" }
+  ]
+}
+```
+
+Run `ras-stack-assets sync` after the application build and `ras-stack-assets check` before packaging. Sync replaces each declared destination, and check compares the exact file set and content. Sources stay inside the repository, destinations stay inside the output directory, overlapping destinations and symbolic links are rejected, and the application retains ownership of asset generation and contents.
+
 Stateful development servers can reuse one typed resource across HMR without application-specific `globalThis` casts:
 
 ```ts

package/dist/build/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/build/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { checkServerAssets, loadServerAssetsConfig, syncServerAssets } from './index.js';
+const command = process.argv[2];
+const configFile = process.argv[3];
+if (command !== 'check' && command !== 'sync') {
+    console.error('usage: ras-stack-assets <check|sync> [config-file]');
+    process.exitCode = 2;
+}
+else {
+    const root = process.cwd();
+    const config = await loadServerAssetsConfig(root, configFile);
+    if (command === 'sync') {
+        await syncServerAssets(root, config);
+    }
+    else {
+        const drift = await checkServerAssets(root, config);
+        for (const destination of drift)
+            console.error(`server asset drift: ${destination}`);
+        if (drift.length > 0) {
+            console.error('run ras-stack-assets sync after the production build');
+            process.exitCode = 1;
+        }
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/build/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/build/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAExF,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAClC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;IAC9C,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAA;IACnE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;AACtB,CAAC;KAAM,CAAC;IACN,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAA;IAC1B,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAC7D,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACtC,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACnD,KAAK,MAAM,WAAW,IAAI,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,uBAAuB,WAAW,EAAE,CAAC,CAAA;QACpF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAA;YACrE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { checkServerAssets, loadServerAssetsConfig, syncServerAssets } from './index.js'\n\nconst command = process.argv[2]\nconst configFile = process.argv[3]\nif (command !== 'check' && command !== 'sync') {\n  console.error('usage: ras-stack-assets <check|sync> [config-file]')\n  process.exitCode = 2\n} else {\n  const root = process.cwd()\n  const config = await loadServerAssetsConfig(root, configFile)\n  if (command === 'sync') {\n    await syncServerAssets(root, config)\n  } else {\n    const drift = await checkServerAssets(root, config)\n    for (const destination of drift) console.error(`server asset drift: ${destination}`)\n    if (drift.length > 0) {\n      console.error('run ras-stack-assets sync after the production build')\n      process.exitCode = 1\n    }\n  }\n}\n"]}

package/dist/build/index.d.ts

@@ -0,0 +1,17 @@
+export type ServerAsset = {
+    source: string;
+    destination: string;
+};
+export type ServerAssetsConfig = {
+    outputDirectory: string;
+    assets: ServerAsset[];
+};
+export declare function loadServerAssetsConfig(root: string, configFile?: string): Promise<{
+    outputDirectory: string;
+    assets: {
+        source: any;
+        destination: any;
+    }[];
+}>;
+export declare function syncServerAssets(root: string, config: ServerAssetsConfig): Promise<void>;
+export declare function checkServerAssets(root: string, config: ServerAssetsConfig): Promise<string[]>;

package/dist/build/index.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+export async function loadServerAssetsConfig(root, configFile = 'ras-stack.assets.json') {
+    const source = JSON.parse(await readFile(path.resolve(root, configFile), 'utf8'));
+    if (!source || typeof source !== 'object' || !('outputDirectory' in source) || !('assets' in source)) {
+        throw new Error(`${configFile} must contain outputDirectory and assets`);
+    }
+    if (typeof source.outputDirectory !== 'string' || !Array.isArray(source.assets)) {
+        throw new Error(`${configFile} must contain a string outputDirectory and an assets array`);
+    }
+    const assets = source.assets.map((asset, index) => {
+        if (!asset ||
+            typeof asset !== 'object' ||
+            !('source' in asset) ||
+            typeof asset.source !== 'string' ||
+            !('destination' in asset) ||
+            typeof asset.destination !== 'string') {
+            throw new Error(`${configFile} assets[${index}] must contain string source and destination paths`);
+        }
+        return { source: asset.source, destination: asset.destination };
+    });
+    return { outputDirectory: source.outputDirectory, assets };
+}
+export async function syncServerAssets(root, config) {
+    const paths = assetPaths(root, config);
+    await Promise.all(paths.map(async (asset) => {
+        await manifest(asset.source);
+        await rm(asset.destination, { force: true, recursive: true });
+        await mkdir(path.dirname(asset.destination), { recursive: true });
+        await cp(asset.source, asset.destination, { recursive: true });
+    }));
+}
+export async function checkServerAssets(root, config) {
+    const compared = await Promise.all(assetPaths(root, config).map(async (asset) => {
+        const [source, destination] = await Promise.all([manifest(asset.source), manifest(asset.destination).catch(() => undefined)]);
+        return !destination || !equalManifest(source, destination) ? asset.label : undefined;
+    }));
+    return compared.filter((destination) => destination !== undefined);
+}
+function assetPaths(root, config) {
+    const repository = path.resolve(root);
+    const output = containedPath(repository, config.outputDirectory, 'outputDirectory');
+    const assets = config.assets.map((asset, index) => ({
+        source: containedPath(repository, asset.source, `assets[${index}].source`),
+        destination: containedPath(output, asset.destination, `assets[${index}].destination`),
+        label: asset.destination,
+    }));
+    for (const [index, asset] of assets.entries()) {
+        for (const other of assets.slice(index + 1)) {
+            if (contains(asset.destination, other.destination) || contains(other.destination, asset.destination)) {
+                throw new Error(`asset destinations must not overlap: ${asset.label} and ${other.label}`);
+            }
+        }
+    }
+    return assets;
+}
+function contains(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function containedPath(parent, child, name) {
+    if (!child.trim())
+        throw new Error(`${name} must not be empty`);
+    const resolved = path.resolve(parent, child);
+    const relative = path.relative(parent, resolved);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`${name} must stay inside ${parent}`);
+    }
+    return resolved;
+}
+async function manifest(root) {
+    const files = new Map();
+    const visit = async (current) => {
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw new Error(`server assets must not contain symbolic links: ${current}`);
+        if (info.isFile()) {
+            files.set(path.relative(root, current) || '.', createHash('sha256')
+                .update(await readFile(current))
+                .digest('hex'));
+            return;
+        }
+        if (!info.isDirectory())
+            throw new Error(`server assets must contain only files and directories: ${current}`);
+        const entries = await readdir(current);
+        await Promise.all(entries.map((entry) => visit(path.join(current, entry))));
+    };
+    await visit(root);
+    return files;
+}
+function equalManifest(left, right) {
+    return left.size === right.size && [...left].every(([name, digest]) => right.get(name) === digest);
+}
+//# sourceMappingURL=index.js.map

package/dist/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto'\nimport { cp, lstat, mkdir, readFile, readdir, rm } from 'node:fs/promises'\nimport path from 'node:path'\n\nexport type ServerAsset = { source: string; destination: string }\nexport type ServerAssetsConfig = { outputDirectory: string; assets: ServerAsset[] }\n\nexport async function loadServerAssetsConfig(root: string, configFile = 'ras-stack.assets.json') {\n  const source = JSON.parse(await readFile(path.resolve(root, configFile), 'utf8')) as unknown\n  if (!source || typeof source !== 'object' || !('outputDirectory' in source) || !('assets' in source)) {\n    throw new Error(`${configFile} must contain outputDirectory and assets`)\n  }\n  if (typeof source.outputDirectory !== 'string' || !Array.isArray(source.assets)) {\n    throw new Error(`${configFile} must contain a string outputDirectory and an assets array`)\n  }\n  const assets = source.assets.map((asset, index) => {\n    if (\n      !asset ||\n      typeof asset !== 'object' ||\n      !('source' in asset) ||\n      typeof asset.source !== 'string' ||\n      !('destination' in asset) ||\n      typeof asset.destination !== 'string'\n    ) {\n      throw new Error(`${configFile} assets[${index}] must contain string source and destination paths`)\n    }\n    return { source: asset.source, destination: asset.destination }\n  })\n  return { outputDirectory: source.outputDirectory, assets } satisfies ServerAssetsConfig\n}\n\nexport async function syncServerAssets(root: string, config: ServerAssetsConfig) {\n  const paths = assetPaths(root, config)\n  await Promise.all(\n    paths.map(async (asset) => {\n      await manifest(asset.source)\n      await rm(asset.destination, { force: true, recursive: true })\n      await mkdir(path.dirname(asset.destination), { recursive: true })\n      await cp(asset.source, asset.destination, { recursive: true })\n    }),\n  )\n}\n\nexport async function checkServerAssets(root: string, config: ServerAssetsConfig) {\n  const compared = await Promise.all(\n    assetPaths(root, config).map(async (asset) => {\n      const [source, destination] = await Promise.all([manifest(asset.source), manifest(asset.destination).catch(() => undefined)])\n      return !destination || !equalManifest(source, destination) ? asset.label : undefined\n    }),\n  )\n  return compared.filter((destination) => destination !== undefined)\n}\n\nfunction assetPaths(root: string, config: ServerAssetsConfig) {\n  const repository = path.resolve(root)\n  const output = containedPath(repository, config.outputDirectory, 'outputDirectory')\n  const assets = config.assets.map((asset, index) => ({\n    source: containedPath(repository, asset.source, `assets[${index}].source`),\n    destination: containedPath(output, asset.destination, `assets[${index}].destination`),\n    label: asset.destination,\n  }))\n  for (const [index, asset] of assets.entries()) {\n    for (const other of assets.slice(index + 1)) {\n      if (contains(asset.destination, other.destination) || contains(other.destination, asset.destination)) {\n        throw new Error(`asset destinations must not overlap: ${asset.label} and ${other.label}`)\n      }\n    }\n  }\n  return assets\n}\n\nfunction contains(parent: string, child: string) {\n  const relative = path.relative(parent, child)\n  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))\n}\n\nfunction containedPath(parent: string, child: string, name: string) {\n  if (!child.trim()) throw new Error(`${name} must not be empty`)\n  const resolved = path.resolve(parent, child)\n  const relative = path.relative(parent, resolved)\n  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {\n    throw new Error(`${name} must stay inside ${parent}`)\n  }\n  return resolved\n}\n\nasync function manifest(root: string) {\n  const files = new Map<string, string>()\n  const visit = async (current: string) => {\n    const info = await lstat(current)\n    if (info.isSymbolicLink()) throw new Error(`server assets must not contain symbolic links: ${current}`)\n    if (info.isFile()) {\n      files.set(\n        path.relative(root, current) || '.',\n        createHash('sha256')\n          .update(await readFile(current))\n          .digest('hex'),\n      )\n      return\n    }\n    if (!info.isDirectory()) throw new Error(`server assets must contain only files and directories: ${current}`)\n    const entries = await readdir(current)\n    await Promise.all(entries.map((entry) => visit(path.join(current, entry))))\n  }\n  await visit(root)\n  return files\n}\n\nfunction equalManifest(left: Map<string, string>, right: Map<string, string>) {\n  return left.size === right.size && [...left].every(([name, digest]) => right.get(name) === digest)\n}\n"]}

package/dist/server/errors.d.ts

@@ -0,0 +1,23 @@
+export type InfrastructureFailure = {
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+export declare class InfrastructureError extends Error {
+    readonly code: string;
+    readonly publicMessage: string;
+    readonly retryable: boolean;
+    constructor(code: string, publicMessage: string, options?: {
+        cause?: unknown;
+        retryable?: boolean;
+    });
+}
+export declare function infrastructureFailure(error: unknown, fallback: InfrastructureFailure): InfrastructureFailure;
+export declare function safeInfrastructureError(error: unknown, fallback: InfrastructureFailure): InfrastructureError;
+export declare function infrastructureDiagnostic(error: unknown): {
+    name: string;
+    message: string;
+    code?: string | number;
+    status?: number;
+};
+export declare function errorHasCode(error: unknown, code: string | number): boolean;

package/dist/server/errors.js

@@ -0,0 +1,64 @@
+export class InfrastructureError extends Error {
+    code;
+    publicMessage;
+    retryable;
+    constructor(code, publicMessage, options = {}) {
+        super(publicMessage, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'InfrastructureError';
+        this.code = code;
+        this.publicMessage = publicMessage;
+        this.retryable = options.retryable ?? false;
+    }
+}
+export function infrastructureFailure(error, fallback) {
+    const known = findCause(error, (candidate) => candidate instanceof InfrastructureError);
+    return known ? { code: known.code, message: known.publicMessage, retryable: known.retryable } : fallback;
+}
+export function safeInfrastructureError(error, fallback) {
+    const failure = infrastructureFailure(error, fallback);
+    return new InfrastructureError(failure.code, failure.message, { cause: error, retryable: failure.retryable });
+}
+export function infrastructureDiagnostic(error) {
+    const found = findCause(error, (candidate) => candidate instanceof Error);
+    if (!found)
+        return { name: 'UnknownError', message: String(error) };
+    const code = findProperty(error, 'code', (value) => typeof value === 'string' || typeof value === 'number');
+    const status = findProperty(error, 'status', (value) => typeof value === 'number');
+    return {
+        name: found.name,
+        message: found.message,
+        ...(code === undefined ? {} : { code }),
+        ...(status === undefined ? {} : { status }),
+    };
+}
+export function errorHasCode(error, code) {
+    return findProperty(error, 'code', (value) => typeof value === 'string' || typeof value === 'number') === code;
+}
+function findCause(error, matches) {
+    let current = error;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        if (matches(current))
+            return current;
+        seen.add(current);
+        current = typeof current === 'object' && 'cause' in current ? current.cause : undefined;
+    }
+    return undefined;
+}
+function findProperty(error, property, matches) {
+    let current = error;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (typeof current !== 'object')
+            return undefined;
+        if (property in current) {
+            const value = current[property];
+            if (matches(value))
+                return value;
+        }
+        current = 'cause' in current ? current.cause : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/server/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/server/errors.ts"],"names":[],"mappings":"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","sourcesContent":["export type InfrastructureFailure = {\n  code: string\n  message: string\n  retryable: boolean\n}\n\nexport class InfrastructureError extends Error {\n  readonly code: string\n  readonly publicMessage: string\n  readonly retryable: boolean\n\n  constructor(code: string, publicMessage: string, options: { cause?: unknown; retryable?: boolean } = {}) {\n    super(publicMessage, options.cause === undefined ? undefined : { cause: options.cause })\n    this.name = 'InfrastructureError'\n    this.code = code\n    this.publicMessage = publicMessage\n    this.retryable = options.retryable ?? false\n  }\n}\n\nexport function infrastructureFailure(error: unknown, fallback: InfrastructureFailure): InfrastructureFailure {\n  const known = findCause(error, (candidate): candidate is InfrastructureError => candidate instanceof InfrastructureError)\n  return known ? { code: known.code, message: known.publicMessage, retryable: known.retryable } : fallback\n}\n\nexport function safeInfrastructureError(error: unknown, fallback: InfrastructureFailure) {\n  const failure = infrastructureFailure(error, fallback)\n  return new InfrastructureError(failure.code, failure.message, { cause: error, retryable: failure.retryable })\n}\n\nexport function infrastructureDiagnostic(error: unknown) {\n  const found = findCause(error, (candidate): candidate is Error => candidate instanceof Error)\n  if (!found) return { name: 'UnknownError', message: String(error) }\n  const code = findProperty(error, 'code', (value): value is string | number => typeof value === 'string' || typeof value === 'number')\n  const status = findProperty(error, 'status', (value): value is number => typeof value === 'number')\n  return {\n    name: found.name,\n    message: found.message,\n    ...(code === undefined ? {} : { code }),\n    ...(status === undefined ? {} : { status }),\n  }\n}\n\nexport function errorHasCode(error: unknown, code: string | number) {\n  return findProperty(error, 'code', (value): value is string | number => typeof value === 'string' || typeof value === 'number') === code\n}\n\nfunction findCause<T>(error: unknown, matches: (candidate: unknown) => candidate is T): T | undefined {\n  let current = error\n  const seen = new Set<unknown>()\n  while (current && !seen.has(current)) {\n    if (matches(current)) return current\n    seen.add(current)\n    current = typeof current === 'object' && 'cause' in current ? current.cause : undefined\n  }\n  return undefined\n}\n\nfunction findProperty<T>(error: unknown, property: string, matches: (value: unknown) => value is T): T | undefined {\n  let current = error\n  const seen = new Set<unknown>()\n  while (current && !seen.has(current)) {\n    seen.add(current)\n    if (typeof current !== 'object') return undefined\n    if (property in current) {\n      const value = current[property as keyof typeof current]\n      if (matches(value)) return value\n    }\n    current = 'cause' in current ? current.cause : undefined\n  }\n  return undefined\n}\n"]}

package/dist/server/health.d.ts

@@ -1,4 +1,7 @@
+import { type InfrastructureFailure } from './errors.js';
 export type HealthResponseOptions = {
     errorMessage?: (error: unknown) => string;
+    failure?: (error: unknown) => InfrastructureFailure;
 };
 export declare function healthResponse(check: () => Promise<void> | void, options?: HealthResponseOptions): Promise<Response>;
+export declare const databaseHealthFailure: (error: unknown) => InfrastructureFailure;

package/dist/server/health.js

@@ -1,10 +1,16 @@
+import { infrastructureFailure } from './errors.js';
 export async function healthResponse(check, options = {}) {
     try {
         await check();
         return Response.json({ ok: true });
     }
     catch (error) {
+        if (options.failure) {
+            const failure = options.failure(error);
+            return Response.json({ ok: false, error: failure.message, code: failure.code }, { status: 503 });
+        }
         return Response.json({ ok: false, error: options.errorMessage?.(error) ?? 'health check failed' }, { status: 503 });
     }
 }
+export const databaseHealthFailure = (error) => infrastructureFailure(error, { code: 'database_unavailable', message: 'database unavailable', retryable: true });
 //# sourceMappingURL=health.js.map

package/dist/server/health.js.map

@@ -1 +1 @@
-{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAiC,EAAE,OAAO,GAA0B,EAAE;IACzG,IAAI,CAAC;QACH,MAAM,KAAK,EAAE,CAAA;QACb,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,IAAI,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACrH,CAAC;AACH,CAAC","sourcesContent":["export type HealthResponseOptions = { errorMessage?: (error: unknown) => string }\n\nexport async function healthResponse(check: () => Promise<void> | void, options: HealthResponseOptions = {}) {\n  try {\n    await check()\n    return Response.json({ ok: true })\n  } catch (error) {\n    return Response.json({ ok: false, error: options.errorMessage?.(error) ?? 'health check failed' }, { status: 503 })\n  }\n}\n"]}
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAA8B,MAAM,aAAa,CAAA;AAO/E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAiC,EAAE,OAAO,GAA0B,EAAE;IACzG,IAAI,CAAC;QACH,MAAM,KAAK,EAAE,CAAA;QACb,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;QAClG,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,IAAI,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACrH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAc,EAAE,EAAE,CACtD,qBAAqB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA","sourcesContent":["import { infrastructureFailure, type InfrastructureFailure } from './errors.js'\n\nexport type HealthResponseOptions = {\n  errorMessage?: (error: unknown) => string\n  failure?: (error: unknown) => InfrastructureFailure\n}\n\nexport async function healthResponse(check: () => Promise<void> | void, options: HealthResponseOptions = {}) {\n  try {\n    await check()\n    return Response.json({ ok: true })\n  } catch (error) {\n    if (options.failure) {\n      const failure = options.failure(error)\n      return Response.json({ ok: false, error: failure.message, code: failure.code }, { status: 503 })\n    }\n    return Response.json({ ok: false, error: options.errorMessage?.(error) ?? 'health check failed' }, { status: 503 })\n  }\n}\n\nexport const databaseHealthFailure = (error: unknown) =>\n  infrastructureFailure(error, { code: 'database_unavailable', message: 'database unavailable', retryable: true })\n"]}

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export * from './canonical-host.js';
+export * from './errors.js';
 export * from './health.js';
 export * from './rpc.js';
 export * from './singleton.js';

package/dist/server/index.js

@@ -1,4 +1,5 @@
 export * from './canonical-host.js';
+export * from './errors.js';
 export * from './health.js';
 export * from './rpc.js';
 export * from './singleton.js';

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA","sourcesContent":["export * from './canonical-host.js'\nexport * from './health.js'\nexport * from './rpc.js'\nexport * from './singleton.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA","sourcesContent":["export * from './canonical-host.js'\nexport * from './errors.js'\nexport * from './health.js'\nexport * from './rpc.js'\nexport * from './singleton.js'\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -17,6 +17,7 @@
     "url": "git+https://github.com/richardsolomou/ras-stack.git"
   },
   "bin": {
+    "ras-stack-assets": "./dist/build/cli.js",
     "ras-stack-policy": "./dist/policy/cli.js"
   },
   "files": [
@@ -42,6 +43,10 @@
       "types": "./dist/email/index.d.ts",
       "default": "./dist/email/index.js"
     },
+    "./build": {
+      "types": "./dist/build/index.d.ts",
+      "default": "./dist/build/index.js"
+    },
     "./database": {
       "types": "./dist/database/index.d.ts",
       "default": "./dist/database/index.js"