@transclude/core 0.1.0

package/bin/dev.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// Hono routes; Vite compiles. The route table is the directory tree. See
+// src/routes.js for the rules.
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { getRequestListener } from '@hono/node-server';
+import { publicFiles as publicHandler } from '../src/public-files.js';
+import { createServer as createViteServer } from 'vite';
+import {
+  ACTION_METHODS,
+  hasRegion,
+  absoluteFrom,
+  methodsOf,
+  renderFragment,
+  renderRoute,
+  responseOf,
+  runAction,
+  withEnvelope,
+} from '../src/document.js';
+import { clientEntryUrl, pageModuleId } from '../src/plugin.js';
+import { resolveRoutesDir, scanRoutes } from '../src/routes.js';
+import { baseApp, endpointMethods, runEndpoint, SERVER_FILE } from '../src/server.js';
+import { randomBytes } from 'node:crypto';
+import { cookiesOf } from '../src/cookies.js';
+import { loadProject, portOf } from '../src/project.js';
+import { includeContext } from '../src/include.js';
+import { nodeLookup } from '../src/lookup.js';
+
+const { root, config } = await loadProject();
+const routesDir = resolveRoutesDir(path.join(root, config.appDir), config.routesDir);
+const PORT = portOf(config, process.env.PORT);
+
+// Built the same way the production server and the build build theirs. Dev used
+// to get only half of it, so a route include worked in production and threw
+// here.
+let include = null;
+
+/**
+ * A signing secret for this process only, when the config has none.
+ *
+ * Dev, and dev alone. Signed cookies stop working across a restart, which is a
+ * fair price for a fresh clone that runs. Production does *not* do this: a server
+ * that invents a secret invalidates every session whenever it restarts and shares
+ * none with a second instance, and finding that out in production is worse than
+ * being told at the first signed cookie.
+ */
+const cookieSecret = config.cookieSecret ?? randomBytes(32).toString('hex');
+if (!config.cookieSecret) {
+  console.log('[transclude] no cookieSecret, so signing with a random one for this process');
+}
+
+const publicRoot = config.publicDir
+  ? path.join(root, config.appDir, config.publicDir)
+  : null;
+
+// The same handler production mounts, over the source directory rather than the
+// copy in dist. Not `precompressed`: nothing has written a .br next to these yet.
+const publicFiles =
+  publicRoot && fs.existsSync(publicRoot)
+    ? publicHandler(path.relative(process.cwd(), publicRoot) || '.')
+    : null;
+
+// Built before Vite, because Vite needs it: in middleware mode with no `hmr`
+// option Vite starts its own WebSocket server on another port, the browser
+// refuses that socket as cross-origin, and every edit needs a manual reload.
+// Handing it this server puts the socket on the same origin as the page.
+const server = http.createServer();
+
+const vite = await createViteServer({
+  root,
+  appType: 'custom',
+  server: { middlewareMode: true, hmr: { server } },
+  // Vite would serve these itself, ahead of Hono, and production would serve
+  // them a different way, which is how dev and production come to disagree. One
+  // way instead: `baseApp` mounts Hono's static middleware in both.
+  publicDir: false,
+});
+
+/**
+ * What every loader and action is handed. `request` is the platform's own
+ * `Request` rather than the server's wrapper. The framework should not be the
+ * reason an author has to learn a router's API to read a form.
+ */
+const contextFor = (route, c, extra = {}) => ({
+  url: c.req.url,
+  // Only ask Hono for params when the route declares them: on the not-found
+  // path nothing matched, and c.req.param() has no stash to read.
+  params: route.params.length ? c.req.param() : {},
+  route: { id: route.id, pattern: route.pattern, path: c.req.path },
+  request: c.req.raw,
+  // The region this request asked for, or null for a whole document. An action
+  // needs it to decide whether a redirect is even an answer: post/redirect/get
+  // is right for a form, and wrong for a caller that asked for markup.
+  fragment: fragmentOf(c),
+  action: null,
+  ...withResponse(c, extra),
+});
+
+/**
+ * The envelope and the cookies that write into it, built together. The cookie
+ * helpers hold the same `response` the server will read, so a `set` in a loader
+ * lands on the way out.
+ */
+function withResponse(c, extra) {
+  const response = responseOf();
+  return {
+    response,
+    cookies: cookiesOf(c.req.raw, response, cookieSecret),
+    absolute: absoluteFrom(config.metadataBase, c.req.url),
+    ...extra,
+  };
+}
+
+/** Whatever the loaders and actions put on `ctx.response`, on the way out. */
+const sendWith = (c, { response }, html, status) => {
+  for (const [name, value] of response.headers) c.header(name, value);
+  return c.html(html, status ?? response.status);
+};
+
+const renderPage = async (route, c, status = null, extra = {}) => {
+  const page = await vite.ssrLoadModule(pageModuleId(route.id));
+  const ctx = contextFor(route, c, extra);
+
+  const html = await renderRoute(page, ctx, {
+    clientEntry: page.client.needed ? clientEntryUrl(route.id) : null,
+    // No query param: Vite content-negotiates, and a <link> sends
+    // `Accept: text/css`, so the plain path returns the stylesheet.
+    stylesheet: config.stylesheet ? `/${config.stylesheet}` : null,
+    csp: config.csp,
+    lang: config.lang,
+    include,
+  });
+  // A loader answered for itself: a redirect, or something that is not a page.
+  if (html instanceof Response) return withEnvelope(html, ctx);
+
+  return sendWith(c, ctx, await vite.transformIndexHtml(c.req.path, html), status);
+};
+
+/**
+ * The region this request is asking for, or null for the whole document. An
+ * empty value (`?fragment`) is the page's own body without its layouts.
+ */
+const fragmentOf = (c) => {
+  if (!config.fragmentParam) return null;
+  const value = c.req.query(config.fragmentParam);
+  return value === undefined ? null : value;
+};
+
+const sendFragment = async (route, c, region, extra = {}) => {
+  const page = await vite.ssrLoadModule(pageModuleId(route.id));
+  const ctx = contextFor(route, c, extra);
+  const html = await renderFragment(page, ctx, { region: region || null, include });
+
+  if (html instanceof Response) return withEnvelope(html, ctx);
+  if (html === null) return c.text(`no fragment "${region}" on ${route.rel}`, 404);
+  // No Vite transform: a fragment is inserted into a document that already ran
+  // the client entry, and injecting the HMR preamble again would run it twice.
+  return sendWith(c, ctx, html);
+};
+
+/**
+ * A form submission, or anything else that is not a GET.
+ *
+ * The action runs first, then the request is answered the same way a GET is: the
+ * whole document, or one region if the URL asked for one. That last part is what
+ * regions are for. POST a form to `?fragment=list` and what comes back is
+ * the list, already rendered, by the same compiled region the page uses.
+ */
+const handleAction = async (route, c) => {
+  const page = await vite.ssrLoadModule(pageModuleId(route.id));
+  const region = fragmentOf(c);
+
+  // Before the action, not after: a request nobody can answer should not have
+  // mutated anything on its way to saying so.
+  if (region !== null && !hasRegion(page, region)) {
+    return c.text(`no fragment "${region}" on ${route.rel}`, 404);
+  }
+
+  const ctx = contextFor(route, c);
+  const outcome = await runAction(page, ctx, c.req.method);
+
+  if (!outcome) {
+    return c.text(`${c.req.method} not allowed on ${route.rel}`, 405, {
+      Allow: methodsOf(page).join(', '),
+    });
+  }
+  if (outcome.response) return withEnvelope(outcome.response, ctx);
+
+  const extra = { action: outcome.action, cookies: ctx.cookies, response: ctx.response };
+  return region === null
+    ? renderPage(route, c, 200, extra)
+    : sendFragment(route, c, region, extra);
+};
+
+const onError = (c, err) => {
+  // Before anything reads the stack: Vite's transform means the raw one points
+  // at generated code, and a reporter given that is worse than none.
+  vite.ssrFixStacktrace(err);
+  console.error(err);
+
+  // The same seam production has, so a reporter is exercised while you are the
+  // one looking at it rather than first on a live site.
+  if (typeof config.onError === 'function') {
+    try {
+      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+    } catch (failed) {
+      console.error('[transclude] onError itself threw:', failed);
+    }
+  }
+
+  return c.text(`${err.name}: ${err.message}\n\n${err.stack ?? ''}`, 500);
+};
+
+const serverFile = path.join(root, config.appDir, SERVER_FILE);
+
+/**
+ * The app's own middleware, through Vite so an edit to it is picked up the same
+ * way an edit to a page is. Production gets the same module out of the SSR
+ * bundle instead, because that server reads `dist` and nothing else.
+ *
+ * Invalidated first, and not for tidiness: the watcher below and Vite's own
+ * invalidation are separate handlers on the same event, and if this runs before
+ * Vite's, `ssrLoadModule` hands back the module as it was. Measured: the first
+ * edit was ignored and the second appeared to work.
+ */
+async function loadMiddleware() {
+  if (!fs.existsSync(serverFile)) return null;
+
+  const url = `/${config.appDir}/${SERVER_FILE}`;
+  const node = await vite.moduleGraph.getModuleByUrl(url, true);
+  if (node) vite.moduleGraph.invalidateModule(node);
+
+  const mod = await vite.ssrLoadModule(url);
+  return mod.default ?? null;
+}
+
+async function buildApp() {
+  const { routes, endpoints, notFound } = scanRoutes(routesDir);
+
+  include = includeContext({
+    config,
+    routes,
+    pageFor: (id) => vite.ssrLoadModule(pageModuleId(id)),
+    lookup: nodeLookup(),
+  });
+  const app = baseApp({
+    csrf: config.csrf,
+    trailingSlash: config.trailingSlash,
+    publicFiles,
+    middleware: await loadMiddleware(),
+  });
+
+  // Already ordered most-specific first, so registration order is deterministic
+  // rather than something to reason about per-router.
+  for (const route of routes) {
+    app.get(route.pattern, async (c) => {
+      try {
+        const fragment = fragmentOf(c);
+        return fragment === null ? await renderPage(route, c) : await sendFragment(route, c, fragment);
+      } catch (err) {
+        return onError(c, err);
+      }
+    });
+
+    // Registered for every route rather than only the ones with an action, so
+    // a POST to a page that has none is a 405 with an `Allow` header instead of
+    // the not-found page. The URL exists, the method does not.
+    app.on(ACTION_METHODS, route.pattern, async (c) => {
+      try {
+        return await handleAction(route, c);
+      } catch (err) {
+        return onError(c, err);
+      }
+    });
+  }
+
+  // `app.all`, because "every verb" is the point: the module decides which it
+  // answers, and anything it does not is a 405 rather than a 404.
+  for (const route of endpoints) {
+    const url = '/' + path.relative(root, route.file).split(path.sep).join('/');
+    app.all(route.pattern, async (c) => {
+      try {
+        const mod = await vite.ssrLoadModule(url);
+        // The same envelope every other path gets. An endpoint that sets a
+        // cookie and returns a redirect is an ordinary thing to write, and the
+        // `Set-Cookie` was dropped without it.
+        const ctx = contextFor(route, c);
+        const out = await runEndpoint(mod, ctx, c.req.method);
+        if (out) return withEnvelope(out, ctx);
+        return c.text(`${c.req.method} not allowed on ${route.rel}`, 405, {
+          Allow: endpointMethods(mod).join(', '),
+        });
+      } catch (err) {
+        return onError(c, err);
+      }
+    });
+  }
+
+  app.notFound(async (c) => {
+    if (!notFound) return c.text('not found', 404);
+    try {
+      return await renderPage(notFound, c, 404);
+    } catch (err) {
+      return onError(c, err);
+    }
+  });
+
+  console.log(
+    `[routes]\n${[...routes, ...endpoints].map((r) => `  ${r.pattern.padEnd(24)} ${r.rel}`).join('\n')}` +
+      (notFound ? `\n  ${'(not found)'.padEnd(24)} ${notFound.rel}` : ''),
+  );
+
+  return app;
+}
+
+let app = await buildApp();
+
+// Adding or removing a page changes the route table, not just a module.
+vite.watcher.on('all', async (event, file) => {
+  // `.js` as well as `.html`: an endpoint is a route too, and watching only for
+  // pages meant adding one needed a restart, with a 404 as the only hint.
+  const extension = path.extname(file);
+  const routing =
+    file.startsWith(routesDir) &&
+    (extension === '.html' || extension === '.js') &&
+    event !== 'change';
+  // Middleware is registered once when the app is built, so a change to it needs
+  // the app rebuilt, unlike a page, which is loaded per request.
+  if (!routing && file !== serverFile) return;
+  try {
+    app = await buildApp();
+  } catch (err) {
+    console.error(err.message);
+  }
+});
+
+const hono = getRequestListener((request) => app.fetch(request));
+
+// Vite owns /@id/, /@vite/client and /src/*; Hono gets everything else.
+server.on('request', (req, res) => {
+  vite.middlewares(req, res, () => hono(req, res));
+});
+
+server.listen(PORT, () => {
+  console.log(`http://localhost:${PORT}`);
+});

package/bin/release.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Prepares a release. It does not publish: it sets the version in both packages,
+// runs everything, and writes a tag. Pushing that tag is what publishes, and
+// that happens in CI where the token lives and provenance can be signed.
+//
+// Both packages move together and share a version. They are one project split
+// for a packaging reason, and a new project's dependency on `@transclude/core`
+// is written by `@transclude/create` from its own version, so two numbers that
+// drift would write a dependency that does not exist.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const MANIFESTS = ['package.json', 'create/package.json'];
+
+const run = (command, args, options = {}) =>
+  execFileSync(command, args, { cwd: root, encoding: 'utf8', stdio: 'pipe', ...options });
+
+const read = (rel) => JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+
+function usage() {
+  return [
+    'Usage: node bin/release.js <version|major|minor|patch> [--dry-run]',
+    '',
+    '  Sets the version in both packages, verifies, commits and tags.',
+    '  Pushing the tag is what publishes. Nothing here talks to a registry.',
+    '',
+  ].join('\n');
+}
+
+/** `1.2.3`, or what `major`/`minor`/`patch` makes of the current one. */
+function nextVersion(current, asked) {
+  if (/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(asked)) return asked;
+
+  const [major, minor, patch] = current.split('.').map(Number);
+  if (asked === 'major') return `${major + 1}.0.0`;
+  if (asked === 'minor') return `${major}.${minor + 1}.0`;
+  if (asked === 'patch') return `${major}.${minor}.${patch + 1}`;
+
+  throw new Error(`${JSON.stringify(asked)} is not a version or major/minor/patch`);
+}
+
+/**
+ * Refuses to release from a tree that is not exactly what was tested.
+ *
+ * A dirty tree means the tag would name a commit that does not hold what was
+ * verified, and the tarball CI builds comes from the tag rather than from here.
+ */
+function assertReleasable() {
+  if (run('git', ['status', '--porcelain']).trim()) {
+    throw new Error('the working tree has changes. Commit or stash them first.');
+  }
+
+  const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+  if (branch !== 'main') throw new Error(`on ${branch}, and a release is cut from main`);
+
+  return read('package.json').version;
+}
+
+/**
+ * Refuses a version that already has a tag.
+ *
+ * Re-tagging is how two different tarballs come to claim one version: the
+ * registry keeps the first and the tag names the second, and nothing afterwards
+ * says which one anybody installed.
+ */
+function assertUntagged(version) {
+  const tags = run('git', ['tag', '--list']).split('\n').map((t) => t.trim());
+  if (tags.includes(`v${version}`)) {
+    throw new Error(`v${version} is already tagged. Releasing it again would move the tag.`);
+  }
+}
+
+function setVersion(version) {
+  for (const rel of MANIFESTS) {
+    const file = path.join(root, rel);
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    manifest.version = version;
+    fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+}
+
+/** Everything, in the order that fails cheapest first. */
+function verify() {
+  const steps = [
+    // `check:src` is not here. It exits non-zero on any diagnostic, and most of
+    // what it reports is a pattern TypeScript cannot model rather than a defect.
+    // The part that is a gate is a test, and `npm test` runs it.
+    ['the framework', 'npm', ['test']],
+    ['the demo', 'npm', ['run', 'test:examples']],
+    ['the docs', 'npm', ['test', '--prefix', 'docs']],
+    ['the docs types', 'npm', ['run', 'check', '--prefix', 'docs']],
+    ['the docs build', 'npm', ['run', 'build', '--prefix', 'docs']],
+  ];
+
+  for (const [what, command, args] of steps) {
+    process.stdout.write(`  ${what} … `);
+    try {
+      run(command, args);
+      process.stdout.write('ok\n');
+    } catch (error) {
+      process.stdout.write('failed\n\n');
+      throw new Error(`${what} failed:\n\n${error.stdout ?? ''}${error.stderr ?? ''}`);
+    }
+  }
+}
+
+/** What each package would ship, so a missing `files` entry is seen before a tag. */
+function packed() {
+  for (const dir of [root, path.join(root, 'create')]) {
+    const listing = run('npm', ['pack', '--dry-run', '--json'], { cwd: dir });
+    const [{ name, files }] = JSON.parse(listing);
+    process.stdout.write(`  ${name}: ${files.length} files\n`);
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const asked = args.find((a) => !a.startsWith('-'));
+
+  if (!asked || args.includes('--help')) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const current = assertReleasable();
+  const version = nextVersion(current, asked);
+  assertUntagged(version);
+  process.stdout.write(`\n${current} -> ${version}\n\n`);
+
+  setVersion(version);
+
+  try {
+    verify();
+    packed();
+  } catch (error) {
+    // Put the versions back. A failed release should leave nothing behind.
+    setVersion(current);
+    throw error;
+  }
+
+  if (dryRun) {
+    setVersion(current);
+    process.stdout.write('\nDry run. Versions put back, nothing committed.\n\n');
+    return;
+  }
+
+  run('git', ['add', ...MANIFESTS]);
+
+  // A first release at the version the manifests already carry changes nothing,
+  // and an empty commit is not worth making. The tag is the release either way.
+  const staged = run('git', ['diff', '--cached', '--name-only']).trim();
+  if (staged) run('git', ['commit', '-m', `Release ${version}`]);
+
+  run('git', ['tag', '-a', `v${version}`, '-m', `Release ${version}`]);
+
+  process.stdout.write(
+    [
+      `\nTagged v${version}. Nothing has been published yet.\n\n`,
+      '  git push --follow-tags\n\n',
+      'That is what publishes. The workflow builds from the tag and signs\n',
+      'provenance against it.\n\n',
+    ].join(''),
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`\n${error.message}\n`);
+  process.exitCode = 1;
+}

package/bin/serve.bun.js

@@ -0,0 +1,15 @@
+// Bun adapter. `bun framework/bin/serve.bun.js`
+//
+// Bun serves whatever a module default-exports with a `fetch`, so there is no
+// listener to write. The app already is one.
+
+import { app, noBuild, port, summary } from '../src/production.js';
+
+if (noBuild) {
+  console.error('No build found. Run `npm run build` first.');
+  process.exit(1);
+}
+
+summary(port);
+
+export default { fetch: app.fetch, port };

package/bin/serve.deno.js

@@ -0,0 +1,15 @@
+// Deno adapter. `deno run -A framework/bin/serve.deno.js`
+//
+// `Deno.serve` takes the same (Request) => Response the other two do.
+
+import { app, noBuild, port as configured, summary } from '../src/production.js';
+
+if (noBuild) {
+  console.error('No build found. Run `npm run build` first.');
+  Deno.exit(1);
+}
+
+// Deno reads its own environment, so PORT is applied here rather than
+// through the `process` shim.
+const port = Number(Deno.env.get('PORT') ?? configured);
+Deno.serve({ port, onListen: () => summary(port) }, app.fetch);

package/bin/serve.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Node adapter. The app is in src/production.js; this listens with it.
+
+import { serve } from '@hono/node-server';
+import { app, noBuild, port, summary } from '../src/production.js';
+
+if (noBuild) {
+  console.error('No build found. Run `npm run build` first.');
+  process.exit(1);
+}
+
+serve({ fetch: app.fetch, port }, ({ port }) => summary(port));