@jaypie/mcp 0.8.156 → 0.8.158

package/dist/suites/docs/index.js

@@ -13,7 +13,7 @@ import { RELEASE_NOTES_HELP } from './help.js';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.156#2f9f851b"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.158#55ed6fbc"
     ;
 // =============================================================================
 // ASSET PATHS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.156",
+  "version": "0.8.158",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.85.md

@@ -0,0 +1,22 @@
+---
+version: 1.2.85
+date: 2026-09-13
+summary: Per-build tags skip DynamoDB tables so migration-owned indexes survive redeploys
+---
+
+## Changes
+
+- **`constructTagger`** adds `buildDate`, `buildHex`, `buildTime`, `commit`, and
+  `version` with `excludeResourceTypes` for `AWS::DynamoDB::GlobalTable` and
+  `AWS::DynamoDB::Table`. These tags changed every synth, forcing a table update
+  on every deploy. A table whose GSIs a migration created rejects that update
+  with `Invalid AttributeDefinitions`, so every deploy after the first rolled
+  back (#548).
+- **`JaypieInfrastructureStack`** applies the same exclusion to `stackSha`.
+
+## Upgrade
+
+Tables deployed with earlier versions carry the build tags. The first deploy on
+this version removes them, which is a table update. A table with no
+migration-owned indexes updates normally. A table with migration-owned indexes
+fails that update: recreate the table or declare its indexes in CDK.

package/release-notes/constructs/1.2.86.md

@@ -0,0 +1,42 @@
+---
+version: 1.2.86
+date: 2026-09-13
+summary: CDK owns DynamoDB indexes; external secrets and SSOSync secret props keep credentials out of templates
+---
+
+## Changes
+
+- **`JaypieMigration`** grants `DescribeTable`, `DescribeTimeToLive`, and
+  `DescribeContinuousBackups` only. `UpdateTable`, `UpdateTimeToLive`, and
+  `UpdateContinuousBackups` are removed: a GSI a migration creates blocks every
+  later CloudFormation update to the table (#552).
+- **`JaypieMigration`** warns at synth when a `JaypieDynamoDb` in `tables`
+  declares no `indexes`. Acknowledge
+  `@jaypie/constructs:migrationTableWithoutIndexes` for tables that need none.
+- **`JaypieDynamoDb`** sorts `indexes` by name, so
+  `indexes: getAllRegisteredIndexes()` synthesizes the same template regardless
+  of import order, and exposes the sorted list as `indexes`.
+- **`constructTagger`** and **`JaypieInfrastructureStack`** apply per-build tags
+  to DynamoDB tables again, reverting 1.2.85.
+- **`JaypieSecret`** and **`JaypieEnvSecret`** accept `external: true`, which
+  creates an empty secret whose value never enters the template, assets
+  bucket, `cdk.out`, or `cdk diff`. An `ExternalArn` output described by the
+  `envKey` locates the secret for CI `put-secret-value` (#551).
+- **`JaypieSsoSyncApplication`** accepts `googleCredentialsSecret` and
+  `scimEndpointAccessTokenSecret` and deploys SSOSync as "App only" with six
+  secret ARNs in `CrossStackConfig`. Literal credentials still work and warn
+  at synth (`@jaypie/constructs:ssoSyncLiteralCredentials`).
+
+## Upgrade
+
+- Declare every registered index in `JaypieDynamoDb` `indexes`.
+- A table with GSIs created outside CDK fails the first deploy on this version,
+  because build tags update the table. CloudFormation cannot adopt those
+  indexes: declare them and recreate the table. See `skill("dynamodb")`.
+- Migrations that call `UpdateTable`, `UpdateTimeToLive`, or
+  `UpdateContinuousBackups` fail with `AccessDenied`. Move those settings into
+  `JaypieDynamoDb`.
+- Add indexes to an existing table one per deploy.
+- Moving `JaypieSsoSyncApplication` to secret props deletes the SAR-created
+  `SSOSync*` secrets. Sync fails until CI writes the new secret values. See
+  `skill("secrets")`.

package/release-notes/mcp/0.8.157.md

@@ -0,0 +1,13 @@
+---
+version: 0.8.157
+date: 2026-09-13
+summary: Document that tables with migration-owned indexes need stable CloudFormation properties
+---
+
+## Changes
+
+- **`dynamodb`** adds "Keep Table Properties Stable": any CloudFormation update
+  to a table fails once a migration creates a GSI.
+- **`migrations`** notes migration-owned index behavior and recovery for stacks
+  deployed before `@jaypie/constructs` 1.2.85.
+- **`cdk`** notes that per-build tags skip DynamoDB tables (#548).

package/release-notes/mcp/0.8.158.md

@@ -0,0 +1,19 @@
+---
+version: 0.8.158
+date: 2026-09-13
+summary: Indexes belong in CDK; external secrets keep credentials out of templates
+---
+
+## Changes
+
+- **`dynamodb`** replaces "Keep Table Properties Stable" with "Share Indexes
+  Between CDK and Runtime" (`indexes: getAllRegisteredIndexes()`) and "Indexes
+  Created Outside CDK" (failure and recovery). Local Development creates the
+  table with `createTable()` from the registry and runs the migration seed,
+  replacing the AWS CLI script that created no GSIs (#552).
+- **`migrations`** documents describe-only grants, the synth warning for tables
+  without indexes, and a seed module shared by the migration and local scripts.
+- **`cdk`** removes the note that per-build tags skip DynamoDB tables.
+- **`secrets`** adds External Secrets (`external: true` with a CI
+  `put-secret-value` step) and SSOSync Credentials, and notes that env-sourced
+  values are written into the template (#551).

package/skills/cdk.md

@@ -131,7 +131,7 @@ workspaces/
    `cdk-{PROJECT_SPONSOR}-{PROJECT_KEY}-{PROJECT_ENV}-{PROJECT_NONCE}[-{key}]`,
    so naming stays consistent across sandbox, personal, and production deploys.
 2. **Account & region** resolved from `CDK_DEFAULT_ACCOUNT` / `CDK_DEFAULT_REGION` (overridable via `env`).
-3. **Standard tags** applied to the stack and propagated to every taggable child resource: `env`, `project`, `sponsor`, `nonce`, `commit`, `buildHex`, `buildDate`, `buildTime`, `version`, `service`, `creation`, `role`, `stack`.
+3. **Standard tags** applied to the stack and propagated to every taggable child resource: `env`, `project`, `sponsor`, `nonce`, `commit`, `buildHex`, `buildDate`, `buildTime`, `version`, `service`, `creation`, `role`, `stack`. Per-build tags update every table on every deploy, so a table must declare its indexes in CDK (see `skill("dynamodb")`).
 
 ```typescript
 import { Construct } from "constructs";
@@ -235,7 +235,7 @@ const handler = new JaypieLambda(this, "ApiHandler", {
 | 1 table | `grantReadWriteData()` plus `Query`/`Scan` on `index/*` | `DYNAMODB_TABLE_NAME` set automatically |
 | 2+ tables | `grantReadWriteData()` plus `Query`/`Scan` on `index/*` for each | No auto env var — set `CDK_ENV_TABLE` manually |
 
-CDK grants index ARNs only for indexes declared in CDK. The explicit `index/*` grant covers GSIs created by migrations (`UpdateTable`) and indexes on imported tables.
+The explicit `index/*` grant also covers indexes on imported tables, which CDK does not know about.
 
 Single table example — at runtime, use `process.env.DYNAMODB_TABLE_NAME`:
 

package/skills/dynamodb.md

@@ -270,9 +270,9 @@ const { items: chats } = await queryByScope({ model: "chat", scope: APEX });
 
 GSIs are defined using `fabricIndex()` from `@jaypie/fabric`. **Do not create all GSIs upfront** — start with zero and add only what your access patterns require. The most common first GSI is `indexModel` for listing entities by model.
 
-**Important:** DynamoDB allows only **one GSI to be added per deployment**. If you need multiple GSIs, add them sequentially across separate deploys. For production tables, the AWS CLI is often better suited for adding GSIs than CDK (which may try to replace the table).
+**Indexes belong in CDK.** Declare every registered `fabricIndex()` in `JaypieDynamoDb` `indexes` (see [Share Indexes Between CDK and Runtime](#share-indexes-between-cdk-and-runtime)). A new table is created with all declared GSIs in one deploy. DynamoDB adds only **one GSI per update** to an existing table, so add indexes to a deployed table one per deploy.
 
-**Grants:** CDK adds `${tableArn}/index/*` to grants only for indexes declared in CDK. GSIs created by migrations or the CLI are invisible to CDK, so a role needs `Query` and `Scan` on the index ARN explicitly. `JaypieLambda` and `JaypieMigration` grant this for every table in `tables`; hand-rolled roles must add it.
+**Grants:** `JaypieLambda` and `JaypieMigration` grant `Query` and `Scan` on `${tableArn}/index/*` for every table in `tables`, which also covers indexes on imported tables. Hand-rolled roles must add it.
 
 All GSIs use a composite sort key of `scope#updatedAt` (stored as `{indexName}Sk`). Queries use `begins_with` on the sk to filter by scope; omitting scope lists across all scopes.
 
@@ -474,17 +474,75 @@ const table = new JaypieDynamoDb(this, "myApp", {
 
 Wire tables to Lambda using the `tables` prop — see `skill("cdk")` for details.
 
+### Share Indexes Between CDK and Runtime
+
+The model registry is the single source of indexes. Register models in a module that both the CDK workspace and the runtime import, then pass the registry to the construct:
+
+```typescript
+// packages/models/src/index.ts
+import { fabricIndex, registerModel } from "@jaypie/fabric";
+
+registerModel({ model: "record", indexes: [fabricIndex(), fabricIndex("alias")] });
+registerModel({ model: "session", indexes: [fabricIndex()], ttl: "30 days" });
+```
+
+```typescript
+// workspaces/cdk/lib/data-stack.ts
+import "@project/models"; // registers models
+import { JaypieDynamoDb } from "@jaypie/constructs";
+import { getAllRegisteredIndexes } from "@jaypie/fabric";
+
+const table = new JaypieDynamoDb(this, "myApp", {
+  indexes: getAllRegisteredIndexes(),
+});
+```
+
+`JaypieDynamoDb` sorts indexes by name, so import order does not change the template. The registry is module state: the CDK workspace and the models module must resolve the same `@jaypie/fabric` copy, or `getAllRegisteredIndexes()` returns an empty list.
+
+### Indexes Created Outside CDK
+
+A GSI created through `UpdateTable` (a migration, the console, or the CLI) blocks every later CloudFormation update to the table:
+
+```
+Invalid AttributeDefinitions Expected the following attributes to be present: [indexModel, ...]
+```
+
+CloudFormation sends only the attributes the template declares, and DynamoDB rejects a request that omits attributes an existing index references. Tag, TTL, point-in-time recovery, and billing changes all fail. `JaypieMigration` grants no `UpdateTable` for this reason.
+
+CloudFormation cannot adopt an existing GSI. Recover by declaring the indexes in `JaypieDynamoDb` and recreating the table. Outside production, delete and redeploy the stack. In production, deploy a new CDK-declared table beside the old one, copy items with `scanTable` and `updateEntity` (see [Migration: v0.4.x to v0.5.0](#migration-v04x-to-v050)), and switch `tables` to the new table.
+
 ## Local Development
 
 Use docker-compose for local DynamoDB. The `@jaypie/dynamodb` MCP tool can generate a `docker-compose.yml` with custom ports.
 
+`createTable()` builds the table with every registered GSI, the same indexes CDK declares. Import the models module, create the table, then run the seed the deployed migration runs (see `skill("migrations")`):
+
+```typescript
+// scripts/dynamo-create-table.ts
+import "@project/models"; // registers models
+import { createTable, initClient } from "@jaypie/dynamodb";
+
+import { seed } from "../packages/api/src/migrations/seed/seed.js";
+
+initClient({
+  credentials: { accessKeyId: "local", secretAccessKey: "local" },
+  endpoint: "http://127.0.0.1:9060",
+  tableName: "jaypie-local",
+});
+
+await createTable();
+await seed();
+```
+
+`createTable()` leaves an existing table unchanged and adds no indexes to it. After registering a new index, run `npm run dynamo:remove && npm run dynamo:init` to rebuild the local table.
+
 ### Suggested package.json Scripts
 
 ```json
 {
   "scripts": {
     "dynamo:init": "docker compose up -d && npm run dynamo:create-table",
-    "dynamo:create-table": "AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local aws dynamodb create-table --table-name jaypie-local --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:9060 2>/dev/null || true",
+    "dynamo:create-table": "tsx scripts/dynamo-create-table.ts",
     "dynamo:remove": "docker compose down -v",
     "dynamo:start": "docker compose up -d",
     "dynamo:stop": "docker compose down"

package/skills/migrations.md

@@ -47,25 +47,38 @@ new JaypieMigration(this, "SeedData", {
 - **Role**: Tagged as `CDK.ROLE.PROCESSING`
 - **Execution**: Uses `cr.Provider` with both `onEventHandler` and `isCompleteHandler` pointing to the same Lambda. The `onEventHandler` returns `PhysicalResourceId` immediately; the migration code runs in `isCompleteHandler` invocations, which are polled by Step Functions until `IsComplete: true`. `Delete` requests skip the migration entirely.
 - **Dependencies**: Use `dependencies` to ensure tables and other resources exist before the migration executes
-- **Permissions**: Tables passed via `tables` get data-plane (`grantReadWriteData`), `Query` and `Scan` on `${tableArn}/index/*`, plus control-plane access (`DescribeTable`, `UpdateTable`, `UpdateTimeToLive`, `UpdateContinuousBackups`) scoped to the table ARN and its indexes — migrations that add GSIs, toggle TTL, or change backups work without extra IAM, and later migrations can query the GSIs earlier ones created
+- **Permissions**: Tables passed via `tables` get data-plane (`grantReadWriteData`), `Query` and `Scan` on `${tableArn}/index/*`, plus `DescribeTable`, `DescribeTimeToLive`, and `DescribeContinuousBackups` scoped to the table ARN and its indexes. Migrations read and write data. They do not change table shape
+- **Indexes**: CDK owns indexes, TTL, and backups. Declare every registered `fabricIndex()` in `JaypieDynamoDb` `indexes` (see `skill("dynamodb")`). A GSI created outside CDK blocks every later CloudFormation update to the table, so `JaypieMigration` grants no `UpdateTable`. Synth warns (`@jaypie/constructs:migrationTableWithoutIndexes`) when a `JaypieDynamoDb` in `tables` declares no indexes; acknowledge it for tables that need none
 
 ## Migration Lambda Handler
 
 Use `migrationHandler` from `jaypie` so errors propagate as CFN failures and the waiter protocol is handled automatically.
 
-```typescript
-// src/migrations/seed/index.ts
-import { initClient, seedEntities, APEX } from "@jaypie/dynamodb";
-import { migrationHandler } from "jaypie";
+Keep the seed in its own module so the local table script runs the same seed (see Local Development in `skill("dynamodb")`):
 
-export const handler = migrationHandler(async (event) => {
-  await initClient();
+```typescript
+// src/migrations/seed/seed.ts
+import { APEX, seedEntities } from "@jaypie/dynamodb";
 
-  await seedEntities([
+export async function seed() {
+  return seedEntities([
     { alias: "config-main", model: "config", name: "Main Config", scope: APEX },
     { alias: "vocab-en", model: "vocabulary", name: "English", scope: APEX },
   ]);
+}
+```
 
+```typescript
+// src/migrations/seed/index.ts
+import "@project/models"; // registers models; indexEntity requires them
+import { initClient } from "@jaypie/dynamodb";
+import { migrationHandler } from "jaypie";
+
+import { seed } from "./seed.js";
+
+export const handler = migrationHandler(async () => {
+  await initClient();
+  await seed();
   return { status: "complete" };
 });
 ```

package/skills/secrets.md

@@ -71,7 +71,7 @@ Synth fails fast whenever a declared secret source produces no secret string, so
 ```typescript
 new JaypieSecret(this, "ApiKey", { value: process.env.MISSING }); // throws ConfigurationError
 new JaypieSecret(this, "ApiKey", { envKey: "MISSING" });          // throws ConfigurationError
-new JaypieSecret(this, "Placeholder");                            // allowed: empty secret, no source declared
+new JaypieSecret(this, "Placeholder");                            // allowed: CDK generates a random value
 ```
 
 `JaypieEnvSecret` applies the same guard, except in consumer environments, where the secret is imported rather than created.
@@ -91,6 +91,8 @@ jobs:
       - run: npx cdk deploy
 ```
 
+An env-sourced value is written into the synthesized template. Copies persist in the deployed stack template, the CDK assets bucket, `cdk.out`, and `cdk diff` output. Use [External Secrets](#external-secrets) for credentials that must stay out of those places.
+
 ## Runtime: Retrieving Secrets
 
 Use `getEnvSecret` to fetch secrets in Lambda:
@@ -202,6 +204,66 @@ new JaypieEnvSecret(this, "AdminSeed", {
 
 With `excludePunctuation: true` and `includeSpace: false`, the generated value contains only base62 characters.
 
+## External Secrets
+
+`external: true` creates an empty secret (no `SecretString` or `GenerateSecretString`), so the value never enters the template, the assets bucket, `cdk.out`, or `cdk diff`. CI sets the value after deploy. `envKey` still names the runtime variable (`SECRET_ANTHROPIC_API_KEY`) but is never read at synth. Combining `external` with `value` or `generateSecretString` throws `ConfigurationError`.
+
+```typescript
+const anthropicSecret = new JaypieSecret(this, "ANTHROPIC_API_KEY", {
+  external: true,
+});
+
+new JaypieLambda(this, "Handler", {
+  code: "dist/lambda",
+  handler: "index.handler",
+  secrets: [anthropicSecret],
+});
+```
+
+The construct outputs the secret ARN with the `envKey` (or construct id) as the output description. Set the value in a step after `cdk deploy`, and keep the value out of the deploy step's environment:
+
+```yaml
+- name: Set external secrets
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    STACK_NAME: my-stack
+  run: |
+    ARN=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
+      --query "Stacks[0].Outputs[?Description=='ANTHROPIC_API_KEY'].OutputValue" \
+      --output text)
+    printf '%s' "$ANTHROPIC_API_KEY" > "$RUNNER_TEMP/secret"
+    aws secretsmanager put-secret-value --secret-id "$ARN" \
+      --secret-string "file://$RUNNER_TEMP/secret" > /dev/null
+    rm -f "$RUNNER_TEMP/secret"
+```
+
+- A new external secret has no value until the step runs; `getEnvSecret` fails until then.
+- CloudFormation never writes the value, so a hand-rotated secret is not overwritten by a later deploy.
+- Switching an existing secret to `external` removes `SecretString` from the template. Run the value step in the same workflow.
+- Each `put-secret-value` creates a secret version. Compare with `get-secret-value` first to skip unchanged writes.
+- In `JaypieEnvSecret` consumer environments the secret is imported; set the value on the provider stack.
+
+### SSOSync Credentials
+
+`JaypieSsoSyncApplication` writes `googleCredentials` and `scimEndpointAccessToken` into the template and warns at synth (`@jaypie/constructs:ssoSyncLiteralCredentials`). Pass secrets instead:
+
+```typescript
+new JaypieSsoSyncApplication(this, "SsoSync", {
+  googleCredentialsSecret: new JaypieSecret(this, "SsoSyncGoogleCredentials", {
+    external: true,
+  }),
+  scimEndpointAccessTokenSecret: new JaypieSecret(this, "SsoSyncScimToken", {
+    external: true,
+  }),
+});
+```
+
+- The application deploys SSOSync as "App only". The construct creates secrets for the admin email, SCIM endpoint URL, region, and identity store ID (still read from `CDK_ENV_SSOSYNC_*`), then passes all six ARNs in `CrossStackConfig`.
+- Both secret props are required together, and neither combines with the literal props.
+- Secrets need a complete ARN: created in the stack or imported with `Secret.fromSecretCompleteArn`. SSOSync reads them with the AWS managed key.
+- Switching an existing application from "App + secrets" deletes the SAR-created `SSOSync*` secrets. Sync fails until CI writes the new secret values. Do not name new secrets `SSOSync*`.
+- SSOSync accepts secret ARNs in `us`, `us-gov`, `ap`, `ca`, `cn`, `eu`, and `sa` regions only.
+
 ## Seeds and API Keys in Workflows
 
 Seeds are secrets used to derive deterministic values (like API keys) at runtime. The generated-secret pattern is ideal for seeds because: