Skip to content

feat(blocks): register dashboard as an app task - #1472

Open
bobbor wants to merge 1 commit into
mainfrom
bobbor/feat/dashboard-cli-command
Open

bobbor wants to merge 1 commit into
mainfrom
bobbor/feat/dashboard-cli-command

Conversation

@bobbor

@bobbor bobbor commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

What

Registers dashboard as an app task, and gives the default template the dashboard and dashboard:doctor scripts that make it reachable.

Rebased onto #1610, which replaced the cdk-blocks bin with @aws-blocks/blocks/run task scripts. That was not a textual rebase: every user-facing string here named the removed bin, and templates-parity.test.ts detected template commands by the literal cdk-blocks, so under #1610 it would have passed while asserting nothing. Details in the last section.

#843 shipped the Blocks Admin UI and core's dashboard() entry point, but nothing could call it: no CLI command, no template script. .changeset/dashboard-command.md already describes blocks dashboard and an npm run dashboard script, so the released docs promise a command that does not exist. This closes that gap.

Commands

Command Behaviour
npm run dashboard Serves the Admin UI for the app it is run from and opens it. Long-running, like npm run dev.
npm run dashboard:doctor Prints a diagnosis instead of starting the server.

Flags on the command itself: --port, --no-open, and a repeatable --allow-origin.

--profile and --region are the CLI's own global flags and already reach the child as AWS_PROFILE / AWS_REGION, and the project root is the one the CLI resolves, so core's --project and its private copies of profile/region are deliberately not re-exposed.

Notes for review

  • The subcommand travels in argv. Core parses the dashboard's flags from DashboardOptions.argv and takes serve/doctor as a leading positional, so the runner passes argv: [] or argv: ['doctor']. It must be explicit: the runner's real argv holds the options JSON and --telemetry-file, which are not dashboard flags, and core would otherwise read them as one.
  • --output json is refused for both tasks by the existing rule (--output json is not supported for "npm run dashboard": it prints text only.), since neither has a structured result. The doctor's machine-readable report exists in core but is not wired through; happy to add it if you want it in this PR.
  • Both entries are aws: true. Corrected after review: an earlier version of this description claimed the flag "makes the CLI demand an AWS_REGION", which is wrong. In context.ts it gates only the shape check on an inherited AWS_REGION and the warning that --profile blanks exported access keys; it never requires a Region. The dashboard reads credentials and deployed stages, so it wants both.
  • migrate: a prerelease "dashboard": "blocks dashboard" script is renamed like the others (RENAMED_ALIASES). migrate still adds no dashboard script to an app that has none, which is how config already behaves, and the parity test's omit list records that.
  • parsePort is exported from config.ts instead of duplicating port validation for --port.

New guard

templates-parity.test.ts holds every task script in every create-blocks-app template to a command the runner actually registers. That is the check that was missing here, and it fails on exactly this class of drift.

It keys on the @aws-blocks/blocks/run import rather than on the invocation's exact spelling, and asserts that its own detection still matches something: a guard that silently selects no scripts asserts nothing, which is precisely what #1610 would have done to the previous version. Mutation-checked by pointing RUNNER_ENTRY at a name no template uses, which fails the vacuity assertion.

Verification

  • npm run build, lint, lint:deps, check:api, check:exports-consistency, check:client-user-agent, check:packed-assets, check:runtime-guard, sync-docs:check: all pass.
  • 4 changeset-guard commands, keywords-guard verify-discovery-tag, sink guards 35/35: all pass.
  • npm run test:unit: 12835 tests, 12822 pass. The 3 remaining failures are bb-agent's Bedrock user-agent cases failing on CredentialsProviderError with no credentials in the environment; packages/bb-agent is untouched here.
  • migrate.test.ts 57/57.
  • Both new tests were mutation-checked: making the runner always pass argv: [] fails the doctor test, and pointing the template script at a command that does not exist fails the parity test.

Not verified: the dashboard was not started end to end from the CLI on this branch, since that needs @aws-blocks/admin-ui installed in a scaffolded app. The tests assert the spawn, its options and its lifetime, not a live browser session.

Rebase onto #1610

#1610 deleted the cdk-blocks bin (packages/blocks/package.json now exposes only blocks-generate-client and blocks-vendorize, plus a ./run export). Converted here:

  • Every registry example, the operation: strings, the --output json refusal, the runner docstring, the README rows and the changeset now name npm run <task>.
  • dashboard doctor needed a TASK_NAMES entry in errors.ts, following feat(blocks)!: run app tasks through package scripts instead of cdk-blocks #1610's convention for a two-word command (dev stop -> dev:stop). Without it, blocksCommand('dashboard', 'doctor') renders npm run dashboard doctor, which npm passes to the dashboard script as an argument. This was unverified until a mutation test showed removing the entry changed nothing, so the --output json test now asserts both messages and both Try: lines.
  • migrate needed a second alias. RENAMED_ALIASES gained cdk-blocks dashboard doctor as well: main's own round-trip test rewrites each template script into the prerelease blocks <cmd> form and asserts migrate restores it, and blocks dashboard doctor was not being renamed. That was caught by main's test, not predicted.
  • Main's help.test.ts hardcodes the runnable task list, so both tasks were added to it; root help lists them under Develop after dev:stop.
  • The template gains dashboard:doctor as well, and migrate.test.ts's omit list covers both, since migrate adds neither to an app that has none (as with config).

@bobbor
bobbor requested a review from a team as a code owner November 12, 2026 12:34
@changeset-bot

changeset-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 139c681

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages
Name Type
@aws-blocks/blocks Minor
@aws-blocks/create-blocks-app Minor
@aws-blocks/core Minor
@aws-blocks/bb-logger Patch
@aws-blocks/bb-kv-store Patch
@aws-blocks/auth-common Patch
@aws-blocks/bb-app-setting Patch
@aws-blocks/bb-secret Patch
@aws-blocks/bb-database Patch
@aws-blocks/bb-auth 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-file-bucket 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

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

@bobbor
bobbor requested a review from xyos November 18, 2026 15:14
@bobbor
bobbor dismissed soberm’s stale review November 18, 2026 15:19

Dismissed by the repository admin (phandpau) because soberm is out of office and all six findings from this review are fixed, answered and verified at the current head.

This review was submitted against 01042d7; the head is now db07a0b, which rebased onto main ac4d4a1 and addressed every item: the README command table and the --output json note, both registry entries marked aws: true (soberm was right that the flag never demands a Region, and the PR body has been corrected), the corrected mutating-routes and /api wording, --allow-origin validation with a canonical pass-through, the isRunnable prefix-fallback guard with a negative case, and the split of the two pending dashboard changesets.

Each thread carries an individual reply naming what changed, and the four new behaviours are mutation-checked. Nothing here is unanswered; the dismissal is about soberm being unavailable to re-review, not about setting the findings aside. Review is still sought from xyos.

The dashboard shipped as a core function with no caller: it was documented in a
changeset and in core, but no task and no template script could run it.

- `npm run dashboard` serves the Admin UI for the app it is run from, as a
  long-running child like the dev server, and `npm run dashboard:doctor` prints
  a diagnosis instead. Both go through a runner, so they use the app's own tsx
  like every other lifecycle command.
- The runner passes core's flags in `DashboardOptions.argv`, because the
  runner's real argv carries the options JSON and `--telemetry-file`, which are
  not dashboard flags. The subcommand travels there too: core reads it as a
  leading positional.
- `--port`, `--no-open` and a repeatable `--allow-origin` are the task's own
  options. `--profile` and `--region` are the runner's globals, which already
  reach the child as AWS_PROFILE and AWS_REGION, and the project root is the one
  the runner resolved, so core's `--project` is not re-exposed.
- `--allow-origin` is checked here and passed on as a canonical origin. The
  dashboard compares against parsed origins and drops what it cannot parse, so
  `*`, a bare hostname or a value with a path would otherwise trust nothing
  silently and leave a proxied dashboard failing its mutation guard with no
  hint why.
- Both entries are `aws: true`: the dashboard reads credentials and the stages
  the app has deployed, so it wants the inherited-AWS_REGION check and the
  warning that `--profile` blanks exported access keys.
- Neither task has a structured result, so `--output json` is refused for both
  by the existing rule; the doctor's JSON report is not wired through.
- A run that may not prompt (no TTY, `--no-input` or `CI`) spawns the runner
  with stdin ignored, so core's offer to install @aws-blocks/admin-ui takes its
  non-TTY branch and reports the manual install instead of waiting for an
  answer nobody can give. The runner cannot enforce that in a child otherwise:
  core decides by its own `process.stdin.isTTY`, which inherited stdio reports
  as a terminal.
- Ctrl-C at that prompt exits 130 rather than 1. readline in raw mode rejects
  with an `AbortError` instead of raising SIGINT, so the runner maps that to
  the `operatorSignal` path `fail.ts` already turns into the documented
  interruption code.
- `dashboard doctor` gets a `TASK_NAMES` entry, so every message naming it says
  `npm run dashboard:doctor`. Without it the rendering is `npm run dashboard
  doctor`, which npm passes to the `dashboard` script as an argument.
- The default template gains `dashboard` and `dashboard:doctor`, and migrate
  renames a prerelease `blocks dashboard[ doctor]` script the way it renames
  the others. migrate adds no dashboard script to an app that has none, as with
  `config`.

A new test holds every template's task script to a command the runner
registers, so a script cannot again promise a command that does not exist. It
keys on the `@aws-blocks/blocks/run` import rather than the invocation's exact
spelling, and asserts its own detection still matches: a guard that silently
selects no scripts asserts nothing, which is the failure this file exists to
prevent. Its prefix fallback only shortens to a command that can take the
leftover tokens, so a misspelled subcommand (`sandbox deplyo`) fails the guard
rather than passing it and then exiting `unknown command`.

The still-unreleased core changeset is narrowed to core's `dashboard()` script
API, so the next changelog does not carry two conflicting descriptions of one
feature.

`parsePort` is exported from config.ts rather than duplicated for `--port`.
@bobbor
bobbor force-pushed the bobbor/feat/dashboard-cli-command branch from db07a0b to 139c681 Compare November 18, 2026 16:44
@bobbor bobbor changed the title feat(blocks): register dashboard in the cdk-blocks CLI feat(blocks): register dashboard as an app task Nov 18, 2026

This branch was previously deployed

2 inactive deployments
e2e — 139c681f Deployed Nov 18, 2026 by bobbor via E2E Teardown Verify #7144
agent-bench — 139c681f Deployed Nov 18, 2026 by bobbor via bench / summary #6223
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.

3 participants