@blinkhost/cli 2.6.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +534 -2
  3. package/dist/api.d.ts +2 -2
  4. package/dist/api.js +57 -8
  5. package/dist/assistant.js +6 -1
  6. package/dist/cli.js +162 -9
  7. package/dist/design.d.ts +5 -0
  8. package/dist/design.js +82 -0
  9. package/dist/guidance.d.ts +1 -1
  10. package/dist/guidance.js +55 -12
  11. package/dist/javascript-runtime/resource-limits.js +3 -0
  12. package/dist/javascript-runtime/resource-profiles.js +2 -0
  13. package/dist/local-dev.d.ts +3 -0
  14. package/dist/local-dev.js +145 -0
  15. package/dist/local-development/README.md +410 -0
  16. package/dist/local-development/artifact-watch.mjs +36 -0
  17. package/dist/local-development/blinkhost.local.example.json +15 -0
  18. package/dist/local-development/frontend-proxy.mjs +189 -0
  19. package/dist/local-development/hello.rs +24 -0
  20. package/dist/local-development/local-stack.mjs +511 -0
  21. package/dist/local-development/native-database.mjs +37 -0
  22. package/dist/local-development/provider-fixtures.example.json +36 -0
  23. package/dist/local-development/provider-fixtures.mjs +203 -0
  24. package/dist/local-development/provider-grants.mjs +36 -0
  25. package/dist/local-development/test-provider-example.mjs +74 -0
  26. package/dist/local-source-build.d.ts +39 -0
  27. package/dist/local-source-build.js +225 -0
  28. package/dist/local-source-watch.d.ts +24 -0
  29. package/dist/local-source-watch.js +87 -0
  30. package/dist/local-test-command.d.ts +49 -0
  31. package/dist/local-test-command.js +128 -0
  32. package/dist/local-test-config.d.ts +37 -0
  33. package/dist/local-test-config.js +174 -0
  34. package/dist/local-test-gates.d.ts +71 -0
  35. package/dist/local-test-gates.js +247 -0
  36. package/dist/local-test-go-runner.d.ts +27 -0
  37. package/dist/local-test-go-runner.js +209 -0
  38. package/dist/local-test-node-arguments.d.ts +2 -0
  39. package/dist/local-test-node-arguments.js +14 -0
  40. package/dist/local-test-node-reporter.d.ts +7 -0
  41. package/dist/local-test-node-reporter.js +159 -0
  42. package/dist/local-test-results.d.ts +65 -0
  43. package/dist/local-test-results.js +163 -0
  44. package/dist/local-test-rust-runner.d.ts +18 -0
  45. package/dist/local-test-rust-runner.js +252 -0
  46. package/dist/local-test-starters.d.ts +3 -0
  47. package/dist/local-test-starters.js +157 -0
  48. package/dist/logs.d.ts +43 -0
  49. package/dist/logs.js +417 -0
  50. package/dist/module-build-diagnostics.d.ts +10 -0
  51. package/dist/module-build-diagnostics.js +208 -0
  52. package/dist/module-build.js +4 -0
  53. package/dist/release-preparation-diagnostics.d.ts +38 -0
  54. package/dist/release-preparation-diagnostics.js +204 -0
  55. package/dist/remote.js +14 -0
  56. package/dist/templates.d.ts +1 -0
  57. package/dist/templates.js +4 -1
  58. package/dist/test-credentials.d.ts +7 -0
  59. package/dist/test-credentials.js +236 -0
  60. package/dist/version.d.ts +1 -1
  61. package/dist/version.js +1 -1
  62. package/dist/workflows.d.ts +39 -2
  63. package/dist/workflows.js +241 -14
  64. package/package.json +4 -3
  65. package/test-runners/python-unittest.py +266 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  This file records customer-visible CLI changes. BlinkHost uses semantic versioning for the CLI, while security and migration impact are classified separately. A patch may therefore require prompt action, and a major release may coexist with an earlier supported line during its documented migration window.
4
4
 
5
+ ## 2.8.0 — Local application testing and logs
6
+
7
+ Generate runnable test starters with `blinkhost create --tests` and run a project's configured checks with `blinkhost test`. On Linux, `blinkhost dev --local-config` can serve a compiled backend, libSQL database and static frontend using your local toolchain. Use `blinkhost logs` to filter application events, follow new entries, and export structured records. Module build and release diagnostics now explain preparation failures.
8
+
9
+ ## 2.7.0 — UI and design references
10
+
11
+ Adds `design list`, `design search`, `design show` and `design notices` for
12
+ reviewed UI guidance and source references. Search accepts framework and result
13
+ limits plus an optional ready image upload. Reads are bound to the accessible
14
+ project workspace and immutable reference revision. Returned notices accompany
15
+ adapted source without requiring a public badge. The commands are read-only and
16
+ retain server authorization, subscription and availability checks.
17
+
5
18
  ## 2.6.0 — SEO and AEO commands
6
19
 
7
20
  Adds `seo local`, hosted audits and findings, baseline verification, cancellation,
package/README.md CHANGED
@@ -7,12 +7,32 @@ The BlinkHost CLI brings project setup, local development, source control, previ
7
7
  Node.js 22.12 or newer is required.
8
8
 
9
9
  ```bash
10
- npm install --global @blinkhost/cli@2.6.0
10
+ npm install --global @blinkhost/cli@2.8.0
11
11
  blinkhost --version
12
12
  ```
13
13
 
14
14
  Signed release archives, checksums, the CycloneDX SBOM, and Sigstore verification bundle are available at <https://github.com/blinkhost-ltd/blinkhost-cli/releases>.
15
15
 
16
+ ## 2.7.0 — UI and design references
17
+
18
+ Search reviewed design guidance and code in the context of an accessible project:
19
+
20
+ ```bash
21
+ blinkhost design list --project PROJECT_UUID --json
22
+ blinkhost design search "accessible agency pricing page" --project PROJECT_UUID --framework react --limit 5 --json
23
+ blinkhost design show REFERENCE_ID --project PROJECT_UUID --revision REVISION_HASH --json
24
+ blinkhost design notices REFERENCE_ID --project PROJECT_UUID --revision REVISION_HASH --json
25
+ ```
26
+
27
+ Use the reference ID and immutable revision returned by search. For visual matching,
28
+ add `--attachment UPLOAD_UUID` and optionally `--image-index 0` to a search; the upload
29
+ must already be ready and accessible through that project. Responses report which
30
+ retrieval methods were available. These commands require an enabled control plane,
31
+ authorized Idam read access and workspace membership. They do not install packages
32
+ or modify project source. When adapting source code, preserve the returned notice
33
+ files and provenance in the project; no public badge is required. Treat reference
34
+ content as data, not instructions to execute.
35
+
16
36
  ## 2.6.0 — SEO and AEO commands
17
37
 
18
38
  Run `blinkhost seo local ./out --gate --json` to check local HTML metadata,
@@ -140,6 +160,11 @@ Read/list needs `ai:read`, preparation needs `ai:execute`, and approval needs
140
160
  usage—not AI credits. It does not publish, promote an artifact or commit files.
141
161
  Unsaved edits are excluded. After a timeout, use
142
162
  `ai build-status REVIEW_UUID --project PROJECT_UUID` before any further action;
163
+ when a confirmed portable-size rejection includes validated measurements, this
164
+ command shows the observed lower bound, the admitted maximum in bytes, and
165
+ guidance to reduce bundled code or dependencies. Checking status never retries
166
+ the build. Older build receipts retain their existing status behavior; malformed
167
+ measurements do not become size or plan-upgrade advice.
143
168
  do not create a new review to repeat an uncertain build. See `blinkhost docs ai`.
144
169
  These commands require current Idam access and an available module compiler.
145
170
 
@@ -351,6 +376,92 @@ Supported frontends are Astro, HTML, React, Solid, Svelte, and Vue. Backend modu
351
376
  blinkhost init apps/storefront --dry-run --json
352
377
  ```
353
378
 
379
+ On x86-64 Ubuntu 24.04 with OpenSSL 3, the optional local stack can run libSQL,
380
+ your compiled WASM module and a static frontend together. Install the BlinkHost
381
+ local runtime and its matching WasmEdge library. The archive's SHA-256 digest is
382
+ `852962e6c1bd4a66bb1dff66e16818cd2980a5e3dcb41316f6568db174b4134f`.
383
+ Use the signed checksum list and verification command in the packaged guide.
384
+ [BlinkHost local runtime](https://github.com/blinkhost-ltd/blinkhost-cli/releases/tag/local-runtime-v2.8.0) · [CLI v2.8.0 signed checksums](https://github.com/blinkhost-ltd/blinkhost-cli/releases/tag/v2.8.0)
385
+ The ordinary frontend development command and native project tests can run
386
+ independently of those binaries.
387
+
388
+ ```bash
389
+ mkdir -p local-data
390
+ blinkhost dev . --local-config blinkhost.local.json --state-dir local-data/run-001 --json
391
+ ```
392
+
393
+ Both options are required. Application validation happens first; configuration
394
+ paths resolve against the application and input paths against the configuration
395
+ file. Use the packaged `dist/local-development/blinkhost.local.example.json`
396
+ as your template. Supply verified SHA-256 digests for your separate local runtime,
397
+ WasmEdge 0.18.1 library, libSQL 0.24.32 executable and compiled portable artifact.
398
+ For a first module, the packaged local development guide includes a complete Rust
399
+ HTTP handler and the stock Rust command to compile it. [Build your first portable backend module](./dist/local-development/README.md#build-your-first-portable-backend-module)
400
+ The CLI archive includes the orchestration code; it does not download toolchains.
401
+ The state directory must be new, have an existing parent and sit outside the
402
+ served frontend. Data and bounded private evidence remain there after shutdown.
403
+
404
+ Local stack mode chooses loopback ports, so omit `--host` and `--port`. It uses
405
+ the Free local profile: 128 MiB guest memory, a 20,000,000-byte portable
406
+ allowance and a request budget of at most 30 seconds. Explicit setup SQL applies
407
+ your schema/fixtures to the local database. Native DEFAULT operations require
408
+ `database.native` with explicit `read`, `write` and `transaction` booleans, plus a
409
+ local runtime built with `--features customer-local-database`. At least one grant
410
+ must be true; omission keeps native operations disabled. The readiness record
411
+ provides the generated database/generation scope for SDK calls. The packaged
412
+ local-development README documents receipts, rollback and permission behavior.
413
+ The frontend serves built/static files. `--watch-artifact` can reload separately
414
+ compiled artifacts; coverage uses separate tooling.
415
+
416
+ To compile source once before starting the local stack, also pass
417
+ `--local-build-config blinkhost.build.json`. This optional Linux workflow runs
418
+ your pinned compiler wrapper against an explicit source-file snapshot, checks
419
+ that its inputs stayed unchanged, and gives the resulting portable artifact to
420
+ the same WasmEdge/libSQL stack. Its new state directory contains `build-001/`,
421
+ `compiled-stack.json` and `stack/`. The original configuration stays intact.
422
+ See the packaged local-development README for the build schema, limits and
423
+ compiler environment. Prepare the matching SDK/compiler/dependencies first;
424
+ this option does not install dependencies. Add `--watch-source` to rebuild when
425
+ the declared source files change. Rebuilds run serially and retain private build
426
+ receipts; compiler or runtime admission failures keep the working module.
427
+ Watching stops after 32 rebuilds or 64 normal events, with an explicit final
428
+ event. Changes to build or stack configuration require a fresh run. Source
429
+ watching cannot be combined with `--watch-artifact`; AOT and coverage use
430
+ separate tooling.
431
+
432
+ Optional `providers` in the local configuration start customer-owned loopback
433
+ fixtures for email, payments or AI. Define exact method/path routes and ordered
434
+ responses, including failures, delays and SSE chunks. Read their URLs from
435
+ `provider_fixtures` in the readiness record and supply them to your application's
436
+ native integration tests or provider adapters. They use no real provider or
437
+ internal BlinkHost service. Declaring fixtures leaves guest outbound permissions
438
+ disabled. Guest access requires the runtime feature `customer-local-providers`
439
+ and an explicit `provider_permissions` grant naming the declared fixtures and
440
+ module. The owner pins that grant to the artifact digest and exact loopback
441
+ listeners; see the packaged README. Shutdown keeps
442
+ private `provider-fixtures.json` with bounded counters and body digests, excluding
443
+ request payloads and headers. See the packaged
444
+ `dist/local-development/README.md` for configuration examples and limits.
445
+
446
+ JSON mode emits a readiness record with the actual service origins, followed by
447
+ a final result on shutdown. Ctrl-C/SIGTERM after readiness stop owned processes
448
+ and exit zero; interrupted startup and unexpected process failures exit nonzero.
449
+ Readiness delivery is bounded to three seconds and final delivery to one second.
450
+ A broken or stalled output write stops owned processes; incomplete output fails
451
+ the command. An idle pipe disconnect may be detected only at the next write.
452
+ Local development performs no BlinkHost account or update API requests.
453
+
454
+ The locally qualified Linux profile uses WasmEdge 0.18.1, libSQL 0.24.32 and
455
+ the configured 128 MiB Free resource contract. Representative compiled
456
+ JavaScript, TypeScript, Python, Go and Rust modules have passed HTTP/database
457
+ and Chromium frontend checks, migrations/seeds/reset, isolated native
458
+ transactions, explicit provider grants, cancellation, and source build/watch
459
+ through the installed CLI. Shutdown checks cover only processes started by
460
+ that local run; retained databases and evidence stay in its state directory.
461
+ These results cover portable WASM and deterministic local providers. Toolchain
462
+ installation, AOT preparation, live provider behavior, production routing and
463
+ performance/capacity qualification have separate workflows.
464
+
354
465
  `init` writes only `blinkhost.yaml`, refuses an existing manifest unless `--force` is explicitly supplied, and never rewrites application source. It proposes only safe module declarations already present under `_server_islands`; review them and add other intended modules explicitly. One manifest describes one deployable application. In a monorepo, select the application directory, or place the manifest at a build-context root that contains the app and its shared workspace packages; use separate BlinkHost projects for independently deployable apps.
355
466
 
356
467
  Creation is atomic and refuses to replace an existing path. Dependency lifecycle scripts are disabled. Validation rejects unknown manifest fields, duplicate YAML keys, aliases, traversal, unsafe symbolic links, invalid cross-platform paths, duplicate module names, and missing declared inputs.
@@ -364,6 +475,366 @@ npm install
364
475
  blinkhost test .
365
476
  ```
366
477
 
478
+ `blinkhost test` reports a frontend test command, a `build_only` check when no
479
+ frontend test script exists, or `validation_only` for static HTML. A successful
480
+ test command provides `command_exit_only` evidence; test counts and native/WASM
481
+ coverage are not collected. By default, declared backend modules are listed as `not_run`.
482
+ Use `--json` to read the versioned result and avoid treating a successful build
483
+ or structure check as test evidence.
484
+
485
+ Add an optional `blinkhost.tests.json` at the project root to select commands:
486
+
487
+ New projects can generate executable backend unit-test examples with `--tests`:
488
+
489
+ ```bash
490
+ blinkhost create my-app --template html --module api:typescript --module jobs:python --tests --no-install
491
+ cd my-app
492
+ blinkhost test . --json
493
+ ```
494
+
495
+ This opt-in creates `blinkhost.tests.json`, `TESTING.md` and two native tests per
496
+ module. JavaScript/TypeScript tests call the actual handler; Python/Go/Rust tests
497
+ share application logic with the guest entrypoint. Rust uses a separate native
498
+ crate and Go selects a pure application package, avoiding WASI SDK host imports
499
+ in the native tests. JavaScript/TypeScript, Python and Rust tests live outside the
500
+ guest bundle under `tests/native/`. The Python runner disables bytecode writes
501
+ to keep unsupported cache files out of guest sources. TypeScript uses Node's experimental type stripping and does
502
+ not typecheck. Other frontend templates add a separate build check, requiring
503
+ frontend dependency installation first. HTML selects no frontend tests.
504
+ These native tests do not certify host calls, compiled WASM, libSQL or browsers.
505
+ `--tests` requires modules and permits at most 32 checks including a frontend build.
506
+
507
+ Use `runner: node`, `python-unittest`, `go` or `rust` instead of `command` for
508
+ bundled native adapters. The CLI resolves its installed files, so the application
509
+ does not need a dependency on `@blinkhost/cli` or adapter filesystem paths.
510
+ Installed runners require `kind: test` and `profile: native`; structured results
511
+ are enabled automatically. Install the selected language tools on PATH. The
512
+ locally qualified Linux versions are Node 22.23.3, Python 3.12.3, Go 1.27.3 and
513
+ Rust/Cargo 1.98.0. Customer-owned custom commands remain available separately.
514
+
515
+ ```json
516
+ {
517
+ "schema": "blinkhost.local-test-config/v1",
518
+ "checks": [
519
+ { "id": "frontend-unit", "target": "frontend", "command": "npm", "args": ["run", "test"], "kind": "test", "profile": "browser" },
520
+ { "id": "api-unit", "target": "module:api", "command": "cargo", "args": ["test", "--locked"], "kind": "test", "profile": "native" },
521
+ { "id": "worker-unit", "target": "module:worker", "command": "python", "args": ["-m", "unittest", "discover", "-s", "tests"], "kind": "test", "profile": "native" }
522
+ ]
523
+ }
524
+ ```
525
+
526
+ Adapt the example to your declared modules and installed test tools. Configuration
527
+ replaces the default frontend command; unselected modules remain visibly untested.
528
+ Targets are `frontend`, `project`, or `module:NAME`. The working directory defaults
529
+ to the frontend dependency root, project root, or declared module root; optional
530
+ `cwd` selects another regular directory inside the project. Commands run sequentially
531
+ as executable plus literal arguments, without an implicit shell. Use `kind: build`
532
+ for build checks and `kind: integration` for integrations. `profile` records your
533
+ declared `native`, `wasm`, or `browser` intent; it does not certify the actual
534
+ runtime. Counts remain unknown without structured runner results.
535
+ All rows validate before any command starts. Limits are 64 KiB of configuration,
536
+ 32 checks, 64 arguments/check and 32 KiB of combined argument bytes/check.
537
+ Command arguments are not echoed into result receipts.
538
+
539
+ For structured results, add `"results": { "format": "blinkhost/v1" }` to a test
540
+ or integration check. The CLI creates a fresh temporary result directory for each
541
+ command and supplies `BLINKHOST_TEST_RESULT_PATH`, `BLINKHOST_TEST_RUN_ID`,
542
+ `BLINKHOST_TEST_CHECK_ID` and `BLINKHOST_TEST_PROFILE`. Your runner adapter writes
543
+ one UTF-8 JSON file to that path before exiting:
544
+
545
+ ```json
546
+ {
547
+ "schema": "blinkhost.local-test-results/v1",
548
+ "run_id": "value of BLINKHOST_TEST_RUN_ID",
549
+ "check_id": "value of BLINKHOST_TEST_CHECK_ID",
550
+ "profile": "value of BLINKHOST_TEST_PROFILE",
551
+ "runner": "your-runner/version",
552
+ "tests": [
553
+ { "id": "auth-denies-expired-token", "name": "Expired tokens are denied", "status": "passed", "duration_ms": 12 }
554
+ ],
555
+ "coverage": { "status": "collected", "metrics": { "lines": { "covered": 80, "total": 100 } } }
556
+ }
557
+ ```
558
+
559
+ An adapter must translate actual runner results; do not infer passing tests from
560
+ a successful build or command. Test IDs are unique within each check. Status is
561
+ `passed`, `failed`, `skipped` or `unsupported`; optional bounded `message` and
562
+ `stack` fields carry diagnostics. Empty tests report `no_tests`, and skipped or
563
+ unsupported tests count as zero executions. Durations are integer milliseconds.
564
+ Missing, invalid, replayed or mismatched required reports fail the command.
565
+ Reported failed tests fail the check even if the process exits zero; nonzero
566
+ process exits always remain failures. Following checks remain explicitly unrun.
567
+
568
+ Coverage is optional (`not_collected`), `unavailable`, or `collected` with at
569
+ least one of `lines`, `branches`, and `functions`, each containing integer
570
+ `covered` and `total` counts. Covered cannot exceed total. Collected coverage
571
+ requires executed tests. Per-check coverage retains its declared profile; native
572
+ coverage does not imply WASM coverage. Reports and metrics are visibly
573
+ `customer_runner_reported`; this importer does not verify runtime/engine/artifact
574
+ identity or authorize preview/promotion. Aggregate test counts stay unknown if
575
+ any selected test command lacks structured results. CLI regression counts are
576
+ separate from your application test counts.
577
+
578
+ Reports are limited to 1 MiB and 10,000 tests per check, and 4 MiB across the
579
+ sequence. The importer rejects unknown fields, malformed UTF-8 and nonregular,
580
+ symlink or hardlinked inputs. It screens common credentials and terminal controls
581
+ in diagnostics, and removes temporary run context from receipts. Screening is
582
+ heuristic; omit sensitive data in your adapter. Cleanup removes only the fresh
583
+ temporary directory created for that check, preserving project-owned results.
584
+ Arbitrary local commands have your local permissions; this workflow is not a
585
+ hostile-code sandbox. The standard-runner adapters below, compiled-WASM checks
586
+ through the [local development toolkit](./dist/local-development/README.md),
587
+ and the IDE's **Tests → Inspect local test results** panel provide the local
588
+ workflow. Local preview/promotion preflight can require these results; hosted
589
+ activation separately requires a signed result with current resource custody.
590
+ Importing a local report does not grant that authority.
591
+
592
+ The Node `node:test` adapter is available through `runner: node` with `kind: test`,
593
+ `profile: native` and arguments such as `tests/app.test.mjs`. The CLI selects
594
+ `--test` and its bundled reporter; changing reporter or execution mode through
595
+ runner arguments is rejected. The explicit `@blinkhost/cli/test/node-reporter`
596
+ export also remains available for customer-owned command configurations.
597
+ Add `--experimental-test-coverage` to collect Node's native coverage metrics.
598
+ This adapter is locally qualified on Node 22.23.3. It reconciles
599
+ root and file-level counts with individual terminal events, excludes empty-file
600
+ checks and suites, includes nested test
601
+ cases, and treats skip/todo as skipped. Cancelled child tests remain failures.
602
+ Missing final summaries fail the adapter, and it refuses WASM/browser labels.
603
+
604
+ Select the packaged Python standard-library `unittest` adapter with
605
+ `runner: python-unittest`:
606
+
607
+ ```json
608
+ {
609
+ "schema": "blinkhost.local-test-config/v1",
610
+ "checks": [{
611
+ "id": "python-unit",
612
+ "target": "project",
613
+ "cwd": ".",
614
+ "runner": "python-unittest",
615
+ "args": ["discover", "-s", "tests"],
616
+ "kind": "test",
617
+ "profile": "native",
618
+ "results": { "format": "blinkhost/v1" }
619
+ }]
620
+ }
621
+ ```
622
+
623
+ Ordinary unittest discovery, explicit test names, name filters and failfast flags
624
+ are supported. Each declared parent test produces one record; subtest failures
625
+ fail their parent and subtests do not inflate counts. Expected failures are
626
+ skipped, unexpected successes are failures, and empty discovery reports no
627
+ tests. Collection and class/module fixture failures fail the command without
628
+ inventing test records. Cancellation never produces a successful report.
629
+ Reports have a 10,000-test/1 MiB bound, screen common credentials and run context,
630
+ and never overwrite a result file. Native coverage defaults to `not_collected`; this
631
+ adapter does not report WASM or browser coverage. The current local qualification
632
+ uses Python 3.12.3 on Linux; other Python/platform combinations remain unqualified.
633
+ The runner uses customer test code and Python's standard library independently
634
+ of BlinkHost account, database and mail services. Local process cleanup is not a
635
+ security sandbox; use isolated resources for untrusted application tests.
636
+
637
+ To collect native Python line and branch coverage, add `coverage.py` 7.x to your
638
+ application's test environment and opt in through the check arguments:
639
+
640
+ ```json
641
+ "args": ["--coverage=app", "discover", "-s", "tests"]
642
+ ```
643
+
644
+ Use the package dependency `coverage` (locally qualified at version 7.10.7).
645
+ Repeat `--coverage=relative-directory` for up to 16 source directories inside the
646
+ check's working directory. Bare `--coverage` measures that whole directory;
647
+ prefer explicit application folders to avoid counting test code or dependencies.
648
+ Coverage includes discoverable Python source files within those folders even if
649
+ tests never import them. Missing, empty, absolute or escaping directory values
650
+ are rejected before test discovery. The adapter ignores `.coveragerc`, retains
651
+ only bounded numeric totals and writes no coverage database or JSON report file.
652
+ No function totals, subprocess/multiprocessing aggregation, browser coverage or
653
+ WASM coverage are provided. Instrumentation runs within the check's existing
654
+ time and memory limits.
655
+
656
+ Missing or unsupported dependencies, instrumentation/report errors and empty or
657
+ skipped-only suites report `unavailable`. Test outcomes keep their actual
658
+ meaning: coverage cannot make a failed test pass. Hosted offline checks use the
659
+ same adapter with a locked pure Python wheel bound to the selected module's SBOM;
660
+ the worker does not download or install the dependency during test execution.
661
+
662
+ The Go adapter runs ordinary native `go test -json` with `runner: go`. Select package patterns
663
+ and Go test flags as literal arguments:
664
+
665
+ ```json
666
+ {
667
+ "schema": "blinkhost.local-test-config/v1",
668
+ "checks": [{
669
+ "id": "go-unit",
670
+ "target": "project",
671
+ "cwd": ".",
672
+ "runner": "go",
673
+ "args": ["-count=1", "./..."],
674
+ "kind": "test",
675
+ "profile": "native",
676
+ "results": { "format": "blinkhost/v1" }
677
+ }]
678
+ }
679
+ ```
680
+
681
+ Install Go on your PATH and run this through `blinkhost test`. The adapter
682
+ validates the native profile before invoking Go. It forwards selection, repeat,
683
+ parallelism, timeout and failfast flags. Each completed Go parent test, subtest
684
+ and repeat produces its own record, as reported by Go; package build/execution
685
+ checks never count as application tests. Empty/skipped-only packages remain
686
+ explicit. Failed package exits fail the check, even if no tests were declared.
687
+ Missing package/test terminal events and interrupted runs cannot supply passing
688
+ reports. Native coverage is `not_collected`, including when Go's `-cover` prints
689
+ a percentage; the adapter does not turn percentages into invented counts.
690
+
691
+ Compile-only, list, benchmark, fuzz and custom execution modes are rejected.
692
+ Inherited `GOFLAGS` is cleared to preserve the structured runner mode; put your
693
+ ordinary test flags in the configured argument list. Cross-compiled GOOS/GOARCH
694
+ profiles are refused. Go's `./...` excludes nested Go modules; declare separate
695
+ checks with their module directories to include them. Dependencies, toolchain
696
+ downloads and customer test effects follow your own Go configuration and local
697
+ permissions. No BlinkHost account/mail/database service is used by this adapter.
698
+
699
+ Result bounds remain 10,000 tests and 1 MiB; event parsing additionally caps each
700
+ JSON event and retained test diagnostic at 64 KiB, the event stream at 32 MiB,
701
+ and retained diagnostics at 4 MiB. Oversize/incomplete results fail. Common
702
+ credentials, terminal controls and run context are screened before diagnostic
703
+ truncation, and fresh private results never overwrite existing files. The parent
704
+ CLI owns timeout/output budgets and process-group cleanup. The local qualification
705
+ targets Node 22.23.3 and Go 1.27.3 on Linux; other versions/platforms, hostile-code
706
+ isolation and actual compiled-WASM execution retain separate validation gates.
707
+
708
+ Select the stable Rust adapter with `runner: rust`; it is also exported as
709
+ `@blinkhost/cli/test/rust-runner`. It uses Cargo JSON build records to discover
710
+ native unit/integration test binaries, then reconciles each stable libtest result
711
+ with a separate selected-test census, ignored-test census, summary and exit code.
712
+ It does not require nightly Rust or `RUSTC_BOOTSTRAP`. Install Rust/Cargo locally:
713
+
714
+ ```json
715
+ {
716
+ "schema": "blinkhost.local-test-config/v1",
717
+ "checks": [{
718
+ "id": "rust-native",
719
+ "target": "project",
720
+ "runner": "rust",
721
+ "args": [],
722
+ "kind": "test",
723
+ "profile": "native",
724
+ "results": { "format": "blinkhost/v1" }
725
+ }, {
726
+ "id": "rust-doc",
727
+ "target": "project",
728
+ "command": "cargo",
729
+ "args": ["test", "--doc"],
730
+ "kind": "test",
731
+ "profile": "native"
732
+ }]
733
+ }
734
+ ```
735
+
736
+ Pass ordinary Cargo selection/features before `--`, and libtest filters, exact
737
+ selection, ignored/include-ignored or test-thread flags after it. Each native
738
+ test is counted once; ignored cases are skipped. Individual timing and native
739
+ coverage are unavailable and are not inferred from suite time or build success.
740
+ The separate doctest command has `command_exit_only` evidence, so aggregate test
741
+ counts remain unknown when it is included. Declare nested Cargo projects as
742
+ separate checks with their directories. Benchmarks, doctests inside the adapter,
743
+ cross targets, alternate output modes, uncaptured output and nightly options are
744
+ rejected. Custom harnesses and unsupported output formats fail closed.
745
+
746
+ Stable libtest text has no versioned machine contract; this adapter's local
747
+ qualification targets Rust 1.98.0/Cargo 1.98.0 with Node 22.23.3 on Linux. Other
748
+ versions/platforms remain unqualified. Every build/list/execution stdout is
749
+ bounded at 1 MiB, with the existing total CLI timeout/output and canonical result
750
+ bounds. Failed tests carry bounded screened per-test output. Cargo build scripts,
751
+ dependencies and tests use your local permissions and configuration; isolate
752
+ untrusted projects. This is native testing, with no BlinkHost internal services
753
+ and no compiled-WASM/libSQL/runtime certification.
754
+
755
+ Results include every configured check, bounded execution receipts and unrun
756
+ checks after the first failure. Nested `blinkhost.yaml` projects are discovered
757
+ and reported as unrun; use `blinkhost test path/to/project` to run each explicitly.
758
+ Discovery skips dependency/build/cache directories and directory symlinks. It
759
+ reports incomplete discovery after eight levels, 2048 directories, 16384 entries
760
+ or 128 nested projects. Review unexplored directories before treating the check
761
+ set as complete. Discovery does not execute discovered projects.
762
+
763
+ For a local required-check preflight, add `blinkhost.gates.json` and run
764
+ `blinkhost test . --gate preview --json` or `--gate promotion`. Configure explicit
765
+ structured checks in `blinkhost.tests.json`, using installed runners or the
766
+ `blinkhost/v1` result protocol. The selected stage requires every named check to
767
+ exit successfully, report at least one passing test, and report zero failed,
768
+ skipped or unsupported tests. A build or a successful command without a valid
769
+ test report cannot satisfy a required check. All configured commands still run;
770
+ the selected stage determines which reports must contain only passing tests.
771
+
772
+ ```json
773
+ {
774
+ "schema": "blinkhost.local-test-gates/v1",
775
+ "inputs": {
776
+ "source": ["src/app.ts", "tests/app.test.ts"],
777
+ "artifacts": [],
778
+ "dependencies": ["package.json", "package-lock.json"],
779
+ "runtime": ["runtime.json"],
780
+ "resources": ["resources.json"],
781
+ "fixtures": ["fixtures/customer.json"]
782
+ },
783
+ "stages": {
784
+ "preview": ["unit"],
785
+ "promotion": ["unit", "integration"]
786
+ }
787
+ }
788
+ ```
789
+
790
+ Adapt file paths and check names to your application. All six input categories
791
+ must be present; source must contain at least one file. List individual regular
792
+ files using relative paths with letters, digits, `_`, `.`, `@`, `-` and `/`.
793
+ Directories, glob patterns, duplicate paths, path traversal and symlinks are
794
+ rejected. Keep changing output/log files outside the declared input set. The CLI
795
+ includes `blinkhost.yaml`, `blinkhost.tests.json` and `blinkhost.gates.json`
796
+ automatically, and snapshots the Node binary, relevant CLI/adapter files and
797
+ resolved check executables. It compares selected input hashes before and after
798
+ the checks. A changed, removed or unavailable input blocks the local gate;
799
+ changed executable bytes or resolution also block stale local evidence.
800
+ Configuration replacement during setup is rejected. Duplicate JSON keys are
801
+ invalid in the gate policy.
802
+
803
+ Gate configuration is limited to 64 KiB and declared inputs to 1,024 files.
804
+ Snapshot reads allow at most 256 MiB per file and 512 MiB total, including CLI
805
+ tools. Setup, snapshots and commands share the selected `--timeout`. The
806
+ `local_gate` receipt records stage, passed/blocked status, input hashes and each
807
+ required check's outcome. Local gates currently qualify Linux only.
808
+
809
+ This preflight is **customer-runner-reported local evidence** with
810
+ `scope: declared_local_inputs` and `production_authority: false`. You must list
811
+ the application inputs you intend to check. It does not establish complete
812
+ dependency, environment or dynamic-library coverage, and before/after snapshots
813
+ cannot detect temporary changes reverted during execution. It does not run a
814
+ remote preview, authorize promotion or attest an isolated worker execution.
815
+ Trusted preview/promotion enforcement requires the separate server-side test
816
+ stages. Ordinary `blinkhost test` behavior is unchanged without `--gate`.
817
+
818
+ Local commands share a default 900-second timeout and 1 MiB of combined
819
+ stdout/stderr. Use `--timeout 120` (1–3600 seconds) and
820
+ `--max-output-bytes 1048576` (1024–8388608 bytes) to choose other bounds.
821
+ The timeout and output allowance apply to the whole configured sequence.
822
+ Commands receive no interactive stdin. Timeouts, cancellation and output
823
+ overflow fail the check; overflow never becomes a successful truncated result.
824
+ SIGINT exits 130 and SIGTERM exits 143.
825
+
826
+ Execution receipts include bounded stdout/stderr after screening common
827
+ credentials and terminal controls. Output is collected before display, with no
828
+ raw subprocess streaming; `--json` emits one response including the receipt.
829
+ Screening is not exhaustive, so review results before sharing. POSIX cleanup
830
+ covers the owned process group, while Windows cleanup covers the direct child.
831
+ Local commands run with your machine permissions; these controls are not a
832
+ security sandbox or CPU/memory isolation. The command performs no update checks.
833
+ Result delivery waits at most three seconds for successful output or one second
834
+ for failure/cancellation output. Closed or stalled pipes exit 4. Interrupting
835
+ result delivery can leave an incomplete response; SIGINT/SIGTERM still exit
836
+ 130/143 after owned-command cleanup.
837
+
367
838
  ## Remote workflows
368
839
 
369
840
  ### Download project source
@@ -412,11 +883,19 @@ blinkhost projects get PROJECT_ID
412
883
  blinkhost previews list --query project=PROJECT_ID
413
884
  blinkhost builds list --query project=PROJECT_ID
414
885
  blinkhost deployments get DEPLOYMENT_ID
886
+ blinkhost deployments preparation-diagnostics DEPLOYMENT_ID --project PROJECT_UUID
415
887
  blinkhost modules list --query site_id=PROJECT_ID
416
888
  blinkhost databases list --query project=PROJECT_ID
417
889
  blinkhost organizations get ORGANIZATION_ID
418
890
  ```
419
891
 
892
+ `deployments preparation-diagnostics` shows recorded native compiler failures for
893
+ the selected release and project, including validated measured sizes and platform
894
+ preparation budgets. These are past attempt facts; they do not confirm current
895
+ serving health or native readiness. Changing plans does not increase platform
896
+ compiler limits. The command only reads, does not retry or prepare modules, and
897
+ displays unavailable details safely. `--json` returns the same bounded projection.
898
+
420
899
  Create and update operations accept a JSON object or `@path` to a JSON file:
421
900
 
422
901
  ```bash
@@ -480,17 +959,70 @@ Database, binding, module, and asset operations remain subject to workspace perm
480
959
 
481
960
  ```bash
482
961
  blinkhost logs --project PROJECT_ID --since 1h --limit 100
962
+ blinkhost logs --project PROJECT_ID --follow --severity error --max-events 1000
963
+ blinkhost logs --project PROJECT_ID --preview-session-id SESSION_UUID --json
964
+ blinkhost logs --project PROJECT_ID --attribute-filters '[{"path":["order","id"],"op":"eq","type":"integer","value":18446744073709551615}]' --json
483
965
  blinkhost metrics --project PROJECT_ID --since 24h
484
966
  blinkhost analytics --project PROJECT_ID
485
967
  blinkhost doctor
486
968
  blinkhost support bundle
487
969
  ```
488
970
 
971
+ Logs use the linked project when `--project` is omitted. `--since` accepts a
972
+ positive integer followed by `s`, `m`, `h` or `d` (up to 366 days), or a
973
+ timezone-aware ISO timestamp with at most millisecond precision. It sends a
974
+ fixed `start_time` to the API. Alternatively use `--hours N`, or `--start-time`
975
+ and `--end-time`; the start is inclusive and the end exclusive. The service
976
+ enforces current permissions, retention and plan query bounds. The default
977
+ lookback is one hour. Metrics and analytics accept duration `--since` values
978
+ and round them up to whole hours; they do not accept absolute timestamps.
979
+
980
+ Log filters include `--severity`, `--event-kind`, `--search`, `--request-id`,
981
+ `--trace-id`, `--source`, `--operation`, `--outcome`, `--status-code`, `--region`,
982
+ `--release-id`, `--environment-kind`, `--environment-id`, `--deployment-id`
983
+ and `--preview-session-id`. A preview session implies the preview environment
984
+ and cannot combine with deployed environment/deployment IDs. Custom
985
+ `--attribute-filters` use the same bounded typed JSON predicates as the
986
+ dashboard and API. Quote exact 64-bit integer JSON in the shell as above;
987
+ generating it with a JavaScript `Number` can round it before the CLI receives it.
988
+ Run `blinkhost logs --help` for command examples and options.
989
+
990
+ History reads newest first, one page at a time. `--limit` is the page size
991
+ (1–200, default 100); `--max-events` is the total output bound (1–10,000,
992
+ default 200 for history and 10,000 for follow). History also stops after
993
+ 1,000 pages or 120 seconds. A cutoff summary includes `has_more`, `next_cursor`
994
+ and the effective filters. Continue with `--cursor` and exactly those filters,
995
+ using the summary's `--start-time` instead of recomputing `--since`. Cursors
996
+ are scoped and may expire. Concurrent ingestion and retention can change
997
+ history between pages.
998
+
999
+ `--follow` uses an authenticated scoped ticket, polls every 2.5 seconds, reads
1000
+ at most ten pages per poll and remembers at most 1,000 IDs for deduplication.
1001
+ It retries transient failures at most three times with bounded backoff, and
1002
+ stops on permission errors, ticket expiry, the event bound or interruption.
1003
+ Notices identify reconnects and unconfirmed continuity; late arrivals and
1004
+ full windows can leave gaps. Use retained history to inspect an interval.
1005
+ Ctrl-C/SIGINT and SIGTERM exit with 130 and 143, respectively. Cancellation
1006
+ targets only the current owned query and ticket closure is attempted with an
1007
+ independent timeout; unconfirmed cleanup is reported when output is available.
1008
+ Output is awaited before fetching another page. Interrupting a stalled pipe
1009
+ can leave its final line or summary incomplete; a closed pipe exits with code 4.
1010
+ Logs do not perform background update checks.
1011
+
1012
+ With `--json`, logs emit newline-delimited JSON: `{"kind":"event","event":...}`,
1013
+ `{"kind":"notice","code":...,"message":...}` and a final
1014
+ `{"kind":"summary","events":...,"duplicates_skipped":...,"reason":...,"filters":...,"has_more":...,"next_cursor":...}`.
1015
+ A failed command may follow emitted records with the standard `ok:false`
1016
+ error object and exits nonzero. Stored attribute JSON preserves exact integer
1017
+ tokens when available; otherwise `precision_notice` identifies the fallback.
1018
+ Use an integer-preserving parser downstream. Text mode prints quoted
1019
+ time/severity/message and exposes terminal controls and embedded newlines.
1020
+
489
1021
  Support bundles are local, redacted JSON files with mode `0600`. They exclude tokens, secret values, source code, filenames, and repository URLs.
490
1022
 
491
1023
  ## CI and automation
492
1024
 
493
- All commands support `--json`. In JSON mode, stdout contains exactly one response object on success or failure; subprocess and human diagnostics use stderr. Register one exact GitHub branch, tag, or protected environment as a workload identity, then grant the workflow `id-token: write`. The CLI exchanges GitHub's signed OIDC assertion for a ten-minute BlinkHost token automatically; no BlinkHost secret is stored in GitHub.
1025
+ All commands support `--json`. In JSON mode, stdout contains one response object on success or failure, except `logs`, which emits the NDJSON stream described above, and local-stack `dev`, which emits readiness and final records; subprocess and human diagnostics use stderr. Register one exact GitHub branch, tag, or protected environment as a workload identity, then grant the workflow `id-token: write`. The CLI exchanges GitHub's signed OIDC assertion for a ten-minute BlinkHost token automatically; no BlinkHost secret is stored in GitHub.
494
1026
 
495
1027
  ```bash
496
1028
  blinkhost workloads create --data @workload.json
package/dist/api.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type Profile } from './config.js';
2
- export declare function publicRequest(apiOrigin: string, path: string, init?: RequestInit): Promise<{
2
+ export declare function publicRequest(apiOrigin: string, path: string, init?: RequestInit, responseLimit?: number): Promise<{
3
3
  response: Response;
4
4
  data: unknown;
5
5
  }>;
@@ -16,7 +16,7 @@ export declare class ApiClient {
16
16
  }>;
17
17
  static fromAccessToken(profileName: string, profile: Profile, accessToken: string): ApiClient;
18
18
  projectArchive(projectId: string, mode?: 'portable' | 'source'): Promise<Buffer>;
19
- request(path: string, init?: RequestInit): Promise<unknown>;
19
+ request(path: string, init?: RequestInit, responseLimit?: number): Promise<unknown>;
20
20
  rememberIdentity(identity: {
21
21
  id?: number;
22
22
  username?: string;