configuration-management 0.1.4 → 0.1.6

package/README.md

@@ -82,22 +82,25 @@ async function main (params) {
 Spectrum-based Commerce Admin extension UI for schema-driven system configuration.
 
 ```js
+import React from 'react'
 import { createRoot } from 'react-dom/client'
 import {
   ConfigurationManagementApp,
-  configureWeb,
-  SystemConfig
+  configureWeb
 } from 'configuration-management/web'
-import actionUrls from './config.json' // deploy-time URLs from aio app deploy
+import actionUrls from './config.json'
 import 'configuration-management/web/styles.css'
 
 configureWeb({ actionUrls })
 
 createRoot(document.getElementById('root')).render(
-  <ConfigurationManagementApp runtime={runtime} ims={ims} />
+  React.createElement(ConfigurationManagementApp, { runtime, ims })
 )
 ```
 
+The web UI is **pre-built** in the package (`web/dist/index.js`), so no Parcel
+`includeNodeModules` or webpack aliases are required in your host `package.json`.
+
 | Export | Description |
 |--------|-------------|
 | `ConfigurationManagementApp` | Full app shell (router + Spectrum provider + UIX registration) |
@@ -114,8 +117,9 @@ OpenWhisk runtime actions and the Commerce Admin extension manifest ship with th
 
 #### Automatic wiring on `npm install`
 
-The package runs a **postinstall** script that patches your project's `app.config.yaml`
-(if it exists) with:
+The package runs a **postinstall** script that:
+
+1. Patches your project's `app.config.yaml` (if present) with:
 
 ```yaml
 extensions:
@@ -123,7 +127,20 @@ extensions:
     $include: node_modules/configuration-management/actions/configurations/ext.config.yaml
 ```
 
-Requirements:
+2. Scaffolds a minimal `web-src/` bootstrap (if missing or previously auto-generated):
+
+```
+web-src/
+├── index.html
+└── src/
+    ├── index.js       ← imports ConfigurationManagementApp from the package
+    ├── exc-runtime.js
+    └── config.json    ← created empty; filled by aio app deploy
+```
+
+Custom `web-src` files are left untouched unless they were created by a prior install
+(files containing the `configuration-management: auto-generated bootstrap` marker, or
+an older bootstrap that imports `configuration-management/web`).
 
 - Run `npm install` from your App Builder project root (where `app.config.yaml` lives).
 - Do not use `npm install --ignore-scripts` (that skips postinstall).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configuration-management",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Schema-driven system configuration for Adobe Commerce App Builder sync apps. Magento-style scoped config in Adobe App Builder Database (ABDB) with encryption, Commerce REST helpers, and React Admin UI.",
   "license": "Apache-2.0",
   "author": "Adobe Inc.",
@@ -16,10 +16,12 @@
   ],
   "main": "./src/index.js",
   "bin": {
-    "configuration-management-setup": "./scripts/setup-app-config.js"
+    "configuration-management-setup": "./scripts/setup.js"
   },
   "scripts": {
-    "postinstall": "node ./scripts/setup-app-config.js"
+    "build": "node ./scripts/build-web.js",
+    "prepublishOnly": "node ./scripts/build-web.js",
+    "postinstall": "node ./scripts/build-web.js && node ./scripts/setup.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -28,8 +30,8 @@
     "./crypto": "./src/system-config-crypto.js",
     "./shared": "./src/system-config-shared.js",
     "./oauth1a": "./src/oauth1a.js",
-    "./web": "./web/index.js",
-    "./web/index.js": "./web/index.js",
+    "./web": "./web/dist/index.js",
+    "./web/index.js": "./web/dist/index.js",
     "./web/styles.css": "./web/src/styles/index.css",
     "./web/src/styles/index.css": "./web/src/styles/index.css",
     "./actions/utils": "./actions/utils.js",
@@ -61,6 +63,7 @@
     "react-router-dom": "^6.8.1"
   },
   "dependencies": {
+    "esbuild": "^0.25.12",
     "got": "^11.8.5",
     "oauth-1.0a": "^2.2.6"
   },

package/scripts/build-web.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const fs = require('fs')
+const path = require('path')
+
+async function main () {
+  let esbuild
+  try {
+    esbuild = require('esbuild')
+  } catch {
+    console.error('[configuration-management] esbuild is required to build the web UI. Run npm install in the package directory.')
+    process.exit(1)
+  }
+
+  const pkgRoot = path.join(__dirname, '..')
+  const entry = path.join(pkgRoot, 'web/src/index.js')
+  const outdir = path.join(pkgRoot, 'web/dist')
+  const outfile = path.join(outdir, 'index.js')
+
+  fs.mkdirSync(outdir, { recursive: true })
+
+  await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    outfile,
+    packages: 'external',
+    jsx: 'automatic',
+    loader: { '.js': 'jsx' },
+    target: ['chrome79', 'firefox85', 'safari13'],
+    logLevel: 'info'
+  })
+
+  console.log('[configuration-management] built web/dist/index.js')
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('[configuration-management] build-web failed:', err.message)
+    process.exit(1)
+  })
+}
+
+module.exports = { main }

package/scripts/setup.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const fs = require('fs')
+const path = require('path')
+
+const EXTENSION_POINT = 'commerce/backend-ui/1'
+const INCLUDE_REL = 'node_modules/configuration-management/actions/configurations/ext.config.yaml'
+const MARKER = '# configuration-management (auto-linked on npm install)'
+const WEB_BOOTSTRAP_MARKER = 'configuration-management: auto-generated bootstrap'
+
+const TEMPLATES_DIR = path.join(__dirname, 'templates')
+
+function escapeRe (str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function findProjectRoot (startDir) {
+  let dir = startDir
+  while (dir && dir !== path.dirname(dir)) {
+    if (
+      fs.existsSync(path.join(dir, 'app.config.yaml')) ||
+      fs.existsSync(path.join(dir, 'web-src'))
+    ) {
+      return dir
+    }
+    dir = path.dirname(dir)
+  }
+  return null
+}
+
+function resolveProjectRoot () {
+  const initCwd = process.env.INIT_CWD
+  if (initCwd) {
+    const fromInit = findProjectRoot(initCwd)
+    if (fromInit) return fromInit
+  }
+  return findProjectRoot(process.cwd())
+}
+
+function readTemplate (name) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8')
+}
+
+function writeIfMissingOrManaged (filePath, content, marker) {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8')
+    if (existing.includes(marker)) {
+      const dir = path.dirname(filePath)
+      fs.mkdirSync(dir, { recursive: true })
+      const changed = existing !== content
+      if (changed) {
+        fs.writeFileSync(filePath, content, 'utf8')
+      }
+      return { changed, reason: changed ? 'updated-managed' : 'unchanged-managed', path: filePath }
+    }
+    return { changed: false, reason: 'skipped-custom-file', path: filePath }
+  }
+  const dir = path.dirname(filePath)
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf8')
+  return { changed: true, reason: 'written', path: filePath }
+}
+
+function writeWebSrcIndex (projectRoot) {
+  const filePath = path.join(projectRoot, 'web-src', 'src', 'index.js')
+  const content = readTemplate('web-src-index.js')
+
+  if (!fs.existsSync(filePath)) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, content, 'utf8')
+    return { changed: true, reason: 'written', path: filePath }
+  }
+
+  const existing = fs.readFileSync(filePath, 'utf8')
+  if (existing.includes(WEB_BOOTSTRAP_MARKER)) {
+    const changed = existing !== content
+    if (changed) {
+      fs.writeFileSync(filePath, content, 'utf8')
+    }
+    return { changed, reason: changed ? 'updated-managed' : 'unchanged-managed', path: filePath }
+  }
+
+  if (existing.includes('configuration-management/web')) {
+    fs.writeFileSync(filePath, content, 'utf8')
+    return { changed: true, reason: 'migrated-stale-bootstrap', path: filePath }
+  }
+
+  return { changed: false, reason: 'skipped-custom-file', path: filePath }
+}
+
+function alreadyLinked (content) {
+  return content.includes('configuration-management/actions/configurations/ext.config.yaml')
+}
+
+function hasExtensionPoint (content) {
+  return /^[ \t]*commerce\/backend-ui\/1:/m.test(content)
+}
+
+function buildExtensionBlock () {
+  return [
+    MARKER,
+    'extensions:',
+    `  ${EXTENSION_POINT}:`,
+    `    $include: ${INCLUDE_REL}`
+  ].join('\n')
+}
+
+function updateExistingExtensionBlock (content) {
+  const match = content.match(/^([ \t]*)commerce\/backend-ui\/1:/m)
+  if (!match) return null
+
+  const indent = match[1]
+  const includeIndent = `${indent}  `
+  const blockRe = new RegExp(
+    `^${escapeRe(indent)}commerce/backend-ui/1:[ \\t]*\\n` +
+      `(?:${escapeRe(includeIndent)}\\$include:[^\\n]*\\n)?`,
+    'm'
+  )
+  const replacement =
+    `${indent}${EXTENSION_POINT}:\n${includeIndent}$include: ${INCLUDE_REL}\n`
+  const next = content.replace(blockRe, replacement)
+  return next !== content ? next : null
+}
+
+function patchAppConfig (content) {
+  if (alreadyLinked(content)) {
+    return { content, changed: false, reason: 'already-linked' }
+  }
+
+  if (hasExtensionPoint(content)) {
+    const updated = updateExistingExtensionBlock(content)
+    if (updated) {
+      return { content: updated, changed: true, reason: 'updated-existing-extension' }
+    }
+    return { content, changed: false, reason: 'extension-exists-unmodified' }
+  }
+
+  if (/^extensions:[ \t]*\n/m.test(content)) {
+    const injection = `  ${EXTENSION_POINT}:\n    $include: ${INCLUDE_REL}\n`
+    const next = content.replace(/^extensions:[ \t]*\n/m, `extensions:\n${injection}`)
+    if (next !== content) {
+      return { content: next, changed: true, reason: 'added-under-extensions' }
+    }
+  }
+
+  if (!/^extensions:/m.test(content)) {
+    const trimmed = content.replace(/\s+$/, '')
+    const separator = trimmed.length > 0 ? '\n\n' : ''
+    return {
+      content: `${trimmed}${separator}${buildExtensionBlock()}\n`,
+      changed: true,
+      reason: 'appended'
+    }
+  }
+
+  return { content, changed: false, reason: 'no-change' }
+}
+
+function setupAppConfig (projectRoot) {
+  const appConfigPath = path.join(projectRoot, 'app.config.yaml')
+  if (!fs.existsSync(appConfigPath)) {
+    return { changed: false, reason: 'no-app-config' }
+  }
+
+  const original = fs.readFileSync(appConfigPath, 'utf8')
+  const { content, changed, reason } = patchAppConfig(original)
+  if (!changed) {
+    return { changed: false, reason }
+  }
+
+  fs.writeFileSync(appConfigPath, content, 'utf8')
+  return { changed: true, reason, detail: INCLUDE_REL }
+}
+
+function setupWebSrc (projectRoot) {
+  const webSrcDir = path.join(projectRoot, 'web-src')
+  const results = []
+
+  const indexJs = writeWebSrcIndex(projectRoot)
+  results.push(indexJs)
+
+  const indexHtml = writeIfMissingOrManaged(
+    path.join(webSrcDir, 'index.html'),
+    readTemplate('web-src-index.html'),
+    'configuration-management'
+  )
+  results.push(indexHtml)
+
+  const excRuntime = writeIfMissingOrManaged(
+    path.join(webSrcDir, 'src', 'exc-runtime.js'),
+    readTemplate('exc-runtime.js'),
+    'Module Runtime: Needs to be within an iframe'
+  )
+  results.push(excRuntime)
+
+  const configPath = path.join(webSrcDir, 'src', 'config.json')
+  if (!fs.existsSync(configPath)) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true })
+    fs.writeFileSync(configPath, '{}\n', 'utf8')
+    results.push({ changed: true, reason: 'created-config-json', path: configPath })
+  }
+
+  const changed = results.some((r) => r.changed)
+  return { changed, results }
+}
+
+function main () {
+  if (process.env.CONFIGURATION_MANAGEMENT_SKIP_SETUP === '1') {
+    return
+  }
+
+  const projectRoot = resolveProjectRoot()
+  if (!projectRoot) {
+    console.log(
+      '[configuration-management] No App Builder project found — skip setup. ' +
+        'Run `npx configuration-management-setup` from your project root after `aio app init`.'
+    )
+    return
+  }
+
+  const app = setupAppConfig(projectRoot)
+  if (app.changed) {
+    console.log(
+      `[configuration-management] Updated app.config.yaml (${app.reason}):\n` +
+        `  $include: ${app.detail}`
+    )
+  }
+
+  const web = setupWebSrc(projectRoot)
+  for (const r of web.results || []) {
+    if (r.changed) {
+      console.log(`[configuration-management] Wrote ${r.path}`)
+    }
+  }
+
+  if (!app.changed && !web.changed) {
+    console.log('[configuration-management] Project already configured.')
+  }
+}
+
+if (require.main === module) {
+  try {
+    main()
+  } catch (err) {
+    console.error('[configuration-management] setup failed:', err.message)
+    process.exitCode = 1
+  }
+}
+
+module.exports = {
+  patchAppConfig,
+  setupAppConfig,
+  setupWebSrc,
+  INCLUDE_REL,
+  EXTENSION_POINT
+}

package/scripts/templates/exc-runtime.js

@@ -0,0 +1,14 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you 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 REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/* eslint-disable-next-line */
+(function(e,t){if(t.location===t.parent.location)throw new Error("Module Runtime: Needs to be within an iframe!");var o=function(e){var t=new URL(e.location.href).searchParams.get("_mr");return t||!e.EXC_US_HMR?t:e.sessionStorage.getItem("unifiedShellMRScript")}(t);if(!o)throw new Error("Module Runtime: Missing script!");if("https:"!==(o=new URL(decodeURIComponent(o))).protocol)throw new Error("Module Runtime: Must be HTTPS!");if(!/^(exc-unifiedcontent\.)?experience(-qa|-stage|-cdn|-cdn-stage)?\.adobe\.(com|net)$/.test(o.hostname)&&!/localhost\.corp\.adobe\.com$/.test(o.hostname))throw new Error("Module Runtime: Invalid domain!");if(!/\.js$/.test(o.pathname))throw new Error("Module Runtime: Must be a JavaScript file!");t.EXC_US_HMR&&t.sessionStorage.setItem("unifiedShellMRScript",o.toString());var n=e.createElement("script");n.async=1,n.src=o.toString(),n.onload=n.onreadystatechange=function(){n.readyState&&!/loaded|complete/.test(n.readyState)||(n.onload=n.onreadystatechange=null,n=void 0,"EXC_MR_READY"in t&&t.EXC_MR_READY())},e.head.appendChild(n)})(document,window);

package/scripts/templates/web-src-index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no">
+  <meta name="theme-color" content="#1473e6">
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <link rel="icon" type="image/svg+xml" href="./favicon.svg">
+  <title>Sync Management</title>
+</head>
+<body>
+<noscript>You need to enable JavaScript to run this app.</noscript>
+<div id="root"></div>
+<script src="./src/index.js" async="true" type="module"></script>
+</body>
+</html>

package/scripts/templates/web-src-index.js

@@ -0,0 +1,61 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you 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
+*/
+// configuration-management: auto-generated bootstrap (updated on npm install)
+
+import 'core-js/stable'
+import 'regenerator-runtime/runtime'
+
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+
+import Runtime, { init } from '@adobe/exc-app'
+import { ConfigurationManagementApp as App, configureWeb } from 'configuration-management/web'
+import actions from './config.json'
+import 'configuration-management/web/styles.css'
+
+configureWeb({ actionUrls: actions })
+
+window.React = React
+
+try {
+  require('./exc-runtime')
+  init(bootstrapInExcShell)
+} catch (e) {
+  console.log('application not running in Adobe Experience Cloud Shell')
+  bootstrapRaw()
+}
+
+function renderApp (runtime, ims) {
+  createRoot(document.getElementById('root')).render(
+    React.createElement(App, { runtime, ims })
+  )
+}
+
+function bootstrapRaw () {
+  renderApp({ on: () => {} }, {})
+}
+
+function bootstrapInExcShell () {
+  const runtime = Runtime()
+  runtime.favicon = './favicon.svg'
+
+  runtime.on('ready', ({ imsOrg, imsToken, imsProfile }) => {
+    runtime.done()
+    renderApp(runtime, {
+      profile: imsProfile,
+      org: imsOrg,
+      token: imsToken
+    })
+  })
+
+  runtime.solution = {
+    icon: 'AdobeExperienceCloud',
+    title: 'Sync Management',
+    shortTitle: 'Sync'
+  }
+  runtime.title = 'Sync Management'
+}