Skip to content

feat(blocks)!: run app tasks through package scripts instead of cdk-blocks - #1610

Merged
xyos merged 3 commits into
aws:mainfrom
xyos:feat/package-manager-tasks
Nov 18, 2026
Merged

xyos merged 3 commits into
aws:mainfrom
xyos:feat/package-manager-tasks

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Applications already use package scripts. They should not need a second command to run their backend or read its documentation.

Changes

  • Remove the cdk-blocks bin. Scripts import the package-owned @aws-blocks/blocks/run bootstrap; there are no new launcher files in generated apps. Preserve closed-pipe handling and core-version diagnostics.
  • Support npm run docs Auth.protect, npm run docs:api KVStore and npm run docs:search "partition key". Structured tasks return text on a terminal and JSON on redirected stdout. With npm use npm run -s to keep its banner out of pipelines. Explicit --output and --query still work.
  • Update the app and contributor AGENTS files, templates, overlays, runtime guidance, pending release notes, native examples, and CI consumers. Migration recognizes generated wrappers and exact legacy task strings without replacing customized scripts.

Breaking / maintainer review: scripts calling the executable must migrate. Piped structured results now default to JSON (including docs); pass --output text to capture the former text. Other specialist binaries and @aws-blocks/blocks/scripts are not removed. This PR supersedes #1516 (closed). Deploy scripts keep automatic JSON on redirected stdout; callers that need the text completion marker can request --output text.

Validation

  • At dc7cacb2c after rebasing: both touched packages compiled independently and 168 focused tests passed, including redirected deploy output and piped migration refusals. The project-reference typecheck also attempted packages/bb-auth and failed in src/types-test.ts on auth options. The full suite was not rerun at this head. Earlier results below.
  • npm run test:e2e:local: 576 passed, 0 failed across five suites.
  • Build, lint, and undeclared dependency checks passed on Linux/Node 22. The 186 focused entry, docs, help, parser and migration tests passed; so did all 434 scaffold tests and the regenerated imports-reference check.
  • Checked member lookup on a pseudo-terminal, quiet JSON pipelines with npm, pnpm and Bun, quoted search, API lookup and explicit Markdown on a pipe.
  • Full local verification is not clean yet: watcher tests encountered EMFILE and a watcher timeout. The task lifecycle suite passed all 46 tests with polling; the hosting watcher suite passed on its own. Windows not run locally. No sandbox deployment.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: dc7cacb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 24 packages
Name Type
@aws-blocks/create-blocks-app Minor
@aws-blocks/blocks Minor
@aws-blocks/bb-auth Patch
@aws-blocks/auth-common Patch
@aws-blocks/bb-database Minor
@aws-blocks/core Minor
@aws-blocks/bb-app-setting Patch
@aws-blocks/bb-file-bucket Patch
@aws-blocks/admin-ui Patch
@aws-blocks/bb-logger Patch
@aws-blocks/bb-kv-store Patch
@aws-blocks/bb-secret Patch
@aws-blocks/bb-realtime Patch
@aws-blocks/bb-async-job Patch
@aws-blocks/bb-dashboard Patch
@aws-blocks/bb-cron-job Patch
@aws-blocks/bb-agent Patch
@aws-blocks/bb-knowledge-base Patch
@aws-blocks/bb-email-client Patch
@aws-blocks/bb-tracer Patch
@aws-blocks/bb-metrics Patch
@aws-blocks/bb-lambda-compute Patch
@aws-blocks/bb-container-compute Patch
@aws-blocks/bb-compute Patch

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@xyos
xyos marked this pull request as ready for review November 18, 2026 11:13
@xyos
xyos requested a review from a team as a code owner November 18, 2026 11:13
@xyos
xyos force-pushed the feat/package-manager-tasks branch from a6ef9f3 to 0b65ab4 Compare November 18, 2026 13:16
Comment thread packages/blocks/package.json Resolved
Comment thread packages/blocks/src/cli/context.ts Resolved
xyos added 3 commits November 18, 2026 14:54
…locks

Expose the package-owned bootstrap without installing a lifecycle binary or scaffolding launcher files.
Use terminal text and piped JSON for structured tasks, update scaffolded and existing apps, and document npm argument forwarding and quiet pipelines.
@xyos
xyos force-pushed the feat/package-manager-tasks branch from 0b65ab4 to dc7cacb Compare November 18, 2026 14:57
@xyos
xyos merged commit e1e4844 into aws:main Nov 18, 2026
75 of 76 checks passed
bobbor added a commit that referenced this pull request Nov 18, 2026
…dk-blocks

Every published package moves from the `@aws-blocks` scope to `@aws-cdk-blocks`.
The umbrella drops its scope entirely: `@aws-blocks/blocks` becomes
`aws-cdk-blocks`. A package's name is also its import specifier and its
dependency key here, so the rename reaches the manifests, ~1500 import
specifiers (dist embeds them, so a consumer of `@aws-cdk-blocks/core` would
otherwise hit an `@aws-blocks/hosting` import for a package it never installed)
and the pending changesets (`changeset publish` matches frontmatter names
against package.json and aborts on a mismatch).

The unscoped umbrella is the part that needed real changes rather than a
substitution. Tooling that selected this monorepo's packages with
`startsWith('@aws-blocks/')` silently stopped seeing the umbrella, and code that
composed `@aws-blocks/` + a folder name produced the dead `@aws-cdk-blocks/blocks`:

  - publish:local dropped the umbrella from the local registry entirely.
  - changeset-guard's frontmatter regex could not match an unscoped entry, so it
    green-lit a release that `changeset publish` aborts.
  - create-blocks-app left `"aws-cdk-blocks": "*"` unstamped in scaffolded apps,
    and package-name-to-directory inference broke (`aws-cdk-blocks` is in
    `packages/blocks`). Shared `isBlocksPackage` / `blocksPackageDir` helpers now
    carry both rules.
  - admin-ui block discovery no longer recognised a block imported from the
    umbrella.
  - create-block built its contributor-mode scope from a bare 'aws-blocks'
    literal, which an `@`-anchored sweep does not touch.
  - cdk-blocks docs: `packageOf` composed the dead `@aws-cdk-blocks/blocks`, and
    the entry filter stripped the scope and the legacy `blocks/` prefix but not
    the umbrella's own name, so `docs aws-cdk-blocks/ui` found nothing.
  - doc-snippets and the docs externals filter classified an umbrella import as
    third-party, because the scope test they inherited had matched
    `@aws-blocks/blocks`.
  - Five test guards forbidding the `cdk-blocks` BINARY matched the new PACKAGE
    name as well: `-` is a non-word character, so `\bcdk-blocks\b` matches inside
    `aws-cdk-blocks`. They now use a `(?<![\w-])` lookbehind, verified to still
    catch `cdk-blocks dev` and to pass `aws-cdk-blocks/run`.
  - Three fixtures installed the umbrella at `node_modules/@aws-cdk-blocks/blocks`
    while the runner resolves the unscoped name.

Local registries now route by npm's DEFAULT registry rather than by scope. npm
resolves a registry per scope, so a `@aws-cdk-blocks:registry=` line cannot route
an unscoped name: verified directly, npm asks registry.npmjs.org for
`aws-cdk-blocks` while a scoped sibling goes to the local server. Every harness
that installs a scaffolded app would have fetched the umbrella from public npm.
Pointing the default registry at the local one requires it to answer for
third-party packages too, so both local registries split by name: this repo's own
packages are served from the published tree or 404, NEVER forwarded (a released
copy of the same name would silently replace the working tree's, which is the
substitution assertLocalRegistry exists to catch), and everything else is
forwarded to registry.npmjs.org. An unreachable upstream is a 502, not a 404.
The routing decision is a pure function in scripts/publish/local-registry.ts,
beside the existing resolver, so it is unit tested. Both listeners bind
127.0.0.1. This also fixed two harbor-bench defects: provenance.py filtered the
lockfile to scoped names with exactly one slash while requiring `aws-cdk-blocks`
to be among those checked, so that assertion could never pass, and registry.mjs
served only `/registry/@aws-cdk-blocks/`, so the umbrella's own tarball 404ed
while sitting on disk.

Names that are historical facts are deliberately untouched, because they record
what was actually published or shipped:

  - The `@aws-blocks/bb-auth-basic`, `-cognito` and `-oidc` packages only ever
    existed under the old scope. They are what `bb-auth migrate` looks for in a
    user's code and what the upgrade-in-place base ref tags are named.
  - packages/blocks/test-fixtures/migrate-apps.json holds snapshots of apps older
    templates really generated, matched by SHA-256 of their content.
  - The CHANGELOG.md files record releases made under the old names.
  - The `aws-blocks` keyword, the `aws-blocks` manifest key carrying the `native`
    and `vendorize` declarations, and the `aws-blocks/` backend directory in
    scaffolded apps, so third-party blocks keep working without a republish.

Rebased from ddae815 onto e1e4844, 49 upstream commits. They added ~980 new
`@aws-blocks/*` references, deleted bb-data, bb-distributed-data and data-common
(which the changeset no longer names, leaving 27 packages), and moved app tasks
onto package scripts (#1610), which is what the binary-name guards above belong to.

Verified: npm install, build:force (0 TS errors), the full unit suite, lint:deps,
check:exports-consistency, sync-docs:check, check:imports,
check:client-user-agent, check:runtime-guard, check:packed-assets, check:api
(API.md regenerated), keywords-guard, all four changeset-guard commands, their
unit tests (45 + 11), the local-registry tests (33) and harbor-bench's python
suite. Against a control build of unmodified main at the same SHA the failure
sets differ by nothing: 24 on the branch, all 24 present on main (a local sandbox
artifact, mise shims node while the tests redirect HOME); the control has 2 more
from port contention. biome reports the same 9 warnings and 5 infos on both sides
and no errors. The suite was run from a wiped build after a stale dist of
upstream-deleted test files produced 20 phantom failures.

Not verified: test:templates, canary and harbor-bench, each of which needs a full
publish and scaffold run.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants