@magland/mochi 0.3.1 → 0.4.1

package/dist/sitesettings.js

@@ -0,0 +1,420 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLLECTION_SITE_FILE = exports.SITE_SETTINGS_FILE = exports.SITE_SOURCES = void 0;
+exports.isSiteSource = isSiteSource;
+exports.isUsableSitePath = isUsableSitePath;
+exports.normalizeSitePath = normalizeSitePath;
+exports.isUsableSiteLabel = isUsableSiteLabel;
+exports.siteSettings = siteSettings;
+exports.editSiteSettings = editSiteSettings;
+exports.findRepoBySiteLabel = findRepoBySiteLabel;
+exports.siteLabelConflict = siteLabelConflict;
+exports.listSiteLabels = listSiteLabels;
+exports.isUsableCollectionAlias = isUsableCollectionAlias;
+exports.storedCollectionAlias = storedCollectionAlias;
+exports.setCollectionAlias = setCollectionAlias;
+exports.collectionSiteAliases = collectionSiteAliases;
+exports.collectionSiteAlias = collectionSiteAlias;
+exports.collectionForSiteAlias = collectionForSiteAlias;
+exports.collectionAliasConflict = collectionAliasConflict;
+exports.siteHostFor = siteHostFor;
+exports.findRepoBySiteHostname = findRepoBySiteHostname;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const atomic_1 = require("./atomic");
+const filecache_1 = require("./filecache");
+const layout_1 = require("./layout");
+const scan_1 = require("./scan");
+const siteshost_1 = require("./siteshost");
+exports.SITE_SOURCES = ['copy', 'actions', 'repository'];
+function isSiteSource(value) {
+    return typeof value === 'string' && exports.SITE_SOURCES.includes(value);
+}
+/**
+ * Whether a string may be stored as the directory a 'repository' site is
+ * published from: empty for the root, or relative path segments of ordinary
+ * filename characters, so `docs` and `build/site` but never `..`, an absolute
+ * path, or a segment that starts with a dot or a dash. The path is later handed to
+ * `git archive` as `<branch>:<path>`, and this grammar is what keeps it a
+ * tree path and nothing git would read as an option or a revision.
+ */
+function isUsableSitePath(value) {
+    if (value === '')
+        return true;
+    if (value.length > 200)
+        return false;
+    return /^[A-Za-z0-9_][A-Za-z0-9._-]*(\/[A-Za-z0-9_][A-Za-z0-9._-]*)*$/.test(value);
+}
+/** A directory field as typed by a person, normalized to what isUsableSitePath accepts. */
+function normalizeSitePath(value) {
+    return value.trim().replace(/^\/+|\/+$/g, '').replace(/\/{2,}/g, '/');
+}
+exports.SITE_SETTINGS_FILE = 'site.json';
+/**
+ * Whether a string may be stored as a custom site label: a single DNS label,
+ * never with a double hyphen, and not one of the names the operator keeps. The
+ * reserved check is here rather than in the grammar because it is a question
+ * about who may claim a name, not about what a hostname may look like: a
+ * request arriving for `www.<sites host>` is parsed as usual and then answers
+ * to nothing, which is what makes the name free for the operator to point
+ * elsewhere.
+ */
+function isUsableSiteLabel(label) {
+    return ((0, siteshost_1.isSiteLabelSafe)(label) &&
+        !label.includes('--') &&
+        label.length <= siteshost_1.MAX_SITE_LABEL &&
+        !(0, siteshost_1.isReservedSiteLabel)(label));
+}
+function defaults() {
+    return { enabled: false, source: 'copy', label: '', path: '' };
+}
+function normalizeSiteSettings(parsed) {
+    const out = defaults();
+    if (typeof parsed !== 'object' || parsed === null)
+        return out;
+    const rec = parsed;
+    if (rec.enabled === true)
+        out.enabled = true;
+    if (rec.source === 'actions' || rec.source === 'repository')
+        out.source = rec.source;
+    if (typeof rec.label === 'string' && isUsableSiteLabel(rec.label))
+        out.label = rec.label;
+    if (typeof rec.path === 'string' && isUsableSitePath(rec.path))
+        out.path = rec.path;
+    return out;
+}
+const settingsCache = (0, filecache_1.fileCache)({
+    read: (file) => {
+        try {
+            return normalizeSiteSettings(JSON.parse(fs.readFileSync(file, 'utf8')));
+        }
+        catch {
+            return defaults();
+        }
+    },
+    missing: () => defaults(),
+});
+/** The site settings of the repository whose bare directory this is. */
+function siteSettings(repoDir) {
+    return settingsCache.get(path.join(repoDir, exports.SITE_SETTINGS_FILE));
+}
+/**
+ * Read-modify-write on a repository's site settings, under a lock, the same
+ * arrangement mochi.json edits use in src/perms.ts. The cache is invalidated
+ * explicitly because a write landing within the mtime granularity would
+ * otherwise be invisible to it.
+ */
+function editSiteSettings(repoDir, fn) {
+    const file = path.join(repoDir, exports.SITE_SETTINGS_FILE);
+    return (0, atomic_1.withFileLock)(`${file}.lock`, () => {
+        let settings = defaults();
+        if (fs.existsSync(file)) {
+            try {
+                settings = normalizeSiteSettings(JSON.parse(fs.readFileSync(file, 'utf8')));
+            }
+            catch {
+                // An unreadable file is edited as the defaults it already reads as.
+            }
+        }
+        fn(settings);
+        (0, atomic_1.writeFileAtomic)(file, JSON.stringify(settings, null, 2) + '\n');
+        settingsCache.invalidate(file);
+        return settings;
+    });
+}
+/**
+ * The repository whose custom label this is, or null. A scan rather than an
+ * index, like every other lookup over a vault's repositories: the answer is a
+ * stat-cached read per repository, and it is only asked for a hostname that is
+ * under the sites host but is not a derived <repo>--<alias> name.
+ */
+function findRepoBySiteLabel(root, label) {
+    if (!isUsableSiteLabel(label))
+        return null;
+    for (const { name: collection } of (0, scan_1.listCollections)(root)) {
+        for (const dirName of (0, scan_1.listRepoDirs)(root, collection)) {
+            if (siteSettings((0, layout_1.repoPath)(root, collection, dirName)).label === label) {
+                return { collection, repo: (0, scan_1.displayName)(dirName) };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The `<collection>/<repo>` already using a label, or null when the label is
+ * free. Asked where a label is being set; the repository setting it does not
+ * conflict with itself. A label cannot collide with any derived label, since a
+ * derived label always contains `--` and a custom one never may.
+ */
+function siteLabelConflict(root, label, collection, repo) {
+    const holder = findRepoBySiteLabel(root, label);
+    if (!holder)
+        return null;
+    if (holder.collection === collection && holder.repo === repo)
+        return null;
+    return `${holder.collection}/${holder.repo}`;
+}
+/**
+ * Every custom label in the vault, with the repository holding it, sorted by
+ * label. The same scan findRepoBySiteLabel does, kept apart from it because
+ * this one answers a different question: what is already taken. Nothing on a
+ * request path asks it; the vault settings page does, so that the flat
+ * namespace of claimed labels can be read rather than discovered one 409 at a
+ * time.
+ */
+function listSiteLabels(root) {
+    const out = [];
+    for (const { name: collection } of (0, scan_1.listCollections)(root)) {
+        for (const dirName of (0, scan_1.listRepoDirs)(root, collection)) {
+            const label = siteSettings((0, layout_1.repoPath)(root, collection, dirName)).label;
+            if (label)
+                out.push({ label, collection, repo: (0, scan_1.displayName)(dirName) });
+        }
+    }
+    return out.sort((a, b) => a.label.localeCompare(b.label));
+}
+// ---- the collection half: collections/<name>/site.json ----
+//
+// A derived site hostname is `<repo>--<alias>`, and the alias is not always the
+// collection's name. Collection names are as permissive as repository names, so
+// a collection called `simulated_instruments` has no name a hostname label may
+// carry, and every repository in it would have been left with no derived
+// hostname at all: the tier that exists precisely to be the guaranteed one.
+// Claiming a custom label was the only way out, which put the guaranteed name
+// behind a first-come namespace.
+//
+// So each collection has a site alias, decided in three tiers:
+//
+//  1. the alias stored in collections/<name>/site.json, when one is set. It is
+//     checked against every other collection where it is written, so it is
+//     unique by construction.
+//  2. otherwise the collection's own name, when that name is already a usable
+//     label. This tier can never be taken away by anything: a vault serving
+//     `webapp--alice` keeps serving it whatever else is created.
+//  3. otherwise the name rewritten as a label (`simulated-instruments`), and
+//     only when no other collection holds that label at any tier. The rewrite
+//     is not injective, so `a_b` and `a.b` would both want `a-b`; neither gets
+//     it, symmetrically, rather than one silently winning. An owner breaks the
+//     tie by storing an alias at tier 1.
+//
+// A separate file rather than a key in collection.json: that file is written
+// through a normalizer that keeps only the owners it knows, so an alias stored
+// there would be dropped by the next owner change. It is the same reason the
+// per-repository settings above are not in mochi.json.
+exports.COLLECTION_SITE_FILE = 'site.json';
+/** Whether a string may be stored as a collection's site alias. */
+function isUsableCollectionAlias(alias) {
+    return (0, siteshost_1.isSiteLabelSafe)(alias) && !alias.includes('--') && alias.length <= siteshost_1.MAX_SITE_LABEL;
+}
+function collectionSiteFile(root, collection) {
+    return path.join((0, layout_1.collectionDir)(root, collection), exports.COLLECTION_SITE_FILE);
+}
+function normalizeCollectionSite(parsed) {
+    if (typeof parsed !== 'object' || parsed === null)
+        return '';
+    const alias = parsed.alias;
+    return typeof alias === 'string' && isUsableCollectionAlias(alias) ? alias : '';
+}
+const aliasCache = (0, filecache_1.fileCache)({
+    read: (file) => {
+        try {
+            return normalizeCollectionSite(JSON.parse(fs.readFileSync(file, 'utf8')));
+        }
+        catch {
+            // An unreadable file stores no alias, which leaves the collection on the
+            // tiers below rather than taking its derived hostnames away.
+            return '';
+        }
+    },
+    missing: () => '',
+});
+/** The alias stored for a collection, or '' when it is on a lower tier. */
+function storedCollectionAlias(root, collection) {
+    return aliasCache.get(collectionSiteFile(root, collection));
+}
+/**
+ * Store a collection's site alias, or clear it with ''. Under a lock and with
+ * the cache invalidated, on the same terms as editSiteSettings above; the file
+ * is removed rather than left holding an empty alias, so a collection that has
+ * never had one and one that had it cleared look the same on disk. The caller
+ * checks collectionAliasConflict first: this writes what it is given.
+ */
+function setCollectionAlias(root, collection, alias) {
+    const file = collectionSiteFile(root, collection);
+    (0, atomic_1.withFileLock)(`${file}.lock`, () => {
+        if (alias === '')
+            fs.rmSync(file, { force: true });
+        else
+            (0, atomic_1.writeFileAtomic)(file, JSON.stringify({ alias }, null, 2) + '\n');
+        aliasCache.invalidate(file);
+    });
+}
+/**
+ * Every collection's site alias, resolved together because the tiers are
+ * decided against each other. Sorted by collection name, as listCollections
+ * returns them.
+ */
+function collectionSiteAliases(root) {
+    const rows = [];
+    // Tiers 1 and 2 first: both are unambiguous on their own, and they are what
+    // tier 3 has to give way to.
+    const claimed = new Map();
+    const pending = new Map();
+    for (const { name } of (0, scan_1.listCollections)(root)) {
+        const stored = storedCollectionAlias(root, name);
+        if (stored) {
+            rows.push({ collection: name, alias: stored, stored: true, taken: '' });
+            if (!claimed.has(stored))
+                claimed.set(stored, name);
+        }
+        else if ((0, siteshost_1.isSiteLabelSafe)(name)) {
+            rows.push({ collection: name, alias: name, stored: false, taken: '' });
+            if (!claimed.has(name))
+                claimed.set(name, name);
+        }
+        else {
+            rows.push({ collection: name, alias: null, stored: false, taken: '' });
+            const wanted = (0, siteshost_1.sanitizedSiteLabel)(name);
+            if (wanted)
+                pending.set(name, wanted);
+        }
+    }
+    // Then tier 3, refused where the label is claimed above or wanted twice.
+    const wantedTwice = new Set();
+    const seen = new Set();
+    for (const wanted of pending.values()) {
+        if (seen.has(wanted))
+            wantedTwice.add(wanted);
+        seen.add(wanted);
+    }
+    for (const row of rows) {
+        const wanted = pending.get(row.collection);
+        if (!wanted)
+            continue;
+        if (claimed.has(wanted) || wantedTwice.has(wanted))
+            row.taken = wanted;
+        else
+            row.alias = wanted;
+    }
+    return rows;
+}
+/**
+ * One collection's site alias, or null when it has none and its repositories
+ * therefore have no derived hostname.
+ *
+ * The two common cases answer without listing the vault's collections at all,
+ * since tiers 1 and 2 are decided by the collection alone; only a name that
+ * needs rewriting pays for the full resolution.
+ */
+function collectionSiteAlias(root, collection) {
+    const stored = storedCollectionAlias(root, collection);
+    if (stored)
+        return stored;
+    if ((0, siteshost_1.isSiteLabelSafe)(collection))
+        return collection;
+    return collectionSiteAliases(root).find((r) => r.collection === collection)?.alias ?? null;
+}
+/**
+ * The collection a derived hostname's alias names, or null when no collection
+ * answers to it. The fast path is the same shortcut collectionSiteAlias takes:
+ * a collection named exactly the alias, with nothing stored, holds it at tier 2
+ * and nothing can have taken it.
+ */
+function collectionForSiteAlias(root, alias) {
+    if (!isUsableCollectionAlias(alias))
+        return null;
+    if ((0, scan_1.isValidName)(alias) && isCollectionDir(root, alias) && storedCollectionAlias(root, alias) === '')
+        return alias;
+    return collectionSiteAliases(root).find((r) => r.alias === alias)?.collection ?? null;
+}
+function isCollectionDir(root, collection) {
+    try {
+        return fs.statSync((0, layout_1.collectionDir)(root, collection)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The collection already holding an alias, or null when it is free. Asked where
+ * an alias is being stored; the collection storing it does not conflict with
+ * itself. Every tier is checked, so storing an alias can neither shadow a
+ * collection that is reached by its own name nor take a rewritten label from
+ * the collection using it.
+ */
+function collectionAliasConflict(root, alias, collection) {
+    const holder = collectionSiteAliases(root).find((r) => r.alias === alias && r.collection !== collection);
+    return holder ? holder.collection : null;
+}
+/**
+ * The full hostname a repository's site would be derived to, or null when the
+ * pair has no derived hostname: the naming rule and the vault's collections in
+ * one call, which is what every caller outside this file wants.
+ */
+function siteHostFor(root, sitesHost, collection, repo) {
+    if (!sitesHost)
+        return null;
+    const alias = collectionSiteAlias(root, collection);
+    return alias === null ? null : (0, siteshost_1.derivedSiteHost)(sitesHost, alias, repo);
+}
+/**
+ * The collection and repository a hostname under the sites host names, or
+ * null: the same question in the other direction, and the one both request
+ * paths that see such a hostname ask (serving the site, and counting its
+ * bytes).
+ *
+ * A label with a doubled hyphen is a derived name, and one without is a label
+ * some repository claimed; the two cannot collide, since a claimed label may
+ * never contain the separator. The names are returned as the hostname carries
+ * them, resolved to a repository that exists by the caller, as usual: an alias
+ * naming no collection is read as a collection name instead, which is what
+ * keeps a renamed collection's published hostnames redirecting rather than
+ * answering nothing.
+ */
+function findRepoBySiteHostname(root, sitesHost, hostname) {
+    const label = (0, siteshost_1.siteHostLabel)(sitesHost, hostname);
+    if (label === null)
+        return null;
+    if (!label.includes('--'))
+        return findRepoBySiteLabel(root, label);
+    const parsed = (0, siteshost_1.parseSiteHost)(sitesHost, hostname);
+    if (!parsed)
+        return null;
+    return {
+        collection: collectionForSiteAlias(root, parsed.collectionAlias) ?? parsed.collectionAlias,
+        repo: parsed.repo,
+    };
+}

package/dist/siteshost.js

@@ -1,16 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SITE_LABEL = void 0;
 exports.isSiteLabelSafe = isSiteLabelSafe;
+exports.isReservedSiteLabel = isReservedSiteLabel;
+exports.reservedSiteLabels = reservedSiteLabels;
+exports.sanitizedSiteLabel = sanitizedSiteLabel;
 exports.normalizeHostname = normalizeHostname;
-exports.siteHostFor = siteHostFor;
+exports.derivedSiteHost = derivedSiteHost;
+exports.siteHostLabel = siteHostLabel;
 exports.parseSiteHost = parseSiteHost;
 exports.isUnderSitesHost = isUnderSitesHost;
 const scan_1 = require("./scan");
 // The grammar of a per-site hostname, in both directions, so that the parser
 // and the link builder cannot drift apart. A site served from
-// <repo>--<collection>.<sitesHost> has an origin of its own, which is what gives
+// <repo>--<alias>.<sitesHost> has an origin of its own, which is what gives
 // it back the cookies, storage, and service workers that the sandbox on the
 // forge host takes away.
+//
+// The `alias` half is the collection's site alias rather than its name: a
+// collection may be called something no hostname label can be, and resolving
+// the two is a question about the vault's collections, which this file cannot
+// see. Everything here is a pure function of the strings it is given, so the
+// grammar stays testable and cheap; src/sitesettings.ts holds the half that
+// reads the vault.
 /**
  * Whether a collection or repository name may appear in a site hostname. The
  * regex is the whole definition: lowercase letters, digits, and single interior
@@ -20,8 +32,67 @@ const scan_1 = require("./scan");
 function isSiteLabelSafe(name) {
     return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name);
 }
-/** The DNS limit on one label, which <repo>--<collection> has to fit inside. */
-const MAX_LABEL = 63;
+/** The DNS limit on one label, which <repo>--<alias> has to fit inside. */
+exports.MAX_SITE_LABEL = 63;
+/**
+ * Labels under the sites host that no repository may claim.
+ *
+ * The sites host is a name the operator will want to use for other things:
+ * `www` for a landing page, `api` for something in front of the vault, the
+ * mail and nameserver names a registrar's defaults create. A repository that
+ * had claimed one of those would quietly own it, and taking it back would mean
+ * finding the repository holding it. Reserving them is the cheap direction.
+ *
+ * The set applies only to the labels a repository claims for itself, not to a
+ * collection's site alias: an alias appears in a hostname only after
+ * `<repo>--`, where it can shadow nothing. Note that `xn--anything` needs no
+ * reserving, since a claimed label may not contain a double hyphen at all.
+ */
+const RESERVED_SITE_LABELS = new Set([
+    'admin',
+    'api',
+    'assets',
+    'cdn',
+    'forge',
+    'git',
+    'localhost',
+    'mail',
+    'ns1',
+    'ns2',
+    'sites',
+    'smtp',
+    'static',
+    'vault',
+    'www',
+]);
+/** Whether a label is one the operator keeps, so no repository may claim it. */
+function isReservedSiteLabel(label) {
+    return RESERVED_SITE_LABELS.has(label);
+}
+/** The reserved labels, sorted, for the settings page to name them. */
+function reservedSiteLabels() {
+    return [...RESERVED_SITE_LABELS].sort();
+}
+/**
+ * A name rewritten as a hostname label, or '' when nothing usable is left.
+ *
+ * Every run of characters a label may not contain becomes a single hyphen and
+ * the ends are trimmed, so `Simulated_Instruments` becomes
+ * `simulated-instruments`. Collapsing the runs is what keeps a double hyphen
+ * out of the result, which the `<repo>--<alias>` grammar depends on.
+ *
+ * The rewrite is not injective: `a_b` and `a.b` both come out as `a-b`. It is
+ * therefore only ever used as a fallback that is dropped when two collections
+ * would land on the same label; see collectionSiteAliases in
+ * src/sitesettings.ts.
+ */
+function sanitizedSiteLabel(name) {
+    const label = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return isSiteLabelSafe(label) && label.length <= exports.MAX_SITE_LABEL ? label : '';
+}
 /**
  * The one normalization a hostname gets, wherever one is read. Exported because
  * the configured sites host and the request's own hostname are compared against
@@ -32,36 +103,39 @@ function normalizeHostname(hostname) {
     return hostname.trim().toLowerCase().replace(/\.$/, '');
 }
 /**
- * The full hostname for a repository's site, or null if it is not eligible.
+ * The full hostname for a repository's site under a collection's site alias, or
+ * null if the pair is not eligible.
  *
- * Repository and collection names are more permissive than a hostname label
- * (isValidName allows '.', '_', and uppercase), so not every repository is
- * eligible, and an ineligible one keeps being served on the forge host. Refusing
- * rather than mangling is deliberate: lowercasing `Webapp1` would collide with a
- * `webapp1` beside it, since hostnames are case-insensitive and both names are
- * legal on disk.
+ * Repository names are more permissive than a hostname label (isValidName
+ * allows '.', '_', and uppercase), so not every repository is eligible, and an
+ * ineligible one keeps being served on the forge host unless its admin claims a
+ * label that is usable. Refusing rather than mangling is deliberate here:
+ * lowercasing `Webapp1` would collide with a `webapp1` beside it, since
+ * hostnames are case-insensitive and both names are legal on disk. A
+ * collection's alias is where the mangling is done instead, because it can be
+ * checked against every other collection first, which a repository name inside
+ * one collection cannot be.
  */
-function siteHostFor(sitesHost, collection, repo) {
+function derivedSiteHost(sitesHost, collectionAlias, repo) {
     if (!sitesHost)
         return null;
     const name = (0, scan_1.displayName)(repo);
-    if (!isSiteLabelSafe(name) || !isSiteLabelSafe(collection))
+    if (!isSiteLabelSafe(name) || !isSiteLabelSafe(collectionAlias))
         return null;
-    const label = `${name}--${collection}`;
-    if (label.length > MAX_LABEL)
+    const label = `${name}--${collectionAlias}`;
+    if (label.length > exports.MAX_SITE_LABEL)
         return null;
     return `${label}.${sitesHost}`;
 }
 /**
- * The collection and repository a request's hostname names, or null.
- *
- * The double hyphen is an unambiguous separator precisely because neither half
- * may contain one, so `a--b` in collection `c` cannot be confused with `a` in
- * collection `b--c`. It also means no label can begin `xn--`, which a browser
- * would read as punycode. No filesystem access happens here; the caller resolves
- * the names with findRepo as usual.
+ * The single label a hostname adds under the sites host, or null: null for a
+ * hostname elsewhere, for the bare sites host, and for a deeper name such as
+ * a.b.<sitesHost>, which is refused and is not covered by a single wildcard
+ * certificate anyway. What the label means is the caller's question: one
+ * containing `--` is a derived <repo>--<alias> name for parseSiteHost below,
+ * and one without is a custom label a repository may have claimed.
  */
-function parseSiteHost(sitesHost, hostname) {
+function siteHostLabel(sitesHost, hostname) {
     if (!sitesHost)
         return null;
     const host = normalizeHostname(hostname);
@@ -69,17 +143,31 @@ function parseSiteHost(sitesHost, hostname) {
     if (!host.endsWith(suffix))
         return null;
     const label = host.slice(0, -suffix.length);
-    // Exactly one remaining label. A deeper name such as a.b.<sitesHost> is
-    // refused, and is not covered by a single wildcard certificate anyway.
     if (label === '' || label.includes('.'))
         return null;
+    return label;
+}
+/**
+ * The collection alias and repository a request's hostname names, or null.
+ *
+ * The double hyphen is an unambiguous separator precisely because neither half
+ * may contain one, so `a--b` under alias `c` cannot be confused with `a` under
+ * alias `b--c`. It also means no label can begin `xn--`, which a browser would
+ * read as punycode. No filesystem access happens here: the alias is turned into
+ * a collection by collectionForSiteAlias, and the repository resolved with
+ * findRepo, as usual.
+ */
+function parseSiteHost(sitesHost, hostname) {
+    const label = siteHostLabel(sitesHost, hostname);
+    if (label === null)
+        return null;
     const parts = label.split('--');
     if (parts.length !== 2)
         return null;
-    const [repo, collection] = parts;
-    if (!isSiteLabelSafe(repo) || !isSiteLabelSafe(collection))
+    const [repo, collectionAlias] = parts;
+    if (!isSiteLabelSafe(repo) || !isSiteLabelSafe(collectionAlias))
         return null;
-    return { collection, repo };
+    return { collectionAlias, repo };
 }
 /**
  * Whether a hostname belongs to the sites host at all, including the bare name

package/dist/source.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseSource = parseSource;
+exports.parseUpstream = parseUpstream;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 // Where an import reads from. `mochi import` accepts an https git URL, an
@@ -88,3 +89,22 @@ function parseSource(input) {
     const name = nameOf(url);
     return name === '' ? null : { url, name, github: githubOf(url) };
 }
+function parseUpstream(input) {
+    if (typeof input !== 'string' || input === '')
+        return null;
+    const github = githubOf(input);
+    if (HTTPS_SOURCE.test(input)) {
+        const label = input.replace(/^https:\/\//, '').replace(/\.git$/i, '').replace(/\/+$/, '');
+        return { url: input, label, web: `https://${label}`, github };
+    }
+    if (SSH_SOURCE.test(input)) {
+        const label = input.replace(/^git@/, '').replace(':', '/').replace(/\.git$/i, '');
+        return {
+            url: input,
+            label,
+            web: github ? `https://github.com/${github.owner}/${github.repo}` : null,
+            github,
+        };
+    }
+    return null;
+}