Subchapter 47.12

Wix Headless Scaffold

Wix Dashboard URL

Also bundled

Publish Manifest

21 more in the appendix

Position

12 of 34

Type

JavaScript

Size

15 KB

Lines

335

Nearby

Source

scripts/wix-headless-scaffold.js

JavaScript335 lines15 KB

1#!/usr/bin/env node
2'use strict';
3
4const { spawn } = require('node:child_process');
5const fs = require('node:fs/promises');
6const path = require('node:path');
7const { readEnvFile, upsertEnvFile, statEnvKeys

wix-headless-scaffold.js on GitHub

}

=

require

(

'../lib/config-env.js'

);

function usage() {

return [

'Usage:',

' node scripts/wix-headless-scaffold.js --business-name <name> [--folder-name frontend] [--site-template commerce] [--project-dir <dir>]',

'',

'Runs the Wix headless scaffold non-interactively through npm create.',

'Idempotent: safe to re-invoke against the same project (spec 0085) — adopts an',

'existing destination receipt instead of re-scaffolding, and never spawns a second',

'site when config/wix.env or frontend/wix.config.json already name one.',

].join('\n');

}

function parseArgs(argv) {

const args = {

folderName: 'frontend',

siteTemplate: 'blank',

projectDir: process.cwd(),

};

for (let i = 0; i < argv.length; i += 1) {

const token = argv[i];

switch (token) {

case '--business-name':

args.businessName = argv[i + 1];

i += 1;

break;

case '--folder-name':

args.folderName = argv[i + 1];

i += 1;

break;

case '--site-template':

args.siteTemplate = argv[i + 1];

i += 1;

break;

case '--project-dir':

args.projectDir = argv[i + 1];

i += 1;

break;

case '--help':

case '-h':

args.help = true;

break;

default:

throw new Error(`Unknown argument: ${token}`);

}

return args;

}

async function readWixConfig(frontendDir) {

try {

const raw = await fs.readFile(path.join(frontendDir, 'wix.config.json'), 'utf8');

const parsed = JSON.parse(raw);

if (parsed && typeof parsed.siteId === 'string' && parsed.siteId.trim() !== '') {

return parsed;

}

return null;

} catch (error) {

if (error && (error.code === 'ENOENT' || error instanceof SyntaxError)) {

return null;

}

throw error;

}

async function readWixEnvValues(wixEnvPath) {

try {

return await readEnvFile(wixEnvPath);

} catch (error) {

if (error && error.code === 'ENOENT') {

return {};

}

throw error;

}

async function isNonEmptyDir(dir) {

try {

const entries = await fs.readdir(dir);

return entries.length > 0;

} catch (error) {

if (error && error.code === 'ENOENT') {

return false;

}

throw error;

}

async function defaultSpawnScaffold(args) {

return new Promise((resolve, reject) => {

const child = spawn('npm', [

'--yes',

'create',

'@wix/new@latest',

'--',

'headless',

'--business-name',

args.businessName,

'--folder-name',

args.folderName,

'--site-template',

args.siteTemplate,

'--skip-install',

], {

cwd: path.resolve(args.projectDir),

stdio: 'inherit',

});

child.on('error', reject);

child.on('exit', (code, signal) => {

resolve({ code: signal ? 1 : (code == null ? 1 : code) });

});

}

// Removes WIX_SCAFFOLD_STATUS entirely (not just blanking its value, which config-env.js's

// upsertEnvFile cannot do and which would itself read back as a present-but-unrecognized

// value) — used only when a spawn-launch failure proves nothing could have been created,

// so the next invocation sees a genuinely untouched config/wix.env, not a lingering marker.

async function clearWixScaffoldStatus(wixEnvPath) {

let raw;

try {

raw = await fs.readFile(wixEnvPath, 'utf8');

} catch (error) {

if (error && error.code === 'ENOENT') {

return;

}

throw error;

}

const hadTrailingNewline = /\r?\n$/.test(raw);

const lines = raw.split(/\r?\n/);

if (hadTrailingNewline && lines[lines.length - 1] === '') {

lines.pop();

}

const kept = lines.filter((line) => {

const trimmed = line.trim();

if (!trimmed || trimmed.startsWith('#')) {

return true;

}

const idx = line.indexOf('=');

return idx === -1 || line.slice(0, idx).trim() !== 'WIX_SCAFFOLD_STATUS';

});

const out = kept.join('\n');

await fs.writeFile(wixEnvPath, out === '' ? '' : `${out}\n`, 'utf8');

}

// Persists WIX_SITE_ID from a confirmed receipt, re-checking for a conflict immediately

// before the write (config/wix.env can change between the top-of-invocation read and now).

// Uses statEnvKeys' placeholder-aware classification for the conflict check — PR #184

// review correction: comparing the raw value directly treated a template placeholder

// (e.g. WIX_SITE_ID=REPLACE_WITH_REAL_VALUE) as a real, conflicting destination, which

// made this throw instead of persisting on the very first scaffold of a freshly

// templated project, silently discarding the receipt this function exists to confirm.

async function persistSiteId(wixEnvPath, siteId, scaffoldStatus) {

const currentStatus = (await statEnvKeys(wixEnvPath, ['WIX_SITE_ID'])).keys.WIX_SITE_ID;

if (currentStatus === 'present') {

const current = await readWixEnvValues(wixEnvPath);

if (current.WIX_SITE_ID !== siteId) {

throw new Error(

`config/wix.env's WIX_SITE_ID (${current.WIX_SITE_ID}) no longer matches the scaffold's own wix.config.json (${siteId}); refusing to overwrite a different destination.`,

);

}

await upsertEnvFile(wixEnvPath, { WIX_SITE_ID: siteId, WIX_SCAFFOLD_STATUS: scaffoldStatus });

}

// spec 0085: safe to call more than once against the same project directory, including

// after its own prior partial failure. Every branch below either confirms a destination

// receipt before returning success, or fails closed without touching config/wix.env.

async function ensureDestinationReceipt(args, { spawnScaffold = defaultSpawnScaffold } = {}) {

const projectDir = path.resolve(args.projectDir);

const frontendDir = path.join(projectDir, args.folderName);

const wixEnvPath = path.join(projectDir, 'config', 'wix.env');

const siteIdStatus = (await statEnvKeys(wixEnvPath, ['WIX_SITE_ID'])).keys.WIX_SITE_ID;

const envValues = await readWixEnvValues(wixEnvPath);

const wixConfig = await readWixConfig(frontendDir);

if (siteIdStatus === 'present') {

// Case 1: config/wix.env already names a destination — checked first, independent of

// wix.config.json, so an env-only receipt (adopted/existing destination, or a lost

// frontend folder) can never fall through to spawning a second site.

if (wixConfig && wixConfig.siteId !== envValues.WIX_SITE_ID) {

// 1b — conflicting.

throw new Error(

`config/wix.env already has WIX_SITE_ID=${envValues.WIX_SITE_ID}, but ${frontendDir}/wix.config.json names a different siteId=${wixConfig.siteId}. Refusing to create or adopt a second destination — resolve the conflict manually.`,

);

}

// 1a — consistent (wix.config.json is absent, has no siteId, or matches).

const status = envValues.WIX_SCAFFOLD_STATUS;

if (status === undefined || status === 'complete') {

return { siteId: envValues.WIX_SITE_ID };

}

if (status === 'incomplete') {

throw new Error(

`Destination ${envValues.WIX_SITE_ID} already exists, but a prior scaffold attempt did not complete (WIX_SCAFFOLD_STATUS=incomplete). Refusing to spawn again — that would risk a duplicate site. Resolve manually before retrying.`,

);

}

throw new Error(

`config/wix.env has an unrecognized WIX_SCAFFOLD_STATUS value (${JSON.stringify(status)}); expected "complete", "incomplete", or the key to be absent. Refusing to proceed.`,

);

}

// Case 2: no confirmed real WIX_SITE_ID (missing, blank, or a placeholder — all treated

// alike here, matching case 1's classification). PR #184 review correction: this branch

// must also inspect WIX_SCAFFOLD_STATUS, not just wix.config.json's existence — a bare

// "wix.config.json exists" check cannot tell a genuinely legacy/host-adopted receipt

// apart from one left behind by a scaffold attempt this script itself started but never

// finished recording (the wrapper crashed, or was killed, after the CLI created the site

// but before persistSiteId ran). Silently adopting the latter as "complete" is the same

// laundering bug as case 1 exists to prevent, just reached from the opposite direction.

const status = envValues.WIX_SCAFFOLD_STATUS;

if (status === 'in_progress') {

if (wixConfig) {

// A prior invocation marked in_progress before spawning (see 2c below) and never

// got to record a final outcome. The CLI may well have finished — never infer

// "complete" from an orphaned receipt like this. Persist it as incomplete (the same

// durable, fail-closed record a known non-zero exit produces) so the *next*

// invocation adopts and blocks via case 1's existing, tested handling instead of

// this ambiguity recurring indefinitely.

await persistSiteId(wixEnvPath, wixConfig.siteId, 'incomplete');

throw new Error(

`A prior scaffold attempt was interrupted before it could record its outcome (WIX_SCAFFOLD_STATUS=in_progress), but a destination was found (WIX_SITE_ID=${wixConfig.siteId}). Persisted as incomplete — resolve manually before retrying.`,

);

}

// PR #184 review correction (round 6): no local receipt either does NOT mean nothing

// was created remotely — a crash could have happened after a remote site was created

// but before wix.config.json was written locally (or even before the frontend folder

// existed at all), which isNonEmptyDir below cannot detect. Fail closed

// unconditionally rather than falling through to 2b/2c; the one case that clears this

// marker for a safe automatic retry is a genuine spawn-launch failure (see 2c) — that

// is handled before this marker is ever left behind, not by re-reading it here.

throw new Error(

'A prior scaffold attempt was interrupted before it could record any outcome (WIX_SCAFFOLD_STATUS=in_progress) and no local destination receipt (wix.config.json) exists either. This cannot be safely distinguished from a remote site having been created before a local receipt was written. Refusing to retry automatically — confirm whether a destination already exists, then either record its WIX_SITE_ID manually or clear WIX_SCAFFOLD_STATUS from config/wix.env if nothing was actually created.',

);

}

if (status !== undefined) {

// WIX_SCAFFOLD_STATUS is set to something else (a known-ambiguous marker from this

// script, or corrupted state) while no real WIX_SITE_ID exists. Fail closed rather

// than silently proceeding as though nothing were recorded.

throw new Error(

`config/wix.env has WIX_SCAFFOLD_STATUS=${JSON.stringify(status)} but no valid WIX_SITE_ID; this cannot be automatically resolved. Refusing to proceed automatically — resolve manually.`,

);

}

if (wixConfig) {

// 2a — adopt a receipt with no status marker at all: a genuinely legacy/host-adopted

// destination, or one scaffolded before this script wrote WIX_SCAFFOLD_STATUS.

await upsertEnvFile(wixEnvPath, { WIX_SITE_ID: wixConfig.siteId, WIX_SCAFFOLD_STATUS: 'complete' });

return { siteId: wixConfig.siteId };

}

if (await isNonEmptyDir(frontendDir)) {

// 2b — genuinely ambiguous state this script cannot resolve on its own.

throw new Error(

`${frontendDir} already exists and is not empty, but no valid wix.config.json was found there and config/wix.env has no WIX_SITE_ID. Refusing to scaffold into this folder automatically — resolve manually before retrying.`,

);

}

// 2c — nothing exists yet; mark in_progress before spawning so a crash between now and

// persisting a final outcome always leaves a distinguishable trace instead of silently

// looking like "nothing was ever attempted."

await upsertEnvFile(wixEnvPath, { WIX_SCAFFOLD_STATUS: 'in_progress' });

let code;

try {

({ code } = await spawnScaffold(args));

} catch (spawnError) {

// A rejection alone isn't proof nothing was created — spawnScaffold could fail for

// reasons other than a launch failure after the child already did real work. Check for

// a receipt regardless of why this rejected: if one exists, leave the in_progress

// marker in place so the next invocation's self-heal branch above handles it (never

// clear a marker out from under a receipt that might exist). Only when there is

// genuinely no receipt is it safe to clear — for the real spawnScaffold, which only

// rejects via child_process's 'error' event (emitted specifically when the OS-level

// process itself could never be launched, before any exit code exists), that absence

// is deterministic: nothing could have been created remotely.

const orphanedConfig = await readWixConfig(frontendDir);

if (!orphanedConfig) {

await clearWixScaffoldStatus(wixEnvPath);

}

throw spawnError;

}

const postConfig = await readWixConfig(frontendDir);

if (postConfig) {

// Persisted even on a non-zero exit: site creation and later template/release work are

// separate phases of the CLI's run, so discarding the id here is exactly how a retry

// would spawn a second site.

await persistSiteId(wixEnvPath, postConfig.siteId, code === 0 ? 'complete' : 'incomplete');

if (code === 0) {

return { siteId: postConfig.siteId };

}

throw new Error(

`Scaffold process exited with code ${code}, but a destination was created (WIX_SITE_ID=${postConfig.siteId}); persisted as incomplete. Do not retry automatically — resolve the underlying failure first.`,

);

}

// The child process definitely ran to completion (it returned an exit code), but no

// valid local receipt was found. This must NOT be left as a retryable in_progress

// marker: a remote site could still have been created before a local write failed.

// Convert it to a durable, always-blocked marker instead.

await upsertEnvFile(wixEnvPath, { WIX_SCAFFOLD_STATUS: 'ambiguous' });

if (code === 0) {

throw new Error('Scaffold process exited 0, but no wix.config.json with a siteId was found afterward — cannot confirm whether a destination was created. Marked ambiguous; resolve manually before retrying.');

}

throw new Error(`Scaffold process exited with code ${code} and no destination receipt was found — cannot confirm whether a destination was created. Marked ambiguous; resolve manually before retrying.`);

}

async function main() {

const args = parseArgs(process.argv.slice(2));

if (args.help) {

console.log(usage());

return;

}

if (!args.businessName) {

console.error(usage());

process.exit(1);

return;

}

const result = await ensureDestinationReceipt(args);

console.log(JSON.stringify({ ok: true, siteId: result.siteId }));

}

if (require.main === module) {

main().catch((error) => {

console.error(error && error.message ? error.message : error);

process.exit(1);

});

}

module.exports = { ensureDestinationReceipt, parseArgs, usage };