@lowdefy/build 5.0.0 → 5.2.0

package/dist/build/fetchGitHubModule.js

@@ -0,0 +1,94 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { promisify } from 'node:util';
+import { Unpack } from 'tar';
+import { ConfigError } from '@lowdefy/errors';
+const execFileAsync = promisify(execFile);
+function isImmutableRef(ref) {
+    // Full or abbreviated commit SHAs
+    if (/^[0-9a-f]{7,40}$/.test(ref)) return true;
+    // Semver-like tags: v1.0.0, v1, 1.2.3, v1.0.0-beta.1, etc.
+    if (/^v?\d+(\.\d+)*(-[\w.]+)?$/.test(ref)) return true;
+    return false;
+}
+async function getGhToken() {
+    try {
+        const { stdout } = await execFileAsync('gh', [
+            'auth',
+            'token'
+        ]);
+        return stdout.trim() || null;
+    } catch  {
+        return null;
+    }
+}
+async function extractTarball(body, destDir) {
+    // Ensure destination exists and is clean
+    fs.mkdirSync(destDir, {
+        recursive: true
+    });
+    // GitHub tarballs have a top-level directory like {owner}-{repo}-{sha}/
+    // We strip it so contents extract directly into destDir
+    await pipeline(body, createGunzip(), new Unpack({
+        cwd: destDir,
+        strip: 1
+    }));
+}
+async function fetchGitHubModule(source, context) {
+    const cacheDir = path.join(context.directories.config, '.lowdefy', 'modules', 'github');
+    const repoCache = path.join(cacheDir, source.owner, source.repo, source.ref);
+    // Check cache — only skip fetch for refs we're confident are immutable
+    if (fs.existsSync(repoCache) && isImmutableRef(source.ref)) {
+        return {
+            packageRoot: repoCache
+        };
+    }
+    // Fetch tarball from GitHub API
+    const url = `https://api.github.com/repos/${source.owner}/${source.repo}/tarball/${source.ref}`;
+    const headers = {
+        Accept: 'application/vnd.github+json'
+    };
+    // Auth: GITHUB_TOKEN env var, then gh CLI token
+    const token = process.env.GITHUB_TOKEN || await getGhToken();
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    const response = await fetch(url, {
+        headers,
+        redirect: 'follow'
+    });
+    if (!response.ok) {
+        throw new ConfigError(`Failed to fetch module from ${url}: ${response.status} ${response.statusText}`);
+    }
+    // Clean existing cache for mutable refs before extracting
+    if (fs.existsSync(repoCache)) {
+        fs.rmSync(repoCache, {
+            recursive: true,
+            force: true
+        });
+    }
+    // Extract tarball to cache
+    await extractTarball(response.body, repoCache);
+    return {
+        packageRoot: repoCache
+    };
+}
+export default fetchGitHubModule;
+export { isImmutableRef, getGhToken, extractTarball };

package/dist/build/fetchModules.js

@@ -0,0 +1,60 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import fs from 'node:fs';
+import path from 'node:path';
+import { ConfigError } from '@lowdefy/errors';
+import fetchGitHubModule from './fetchGitHubModule.js';
+import parseModuleSource from './parseModuleSource.js';
+function findGitRoot(startPath) {
+    let dir = startPath;
+    while(true){
+        if (fs.existsSync(path.join(dir, '.git'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+async function fetchModules({ moduleEntries, context }) {
+    const resolved = {};
+    for (const entry of moduleEntries){
+        const source = parseModuleSource(entry.source);
+        if (source.type === 'file') {
+            const resolvedPath = path.resolve(context.directories.config, source.path);
+            if (!fs.existsSync(path.join(resolvedPath, 'module.lowdefy.yaml'))) {
+                throw new ConfigError(`Module "${entry.id}": module.lowdefy.yaml not found at ${resolvedPath}`);
+            }
+            resolved[entry.id] = {
+                packageRoot: findGitRoot(resolvedPath) ?? resolvedPath,
+                moduleRoot: resolvedPath,
+                isLocal: true
+            };
+        } else if (source.type === 'github') {
+            const cached = await fetchGitHubModule(source, context);
+            const moduleRoot = source.path ? path.join(cached.packageRoot, source.path) : cached.packageRoot;
+            if (!fs.existsSync(path.join(moduleRoot, 'module.lowdefy.yaml'))) {
+                throw new ConfigError(`Module "${entry.id}": module.lowdefy.yaml not found at path "${source.path || '/'}" in ${source.owner}/${source.repo}@${source.ref}`);
+            }
+            resolved[entry.id] = {
+                packageRoot: cached.packageRoot,
+                moduleRoot,
+                isLocal: false
+            };
+        }
+    }
+    return resolved;
+}
+export default fetchModules;

package/dist/build/full/buildPages.js

@@ -16,6 +16,7 @@
 import { ConfigError, shouldSuppressBuildCheck } from '@lowdefy/errors';
 import buildPage from '../buildPages/buildPage.js';
 import createCheckDuplicateId from '../../utils/createCheckDuplicateId.js';
+import validateCallApiRefs from '../buildPages/validateCallApiRefs.js';
 import validateLinkReferences from '../buildPages/validateLinkReferences.js';
 import validatePayloadReferences from '../buildPages/validatePayloadReferences.js';
 import validateServerStateReferences from '../buildPages/validateServerStateReferences.js';
@@ -25,8 +26,9 @@ function buildPages({ components, context }) {
     const checkDuplicatePageId = createCheckDuplicateId({
         message: 'Duplicate pageId "{{ id }}".'
     });
-    // Initialize linkActionRefs to collect Link action references across all pages
+    // Initialize action ref collections across all pages
     context.linkActionRefs = [];
+    context.callApiActionRefs = [];
     // Track which pages failed to build so we skip them in validation
     const failedPageIndices = new Set();
     // Wrap each page build to collect errors instead of stopping on first error
@@ -64,6 +66,13 @@ function buildPages({ components, context }) {
         pageIds,
         context
     });
+    // Validate that CallAPI actions don't target InternalApi endpoints
+    const endpointConfigs = type.isArray(components.api) ? components.api : [];
+    validateCallApiRefs({
+        callApiActionRefs: context.callApiActionRefs,
+        endpointConfigs,
+        context
+    });
     // Validate that _state references use defined block IDs
     // and _payload references use defined payload keys
     // Skip pages that failed to build

package/dist/build/full/writePages.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */ import { serializer } from '@lowdefy/helpers';
 async function writePage({ page, context }) {
-    await context.writeBuildArtifact(`pages/${page.pageId}/${page.pageId}.json`, serializer.serializeToString(page ?? {}));
+    await context.writeBuildArtifact(`pages/${page.pageId}.json`, serializer.serializeToString(page ?? {}));
 }
 async function writePages({ components, context }) {
     const writePromises = components.pages.map((page)=>writePage({

package/dist/build/jit/buildPageJit.js

@@ -19,6 +19,7 @@ import { ConfigError, LowdefyInternalError } from '@lowdefy/errors';
 import operators from '@lowdefy/operators-js/operators/build';
 import addKeys from '../addKeys.js';
 import buildPage from '../buildPages/buildPage.js';
+import validateCallApiRefs from '../buildPages/validateCallApiRefs.js';
 import validateLinkReferences from '../buildPages/validateLinkReferences.js';
 import validatePayloadReferences from '../buildPages/validatePayloadReferences.js';
 import validateServerStateReferences from '../buildPages/validateServerStateReferences.js';
@@ -83,7 +84,7 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
         // All user pages (with refId) always JIT-resolve from source YAML so that
         // page-only edits are picked up without a skeleton rebuild.
         if (!pageEntry.refId) {
-            const pagePath = path.join(buildContext.directories.build, 'pages', pageId, `${pageId}.json`);
+            const pagePath = path.join(buildContext.directories.build, 'pages', `${pageId}.json`);
             try {
                 const content = await fs.promises.readFile(pagePath, 'utf8');
                 const page = serializer.deserialize(JSON.parse(content));
@@ -96,6 +97,13 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
                 if (err.code !== 'ENOENT') throw err;
             }
         }
+        // If this is a module page, set up module context
+        let moduleDependencies = null;
+        let moduleEntry = null;
+        if (pageEntry.moduleEntryId) {
+            moduleEntry = buildContext.modules[pageEntry.moduleEntryId];
+            moduleDependencies = moduleEntry?.moduleDependencies ?? null;
+        }
         // Resolve the page file from scratch using the source file path determined
         // by createPageRegistry's parent chain walk.
         if (!pageEntry.refPath && !pageEntry.resolverOriginal) {
@@ -113,6 +121,10 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
                 refId: varRefDef.id,
                 sourceRefId: null,
                 vars: {},
+                moduleDependencies,
+                moduleEntry: moduleEntry ?? null,
+                moduleRoot: moduleEntry?.moduleRoot ?? null,
+                packageRoot: moduleEntry?.packageRoot ?? null,
                 path: '',
                 currentFile: pageEntry.refPath ?? pageEntry.resolverOriginal?.resolver ?? '',
                 refChain: new Set(),
@@ -149,6 +161,10 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
             refId: refDef.id,
             sourceRefId: null,
             vars: refDef.vars ?? {},
+            moduleDependencies,
+            moduleEntry: moduleEntry ?? null,
+            moduleRoot: moduleEntry?.moduleRoot ?? null,
+            packageRoot: moduleEntry?.packageRoot ?? null,
             path: '',
             currentFile: refDef.path ?? '',
             refChain: new Set(),
@@ -164,13 +180,18 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
             refDef
         });
         // When resolving from a collection file (with vars), the result is an array of pages.
-        // Find the specific page by ID.
+        // Find the specific page by ID. For module pages, source IDs are unscoped.
         if (type.isArray(processed)) {
-            processed = processed.find((p)=>type.isObject(p) && p.id === pageId);
+            const unscopedId = moduleEntry ? pageId.slice(`${moduleEntry.id}/`.length) : pageId;
+            processed = processed.find((p)=>type.isObject(p) && p.id === unscopedId);
             if (!processed) {
                 throw new ConfigError(`Page "${pageId}" not found in resolved page source file.`);
             }
         }
+        // JIT builds resolve from source YAML — the page ID is unscoped for module pages
+        if (moduleEntry && type.isObject(processed) && processed.id) {
+            processed.id = `${moduleEntry.id}/${processed.id}`;
+        }
         // Tag all objects with ~r for ref provenance (normally done inside _ref
         // resolution by the walker; JIT resolves the page file directly).
         tagRefDeep(processed, refDef.id);
@@ -186,10 +207,13 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
         await writeMaps({
             context: buildContext
         });
-        // Initialize linkActionRefs for buildPage (normally done by buildPages)
+        // Initialize action ref collections for buildPage (normally done by buildPages)
         if (!buildContext.linkActionRefs) {
             buildContext.linkActionRefs = [];
         }
+        if (!buildContext.callApiActionRefs) {
+            buildContext.callApiActionRefs = [];
+        }
         // Build the page (validation, block processing)
         const checkDuplicatePageId = createCheckDuplicateId({
             message: 'Duplicate pageId "{{ id }}".'
@@ -237,6 +261,12 @@ async function buildPageJit({ pageId, pageRegistry, context, directories, logger
             pageIds,
             context: buildContext
         });
+        const endpointConfigs = type.isArray(buildContext.components?.api) ? buildContext.components.api : [];
+        validateCallApiRefs({
+            callApiActionRefs: buildContext.callApiActionRefs,
+            endpointConfigs,
+            context: buildContext
+        });
         validateStateReferences({
             page: processed,
             context: buildContext

package/dist/build/jit/collectSkeletonSourceFiles.js

@@ -39,6 +39,14 @@ function collectSkeletonSourceFiles({ components, context }) {
         if (key === 'pages') continue;
         walkRefIds(components[key], refIds);
     }
+    // Module consumerVars contribute to skeleton state via modules.json.
+    // Their ~r markers may only appear under pages (when consumed via
+    // _module.var inside page-referenced components), so the non-page
+    // walk above can miss them. Walk here so changes to per-app module
+    // vars files trigger a skeleton rebuild.
+    for (const moduleEntry of Object.values(context.modules ?? {})){
+        walkRefIds(moduleEntry.consumerVars, refIds);
+    }
     const sourceFiles = new Set();
     // Walk parent chains for each collected ref ID
     for (const refId of refIds){

package/dist/build/jit/createPageRegistry.js

@@ -58,6 +58,14 @@ function findPageSourceRef(refId, refMap, unresolvedRefVars) {
     }
     return firstChildOfRoot;
 }
+function getModuleEntryId(pageId, context) {
+    for (const entryId of Object.keys(context.modules ?? {})){
+        if (pageId.startsWith(`${entryId}/`)) {
+            return entryId;
+        }
+    }
+    return null;
+}
 function createPageRegistry({ components, context }) {
     const registry = new Map();
     const unresolvedRefVars = context.unresolvedRefVars ?? {};
@@ -77,7 +85,8 @@ function createPageRegistry({ components, context }) {
             refId: isInline ? null : refId,
             refPath: sourceRef?.path ?? null,
             unresolvedVars: sourceRef?.unresolvedVars ?? null,
-            resolverOriginal: sourceRef?.original ?? null
+            resolverOriginal: sourceRef?.original ?? null,
+            moduleEntryId: getModuleEntryId(page.id, context)
         });
     });
     return registry;

package/dist/build/jit/shallowBuild.js

@@ -12,7 +12,8 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ import { BuildError, LowdefyInternalError } from '@lowdefy/errors';
+*/ import { serializer } from '@lowdefy/helpers';
+import { BuildError, LowdefyInternalError } from '@lowdefy/errors';
 import createContext from '../../createContext.js';
 import logCollectedErrors from '../../utils/logCollectedErrors.js';
 import makeId from '../../utils/makeId.js';
@@ -26,6 +27,8 @@ import buildApi from '../buildApi/buildApi.js';
 import buildLogger from '../buildLogger.js';
 import buildImports from '../buildImports/buildImports.js';
 import buildMenu from '../buildMenu.js';
+import buildModuleDefs from '../buildModuleDefs.js';
+import buildModules from '../buildModules.js';
 import buildRefs from '../buildRefs/buildRefs.js';
 import buildTypes from '../buildTypes.js';
 import cleanBuildDirectory from '../cleanBuildDirectory.js';
@@ -51,15 +54,19 @@ import buildJsShallow from './buildJsShallow.js';
 import buildShallowPages from './buildShallowPages.js';
 import collectPageContent from '../collectPageContent.js';
 import collectSkeletonSourceFiles from './collectSkeletonSourceFiles.js';
-import stripPageContent from './stripPageContent.js';
 import writeSourcelessPages from './writeSourcelessPages.js';
 async function shallowBuild(options) {
     makeId.reset();
     let context;
     try {
         context = createContext(options);
+        // Phase 1: Build module definitions
+        await buildModuleDefs({
+            context
+        });
         let components;
         try {
+            // Phase 2: Ref resolution (with shallow options)
             components = await buildRefs({
                 context,
                 shallowOptions: true
@@ -75,6 +82,11 @@ async function shallowBuild(options) {
         // Failed _ref resolutions leave null entries in arrays — logging now
         // surfaces the real error before downstream code crashes on nulls.
         logCollectedErrors(context);
+        // Phase 3: Process modules — scopes IDs, merges into components
+        buildModules({
+            components,
+            context
+        });
         // Collect skeleton source files while ~r markers still exist on objects.
         const skeletonSourceFiles = collectSkeletonSourceFiles({
             components,
@@ -85,6 +97,13 @@ async function shallowBuild(options) {
             components,
             context
         });
+        tryBuildStep(testSchema, 'testSchema', {
+            components,
+            context
+        });
+        logCollectedErrors(context);
+        // Collect page content strings for Tailwind to scan.
+        // Runs after testSchema so null block entries are caught before walking.
         context.tailwindContentMap = new Map();
         for (const page of components.pages ?? []){
             const content = collectPageContent([
@@ -94,15 +113,6 @@ async function shallowBuild(options) {
                 context.tailwindContentMap.set(page.id, content);
             }
         }
-        stripPageContent({
-            components,
-            context
-        });
-        tryBuildStep(testSchema, 'testSchema', {
-            components,
-            context
-        });
-        logCollectedErrors(context);
         // Build skeleton steps (everything except page content)
         tryBuildStep(buildApp, 'buildApp', {
             components,
@@ -238,6 +248,7 @@ async function shallowBuild(options) {
         await context.writeBuildArtifact('installedPluginPackages.json', JSON.stringify([
             ...context.installedPackages ?? []
         ]));
+        await context.writeBuildArtifact('modules.json', serializer.serializeToString(context.modules ?? {}));
         await writePluginImports({
             components,
             context

package/dist/build/jit/writePageJit.js

@@ -19,7 +19,7 @@ import collectPageContent from '../collectPageContent.js';
 import writeJs from '../buildJs/writeJs.js';
 async function writePageJit({ page, context }) {
     // Write page JSON
-    await context.writeBuildArtifact(`pages/${page.pageId}/${page.pageId}.json`, serializer.serializeToString(page ?? {}));
+    await context.writeBuildArtifact(`pages/${page.pageId}.json`, serializer.serializeToString(page ?? {}));
     // Write page request JSONs
     const requests = page.requests ?? [];
     for (const request of requests){
@@ -47,6 +47,6 @@ async function writePageJit({ page, context }) {
     const pageContent = collectPageContent([
         page
     ]);
-    await writeFile(path.join(context.directories.server, 'lowdefy-build', 'tailwind', `${page.pageId}.html`), '<!-- Generated by Lowdefy build -->\n' + (pageContent ?? ''));
+    await writeFile(path.join(context.directories.server, 'lowdefy-build', 'tailwind', `${encodeURIComponent(page.pageId)}.html`), '<!-- Generated by Lowdefy build -->\n' + (pageContent ?? ''));
 }
 export default writePageJit;

package/dist/build/jit/writeSourcelessPages.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */ async function writeSourcelessPages({ sourcelessPageArtifacts, context }) {
     for (const artifact of sourcelessPageArtifacts){
-        await context.writeBuildArtifact(`pages/${artifact.pageId}/${artifact.pageId}.json`, artifact.pageJson);
+        await context.writeBuildArtifact(`pages/${artifact.pageId}.json`, artifact.pageJson);
         for (const request of artifact.requests){
             await context.writeBuildArtifact(`pages/${artifact.pageId}/requests/${request.requestId}.json`, request.requestJson);
         }

package/dist/build/parseModuleSource.js

@@ -0,0 +1,48 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigError } from '@lowdefy/errors';
+function parseModuleSource(source) {
+    if (source.startsWith('file:')) {
+        return {
+            type: 'file',
+            path: source.slice(5)
+        };
+    }
+    if (source.startsWith('github:')) {
+        const rest = source.slice(7);
+        const atIndex = rest.lastIndexOf('@');
+        if (atIndex === -1) {
+            throw new ConfigError(`Module source "${source}" is missing @ref (e.g., @v1.0.0).`);
+        }
+        const ref = rest.slice(atIndex + 1);
+        const fullPath = rest.slice(0, atIndex);
+        const segments = fullPath.split('/');
+        if (segments.length < 2) {
+            throw new ConfigError(`Module source "${source}" must include owner/repo.`);
+        }
+        const owner = segments[0];
+        const repo = segments[1];
+        const path = segments.length > 2 ? segments.slice(2).join('/') : null;
+        return {
+            type: 'github',
+            owner,
+            repo,
+            path,
+            ref
+        };
+    }
+    throw new ConfigError(`Unknown module source type: "${source}". Expected "github:" or "file:".`);
+}
+export default parseModuleSource;