@adobedjangir/commerce-admin-snapshots 0.1.0

package/actions/ext.config.yaml

@@ -0,0 +1,50 @@
+# Action fragment for the snapshots add-on. $included by app.config.yaml
+# under application.runtimeManifest.packages.Snapshots.
+license: Apache-2.0
+actions:
+  system-config-snapshot-create:
+    function: system-config-snapshot-create/index.js
+    web: 'yes'
+    runtime: 'nodejs:20'
+    inputs:
+      LOG_LEVEL: debug
+      OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
+      OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
+      OAUTH_ORG_ID: $OAUTH_ORG_ID
+      OAUTH_SCOPES: $OAUTH_SCOPES
+      AIO_DB_REGION: $AIO_DB_REGION
+    annotations:
+      require-adobe-auth: false
+      include-ims-credentials: true
+      final: true
+  system-config-snapshot-list:
+    function: system-config-snapshot-list/index.js
+    web: 'yes'
+    runtime: 'nodejs:20'
+    inputs:
+      LOG_LEVEL: debug
+      OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
+      OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
+      OAUTH_ORG_ID: $OAUTH_ORG_ID
+      OAUTH_SCOPES: $OAUTH_SCOPES
+      AIO_DB_REGION: $AIO_DB_REGION
+    annotations:
+      require-adobe-auth: false
+      include-ims-credentials: true
+      final: true
+  system-config-snapshot-restore:
+    function: system-config-snapshot-restore/index.js
+    web: 'yes'
+    runtime: 'nodejs:20'
+    inputs:
+      LOG_LEVEL: debug
+      SYSTEM_CONFIG_CRYPT_KEY: $SYSTEM_CONFIG_CRYPT_KEY
+      OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
+      OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
+      OAUTH_ORG_ID: $OAUTH_ORG_ID
+      OAUTH_SCOPES: $OAUTH_SCOPES
+      AIO_DB_REGION: $AIO_DB_REGION
+    annotations:
+      require-adobe-auth: false
+      include-ims-credentials: true
+      final: true

package/actions/system-config-snapshot-create/index.js

@@ -0,0 +1,108 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+// Capture a point-in-time snapshot of system_config_data into the
+// system_config_snapshots collection. The snapshot is a single document
+// that contains the entire schema + all value rows, so restore is a clean
+// replay (no merge logic). Sensitive values stay encrypted on the way in.
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse } = require('@adobedjangir/commerce-admin-management/actions/utils')
+const { getClient } = require('@adobedjangir/commerce-admin-management/abdb')
+
+const DATA_COLLECTION = 'system_config_data'
+const SCHEMA_COLLECTION = 'system_config_schema'
+const SCHEMA_DOC_ID = 'v1'
+const SNAPSHOT_COLLECTION = 'system_config_snapshots'
+const SNAPSHOT_MAX = 100
+
+async function ensureCollection (client, name) {
+  try { await client.createCollection(name) } catch (err) {
+    const msg = (err && err.message) ? String(err.message) : String(err)
+    if (!/exist|already|duplicate/i.test(msg)) throw err
+  }
+}
+
+async function tryFindOne (col, query) {
+  try {
+    const arr = await col.find(query).limit(1).toArray()
+    return arr && arr.length ? arr[0] : null
+  } catch (err) {
+    const msg = err && err.message ? String(err.message) : String(err)
+    if (/not found/i.test(msg)) return null
+    throw err
+  }
+}
+
+async function main (params) {
+  const logger = Core.Logger('system-config-snapshot-create', { level: params.LOG_LEVEL || 'info' })
+  const label = (params.label && String(params.label).trim()) || `Snapshot ${new Date().toISOString()}`
+  const createdBy = (params.actor && String(params.actor)) ||
+    (params.__ow_headers && (params.__ow_headers['x-gw-ims-org-id'] || params.__ow_headers['x-ims-org-id'])) ||
+    'system'
+
+  let handle
+  try {
+    handle = await getClient(params)
+  } catch (e) {
+    return errorResponse(500, `ABDB connect failed: ${e.message}`, logger)
+  }
+  const { client, close } = handle
+
+  try {
+    await ensureCollection(client, SNAPSHOT_COLLECTION)
+    const dataCol = await client.collection(DATA_COLLECTION)
+    const schemaCol = await client.collection(SCHEMA_COLLECTION)
+    const snapCol = await client.collection(SNAPSHOT_COLLECTION)
+
+    const [valueDocs, schemaDoc] = await Promise.all([
+      dataCol.find({}).toArray().catch(() => []),
+      tryFindOne(schemaCol, { _id: SCHEMA_DOC_ID })
+    ])
+
+    const now = new Date().toISOString()
+    const snapshot = {
+      _id: `snap_${now.replace(/[:.]/g, '-')}_${Math.random().toString(36).slice(2, 8)}`,
+      createdAt: now,
+      createdBy,
+      label,
+      schema: schemaDoc && schemaDoc.schema ? schemaDoc.schema : null,
+      values: valueDocs.map((d) => ({
+        scope: d.scope,
+        scope_id: d.scope_id,
+        path: d.path,
+        value: d.value
+      })),
+      counts: {
+        values: valueDocs.length,
+        sections: schemaDoc && schemaDoc.schema ? (schemaDoc.schema.sections || []).length : 0
+      }
+    }
+    await snapCol.insertOne(snapshot)
+
+    // Compact older snapshots — keep only the most recent SNAPSHOT_MAX.
+    try {
+      const total = await snapCol.countDocuments({})
+      if (total > SNAPSHOT_MAX) {
+        const over = total - SNAPSHOT_MAX
+        const oldest = await snapCol.find({}).sort({ createdAt: 1 }).limit(over).toArray()
+        for (const o of oldest) await snapCol.deleteOne({ _id: o._id })
+      }
+    } catch (_) { /* compaction best-effort */ }
+
+    logger.info(`Snapshot ${snapshot._id} created (${snapshot.counts.values} values)`)
+    return {
+      statusCode: 200,
+      body: { ok: true, snapshot: { _id: snapshot._id, label, createdAt: now, createdBy, counts: snapshot.counts } }
+    }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'snapshot create failed', logger)
+  } finally {
+    try { await close() } catch (_) {}
+  }
+}
+
+exports.main = main

package/actions/system-config-snapshot-list/index.js

@@ -0,0 +1,47 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+// Paginated list of snapshots. Returns metadata only (label/createdAt/counts) —
+// the full value array is omitted so the UI list stays light. The restore
+// action loads the full doc on demand.
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse } = require('@adobedjangir/commerce-admin-management/actions/utils')
+const { getClient } = require('@adobedjangir/commerce-admin-management/abdb')
+
+const SNAPSHOT_COLLECTION = 'system_config_snapshots'
+
+async function main (params) {
+  const logger = Core.Logger('system-config-snapshot-list', { level: params.LOG_LEVEL || 'info' })
+  const limit = Math.min(Math.max(parseInt(params.limit, 10) || 50, 1), 500)
+  const skip = Math.max(parseInt(params.skip, 10) || 0, 0)
+
+  let handle
+  try { handle = await getClient(params) } catch (e) {
+    return errorResponse(500, `ABDB connect failed: ${e.message}`, logger)
+  }
+  const { client, close } = handle
+
+  try {
+    const col = await client.collection(SNAPSHOT_COLLECTION)
+    const docs = await col.find({}).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray().catch(() => [])
+    // Strip large payloads from the list response.
+    const items = docs.map((d) => ({
+      _id: d._id,
+      label: d.label,
+      createdAt: d.createdAt,
+      createdBy: d.createdBy,
+      counts: d.counts
+    }))
+    return { statusCode: 200, body: { ok: true, items, limit, skip, returned: items.length } }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'snapshot list failed', logger)
+  } finally {
+    try { await close() } catch (_) {}
+  }
+}
+
+exports.main = main

package/actions/system-config-snapshot-restore/index.js

@@ -0,0 +1,154 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+// Restore the entire system_config_data collection from a snapshot.
+// Strategy: write a snapshot of the CURRENT state first (so the restore
+// itself is auditable + reversible), then wipe + repopulate.
+//
+// Sensitive values in the snapshot are stored as ciphertext (we never
+// decrypt at snapshot time), so restore replays them verbatim — they
+// remain readable as long as SYSTEM_CONFIG_CRYPT_KEY hasn't changed
+// between snapshot and restore.
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse, checkMissingRequestInputs } = require('@adobedjangir/commerce-admin-management/actions/utils')
+const { getClient } = require('@adobedjangir/commerce-admin-management/abdb')
+const { toStateKey } = require('@adobedjangir/commerce-admin-management/shared')
+
+const DATA_COLLECTION = 'system_config_data'
+const SCHEMA_COLLECTION = 'system_config_schema'
+const SCHEMA_DOC_ID = 'v1'
+const SNAPSHOT_COLLECTION = 'system_config_snapshots'
+const AUDIT_COLLECTION = 'system_config_audit'
+
+async function ensureCollection (client, name) {
+  try { await client.createCollection(name) } catch (err) {
+    const msg = (err && err.message) ? String(err.message) : String(err)
+    if (!/exist|already|duplicate/i.test(msg)) throw err
+  }
+}
+
+async function main (params) {
+  const logger = Core.Logger('system-config-snapshot-restore', { level: params.LOG_LEVEL || 'info' })
+  const missing = checkMissingRequestInputs(params, ['snapshotId'], [])
+  if (missing) return errorResponse(400, missing, logger)
+  const snapshotId = String(params.snapshotId)
+  const actor = (params.actor && String(params.actor)) || 'system'
+  const restoreSchema = params.restoreSchema !== false && params.restoreSchema !== 'false'
+
+  let handle
+  try { handle = await getClient(params) } catch (e) {
+    return errorResponse(500, `ABDB connect failed: ${e.message}`, logger)
+  }
+  const { client, close } = handle
+
+  try {
+    const snapCol = await client.collection(SNAPSHOT_COLLECTION)
+    const snap = await (async () => {
+      try { return await snapCol.findOne({ _id: snapshotId }) }
+      catch { return null }
+    })()
+    if (!snap) return errorResponse(404, `Snapshot ${snapshotId} not found`, logger)
+
+    // 1) Capture a "pre-restore" snapshot of the current state so this op is
+    //    reversible. Inline rather than reusing the create action.
+    const dataCol = await client.collection(DATA_COLLECTION)
+    const schemaCol = await client.collection(SCHEMA_COLLECTION)
+    const now = new Date().toISOString()
+    const currentValues = await dataCol.find({}).toArray().catch(() => [])
+    const currentSchemaDoc = await (async () => {
+      try { return await schemaCol.findOne({ _id: SCHEMA_DOC_ID }) }
+      catch { return null }
+    })()
+    const preRestoreSnap = {
+      _id: `snap_${now.replace(/[:.]/g, '-')}_pre-restore`,
+      createdAt: now,
+      createdBy: actor,
+      label: `Auto: pre-restore of ${snap.label || snapshotId}`,
+      schema: currentSchemaDoc && currentSchemaDoc.schema ? currentSchemaDoc.schema : null,
+      values: currentValues.map((d) => ({ scope: d.scope, scope_id: d.scope_id, path: d.path, value: d.value })),
+      counts: {
+        values: currentValues.length,
+        sections: currentSchemaDoc && currentSchemaDoc.schema ? (currentSchemaDoc.schema.sections || []).length : 0
+      }
+    }
+    try { await snapCol.insertOne(preRestoreSnap) } catch (e) {
+      logger.warn(`pre-restore snapshot failed (continuing): ${e.message}`)
+    }
+
+    // 2) Replace schema if the snapshot has one and the caller wants it.
+    if (restoreSchema && snap.schema) {
+      try {
+        await schemaCol.updateOne(
+          { _id: SCHEMA_DOC_ID },
+          { $set: { schema: snap.schema, updatedAt: now }, $setOnInsert: { _id: SCHEMA_DOC_ID, createdAt: now } },
+          { upsert: true }
+        )
+      } catch (e) {
+        // Fallback for drivers without upsert.
+        if (currentSchemaDoc) await schemaCol.updateOne({ _id: SCHEMA_DOC_ID }, { $set: { schema: snap.schema, updatedAt: now } })
+        else await schemaCol.insertOne({ _id: SCHEMA_DOC_ID, schema: snap.schema, createdAt: now, updatedAt: now })
+      }
+    }
+
+    // 3) Wipe data collection then bulk-insert the snapshot's values.
+    for (const d of currentValues) {
+      await dataCol.deleteOne({ _id: d._id })
+    }
+    let inserted = 0
+    for (const v of (snap.values || [])) {
+      try {
+        const id = toStateKey(v.scope, v.scope_id, v.path)
+        await dataCol.insertOne({
+          _id: id,
+          scope: v.scope,
+          scope_id: v.scope_id,
+          path: v.path,
+          value: v.value,
+          createdAt: now,
+          updatedAt: now
+        })
+        inserted++
+      } catch (e) {
+        logger.warn(`failed to restore ${v.path} at ${v.scope}:${v.scope_id}: ${e.message}`)
+      }
+    }
+
+    // 4) Audit row for the restore action — a single high-level entry.
+    try {
+      await ensureCollection(client, AUDIT_COLLECTION)
+      const auditCol = await client.collection(AUDIT_COLLECTION)
+      await auditCol.insertOne({
+        scope: 'default',
+        scope_id: '0',
+        path: '_system/snapshot/restore',
+        action: 'update',
+        oldValue: `pre:${preRestoreSnap._id}`,
+        newValue: `from:${snapshotId}`,
+        changedBy: actor,
+        changedAt: now
+      })
+    } catch (_) {}
+
+    logger.info(`Restored snapshot ${snapshotId}: deleted ${currentValues.length}, inserted ${inserted}`)
+    return {
+      statusCode: 200,
+      body: {
+        ok: true,
+        restoredFrom: snapshotId,
+        preRestoreSnapshot: preRestoreSnap._id,
+        deleted: currentValues.length,
+        inserted
+      }
+    }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'snapshot restore failed', logger)
+  } finally {
+    try { await close() } catch (_) {}
+  }
+}
+
+exports.main = main

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@adobedjangir/commerce-admin-snapshots",
+  "version": "0.1.0",
+  "description": "Snapshot + rollback add-on for @adobedjangir/commerce-admin-management. Capture point-in-time copies of schema + values, restore wholesale (auto pre-restore backup included).",
+  "license": "Apache-2.0",
+  "author": "Adobe Inc.",
+  "keywords": ["adobe-io", "aio", "app-builder", "commerce-admin", "snapshot", "rollback"],
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./web": "./web/index.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/setup.js"
+  },
+  "files": ["src", "actions", "web", "scripts", "README.md"],
+  "engines": { "node": ">=18" },
+  "peerDependencies": {
+    "@adobedjangir/commerce-admin-management": ">=0.3.0",
+    "@adobedjangir/commerce-admin-get-config": ">=0.0.7"
+  }
+}

package/scripts/setup.js

@@ -0,0 +1,168 @@
+#!/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')
+
+// ── Per-add-on configuration ──
+const PACKAGE_NAME = '@adobedjangir/commerce-admin-snapshots'
+const RUNTIME_KEY  = 'Snapshots'
+const INCLUDE_REL  = 'node_modules/@adobedjangir/commerce-admin-snapshots/actions/ext.config.yaml'
+const REGISTER_IMPORT = "import registerSnapshots from '@adobedjangir/commerce-admin-snapshots/web'"
+const REGISTER_CALL   = 'registerSnapshots()'
+const MARKER = `# ${PACKAGE_NAME} (auto-linked on npm install)`
+
+// ── Boilerplate (identical across add-ons; small enough to inline) ──
+function findProjectRoot (startDir) {
+  let dir = startDir
+  while (dir && dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'app.config.yaml'))) return dir
+    dir = path.dirname(dir)
+  }
+  return null
+}
+function resolveProjectRoot () {
+  return (process.env.INIT_CWD && findProjectRoot(process.env.INIT_CWD)) ||
+         findProjectRoot(process.cwd())
+}
+
+/**
+ * Add (or replace) an `application.runtimeManifest.packages.<RUNTIME_KEY>`
+ * block that $includes our fragment. Idempotent.
+ */
+function patchAppConfig (content) {
+  // Look for our own marker to detect prior installs.
+  const blockRe = new RegExp(
+    String.raw`^[ \t]*${MARKER}\n([ \t]+${RUNTIME_KEY}:[ \t]*\n[ \t]+\$include:[^\n]*\n)`, 'm'
+  )
+  const desiredBody = `      ${MARKER}\n      ${RUNTIME_KEY}:\n        $include: ${INCLUDE_REL}\n`
+
+  if (blockRe.test(content)) {
+    // Already linked — leave it.
+    return { content, changed: false, reason: 'already-linked' }
+  }
+
+  // 1. application.runtimeManifest.packages exists → append our subkey.
+  if (/^application:[ \t]*\n([ \t]+[^\n]*\n)*[ \t]+runtimeManifest:[ \t]*\n([ \t]+[^\n]*\n)*[ \t]+packages:[ \t]*\n/m.test(content)) {
+    const next = content.replace(
+      /([ \t]+packages:[ \t]*\n)/m,
+      (m) => m + desiredBody
+    )
+    return { content: next, changed: next !== content, reason: 'appended-under-packages' }
+  }
+
+  // 2. application.runtimeManifest exists but no `packages:` → add one.
+  if (/^application:[ \t]*\n([ \t]+[^\n]*\n)*[ \t]+runtimeManifest:[ \t]*\n/m.test(content)) {
+    const next = content.replace(
+      /([ \t]+runtimeManifest:[ \t]*\n)/m,
+      (m) => m + `    packages:\n${desiredBody}`
+    )
+    return { content: next, changed: next !== content, reason: 'added-packages' }
+  }
+
+  // 3. application: exists but no runtimeManifest → add the whole tree.
+  if (/^application:[ \t]*\n/m.test(content)) {
+    const next = content.replace(
+      /^application:[ \t]*\n/m,
+      `application:\n  runtimeManifest:\n    packages:\n${desiredBody}`
+    )
+    return { content: next, changed: next !== content, reason: 'added-runtimeManifest' }
+  }
+
+  // 4. No application: → append the whole block.
+  const trimmed = content.replace(/\s+$/, '')
+  const sep = trimmed ? '\n\n' : ''
+  return {
+    content: `${trimmed}${sep}application:\n  runtimeManifest:\n    packages:\n${desiredBody}`,
+    changed: true,
+    reason: 'appended-application'
+  }
+}
+
+/**
+ * Patch the host's web-src/src/index.js to import + call our register fn.
+ * We look for a managed `// --- COMMERCE-ADMIN ADDONS ---` block; if it's
+ * absent we add one. Idempotent — the registration line is only added once.
+ */
+function patchBootstrap (content) {
+  const blockStart = '// --- COMMERCE-ADMIN ADDONS (auto-managed) ---'
+  const blockEnd   = '// --- COMMERCE-ADMIN ADDONS END ---'
+  // Already registered?
+  if (content.includes(REGISTER_IMPORT) && content.includes(REGISTER_CALL)) {
+    return { content, changed: false, reason: 'already-registered' }
+  }
+
+  // Find or create the managed block.
+  if (content.includes(blockStart)) {
+    // Insert our import + call inside the block.
+    const next = content.replace(
+      blockStart + '\n',
+      blockStart + '\n' + REGISTER_IMPORT + '\n' + REGISTER_CALL + '\n'
+    )
+    return { content: next, changed: true, reason: 'inserted-into-existing-block' }
+  }
+
+  // No block yet — append one after `configureWeb({...})` call.
+  const cwRe = /configureWeb\s*\([^)]*\)\s*\n/
+  if (cwRe.test(content)) {
+    const next = content.replace(
+      cwRe,
+      (m) => m + '\n' + blockStart + '\n' + REGISTER_IMPORT + '\n' + REGISTER_CALL + '\n' + blockEnd + '\n'
+    )
+    return { content: next, changed: true, reason: 'created-block-after-configureWeb' }
+  }
+
+  // No configureWeb? Append at end as a best effort.
+  return {
+    content: content + '\n' + blockStart + '\n' + REGISTER_IMPORT + '\n' + REGISTER_CALL + '\n' + blockEnd + '\n',
+    changed: true,
+    reason: 'appended-block-at-end'
+  }
+}
+
+function main () {
+  if (process.env.CONFIGURATION_MANAGEMENT_SKIP_SETUP === '1') return
+  const root = resolveProjectRoot()
+  if (!root) {
+    console.log(`[${PACKAGE_NAME}] No app.config.yaml found — skip setup.`)
+    return
+  }
+
+  // 1. app.config.yaml
+  const cfg = path.join(root, 'app.config.yaml')
+  if (fs.existsSync(cfg)) {
+    const before = fs.readFileSync(cfg, 'utf8')
+    const { content, changed, reason } = patchAppConfig(before)
+    if (changed) {
+      fs.writeFileSync(cfg, content, 'utf8')
+      console.log(`[${PACKAGE_NAME}] app.config.yaml: ${reason}`)
+    } else {
+      console.log(`[${PACKAGE_NAME}] app.config.yaml: ${reason}`)
+    }
+  }
+
+  // 2. bootstrap (web-src/src/index.js)
+  const boot = path.join(root, 'web-src', 'src', 'index.js')
+  if (fs.existsSync(boot)) {
+    const before = fs.readFileSync(boot, 'utf8')
+    const { content, changed, reason } = patchBootstrap(before)
+    if (changed) {
+      fs.writeFileSync(boot, content, 'utf8')
+      console.log(`[${PACKAGE_NAME}] web-src/src/index.js: ${reason}`)
+    } else {
+      console.log(`[${PACKAGE_NAME}] web-src/src/index.js: ${reason}`)
+    }
+  }
+}
+
+if (require.main === module) {
+  try { main() } catch (err) {
+    // Never fail npm install on scaffold issues.
+    console.error(`[${PACKAGE_NAME}] setup error (install continues):`, err.message)
+  }
+}
+
+module.exports = { patchAppConfig, patchBootstrap }

package/src/index.js

@@ -0,0 +1,12 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+// Snapshots add-on has no server-side hooks back into core today — the
+// snapshot actions are self-contained. This file is the package's entry
+// point for completeness; consumers don't normally need to import from it.
+
+module.exports = {
+  SNAPSHOT_COLLECTION: 'system_config_snapshots'
+}

package/web/index.js

@@ -0,0 +1,26 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+import { configureWeb } from '@adobedjangir/commerce-admin-management/web'
+import SnapshotHistory from './src/SnapshotHistory'
+
+export default function registerSnapshots () {
+  configureWeb({
+    actionKeys: {
+      systemConfigSnapshotCreate:  'Snapshots/system-config-snapshot-create',
+      systemConfigSnapshotList:    'Snapshots/system-config-snapshot-list',
+      systemConfigSnapshotRestore: 'Snapshots/system-config-snapshot-restore'
+    },
+    extraNav: [{
+      id: 'snapshots',
+      path: '/snapshots',
+      label: 'Snapshots',
+      icon: 'Box'
+    }],
+    extraPages: { snapshots: SnapshotHistory }
+  })
+}
+
+export { default as SnapshotHistory } from './src/SnapshotHistory'

package/web/src/SnapshotHistory.js

@@ -0,0 +1,228 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+// Snapshot history viewer + restore UI. Snapshots are written by either:
+//   - the create action (user clicks "Save snapshot now")
+//   - the restore action (an auto pre-restore snapshot is taken first)
+
+import React, { useCallback, useEffect, useState } from 'react'
+import {
+  View, Flex, Heading, Text, Button, TextField, ProgressCircle,
+  StatusLight, Well, DialogTrigger, Dialog, Content, Header, ButtonGroup,
+  Divider, Switch
+} from '@adobe/react-spectrum'
+import { callAction, resolveActor } from '@adobedjangir/commerce-admin-management/web'
+import { getActionKey } from '@adobedjangir/commerce-admin-management/web'
+import { PALETTE, RADIUS, SHADOW } from '@adobedjangir/commerce-admin-management/web'
+
+export default function SnapshotHistory ({ runtime, ims }) {
+  const [items, setItems] = useState([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [status, setStatus] = useState({ tone: 'neutral', message: '' })
+  const [newLabel, setNewLabel] = useState('')
+  const [creating, setCreating] = useState(false)
+  const [confirmRow, setConfirmRow] = useState(null)
+  const [restoreSchema, setRestoreSchema] = useState(true)
+  const [restoring, setRestoring] = useState(false)
+
+  const fetchList = useCallback(async () => {
+    setLoading(true); setError(null)
+    try {
+      const res = await callAction({ runtime, ims }, getActionKey('systemConfigSnapshotList'), '', { limit: 100 })
+      const body = res?.body || res
+      setItems(Array.isArray(body?.items) ? body.items : [])
+    } catch (e) {
+      setError(e.message || 'Failed to load snapshots')
+    } finally {
+      setLoading(false)
+    }
+  }, [runtime, ims])
+
+  useEffect(() => { fetchList() }, [fetchList])
+
+  const doCreate = async () => {
+    setCreating(true); setStatus({ tone: 'notice', message: 'Creating snapshot…' })
+    try {
+      const res = await callAction({ runtime, ims }, getActionKey('systemConfigSnapshotCreate'), '', {
+        label: newLabel.trim() || undefined,
+        actor: resolveActor(ims)
+      })
+      const body = res?.body || res
+      if (body?.ok) {
+        setStatus({ tone: 'positive', message: `Snapshot saved: ${body.snapshot.label}` })
+        setNewLabel('')
+        await fetchList()
+      } else {
+        setStatus({ tone: 'negative', message: body?.error || 'Snapshot failed' })
+      }
+    } catch (e) {
+      setStatus({ tone: 'negative', message: e.message || 'Snapshot failed' })
+    } finally {
+      setCreating(false)
+    }
+  }
+
+  const doRestore = async () => {
+    if (!confirmRow) return
+    setRestoring(true)
+    setStatus({ tone: 'notice', message: 'Restoring…' })
+    try {
+      const res = await callAction({ runtime, ims }, getActionKey('systemConfigSnapshotRestore'), '', {
+        snapshotId: confirmRow._id,
+        restoreSchema,
+        actor: resolveActor(ims)
+      })
+      const body = res?.body || res
+      if (body?.ok) {
+        setStatus({
+          tone: 'positive',
+          message: `Restored from ${confirmRow.label}. Pre-restore backup saved as ${body.preRestoreSnapshot}.`
+        })
+        await fetchList()
+      } else {
+        setStatus({ tone: 'negative', message: body?.error || 'Restore failed' })
+      }
+    } catch (e) {
+      setStatus({ tone: 'negative', message: e.message || 'Restore failed' })
+    } finally {
+      setRestoring(false)
+      setConfirmRow(null)
+    }
+  }
+
+  return (
+    <View padding="size-400" UNSAFE_style={{ background: PALETTE.bg, minHeight: '100vh' }}>
+      <Heading level={2} marginTop={0}>Snapshots</Heading>
+      <Text UNSAFE_style={{ color: PALETTE.textMuted }}>
+        Each snapshot captures the entire schema + every value row. Restore
+        replays a snapshot wholesale — the current state is automatically
+        backed up first so a restore is itself reversible.
+      </Text>
+
+      {status.message && (
+        <View marginTop="size-150"><StatusLight variant={status.tone}>{status.message}</StatusLight></View>
+      )}
+      {error && (
+        <Well marginTop="size-150" UNSAFE_style={{ borderColor: PALETTE.danger }}>
+          <Text UNSAFE_style={{ color: PALETTE.danger }}>{error}</Text>
+        </Well>
+      )}
+
+      <View
+        marginTop="size-200"
+        padding="size-200"
+        UNSAFE_style={{ background: PALETTE.surface, border: `1px solid ${PALETTE.border}`, borderRadius: RADIUS.lg, boxShadow: SHADOW.xs }}
+      >
+        <Flex gap="size-150" alignItems="end" wrap>
+          <TextField
+            label="Snapshot label (optional)"
+            value={newLabel}
+            onChange={setNewLabel}
+            width="size-4600"
+            placeholder="e.g. before-2026-Q2-release"
+          />
+          <Button variant="cta" onPress={doCreate} isDisabled={creating || loading}>
+            {creating ? 'Saving…' : 'Save snapshot now'}
+          </Button>
+          <Button variant="secondary" onPress={fetchList} isDisabled={loading}>
+            Reload
+          </Button>
+        </Flex>
+      </View>
+
+      <View
+        marginTop="size-200"
+        UNSAFE_style={{ background: PALETTE.surface, border: `1px solid ${PALETTE.border}`, borderRadius: RADIUS.lg, boxShadow: SHADOW.xs, overflow: 'hidden' }}
+      >
+        <div style={{
+          display: 'grid',
+          gridTemplateColumns: 'minmax(180px, 1fr) minmax(140px, 200px) minmax(160px, 220px) 110px 110px 120px',
+          padding: '12px 16px',
+          gap: 12,
+          background: PALETTE.surfaceMuted,
+          fontSize: 11,
+          fontWeight: 700,
+          letterSpacing: 0.6,
+          textTransform: 'uppercase',
+          color: PALETTE.textMuted,
+          borderBottom: `1px solid ${PALETTE.border}`
+        }}>
+          <div>Label</div>
+          <div>Created at</div>
+          <div>Created by</div>
+          <div>Values</div>
+          <div>Sections</div>
+          <div>Action</div>
+        </div>
+        {loading && items.length === 0 ? (
+          <Flex justifyContent="center" margin="size-400"><ProgressCircle aria-label="Loading" isIndeterminate /></Flex>
+        ) : items.length === 0 ? (
+          <View padding="size-400"><Text UNSAFE_style={{ color: PALETTE.textMuted }}>No snapshots yet.</Text></View>
+        ) : (
+          items.map((row, i) => (
+            <div
+              key={row._id}
+              style={{
+                display: 'grid',
+                gridTemplateColumns: 'minmax(180px, 1fr) minmax(140px, 200px) minmax(160px, 220px) 110px 110px 120px',
+                padding: '12px 16px',
+                gap: 12,
+                borderBottom: `1px solid ${PALETTE.border}`,
+                fontSize: 13,
+                background: i % 2 === 0 ? PALETTE.surface : PALETTE.surfaceSubtle,
+                alignItems: 'center'
+              }}
+            >
+              <div style={{ wordBreak: 'break-word' }}>
+                <div style={{ fontWeight: 600 }}>{row.label}</div>
+                <div style={{ color: PALETTE.textMuted, fontSize: 11, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace' }}>{row._id}</div>
+              </div>
+              <div style={{ color: PALETTE.textMuted, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 12 }}>
+                {row.createdAt ? new Date(row.createdAt).toLocaleString() : ''}
+              </div>
+              <div style={{ color: PALETTE.textMuted, wordBreak: 'break-word' }}>{row.createdBy || 'system'}</div>
+              <div>{row.counts?.values ?? '?'}</div>
+              <div>{row.counts?.sections ?? '?'}</div>
+              <div>
+                <Button variant="secondary" onPress={() => setConfirmRow(row)} isDisabled={restoring}>
+                  Restore
+                </Button>
+              </div>
+            </div>
+          ))
+        )}
+      </View>
+
+      <DialogTrigger isOpen={!!confirmRow} onOpenChange={(o) => { if (!o) setConfirmRow(null) }}>
+        <div style={{ display: 'none' }} aria-hidden="true">trigger</div>
+        <Dialog>
+          <Heading>Restore this snapshot?</Heading>
+          <Header><Text>{confirmRow?.label}</Text></Header>
+          <Divider />
+          <Content>
+            <Text>
+              The current state will be saved as a backup snapshot, then every
+              value row will be replaced with the snapshot's contents.
+              {' '}{confirmRow?.counts?.values ?? '?'} value rows and
+              {' '}{confirmRow?.counts?.sections ?? '?'} schema sections.
+            </Text>
+            <View marginTop="size-200">
+              <Switch isSelected={restoreSchema} onChange={setRestoreSchema}>
+                Restore schema too (uncheck to keep current schema, restore values only)
+              </Switch>
+            </View>
+          </Content>
+          <ButtonGroup>
+            <Button variant="secondary" onPress={() => setConfirmRow(null)} isDisabled={restoring}>Cancel</Button>
+            <Button variant="cta" onPress={doRestore} isDisabled={restoring}>
+              {restoring ? 'Restoring…' : 'Restore'}
+            </Button>
+          </ButtonGroup>
+        </Dialog>
+      </DialogTrigger>
+    </View>
+  )
+}