@makerclay/core 1.0.0

package/LICENSE

@@ -0,0 +1,221 @@
+First Million Stays Yours License
+Version 1.0
+
+Copyright (c) 2026 Hyperspace Systems LLC
+
+----------------------------------------------------------------------
+LICENSE DETAILS FOR THIS RELEASE
+
+  Software:             @makerclay/core 1.0.0
+  Released:             2026-08-20
+  MIT Conversion Date:  2028-02-20  (18 months after release)
+
+  Licensor:             Hyperspace Systems LLC, and its successors
+                        and assigns
+  Payment, program, plain answers:  https://hyperclay.com/host-program
+  Questions, notices, Coverage Certificates:  license@hyperclay.com
+  SPDX identifier:      LicenseRef-First-Million-Stays-Yours-1.0
+                        (MIT after the Conversion Date)
+  Where to start:       Section 1.
+----------------------------------------------------------------------
+
+
+1. THE CONDITION, AND WHO IT NEVER REACHES
+
+This license gives You every right the MIT License gives You,
+granted in Section 2, on one condition beyond MIT's: if products
+and services that contain the Software, derive from it, or provide
+its functionality to others by running it bring You, together with
+every entity under common control with You, more than
+US $1,000,000 in a calendar year, You pay Licensor 3% of the
+amount above US $1,000,000. Almost nobody owes it. Where the
+Software is one component of something larger, only the share
+fairly attributable to it counts.
+
+Under that line You owe nothing and condition (b) of Section 2 is
+satisfied for the year with no act on Your part: nothing to pay,
+report, register, or notify. Keep the copyright notice in copies,
+as condition (a) requires, and You are finished with this license.
+The line is tested year by year, so look again once a year. If You
+are not sure whether something You sell is covered, Section 5
+makes the answer free and binding within 30 days.
+
+Crossing the line never makes the first US $1,000,000 payable,
+never reaches back into an earlier year, and never ends this
+license. Sections 4 through 6 say how Covered Revenue is counted
+and the fee is paid. This section describes the condition; Section
+2 states it and Sections 4 through 6 measure it. Where this
+section and those differ, those govern, and nothing in this
+section creates an obligation they do not.
+
+
+2. GRANT AND CONDITIONS
+
+Permission is hereby granted, free of charge except as condition (b)
+below provides, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+  (a) The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.
+
+  (b) If in a calendar year the Covered Revenue of You and every
+      entity under common control with You exceeds US $1,000,000,
+      You shall pay Licensor 3% of the amount above US $1,000,000,
+      as Section 6 provides. "Covered Revenue" is receipts from
+      products and services You supply that themselves contain the
+      Software, are derived from it, or provide its functionality
+      to others by running it, less refunds, chargebacks, and
+      transaction taxes, attributed as Section 4 provides.
+      Otherwise this condition is satisfied for the year with no
+      act on Your part.
+
+Both (a) and (b) are conditions of this grant, not independent
+covenants. Exercising the rights granted here without satisfying
+them, subject to the cure and good-faith provisions of Section 6, is
+outside the scope of this license.
+
+In this license, the "Software" is the version of the work identified
+in the License Details above, in source or binary form, including
+modifications of it and works derived from it; a work is derived
+from the Software only if it would infringe copyright in the
+Software without this license; the "Package" is the software line of
+which this Software is one version; and "You" means the person or
+legal entity exercising these rights.
+
+
+3. CONVERSION TO THE MIT LICENSE
+
+On the MIT Conversion Date stated above, this version of the
+Software becomes licensed to everyone under the MIT License,
+automatically and without notice or any further act. That happens by
+operation of this text. On that date:
+
+  (a) in Section 2, the words "free of charge except as condition
+      (b) below provides" read simply "free of charge";
+
+  (b) in Section 2, condition (b), the label "(a)", the paragraph
+      beginning "Both (a) and (b)", and the paragraph beginning "In
+      this license" are deleted;
+
+  (c) Section 1 and Sections 4 through 6 cease to have effect;
+
+  (d) this Section 3 ceases to have effect, the conversion it makes
+      having already taken effect irrevocably; and
+
+  (e) the License Details block, the section headings, and the
+      section numbering become a record of this release and have no
+      operative effect.
+
+What then remains, Section 2 as amended and the disclaimer in
+Section 7, under the copyright notice above, is the MIT License
+(SPDX identifier: MIT), word for word. From that date copies of this
+version may also carry the standard MIT License text in place of
+this document.
+
+This conversion is automatic, unconditional, and irrevocable, and
+binds Licensor and its successors and assigns. It takes effect
+whether or not Licensor republishes this version under a separate
+MIT license file.
+
+The same conversion happens immediately, without notice or any
+further act, if for any period of 12 consecutive months Licensor
+neither makes a public release of the Package nor provides any
+security response to a responsibly reported vulnerability in it, or
+if Licensor ceases business operations without a successor that
+assumes this license.
+
+The terms of this license, including the MIT Conversion Date, are
+fixed for this version of the Software at its release and will never
+change. Later versions of the Package may ship under revised terms;
+revised terms apply only to those later versions, never
+retroactively.
+
+
+4. COUNTING COVERED REVENUE
+
+"Control" means (i) the power, direct or indirect, to cause the
+direction or management of an entity, whether by contract or
+otherwise, (ii) ownership of fifty percent (50%) or more of an
+entity's outstanding shares, or (iii) beneficial ownership of an
+entity. Aggregation across common control exists solely to prevent
+splitting one business across entities to multiply the
+US $1,000,000 exemption; there is no other affiliate test in this
+license. Aggregated Covered Revenue is counted once, and one
+self-certification and payment by any of the aggregated entities
+discharges condition (b) and Section 6 for all of them.
+
+The fee is charged at most once for a product or service. It never
+stacks across Licensor's other packages under this License used
+together in one offering, across versions of the Software, or across
+copies and instances, and revenue counted once under this or any other
+First Million Stays Yours License is never counted again.
+
+If the Software, a work derived from it, or a product or service
+that contains it is one component of a larger product, service,
+bundle, or subscription, whether or not that component is
+separately priced or sold, its Covered Revenue is the portion of
+the receipts fairly attributable to that component: its actual
+standalone price if You also sell it on a standalone basis;
+otherwise, any reasonable allocation method You apply consistently
+in Your own financial statements or management accounts. An
+allocation that complies with this paragraph binds Licensor for the
+calendar year it covers, and allocated Covered Revenue never
+exceeds the actual receipts of the whole.
+
+Where the customer holds its own copy of the Software under this
+license, Your receipts for installing, configuring, or maintaining
+that copy are not Covered Revenue.
+
+
+5. COVERAGE CERTIFICATES
+
+At any time and at no charge, You may send Licensor, at the address
+above, a complete and accurate written description of an offering
+and, if applicable, a proposed allocation. Licensor shall respond
+within 30 days with a written determination of whether, and to what
+extent, receipts from the offering are Covered Revenue and whether
+the allocation complies with Section 4. Silence for 30 days accepts
+the request as submitted, except as to facts the request omitted or
+misstated.
+
+A determination, including a deemed acceptance, binds Licensor and
+its successors for the versions of the Package it names, for as long
+as the material facts described in the request remain accurate.
+
+
+6. REPORTING, PAYMENT, AUDIT, AND CURE
+
+If a fee is due under condition (b) for a calendar year, You shall,
+within 90 days after the end of that year, send Licensor a
+self-certification stating the Covered Revenue and the fee due, and
+pay the fee through the address or URL in the License Details
+above.
+
+Licensor may audit the calculation at most once per calendar year,
+at Licensor's expense, through an independent accountant under
+confidentiality, on 30 days' written notice. If an audit finds
+underpayment exceeding 5% of the amount due, You shall also
+reimburse the reasonable cost of that audit.
+
+A good-faith underpayment, late report, or late payment does not
+terminate this license and is not copyright infringement; any
+unpaid amount remains a debt owed to Licensor. If You fail to pay
+or report as this section requires, Licensor shall give You written
+notice, and You have 30 days from that notice to cure. Only a
+failure to cure within those 30 days is a failure of condition (b).
+
+
+7. DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @makerclay/core
+
+> **License: First Million Stays Yours License.** Free to use, no matter who you are or what you use it for. It only ever costs money if you sell or host a product built on this software and that product makes you more than $1M in a year. Under that line you owe nothing, sign nothing, register nowhere.
+>
+> | Free under | Above it | Becomes MIT |
+> |---|---|---|
+> | $1M/year from products built on it | 3% of the excess | 2028-02-20 (this version) |
+>
+> Plain answers: [hyperclay.com/host-program](https://hyperclay.com/host-program) · binding text in [LICENSE](LICENSE) · questions: license@hyperclay.com
+
+The host for malleable HTML files, as an embeddable Express app.
+
+This is the engine behind [`makerclay`](https://www.npmjs.com/package/makerclay).
+If you want to run a server, install that instead. Install this when you are
+building the server: a desktop app, a different CLI, a host with its own auth.
+
+```js
+import express from 'express';
+import { createHost, createSqliteStore } from '@makerclay/core';
+import { ownerPassword } from '@makerclay/core/auth/password';
+
+const host = createHost({
+  data: './my-data',
+  store: createSqliteStore(),
+  auth: ownerPassword(),
+});
+
+await host.ready;
+express().use(host.app).listen(4600);
+```
+
+`host.app` is an Express app. `host.ready` resolves once the boot scan and any
+crash recovery have finished. `host.close()` releases the single-writer lock.
+
+## What `createHost` gives you
+
+Everything under `/_/` (dashboard, editor, versions, trash, uploads, share links,
+collections, signups, the spec's `/_/meta` and `/_/save` lanes), plus document
+serving for everything else. It owns one directory:
+
+```
+<data>/files/          documents
+<data>/tenants/        one folder per signup
+<data>/versions/       history, keyed by document identity
+<data>/trash/          soft deletes
+<data>/records/        collection submissions
+<data>/makerclay.db    a sparse overlay
+```
+
+**The store is an overlay, not a mirror.** Rows exist only for state a file cannot
+hold: which document is private, which is trashed, who is signed in. Lose the
+database and the overlay rebuilds itself from the durable records under
+`versions/`, minus the credentials, which are reissued rather than invented. With
+state on disk and no records left to read it by, the host refuses to serve.
+
+## The pieces you can replace
+
+| Option | What it is |
+|---|---|
+| `auth` | An identity provider. `none()` makes every request the owner (embedded/desktop). `ownerPassword()` is the single-owner password provider with first-run setup. Write your own: it needs `identify(req)` and, optionally, `routes()`. |
+| `store` | The metadata overlay. `createSqliteStore()` uses the built-in `node:sqlite`. `null` is supported and turns off everything that needs a row. |
+| `isolation` | `off`, `untrusted` (the default: tenant documents and any file the host never saved) or `all`. |
+| `features` | Switches for the dashboard, editor, uploads, collections, share links, signups. |
+| `wire` | Compatibility with older clients. See `src/wire-compat.js`, which names the deployed client behind every shim. |
+
+Also exported: `can()` and the capability matrix, the path resolver, the spec's
+etag and header helpers, the root-attribute reader and writer, and `ulid()`.
+
+## Invariants it will not let you break
+
+- Every document mutation goes through `host.documents.replace`. Nothing else
+  writes a managed file.
+- The document root is never served statically. Every read passes the gate.
+- Serving never mutates a stored file. Serve-time injection happens on the
+  response bytes, and both injected attributes are stripped on the way back in.
+- A response on any save lane is a JSON object, on every status.
+
+## Requirements
+
+Node 22.13 or newer, for `node:sqlite`, which is behind a flag before then.
+
+First Million Stays Yours License; see the matrix at the top of this README and the LICENSE file.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@makerclay/core",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "The embeddable single-tenant host for malleable HTML files",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./paths": "./src/paths.js",
+    "./store/sqlite": "./src/store/sqlite.js",
+    "./auth/password": "./src/auth/password.js",
+    "./auth/none": "./src/auth/none.js",
+    "./auth/can": "./src/auth/can.js"
+  },
+  "files": [
+    "src/",
+    "ui/",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@panphora/clayjs": "^1.2.0",
+    "busboy": "^1.6.0",
+    "cheerio": "1.2.0",
+    "chokidar": "^4.0.0",
+    "codemirror": "^5.65.21",
+    "express": "^4.21.2",
+    "hyper-html-api": "0.8.0",
+    "js-beautify": "^1.15.1",
+    "livesync-hyperclay": "^0.15.1",
+    "qrcode-generator": "^1.5.2",
+    "upath": "^2.0.1"
+  },
+  "peerDependencies": {
+    "tailwind-hyperclay": "*"
+  },
+  "peerDependenciesMeta": {
+    "tailwind-hyperclay": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "prepublishOnly": "python3 ../../scripts/ablation-check.py LICENSE"
+  }
+}

package/src/admin/listing.js

@@ -0,0 +1,149 @@
+import path from 'upath';
+import { statIfExists, readdirIfExists } from '../util/fsx.js';
+import { isDocumentPath, isReservedNodePath } from '../paths.js';
+
+// The `/_/nodes` serializer. Ordering and formatting are ported from the
+// platform's dashboard-nodes.js; the data model underneath is different, and
+// deliberately so: the DIRECTORY is the truth and the store only decorates it.
+// List a folder with the db deleted and you still get every file, just without
+// the private/shared badges.
+
+const SORTS = new Set(['name', 'modified', 'size', 'kind']);
+
+function formatSize(bytes) {
+  if (bytes === null || bytes === undefined) return '';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) { value /= 1024; unit += 1; }
+  return `${value >= 10 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+
+function buildBreadcrumbs(dir) {
+  const crumbs = [{ name: 'Home', path: '' }];
+  if (!dir) return crumbs;
+  const segments = dir.split('/').filter(Boolean);
+  let accumulated = '';
+  for (const segment of segments) {
+    accumulated = accumulated ? `${accumulated}/${segment}` : segment;
+    crumbs.push({ name: segment, path: accumulated });
+  }
+  return crumbs;
+}
+
+// Folders always lead, whatever the sort. A file browser that interleaves them
+// makes the tree unreadable, and every listing anyone has ever liked does this.
+function sortEntries(entries, sort = 'name', direction = 'asc') {
+  const key = SORTS.has(sort) ? sort : 'name';
+  const sign = direction === 'desc' ? -1 : 1;
+  const compare = {
+    name: (a, b) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' }),
+    modified: (a, b) => (a.modified || 0) - (b.modified || 0),
+    size: (a, b) => (a.size || 0) - (b.size || 0),
+    kind: (a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name),
+  }[key];
+
+  return [...entries].sort((a, b) => {
+    if (a.kind === 'dir' && b.kind !== 'dir') return -1;
+    if (b.kind === 'dir' && a.kind !== 'dir') return 1;
+    return compare(a, b) * sign || a.name.localeCompare(b.name);
+  });
+}
+
+export function createListing({ paths, nodes, isolation = null, store = null }) {
+  function decorate(entry, row) {
+    if (!row) return entry;
+    return {
+      ...entry,
+      id: row.id,
+      private: !!row.private,
+      signups: !!row.signups,
+      isolated: isolation ? isolation.isolatedFor(row) : false,
+      shared: store ? store.listShares(row.id).filter((share) => !share.revokedAt).length : 0,
+      collection: store ? (store.getCollection(row.id)?.slug ?? null) : null,
+      etag: row.etag ?? null,
+    };
+  }
+
+  async function list({ owner = '', dir = '', q = '', sort = 'name', direction = 'asc' } = {}) {
+    let target = paths.realmRoot(owner);
+    if (dir) {
+      // The same resolution every other reader uses, rather than a bare join:
+      // it refuses `..`, dotfiles, an absolute path and any symlink that leaves
+      // the realm. A join would answer `?dir=../../../../etc` with a listing of
+      // the machine.
+      try {
+        target = await paths.resolveRead(owner, dir);
+      } catch {
+        return null;
+      }
+    }
+    const stat = await statIfExists(target);
+    if (!stat?.isDirectory()) return null;
+
+    const needle = String(q || '').trim().toLowerCase();
+    const entries = [];
+    for (const item of await readdirIfExists(target, { withFileTypes: true })) {
+      if (item.name.startsWith('.')) continue;
+      // A symlink inside a managed tree is refused everywhere else, so listing
+      // one would advertise a file that 404s and leak its target's size.
+      if (item.isSymbolicLink()) continue;
+      if (needle && !item.name.toLowerCase().includes(needle)) continue;
+      const full = path.join(target, item.name);
+      const info = await statIfExists(full);
+      if (!info) continue;
+      const relPath = dir ? `${dir}/${item.name}` : item.name;
+      const kind = info.isDirectory() ? 'dir' : (isDocumentPath(relPath) ? 'doc' : 'file');
+      entries.push(decorate({
+        name: item.name,
+        path: relPath,
+        kind,
+        size: info.isDirectory() ? null : info.size,
+        sizeLabel: info.isDirectory() ? '' : formatSize(info.size),
+        modified: Math.round(info.mtimeMs),
+        url: `${owner ? `/~${owner}` : ''}/${relPath}`,
+      }, nodes.get(owner, relPath)));
+    }
+
+    return {
+      owner,
+      dir,
+      breadcrumbs: buildBreadcrumbs(dir),
+      sort,
+      direction,
+      q: String(q || ''),
+      entries: sortEntries(entries, sort, direction),
+    };
+  }
+
+  async function trash() {
+    if (!store) return { entries: [] };
+    // A deleted collection record is a row in here too, but it is not a file and
+    // it comes back through the collection API, not this view.
+    const rows = store.listTrash().filter((row) => !isReservedNodePath(row.path));
+    const entries = [];
+    for (const row of rows) {
+      // A child of a trashed folder went in with its parent and comes back with
+      // it, so only the roots are offered.
+      const parent = path.dirname(row.path);
+      if (parent !== '.' && rows.some((other) => other.id !== row.id && other.path === parent)) continue;
+      const stored = paths.trashPath(row.id, path.basename(row.path));
+      const info = await statIfExists(stored);
+      entries.push({
+        id: row.id,
+        name: path.basename(row.path),
+        path: row.path,
+        owner: row.owner,
+        kind: row.kind,
+        deletedAt: row.deletedAt,
+        size: info && !info.isDirectory() ? info.size : null,
+        sizeLabel: info && !info.isDirectory() ? formatSize(info.size) : '',
+        recoverable: !!info,
+      });
+    }
+    return { entries };
+  }
+
+  return { list, trash };
+}