@ductape/mcp 0.1.60 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.2.0 - 2026-07-26
+
+- Added exhaustive AI-led migration guidance for TypeScript, Go, Java, and .NET.
+- Added original E2E gates, contextual review, semantic database and frontend guidance, and strict verification matrices.
+- Added dependency-aware large-repository guidance.
+- Reinforced the administrative CLI/runtime execute boundary and access-key isolation.

package/README.md

@@ -1,5 +1,10 @@
 # Ductape MCP Server
 
+Migration guidance is available from `ductape_docs({ topic: "migration" })`. It starts with an original E2E
+baseline, defaults to a separate new codebase, requires contextual review and strict parity evidence, and ends
+against the unchanged original E2E suite. Administrative work uses `ductape_cli`; `ductape_execute` remains
+publishable-key runtime-only. MCP never accepts or forwards `DUCTAPE_ACCESS_KEY`.
+
 MCP (Model Context Protocol) server that exposes **Ductape SDK** operations as tools. All calls go through the **Ductape backend proxy** at a fixed URL; the SDK never runs in the MCP process. It is completely stateless; you provide your **Publishable Key** per execution.
 
 ## Prerequisites

package/dist/index.js

@@ -946,7 +946,7 @@ const payloadGenerateInputSchema = z.object({
     execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe('Actor intent for this runtime operation. "user" means an active request initiated by the authenticated user; ' +
         '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
         'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'),
-    include_cache: z.boolean().optional().default(true).describe('Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'),
+    include_cache: z.boolean().optional().describe('Include a cache tag inside the generated payload. Defaults to false; set true only when the runtime call should use cache explicitly.'),
     schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe('"strict" — fail if any required field cannot be resolved. ' +
         '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'),
     input_hint: z.record(z.any()).optional().describe('Optional. Partial input values you already know. These are merged into the generated payload template ' +
@@ -1135,14 +1135,28 @@ const ADMIN_SUBCOMMANDS = [
     'events',
     'cloud',
     'secrets',
+    'secrets-import-env',
     'generate',
     'apply',
     'db',
     'graph',
+    'migrate-codebase',
+    'migration-review',
+    'migration-slice',
+    'migration-portfolio',
+    'migration-database',
+    'migration-environments',
+    'migration-products',
+    'migration-secrets',
 ];
 function checkCli() {
     try {
-        const out = execSync('ductape --version', { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const out = execSync('ductape --version', {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
+        }).trim();
         return { available: true, version: out || 'unknown' };
     }
     catch {
@@ -1158,6 +1172,7 @@ function checkLoginState() {
             encoding: 'utf8',
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
         });
         authState = 'ok';
         return 'ok';
@@ -1173,7 +1188,12 @@ function syncWorkspace() {
     if (!target)
         return;
     try {
-        execSync(`ductape workspaces use "${target}"`, { encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+        execSync(`ductape workspaces use "${target}"`, {
+            encoding: 'utf8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
+        });
     }
     catch {
         // best-effort; if it fails the user will see workspace-mismatch errors on subsequent commands
@@ -1200,6 +1220,7 @@ function runCli(command) {
             // instead of this wrapper killing the CLI first and reducing it to "(no data)".
             timeout: 90000,
             stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
         });
         return { success: true, output: output.trim() };
     }
@@ -1243,13 +1264,431 @@ function runCli(command) {
         return { success: false, output: msg };
     }
 }
+/**
+ * MCP is publishable-key-only. The standalone CLI may manage its own access-key
+ * credentials, but an access key present in the MCP host environment is never
+ * forwarded into CLI subprocesses.
+ */
+function cliEnvironment() {
+    const environment = { ...process.env };
+    delete environment.DUCTAPE_ACCESS_KEY;
+    return environment;
+}
+function shellArgument(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-        'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue'),
+        'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
+});
+const migrationInputSchema = z.object({
+    source: z.string().describe('Absolute path to the existing codebase.'),
+    e2e_baseline: z.string().describe('Absolute path to a passing migration-e2e baseline manifest created before migration inspection.'),
+    mode: z.enum(['in-place', 'new-codebase']).default('new-codebase').describe('Selects where advisory guidance is written. It never generates or rewrites application code.'),
+    destination: z.string().optional().describe('Required destination path for new-codebase mode.'),
+    product: z.string().optional().describe('Ductape product tag; defaults to a slug of the source directory name.'),
+    name: z.string().optional().describe('Product display name.'),
+    database: z.string().optional().describe('Target database tag recorded for the AI review; no schema is generated.'),
+    max_file_bytes: z.number().int().positive().optional().default(2_000_000),
+    include: z.array(z.string()).optional().default([]).describe('Repository-relative glob patterns to include.'),
+    exclude: z.array(z.string()).optional().default([]).describe('Repository-relative glob patterns to exclude with audit evidence.'),
+    ensure_product: z.boolean().optional().default(false).describe('Create the product through the standalone authenticated CLI when it does not exist.'),
+    write: z.boolean().optional().default(false).describe('Write redacted advisory artifacts only. This never writes application code or executable Ductape assets.'),
 });
 const DOCS = {
+    migration: `
+DUCTAPE CODEBASE MIGRATION GUIDE
+
+NON-NEGOTIABLE AUTOMATION BOUNDARY
+  The scanner is an evidence collector and standards engine, not a code generator or codemod.
+  Scanner findings are evidence, not implementation instructions.
+  It MUST NOT create, rewrite, patch, or mechanically replace application source.
+  It MUST NOT emit executable migrations or authoritative Ductape assets.
+  The scanner does not generate or propose a schema. Schema decisions belong to the contextual AI review.
+  migration-evidence.json is checksummed source evidence, never an executable migration.
+  The AI must inspect relevant source files and installed SDK APIs, explain its design, and then write
+  code through normal editing tools. Builds, tests, rescans, inventory checks, and smoke tests verify it.
+
+SUPPORTED SERVER LANGUAGES
+  TypeScript/Node.js (including NestJS), Go, Java, and .NET.
+  Inspect installed package exports before generating code; language APIs pursue parity but signatures differ.
+
+START
+  1. Inspect the original project and create or complete project-level E2E tests before changing application code.
+     Run them against the original codebase. The AI executes the project test command with normal coding tools;
+     Ductape CLI only records evidence and never executes an arbitrary command.
+     Create a value-free definition containing command, suite_files, and passing baseline status/evidence/environment:
+       ductape_cli("migration-e2e init --source <source> --definition <baseline-definition.json> --output <e2e-baseline.json> --json")
+     The manifest SHA-256 binds every original test/fixture. Preserve it unchanged as the acceptance oracle.
+  2. Call ductape_migration_plan in read-only mode with e2e_baseline set to that passing manifest.
+  3. Present the review queue, inventory, secret NAMES, migration evidence, and low-confidence
+     deterministic hints. Never present a hint as a component decision.
+  4. Use the default new-codebase mode unless the user explicitly selects in-place:
+       in-place      — progressively migrate the existing repository.
+       new-codebase  — place guidance in a separate destination while preserving the source untouched.
+                       It does not generate a new application; the AI creates it deliberately.
+  5. Call again with write=true only after confirming the destination. This writes guidance artifacts only.
+  6. Call with ensure_product=true when product inventory confirms the product is absent.
+
+FINAL E2E ACCEPTANCE GATE
+  End the migration by running the exact original E2E command against the migrated codebase while retaining
+  the original checksum-bound suite. Do not silently edit, delete, skip, quarantine, or weaken baseline tests.
+  Record the passing result in a value-free evidence JSON containing the command, status, evidence,
+  environment, and absolute suite_root of the migrated codebase, then:
+    ductape_cli("migration-e2e final --manifest <e2e-baseline.json> --evidence <final-evidence.json> --json")
+    ductape_cli("migration-e2e validate --manifest <e2e-baseline.json> --strict --json")
+  The final command must exactly equal the baseline command. Every suite file under suite_root must match
+  its original checksum, proving the migrated codebase is tested with the same original tests and fixtures.
+  New migration-specific tests supplement the baseline; they never replace it. A failing original E2E case blocks
+  readiness unless the user explicitly authorizes a product behavior change and the exception is separately audited.
+
+SECURITY
+  Never read secret values into MCP arguments or output. Discovery reports names and locations only.
+  The MCP server accepts publishable keys only and never accepts an access key.
+  Secret values must be imported by the standalone CLI reading local files directly. Assets reference
+  $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.
+  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,
+  environment-specific, shared, or suitable for a Ductape secret; never resolve it through MCP.
+  Classify and reconcile every discovered reference through a value-free artifact:
+    ductape_cli("migration-secrets init --analysis <analysis.json> --definition <secret-map-definition.json> --output <secret-map.json> --json")
+    ductape_cli("migration-secrets validate --file <secret-map.json> --strict --json")
+  Each classification requires environment, service, provider, sensitivity, rotation owner,
+  Ductape secret tag, authenticated inventory action/evidence, and rotation validation/rollback.
+  The validator rejects value, password, credential, private-key, and access-token fields.
+  potential_secret_exposures are low-confidence security-review findings only. They contain source,
+  line, category, and a truncated SHA-256 fingerprint; matched material is always [NOT_RETURNED].
+  Never ask the scanner, CLI, user, or MCP to reveal a finding. Ask the user/security owner to rotate
+  and remediate confirmed exposure through trusted local processes.
+
+ENVIRONMENTS
+  Detect environments from .env variants, deployment files, CI, Docker, Kubernetes, Terraform,
+  framework configuration, and existing database/provider configuration. Normalize common aliases
+  (production→prd, sandbox→snd, staging→stg) but present uncertain mappings for confirmation.
+  Before creating any asset, list product environments and require complete per-environment coverage.
+  Missing environments can be created idempotently through the authenticated standalone CLI:
+    ductape_cli("products environments create <product-tag> -f <environment.json> --json")
+  The JSON requires env_name, description, and a three-character slug. The CLI fetches first, creates only
+  when absent, then fetches again to verify persistence. Update and verify with:
+    ductape_cli("products environments update <product-tag> <slug> -f <patch.json> --json")
+  Export authenticated inventory with ductape_cli("products environments list <product-tag> --json"),
+  save it as evidence, then reconcile locally:
+    ductape_cli("migration-environments --analysis <analysis.json> --inventory <inventory.json> --strict --json")
+  Report matched, missing, extra, and ambiguous normalized aliases. Never guess an ambiguous mapping.
+  Environment mutation is administrative CLI work and must never be routed through ductape_execute.
+
+PRODUCT AND ASSET BOOTSTRAP
+  Product creation is idempotent: fetch by tag, create only when absent, then link the destination.
+  Use ductape_cli for products, apps, resources, cloud connections, secrets, apply, and migrations.
+  Use ductape_execute only for runtime calls with a publishable key.
+  For monorepos, define explicit service ownership, product boundaries, asset environment coverage,
+  and environment promotion evidence:
+    ductape_cli("migration-products init --analysis <analysis.json> --definition <product-map-definition.json> --output <product-map.json> --json")
+    ductape_cli("migration-products validate --file <product-map.json> --strict --json")
+  Every discovered workspace-unit manifest must have exactly one service owner. Each service records
+  its product and target environments. Every required asset records authenticated inventory evidence
+  and configured environments. Every mapped product requires promotion entry conditions, validation,
+  and rollback; never assume repository, service, and product boundaries are identical.
+
+DATABASE SCHEMAS AND MIGRATIONS
+  For every database migration, create a definition containing baseline, data, and cutover sections:
+    ductape_cli("migration-database init --definition <database-definition.json> --output <guidance-dir> --json")
+    ductape_cli("migration-database validate --directory <guidance-dir> --strict --json")
+  Baseline evidence covers code/live/applied schemas, drift, views/triggers/procedures/indexes/constraints,
+  permissions/RLS/encryption, tenancy/sharding/partitioning, provider compatibility, IDs/timezones/collation,
+  and query-performance baselines. Data planning covers transformations, batching, checkpoints, resumability,
+  idempotency, PII/retention, seed data, validation and reconciliation. Cutover uses expand/backfill/
+  dual-compatibility/contract phases with deployment ordering, locks, backup, tested restore, rollback,
+  irreversible-change disclosure, monitoring, reconciliation, and explicit approval.
+  All three artifacts require the same migration_id and database_tag. Baseline schema_snapshots cover
+  code, migration, applied, live, and proposed structures with source-file SHA-256, structure hash,
+  timestamp, and evidence; stale source evidence blocks readiness. structural_comparison must be matched
+  or contain explicit approved differences. Data transformations require versioned source/target field
+  mappings, positive batch/concurrency/memory/timeout limits, and an atomic persistent checkpoint with
+  replay-test evidence. Cutover phases require unique positive order and valid prerequisite IDs.
+  Inventory Prisma, TypeORM, Sequelize, Mongoose, SQL, Flyway, Liquibase, Hibernate/JPA,
+  Entity Framework, golang-migrate, Goose, and other migration/schema sources.
+  The planner only identifies possible schema and migration source files. It does not parse them into
+  a proposed Ductape schema. The AI must inspect models, relations, indexes, constraints, migrations,
+  repository behavior, tests, live/provider semantics, and applied history before proposing or writing
+  ductape/database/schema.json.
+  Existing migrations are recorded in migration-imports.json with order and SHA-256 checksums. Review
+  their intent, then generate portable reversible files under ductape/database/migrations/<db-tag>/.
+  Raw source SQL is never silently executed or wrapped because Ductape migrations deliberately use
+  provider-portable operations and require honest rollback behavior.
+  Preserve applied order, identifiers, indexes, constraints, defaults, nullability, and rollback semantics.
+  Never mark converted migrations applied merely because source files exist. Compare live schema in snd,
+  run db schema generate, inspect the diff, then db migrate --dry-run before applying.
+  Composite/partial/provider-specific indexes remain explicit Ductape migration operations.
+
+THIRD-PARTY APIS
+  Group repeated HTTP calls by stable base host into one reusable Ductape App. Model stable operations as
+  Actions with auth, headers, input mapping, output mapping, retry/timeout policy, and environment-specific
+  base URLs. Prefer OpenAPI/Postman import when available. Do not create one App per call site and do not
+  route internal application services through fake HTTP Apps; use Events for internal boundaries.
+
+COMPONENT DECISIONS
+  Databases/transactions → Ductape Database; brokers/queues → Events; object stores → Storage;
+  SMTP/SMS/push/callbacks → Notifications; Redis/cache → Cache; Neo4j/Neptune/Arango/Memgraph → Graph;
+  Pinecone/Qdrant/Weaviate/OpenSearch → Vector; JWT/session middleware → Sessions.
+  Multi-step durable/scheduled/signal-driven work → code-first Features.
+  Retries, health checks, fallbacks, quotas, circuit breakers → Resilience.
+  Keep deterministic calculations, validation, domain rules, and ordinary synchronous services as code.
+
+LANGUAGE RUNTIME SHAPES
+  TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, and request-scoped context.
+  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.
+
+SESSIONS AND DURABLE ACTORS
+  Immediate user work passes the original full session token. Delayed work must not persist raw JWTs
+  indefinitely; use system context or an approved delegated actor plus immutable non-secret metadata.
+
+ROLLOUT
+  The AI migrates one vertical slice end-to-end, test snd, introduce a feature flag/dual path where safe,
+  verify idempotency, concurrency, retries, duplicate delivery, logs, and rollback, then progressively cut over.
+
+AI EDITING STANDARD
+  Before every edit, inspect the relevant source, dependencies, installed SDK types, configuration, tests,
+  and neighboring architecture. Preserve domain behavior and public contracts unless explicitly authorized.
+  Do not change or invent public or internal interfaces, method signatures, types, DTOs, event schemas,
+  serialized formats, error contracts, or lifecycle contracts unless the user explicitly authorizes that
+  exact change. An SDK mismatch is a finding to report and resolve, not permission to reshape application code.
+  Do not assume functionality from filenames, symbols, patterns, comments, documentation, or scanner hints.
+  Trace the implementation, callers, callees, tests, configuration, persisted data, and runtime effects.
+  If behavior remains unclear, run or add characterization tests and record the uncertainty. Never fabricate
+  behavior, compatibility, defaults, rollback guarantees, idempotency, or provider support.
+  Maintain full functional parity:
+    - accepted inputs, returned outputs, validation, domain results, state changes, external side effects,
+      serialized data, errors, events, and user-visible behavior.
+  Maintain full operational parity:
+    - ordering, timing-sensitive guarantees, concurrency, transactions, retries, duplicate delivery,
+      idempotency, authorization, privacy, observability, performance-sensitive behavior, startup,
+      shutdown, cancellation, recovery, and degraded/failure behavior.
+  Compilation and happy-path tests alone do not demonstrate parity. Use existing tests, characterization
+  tests, contract tests, integration tests, failure injection, and snd smoke tests appropriate to the slice.
+  If parity cannot be demonstrated, stop short of cutover and report the exact unverified behavior.
+  Use Events for internal async boundaries and Apps/Actions for external APIs. Keep deterministic rules in code.
+  Immediate work propagates the full session; durable work uses approved actor metadata or system context.
+  Consumers are idempotent, retry ownership is singular and bounded, and external effects are not duplicated.
+  After each slice: format, build, test, rescan, reconcile assets through ductape_cli, smoke-test in snd,
+  and report unresolved findings. A clean scanner result alone never proves a correct migration.
+
+CONTEXTUAL FILE REVIEW PROTOCOL
+  Use review_queue as a coverage aid. Review relevant files individually, starting with repository
+  instructions, manifests, entrypoints, configuration, dependency injection, tests, and deployment files.
+  For each file record: purpose; imports/dependencies; callers/callees; configuration and secret-name
+  references; interfaces/types/signatures/DTOs/event schemas/serialized contracts; database behavior;
+  events/background work; external APIs; sessions/authorization;
+  cache/storage/notifications/graph/vector use; failure policy; tests/invariants; and follow-up files.
+  Follow wrappers and references until the actual external effect and domain intent are understood.
+  Classify each ledger finding:
+    observed  — directly supported by source/configuration
+    inferred  — likely, but requires more context
+    proposed  — possible Ductape design, not yet approved
+    confirmed — verified through source, installed SDK types, tests, inventory, or user confirmation
+  Do not claim coverage until every relevant queue item is reviewed or excluded with a written reason.
+  Do not read .env secret values into MCP context: record names only and use standalone CLI import.
+
+AUDITABLE REVIEW LEDGER
+  After write=true creates migration-guidance/analysis.json, initialize the ledger:
+    ductape_cli("migration-review init --analysis <path>/analysis.json --json")
+  Record contextual evidence through a validated JSON input file:
+    ductape_cli("migration-review record --ledger <ledger> --file <relative-file> --data <evidence.json> --json")
+  The evidence file may contain purpose, dependencies, follow_up_files, interfaces, findings, and
+  references. Reference kinds are import | caller | callee | implements | event | test | config | schema.
+  Every finding requires location: { start_line, end_line } with positive, ordered source lines.
+  Every finding also requires symbol: { kind, name, qualified_name? } so evidence identifies the
+  affected module/class/interface/function/method/field/route/event/schema rather than only a filename.
+  Internal references must point to reviewed/excluded ledger files before readiness.
+  Add a newly discovered repository file without dropping review coverage:
+    ductape_cli("migration-review follow-up --ledger <ledger> --file <source> --follow-up <target> --json")
+  Record parity with structured validation:
+    ductape_cli("migration-review parity --ledger <ledger> --file <file> --concern interface --status verified --evidence <evidence> --json")
+    ductape_cli("migration-review parity --ledger <ledger> --file <file> --concern functional --status verified --evidence <evidence> --json")
+    ductape_cli("migration-review parity --ledger <ledger> --file <file> --concern operational --status verified --evidence <evidence> --json")
+  For a genuine not-applicable concern, use --status not_applicable --reason <reason>.
+  For each entry the ledger records purpose, dependencies, follow-up files, references, interfaces,
+  findings, exclusion metadata where applicable, and:
+    interface_parity, functional_parity, operational_parity
+  Each parity status is pending | verified | not_applicable.
+  verified requires concrete evidence. not_applicable requires a reason.
+  After completing a file, snapshot the exact reviewed content:
+    ductape_cli("migration-review snapshot --ledger <path>/review-ledger.json --file <relative-file> --json")
+  A later checksum change makes that review stale. Follow-up files must also exist in the ledger;
+  never silently omit a referenced file. Reopen a review explicitly when needed:
+    ductape_cli("migration-review reopen --ledger <ledger> --file <relative-file> --json")
+  Exclude only with a classification and reason:
+    ductape_cli("migration-review exclude --ledger <ledger> --file <file> --classification <type> --reason <reason> --json")
+  Types: generated | vendor | build | snapshot | other. Generated exclusions additionally require
+  --generator and --regeneration-test so generated contracts are not silently ignored.
+  If a reviewed file disappears, validation reports checksum-matched probable_moves without changing
+  history. Accept a verified move only when content is identical:
+    ductape_cli("migration-review move --ledger <ledger> --from <old-file> --to <new-file> --json")
+  A stale file transitively invalidates reviewed entries that reference it through internal references,
+  follow-up files, or finding follow-ups. Re-review the dependency chain before readiness.
+  Every structured ledger mutation uses an exclusive lock, checks the expected revision, appends an
+  actor/tool/version/timestamp operation event, chains it to the previous SHA-256 hash, and binds the
+  newest event to the current ledger-entry state. Never edit review-ledger.json directly after audit
+  events exist: validation treats that as tampering. A concurrent conflict must be retried after re-reading
+  the latest ledger; never overwrite another reviewer.
+  For parallel branches, merge only against an explicit common base:
+    ductape_cli("migration-review merge --base <base.json> --current <current.json> --incoming <incoming.json> --output <merged.json> --json")
+  Non-overlapping file reviews merge into a new ledger; divergent edits to the same file return conflicts
+  and never overwrite either input. For trusted release attestation, sign outside MCP with a protected
+  Ed25519 private-key file and verify using the independently distributed public key:
+    ductape_cli("migration-review sign --ledger <ledger> --private-key <private.pem> --key-id <identity> --json")
+    ductape_cli("migration-review verify-signature --ledger <ledger> --signature <ledger.sig.json> --public-key <public.pem> --json")
+  Never pass private-key contents through MCP or prompts.
+  Check progress without claiming readiness:
+    ductape_cli("migration-review validate --ledger <path>/review-ledger.json --json")
+  Before proposing cutover, require strict validation:
+    ductape_cli("migration-review validate --ledger <path>/review-ledger.json --strict --json")
+  Strict readiness requires no pending or stale files, reasoned exclusions, complete follow-ups,
+  covered internal references, recorded file purpose, and verified or reasoned-not-applicable
+  interface/functional/operational parity.
+
+GENERATED, VENDORED, AND SNAPSHOT CONTRACTS
+  Scanner generated_source_hints are navigation evidence, never permission to ignore a file. Contextually
+  classify every hint and any discovered generated or vendored file in a definition, then:
+    ductape_cli("migration-generated init --analysis <analysis.json> --definition <generated-vendor-definition.json> --json")
+    ductape_cli("migration-generated validate --file <generated-vendor-evidence.json> --strict --json")
+  For generated files record contract_kind (public_api | generated_client | schema | ui_snapshot | internal),
+  owner, generator name/version/command, repository-relative generator inputs, passing clean-workspace
+  regeneration evidence, the regenerated output file, and compatibility_tests. The CLI records SHA-256
+  input/checked-in/regenerated checksums and compares output; it never executes an arbitrary generator command.
+  public_api, generated_client, schema, and ui_snapshot are contracts and require compatibility tests.
+  A clean-regenerated mismatch or changed generator input blocks readiness.
+  For vendored source record upstream source/version/SHA-256 checksum, owner, locally_modified, diff_evidence,
+  and compatibility tests. The validator derives modification from current versus upstream checksum; it rejects
+  a false classification, and locally modified vendor source requires owned diff evidence.
+  Never overwrite or normalize checked-in generated/vendor output to make validation pass. Re-run the real
+  generator in an isolated clean workspace using normal development tools, inspect the diff, and record evidence.
+
+REPOSITORY-WIDE ASSURANCE MATRIX
+  Create a version:1, artifact_kind:"ductape_migration_assurance" JSON artifact and validate it with:
+    ductape_cli("migration-assurance --file <assurance.json> --strict --json")
+  This is an evidence gate, not a test runner. The AI runs the referenced tests with normal development tools.
+  It requires tested session flows from frontend through backend, Events, Features, and scheduled work, including
+  refresh, revocation, logout, account switching, expiry, and actor-audit evidence that is not authorization.
+  It requires Feature duplicate-delivery, signal, compensation, restart, layered retry-budget, fallback, quota,
+  and health-check evidence.
+  Every third_party_calls entry records the inspected wrapper chain and client family (Axios, Fetch, Java, .NET,
+  Go, GraphQL, gRPC, or generated), base URL, auth, headers, timeout, retries, pagination, rate limits, normalized
+  errors, webhook/replay behavior, parity evidence, and tests.
+  Component matrices require:
+    graph — schema, edges, indexes, traversal, reconciliation
+    vector — dimensions, metric, embedding version, metadata schema, batching, quality
+    storage — object keys, metadata, ACL, encryption, retention, multipart, checksums
+    cache — keys, TTL, invalidation, stampede, consistency, fallback
+    notifications — templates, channels, providers, suppression, retry, delivery, privacy
+    analytics — event schema, identity, consent, masking, delivery, dashboard parity
+  Provider migrations require tested resumability evidence.
+  Runtime evidence covers safe procedures for TypeScript, Go, Java, and .NET; request/query/Event/Feature/external
+  effect correlation; trace/log compatibility; load/concurrency/retry/duplicate delivery; lifecycle/restart;
+  redaction; dashboards and alert thresholds.
+  The sdk_matrix requires each supported language's exact package/version, installed capability evidence,
+  equivalent parity tests, lifecycle and error-mapping requirements, examples, anti-patterns, and an explicit
+  block/escalate policy for unsupported capabilities. Never silently emulate a missing SDK capability.
+
+COMPREHENSIVE VERIFICATION MATRIX
+  Record automation that the AI actually ran with normal project tools in a version:1,
+  artifact_kind:"ductape_migration_verification_matrix" file, then:
+    ductape_cli("migration-verification --file <verification-matrix.json> --strict --json")
+  This command validates evidence; it never executes the recorded commands. Every one of 63 requirements
+  must be passed and include tests, structured details, automation tool/command/result/environment, and
+  source citations containing absolute repository, relative file, exact line range, and current SHA-256.
+  A changed or missing cited file invalidates readiness.
+  Categories cover multi-repository summaries/checkpoints/contracts; normalized before/after parity,
+  nondeterminism, test strength, mutation and safe shadow signals; frontend browser/accessibility/visual/
+  performance/security/mobile evidence; complete database modeling, data movement and cutover drills;
+  component asset design/inventory/environment/provider/payload/dependency evidence; and contextual
+  third-party client and App/Action designs.
+  Dependency records require nodes, edges, and an evidenced order. Before/after records require explicit
+  normalization and comparison. Nondeterminism requires named fields and approved differences. Visual,
+  irreversible, and residual-uncertainty decisions require actor, authority, and approval evidence.
+  Never manufacture an automation result or approval to satisfy the matrix. A blocked or failed record
+  remains a blocker and must be reported as residual risk.
+
+DEPENDENCY-AWARE LARGE-REPOSITORY PROPOSAL
+  After contextual references exist in the review ledger, generate a non-authoritative proposal:
+    ductape_cli("migration-portfolio propose --ledger <ledger> --max-bytes <bytes> --max-tokens <tokens> --json")
+  The proposer builds the internal reference graph, condenses strongly connected components so cyclic files
+  stay together, topologically orders dependencies before consumers, and records byte plus ceil(bytes/4)
+  token estimates. An indivisible SCC over either configured limit is marked oversized_scc for human/AI
+  review; it is never split unsafely. The output authority is advisory_only and must be contextually reviewed
+  before it becomes a portfolio definition.
+  Verification-matrix records may declare details.depends_on using category.requirement identifiers. A stale
+  cited dependency transitively invalidates dependent service/package summaries and readiness.
+
+PARITY-GATED MIGRATION SLICES
+  Create a JSON array containing the reviewed repository-relative files for one vertical slice, then:
+    ductape_cli("migration-slice init --ledger <ledger> --tag <tag> --name <name> --files <files.json> --json")
+  Complete the generated slice manifest with:
+    product_boundary, sdk_capabilities,
+    interface_contracts, functional_requirements, operational_requirements,
+    required_assets, tests, failure_tests, runtime_evidence, smoke_checks,
+    cutover_conditions, rollback_conditions, deployment_cutover.
+  Apply those fields through a validated definition JSON file:
+    ductape_cli("migration-slice define --slice <slice.json> --data <definition.json> --json")
+  Each required asset records kind, tag, action (reuse | create | update | blocked), and inventory_evidence.
+  Inventory evidence must come from ductape_cli administrative inventory, never an assumed asset.
+  product_boundary records product_tag, included services, target environments, and repository/inventory
+  evidence. Never assume one repository equals one service or one Ductape product.
+  sdk_capabilities records language, installed package, exact version, capability, and evidence from
+  installed exports/types or version-matched primary documentation. Never assume cross-language parity.
+  runtime_evidence and failure_tests cover behavior static review cannot prove: external effects,
+  transactions, ordering, concurrency, retry/duplicate delivery, startup/shutdown, and degraded behavior.
+  deployment_cutover records the implementation commit, per-environment deployed versions, feature-flag/
+  dual-run/traffic state, explicit no-return points and mitigations, a timed observation window with success
+  thresholds, dashboard/alert evidence, and a passing executed rollback rehearsal. Unrecorded deployment
+  state or an untested rollback blocks strict readiness.
+  Validate during work:
+    ductape_cli("migration-slice validate --slice <slice.json> --json")
+  Gate cutover:
+    ductape_cli("migration-slice validate --slice <slice.json> --strict --json")
+  A slice cannot be ready with stale/unreviewed files, incomplete parity, missing tests/smoke checks,
+  missing failure/runtime evidence, an unproven product boundary or SDK capability, missing cutover or
+  rollback conditions, incomplete asset evidence, or blocked reconciliation.
+
+LARGE CODEBASES AND CONTEXT BOUNDARIES
+  Never load a huge repository into one model context or rely on conversational memory for coverage.
+  Partition reviewed files into bounded, non-overlapping groups with an explicit context_budget,
+  durable summary, and file-checksum provenance. Define partitions, slice paths, and cross-slice contracts:
+    ductape_cli("migration-portfolio init --ledger <ledger> --definition <portfolio-definition.json> --json")
+  The CLI computes provenance checksums; changed files stale the affected partition summary.
+  Validate resumable repository-wide coverage:
+    ductape_cli("migration-portfolio validate --portfolio <portfolio.json> --json")
+  Gate repository cutover:
+    ductape_cli("migration-portfolio validate --portfolio <portfolio.json> --strict --json")
+  Strict portfolio validation requires every ledger file in exactly one partition, current provenance,
+  every slice ready, and evidenced provider/consumer cross-slice contracts. Summaries are navigation
+  aids only; reopen source review whenever provenance becomes stale.
+
+FRONTEND MIGRATION PARITY
+  Mark frontend slices with surfaces: ["frontend"] (or include backend/worker for a mixed slice).
+  Frontend strict readiness requires evidence for routes/navigation, rendered loading/empty/error/success
+  states, forms/validation, accessibility, responsive behavior, browser storage, authentication transitions,
+  SSR/hydration, realtime reconnect/resubscription, analytics/privacy, performance budgets,
+  visual regression, and cross-browser behavior.
+  Inspect installed @ductape/client, @ductape/react, or @ductape/vue exports before editing. Preserve UI
+  contracts and application state semantics; do not replace domain state with analytics. Verify full-session
+  identify/clearSession lifecycle, route pageviews, privacy masking, hidden-state exclusion, trace correlation,
+  unsubscribe/teardown, reconnect duplication, SSR browser boundaries, and accessibility behavior.
+
+PARITY CLAIMS
+  Never promise or report "100% parity" merely because gates pass. The gates require the strongest available
+  evidence and make unverified behavior explicit; arbitrary software cannot receive a mathematical parity
+  guarantee from static review and finite tests. Each slice records before/after evidence from appropriate
+  characterization, contract, golden, side-effect, database-state, event-order, failure-injection,
+  load/concurrency, or safe shadow-comparison checks. Report residual uncertainty honestly.
+`.trim(),
     frontend: `
 DUCTAPE FRONTEND SDK GUIDE
 
@@ -3764,7 +4203,15 @@ async function main() {
         }
         const firstWord = args.command.trim().split(/\s+/)[0];
         const isAuthCommand = firstWord === 'login' || firstWord === 'logout';
-        if (!isAuthCommand) {
+        const isLocalMigrationGuidance = (firstWord === 'migrate-codebase' && !args.command.includes('--ensure-product')) ||
+            firstWord === 'migration-review' ||
+            firstWord === 'migration-slice' ||
+            firstWord === 'migration-portfolio' ||
+            firstWord === 'migration-database' ||
+            firstWord === 'migration-environments' ||
+            firstWord === 'migration-products' ||
+            firstWord === 'migration-secrets';
+        if (!isAuthCommand && !isLocalMigrationGuidance) {
             // Cache successful authentication, but re-check a missing/expired session on every call.
             // 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.
@@ -3814,6 +4261,31 @@ async function main() {
             ...(result.success ? {} : { isError: true }),
         };
     };
+    const migrationHandler = async (args) => {
+        if (args.mode === 'new-codebase' && !args.destination) {
+            return {
+                content: [{ type: 'text', text: 'Error: destination is required for new-codebase mode.' }],
+                isError: true,
+            };
+        }
+        const command = [
+            'migrate-codebase',
+            '--source', shellArgument(args.source),
+            '--e2e-baseline', shellArgument(args.e2e_baseline),
+            '--mode', args.mode,
+            ...(args.destination ? ['--destination', shellArgument(args.destination)] : []),
+            ...(args.product ? ['--product', shellArgument(args.product)] : []),
+            ...(args.name ? ['--name', shellArgument(args.name)] : []),
+            ...(args.database ? ['--database', shellArgument(args.database)] : []),
+            '--max-file-bytes', String(args.max_file_bytes),
+            ...(args.include.length ? ['--include', shellArgument(args.include.join(','))] : []),
+            ...(args.exclude.length ? ['--exclude', shellArgument(args.exclude.join(','))] : []),
+            ...(args.ensure_product ? ['--ensure-product'] : []),
+            ...(args.write ? ['--write'] : []),
+            '--json',
+        ].join(' ');
+        return cliHandler({ command });
+    };
     const executeHandler = async (args) => {
         try {
             const runtimeMutationMethods = {
@@ -3834,7 +4306,8 @@ async function main() {
             }
             const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
             if (!key) {
-                throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
+                throw new Error('Runtime authentication is missing. Set DUCTAPE_PUBLISHABLE_KEY in the MCP server environment ' +
+                    'or pass publishable_key to ductape_execute. The MCP server never accepts access keys.');
             }
             // The TS SDK uses ductape.events.* for broker operations; the backend proxy uses messageBrokers.
             const proxyModule = args.module === 'events' ? 'messageBrokers' : args.module;
@@ -3857,7 +4330,18 @@ async function main() {
                     return p;
                 });
             }
-            const result = await executeViaProxy(key, proxyModule, args.method, params);
+            let result;
+            try {
+                result = await executeViaProxy(key, proxyModule, args.method, params);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/authentication failed|unauthorized|invalid.*key/i.test(message)) {
+                    throw new Error('The DUCTAPE_PUBLISHABLE_KEY was rejected by the runtime proxy. ' +
+                        'Use a publishable key for the same workspace/product. The MCP server never accepts or forwards access keys.');
+                }
+                throw error;
+            }
             return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
         }
         catch (err) {
@@ -3989,9 +4473,18 @@ async function main() {
                 'index strategy, operation types) that should be confirmed with the user first.\n\n' +
                 'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
                 'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-                'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
+                'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
+        server.registerTool('ductape_migration_plan', {
+            title: 'Ductape AI Migration Guidance',
+            description: 'Inspect a TypeScript, Go, Java, or .NET repository without exposing secret values. ' +
+                'Builds a relevant-file review queue, secret-name inventory, checksummed migration evidence, and low-confidence navigation hints. ' +
+                'The AI must review files contextually and maintain an evidence ledger before proposing components or schemas. ' +
+                'It never generates or rewrites application code or executable assets. ' +
+                'Supports in-place and new-codebase guidance destinations. Read-only unless write or ensure_product is explicitly enabled.',
+            inputSchema: migrationInputSchema,
+        }, migrationHandler);
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +
@@ -4101,6 +4594,7 @@ async function main() {
         server.tool('ductape_generate_snippet', snippetGenerateInputSchema.shape, snippetGenerateHandler);
         server.tool('ductape_schema', schemaInputSchema.shape, schemaHandler);
         server.tool('ductape_docs', docsInputSchema.shape, docsHandler);
+        server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }
     else {