@edgedev/create-edge-app 1.2.35 → 1.2.36

package/agents.md

@@ -99,25 +99,51 @@ Adjust props (search, filters, pagination, save overrides) using the existing co
 - Array loop aliases use `as` (for example `{{{#array {"field":"items","as":"card"}}}}`).
 - Use `subarray` for nested arrays and `entries` for object key/value iteration.
 - Use `renderBlocks` when an item contains nested CMS block content (for example post body content).
+- Inside `renderBlocks`, use `{{renderItem.someField}}` to render values directly from the current item passed into that block render.
 
 ### Array data loading (Firestore/API)
 - Firestore arrays use `collection` config with `path`, `uniqueKey`, `query`, `order`, `limit`.
 - `path` is org-scoped under `organizations/{orgId}`.
-- `uniqueKey` supports template tokens like `{orgId}` and `{siteId}`.
+- `uniqueKey` supports runtime tokens such as `{orgId}` and `{siteId}` and is resolved in memory at runtime.
+- `collection.canonicalLookup.key` is optional and supports runtime token replacement for direct canonical fetches.
 - API arrays use `api`, optional `apiQuery`, and `apiField`.
 - `queryOptions` creates CMS filter controls; selected values are stored in `meta.queryItems`.
+- `query` and `queryItems` stay saved exactly as authored; supported runtime tokens in `query`, `queryItems`, `uniqueKey`, and `collection.canonicalLookup.key` include `{orgId}`, `{siteId}`, and `{routeLastSegment}`.
+- If you manually author a key in `queryItems`, that value overrides a `queryOption` on the same key. In practice, do not manually set a `queryItems` key that you want CMS users to edit through `queryOptions`.
 - Loading state tokens are supported while async array data resolves: `{{loading}}` and `{{loaded}}`.
 
 ### Array query execution model (critical)
+- Before runtime fetches, tokens in `collection.query`, `queryItems`, `uniqueKey`, and `collection.canonicalLookup.key` are resolved in memory only. Saved blocks keep the original tokens.
 - Each `queryItems` entry performs its own KV index lookup via `kvClient.queryIndex`.
 - Query keys only work if the field is present in KV mirror config: include keys in `indexKeys`, and also in `metadataKeys` when needed for rendering/sorting.
 - Multiple `queryItems` are unioned first (OR behavior at lookup stage).
 - Candidate duplicates are removed by canonical key.
 - `collection.query` then runs in JavaScript as final filtering (AND behavior across rules).
 - `collection.order` sorts the filtered result set.
+- If `collection.canonicalLookup.key` is present, runtime can fetch the exact document directly instead of relying on indexed lookups.
 - Final output is written to `values[field]`.
 - If load fails, runtime falls back to inline `value` or `[]` when no fallback value exists.
 
+### Array query strategy examples
+- Indexed detail lookup by slug/name:
+```hbs
+{{{#array {"field":"list","collection":{"path":"posts","queryItems":{"name":"{routeLastSegment}"},"order":[]},"queryOptions":[],"limit":1,"value":[]}}}}
+  {{{#renderBlocks {"field":"item"}}}}
+{{{/array}}}
+```
+- Inside a block rendered by `renderBlocks`, use `renderItem` against the passed item:
+```hbs
+<article>
+  <h2>{{renderItem.name}}</h2>
+  {{{content}}}
+</article>
+```
+- Canonical direct lookup:
+```hbs
+{{{#array {"field":"siteDoc","collection":{"path":"sites","canonicalLookup":{"key":"{orgId}:{siteId}"},"order":[]},"value":[]}}}}
+```
+- For canonical-only fetches, `uniqueKey` and `limit` are not required.
+
 ### Firestore index + KV mirror requirements
 - Any Firestore compound query used by blocks (for example array contains + order) requires matching composite indexes in `firestore.indexes.json`.
 - Fast CMS filtering requires KV mirroring in Functions with both index and metadata coverage.
@@ -154,14 +180,17 @@ exports.onListingWritten = createKvMirrorHandlerFromFields({
 - Do reuse Edge components (`dashboard`, `editor`, `cms` blocks, auth widgets) before adding new ones.
 - Do keep Firestore paths, queries, and role checks consistent with `edgeGlobal` helpers (`isAdminGlobal`, `getRoleName`, etc.).
 - Do use the `edge-*.sh` scripts (like `edge-pull.sh` and `edge-components-update.sh`) to sync/update the `edge` subtree instead of manual edits.
+- For CMS work, all approved code changes must stay inside `edge/**` unless the change specifically belongs in `functions/cms.js` or `functions/history.js` and that file was explicitly approved for this task. Do not add CMS-specific code in root-level `components/`, `composables/`, `pages/`, or other non-`edge` app locations.
+- If the likely correct fix appears to be inside `edge/**`, `functions/cms.js`, or `functions/history.js`, ask for permission to edit that location. Do not avoid the correct fix by automatically routing around those files.
 - Don’t introduce TypeScript, Options API, raw Firebase SDK calls, or ad-hoc forms/tables when an Edge component exists.
 - Don’t edit code inside the `edge` folder (including `edge/components/cms/*`) unless absolutely required and you have asked for and received user permission for that specific edit every time; it is a shared repo.
 - If an `edge/*` change is unavoidable, keep it generic (no project-specific hacks) and call out the suggestion instead of making the edit when possible.
 - Don’t modify `storage.rules` or `firestore.rules`.
 
 ## Firebase Functions guidance
-- Review `functions/config.js`, `functions/edgeFirebase.js`, and `functions/cms.js` to mirror established patterns.
-- Only edit `functions/config.js`, `functions/edgeFirebase.js`, or `functions/cms.js` when absolutely required and only after asking for and receiving user permission each time.
+- Review `functions/config.js`, `functions/edgeFirebase.js`, `functions/cms.js`, and `functions/history.js` to mirror established patterns.
+- Only edit `functions/config.js`, `functions/edgeFirebase.js`, `functions/cms.js`, or `functions/history.js` when absolutely required and only after asking for and receiving user permission each time.
+- When a bug or feature likely belongs in `functions/cms.js` or `functions/history.js`, ask to edit that file instead of automatically creating a workaround in a new function or another file.
 - When adding new cloud functions, create a new JS file under `functions/` and export handlers using the shared imports from `config.js`. Wire it up by requiring it in `functions/index.js` (same pattern as `stripe.js`), instead of modifying restricted files.
 - For every `onCall` function, always enforce both checks up front: `request.auth?.uid` must exist, and `request.data?.uid` must exactly match `request.auth.uid`. Throw `HttpsError('unauthenticated', ...)` when auth is missing and `HttpsError('permission-denied', ...)` when the uid does not match.
 

package/edge-update-all.sh

@@ -50,6 +50,9 @@ sync_edge_functions() {
 
   find "$edge_functions_dir" -type f | sort | while IFS= read -r src_file; do
     rel_path="${src_file#$edge_functions_dir/}"
+    if [ "$rel_path" = "index.js" ]; then
+      continue
+    fi
     dest_file="$local_functions_dir/$rel_path"
     dest_dir="$(dirname "$dest_file")"
 
@@ -59,6 +62,68 @@ sync_edge_functions() {
   done
 }
 
+merge_edge_functions_index() {
+  edge_index="$SCRIPT_DIR/edge/functions/index.js"
+  local_index="$SCRIPT_DIR/functions/index.js"
+
+  if [ ! -f "$edge_index" ] || [ ! -f "$local_index" ]; then
+    return
+  fi
+
+  echo "==> Merging extra edge function exports into local functions/index.js"
+  EDGE_FUNCTIONS_INDEX_PATH="$edge_index" LOCAL_FUNCTIONS_INDEX_PATH="$local_index" node <<'EOF'
+const fs = require('fs')
+
+const edgePath = process.env.EDGE_FUNCTIONS_INDEX_PATH
+const localPath = process.env.LOCAL_FUNCTIONS_INDEX_PATH
+const startMarker = '// START EXTRA EDGE functions'
+const endMarker = '// END EXTRA EDGE functions'
+
+const readText = filePath => fs.readFileSync(filePath, 'utf8')
+
+const extractMarkedBlock = (text) => {
+  const start = text.indexOf(startMarker)
+  const end = text.indexOf(endMarker)
+  if (start === -1 || end === -1 || end < start)
+    throw new Error(`Missing ${startMarker}/${endMarker} block in ${edgePath}`)
+
+  const endLine = text.indexOf('\n', end)
+  return endLine === -1 ? text.slice(start) : text.slice(start, endLine + 1)
+}
+
+const replaceMarkedBlock = (text, replacement) => {
+  const start = text.indexOf(startMarker)
+  const end = text.indexOf(endMarker)
+  const edgeFirebaseEndMarker = '// END @edge/firebase functions'
+
+  if (start === -1 || end === -1 || end < start) {
+    const edgeFirebaseEnd = text.indexOf(edgeFirebaseEndMarker)
+    if (edgeFirebaseEnd !== -1) {
+      const edgeFirebaseEndLine = text.indexOf('\n', edgeFirebaseEnd)
+      const insertAt = edgeFirebaseEndLine === -1 ? text.length : edgeFirebaseEndLine + 1
+      const before = text.slice(0, insertAt)
+      const after = text.slice(insertAt)
+      const joiner = before.endsWith('\n\n') ? '' : '\n'
+      return `${before}${joiner}${replacement}${after}`
+    }
+    const normalized = text.endsWith('\n') ? text : `${text}\n`
+    return `${normalized}\n${replacement}`
+  }
+
+  const endLine = text.indexOf('\n', end)
+  const after = endLine === -1 ? '' : text.slice(endLine + 1)
+  return `${text.slice(0, start)}${replacement}${after}`
+}
+
+const edgeText = readText(edgePath)
+const localText = readText(localPath)
+const edgeBlock = extractMarkedBlock(edgeText)
+const mergedText = replaceMarkedBlock(localText, edgeBlock)
+
+fs.writeFileSync(localPath, mergedText.endsWith('\n') ? mergedText : `${mergedText}\n`)
+EOF
+}
+
 merge_firestore_indexes() {
   edge_indexes="$SCRIPT_DIR/edge/root/firestore.indexes.json"
   local_indexes="$SCRIPT_DIR/firestore.indexes.json"
@@ -112,11 +177,66 @@ fs.writeFileSync(localPath, `${JSON.stringify(merged, null, 2)}\n`)
 EOF
 }
 
+merge_history_config() {
+  edge_history_config="$SCRIPT_DIR/edge/root/history.config.json"
+  local_history_config="$SCRIPT_DIR/functions/history.config.json"
+
+  if [ ! -f "$edge_history_config" ]; then
+    return
+  fi
+
+  if [ ! -f "$local_history_config" ]; then
+    echo "==> Writing functions/history.config.json from edge/root"
+    mkdir -p "$(dirname "$local_history_config")"
+    cp "$edge_history_config" "$local_history_config"
+    return
+  fi
+
+  echo "==> Merging functions/history.config.json with local priority"
+  EDGE_HISTORY_CONFIG_PATH="$edge_history_config" LOCAL_HISTORY_CONFIG_PATH="$local_history_config" node <<'EOF'
+const fs = require('fs')
+
+const edgePath = process.env.EDGE_HISTORY_CONFIG_PATH
+const localPath = process.env.LOCAL_HISTORY_CONFIG_PATH
+
+const readJson = filePath => JSON.parse(fs.readFileSync(filePath, 'utf8'))
+
+const isPlainObject = value => {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+const mergeWithLocalPriority = (edgeValue, localValue) => {
+  if (localValue === undefined)
+    return edgeValue
+
+  if (Array.isArray(edgeValue) || Array.isArray(localValue))
+    return localValue
+
+  if (isPlainObject(edgeValue) && isPlainObject(localValue)) {
+    const merged = { ...edgeValue }
+    for (const key of Object.keys(localValue))
+      merged[key] = mergeWithLocalPriority(edgeValue?.[key], localValue[key])
+    return merged
+  }
+
+  return localValue
+}
+
+const edgeJson = readJson(edgePath)
+const localJson = readJson(localPath)
+const merged = mergeWithLocalPriority(edgeJson, localJson)
+
+fs.writeFileSync(localPath, `${JSON.stringify(merged, null, 2)}\n`)
+EOF
+}
+
 echo "==> Updating edge subtree"
 "$SCRIPT_DIR/edge-pull.sh"
 
 sync_edge_functions
+merge_edge_functions_index
 merge_firestore_indexes
+merge_history_config
 
 echo "==> Removing @edgedev packages"
 pnpm remove @edgedev/template-engine @edgedev/firebase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgedev/create-edge-app",
-  "version": "1.2.35",
+  "version": "1.2.36",
   "description": "Create Edge Starter App",
   "bin": {
     "create-edge-app": "./bin/cli.js"