@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-source-shopify/source-schema.example.json

@@ -1,201 +0,0 @@
-{
-  "$comment": "TEMPLATE / EXAMPLE for migrations/<project>/source-schema.json when platform=shopify (private data, read through the Shopify CLI). A shape to follow, NOT a strict schema to validate against. Keep the agnostic core identical to every other platform; push Shopify quirks into the open `sourceMeta` blobs. Synthesize it from data/shopify-discovery/entities/*.json. All values below are invented.",
-  "platform": "shopify",
-  "capturedAt": "2026-10-15T00:00:00.000Z",
-  "rawDiscovery": "data/shopify-discovery/",
-  "$comment_failedReads": "An entity whose read failed (for example discounts) is NOT synthesized as an empty entity: it is already a `shopify:<entity>` capture-failed row in source-coverage.json. Omit it from `entities`.",
-  "sourceMeta": {
-    "$comment": "Store-level facts from the `shop` singleton and the access path.",
-    "accessPath": "shopify-cli",
-    "readOnly": true,
-    "shopDomain": "example-store.myshopify.com",
-    "currencyCode": "USD",
-    "ianaTimezone": "America/New_York",
-    "quirks": [
-      "Global ids are `gid://shopify/<Type>/<n>`; keep them verbatim as source identifiers.",
-      "The CLI shows only recent orders; older orders are a source-coverage row, not missing data."
-    ]
-  },
-  "entities": {
-    "products": {
-      "rawFile": "entities/products.json",
-      "recordCount": 42,
-      "inUse": true,
-      "sourceIdField": "id",
-      "fields": {
-        "id": {
-          "type": "string",
-          "required": true,
-          "example": "gid://shopify/Product/1001"
-        },
-        "title": {
-          "type": "string",
-          "required": true,
-          "example": "Example Tee"
-        },
-        "handle": {
-          "type": "string",
-          "required": true,
-          "example": "example-tee"
-        },
-        "status": {
-          "type": "enum",
-          "values": [
-            "ACTIVE",
-            "DRAFT",
-            "ARCHIVED"
-          ],
-          "example": "DRAFT"
-        },
-        "vendor": {
-          "type": "string",
-          "example": "Example Vendor"
-        },
-        "productType": {
-          "type": "string",
-          "example": "Shirts"
-        },
-        "tags": {
-          "type": "string[]",
-          "example": [
-            "summer"
-          ]
-        },
-        "options": {
-          "type": "object[]",
-          "example": [
-            {
-              "name": "Size",
-              "values": [
-                "S",
-                "M"
-              ]
-            }
-          ]
-        }
-      },
-      "relations": [
-        {
-          "to": "variants",
-          "kind": "has-many",
-          "via": "variants",
-          "evidence": "entities/products.json samples[].variants"
-        }
-      ],
-      "sourceMeta": {
-        "$comment": "Draft and archived products are included: the Admin API lists every status.",
-        "statusesSeen": [
-          "ACTIVE",
-          "DRAFT",
-          "ARCHIVED"
-        ],
-        "candidateTargetRefs": [
-          "stores/product"
-        ]
-      }
-    },
-    "variants": {
-      "rawFile": "entities/products.json",
-      "recordCount": null,
-      "inUse": true,
-      "sourceIdField": "id",
-      "fields": {
-        "id": {
-          "type": "string",
-          "required": true,
-          "example": "gid://shopify/ProductVariant/2001"
-        },
-        "sku": {
-          "type": "string",
-          "example": "EX-TEE-S"
-        },
-        "price": {
-          "type": "decimal-string",
-          "example": "20.00"
-        },
-        "compareAtPrice": {
-          "type": "decimal-string",
-          "nullable": true,
-          "example": null
-        },
-        "inventoryQuantity": {
-          "type": "integer",
-          "example": 5
-        }
-      },
-      "sourceMeta": {
-        "$comment": "Read nested under products; there is no separate variant count at discovery.",
-        "nestedIn": "products"
-      }
-    },
-    "orders": {
-      "rawFile": "entities/orders.json",
-      "recordCount": 7,
-      "inUse": true,
-      "sourceIdField": "id",
-      "fields": {
-        "id": {
-          "type": "string",
-          "required": true,
-          "example": "gid://shopify/Order/4001"
-        },
-        "name": {
-          "type": "string",
-          "required": true,
-          "example": "#1001"
-        },
-        "createdAt": {
-          "type": "datetime",
-          "required": true,
-          "example": "2026-09-20T12:00:00Z"
-        },
-        "displayFinancialStatus": {
-          "type": "enum",
-          "example": "PAID"
-        },
-        "displayFulfillmentStatus": {
-          "type": "enum",
-          "example": "FULFILLED"
-        },
-        "totalPriceSet.shopMoney": {
-          "type": "money",
-          "example": {
-            "amount": "32.00",
-            "currencyCode": "USD"
-          }
-        }
-      },
-      "sourceMeta": {
-        "$comment": "recordCount is what the CLI can see (its order-history window), not the store's lifetime total.",
-        "countScope": "cli-window"
-      }
-    },
-    "customers": {
-      "$comment": "Example of a lower-bound count: Shopify answered precision AT_LEAST (countExact false), so recordCount is null and the bound is recordCountAtLeast. An exact count would be recordCount: 12.",
-      "rawFile": "entities/customers.json",
-      "recordCount": null,
-      "recordCountAtLeast": 12,
-      "inUse": true,
-      "sourceIdField": "id",
-      "fields": {
-        "id": {
-          "type": "string",
-          "required": true,
-          "example": "gid://shopify/Customer/6001"
-        },
-        "createdAt": {
-          "type": "datetime",
-          "example": "2026-03-01T00:00:00Z"
-        },
-        "numberOfOrders": {
-          "type": "integer-string",
-          "example": "1"
-        },
-        "tags": {
-          "type": "string[]",
-          "example": []
-        }
-      }
-    }
-  }
-}

package/skills/wix-replatform/resources/rp-source-wordpress/PLUGIN-READ-PLANS.md

@@ -1,146 +0,0 @@
-# Project-local plugin entity plans
-
-Use this path when a selected WordPress plugin entity has no complete supported REST
-reader. A permanent plugin profile is optional. Do not install source code, edit this skill
-bundle, or invent a table/relationship to make discovery pass. Use actual schema, plugin
-storage documentation/source and bounded samples. Existing table restrictions, credential
-selection, secret filtering, mapping approval and confidentiality rules remain binding.
-
-## Prepare once in discovery
-
-Prefer a complete supported REST route. An owner-provided export is still an explicit
-owner action. Otherwise reuse verified profile knowledge or investigate storage once per
-unfamiliar plugin; cache schemas and valid plans within the project. No model work per row.
-
-Use `lib/plugin-entity-read-plan.js`:
-
-1. `sourceEntityRef(pluginSlug, entityKey)` returns `plugin.<inventory-slug>.<entity-key>`.
-   Persist this identity across coverage, source schema, mapping and deferred records.
-2. Save schema/storage evidence and exact requests under the project's
-   `data/wp-discovery/` with `writeJson(projectDir, path, value)`. It returns `{path,sha256}`.
-   Paths must stay inside the project; absolute, traversal and symlink paths are refused.
-3. Author the plan from evidence, using the shape below. `writePluginEntityReadPlan({
-   projectDir, plan, sourceEntity, siteBaseUrl })` validates it and returns the binding.
-   It sets `sourceEntity.sourceMeta.extractionPlan` and updates an existing
-   `source-schema.json` (object or array entities). When canonical synthesis has not yet
-   happened, carry that exact reference into it. Never infer filenames from table labels.
-4. Run the bounded samples through the same declared assembly. Inspect identity,
-   required relationships and fields before treating the plan as prepared. Preview
-   samples do not prove complete extraction. Preserve missing coverage and target decisions.
-5. If no valid recipe can be produced, call `recordPluginExtractionDeferral` with the
-   canonical reference, typed code and precise reason. It works without a table or plan.
-   Keep that entity in scope; an identical discovery rerun is not a remedy for missing
-   producer support. Do not substitute empty output or fictitious business records.
-
-Required plan members:
-
-| Member | Meaning |
-| --- | --- |
-| `schemaVersion` | `1` |
-| `sourceEntityRef` | Stable inventory-derived reference |
-| `sourceIdentity` | Credential-free base URL from `sourceIdentity(siteBaseUrl)`; retain subdirectory |
-| `evidenceRefs` | Nonempty array of persisted storage/schema `{path,sha256}` references |
-| `components` | One root and optional direct children, with distinct token `id`, physical bare `table`, `variant`, `schema`, `readArtifacts`, `scope` |
-| `components[].schema` | Actual `{table,columns,eavPair?}` schema evidence |
-| `components[].readArtifacts` | `{structureRequest: reference}` or `{eavReadPlan: reference}`; EAV key-name requests are insufficient |
-| `components[].scope` | `{where: [...]}`; a child adds `parent: {component: rootId, column: childForeignKey, parentColumn: rootIdColumn}` |
-| `assembly` | Explicit identity and relationship/cardinality configuration below |
-| `cost` | Preparation/query/page estimates, with unknown values recorded as null |
-
-`variant` is `single-request` or `eav`. Use the shared client `discoverEavKeys` and
-`buildEavReadPlan` with the same optional `scope` predicates for key discovery, counts and
-value requests. Keep complete keys/identity, existing server limits and request integrity.
-For a parent-scoped child, the retained sample EAV plan is the recipe evidence; full
-extraction discovers/materializes keys only for the completed root's IDs in chunks of
-`MAX_IN_VALUES`. It pins up to `MAX_PINNED_KEYS` per value request and pages all streams.
-Zero parents means zero child calls. No unrestricted read followed by local filtering.
-
-## Assembly
-
-For one row per logical record use `{kind:'identity', identityColumn:'<source-id>'}`.
-For a standalone EAV stream use `kind:'eav-pivot-v1'` with `identityColumn`, `keyColumn`,
-`valueColumn`, and `keys: { '<verified-key>': 'scalar' | 'array' }`.
-
-For a root plus metadata children use `kind:'eav-pivot-v1'`, the root `identityColumn`, and
-`children: [{component, foreignKey, keyColumn, valueColumn, keys, required, outputField?}]`.
-Name every child once. Required missing children, orphan relations, missing identity and
-duplicate scalar keys defer the entity; repeated values remain arrays in retained order.
-Unknown/new keys require renewed storage/schema preparation rather than omission.
-
-Use `kind:'module'` only for another verified one-level relationship. Include
-`identityColumn`, `module:{path,sha256}` under `src/extract/` or `src/lib/`, and `export`.
-The exported synchronous function takes `{components:{componentId:records[]}}` and returns
-logical records. Test it with invented values and source samples before full use. Its code
-digest is part of readiness/freshness. Deeper graphs require explicit additional support;
-do not flatten or silently omit them.
-
-## Extract and import
-
-`extractBoundPluginEntity({projectDir,sourceEntityRef,planRef,transport,restart?})` uses the
-existing shared reader for every component. It preserves pagination, checkpoints, frozen
-counts and complete-identity checks; a failed component leaves the logical entity deferred.
-Only a reconciled full output and current entity/component manifests authorize import.
-`sample:true` returns a preview without full-reader calls or artifact/status changes.
-
-Generate bridge dispatch with the committed `lib/generated-plugin-handoff.js` emitter.
-It owns `src/import/plugin-handoff.js` and the thin importer/extractor entrypoints. It
-refuses to overwrite any existing non-template entrypoint, checking all destinations
-before writing. Before deliberately replacing an existing entrypoint, adapt its implementation
-into `src/project/plugin-runtime.js`, preserving its heartbeat, self-check, ledger, selectors
-and target dependency order. The adapter exports:
-
-- `describeImport()`: pure declaration from the retained importer's actual configuration,
-  including its run-ID source, supported selection modes and actual ledger paths. The
-  wrapper never manufactures these capabilities. Also include `entityOrder`, listing every
-  planned canonical entity reference exactly once in the existing target dependency order.
-  The wrapper preserves this ordering and topologically orders source prerequisites;
-  missing references, cycles or a conflict with the declared target order fail before hooks/writes. This does not add the separate
-  target-parent readiness gate.
-- `sourceTransport({entity,projectDir,siteBaseUrl})`: same authenticated shared HTTP bridge
-  transport and telemetry callback discovery used; load secrets from the configured source.
-- `preview(entity)`: retained discovery samples only, or null. Never fetch full data here.
-- `extractNative({entity,selection,projectDir})`: existing supported native extraction.
-- `preflight({entities,selection,projectDir,runId})`: existing run-scoped authorization/setup/mute
-  checks, once before the first ready write; throw on refusal. Do not replace them with a
-  fixed successful response.
-- `importEntity({entity,selection,projectDir,dryRun})`: existing target writer, record
-  selectors, ledger, idempotency and recovery. Honour `dryRun` and every selection flag;
-  the wrapper's source-readiness gate grants no target permission or omission approval.
-- `finalizeImport({results,selection,projectDir,runId,deferredExtraction})`: retain existing
-  per-run recovery/completion publication, merging `deferredExtraction.operatorActions`
-  and `statuses` with the real journal-backed outcomes. It runs once even when all selected
-  plugin entities are held. A local finalization error never rewrites target receipts as
-  rejected creates.
-- `afterExtraction({results,selection,projectDir,runId})`: file accumulated source-read
-  telemetry once after the read pass, including deferred reads. Telemetry failure must not
-  discard extraction evidence.
-
-Full generated extraction covers mapped scopes and their source prerequisites; an excluded
-discovery entity does not become an extraction task. Only mapped target scopes dispatch
-for import, under existing mapping approval. One process run ID is supplied to adapter hooks. The
-guard checks the selected bridge entities and transitive source prerequisites once per
-entity/pass before target hooks run. Loading the adapter and calling its descriptor must
-have no side effects. Its descriptor is validated both on `--describe` and normal startup. Native-only unrelated reruns gain no extraction gate.
-Record filters apply after entity readiness, so missing extraction files cannot erase scope.
-
-The external verifier checks exact emitted wiring and helper bytes before `--describe`.
-Pass the same selection after `--`, for example `-- --entity <entity> --failed-only`.
-Unsupported wiring returns to codegen. Missing/stale preparation becomes a typed entity
-deferral. No skip flag, default query, alias probing or dynamic dispatch workaround.
-
-## Deferred handoff and cost
-
-Use the existing `<entity>.deferred.json`, `collectDeferredExtractions` and
-`deferredExtractionReportInput` completion integration. Codes `plan-unavailable`,
-`plan-invalid` and `assembly-failed` retain different producer repairs. Import readiness
-preserves an open extraction task for the current plan, including its restart policy.
-Otherwise missing/stale full evidence produces `full-extraction-unavailable` or
-`full-extraction-stale`, with a full-extraction action and project-relative diagnostics.
-Unknown tables/counts
-stay unknown. **Requires Import Operator** prompts name source access, timing and complete
-full-manifest resolution. Shared Cutover UI integration remains pending.
-
-Measure preparation tokens/time separately from source requests/bytes and elapsed I/O.
-Each dispatched key-discovery/value query costs at least one page; multiply value pages
-by parent chunks and key batches. Reuse current plans and shared assemblers. Never claim a
-synthetic transport timing measures live latency or agent storage-research cost.