@wix/origami-site 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@wix/origami-site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Runs an exported Wix origami site: file-based routing, Wix dynamic pages, popups and build checks. Use with @wix/origami-site-astro or @wix/origami-site-express.",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "oxlint .",
+    "test": "node --test test/*.spec.js && tsc --noEmit -p tsconfig.test.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3",
+    "vite": "^8"
+  },
+  "publishUnscoped": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "origami-site",
+      "targets": {
+        "docker": false
+      }
+    },
+    "validations": {
+      "source": [
+        "lint"
+      ],
+      "postBuild": [
+        "test"
+      ]
+    }
+  },
+  "dependencies": {
+    "@wix/origami-types": "1.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@wix/builder-error-pages": "^1.1.6",
+    "@wix/builder-piler-components": "^1.6.7",
+    "@babel/parser": "^7.25.0"
+  },
+  "exports": {
+    "./server": {
+      "types": "./src/server/index.d.ts",
+      "default": "./src/server/index.js"
+    },
+    "./browser": {
+      "types": "./src/browser/index.d.ts",
+      "default": "./src/browser/index.js"
+    },
+    "./popups": {
+      "types": "./src/popups/index.d.ts",
+      "default": "./src/popups/index.js"
+    },
+    "./vite-plugins": {
+      "types": "./src/vite-plugins/index.d.ts",
+      "default": "./src/vite-plugins/index.js"
+    },
+    "./types": {
+      "types": "./src/types/index.d.ts"
+    },
+    "./default-error-404": "./src/default-error-404.jsx"
+  },
+  "falconPackageHash": "236041398ac8f5cb5996fd571ab7dbe9f17287f25c51e01599157dc7"
 }

package/src/browser/index.d.ts

@@ -0,0 +1,10 @@
+import type { PageData } from '../server/index.js'
+// PLAN-QUESTION: mountPage options follow the example; page modules remain unknown until milestone 1.7.
+export type MountPageOptions = {
+  pages: Record<string, () => Promise<unknown>>
+  popups: Record<string, () => Promise<unknown>>
+  seoUriByPageId: Record<string, string>
+  beforeMount: () => Promise<unknown>
+}
+export function mountPage(element: Element | null, options: MountPageOptions): Promise<() => void>
+export function readPageData(): PageData

package/src/browser/index.js

@@ -0,0 +1 @@
+export {}

package/src/default-error-404.jsx

@@ -0,0 +1,9 @@
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import { DefaultError404 } from '@wix/builder-error-pages'
+import { PilerPage } from '@wix/builder-piler-components'
+import '@wix/builder-error-pages/style.css'
+
+createRoot(document.getElementById('root')).render(
+    React.createElement(React.StrictMode, null, React.createElement(PilerPage, { Page: DefaultError404 }))
+)

package/src/popups/index.d.ts

@@ -0,0 +1,3 @@
+// PLAN-QUESTION: Popup option/result types are unspecified here; leave options opaque until milestone 3.2.
+export function openPopup(seoUri: string, options?: Record<string, unknown>): void
+export function closePopup(): void

package/src/popups/index.js

@@ -0,0 +1 @@
+export {}

package/src/server/index.d.ts

@@ -0,0 +1,81 @@
+import type { SiteRouteTable, PageRoute, RouterRoute, AccessRule } from '@wix/origami-types'
+export type { AccessRule } from '@wix/origami-types'
+// PLAN-QUESTION: Logger is unnamed structurally in the plan; only warn/error are used.
+export type Logger = Pick<Console, 'warn' | 'error'>
+export type RequestContext = { request: Request; url: URL; tokens: TokenProvider; locals: Map<string, unknown> }
+
+export type SiteOptions = {
+  root: string                       // the site package folder
+  mode: 'dev' | 'prod'
+  table?: SiteRouteTable                 // prod: the table from the build. dev: omitted, the core scans.
+  wix: { clientId: string; siteId: string }   // from VITE_WIX_CLIENT_ID / VITE_WIX_SITE_ID
+  tokens?: TokenProvider             // default: builderAuthTokenProvider (3.3)
+  access?: AccessSource              // default: noAccessRules (4)
+  accessHandlers?: AccessHandler[]   // default: []
+  fetch?: typeof fetch               // tests inject a fake
+  wixApiBaseUrl?: string             // default 'https://www.wixapis.com'; the conformance suite points it at the fake
+  routerTimeoutMs?: number           // default 5000
+  logger?: Logger                    // default: console with an [origami] prefix
+}
+
+export interface OrigamiSite {
+  /** Current route table (dev: rescans if dirty). */
+  table(): Promise<SiteRouteTable>
+  /** Reference URL matcher. Pure, no network. */
+  match(url: URL): Promise<RouteMatch>
+  /** Answer one request. Never throws: errors become a Resolution. */
+  handle(request: Request): Promise<Resolution>
+  /** Dev: tell the core a file changed (adapters forward Vite watcher events). */
+  fileChanged(path: string): void
+  /** Dev: subscribe to table changes, e.g. to invalidate the virtual:origami-site module. */
+  onTableChange(listener: (table: SiteRouteTable) => void): () => void
+  close(): Promise<void>
+}
+
+export type RouteMatch =
+  | { kind: 'page'; route: PageRoute }
+  | { kind: 'router'; route: RouterRoute; suffix: string }     // '/a/b/c'; '/' for bare '/team'
+  | { kind: 'reserved'; path: string }                        // /_origami/*
+  | { kind: 'notFound' }
+
+export type Resolution =
+  | { kind: 'page'; status: 200 | 404; page: PageRef; data: PageData; headers: Headers }
+  | { kind: 'response'; response: Response }   // redirects, reserved endpoints, 405, 503
+
+export type PageRef = { key: string; itemPath?: string; title: string }
+
+export type PageData = {
+  page: string                                   // PageRef.key; the browser loads this page
+  route: { kind: 'page' | 'router' | 'notFound'; url: string; role?: string }
+  services: Record<string, unknown>              // runtime configs merged into the page's services
+}
+
+export interface TokenProvider {
+  /** The access token to use for this request. Called at most once per request (memoised in the context). */
+  getAccessToken(request: Request): Promise<string>
+}
+
+// AccessRule is shared with route types.   // e.g. { type: 'members' }, { type: 'password' }
+
+/** Where rules come from: a file next to the page, a central file, … — not decided. One swappable loader. */
+export interface AccessSource {
+  load(table: SiteRouteTable, root: string): Promise<Map<string /* route key */, AccessRule[]>>
+}
+export const noAccessRules: AccessSource
+
+/** One handler per rule type. Returns null to allow, or a Response (redirect, 401, a form). */
+export interface AccessHandler {
+  type: string
+  check(rule: AccessRule, request: Request, ctx: RequestContext): Promise<Response | null>
+}
+
+
+export { SiteTreeError } from './requests/errors.js'
+export type { RouterServiceError } from './requests/errors.js'
+export function createSite(options: SiteOptions): Promise<OrigamiSite>
+export function readSiteTree(root: string): Promise<SiteRouteTable>
+export function runInRequestContext<T>(ctx: RequestContext, fn: () => Promise<T>): Promise<T>
+export function getRequestContext(): RequestContext
+export function getAccessToken(): Promise<string>
+export function serializePageData(data: PageData): string
+export function builderAuthTokenProvider(options: { clientId: string; siteId: string }): TokenProvider

package/src/server/index.js

@@ -0,0 +1,2 @@
+export { readSiteTree } from './site-tree/readSiteTree.js'
+export { SiteTreeError } from './requests/errors.js'

package/src/server/requests/errors.d.ts

@@ -0,0 +1,25 @@
+export class SiteTreeError extends Error {
+  code:
+    | 'NOT_SUPPORTED_YET'                // router pages are not supported in stage 1
+    | 'DUPLICATE_URL'                    // two folders give the same URL
+    | 'ROUTE_JSON_INVALID'               // not JSON, or a required field missing or of the wrong type
+    | 'ROUTE_JSON_MISSING_SERVICE_URL'   // no routerServiceUrl: origami refuses to start
+    | 'ROUTE_JSON_SIBLINGS_DIFFER'       // [a]/route.json and [b]/route.json differ
+    | 'ROLE_FOLDER_MISSING'              // pages.member = 'team-member' but no [team-member]/ folder
+    | 'ROLE_FOLDER_NOT_IN_PAGES'         // a [x]/ folder that no role in pages names
+    | 'BRACKET_OUTSIDE_PREFIX'           // [x]/ not directly under a prefix folder
+    | 'PREFIX_HAS_FILES'                 // team/ itself holds page files
+    | 'ROLE_PAGE_HAS_CHILDREN'           // a folder inside [x]/ that isn't _generated
+    | 'PREFIX_COLLIDES_WITH_PAGE'        // pages/team is both a page and a prefix
+    | 'NOT_FOUND_HAS_CHILDREN'
+    | 'DUPLICATE_POPUP'
+    | 'UNSUPPORTED_ACCESS_RULE'          // see section 4
+  constructor(code: SiteTreeError['code'], paths: string[], message: string)
+  paths: string[]
+}
+
+export class RouterServiceError extends Error {
+  code: 'TIMEOUT' | 'NETWORK' | 'HTTP_STATUS' | 'BAD_RESPONSE'
+  routerPrefix: string
+  status?: number
+}

package/src/server/requests/errors.js

@@ -0,0 +1,13 @@
+export class SiteTreeError extends Error {
+    /**
+     * @param {import('./errors.js').SiteTreeError['code']} code
+     * @param {string[]} paths Paths relative to the site package root.
+     * @param {string} message
+     */
+    constructor(code, paths, message) {
+        super(`SiteTreeError ${code}\n${paths.map(path => `  ${path}`).join('\n')}\n  ${message}`)
+        this.name = 'SiteTreeError'
+        this.code = code
+        this.paths = [...paths]
+    }
+}

package/src/server/requests/index.js

@@ -0,0 +1 @@
+export {}

package/src/server/site-tree/createSiteTree.js

@@ -0,0 +1,55 @@
+import { relative, resolve, sep } from 'node:path'
+import { readSiteTree, siteRoot } from './readSiteTree.js'
+
+/** Internal live table; adapters supply file events, never a second watcher. */
+export const createSiteTree = root => {
+    const rootPath = siteRoot(root)
+    let dirty = true
+    let closed = false
+    /** @type {Promise<import('@wix/origami-types').SiteRouteTable> | undefined} */
+    let pending
+    /** @type {import('@wix/origami-types').SiteRouteTable | undefined} */
+    let current
+    let signature
+    /** @type {Set<(table: import('@wix/origami-types').SiteRouteTable) => void>} */
+    const listeners = new Set()
+    return {
+        table() {
+            if (closed) return Promise.reject(new Error('Site tree is closed.'))
+            if (dirty) {
+                dirty = false
+                // Serialize rescans, including recovery after a rejected scan.
+                pending = (pending ?? Promise.resolve()).catch(() => {}).then(async () => {
+                    const next = await readSiteTree(rootPath)
+                    const nextSignature = JSON.stringify(next)
+                    if (signature !== nextSignature) {
+                        const hadTable = current !== undefined
+                        current = next
+                        signature = nextSignature
+                        if (hadTable && !closed) for (const listener of listeners) listener(next)
+                    }
+                    return /** @type {import('@wix/origami-types').SiteRouteTable} */ (current)
+                })
+            }
+            return /** @type {Promise<import('@wix/origami-types').SiteRouteTable>} */ (pending)
+        },
+        fileChanged(path) {
+            if (closed) return
+            const changed = resolve(rootPath, path)
+            for (const directory of ['pages', 'popups']) {
+                const suffix = relative(resolve(rootPath, 'src', directory), changed)
+                if (suffix === '' || (suffix !== '..' && !suffix.startsWith(`..${sep}`) && !suffix.startsWith(sep))) dirty = true
+            }
+        },
+        /** @param {(table: import('@wix/origami-types').SiteRouteTable) => void} listener */
+        onTableChange(listener) {
+            if (!closed) listeners.add(listener)
+            return () => { listeners.delete(listener) }
+        },
+        async close() {
+            closed = true
+            listeners.clear()
+            await pending?.catch(() => {})
+        },
+    }
+}

package/src/server/site-tree/index.js

@@ -0,0 +1 @@
+export {}

package/src/server/site-tree/readSiteTree.js

@@ -0,0 +1,97 @@
+// Ported from origami-site-runtime/routing/pagesToRoutes.js for the layout 2 tree.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { parse } from '@babel/parser'
+import { SiteTreeError } from '../requests/errors.js'
+
+/** @type {Map<string, { mtimeMs: number, metadata: { title?: string, pageId?: string } }>} */
+const metadataCache = new Map()
+
+const readMetadata = structure => {
+    const ast = parse(readFileSync(structure, 'utf8'), { sourceType: 'module', plugins: ['jsx'] })
+    /** @type {{ title?: string, pageId?: string }} */
+    const metadata = {}
+    // Walk Babel's AST without a runtime dependency on @babel/types.
+    const visit = node => {
+        if (!node || typeof node !== 'object') return
+        if (node.type === 'JSXOpeningElement' && node.name.type === 'JSXIdentifier' && node.name.name === 'Page') {
+            for (const attribute of node.attributes) {
+                if (attribute.type !== 'JSXAttribute') continue
+                if (attribute.name.name === 'id' && attribute.value?.type === 'StringLiteral' && metadata.pageId === undefined)
+                    metadata.pageId = attribute.value.value
+                if (metadata.title !== undefined || attribute.name.name !== 'data' ||
+                    attribute.value?.type !== 'JSXExpressionContainer' ||
+                    attribute.value.expression.type !== 'ObjectExpression') continue
+                const property = attribute.value.expression.properties.find(candidate =>
+                    candidate.type === 'ObjectProperty' && !candidate.computed &&
+                    ((candidate.key.type === 'Identifier' && candidate.key.name === 'title') ||
+                        (candidate.key.type === 'StringLiteral' && candidate.key.value === 'title')))
+                if (property?.value.type === 'StringLiteral') metadata.title = property.value.value
+            }
+        }
+        for (const value of Object.values(node)) {
+            if (Array.isArray(value)) value.forEach(visit)
+            else if (value && typeof value === 'object') visit(value)
+        }
+    }
+    visit(ast)
+    return metadata
+}
+
+const pageMetadata = folder => {
+    const structure = resolve(folder, 'structure.jsx')
+    const fallback = basename(folder).replace(/^\(([^()]+)\)$/, '$1')
+    if (!existsSync(structure)) {
+        metadataCache.delete(structure)
+        return { title: fallback }
+    }
+    const { mtimeMs } = statSync(structure)
+    let cached = metadataCache.get(structure)
+    if (cached?.mtimeMs !== mtimeMs) {
+        cached = { mtimeMs, metadata: readMetadata(structure) }
+        metadataCache.set(structure, cached)
+    }
+    return { ...cached.metadata, title: cached.metadata.title ?? fallback }
+}
+
+export const siteRoot = root => {
+    if (typeof root !== 'string' || !root) throw new TypeError('root must be a non-empty string.')
+    return resolve(root)
+}
+
+/** @param {string} root @returns {Promise<import('@wix/origami-types').SiteRouteTable>} */
+export const readSiteTree = async root => {
+    const pagesDir = resolve(siteRoot(root), 'src/pages')
+    /** @type {import('@wix/origami-types').PageRoute[]} */
+    const pages = []
+    /** @type {import('@wix/origami-types').SiteNotFoundRoute} */
+    let notFound = { key: '@wix/origami-site/default-error-404', title: 'Page not found' }
+    const pathsByUrl = new Map()
+    const walk = (folder, itemPath) => {
+        const entries = readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))
+        const path = `src/${itemPath}`
+        if (/^\[.*\]$/.test(basename(folder)))
+            throw new SiteTreeError('NOT_SUPPORTED_YET', [path], 'Router pages are not supported yet.')
+        if (entries.some(entry => entry.name === 'route.json'))
+            throw new SiteTreeError('NOT_SUPPORTED_YET', [`${path}/route.json`], 'Router pages are not supported yet.')
+        const children = entries.filter(entry => entry.isDirectory() && !entry.name.startsWith('.') &&
+            !['_generated', 'node_modules'].includes(entry.name))
+        if (itemPath === 'pages/error404' && children.length)
+            throw new SiteTreeError('NOT_FOUND_HAS_CHILDREN', [path, ...children.map(child => `${path}/${child.name}`)],
+                'The not-found page cannot have children.')
+        if (entries.some(entry => entry.isFile() && !entry.name.startsWith('.'))) {
+            const metadata = pageMetadata(folder)
+            if (itemPath === 'pages/error404') notFound = { key: itemPath, itemPath, title: metadata.title }
+            else {
+                const url = '/' + itemPath.split('/').slice(1).filter(segment => !/^\([^()]+\)$/.test(segment)).join('/')
+                const previous = pathsByUrl.get(url)
+                if (previous) throw new SiteTreeError('DUPLICATE_URL', [previous, path], `Both pages serve "${url}".`)
+                pathsByUrl.set(url, path)
+                pages.push({ key: itemPath, url, itemPath, ...metadata, access: [] })
+            }
+        }
+        for (const child of children) walk(resolve(folder, child.name), `${itemPath}/${child.name}`)
+    }
+    if (existsSync(pagesDir)) walk(pagesDir, 'pages')
+    return { version: 2, pages, routers: [], notFound, popups: [] }
+}

package/src/styles.d.ts

@@ -0,0 +1,2 @@
+// The copied 404 entry imports the package's stylesheet as a bundler side effect.
+declare module '@wix/builder-error-pages/style.css'

package/src/types/index.d.ts

@@ -0,0 +1,48 @@
+/** What each adapter package exports as its default `origami` descriptor. */
+export interface OrigamiAdapter {
+  name: string                                   // '@wix/origami-site-astro'
+  version: string                                // its package version
+  framework: { name: string; range: string }     // { name: 'astro', range: '^7.3.0' }
+  /** Files and package.json fields the generator writes for this adapter (section 8). */
+  project(ctx: ProjectContext): ProjectFiles
+  /** How the conformance suite runs a site with this adapter. */
+  conformance: ConformanceDriver
+}
+
+export type ProjectContext = {
+  siteName: string
+  coreVersion: string                            // the @wix/origami-site range to depend on
+  nodeVersion: string                            // '22'
+}
+
+export type ProjectFiles = {
+  files: Record<string /* path relative to the site package */, string /* contents */>   // e.g. astro.config.mjs, Dockerfile
+  packageJson: {
+    scripts: { dev: string; build: string; start: string } & Record<string, string>
+    dependencies: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  readme: string                                 // markdown section appended to the site README
+}
+
+export interface ConformanceDriver {
+  /** Start `yarn dev`. Resolves when the server answers. */
+  dev(root: string, env: SiteEnv): Promise<RunningSite>
+  // PLAN-QUESTION: Keep the explicit BuildResult union; rejection policy is deferred to adapters.
+  /** Run `yarn build`. */
+  build(root: string, env: SiteEnv): Promise<BuildResult>
+  /** Start `yarn start` after a build. */
+  start(root: string, env: SiteEnv): Promise<RunningSite>
+}
+
+export type SiteEnv = Record<string, string>     // VITE_WIX_CLIENT_ID, VITE_WIX_SITE_ID, ORIGAMI_WIX_API_BASE (tests), PORT
+export type RunningSite = { url: URL; logs(): string; restarts(): number; stop(): Promise<void> }
+export type BuildResult = { ok: true; output: string } | { ok: false; output: string }
+
+
+/** Core contracts only; runtime APIs belong to @wix/origami-site/server. */
+export type {
+  SiteOptions, OrigamiSite, RouteMatch, Resolution, PageRef, PageData,
+  RequestContext, TokenProvider, AccessRule, AccessSource, AccessHandler,
+  Logger, SiteTreeError, RouterServiceError,
+} from '../server/index.js'

package/src/types/index.js

@@ -0,0 +1 @@
+export {}

package/src/vite-plugins/index.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite'
+export function origamiVitePlugins(options: { root: string }): Plugin[]

package/src/vite-plugins/index.js

@@ -0,0 +1 @@
+export {}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.