Repository navigation
Conversation
🦋 Changeset detectedLatest commit: 2d05db1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-core
branch
2 times, most recently
from
November 18, 2026 22:39
e3af571 to
77074e8
Compare
The production CORS subsection said every allowedOrigins entry is a regex, that an invalid regex falls back to a literal match, and that https://app.example.com also matches https://appXexample.com. A plain origin is matched exactly and an invalid entry fails synth (src/cors.ts); the subsection now says so and links to the allowedOrigins rules above it. The Pipeline pointer links to the pipeline README.
…T.md More than half of the core README (983 of 1,884 lines) was the platform's side of running many apps in one AWS account: three IAM policies in full, the pipeline, the project template and adopting defaults.appIdentity in an existing app. That text moves verbatim into SHARED-ACCOUNT.md, added to the package's files; only its heading levels change. The README section keeps what each app sets (defaults.appIdentity, defaults.permissionsBoundary, the reserved ids, the IAM report) and links to the file. readme-policies.test.ts reads the JSON policies from the new file; JSDoc and comments that named the README section for the policies name the file.
…orrect port and params rules The README said only the backend and amplify templates serve the API on :3001, that -32602 is reserved, that a null params gives no arguments, that the shared gateway's RPC URL is the ApiUrl stack output, and that IAM report statements have a conditions field. It now says blocks.dev.port sets the port (3001 in the five templates without a frontend and in the amplify overlay), that params which is present and is neither an array nor an object, null included, fails with -32602 (src/rpc.ts), that ApiUrl is publicApiUrl (src/cdk/index.ts), and that the field is condition (src/cdk/iam-report.ts). A new section, BlocksStack and BlocksBackend, documents create(), its props, the properties of the result and every defaults option with its value in both presets (src/cdk/blocks-defaults.ts); the file opens with a table of entry points, and Scope, ApiNamespace and withAuth open with their signatures. The Key Exports wrapper is removed, so each export is its own level-two section, and withAuth moves next to the other exports. The two RPC paths are stated once under Calling the API over HTTP, and rules that were single paragraphs (resend, runtime config, WAF, request checks, allowedOrigins, service-principal trust, the IAM report's violations) are lists or tables. The per-door settings matrix, build retention and plain-HTTP details under Hosting are replaced by a link to the hosting README, which holds them.
…d; long rules become lists The per-service table said AWS::BedrockAgentCore::Runtime is not scoped, while the text below it and the boundary's OwnTaggedResources statement scope runtimes by the app tag. The row now says tag, with the runtimes' workload identities as an accepted exception, and the adoption section's list of tag-scoped types includes AgentCore runtimes. The boundary's statement groups, the five tag statements, the API Gateway tagging rules, the AgentCore rules, the bootstrap-template steps, the pipeline's two commands and adoption step 4 are lists instead of single paragraphs. Acronym glosses and repeated statements are removed; the Limits item still says runtime API calls are outside the isolation. No JSON policy block, shell command or heading changes.
The first sentence of the core README changed ("with the AWS Blocks" became "with AWS Blocks"); `npm run sync-docs` copies it into the catalog table.
xyos
force-pushed
the
docs/readme-core
branch
from
November 19, 2026 06:11
77074e8 to
030a626
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
packages/core/README.mdwas 1,886 lines and 18,737 words, with 93 prose lines over 400 characters, andnpm run docs coreprints all of it.allowedOriginsentry is a regex and an invalid one falls back to a literal match, that only thebackendandamplifytemplates serve the API on:3001, that-32602is reserved, and that anullparamsgives no arguments.BlocksStack.create()and thedefaults.*options were used in every example and documented nowhere in the file.Issue #, if available:
Changes
Four commits, in this order.
1.
bd027bf9dProductionallowedOriginsrules (README). A plain origin is matched exactly and an invalid entry fails synth (packages/core/src/cors.ts:343-383). The Pipeline pointer links to the pipeline README.2.
c024d9d0bMove of the platform guide. 983 lines move verbatim from the README into the newpackages/core/SHARED-ACCOUNT.md; only the six heading levels change. The README section keeps what each app sets and links to the file. Also in this commit:packages/core/package.json:SHARED-ACCOUNT.mdadded tofiles.packages/core/src/cdk/readme-policies.test.ts: the test that parses every JSON policy block and checks each full policy against IAM's managed-policy limit of 6,144 characters now readsSHARED-ACCOUNT.mdinstead of a slice of the README.packages/core/src/cdk/blocks-defaults.ts(permissionsBoundary,appIdentity) and comments inapp-isolation-rules.tsandtest-apps/comprehensive/test/app-identity-synth.test.tsname the file instead of the README section.3.
packages/core/README.md. Corrections:blocks.dev.portsets it; 3000 by default (packages/core/src/scripts/dev-server.ts:1036), 3001 inapi-only,backend,cron,observability,sql(packages/create-blocks-app/templates/*/package.json) and theamplifyoverlay (packages/create-blocks-app/src/index.ts:952).-32602is returned whenparamsis present and is neither an array nor an object,nullincluded (packages/core/src/rpc.ts:248-258,rpc.test.ts:422-441).-32603is not used (rpc.ts:87is its only occurrence).ApiUrloutput;ApiUrlispublicApiUrl(packages/core/src/cdk/index.ts:173-192).condition, notconditions(packages/core/src/cdk/iam-report.ts:16-24).blocks-defaults.ts:319-347,rpc.ts:239-246).Added, each derived from the source: a table of entry points (
package.jsonexports);## BlocksStack and BlocksBackendwithcreate()props (src/common/index.ts:623-700), result properties (src/cdk/index.ts:108-192) and all 13defaults.*options with both preset values (src/cdk/blocks-defaults.ts:41-487); signatures and option tables forScope,ApiNamespace,isBlocksErrorandwithAuth; anapiWafsubsection (src/cdk/api-waf.ts:31-77).Structure: the
## Key Exportswrapper is removed and each export is a##section;withAuthmoves to afterRawRoute. Long rule paragraphs are lists; the IAM report's violations are a table.Removed: the per-door settings matrix, build retention and plain-HTTP details under
Hosting(inpackages/hosting/README.md, linked); curl examples (innpm run docs troubleshooting); the partial list of Building Block packages (npm run docs); a sentence about a future release; design rationale.4.
packages/core/SHARED-ACCOUNT.md. One correction: the per-service table saidAWS::BedrockAgentCore::Runtimeis "not scoped"; the text below it and the boundary'sOwnTaggedResourcesstatement scope it by tag. The row and the adoption list of tag-scoped types now say so. Otherwise wording only: long paragraphs become lists, acronym glosses and repeated statements are removed. No JSON policy block, shell command or heading changes.A further commit regenerates the block catalog in
packages/blocks/README.md(npm run sync-docs): the first sentence of the core README changed from "with the AWS Blocks" to "with AWS Blocks", and the catalog row copies it.packages/core/README.mdpackages/core/SHARED-ACCOUNT.md(new)The two files together are about as long as the README was. What changes is what
npm run docs coreprints: 11,807 words instead of 18,737.Look hardest at:
SHARED-ACCOUNT.md: a public doc comment changed.defaults.*table and both preset columns againstpackages/core/src/cdk/blocks-defaults.ts.## Key Exports: the heading outline changes, and with it whatnpm run docs core -- --section <topic>matches.paramsstatements.Not changed on purpose:
BlocksStack,BlocksBackendandBlocksPresetsare shown from@aws-blocks/blocks/cdkandHostingfrom@aws-blocks/core/cdk, as before.packages/core/src/common/index.tsstill says a future release will reject afullIdcollision.Open questions:
defaults.*table belong here or in the@aws-blocks/blocksguide?BLOCKS_SKIP_FRONTEND_BUILD,HostingPresetsandnpm run sandbox:previeware documented only in the core README, not in the hosting README. Which is their home?packages/blocks/TROUBLESHOOTING.mdsays every namespace is served atPOST /aws-blocks/api; underapiFrontDoor: 'cloudfront'andstrictNamespacePlacementthat is not the whole rule.SHARED-ACCOUNT.mdhas no execution-policy JSON for AgentCore runtimes, only prose; the "tag" row was checked against that prose and the boundary JSON.SHARED-ACCOUNT.mdstill says LambdaVpcConfigand RDS subnet groups "very likely have the same gap (not yet verified)". Someone who can test it should state it either way.Carried from
main: the directory rename to.cdk-blocks-sandbox(#1644) is applied to the revised text: nine lines ofpackages/core/README.md, including the heading "Runtime config (/.cdk-blocks-sandbox/config.json)".Related pull requests: supersedes the core part of #1496 (the CORS correction and the Pipeline pointer, taken over unchanged as
bd027bf9d). Open pull requests that also touchpackages/core/README.md: #726, #1197, #1402, #1405, #1615. Whichever merges second rebases.Part of a set of README revisions: #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.
Validation
Run on this branch alone at
030a62658, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.Files other than Markdown in this pull request:
packages/core/package.json,packages/core/src/cdk/app-isolation-rules.ts,packages/core/src/cdk/blocks-defaults.ts,packages/core/src/cdk/readme-policies.test.ts,test-apps/comprehensive/test/app-identity-synth.test.ts.Tests changed:
packages/core/src/cdk/readme-policies.test.ts,test-apps/comprehensive/test/app-identity-synth.test.ts. No test was added: the tests listed above already read these files.Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.