@ductape/mcp 0.3.2 → 0.3.3

package/dist/index.js

@@ -857,7 +857,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.create  [{ product, tag, name, description?, type: "neo4j"|"nebula"|"arangodb", envs: [{slug, connection_url, username?, password?}] }]
   graph.fetch   [product_tag, graph_tag]
   graph.list    [product_tag?]
-  graph.update  [product_tag, graph_tag, data: { name?: string, description?: string, type?: "neo4j"|"neptune"|"arangodb"|"memgraph", envs?: [{ slug: string, connection_url: string, username?: string, password?: string, database?: string, graphName?: string, region?: string }] }]
+  graph.update  [product_tag, graph_tag, data: { name?: string, description?: string, type?: "neo4j"|"neptune"|"arangodb"|"memgraph", envs?: [{ slug: string, connection_url?: string, username?: string, password?: string, database?: string, graphName?: string, region?: string }] }]
+    Each env entry is a PARTIAL patch merged with that env's existing persisted config — only
+    include the fields you're actually changing (e.g. just { slug, password } to rotate a
+    password). connection_url is required only when adding a brand-new env slug; omitting it on
+    an existing slug leaves the current value untouched. Field name is "password", not
+    "masterPassword" — that's a different field used only by cloud resources import-persist-all
+    (see the Neo4j Aura import flow section below), not by graph.create/graph.update.
   graph.delete  [graph_tag, product_tag?]
   graph.connect [{ product, env, graph }]
   graph.testConnection [config]
@@ -1469,7 +1475,7 @@ const ADMIN_SUBCOMMANDS = [
     'migration-products',
     'migration-secrets',
 ];
-function checkCli() {
+function checkCli(projectDir) {
     try {
         const out = execFileSync('ductape', ['--version'], {
             shell: false,
@@ -1477,7 +1483,7 @@ function checkCli() {
             timeout: 15000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         }).trim();
         return { available: true, version: out || 'unknown' };
     }
@@ -1489,7 +1495,7 @@ function checkCli() {
         return { available: !commandMissing };
     }
 }
-function checkLoginState() {
+function checkLoginState(projectDir) {
     try {
         // `ductape whoami` only reports whether a local credentials file exists. It does not validate
         // the stored token, so an expired token would be cached as authenticated and fail later with 401.
@@ -1500,7 +1506,7 @@ function checkLoginState() {
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
         authState = 'ok';
         return 'ok';
@@ -1510,7 +1516,7 @@ function checkLoginState() {
         return 'none';
     }
 }
-function syncWorkspace() {
+function syncWorkspace(projectDir) {
     const target = process.env.DUCTAPE_WORKSPACE;
     workspaceSynced = true; // mark done regardless so we don't retry on every call
     if (!target)
@@ -1522,14 +1528,14 @@ function syncWorkspace() {
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
     }
     catch {
         // best-effort; if it fails the user will see workspace-mismatch errors on subsequent commands
     }
 }
-function runCli(command) {
+function runCli(command, projectDir) {
     let argv;
     try {
         argv = parseCliCommand(command);
@@ -1558,7 +1564,7 @@ function runCli(command) {
             timeout: 90000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
         return { success: true, output: output.trim() };
     }
@@ -1567,7 +1573,7 @@ function runCli(command) {
         if (/\bHTTP 401\b|unauthori[sz]ed|invalid token|token expired/i.test(msg)) {
             // Distinguish a genuinely expired login from a command-specific endpoint/auth bug.
             // A valid workspace read proves the CLI session and selected workspace are authenticated.
-            if (checkLoginState() === 'ok') {
+            if (checkLoginState(projectDir) === 'ok') {
                 return {
                     success: false,
                     output: [
@@ -1635,8 +1641,14 @@ function cliEnvironment() {
  * cwd is unrelated to the project). Set DUCTAPE_PROJECT_DIR explicitly in the server's env
  * (e.g. in .mcp.json) to pin it; falls back to this process's own cwd otherwise.
  */
-function cliCwd() {
-    return process.env.DUCTAPE_PROJECT_DIR || process.cwd();
+// `process.cwd()` here is the long-running MCP server process's own working directory — fixed for
+// its whole lifetime by whatever launched it, not the project the calling agent is currently
+// working in. A static DUCTAPE_PROJECT_DIR env var has the same problem: it can't track an agent
+// session that moves between projects. `override` lets a per-call `project_dir` argument (see
+// cliInputSchema, eventsProjectValidationInputSchema, eventsTopicSetupInputSchema) take precedence
+// over both, so a single long-lived MCP server can be pointed at the right project per call.
+function cliCwd(override) {
+    return override || process.env.DUCTAPE_PROJECT_DIR || process.cwd();
 }
 function shellArgument(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -1676,9 +1688,20 @@ const eventsTopicSetupInputSchema = z.object({
     sample: z.record(z.unknown()).optional(),
     idempotent: z.boolean().optional(),
     queueUrls: z.array(z.object({ env_slug: z.string().min(1), url: z.string().url() }).strict()).optional(),
+    project_dir: z.string().optional().describe('Absolute path to the project this topic asset belongs to. Without this, the returned path ' +
+        'resolves against the MCP server\'s own working directory or DUCTAPE_PROJECT_DIR, which does ' +
+        'not track which project the current session is working in — pass it whenever working in a ' +
+        'project other than wherever the MCP server happened to start.'),
 });
 const eventsProjectValidationInputSchema = z.object({
-    dir: z.string().default('ductape/events').describe('Must be ductape/events relative to DUCTAPE_PROJECT_DIR.'),
+    dir: z.string().default('ductape/events').describe('Must be ductape/events relative to the resolved project directory.'),
+    project_dir: z.string().optional().describe('Absolute path to the project to validate. Without this, resolution falls back to the MCP ' +
+        'server\'s own working directory or DUCTAPE_PROJECT_DIR, which does not track which project ' +
+        'the current session is working in — pass it whenever working in a project other than ' +
+        'wherever the MCP server happened to start.'),
+});
+const featuresProjectValidationInputSchema = z.object({
+    project_dir: z.string().describe('Absolute path to the linked Ductape project containing ductape/features/. The validator is read-only.'),
 });
 const readOnlyLocalAnnotations = {
     readOnlyHint: true,
@@ -1914,6 +1937,16 @@ SECURITY
   $Secret{tag}; manifests never embed credentials. Keep snd/stg/prd values separate.
   Use ductape_cli("secrets-import-env --env-file <local-file> --source-key <ENV_KEY> --key <secret-tag> --env <slug> --json").
   The command reads the value locally and redacts it from output; never place the value in an MCP argument.
+  Before running that import for any discovered .env-backed secret candidate, ask the user
+  explicitly whether to create a Ductape Secret from it — never decide silently either way (not
+  "migrate everything found" and not "leave .env alone"). Once a value is migrated, update the
+  consuming code to read it through Ductape rather than the environment: NestJS code uses the
+  @Secret() decorator from @ductape/nestjs (see ductape_docs({ topic: "secrets" }) for the DI
+  pattern); every other runtime calls secrets.fetch(key) (ductape_execute("secrets.fetch", [key]))
+  instead of process.env / os.Getenv / System.getenv / IConfiguration for that value. Only remove
+  the .env entry after the new code path is verified working, and never do this for bootstrap
+  config Ductape itself needs to start (DUCTAPE_ACCESS_KEY, DUCTAPE_REDIS_URL, NODE_ENV) — those
+  necessarily stay in the environment.
   secret_references are names-only navigation evidence from Docker Compose, Kubernetes secretKeyRef,
   GitHub/GitLab/Jenkins, Spring, .NET configuration, Terraform, and AWS/GCP/Azure secret managers.
   Their value is always [NOT_READ]. Inspect context before deciding whether a reference is sensitive,
@@ -2022,7 +2055,9 @@ COMPONENT DECISIONS
   represents a reusable product capability.
 
 LANGUAGE RUNTIME SHAPES
-  TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, and request-scoped context.
+  TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, request-scoped context,
+  and @Secret() (DuctapeSecretsModule.register({ keys })) for any secret value instead of .env/
+  ConfigService — see ductape_docs({ topic: "secrets" }).
   Go: explicit services, context.Context, cancellation, typed errors, and owned worker shutdown.
   Java: DI/Spring integration where present, executor ownership, CompletableFuture boundaries.
   .NET: DI, hosted services, async/await, CancellationToken, configuration binding.
@@ -2904,7 +2939,7 @@ 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?, masterPassword? }
+  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName?, masterPassword?, username? }
   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
@@ -2917,9 +2952,17 @@ Import an existing resource and register it on the product:
   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.
+  master password. Atlas (atlas-cluster) does NOT need masterPassword — Ductape mints/rotates
+  its own database user via the Atlas Admin API.
+
+  username (aura-instance only) defaults to "neo4j" if omitted — that IS the correct value for
+  most Aura instances. But this default is NOT a hard guarantee: at least one real Aura instance
+  has been confirmed to authenticate with a different database username instead (its instance id,
+  in the one case observed) and rejects "neo4j" as unauthorized. If a fresh Aura import connects
+  successfully but then fails at runtime with a Neo4j "unauthorized"/access-denied error despite a
+  correct password, don't assume the password is wrong — try re-importing with username set
+  explicitly (ask the user what database username the instance actually uses) before concluding
+  the password itself is bad.
 
 Provision a brand-new resource and register it:
   ductape_cli("cloud resources provision-persist-all -f all-envs.json --json")
@@ -3074,6 +3117,47 @@ Important:
   - Other services (storage, broker, graph, etc.) resolve $Secret{} references automatically
     using the singleton secrets service — no manual resolution needed in most cases.
   - Never log or return resolved secret values to end users.
+
+APPLICATION CODE — PREFER DUCTAPE SECRETS OVER .env / process.env:
+  Once a workspace secret exists for a value, application code should read it through Ductape,
+  not through the process environment or a framework config layer backed by .env. This applies
+  to values the code reads for its own runtime use (API keys, DB passwords, webhook signing
+  secrets, etc.) — it does not apply to non-secret bootstrap config Ductape itself needs to start
+  (DUCTAPE_ACCESS_KEY, DUCTAPE_REDIS_URL, NODE_ENV), which necessarily stay in the environment.
+
+  NestJS: inject with the @Secret() decorator from @ductape/nestjs instead of ConfigService.get()
+  or process.env for any value that is (or should be) a Ductape secret:
+    import { DuctapeSecretsModule, Secret, SecretHandle } from '@ductape/nestjs';
+
+    @Module({ imports: [DuctapeSecretsModule.register({ keys: ['STRIPE_API_KEY'] })] })
+    class PaymentsModule {}
+
+    @Injectable()
+    class PaymentsService {
+      constructor(@Secret('STRIPE_API_KEY') private readonly stripeKey: SecretHandle) {}
+      // this.stripeKey.value holds the decrypted secret
+    }
+  Register every key the module needs via DuctapeSecretsModule.register({ keys: [...] }); each
+  registered key becomes an injectable token resolved through DuctapeContextService, not read
+  from process.env at any point.
+
+  Other runtimes (plain Node/Express/Fastify, Go, Java, .NET, etc.): call
+  ductape_execute("secrets.fetch", ["KEY"]) (or the SDK's secrets.fetch(key) directly in
+  application code) rather than reading process.env / os.Getenv / System.getenv / IConfiguration
+  for a value that is a Ductape secret. Resolve $Secret{KEY} references in config the same way —
+  through the secrets service, never by pre-substituting from the environment.
+
+  MIGRATING EXISTING .env SECRETS: when environment/codebase discovery (see ENVIRONMENTS and
+  SECURITY sections of the migrate-codebase guidance) finds .env entries that look like secrets
+  (API keys, passwords, tokens, connection strings with embedded credentials), do not silently
+  decide either way. Ask the user explicitly whether to create Ductape Secrets from those .env
+  entries — do not assume "yes, migrate everything" or "no, leave .env alone". If the user agrees,
+  import each value locally and specifically:
+    ductape_cli("secrets-import-env --env-file <local-file> --source-key <ENV_KEY> --key <secret-tag> --env <slug> --json")
+  then update application code to read the new secret through @Secret()/secrets.fetch() as above,
+  and only remove the .env entry once that code path is verified working. Never read the .env
+  value into MCP context or an MCP argument while doing this: the CLI command above reads the
+  local file directly and redacts the value from its own output.
 `.trim(),
     apps: `
 DUCTAPE APPS
@@ -4289,8 +4373,11 @@ STEP 6 — WRITE the feature into the project codebase
        exiting. Ductape cannot run this step for you generically — a Feature handler is real
        application code that typically depends on the app's own services, unlike a migration file,
        which is declarative data the Ductape backend can apply directly.
-    4. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
-       finds the linked project and runs its "features:sync" script — never automatically on boot.
+    4. Run ductape_features_validate_project({ project_dir: "<absolute-project-root>" }). This is a
+       read-only AST conformance gate. Stop on any diagnostic; do not sync or mutate remote state.
+    5. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
+       repeats the fail-closed validator, then finds the linked project and runs its "features:sync"
+       script — never automatically on boot.
        Pass an optional filter argument to scope it: "ductape features sync payments".
 
   A NestJS service with both concerns split looks like:
@@ -4322,7 +4409,8 @@ STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
     6. Direct Date.now() and Math.random() are forbidden in handlers. Use ctx.transform.now(),
        ctx.transform.uuid(), and ctx.transform.concat/replace/substring/upper/lower/trim so values
        are generated at execution time. Use a portable Function for domain-specific generators.
-    7. Never use branchOverrides in newly generated code. It exists only to migrate old handlers.
+    7. Never use branchOverrides or recordScenarios in newly generated code. Existing handlers must
+       set controlFlowMode: "legacy" explicitly while they are being migrated.
 
   Prefer explicit portable branching for step results:
     const result = await ctx.step("find", () => ctx.database.execute(...));
@@ -5924,8 +6012,8 @@ const eventsTopicSetupHandler = async (args) => {
     return {
         content: [{ type: 'text', text: JSON.stringify({
                     ok: true,
-                    project_root: cliCwd(),
-                    path: join(cliCwd(), relativePath),
+                    project_root: cliCwd(args.project_dir),
+                    path: join(cliCwd(args.project_dir), relativePath),
                     relative_path: relativePath,
                     definition,
                     create_command: `ductape events topics create -f ${relativePath} --json`,
@@ -5946,7 +6034,14 @@ const eventsProjectValidationHandler = async (args) => {
             isError: true,
         };
     }
-    const result = runCli('events topics validate --dir ductape/events --json');
+    const result = runCli('events topics validate --dir ductape/events --json', args.project_dir);
+    return {
+        content: [{ type: 'text', text: result.output || '(no output)' }],
+        ...(result.success ? {} : { isError: true }),
+    };
+};
+const featuresProjectValidationHandler = async (args) => {
+    const result = runCli('features validate --json', args.project_dir);
     return {
         content: [{ type: 'text', text: result.output || '(no output)' }],
         ...(result.success ? {} : { isError: true }),
@@ -5965,13 +6060,22 @@ const cliInputSchema = z.object({
         '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 under ductape/features/. Persist them with ' +
+        'application code with features.define under ductape/features/. Always run "features validate" first; ' +
+        'it performs read-only AST conformance checks and "features sync" repeats the same fail-closed preflight. Persist them with ' +
         '"features sync" (runs the project\'s own "features:sync" npm script) — never call ' +
         'features.define from the app\'s normal startup path, since that blocks every boot on ' +
         'Ductape API reachability. See ductape_docs for the full convention.\n\n' +
         'The CLI uses the user\'s local logged-in session. Prefer browser OAuth in a trusted local terminal: ' +
         'ductape login --browser google (or github). It returns automatically through a validated loopback callback. ' +
         'Never invoke interactive login through MCP or ask the user for credentials.'),
+    project_dir: z.string().optional().describe('Absolute path to the project this command should run against (e.g. "ductape/events" is ' +
+        'resolved relative to this directory, and product/project linking state is read from it). ' +
+        'The MCP server is a long-running process — its own working directory (or a static ' +
+        'DUCTAPE_PROJECT_DIR env var, if set) does NOT follow which project the current conversation ' +
+        'is actually working in. Pass this whenever the command is project-relative (events topics, ' +
+        'anything reading ductape/ files, link/unlink) and the session is working in a project other ' +
+        'than wherever the MCP server happened to start. Omit only for purely workspace-level commands ' +
+        '(e.g. "products list") where no project directory is relevant.'),
 });
 async function loadMcpSdk() {
     try {
@@ -6116,7 +6220,7 @@ async function main() {
         ],
     }));
     const cliHandler = async (args) => {
-        const cli = checkCli();
+        const cli = checkCli(args.project_dir);
         if (!cli.available) {
             return {
                 content: [{
@@ -6165,7 +6269,7 @@ async function main() {
             // The user may complete `ductape login` in another terminal while this MCP process remains
             // alive; caching "none" would otherwise make the MCP blind to the newly written session.
             if (authState === 'unknown' || authState === 'none') {
-                checkLoginState();
+                checkLoginState(args.project_dir);
             }
             if (authState === 'none') {
                 const wsFlag = process.env.DUCTAPE_WORKSPACE ? ` --workspace "${process.env.DUCTAPE_WORKSPACE}"` : '';
@@ -6193,10 +6297,10 @@ async function main() {
             }
             // Sync to the configured workspace once per process (best-effort)
             if (!workspaceSynced) {
-                syncWorkspace();
+                syncWorkspace(args.project_dir);
             }
         }
-        const result = runCli(args.command);
+        const result = runCli(args.command, args.project_dir);
         // Update cached state after auth commands
         if (firstWord === 'login' && result.success) {
             authState = 'ok';
@@ -6786,6 +6890,14 @@ async function main() {
             inputSchema: eventsProjectValidationInputSchema,
             annotations: readOnlyLocalAnnotations,
         }, eventsProjectValidationHandler);
+        server.registerTool('ductape_features_validate_project', {
+            title: 'Validate Ductape Feature Project',
+            description: 'Read-only AST validation of code-first Features under ductape/features/. Detects native branching, loops, ' +
+                'collection callbacks, host-bound time/random/environment access, and legacy recording options before sync. ' +
+                'A failed result means features sync must not be run.',
+            inputSchema: featuresProjectValidationInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, featuresProjectValidationHandler);
         server.registerTool('ductape_function_setup', {
             title: 'Ductape Portable Function Setup',
             description: 'Read-only: generate (without applying) the mandatory secure local + remote runtime setup for application functions used by Features. ' +
@@ -6971,8 +7083,14 @@ async function main() {
                 '    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' +
+                '    naming exactly this.\n' +
+                '    username defaults to "neo4j" if omitted, which is correct for most Aura instances — but this\n' +
+                '    is NOT a hard guarantee. At least one real instance has been confirmed to use a different\n' +
+                '    database username instead (its instance id, in the one case observed) and rejects "neo4j" as\n' +
+                '    unauthorized. If the import succeeds but connect later fails with a Neo4j\n' +
+                '    unauthorized/access-denied error despite a correct password, re-import with username set\n' +
+                '    explicitly (ask the user what database username the instance actually uses) rather than\n' +
+                '    assuming the password is wrong.\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' +
@@ -6983,7 +7101,9 @@ async function main() {
                 '      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' +
+                '        Step 1), masterPassword (the instance password — ask the user, do not guess or omit),\n' +
+                '        username (optional — omit for the "neo4j" default; only set if the user tells you the\n' +
+                '        instance uses a different one, or if a prior attempt with "neo4j" failed to authenticate).\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' +
@@ -7027,6 +7147,7 @@ async function main() {
         server.tool('ductape_events_discover', eventsDiscoveryInputSchema.shape, eventsDiscoveryHandler);
         server.tool('ductape_events_topic_setup', eventsTopicSetupInputSchema.shape, readOnlyLocalAnnotations, eventsTopicSetupHandler);
         server.tool('ductape_events_validate_project', eventsProjectValidationInputSchema.shape, readOnlyLocalAnnotations, eventsProjectValidationHandler);
+        server.tool('ductape_features_validate_project', featuresProjectValidationInputSchema.shape, readOnlyLocalAnnotations, featuresProjectValidationHandler);
         server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupAnnotations, portableFunctionSetupHandler);
         server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);

package/package.json

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