Custom Adapters

import { join } from "node:path";
import {
  defineAdapter,
  type AdapterBuildContext,
  type AdapterBuildResult,
} from "@bascik/bascik/adapter";

export default defineAdapter({
  name: "custom-node",
  async build(context: AdapterBuildContext): Promise<AdapterBuildResult> {
    context.log("Building custom Node deployment bundle...");

    return {
      publicDir: join(context.outDir, "public"),
      notes: ["Custom adapter finished successfully."],
    };
  },
});

import { mkdir, copyFile } from "node:fs/promises";
import { join } from "node:path";
import {
  defineAdapter,
  type AdapterBuildContext,
  type AdapterBuildResult,
} from "@bascik/bascik/adapter";

export default defineAdapter({
  name: "custom-node",
  async build(context: AdapterBuildContext): Promise<AdapterBuildResult> {
    const { graph, outDir, distDir, log } = context;
    const publicDir = join(outDir, "public");

    log("Preparing public static files...");
    await mkdir(publicDir, { recursive: true });

    for (const relFile of graph.publicFiles) {
      const src = join(distDir, relFile);
      const dest = join(publicDir, relFile);
      await mkdir(join(dest, ".."), { recursive: true });
      await copyFile(src, dest);
    }

    return {
      publicDir,
      notes: [
        `Copied ${graph.publicFiles.length} static assets to public output directory.`,
      ],
    };
  },
});

import { copyFile, mkdir, writeFile } from "node:fs/promises";
import { basename, dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import {
  defineAdapter,
  type AdapterBuildContext,
  type AdapterBuildResult,
  type SiteGraphJob,
} from "@bascik/bascik/adapter";

/**
 * A loader for a job. An inline script is staged under `outDir/.staging/`,
 * which the build removes once the adapter returns, so it is copied next to
 * the server; a `src=` module is imported where it is.
 */
const jobLoader = async (
  job: SiteGraphJob,
  outDir: string,
): Promise<string> => {
  if (job.source.kind === "module")
    return `() => import(${JSON.stringify(pathToFileURL(job.source.path).href)})`;
  const name = basename(job.source.stagedPath);
  await mkdir(join(outDir, "jobs"), { recursive: true });
  await copyFile(job.source.stagedPath, join(outDir, "jobs", name));
  return `() => import(${JSON.stringify(`./jobs/${name}`)})`;
};

/** An object literal of loaders, keyed by `key`. */
const loaderTable = (entries: [string, string][]): string =>
  `{\n${entries.map(([key, loader]) => `  ${JSON.stringify(key)}: ${loader},`).join("\n")}\n}`;

export default defineAdapter({
  name: "custom-node",
  async build(context: AdapterBuildContext): Promise<AdapterBuildResult> {
    const { graph, outDir, distDir, log } = context;
    const publicDir = join(outDir, "public");

    log("Preparing public static files...");
    for (const relFile of graph.publicFiles) {
      const dest = join(publicDir, relFile);
      await mkdir(dirname(dest), { recursive: true });
      await copyFile(join(distDir, relFile), dest);
    }

    log("Emitting the site module and the server...");
    const pageJobs: [string, string][] = [];
    for (const page of Object.values(graph.pages))
      for (const job of Object.values(page.jobs))
        pageJobs.push([`${page.path}#${job.id}`, await jobLoader(job, outDir)]);
    const componentJobs: [string, string][] = [];
    for (const job of Object.values(graph.components?.jobs ?? {}))
      componentJobs.push([job.id, await jobLoader(job, outDir)]);
    const apiModules = graph.apiRoutes.map((route): [string, string] => [
      route.path,
      `() => import(${JSON.stringify(pathToFileURL(route.filePath).href)})`,
    ]);
    const site = [
      `export const graph = ${JSON.stringify(graph)};`,
      `export const pageJobs = ${loaderTable(pageJobs)};`,
      `export const componentJobs = ${loaderTable(componentJobs)};`,
      `export const apiModules = ${loaderTable(apiModules)};`,
    ].join("\n\n");
    await writeFile(join(outDir, "site.mjs"), `${site}\n`, "utf8");

    // The request handler is ordinary code next to this file.
    const workerPath = join(outDir, "server.mjs");
    await copyFile(
      join(dirname(fileURLToPath(import.meta.url)), "custom-node-server.mjs"),
      workerPath,
    );

    return {
      workerPath,
      publicDir,
      // server.mjs renders component tags in script output.
      components: true,
      notes: [`Run it with: node ${workerPath}`],
    };
  },
});

import { createHash } from "node:crypto";
import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import { extname, join } from "node:path";
import { Readable } from "node:stream";
import {
  InvalidApiPathError,
  applyOutputScope,
  composeBufferedResponse,
  createNameHasher,
  decodeOutputScope,
  dispatchApiHandler,
  dynamicPageHeaders,
  errorResponse,
  hasHiddenSegment,
  internalErrorPage,
  invokeLoadedWithDeadline,
  isUnsafePathname,
  matchApiRoute,
  pageLookupCandidates,
  renderFailureMessage,
  requestRoutePath,
  scriptTimeoutError,
  serverScriptOutput,
  serverScriptOutputErrorMessage,
  streamComposedResponse,
  stripAnsiEscapeCodes,
  wrapRunner,
} from "@bascik/bascik/runtime";
import { apiModules, componentJobs, graph, pageJobs } from "./site.mjs";

const publicDir = join(import.meta.dirname, "public");
const encoder = new TextEncoder();
const platform = { name: "custom-node" };

/** Scripts whose refused return value was already logged. */
const warnedRefused = new WeakSet();

/** Run one script job under the deadline and the onServerScriptError policy. */
const runJob = async (job, load, request, context, signal, timeoutMs) => {
  const result = await invokeLoadedWithDeadline(
    load,
    (mod, { signal: jobSignal }) =>
      mod.default(request, context, { signal: jobSignal }),
    { timeoutMs, signal, timeoutError: scriptTimeoutError },
  );
  let printed;
  let failure = result.error;
  if (result.ok) {
    try {
      // What the value prints, by the rule every host uses: an array joined
      // with no separator; an object, a Response or an array of Promises refused.
      printed = serverScriptOutput(result.value);
    } catch (error) {
      // The author's own toString threw while printing: the script failed.
      failure = error;
    }
  }
  if (printed) {
    if (printed.error) {
      // Production: an empty slot and one warning per script.
      if (graph.onServerScriptError !== "ignore" && !warnedRefused.has(job)) {
        warnedRefused.add(job);
        console.warn(
          serverScriptOutputErrorMessage(
            printed.error,
            request.url,
            job.owner ?? `${job.mode} script`,
            { production: true },
          ),
        );
      }
      return "";
    }
    const output = stripAnsiEscapeCodes(printed.text);
    // A component's script gets the component's scoped class names.
    const scope = decodeOutputScope(job.outputScope);
    return scope ? applyOutputScope(output, scope) : output;
  }
  // The client went away: nothing is delivered, nothing to report.
  if (result.aborted && !result.timedOut) return "";
  const message =
    `[bascik] server script error at "${new URL(request.url).pathname}":\n` +
    `${failure?.stack ?? failure}\n    in the ${job.owner}`;
  if (graph.onServerScriptError === "error") throw new Error(message);
  if (graph.onServerScriptError === "warn") console.warn(message);
  return "";
};

/** The page as an execution plan, script segments keyed by their index. */
const planFor = (page) => {
  const segments = page.segments.map((segment, index) =>
    segment.kind === "static"
      ? { kind: "static", bytes: encoder.encode(segment.text ?? "") }
      : { kind: "script", mode: page.jobs[segment.id].mode, id: String(index) },
  );
  const firstStreamIndex = segments.findIndex(
    (s) => s.kind === "script" && s.mode === "stream",
  );
  return { segments, firstStreamIndex };
};

const sha256 = (input) => createHash("sha256").update(input);
const hashName = graph.components?.manifest.identifiers
  ? createNameHasher((input) => sha256(input).digest())
  : (input) => input;

/** The page's job runner, rendering component tags in its output. */
const runnerFor = (page, plan, request, context) => {
  const run = (index, signal) => {
    const id = page.segments[Number(index)].id;
    const load = pageJobs[`${page.path}#${id}`];
    return runJob(
      page.jobs[id],
      load,
      request,
      context,
      signal,
      graph.scriptTimeoutMs,
    );
  };
  if (!graph.components) return run;
  return wrapRunner(run, plan, {
    manifest: graph.components.manifest,
    hashName,
    hashHex: (input) => sha256(input).digest("hex"),
    httpPath: requestRoutePath(request.url),
    timeoutMs: graph.scriptTimeoutMs,
    runComponentJob: (id, signal, timeoutMs) =>
      runJob(
        graph.components.jobs[id],
        componentJobs[id],
        request,
        context,
        signal,
        timeoutMs,
      ),
    externalTags: () => false,
    // A render failure (a budget, the depth limit) follows the policy too.
    onRenderError: (error) => {
      const message = renderFailureMessage(error, request.url);
      if (graph.onServerScriptError === "error") throw new Error(message);
      if (graph.onServerScriptError === "warn") console.warn(message);
    },
  });
};

const TYPES = {
  ".html": "text/html; charset=utf-8",
  ".css": "text/css; charset=utf-8",
  ".js": "text/javascript; charset=utf-8",
  ".json": "application/json",
  ".svg": "image/svg+xml",
  ".png": "image/png",
  ".ico": "image/x-icon",
};

/** A file from public/, the way a CDN would serve it. */
const serveStatic = async (pathname) => {
  for (const candidate of [
    pathname,
    `${pathname}.html`,
    `${pathname}/index.html`,
  ]) {
    try {
      const body = await readFile(join(publicDir, candidate));
      const type = TYPES[extname(candidate)] ?? "application/octet-stream";
      return new Response(body, { headers: { "content-type": type } });
    } catch {
      // Not this candidate; try the next one.
    }
  }
  // The site's own 404 page when it has one, as bascik --server does.
  const notFound = await readFile(join(publicDir, "404.html")).catch(
    () => null,
  );
  if (!notFound) return errorResponse(404, "Not Found");
  return new Response(notFound, {
    status: 404,
    headers: { "content-type": TYPES[".html"] },
  });
};

const handle = async (request, remoteIp) => {
  const url = new URL(request.url);
  let pathname;
  try {
    pathname = decodeURIComponent(url.pathname);
  } catch {
    return errorResponse(400, "Bad Request");
  }
  if (isUnsafePathname(pathname)) return errorResponse(400, "Bad Request");
  if (hasHiddenSegment(pathname)) return errorResponse(404, "Not Found");

  let api;
  try {
    api = matchApiRoute(graph.apiRoutes, pathname, url.pathname);
  } catch (error) {
    if (error instanceof InvalidApiPathError)
      return errorResponse(400, "Bad Request");
    throw error;
  }
  if (api) {
    const mod = await apiModules[api.route.path]();
    return dispatchApiHandler(
      mod,
      request,
      { params: api.params, remoteIp, platform },
      {
        timeoutMs: graph.apiTimeoutMs,
        signal: request.signal,
        onError: (message, error) => console.error(message, error ?? ""),
      },
    );
  }

  const page = pageLookupCandidates(pathname)
    .map((candidate) => graph.pages[candidate])
    .find(Boolean);
  if (!page) return serveStatic(pathname);
  const isHead = request.method === "HEAD";
  if (request.method !== "GET" && !isHead)
    return new Response("Method Not Allowed", {
      status: 405,
      headers: { allow: "GET, HEAD" },
    });

  const status = page.is404 ? 404 : 200;
  const plan = planFor(page);
  const run = runnerFor(page, plan, request, { remoteIp, platform });
  if (plan.firstStreamIndex === -1 || isHead) {
    try {
      const body = await composeBufferedResponse(plan, run, request.signal);
      const headers = dynamicPageHeaders({ contentLength: body.byteLength });
      return new Response(isHead ? null : body, { status, headers });
    } catch (error) {
      console.error(error instanceof Error ? error.message : error);
      return internalErrorPage(graph.custom500);
    }
  }
  // Server scripts settle before the status is sent; stream scripts after.
  const streamer = streamComposedResponse(plan, run, undefined, {
    signal: request.signal,
    onStreamError: (error) =>
      console.error(error instanceof Error ? error.message : error),
  });
  try {
    await streamer.ready;
  } catch (error) {
    console.error(error instanceof Error ? error.message : error);
    return internalErrorPage(graph.custom500);
  }
  const body = streamer.toReadableStream();
  return new Response(body, { status, headers: dynamicPageHeaders() });
};

const server = createServer(async (req, res) => {
  // Abort every running script when the client goes away.
  const controller = new AbortController();
  res.on("close", () => controller.abort());
  const headers = new Headers();
  for (const [name, value] of Object.entries(req.headers))
    for (const item of [value].flat())
      if (item !== undefined) headers.append(name, item);
  const method = req.method ?? "GET";
  const request = new Request(
    new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`),
    {
      method,
      headers,
      signal: controller.signal,
      ...(method === "GET" || method === "HEAD"
        ? {}
        : { body: Readable.toWeb(req), duplex: "half" }),
    },
  );
  const response = await handle(request, req.socket.remoteAddress ?? "");
  const outgoing = Object.fromEntries(response.headers);
  const cookies = response.headers.getSetCookie();
  if (cookies.length) outgoing["set-cookie"] = cookies;
  res.writeHead(response.status, outgoing);
  if (response.body) Readable.fromWeb(response.body).pipe(res);
  else res.end();
});

const port = Number(process.env.PORT ?? 3000);
server.listen(port, () => console.log(`Listening on http://localhost:${port}`));

bascik --build --target ./adapters/custom-node.ts

dist/.bascik/__adapters_custom-node_ts_602c65fd/
  public/
  jobs/
  site.mjs
  server.mjs

node dist/.bascik/__adapters_custom-node_ts_602c65fd/server.mjs

my-adapter/
  package.json
  src/
    index.ts
  README.md

import {
  defineAdapter,
  type AdapterBuildContext,
  type AdapterBuildResult,
} from "@bascik/bascik/adapter";

export interface MyAdapterOptions {
  memoryMb?: number;
  region?: string;
}

export function createAdapter(options: MyAdapterOptions = {}) {
  return defineAdapter({
    name: "my-cloud",
    async build(context: AdapterBuildContext): Promise<AdapterBuildResult> {
      context.log(
        `Building with ${options.memoryMb ?? 128}MB memory in ${options.region ?? "auto"}...`,
      );
      // Build platform bundles...
      return {
        publicDir: `${context.outDir}/public`,
      };
    },
  });
}

// Default export used when invoked via CLI: bascik --build --target my-adapter
export default createAdapter();

bascik --build --target my-adapter

// adapters/my-cloud.ts
import { createAdapter } from "my-adapter";

export default createAdapter({ memoryMb: 256, region: "eu" });

bascik --build --target ./adapters/my-cloud.ts

export interface HostingAdapter {
  name: string;
  build(context: AdapterBuildContext): Promise<AdapterBuildResult>;
}

export function defineAdapter(adapter: HostingAdapter): HostingAdapter;

export interface AdapterBuildResult {
  /** Path to primary generated handler or worker bundle. */
  workerPath?: string;
  /** Directory containing static files to deploy to static storage or CDN. */
  publicDir: string;
  /** Size in bytes of the generated worker bundle. */
  bundleBytes?: number;
  /** Informational notes or post-build instructions printed to stdout. */
  notes?: string[];
  /** True when the runtime renders component tags in script output (graph.components). */
  components?: boolean;
}

[bascik] --target my-platform: adapter "my-platform" does not declare components: true, so component tags returned by server and stream scripts are not rendered on this host and reach the client as written (.bascik/dist/components.json lists <product-card>). Upgrade the adapter, or keep component tags out of script output for this target.

export interface SiteGraph {
  base: string; // Configured site base path (default '/')
  release: string; // Deterministic release ID hash for the build
  scriptTimeoutMs: number; // Configured timeout for server scripts
  apiTimeoutMs: number; // Configured timeout for API routes
  onServerScriptError: "error" | "warn" | "ignore";
  publicFiles: string[]; // Relative paths of all static assets in dist/
  pages: Record<string, SiteGraphPage>; // Dynamic pages keyed by route path
  apiRoutes: SiteGraphApiRoute[]; // Sorted list of API route handlers
  custom500?: string; // Content or path of custom 500.html template if present
  importRoot: string; // Absolute path to project source import root
  components?: SiteGraphComponents; // Present when the build wrote .bascik/dist/components.json
  contentSecurityPolicy?: SiteGraphContentSecurityPolicy; // Present when contentSecurityPolicy is set
  responseSecurity?: ResponseSecurity; // security.headers, hsts and privateDynamicPages, resolved
  hideDotfiles?: boolean; // security.hideDotfiles (absent: true)
  stripAnsi?: boolean; // scripts.stripAnsi (absent: true)
  renderLimits?: RenderLimitsOptions; // scripts.renderLimits, every field set
}

export interface SiteGraphComponents {
  manifest: ComponentManifest; // The parsed .bascik/dist/components.json
  jobs: Record<string, SiteGraphJob>; // Server and stream scripts inside components, by job ID
}

export interface SiteGraphContentSecurityPolicy {
  policy: ContentSecurityPolicyConfig; // The contentSecurityPolicy option as configured
  hashes: Record<string, CspRouteHashes>; // Each route's inline script and style hashes
  staticRoutes: string[]; // HTTP paths of static pages, which a host serves without the runtime
}

export interface SiteGraphPage {
  path: string; // Route path, e.g. '/dashboard' or '/products/:id'
  is404: boolean; // True if this template serves custom 404s
  segments: DistPageSegment[]; // Interleaved static HTML chunks and script markers
  jobs: Record<string, SiteGraphJob>; // Map of job ID to script metadata
}

export interface DistPageSegment {
  kind: "static" | "script";
  text?: string; // HTML markup for static segment
  id?: string; // Job ID for script segment
}

export interface SiteGraphJob {
  id: string; // Unique job ID within the page
  mode: "server" | "stream"; // Blocking server script vs streaming chunk script
  source:
    | { kind: "module"; path: string }
    | { kind: "inline"; code: string; stagedPath: string };
  owner: string; // Authoring source location for diagnostic traces
  outputScope?: string; // A component's class mapping for this job's output, when the job is inside a component
}

export interface SiteGraphApiRoute {
  path: string; // URL route path, e.g. '/api/users/:id'
  filePath: string; // Absolute path to compiled handler file
  paramNames: string[]; // List of dynamic path parameters
  isDynamic: boolean; // True if route contains parameterized segments
}

import {
  composeBufferedResponse,
  dynamicPageHeaders,
  internalErrorPage,
  type ExecutionPlan,
} from "@bascik/bascik/runtime";

const encoder = new TextEncoder();
const plan: ExecutionPlan = {
  segments: page.segments.map((segment, index) =>
    segment.kind === "static"
      ? { kind: "static", bytes: encoder.encode(segment.text ?? "") }
      : {
          kind: "script",
          mode: page.jobs[segment.id!].mode,
          id: String(index),
        },
  ),
  firstStreamIndex: -1,
};
try {
  const body = await composeBufferedResponse(plan, run, request.signal);
  return new Response(body, {
    status: page.is404 ? 404 : 200,
    headers: dynamicPageHeaders({ contentLength: body.byteLength }),
  });
} catch {
  return internalErrorPage(graph.custom500);
}