@ductape/mcp 0.3.0 → 0.3.2

package/dist/index.js

@@ -2904,11 +2904,23 @@ Import an existing resource and register it on the product:
   Use import-persist-all for multi-env products (required):
     ductape_cli("cloud resources import-persist-all -f all-envs.json --json")
   File is a JSON ARRAY — one entry per env, same product + component tag across all entries.
-  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName? }
+  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName?, masterPassword? }
   Supported service identifiers: s3, gcs, blob, rds, postgresql, cloudsql, sqs, pubsub,
     servicebus, neptune, cosmos-gremlin, opensearch, azure-search, atlas-cluster, aura-instance,
     vertex-vector-search, spanner-graph, dynamodb, keyspaces, mysql
 
+  masterPassword is required for self-hosted-style imports where Ductape cannot mint or fetch
+  credentials on its own: rds, postgresql, cloudsql, mysql (unless the instance already has
+  stored Ductape credentials from a prior link), and — critically — aura-instance. Neo4j Aura
+  shows the auto-generated database password only ONCE, at instance creation, in the Aura
+  console, and it can never be retrieved again via the Aura API. Importing an Aura instance
+  without masterPassword will fail with a clear error at import time; skipping that check and
+  importing anyway is not possible — always ask the user for the instance's password before
+  calling import-persist-all for an aura-instance entry, the same as you would ask for an RDS
+  master password. Aura's username is always "neo4j" — never ask the user for it. Atlas
+  (atlas-cluster) does NOT need masterPassword — Ductape mints/rotates its own database user via
+  the Atlas Admin API.
+
 Provision a brand-new resource and register it:
   ductape_cli("cloud resources provision-persist-all -f all-envs.json --json")
   Additional per-entry fields: tier, region/location, waitForReady.
@@ -3709,7 +3721,7 @@ QUOTAS — weighted/provider-capacity routing pools (NOT request rate limiting):
     input: { to: { type: "string", required: true }, message: { type: "string" } },
     options: [
       { provider: "twilio", app: "twilio-app", type: "action", event: "send-sms",
-        quota: 1000, uses: 0, retries: 2,
+        quota: 1000, uses: 0, retries: 2, health: "twilio-health",
         input: { "body:to": "$Input{to}", "body:message": "$Input{message}" },
         output: {} },
       { provider: "nexmo", app: "nexmo-app", type: "action", event: "send-sms",
@@ -3731,13 +3743,54 @@ FALLBACKS — automatic provider switching on failure:
   fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
+HEALTH-GATED PROVIDERS — REQUIRED BEHAVIOR:
+  Provider options may declare health: "<healthcheck-tag>". healthcheck is a deprecated input alias;
+  generate health in new JSON and code. Before creating a quota/fallback, list the product's existing
+  healthchecks and reuse one whose probe targets the same app/resource and operation. Create a new
+  healthcheck only when no equivalent check exists. Verify the referenced tag exists in the same
+  product and covers every environment used by the quota/fallback.
+
+  This is an active prerequisite, not optional advice. When creating or updating a quota/fallback:
+  1. List existing healthchecks and connected product providers.
+  2. Match each provider to an existing check by probe type + provider asset/app + safe probe event.
+  3. For every unmatched provider, inspect its live action/resource schema, choose a repeat-safe probe,
+     write ductape/healthchecks/<tag>.json, and run: ductape resources health create --tag <product>
+     -f ductape/healthchecks/<tag>.json --json.
+  4. Fetch and explicitly run each newly-created check in every target environment. Do not create the
+     quota/fallback until the probe schema and status lookup both succeed.
+  5. Put health: "<verified-healthcheck-tag>" on every provider option, then create/update and refetch
+     the quota/fallback. A provider without a verified health tag is an incomplete resilience asset.
+  If no safe repeatable probe exists, stop and explain the blocker; never invent an endpoint or omit
+  health silently.
+
+  Runtime contract:
+  - Read the linked health status before provider selection.
+  - Never select a provider whose linked status is unavailable, even when every provider is down.
+    Return NO_HEALTHY_PROVIDERS/NO_PROVIDERS_AVAILABLE instead of forcing traffic through it.
+  - When a selected provider exhausts its bounded retries, immediately mark the linked healthcheck
+    unavailable. The current fallback or quota invocation must immediately continue/reselect from
+    the remaining healthy options; subsequent invocations must also skip it. Never wait for the
+    health poll before performing local failover.
+  - Runtime success does not close the circuit. Only a successful scheduled or explicit health probe
+    restores available, preventing one opportunistic request from bypassing recovery validation.
+  - One global Tickets-hosted scheduler is the fallback runner when no fresh local SDK monitor result
+    exists. Do not require application code to call monitor() for platform healthchecks to run.
+  - Remote and local runtimes share health through the product's centrally persisted health state,
+    not through a common Redis instance. SDK runtime-manifest polling compares healthRevision and
+    atomically refreshes an in-process health snapshot in the background. Quota/fallback routing uses
+    synchronous snapshot reads; never add a bootstrap, Redis, or backend lookup to the invocation path.
+    A local provider failure trips the in-process state immediately and persists it asynchronously so
+    other instances receive it on their next lightweight poll.
+  - A transition from available to unavailable sends one alert to accepted workspace participants;
+    repeated unhealthy probe results must not generate duplicate transition emails.
+
 HEALTHCHECKS — continuous probe with failure notifications:
-  Scheduled probes have a platform-owned fallback runner in the Ductape proxy. A local SDK monitor
-  may also run them: while it consistently persists a fresh lastChecked record, the proxy defers
-  that product/env/check. The proxy freshness window accounts for the SDK's batched backend status
+  Scheduled probes have a platform-owned global fallback runner in the Ductape Tickets service. A local SDK monitor
+  may also run them: while it consistently persists a fresh lastChecked record, the global worker defers
+  that product/env/check. The server freshness window accounts for the SDK's batched backend status
   flush (currently five minutes), not only the shorter probe interval. If records stop arriving and
-  the freshness window expires, the proxy automatically takes over. Do not instruct users to
-  disable the proxy fallback when using a local monitor.
+  the freshness window expires, the global worker automatically takes over. Do not instruct users to
+  disable the server fallback when using a local monitor.
 
   Workbench definition shape:
   {
@@ -6912,6 +6965,32 @@ async function main() {
                 '        "product":"my-product","component":"billing-db","env":"snd","resource":"Cluster0","dbName":"billing_snd"},\n' +
                 '        {"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
                 '        "product":"my-product","component":"billing-db","env":"prd","resource":"Cluster0","dbName":"billing_prd"}]\n' +
+                '  - Neo4j Aura (graph) import flow — service identifier is "aura-instance":\n' +
+                '    CRITICAL: masterPassword is REQUIRED in every import entry for aura-instance. Aura shows the\n' +
+                '    auto-generated database password only ONCE, at instance creation, in the Aura console, and it\n' +
+                '    can never be retrieved again via the Aura API — Ductape has no way to source it automatically.\n' +
+                '    Always ask the user for the instance password before calling import-persist-all for an\n' +
+                '    aura-instance entry; do not attempt the import without it, it will fail with a clear error\n' +
+                '    naming exactly this. The username is always "neo4j" for every Aura instance — never ask the\n' +
+                '    user for it, and never put it in masterPassword by mistake.\n' +
+                '    Step 1 — discover the instance:\n' +
+                '      ductape_cli("cloud resources list -f /tmp/aura-list.json --json")\n' +
+                '      File: {"cloud": "<aura-connection-tag>", "service": "aura-instance"}\n' +
+                '      Returns a list of Aura instances; note the "id" or "name" field (this is your resource\n' +
+                '      identifier). Aura instances cannot be created through Ductape — provision-persist-all is\n' +
+                '      not supported for this provider; only an already-existing instance can be linked.\n' +
+                '    Step 2 — import (one entry per product env, same instance across all envs unless the user\n' +
+                '      explicitly wants different Aura instances per environment):\n' +
+                '        cloud (connection tag), service: "aura-instance", type: "graphs",\n' +
+                '        product, component (new or existing graph tag), env, resource (instance id/name from\n' +
+                '        Step 1), masterPassword (the instance password — ask the user, do not guess or omit).\n' +
+                '      Example (two envs, same Aura instance):\n' +
+                '      [{"cloud":"aura-tag","service":"aura-instance","type":"graphs",\n' +
+                '        "product":"my-product","component":"commerce-network","env":"snd",\n' +
+                '        "resource":"1d7fc731","masterPassword":"<user-supplied>"},\n' +
+                '        {"cloud":"aura-tag","service":"aura-instance","type":"graphs",\n' +
+                '        "product":"my-product","component":"commerce-network","env":"prd",\n' +
+                '        "resource":"1d7fc731","masterPassword":"<user-supplied>"}]\n' +
                 '  - Message broker / event broker import:\n' +
                 '    CLI accepts these aliases for the messageBrokers module: events, event, broker, brokers, message-brokers.\n' +
                 '    List existing brokers: ductape_cli("resources events list --json")\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs && node scripts/check-runtime-input-recovery.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs && node scripts/check-runtime-input-recovery.mjs && node scripts/check-resilience-health-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },