@moloodev/platform 0.0.0-stage → 0.2.0

package/src/builtin-editors.ts

@@ -0,0 +1,15 @@
+export const builtinEditors = [
+  { id: "091d9isv5yp3x5mhwum08p1f", publisherHandle: "moloo", slug: "markdown" },
+  { id: "1o5gtual80gchlsd5uug3wfv", publisherHandle: "moloo", slug: "loop" },
+  { id: "g6qihgfq096rsp3k1kimttvy", publisherHandle: "moloo", slug: "table" },
+  { id: "2cnatugu7hupo4stgh2srv68", publisherHandle: "moloo", slug: "bundle" },
+  { id: "uqq597gzhpzkds0mrmc2zdtu", publisherHandle: "moloo", slug: "layout" },
+] as const;
+
+export function builtinEditorId(
+  slug: (typeof builtinEditors)[number]["slug"],
+): string {
+  const row = builtinEditors.find((item) => item.slug === slug);
+  if (row === undefined) throw new Error(`builtin editor ${slug} is missing`);
+  return row.id;
+}

package/src/bundle.ts

@@ -0,0 +1,217 @@
+import { z } from "zod";
+
+export const BUNDLE_SCHEMA_VERSION = 1;
+
+export const inclusionSchema = z.enum(["direct", "auto"]);
+export type Inclusion = z.infer<typeof inclusionSchema>;
+
+export const entrySchema = z.object({
+  inclusion: inclusionSchema,
+  revision: z.number().int().min(1).nullable(),
+  type: z.string().min(1),
+});
+export type Entry = z.infer<typeof entrySchema>;
+
+export type BundleContent = {
+  version: typeof BUNDLE_SCHEMA_VERSION;
+  entries: Record<string, Entry>;
+};
+
+export type BundleContentIssue = {
+  severity: "error";
+  code:
+    | "invalid_document"
+    | "unsupported_schema"
+    | "invalid_entries"
+    | "invalid_asset_id"
+    | "invalid_entry"
+    | "invalid_inclusion"
+    | "invalid_revision"
+    | "invalid_type";
+  path: readonly (string | number)[];
+};
+
+const INCLUSIONS = new Set<Inclusion>(inclusionSchema.options);
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function identifier(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function revisionValue(value: unknown): value is number | null {
+  if (value === null) return true;
+  return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+
+export function blankBundleContent(
+  entries: Record<string, Entry> = {},
+): BundleContent {
+  return { version: BUNDLE_SCHEMA_VERSION, entries };
+}
+
+export function inspectBundleContent(input: unknown): {
+  schemaVersion: number | null;
+  issues: readonly BundleContentIssue[];
+  references: readonly {
+    assetId: string;
+    assetType: string;
+    path: readonly (string | number)[];
+  }[];
+} {
+  const issues: BundleContentIssue[] = [];
+  const references: {
+    assetId: string;
+    assetType: string;
+    path: readonly (string | number)[];
+  }[] = [];
+  const issue = (
+    code: BundleContentIssue["code"],
+    path: readonly (string | number)[],
+  ) => {
+    issues.push({ severity: "error", code, path });
+  };
+  if (!record(input)) {
+    issue("invalid_document", []);
+    return { schemaVersion: null, issues, references };
+  }
+  const version = input.version;
+  const schemaVersion =
+    typeof version === "number" && Number.isInteger(version) && version > 0
+      ? version
+      : null;
+  if (version !== BUNDLE_SCHEMA_VERSION) {
+    issue(
+      schemaVersion === null ? "invalid_document" : "unsupported_schema",
+      ["version"],
+    );
+    return { schemaVersion, issues, references };
+  }
+  if (!record(input.entries)) {
+    issue("invalid_entries", ["entries"]);
+    return { schemaVersion: BUNDLE_SCHEMA_VERSION, issues, references };
+  }
+  for (const [assetId, raw] of Object.entries(input.entries)) {
+    const path = ["entries", assetId];
+    if (!identifier(assetId)) {
+      issue("invalid_asset_id", path);
+      continue;
+    }
+    if (!record(raw)) {
+      issue("invalid_entry", path);
+      continue;
+    }
+    if (!INCLUSIONS.has(raw.inclusion as Inclusion)) {
+      issue("invalid_inclusion", [...path, "inclusion"]);
+    }
+    if (!revisionValue(raw.revision)) {
+      issue("invalid_revision", [...path, "revision"]);
+    }
+    if (!identifier(raw.type)) {
+      issue("invalid_type", [...path, "type"]);
+    }
+    if (
+      INCLUSIONS.has(raw.inclusion as Inclusion) &&
+      revisionValue(raw.revision) &&
+      identifier(raw.type)
+    ) {
+      references.push({
+        assetId,
+        assetType: raw.type,
+        path,
+      });
+    }
+  }
+  return { schemaVersion: BUNDLE_SCHEMA_VERSION, issues, references };
+}
+
+export function readBundleContent(input: unknown): BundleContent | null {
+  return inspectBundleContent(input).issues.length === 0
+    ? (input as BundleContent)
+    : null;
+}
+
+const issueCodeSchema = z.enum([
+  "missing",
+  "revision_required",
+  "revision_missing",
+  "trashed",
+  "locked",
+  "nested",
+]);
+
+export type IssueCode = z.infer<typeof issueCodeSchema>;
+
+const issueSchema = z.object({
+  assetId: z.string(),
+  code: issueCodeSchema,
+});
+
+export type Issue = z.infer<typeof issueSchema>;
+
+const memberSchema = z.object({
+  assetId: z.string(),
+  name: z.string(),
+  path: z.string(),
+  type: z.string(),
+  inclusion: inclusionSchema,
+  via: z.string().nullable(),
+  selected: z.number().nullable(),
+  previous: z.number().nullable(),
+  latest: z.number(),
+  locked: z.boolean(),
+  size: z.number(),
+});
+
+export type Member = z.infer<typeof memberSchema>;
+
+const refSchema = z.object({
+  parentId: z.string(),
+  childId: z.string(),
+});
+
+export type Ref = z.infer<typeof refSchema>;
+
+export const compositionSchema = z.object({
+  bundleId: z.string(),
+  bundleName: z.string(),
+  bundleEpoch: z.number(),
+  bundleUpdatedAt: z.string(),
+  headRevision: z.number(),
+  entries: z.record(z.string(), entrySchema),
+  members: z.array(memberSchema),
+  refs: z.array(refSchema),
+  previousMembers: z.array(memberSchema),
+  previousRefs: z.array(refSchema),
+  added: z.array(z.string()),
+  removed: z.array(z.string()),
+  issues: z.array(issueSchema),
+  reviewed: z.string(),
+  totalBytes: z.number(),
+  deltaBytes: z.number(),
+});
+
+export type Composition = z.infer<typeof compositionSchema>;
+
+export const publicationSchema = z.object({
+  visibility: z.enum(["private", "public"]),
+});
+
+export type Publication = z.infer<typeof publicationSchema>;
+
+export const bundleConfirmSchema = z.object({
+  composition: compositionSchema,
+  revision: z.number().int(),
+});
+
+export type BundleConfirm = z.infer<typeof bundleConfirmSchema>;
+
+export const DEFAULT_PUBLICATION: Publication = {
+  visibility: "private",
+};
+
+export function compositionBlocksConfirm(issues: readonly Issue[]): boolean {
+  return issues.some((issue) => issue.code !== "locked");
+}

package/src/constants.ts

@@ -0,0 +1,14 @@
+/** Reserved basename for empty-directory sentinel assets. */
+export const KEEP_NAME = ".keep";
+
+/** Soft-deleted assets older than this are hard-purged. */
+export const TRASH_RETENTION_DAYS = 30;
+
+/**
+ * Default per-workspace user-content quota (release policy §8): drafts,
+ * revisions, and distinct file bytes. Plans and purchases may raise it later.
+ */
+export const WORKSPACE_STORAGE_LIMIT_BYTES = 1024 * 1024 * 1024;
+
+/** Maximum file size parsed into document content during import. */
+export const IMPORT_MAX_BYTES = 4 * 1024 * 1024;

package/src/dev-certs.ts

@@ -0,0 +1,10 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function readLocalDevCert(): { cert: Buffer; key: Buffer } | undefined {
+  const cert = fileURLToPath(new URL("../../../.certs/local.moloo.dev.pem", import.meta.url));
+  const key = fileURLToPath(new URL("../../../.certs/local.moloo.dev-key.pem", import.meta.url));
+  return existsSync(cert) && existsSync(key)
+    ? { cert: readFileSync(cert), key: readFileSync(key) }
+    : undefined;
+}

package/src/file-content.ts

@@ -0,0 +1,113 @@
+export const FILE_SCHEMA_VERSION = 1;
+
+/** Per-file cap from the release policy (§7). Enforced before any upload starts. */
+export const MAX_FILE_BYTES = 100 * 1024 * 1024;
+
+/**
+ * Content of a blob-mode asset: a pointer to immutable bytes. The bytes live in
+ * managed object storage; this JSON is what drafts, revisions, holds, and
+ * bundles carry. Interpretation metadata (`contentType`, `size`, `sha256`) is
+ * fixed with the revision; `fileName` is the uploaded name, kept for exports.
+ */
+export type FileContent = {
+  version: typeof FILE_SCHEMA_VERSION;
+  /** Lowercase hex SHA-256 of the bytes; also the storage key. */
+  sha256: string;
+  size: number;
+  contentType: string;
+  fileName: string;
+};
+
+export type FileContentIssue = {
+  severity: "error";
+  code:
+    | "invalid_document"
+    | "unsupported_schema"
+    | "invalid_sha256"
+    | "invalid_size"
+    | "file_too_large"
+    | "invalid_content_type"
+    | "invalid_file_name";
+  path: readonly (string | number)[];
+};
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export function isSha256Hex(value: unknown): value is string {
+  return typeof value === "string" && SHA256_HEX.test(value);
+}
+
+export function fileContent(input: Omit<FileContent, "version">): FileContent {
+  return { version: FILE_SCHEMA_VERSION, ...input };
+}
+
+export function inspectFileContent(input: unknown): {
+  schemaVersion: number | null;
+  issues: readonly FileContentIssue[];
+} {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return {
+      schemaVersion: null,
+      issues: [{ severity: "error", code: "invalid_document", path: [] }],
+    };
+  }
+  const document = input as Record<string, unknown>;
+  if (document.version !== FILE_SCHEMA_VERSION) {
+    const version = document.version;
+    return {
+      schemaVersion:
+        typeof version === "number" && Number.isInteger(version) && version > 0
+          ? version
+          : null,
+      issues: [
+        { severity: "error", code: "unsupported_schema", path: ["version"] },
+      ],
+    };
+  }
+  const issues: FileContentIssue[] = [];
+  if (!isSha256Hex(document.sha256))
+    issues.push({ severity: "error", code: "invalid_sha256", path: ["sha256"] });
+  if (
+    typeof document.size !== "number" ||
+    !Number.isInteger(document.size) ||
+    document.size < 0
+  )
+    issues.push({ severity: "error", code: "invalid_size", path: ["size"] });
+  else if (document.size > MAX_FILE_BYTES)
+    issues.push({ severity: "error", code: "file_too_large", path: ["size"] });
+  if (typeof document.contentType !== "string" || !document.contentType)
+    issues.push({
+      severity: "error",
+      code: "invalid_content_type",
+      path: ["contentType"],
+    });
+  if (typeof document.fileName !== "string" || !document.fileName.trim())
+    issues.push({
+      severity: "error",
+      code: "invalid_file_name",
+      path: ["fileName"],
+    });
+  return { schemaVersion: FILE_SCHEMA_VERSION, issues };
+}
+
+export function readFileContent(
+  data: Record<string, unknown> | null | undefined,
+): FileContent | null {
+  if (!data) return null;
+  return inspectFileContent(data).issues.length === 0
+    ? (data as FileContent)
+    : null;
+}
+
+export function measureFileContent(
+  input: unknown,
+): { contentType: string; contentBytes: number } | null {
+  const content = readFileContent(
+    input && typeof input === "object" && !Array.isArray(input)
+      ? (input as Record<string, unknown>)
+      : null,
+  );
+  return content
+    ? { contentType: content.contentType, contentBytes: content.size }
+    : null;
+}

package/src/file-delivery.ts

@@ -0,0 +1,187 @@
+/**
+ * The file origin (`files.moloo.cloud`) contract shared by the platform that
+ * issues links and the Worker that serves them. Runtime-agnostic.
+ *
+ * Storage objects are immutable and named by a random id minted per upload,
+ * never by the file name or the digest. The URL is the capability: knowing
+ * `/{workspaceId}/{objectId}` is what grants access, exactly as with the
+ * platform's Vercel Blob media, so links never expire and cache forever. Bytes
+ * disappear only when the platform deletes the object and purges its tags.
+ *
+ * URL: `/{workspaceId}/{objectId}/{variant}`, plus `?name=<file name>` so a
+ * rendered original saves under its name, or `?download=<file name>` to save
+ * instead of render. `variant` is `orig` or `w{width}.{format}` from the fixed
+ * sets below.
+ */
+
+/** Resized widths, powers of two so game assets scale cleanly. */
+export const VARIANT_WIDTHS = [256, 512, 1024, 2048] as const;
+export type VariantWidth = (typeof VARIANT_WIDTHS)[number];
+
+/** Output of resized variants. Browsers in scope decode AVIF; WebP stays parseable for a fallback. */
+const VARIANT_FORMATS = ["avif", "webp"] as const;
+type VariantFormat = (typeof VARIANT_FORMATS)[number];
+export const DEFAULT_VARIANT_FORMAT: VariantFormat = "avif";
+
+/** The one resized variant the platform materializes at upload for instant previews. */
+export const PREVIEW_WIDTH: VariantWidth = 256;
+
+/** Cloudflare Images input cap; larger images are served as originals only. */
+const TRANSFORM_MAX_BYTES = 20 * 1024 * 1024;
+
+/** Cache purge endpoint on the origin; platform-only, bearer `FILES_ADMIN_KEY`. */
+export const PURGE_PATH = "/_purge";
+
+export type Variant =
+  | { kind: "orig" }
+  | { kind: "resized"; width: VariantWidth; format: VariantFormat };
+
+export type DeliveryTarget = {
+  workspaceId: string;
+  objectId: string;
+  variant: Variant;
+};
+
+/** `createId()` ids (24 chars) and the digest names of objects stored before ids. */
+const OBJECT_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function variantSegment(variant: Variant): string {
+  return variant.kind === "orig" ? "orig" : `w${variant.width}.${variant.format}`;
+}
+
+export function parseVariant(segment: string): Variant | null {
+  if (segment === "orig") return { kind: "orig" };
+  const match = /^w(\d+)\.([a-z]+)$/.exec(segment);
+  if (!match) return null;
+  const width = Number(match[1]);
+  const format = match[2];
+  if (!(VARIANT_WIDTHS as readonly number[]).includes(width)) return null;
+  if (!(VARIANT_FORMATS as readonly string[]).includes(format)) return null;
+  return { kind: "resized", width: width as VariantWidth, format: format as VariantFormat };
+}
+
+function deliveryPath(target: DeliveryTarget): string {
+  return `/${target.workspaceId}/${target.objectId}/${variantSegment(target.variant)}`;
+}
+
+export function parseDeliveryPath(pathname: string): DeliveryTarget | null {
+  const parts = pathname.split("/");
+  if (parts.length !== 4 || parts[0] !== "") return null;
+  const [, workspaceId, objectId, segment] = parts as [string, string, string, string];
+  if (!OBJECT_ID.test(workspaceId) || !OBJECT_ID.test(objectId)) return null;
+  const variant = parseVariant(segment);
+  return variant ? { workspaceId, objectId, variant } : null;
+}
+
+/**
+ * Absolute URL for one variant of an object. `name` labels an inline response
+ * so saving it keeps the file name; `download` forces saving under that name.
+ */
+export function deliveryUrl(
+  origin: string,
+  target: DeliveryTarget,
+  options: { name?: string; download?: string } = {},
+): string {
+  const url = new URL(deliveryPath(target), origin);
+  if (options.download) url.searchParams.set("download", options.download);
+  else if (options.name) url.searchParams.set("name", options.name);
+  return url.toString();
+}
+
+/** The only R2 bucket. Every environment writes here. */
+export const FILES_BUCKET = "moloo-files-prod";
+
+/**
+ * Cloudflare account that owns `moloo-files-prod`.
+ * Same id as `apps/files` wrangler `account_id`.
+ */
+export const FILES_ACCOUNT_ID = "a01517696189c6f337df29071a295c33";
+
+/** The only file origin. Every environment links here. */
+export const FILES_ORIGIN = "https://files.moloo.cloud";
+
+/** Workspace id segment in an object key. No slashes. */
+const WORKSPACE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Where the original bytes live in the bucket. */
+export function blobKey(workspaceId: string, objectId: string): string {
+  return `files/${workspaceId}/${objectId}`;
+}
+
+/**
+ * Prefix of every object for one workspace, including derivatives
+ * (`{objectId}.d/…`). Cleanup may delete only keys under this prefix.
+ */
+export function workspaceFilesPrefix(workspaceId: string): string {
+  if (!WORKSPACE_ID.test(workspaceId)) {
+    throw new Error("workspace id is not a storage key segment");
+  }
+  return `files/${workspaceId}/`;
+}
+
+/** The keys a caller may delete. A key outside the workspace prefix is refused. */
+export function workspaceKeysToDelete(workspaceId: string, keys: readonly string[]): string[] {
+  const prefix = workspaceFilesPrefix(workspaceId);
+  return keys.map((key) => {
+    if (!key.startsWith(prefix)) {
+      throw new Error(`refusing to delete outside workspace ${workspaceId}`);
+    }
+    return key;
+  });
+}
+
+/** Where a materialized resized variant lives; deleted together with the blob. */
+export function derivativeKey(
+  workspaceId: string,
+  objectId: string,
+  variant: Extract<Variant, { kind: "resized" }>,
+): string {
+  return `${blobKey(workspaceId, objectId)}.d/${variantSegment(variant)}`;
+}
+
+/** Every derivative the platform may have written for a blob. */
+export function derivativeKeys(workspaceId: string, objectId: string): string[] {
+  return [
+    derivativeKey(workspaceId, objectId, {
+      kind: "resized",
+      width: PREVIEW_WIDTH,
+      format: DEFAULT_VARIANT_FORMAT,
+    }),
+  ];
+}
+
+/** Tags on every cached response: purge one object, or a whole workspace. */
+export function cacheTags(workspaceId: string, objectId: string): string[] {
+  return [`ws:${workspaceId}`, `obj:${objectId}`];
+}
+
+function isImageContentType(contentType: string): boolean {
+  return /^image\//i.test(contentType.trim());
+}
+
+/**
+ * Content-Type bound into the signed PUT. Browsers rewrite `text/*` bodies
+ * (charset, newlines) when XHR sees a textual type, so those uploads go as
+ * opaque bytes. Media types stay as declared so the file origin can resize
+ * images from object metadata. The pointer still records the real MIME.
+ */
+export function putContentType(declared: string): string {
+  const mime = declared.split(";")[0]!.trim().toLowerCase();
+  // XHR rewrites textual types (charset, newline conversion). Store them as bytes.
+  if (!mime || mime.startsWith("text/")) return "application/octet-stream";
+  return mime;
+}
+
+/** Whether resized variants exist for this file: an image small enough to transform. */
+export function canResize(contentType: string, size: number): boolean {
+  return isImageContentType(contentType) && size <= TRANSFORM_MAX_BYTES;
+}
+
+/** RFC 6266 value: ASCII fallback plus UTF-8 `filename*` for non-ASCII names. */
+export function contentDisposition(
+  type: "inline" | "attachment",
+  fileName: string,
+): string {
+  const ascii = fileName.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+  return `${type}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(fileName)}`;
+}

package/src/ids.ts

@@ -0,0 +1,9 @@
+import { customAlphabet } from "nanoid";
+
+const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+const nanoid = customAlphabet(alphabet, 24);
+
+/** 24-char lowercase alphanumeric id (nanoid). Shared by every table and CRDT model. */
+export function createId(): string {
+  return nanoid();
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+export { type AppIcon } from "./app-icon";
+
+export {
+  isQualifiedName,
+  parseQualifiedName,
+  type QualifiedName,
+} from "./qualified-name";
+
+export {
+  FILE_APPEARANCE_ICONS,
+  FIRST_PARTY_SCHEMAS,
+  KNOWN_PATTERN_IDS,
+  STORAGE_MODES,
+  UNKNOWN_FILE_APPEARANCE,
+  classifyFile,
+  isStorageMode,
+  patternForContentType,
+  resolveFileAppearance,
+  resolvePatternAppearance,
+  type AssetTypeIcon,
+  type FileAppearance,
+  type FileAppearanceMatcher,
+  type FirstPartySchemaKey,
+  type KnownPatternId,
+  type StorageMode,
+} from "./asset-types";
+
+export {
+  IDENTITY_ISSUER,
+  MARKETING_SITE,
+  PLATFORM_APPS,
+  getPlatformAppById,
+  getPlatformAppUrl,
+  resolveDevPort,
+  resolveSiteOrigin,
+  type PlatformApp,
+  type PlatformAppId,
+  type SiteOriginRef,
+} from "./platform";
+
+export {
+  getIdAccountUrl,
+  getIdOrigin,
+  getIdSignInUrl,
+  getInviteUrl,
+  getMarketingOrigin,
+  getWorkspaceUrl,
+} from "./origins";
+
+export { resolveSiteEnv, type SiteEnv } from "./url";
+
+export {
+  PLATFORM_API,
+  RESERVED_API_ROOT_SEGMENTS,
+  getApiOrigin,
+  getDocsOrigin,
+  getDocsSurfaceUrl,
+  getApiOpenApiUrl,
+  getApiOpenApiJsonUrl,
+  getPlatformApiBaseUrl,
+  resolveApiSurface,
+  isProductApiSurface,
+  getSurfaceChromeLinks,
+  type ApiSurfaceRef,
+} from "./api-surfaces";
+
+export {
+  WORKSPACE_HOST,
+  WORKSPACE_HOST_API,
+  getWorkspaceHostUrl,
+  normalizeWorkspaceSlug,
+  resolveWorkspaceHostDevPort,
+  WORKSPACE_SLUG_MAX,
+  type WorkspaceSlugInputError,
+} from "./workspace-host";
+
+export {
+  isTrustedBrowserOrigin,
+  matchTrustedOrigin,
+} from "./trusted-origins";
+
+export { createId } from "./ids";
+export * from "./constants";
+export * from "./naming";
+export * from "./occupancy-protocol";
+export * from "./file-content";
+export * from "./bundle";
+export * from "./file-delivery";