@ductape/mcp 0.2.2 → 0.2.4

package/dist/index.js

@@ -11,6 +11,8 @@
  */
 import { createRequire } from 'module';
 import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { delimiter, join } from 'path';
 import { z } from 'zod';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 const MODULES = [
@@ -141,9 +143,10 @@ There are THREE categories of operations. Use the right tool for each:
            ductape_cli("resources database create -f db-config.json")
        This applies to: products, apps, and resources (databases, storage, caches, etc.),
        cloud connections, and secrets. Environments have their own CLI commands (see below);
-       app actions, auths, quotas, fallbacks, jobs, and healthchecks are configured in the
-       Workbench UI. Features have no CLI create command because their definitions are code-first
-       through features.define.
+       App actions and auths are configured in the Workbench UI. Quotas, fallbacks, jobs, and
+       healthchecks are administrative resources managed with ductape_cli("resources <type> ...").
+       Features have no CLI create command because their definitions are code-first through
+       features.define.
 
        ⚠ MULTI-ENV REQUIREMENT — applies to ALL product assets (storage, database, cache,
        messageBroker, graph, vector, and any other resource with an envs array):
@@ -1175,15 +1178,19 @@ function checkCli() {
     try {
         const out = execSync('ductape --version', {
             encoding: 'utf8',
-            timeout: 5000,
+            timeout: 15000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
             cwd: cliCwd(),
         }).trim();
         return { available: true, version: out || 'unknown' };
     }
-    catch {
-        return { available: false };
+    catch (error) {
+        const message = String(error?.stderr || error?.message || error);
+        const commandMissing = error?.code === 'ENOENT' ||
+            error?.status === 127 ||
+            /\b(command not found|not recognized as an internal|no such file or directory)\b/i.test(message);
+        return { available: !commandMissing };
     }
 }
 function checkLoginState() {
@@ -1298,6 +1305,18 @@ function runCli(command) {
 function cliEnvironment() {
     const environment = { ...process.env };
     delete environment.DUCTAPE_ACCESS_KEY;
+    const pathKey = Object.keys(environment).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
+    const configuredPath = environment[pathKey] ?? '';
+    const fallbackBins = [
+        join(homedir(), '.npm-global', 'bin'),
+        join(homedir(), '.local', 'bin'),
+        '/opt/homebrew/bin',
+        '/usr/local/bin',
+    ];
+    environment[pathKey] = [...new Set([
+            ...configuredPath.split(delimiter).filter(Boolean),
+            ...fallbackBins,
+        ])].join(delimiter);
     return environment;
 }
 /**
@@ -2788,10 +2807,13 @@ Resilience covers three mechanisms: quotas (rate-limited provider pools), fallba
 provider switching), and healthchecks (continuous probe monitoring with failure actions).
 
 CONFIGURATION BOUNDARY
-  Quotas, fallbacks, and health checks are administrative product configuration. Configure them in
-  Workbench (or a future access-key administrative tool explicitly documented for the asset).
-  Never route administrative create/update methods through ductape_execute: its publishable-key
-  runtime proxy will fail.
+  Quotas, fallbacks, and health checks are administrative product configuration. Manage them with
+  the authenticated CLI:
+    ductape_cli("resources quota ...")
+    ductape_cli("resources fallback ...")
+    ductape_cli("resources health ...")
+  Workbench is also supported. Never route their administrative create/update methods through
+  ductape_execute: its publishable-key runtime proxy will fail.
 
 QUOTAS — rate-limited multi-provider pools:
   Workbench definition shape:
@@ -2822,6 +2844,13 @@ FALLBACKS — automatic provider switching on failure:
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
 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
+  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.
+
   Workbench definition shape:
   {
     tag: "payment-health",
@@ -2829,7 +2858,7 @@ HEALTHCHECKS — continuous probe with failure notifications:
     probe: { type: "app", app: "stripe-app", event: "ping" },
     interval: 30000,    // ms between checks
     retries: 3,
-    envs: [{ slug: "prd", input: {} }],
+    envs: [{ slug: "prd", input: { path: "/health" } }],
     onFailure: {
       notifications: [{ notification: "ops-alerts", message: "payment-down",
         channels: { email: { recipients: ["ops@example.com"] } } }],
@@ -2840,8 +2869,37 @@ HEALTHCHECKS — continuous probe with failure notifications:
   health.check  [{ product, env, tag }]   → same as run
   health.status [{ product, env, tag }]   → current health status
 
-Probe types: app | database | feature | graph | message_broker | storage
-Failure actions: notification channels, HTTP webhooks, and/or message broker emit — all can
+Probe types: app | database | feature | graph | events | storage
+Canonical Events probe:
+  { type: "events", events: "statecraft-events", event: "health" }
+Do not create new probes with type/field message_broker or messageBroker; those names are deprecated
+compatibility aliases.
+
+APP HEALTHCHECK SETUP — REQUIRED DISCOVERY AND VALIDATION
+  An app healthcheck is not a generic URL ping. It invokes one action belonging to an app already
+  connected to the product. Before creating it:
+  1. Read the product's connected apps with:
+       ductape_cli("products components get --product-tag <product> --type apps --json")
+  2. Select a connected app by its product access tag. Never invent or use an unconnected app tag.
+  3. Inspect that connected app's available actions/schema using the app/schema tools. Select an
+     existing action intended to be safe for repeated health probes.
+  4. Build a payload matching that action's required input schema for every selected product
+     environment. Payloads belong in envs[].input and may differ by environment.
+  5. Create the resource with:
+       ductape_cli("resources health create --tag <product> -f <healthcheck.json> --json")
+  6. Fetch the created healthcheck and verify probe.app, probe.event, and every env payload target;
+     then run one immediate check and inspect status before relying on the schedule.
+
+  Required app probe shape:
+  {
+    probe: { type: "app", app: "<connected-app-access-tag>", event: "<existing-action-tag>" },
+    envs: [{ slug: "<product-env>", input: { ...actionPayload } }]
+  }
+  Do not create an app healthcheck when the app, action, or required payload cannot be verified.
+  The platform must reject missing/unconnected apps, unknown actions, and invalid action payloads;
+  never interpret a successful create response alone as proof that the probe is runnable.
+
+Failure actions: notification channels, HTTP webhooks, and/or Events emit — all can
   be configured simultaneously on the same healthcheck.
 Input template references: $Input{field} → maps declared input to the probe's action input.
 Provider status: available | unavailable
@@ -4332,8 +4390,9 @@ const cliInputSchema = z.object({
         'resources (databases, storage, caches…), event broker topics, cloud connections, secrets, ' +
         'and for apply/migrate workflows.\n\n' +
         'Note: environments have their own CLI commands (products environments list/get/create/update, ' +
-        'no linked project required — the product tag is always an explicit argument). App actions, ' +
-        'quotas, fallbacks, and jobs are configured in the Workbench UI. Features also have no CLI ' +
+        'no linked project required — the product tag is always an explicit argument). Quotas, ' +
+        'fallbacks, jobs, and healthchecks use resources commands. App actions and auths are ' +
+        'configured in the Workbench UI. Features have no CLI ' +
         'creation command: define them in application code with features.define so application ' +
         'boot/runtime registration makes them available.\n\n' +
         'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
@@ -4788,13 +4847,14 @@ async function main() {
                 '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
                 '  - Listing workspaces, products, focused product components, secrets\n' +
                 '    Prefer "products components list --product-tag <tag> --json" for compact inventory; use\n' +
-                '    "products components get --product-tag <tag> --type notifications|events --json" for focused detail.\n' +
+                '    "products components get --product-tag <tag> --type notifications|events|healthchecks|features --json" for focused detail.\n' +
                 '  - Managing notification components and message templates through "resources notifications" and "notifications messages"\n' +
                 '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
                 '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
                 '  - Running database migrations: "db migrate", "db schema generate"\n\n' +
-                'NOTE: Environments have their own CLI commands (products environments *). App actions, ' +
-                'auths, quotas, fallbacks, and jobs are configured in the Workbench UI. Features have no ' +
+                'NOTE: Environments have their own CLI commands (products environments *). App actions ' +
+                'and auths are configured in the Workbench UI. Quotas, fallbacks, jobs, and healthchecks ' +
+                'are managed with resources commands. Features have no ' +
                 'CLI creation command because definitions are code-first through features.define and ' +
                 'registered by the application runtime.\n\n' +
                 'DO NOT use ductape_execute for admin operations — it uses a publishable key which only ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",