npm - @makerclay/core - Versions diffs - 1.0.0 - Mend

@makerclay/core 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/LICENSE +221 -0
package/README.md +82 -0
package/package.json +52 -0
package/src/admin/listing.js +149 -0
package/src/admin/routes.js +362 -0
package/src/attic.js +168 -0
package/src/auth/can.js +79 -0
package/src/auth/csrf.js +74 -0
package/src/auth/none.js +24 -0
package/src/auth/password.js +281 -0
package/src/auth/passwords.js +79 -0
package/src/auth/rate-limit.js +66 -0
package/src/auth/sessions.js +86 -0
package/src/auth/token-lanes.js +72 -0
package/src/boot.js +120 -0
package/src/client.js +99 -0
package/src/collections/index.js +397 -0
package/src/collections/routes.js +166 -0
package/src/create-host.js +351 -0
package/src/derived/data-extractor.js +22 -0
package/src/derived/index.js +121 -0
package/src/documents/format-html.js +313 -0
package/src/documents/replace.js +257 -0
package/src/documents/root-attrs.js +171 -0
package/src/documents/serve.js +137 -0
package/src/documents/stale.js +20 -0
package/src/index.js +12 -0
package/src/inspect.js +136 -0
package/src/json-errors.js +59 -0
package/src/livesync.js +75 -0
package/src/nodes/identity.js +14 -0
package/src/nodes/names.js +57 -0
package/src/nodes/ops.js +613 -0
package/src/nodes/scanner.js +321 -0
package/src/nodes/store.js +111 -0
package/src/pages.js +166 -0
package/src/paths.js +302 -0
package/src/recovery/overlay.js +327 -0
package/src/recovery/replay.js +236 -0
package/src/recovery-ui.js +185 -0
package/src/recovery.js +30 -0
package/src/requests.js +73 -0
package/src/routes/meta.js +62 -0
package/src/routes/read.js +105 -0
package/src/routes/save.js +102 -0
package/src/routes/sync.js +118 -0
package/src/routes/upload.js +128 -0
package/src/share/index.js +207 -0
package/src/share/save-tokens.js +65 -0
package/src/spec/codes.js +42 -0
package/src/spec/meta.js +52 -0
package/src/spec/wire.js +115 -0
package/src/store/index.js +29 -0
package/src/store/migrations/001-init.sql +114 -0
package/src/store/sqlite.js +540 -0
package/src/templates.js +50 -0
package/src/tenants/index.js +355 -0
package/src/tenants/isolation.js +91 -0
package/src/tenants/routes.js +131 -0
package/src/ui.js +95 -0
package/src/util/cookies.js +26 -0
package/src/util/express.js +8 -0
package/src/util/fsx.js +205 -0
package/src/util/id.js +37 -0
package/src/util/lockfile.js +52 -0
package/src/util/locks.js +35 -0
package/src/util/multipart.js +33 -0
package/src/versions/files.js +307 -0
package/src/versions/index.js +16 -0
package/src/versions/naming.js +172 -0
package/src/versions/routes.js +91 -0
package/src/wire-compat.js +61 -0
package/ui/app.css +164 -0
package/ui/attic.html +198 -0
package/ui/dashboard.html +456 -0
package/ui/editor.html +156 -0
package/ui/error.html +18 -0
package/ui/login.html +58 -0
package/ui/records.html +173 -0
package/ui/recovery.html +152 -0
package/ui/setup.html +61 -0
package/ui/share-qr.html +44 -0
package/ui/templates/blank.html +16 -0
package/ui/templates/devlog.html +71 -0
package/ui/templates/hackable-dashboard.html +145 -0
package/ui/templates/kanban.html +85 -0
package/ui/templates/landing.html +108 -0
package/ui/templates/writer.html +50 -0
package/ui/tenants.html +172 -0
package/ui/trash.html +134 -0
package/ui/versions.html +114 -0

package/src/documents/root-attrs.js ADDED Viewed

@@ -0,0 +1,171 @@
+// Read, inject and strip attributes on a document's root <html> start tag.
+//
+// Spec §4 permits exactly two serve-time injections (the ephemeral save token
+// and the durable document identity) and forbids serving from mutating the
+// stored file, so every operation here works on a byte string and splices only
+// the spans it must. The rest of the document, and the rest of the root tag,
+// comes out byte-identical.
+//
+// The scan mirrors how a browser parses the tag: quotes only delimit in value
+// position, only ASCII whitespace separates attributes, comments end at --> or
+// --!>, and a start tag that never closes is not a root tag at all. It cannot
+// backtrack, so hostile input costs one linear pass.
+function isWs(c) {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+}
+function commentEnd(str, from) {
+  if (str[from] === '>') return from + 1;
+  if (str[from] === '-' && str[from + 1] === '>') return from + 2;
+  const len = str.length;
+  for (let k = from; k < len; k++) {
+    if (str[k] === '-' && str[k + 1] === '-') {
+      let e = k + 2;
+      if (str[e] === '!') e++;
+      if (str[e] === '>') return e + 1;
+    }
+  }
+  return -1;
+}
+export function scanRootTag(html) {
+  if (typeof html !== 'string' || html.length === 0) return null;
+  const len = html.length;
+  let i = html.charCodeAt(0) === 0xFEFF ? 1 : 0;
+  while (i < len) {
+    const c = html[i];
+    if (isWs(c)) { i++; continue; }
+    if (c !== '<') return null;
+    if (html[i + 1] === '!' && html[i + 2] === '-' && html[i + 3] === '-') {
+      const end = commentEnd(html, i + 4);
+      if (end === -1) return null;
+      i = end;
+      continue;
+    }
+    if (html[i + 1] === '!' || html[i + 1] === '?') {
+      const end = html.indexOf('>', i);
+      if (end === -1) return null;
+      i = end + 1;
+      continue;
+    }
+    break;
+  }
+  if (html.substr(i, 5).toLowerCase() !== '<html') return null;
+  const boundary = html[i + 5];
+  if (boundary === undefined || !(isWs(boundary) || boundary === '>' || boundary === '/')) return null;
+  const tagStart = i;
+  const nameEnd = i + 5;
+  i = nameEnd;
+  const attrs = [];
+  while (i < len) {
+    const leadStart = i;
+    while (i < len && (isWs(html[i]) || html[i] === '/')) i++;
+    if (i >= len) return null;
+    if (html[i] === '>') {
+      return { tagStart, nameEnd, tagEnd: i + 1, insertAt: nameEnd, attrs };
+    }
+    const nameStart = i;
+    while (i < len && !isWs(html[i]) && html[i] !== '=' && html[i] !== '>' && html[i] !== '/') i++;
+    if (i === nameStart) i++;
+    const name = html.slice(nameStart, i).toLowerCase();
+    let cursor = i;
+    while (cursor < len && isWs(html[cursor])) cursor++;
+    let value = '';
+    let attrEnd = i;
+    if (html[cursor] === '=') {
+      cursor++;
+      while (cursor < len && isWs(html[cursor])) cursor++;
+      const quote = html[cursor];
+      if (quote === '"' || quote === "'") {
+        const close = html.indexOf(quote, cursor + 1);
+        if (close === -1) return null;
+        value = html.slice(cursor + 1, close);
+        attrEnd = close + 1;
+      } else {
+        const valueStart = cursor;
+        while (cursor < len && !isWs(html[cursor]) && html[cursor] !== '>') cursor++;
+        value = html.slice(valueStart, cursor);
+        attrEnd = cursor;
+      }
+      i = attrEnd;
+    }
+    attrs.push({ name, value, leadStart, nameStart, attrEnd });
+  }
+  return null;
+}
+export function hasRootTag(html) {
+  return scanRootTag(html) !== null;
+}
+function decodeEntities(value) {
+  return String(value)
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+// First occurrence wins, matching how a browser resolves duplicate attributes.
+export function getRootAttr(html, name) {
+  const root = scanRootTag(html);
+  if (!root) return null;
+  const wanted = name.toLowerCase();
+  const hit = root.attrs.find((attr) => attr.name === wanted);
+  return hit ? decodeEntities(hit.value) : null;
+}
+export function stripRootAttrs(html, names) {
+  const root = scanRootTag(html);
+  if (!root) return html;
+  const wanted = new Set(names.map((name) => name.toLowerCase()));
+  const spans = root.attrs
+    .filter((attr) => wanted.has(attr.name))
+    .map((attr) => [attr.leadStart, attr.attrEnd])
+    .sort((a, b) => b[0] - a[0]);
+  if (!spans.length) return html;
+  let out = html;
+  for (const [from, to] of spans) out = out.slice(0, from) + out.slice(to);
+  return out;
+}
+// Serve-time injection. Attributes already present keep the document's own
+// value. Nothing durable is injected any more, so the only caller that matters
+// reaches this through setRootAttrs, which strips first.
+export function injectRootAttrs(html, values) {
+  const root = scanRootTag(html);
+  if (!root) return html;
+  const present = new Set(root.attrs.map((attr) => attr.name));
+  const additions = Object.entries(values)
+    .filter(([name, value]) => value != null && !present.has(name.toLowerCase()))
+    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
+    .join('');
+  if (!additions) return html;
+  return html.slice(0, root.insertAt) + additions + html.slice(root.insertAt);
+}
+// Replace an attribute's value even when the document already carries one. Used
+// where the host's own value must win: a document carrying a literal savetoken
+// of its own is served the host's token, never its own.
+export function setRootAttrs(html, values) {
+  let out = stripRootAttrs(html, Object.keys(values));
+  out = injectRootAttrs(out, values);
+  return out;
+}

package/src/documents/serve.js ADDED Viewed

@@ -0,0 +1,137 @@
+import path from 'upath';
+import { can, shareFor } from '../auth/can.js';
+import { PathError, decodeOnce } from '../paths.js';
+import { documentEtag } from '../spec/wire.js';
+import { setRootAttrs } from './root-attrs.js';
+import { readFileText, statIfExists } from '../util/fsx.js';
+// Document serving, realm resolution and serve-time injection.
+//
+// Invariant 3: the document root is never served statically. There is no
+// express.static(filesRoot) anywhere in the core; every read passes the gate,
+// which is what makes private-as-a-flag safe.
+//
+// Invariant 5: serving never mutates the stored file. Injection happens on the
+// response bytes only.
+const REALM_PREFIX = '~';
+export function parseRealm(urlPath) {
+  const decoded = decodeOnce(urlPath).replace(/^\/+/, '');
+  if (!decoded.startsWith(REALM_PREFIX)) return { owner: '', rest: decoded };
+  const slash = decoded.indexOf('/');
+  if (slash === -1) return { owner: decoded.slice(1), rest: '' };
+  return { owner: decoded.slice(1, slash), rest: decoded.slice(slash + 1) };
+}
+// Within a realm, an unmatched path whose longest .html-suffixed prefix resolves
+// to a real document serves that document: /blog/app.html/dashboard is the app
+// with an SPA route, not a missing file.
+function collapseSpaTail(relPath) {
+  const match = relPath.match(/^(.*?\.(?:html|htmlclay))(?:\/.*)?$/i);
+  return match ? match[1] : relPath;
+}
+export function createServe({
+  paths, nodes, config, isolation = null, saveTokens = null,
+}) {
+  const ctx = { requireAuthToRead: !!config.requireAuthToRead };
+  async function locate(owner, rest) {
+    const relPath = rest === '' ? 'index.html' : rest;
+    const candidates = [relPath];
+    const collapsed = collapseSpaTail(relPath);
+    if (collapsed !== relPath) candidates.unshift(collapsed);
+    for (const candidate of candidates) {
+      let real;
+      try {
+        real = await paths.resolveRead(owner, candidate);
+      } catch (error) {
+        if (error instanceof PathError && error.code === 'not-found') continue;
+        throw error;
+      }
+      const stat = await statIfExists(real);
+      if (!stat) continue;
+      if (stat.isDirectory()) {
+        const index = path.join(candidate, 'index.html');
+        try {
+          const indexReal = await paths.resolveRead(owner, index);
+          const indexStat = await statIfExists(indexReal);
+          if (indexStat?.isFile()) return { relPath: index, real: indexReal, stat: indexStat };
+        } catch {
+          continue;
+        }
+        continue;
+      }
+      return { relPath: candidate, real, stat };
+    }
+    return null;
+  }
+  // Gate refusals for reads are 404, shaped like a missing document. Never 403:
+  // a 403 tells a stranger the document exists.
+  async function resolveForRead(actor, urlPath) {
+    const { owner, rest } = parseRealm(urlPath);
+    if (owner && !config.features?.tenants) return null;
+    const found = await locate(owner, rest);
+    if (!found) return null;
+    const node = identify(owner, found.relPath);
+    if (!can(actor, 'read', node, ctx)) return null;
+    return { owner, node, ...found };
+  }
+  // A row if there is one, a provisional node otherwise. Reconciling a
+  // document's self-declared identity used to happen here; a file is now
+  // recognised by (dev, ino) and by its digest, in the scanner.
+  function identify(owner, relPath) {
+    return nodes.get(owner, relPath) || nodes.provisional(owner, relPath);
+  }
+  function isolationFor(node) {
+    if (!isolation) return false;
+    return isolation.isolatedFor(node);
+  }
+  // Serve-time injection. The save token exists only in the bytes sent to the
+  // browser: it is ephemeral and stripped on the way back, and nothing durable
+  // is ever written into a document.
+  async function renderDocument({ actor, node, real }) {
+    const stored = await readFileText(real);
+    const etag = documentEtag(stored);
+    const isolated = isolationFor(node);
+    const injections = {};
+    const canWrite = can(actor, 'write', node, ctx);
+    const share = shareFor(actor, node, ['edit']);
+    if (saveTokens && canWrite && (isolated || share)) {
+      const token = await saveTokens.mintFor({
+        actor,
+        node,
+        shareHash: share?.tokenHash ?? null,
+        grantKind: share?.grantKind ?? 'edit',
+      });
+      if (token) {
+        // The spec's spelling, and the one clayjs prefers. htmlclay injects
+        // `htmlclaytoken` on its own host; this one does not need to speak both.
+        injections.savetoken = token;
+      }
+    }
+    let body = stored;
+    if (Object.keys(injections).length) body = setRootAttrs(stored, injections);
+    return { body, etag, stored, node, isolated, hasToken: !!injections.savetoken };
+  }
+  return {
+    ctx,
+    locate,
+    identify,
+    resolveForRead,
+    renderDocument,
+    isolationFor,
+    parseRealm,
+  };
+}

package/src/documents/stale.js ADDED Viewed

@@ -0,0 +1,20 @@
+import { documentEtag } from '../spec/wire.js';
+// Whole-file drift detection (§11.4), layered UNDER If-Match.
+//
+// No shipping client sends If-Match, so `conditional` alone protects nobody
+// today. This is htmlclay's protection instead: the host remembers the etag of
+// the bytes it last wrote, and if the file on disk no longer matches, something
+// else changed it. The save still lands (last-write-wins is the core rule), but
+// the bytes about to be clobbered are published as a version FIRST and the
+// response carries msgType:'warning', which clayjs already renders as a distinct
+// toast. Zero client changes.
+export const DRIFT_MESSAGE =
+  'This file changed outside this tab. Your version was saved; the previous one is in Versions.';
+export function detectDrift({ storedBytes, lastKnownEtag }) {
+  if (!lastKnownEtag) return 'unknown';
+  if (storedBytes == null) return 'unknown';
+  return documentEtag(storedBytes) === lastKnownEtag ? 'match' : 'drift';
+}

package/src/index.js ADDED Viewed

@@ -0,0 +1,12 @@
+export { createHost, HOST_DEFAULTS } from './create-host.js';
+export { createSqliteStore } from './store/sqlite.js';
+export { inspectInstallation } from './inspect.js';
+export { none } from './auth/none.js';
+export { can, ACTIONS, GUEST } from './auth/can.js';
+export { createPaths, PathError, validateSegments, decodeOnce, isDocumentPath } from './paths.js';
+export { documentEtag, ifMatchSatisfied, documentUrlHeader, isJsonContentType, resolveDocumentHref } from './spec/wire.js';
+export { hostMeta, SPEC_VERSION } from './spec/meta.js';
+export { HostError, CODES } from './spec/codes.js';
+export { formatHtml, hasHtmlRoot } from './documents/format-html.js';
+export { getRootAttr, injectRootAttrs, stripRootAttrs, scanRootTag } from './documents/root-attrs.js';
+export { ulid, token } from './util/id.js';

package/src/inspect.js ADDED Viewed

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'upath';
+import { createPaths } from './paths.js';
+import { createSqliteStore } from './store/sqlite.js';
+import { createRecovery } from './recovery.js';
+import { statIfExists } from './util/fsx.js';
+// Look at an installation without touching it.
+//
+// `makerclay doctor` is documented as read-only and used to boot a whole host to
+// produce its report, which meant asking for a health check FINISHED interrupted
+// operations, could rebuild the entire database from disk, reconciled metadata,
+// reinstalled the shipped UI files, scanned every realm and left file watchers
+// running. A report that repairs is not a report, and the one moment you most
+// want to look before touching anything is the moment something has gone wrong.
+//
+// So this reads and reports, and the read-only promise is enforced rather than
+// intended:
+//
+//   - the database is opened with SQLite's own readOnly connection, which
+//     refuses writes at the driver. The normal open MIGRATES, which is a schema
+//     change no health check should make.
+//   - paths are built with `create: false`, so looking at a directory that is
+//     not an installation does not create one.
+//   - the lock file is never acquired, so this works against a RUNNING server.
+//     That is the case where booting a second host could not work at all.
+//
+// The verdict comes from `recovery.assess()`, the same function boot calls, so
+// what this predicts and what boot would do cannot drift. assess() only reads;
+// `rebuild()` is the half that writes, and is never called here.
+async function countFiles(dir) {
+  let files = 0;
+  let directories = 0;
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await fs.promises.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        directories += 1;
+        await walk(path.join(current, entry.name));
+      } else {
+        files += 1;
+      }
+    }
+  }
+  await walk(dir);
+  return { files, directories };
+}
+export async function inspectInstallation({ data, layout = 'clean', logger = console } = {}) {
+  const dataDir = path.resolve(String(data));
+  const report = {
+    dataDir,
+    exists: false,
+    running: false,
+    files: 0,
+    directories: 0,
+    nodes: null,
+    trashed: null,
+    pendingOperations: [],
+    missing: [],
+    integrity: null,
+    state: null,
+    database: 'absent',
+    warnings: [],
+  };
+  if (!(await statIfExists(dataDir))) return report;
+  report.exists = true;
+  const paths = createPaths({ data: dataDir, layout, create: false });
+  // Presence of the lock file, not ownership of it. Taking the lock is what the
+  // old implementation did, and it is why doctor refused to run against a live
+  // server; the whole point of a read-only report is that it can.
+  const lock = await statIfExists(paths.files.lock);
+  report.running = !!lock;
+  const counts = await countFiles(paths.dirs.files);
+  report.files = counts.files;
+  report.directories = counts.directories;
+  const dbFile = await statIfExists(paths.files.db);
+  if (!dbFile) {
+    report.database = 'absent';
+  } else {
+    let store = null;
+    try {
+      store = createSqliteStore({ file: paths.files.db });
+      store.open({ paths, readOnly: true });
+      report.database = 'open';
+      const integrity = store.integrityCheck();
+      report.integrity = integrity.length === 1 && integrity[0] === 'ok' ? 'ok' : integrity.join('; ');
+      report.nodes = store.listAllNodes().length;
+      report.trashed = store.listTrash().length;
+      report.pendingOperations = store.listOperations();
+      // A row whose file is gone. Read with the store's own path resolution so a
+      // tenant realm is looked for where it actually lives.
+      for (const node of store.listAllNodes()) {
+        if (node.kind === 'dir') continue;
+        const real = path.join(paths.realmRoot(node.owner || ''), node.path);
+        if (!(await statIfExists(real))) report.missing.push({ path: node.path, owner: node.owner || '' });
+      }
+      // nodes and versions are unused by assess(); it reads the store, the
+      // durable records and two directories. Passing them would mean building
+      // machinery this must not run.
+      const recovery = createRecovery({
+        paths, store, nodes: null, versions: null, clock: { now: () => Date.now() }, logger,
+      });
+      report.state = await recovery.assess();
+    } catch (error) {
+      report.database = 'unreadable';
+      report.warnings.push(
+        `The database could not be read: ${error?.message || error}. `
+        + 'Nothing was changed. The files and their history are on disk and do not depend on it.',
+      );
+    } finally {
+      try {
+        store?.close();
+      } catch {
+        // Closing a connection that never opened is not a finding.
+      }
+    }
+  }
+  return report;
+}

package/src/json-errors.js ADDED Viewed

@@ -0,0 +1,59 @@
+import { HostError, statusForCode } from './spec/codes.js';
+// Invariant 6: every response on a save-lane route is a JSON object, on every
+// status. clayjs calls res.json() unconditionally, so an HTML error page from
+// the framework turns a clean 413 into "Save failed" with no explanation.
+//
+// One formatter covers two sources at once: thrown HostErrors, which now
+// includes PathError, and body-parser failures (which arrive as errors with a
+// `type`). PathError used to need a branch of its own here that reconstructed
+// its code from its status, because it carried a status and usually no code.
+export function sendJson(res, status, body) {
+  if (res.headersSent) return res;
+  return res.status(status).json(body);
+}
+export function jsonError(res, code, msg, extra = {}) {
+  return sendJson(res, statusForCode(code), { msg, msgType: 'error', code, ...extra });
+}
+const BODY_PARSER_CODES = {
+  'entity.too.large': 'too-large',
+  'entity.parse.failed': 'bad-request',
+  'entity.verify.failed': 'bad-request',
+  'request.aborted': 'bad-request',
+  'request.size.invalid': 'bad-request',
+  'encoding.unsupported': 'unsupported-media-type',
+  'charset.unsupported': 'unsupported-media-type',
+};
+function errorToJson(error) {
+  if (error instanceof HostError) {
+    return { status: error.status, body: { msg: error.message, msgType: 'error', code: error.code } };
+  }
+  const parserCode = BODY_PARSER_CODES[error?.type];
+  if (parserCode) {
+    return {
+      status: statusForCode(parserCode),
+      body: { msg: error.message || 'Bad request', msgType: 'error', code: parserCode },
+    };
+  }
+  if (error?.status || error?.statusCode) {
+    const status = error.status || error.statusCode;
+    return { status, body: { msg: error.message || 'Request failed', msgType: 'error', code: 'bad-request' } };
+  }
+  return {
+    status: 500,
+    body: { msg: 'Internal server error', msgType: 'error', code: 'server-error' },
+  };
+}
+export function jsonErrorHandler({ logger = console } = {}) {
+  return function handleJsonError(error, req, res, next) {
+    if (res.headersSent) return next(error);
+    const { status, body } = errorToJson(error);
+    if (status >= 500) logger.error?.('[makerclay]', req.method, req.path, error);
+    return sendJson(res, status, body);
+  };
+}

package/src/livesync.js ADDED Viewed

@@ -0,0 +1,75 @@
+import pkg from 'livesync-hyperclay';
+const { liveSync } = pkg;
+// livesync-hyperclay wiring. Channel keys are namespaced
+// `${hostId}:${owner}:${path}` from day one: hyperclay-local's bare-name keys
+// cross-talk between roots, and two hosts in one process (which is how the test
+// suite stays fast) would share every channel.
+export function createLiveSync({ hostId, config, logger = console }) {
+  const keepaliveMs = config.limits?.sseKeepaliveMs ?? 30_000;
+  const open = new Set();
+  function channelKey(owner, relPath) {
+    return `${hostId}:${owner || ''}:${relPath}`;
+  }
+  function subscribe(owner, relPath, res, { lane = 'live' } = {}) {
+    const key = channelKey(owner, relPath);
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.flushHeaders?.();
+    liveSync.subscribe(key, res, { lane });
+    const keepAlive = setInterval(() => {
+      try {
+        res.write(': ping\n\n');
+      } catch {
+        clearInterval(keepAlive);
+      }
+    }, keepaliveMs);
+    keepAlive.unref?.();
+    const entry = { key, res, keepAlive };
+    open.add(entry);
+    const cleanup = () => {
+      clearInterval(keepAlive);
+      liveSync.unsubscribe(key, res);
+      open.delete(entry);
+    };
+    res.req?.on('close', cleanup);
+    res.write(': connected\n\n');
+    return cleanup;
+  }
+  function broadcast(owner, relPath, payload, options) {
+    return liveSync.broadcast(channelKey(owner, relPath), payload, options);
+  }
+  function notify(owner, relPath, payload, options) {
+    return liveSync.notify(channelKey(owner, relPath), payload, options);
+  }
+  // Revoking a share must close its open streams within one keepalive.
+  function closeChannel(owner, relPath) {
+    return liveSync.closeChannel(channelKey(owner, relPath));
+  }
+  function closeAll() {
+    for (const entry of [...open]) {
+      clearInterval(entry.keepAlive);
+      liveSync.unsubscribe(entry.key, entry.res);
+      try {
+        entry.res.end();
+      } catch {
+        logger.debug?.('[livesync] stream already closed');
+      }
+      open.delete(entry);
+    }
+  }
+  return { channelKey, subscribe, broadcast, notify, closeChannel, closeAll, stats: () => liveSync.getStats() };
+}

package/src/nodes/identity.js ADDED Viewed

@@ -0,0 +1,14 @@
+import crypto from 'node:crypto';
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+// A ULID-shaped identity derived from (owner, path). Used only when the host
+// runs with `store: null`: there are no rows to hold a minted id, so version
+// directories key off a stable hash of the path instead. Renames lose history in
+// that configuration, which is exactly what "no metadata features" means.
+export function stableId(owner, relPath) {
+  const digest = crypto.createHash('sha256').update(`${owner ?? ''}\0${relPath}`).digest();
+  let out = '';
+  for (let i = 0; i < 26; i++) out += ENCODING[digest[i] % 32];
+  return out;
+}

package/src/nodes/names.js ADDED Viewed

@@ -0,0 +1,57 @@
+import path from 'upath';
+import { statIfExists } from '../util/fsx.js';
+// What may be typed into a name box. Behavior port of hyperclay's
+// is-valid-name.js + shared/validation.js, with the platform's slug rules
+// dropped: a makerclay name is a real filename, not a subdomain label, so it
+// keeps its extension, its case and its spaces.
+// Reserved on Windows even with an extension, and a makerclay export is meant to
+// unzip anywhere. Cheap to refuse at the door, expensive to discover later.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+export function nameError(name) {
+  if (typeof name !== 'string' || name.length === 0) return 'A name is required.';
+  if (name.length > 255) return 'That name is too long.';
+  if (name === '.' || name === '..') return 'That name is reserved.';
+  if (name.startsWith('.')) return 'Names cannot start with a dot.';
+  if (/[/\\]/.test(name)) return 'Names cannot contain slashes.';
+  // eslint-disable-next-line no-control-regex
+  if (/[\0-\x1f\x7f]/.test(name)) return 'That name contains control characters.';
+  if (/[<>:"|?*]/.test(name)) return 'That name contains a character some filesystems refuse.';
+  if (name.endsWith(' ') || name.endsWith('.')) return 'Names cannot end with a space or a dot.';
+  if (WINDOWS_RESERVED.test(name)) return 'That name is reserved on some systems.';
+  return null;
+}
+export function splitName(name) {
+  const match = /^(.*?)(\.[A-Za-z0-9]{1,12}(?:\.[A-Za-z0-9]{1,12})?)$/.exec(name);
+  if (!match || !match[1]) return { stem: name, ext: '' };
+  return { stem: match[1], ext: match[2] };
+}
+// A free name in `dir`, derived from `name`. Uniqueness is decided by what is
+// actually on disk under the full filename, which is the fix for the platform
+// bug where a folder named `todo` blocked a document named `todo`: here the
+// document is `todo.html` and the two coexist, exactly as the filesystem allows.
+export async function uniqueName(dir, name, { skip = null } = {}) {
+  const { stem, ext } = splitName(name);
+  for (let n = 0; n < 1000; n++) {
+    const candidate = n === 0 ? name : `${stem}-${n + 1}${ext}`;
+    const full = path.join(dir, candidate);
+    if (full === skip) return candidate;
+    if (!(await statIfExists(full))) return candidate;
+  }
+  throw new Error(`No free name for ${name} in ${dir}`);
+}
+// The folder a document's uploads land in: `assets-<stem>/` beside the document.
+// One convention, shared by the upload lane that creates it and the tree
+// operations that have to carry it, because a document and its files are a pair
+// and two spellings of the pairing rule would drift.
+export function assetsDirFor(relPath) {
+  const dir = relPath.includes('/') ? relPath.slice(0, relPath.lastIndexOf('/')) : '';
+  const base = relPath.slice(relPath.lastIndexOf('/') + 1);
+  const folder = `assets-${base.replace(/\.[^.]*$/, '')}`;
+  return dir ? `${dir}/${folder}` : folder;
+}