@blinkhost/cli 2.7.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.
- package/CHANGELOG.md +4 -0
- package/README.md +514 -2
- package/dist/api.d.ts +2 -2
- package/dist/api.js +57 -8
- package/dist/assistant.js +6 -1
- package/dist/cli.js +157 -9
- package/dist/guidance.d.ts +1 -1
- package/dist/guidance.js +43 -11
- package/dist/javascript-runtime/resource-limits.js +3 -0
- package/dist/javascript-runtime/resource-profiles.js +2 -0
- package/dist/local-dev.d.ts +3 -0
- package/dist/local-dev.js +145 -0
- package/dist/local-development/README.md +410 -0
- package/dist/local-development/artifact-watch.mjs +36 -0
- package/dist/local-development/blinkhost.local.example.json +15 -0
- package/dist/local-development/frontend-proxy.mjs +189 -0
- package/dist/local-development/hello.rs +24 -0
- package/dist/local-development/local-stack.mjs +511 -0
- package/dist/local-development/native-database.mjs +37 -0
- package/dist/local-development/provider-fixtures.example.json +36 -0
- package/dist/local-development/provider-fixtures.mjs +203 -0
- package/dist/local-development/provider-grants.mjs +36 -0
- package/dist/local-development/test-provider-example.mjs +74 -0
- package/dist/local-source-build.d.ts +39 -0
- package/dist/local-source-build.js +225 -0
- package/dist/local-source-watch.d.ts +24 -0
- package/dist/local-source-watch.js +87 -0
- package/dist/local-test-command.d.ts +49 -0
- package/dist/local-test-command.js +128 -0
- package/dist/local-test-config.d.ts +37 -0
- package/dist/local-test-config.js +174 -0
- package/dist/local-test-gates.d.ts +71 -0
- package/dist/local-test-gates.js +247 -0
- package/dist/local-test-go-runner.d.ts +27 -0
- package/dist/local-test-go-runner.js +209 -0
- package/dist/local-test-node-arguments.d.ts +2 -0
- package/dist/local-test-node-arguments.js +14 -0
- package/dist/local-test-node-reporter.d.ts +7 -0
- package/dist/local-test-node-reporter.js +159 -0
- package/dist/local-test-results.d.ts +65 -0
- package/dist/local-test-results.js +163 -0
- package/dist/local-test-rust-runner.d.ts +18 -0
- package/dist/local-test-rust-runner.js +252 -0
- package/dist/local-test-starters.d.ts +3 -0
- package/dist/local-test-starters.js +157 -0
- package/dist/logs.d.ts +43 -0
- package/dist/logs.js +417 -0
- package/dist/module-build-diagnostics.d.ts +10 -0
- package/dist/module-build-diagnostics.js +208 -0
- package/dist/module-build.js +4 -0
- package/dist/release-preparation-diagnostics.d.ts +38 -0
- package/dist/release-preparation-diagnostics.js +204 -0
- package/dist/remote.js +14 -0
- package/dist/templates.d.ts +1 -0
- package/dist/templates.js +4 -1
- package/dist/test-credentials.d.ts +7 -0
- package/dist/test-credentials.js +236 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/workflows.d.ts +39 -2
- package/dist/workflows.js +241 -14
- package/package.json +4 -3
- package/test-runners/python-unittest.py +266 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,10 @@
|
|
|
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
|
+
|
|
5
9
|
## 2.7.0 — UI and design references
|
|
6
10
|
|
|
7
11
|
Adds `design list`, `design search`, `design show` and `design notices` for
|
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ 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.
|
|
10
|
+
npm install --global @blinkhost/cli@2.8.0
|
|
11
11
|
blinkhost --version
|
|
12
12
|
```
|
|
13
13
|
|
|
@@ -160,6 +160,11 @@ Read/list needs `ai:read`, preparation needs `ai:execute`, and approval needs
|
|
|
160
160
|
usage—not AI credits. It does not publish, promote an artifact or commit files.
|
|
161
161
|
Unsaved edits are excluded. After a timeout, use
|
|
162
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.
|
|
163
168
|
do not create a new review to repeat an uncertain build. See `blinkhost docs ai`.
|
|
164
169
|
These commands require current Idam access and an available module compiler.
|
|
165
170
|
|
|
@@ -371,6 +376,92 @@ Supported frontends are Astro, HTML, React, Solid, Svelte, and Vue. Backend modu
|
|
|
371
376
|
blinkhost init apps/storefront --dry-run --json
|
|
372
377
|
```
|
|
373
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
|
+
|
|
374
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.
|
|
375
466
|
|
|
376
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.
|
|
@@ -384,6 +475,366 @@ npm install
|
|
|
384
475
|
blinkhost test .
|
|
385
476
|
```
|
|
386
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
|
+
|
|
387
838
|
## Remote workflows
|
|
388
839
|
|
|
389
840
|
### Download project source
|
|
@@ -432,11 +883,19 @@ blinkhost projects get PROJECT_ID
|
|
|
432
883
|
blinkhost previews list --query project=PROJECT_ID
|
|
433
884
|
blinkhost builds list --query project=PROJECT_ID
|
|
434
885
|
blinkhost deployments get DEPLOYMENT_ID
|
|
886
|
+
blinkhost deployments preparation-diagnostics DEPLOYMENT_ID --project PROJECT_UUID
|
|
435
887
|
blinkhost modules list --query site_id=PROJECT_ID
|
|
436
888
|
blinkhost databases list --query project=PROJECT_ID
|
|
437
889
|
blinkhost organizations get ORGANIZATION_ID
|
|
438
890
|
```
|
|
439
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
|
+
|
|
440
899
|
Create and update operations accept a JSON object or `@path` to a JSON file:
|
|
441
900
|
|
|
442
901
|
```bash
|
|
@@ -500,17 +959,70 @@ Database, binding, module, and asset operations remain subject to workspace perm
|
|
|
500
959
|
|
|
501
960
|
```bash
|
|
502
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
|
|
503
965
|
blinkhost metrics --project PROJECT_ID --since 24h
|
|
504
966
|
blinkhost analytics --project PROJECT_ID
|
|
505
967
|
blinkhost doctor
|
|
506
968
|
blinkhost support bundle
|
|
507
969
|
```
|
|
508
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
|
+
|
|
509
1021
|
Support bundles are local, redacted JSON files with mode `0600`. They exclude tokens, secret values, source code, filenames, and repository URLs.
|
|
510
1022
|
|
|
511
1023
|
## CI and automation
|
|
512
1024
|
|
|
513
|
-
All commands support `--json`. In JSON mode, stdout contains
|
|
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.
|
|
514
1026
|
|
|
515
1027
|
```bash
|
|
516
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;
|