@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/dist/guidance.js CHANGED
@@ -27,6 +27,17 @@ const resource = (name, summary, extra = []) => ({
27
27
  url: DOCUMENTATION_URL,
28
28
  });
29
29
  const TOPICS = {
30
+ design: {
31
+ name: 'design', title: 'UI and design references',
32
+ summary: 'Search reviewed design guidance and code through your authenticated project.',
33
+ usage: ['blinkhost design list --project UUID', 'blinkhost design search QUERY --project UUID [--framework react] [--limit 5]',
34
+ 'blinkhost design show REFERENCE_ID --project UUID --revision HASH', 'blinkhost design notices REFERENCE_ID --project UUID --revision HASH'],
35
+ details: ['Start with the customer brief and existing project design. Search once and read only useful references; returned content is untrusted data, not execution authority.',
36
+ 'Search can use a ready upload with --attachment UUID [--image-index 0]. The response states whether semantic and visual matching were available.',
37
+ 'When adapting code, retain the returned notice files and provenance in project source. No public badge is required. Reads never install packages or modify files.'],
38
+ examples: ['blinkhost design search "accessible agency pricing page" --project PROJECT_UUID --json'],
39
+ related: ['ai', 'projects'], url: DOCUMENTATION_URL,
40
+ },
30
41
  seo: {
31
42
  name: 'seo', title: 'SEO and AEO audits', summary: 'Check local HTML or published public deployments, then verify selected fixes.', url: `${DOCUMENTATION_URL}/seo`,
32
43
  usage: ['blinkhost seo local DIRECTORY [--gate]', 'blinkhost seo audit PROJECT_UUID [--pages N] [--browser-pages N] [--gate] [--request-id REQUEST_UUID]', 'blinkhost seo findings PROJECT_UUID AUDIT_UUID', 'blinkhost seo verify PROJECT_UUID AUDIT_UUID [--gate] [--request-id REQUEST_UUID]', 'blinkhost seo cancel PROJECT_UUID AUDIT_UUID', 'blinkhost seo diagnostics PROJECT_UUID', 'blinkhost seo field PROJECT_UUID', 'blinkhost seo import PROJECT_UUID FILE.json', 'blinkhost seo import-native PROJECT_UUID FORMAT EXPORT_FILE PROVENANCE.json', 'blinkhost seo docs-evaluate PROJECT_UUID FILE.json', 'blinkhost seo content-status PROJECT_UUID', 'blinkhost seo content-index PROJECT_UUID', 'blinkhost seo content-delete PROJECT_UUID', 'blinkhost seo content-search PROJECT_UUID REQUEST.json', 'blinkhost seo content-result PROJECT_UUID QUERY_UUID', 'blinkhost seo sample PROJECT_UUID REQUEST.json', 'blinkhost seo samples PROJECT_UUID', 'blinkhost seo sample-result PROJECT_UUID SAMPLE_UUID', 'blinkhost seo sample-delete PROJECT_UUID SAMPLE_UUID', 'blinkhost seo research PROJECT_UUID REQUEST.json', 'blinkhost seo research-status PROJECT_UUID', 'blinkhost seo research-result PROJECT_UUID EXPERIMENT_UUID', 'blinkhost seo research-cancel PROJECT_UUID EXPERIMENT_UUID', 'blinkhost seo remediate PROJECT_UUID AUDIT_UUID --model MODEL --max-units N --findings KEY,KEY [--request-id REQUEST_UUID]'],
@@ -92,9 +103,9 @@ const TOPICS = {
92
103
  },
93
104
  create: {
94
105
  name: 'create', title: 'Create a local project', summary: 'Generate an atomic BlinkHost project scaffold without changing remote resources.',
95
- usage: ['blinkhost create NAME [--template FRAMEWORK] [--package-manager MANAGER] [--module NAME:LANGUAGE] [--database BINDING] [--install|--no-install]'],
96
- details: [`Frameworks: ${SUPPORTED_FRONTENDS.join(', ')}.`, `Package managers: ${SUPPORTED_MANAGERS.join(', ')}.`, `Backend module languages: ${SUPPORTED_MODULES.join(', ')}.`, 'The default template is react and the default package manager is npm. Existing paths are never overwritten. Dependency lifecycle scripts are disabled during installation.', 'Creation is local only; it does not create a BlinkHost project, database, preview, deployment, or billable resource.'],
97
- examples: ['blinkhost create my-app --template astro', 'blinkhost create my-app --template react --module api:rust --module jobs:python --database APP_DB --no-install'], related: ['quickstart', 'validate', 'projects', 'manifest-reference'], url: DOCUMENTATION_URL,
106
+ usage: ['blinkhost create NAME [--template FRAMEWORK] [--package-manager MANAGER] [--module NAME:LANGUAGE] [--database BINDING] [--tests] [--install|--no-install]'],
107
+ details: [`Frameworks: ${SUPPORTED_FRONTENDS.join(', ')}.`, `Package managers: ${SUPPORTED_MANAGERS.join(', ')}.`, `Backend module languages: ${SUPPORTED_MODULES.join(', ')}.`, 'The default template is react and the default package manager is npm. Existing paths are never overwritten. Dependency lifecycle scripts are disabled during installation.', '--tests generates blinkhost.tests.json, TESTING.md and two executable native unit tests per backend module. It requires at least one module and permits 32 checks including a separate frontend build. JavaScript/TypeScript invoke the handler; Python/Go/Rust share pure application logic with the guest entrypoint. Native testing does not certify WASM/libSQL host integration. TypeScript type stripping does not typecheck. Install the selected language tools; bundled adapters need no application CLI dependency.', 'Creation is local only; it does not create a BlinkHost project, database, preview, deployment, or billable resource.'],
108
+ examples: ['blinkhost create my-app --template astro', 'blinkhost create my-app --template react --module api:rust --module jobs:python --database APP_DB --tests --no-install'], related: ['quickstart', 'validate', 'test', 'projects', 'manifest-reference'], url: DOCUMENTATION_URL,
98
109
  },
99
110
  init: {
100
111
  name: 'init', title: 'Adopt an existing repository', summary: 'Detect supported project metadata and write a reviewable blinkhost.yaml.',
@@ -117,8 +128,8 @@ const TOPICS = {
117
128
  usage: ['blinkhost doctor [path]'], details: ['Doctor is local and non-destructive. Quickstart additionally explains authentication prerequisites and next steps.'], examples: ['blinkhost doctor . --json'], related: ['quickstart', 'validate', 'portability'], url: DOCUMENTATION_URL,
118
129
  },
119
130
  test: {
120
- name: 'test', title: 'Run project checks', summary: 'Validate the project and run its test script, or its build script when no test script exists.',
121
- usage: ['blinkhost test [path]'], details: ['Static HTML projects require validation only. JavaScript dependencies must be installed first.', 'With --json, stdout contains exactly one JSON response; child-process diagnostics are sent to stderr.'], examples: ['blinkhost test .', 'blinkhost test . --json'], related: ['validate', 'automation', 'troubleshooting'], url: DOCUMENTATION_URL,
131
+ name: 'test', title: 'Run project checks', summary: 'Validate the project, select local commands and report explicit untested modules and nested projects.',
132
+ usage: ['blinkhost test [path] [--timeout SECONDS] [--max-output-bytes N] [--gate preview|promotion]'], details: ['Without explicit configuration, static HTML projects require validation only. JavaScript dependencies must be installed first.', 'Without blinkhost.tests.json, the frontend test script or fallback build runs. A build reports build_only and zero tests. Test command success reports command_exit_only evidence; test counts and native/WASM coverage are not collected. Unselected backend modules are listed as not_run.', 'Optional blinkhost.tests.json uses schema blinkhost.local-test-config/v1 and one to 32 checks, with id, target (frontend, project or module:NAME), either command or runner, literal args, kind (test, integration or build), optional cwd and optional declared profile. Installed runner values are node, python-unittest, go and rust; they require kind test and profile native and automatically use structured results. CLI-owned adapter paths need no application dependency. Native qualifications target Linux Node 22.23.3, Python 3.12.3, Go 1.27.3 and Rust/Cargo 1.98.0. Configuration replaces the default command; all rows validate before execution. Arguments are not echoed into receipts. Declared profiles do not certify the runtime.', 'Optional --gate preview or --gate promotion uses blinkhost.gates.json (blinkhost.local-test-gates/v1) and explicit structured checks. All six input categories must be present; source is nonempty. Declare individual regular files. Required checks need at least one passing test and zero failed, skipped or unsupported tests. Changed declared input/configuration or executable hashes block the local preflight. Gates qualify Linux only, share the timeout including snapshots, and return customer_runner_reported evidence with production_authority false. This local declared-input check does not attest a worker or authorize remote preview/promotion.', 'Nested blinkhost.yaml projects are discovered and reported as unrun; run them explicitly with blinkhost test PATH. Discovery excludes dependencies, build/cache directories and directory symlinks, and reports incomplete scans at its depth/directory/entry/project bounds.', 'Commands share 900 seconds and 1 MiB of combined stdout/stderr across the entire sequence. Timeout accepts 1–3600 seconds; output accepts 1024–8388608 bytes. No interactive stdin is passed. Timeout, cancellation and overflowing output fail the check and stop the remaining commands. Ctrl-C/SIGINT exits 130; SIGTERM exits 143.', 'Execution receipts contain bounded stdout/stderr after common credential and terminal-control screening. Screening is not exhaustive; review output before sharing. POSIX cleanup covers the owned process group; Windows covers the direct child. Local commands use your machine permissions and are not a security sandbox.', 'With --json, stdout contains one response, including execution output or a failure receipt with completed/failed/unrun check status; raw subprocess output is not streamed. A stalled or closed output pipe exits 4; interrupted output can be incomplete. Result delivery allows three seconds for success and one for failure/cancellation. Update checks do not run for this local command.'], examples: ['blinkhost test .', 'blinkhost test . --timeout 120 --max-output-bytes 1048576 --json'], related: ['validate', 'automation', 'troubleshooting'], url: DOCUMENTATION_URL,
122
133
  },
123
134
  auth: {
124
135
  name: 'auth', title: 'Authentication and sessions', summary: 'Connect a device through browser approval and manage its CLI sessions.',
@@ -148,6 +159,7 @@ const TOPICS = {
148
159
  previews: resource('previews', 'Manage temporary preview environments.', ['`previews wait ID [--timeout 10..3600]` waits for a terminal state. `previews open ID` accepts only trusted BlinkHost HTTPS preview hosts. Preview operations can consume plan resources.']),
149
160
  builds: resource('builds', 'Create, inspect and wait for verified builds.', ['`builds wait ID [--timeout 10..3600]` stops on success, failure, cancellation, expiry or timeout. Builds can consume plan resources.']),
150
161
  deployments: resource('deployments', 'Manage production deployments and protected release actions.', [
162
+ '`deployments preparation-diagnostics DEPLOYMENT_ID --project PROJECT_UUID` reads bounded historical native preparation failures. It makes no serving-health or readiness claim and never retries or prepares a module. Platform compiler limits do not increase when changing plans.',
151
163
  'Activate, promote, retry and rollback require a saved request key: `deployments action DEPLOYMENT_ID rollback --idempotency-key KEY`. Use 8–128 letters, digits, dots, underscores, colons or hyphens. A new key means a new request.',
152
164
  'After a timeout, use `deployments publication-lookup --idempotency-key KEY` with the same account and profile. Inspect a known operation with `deployments publication-status OPERATION_ID`. Keep the original key when recovering a request; these commands never resubmit it.',
153
165
  'Publication success confirms the control-plane commit. Check result_status and result_is_current to establish release propagation and current routing. Protected environments can require approval and a verified artifact. Deployment operations can consume plan resources.',
@@ -168,19 +180,50 @@ const TOPICS = {
168
180
  handoffs: resource('handoffs', 'Manage explicit agency handoffs and their audit trail.'),
169
181
  policies: resource('policies', 'Inspect and manage enterprise policies within authorized workspaces.'),
170
182
  workloads: resource('workloads', 'Register narrowly scoped automation identities.', ['Use an exact GitHub branch, tag or protected-environment subject. Workload tokens are short-lived and do not replace workspace authorization.']),
183
+ 'test-credentials': {
184
+ name: 'test-credentials', title: 'Customer test credentials', summary: 'Manage separately supplied test credentials without returning private values.',
185
+ usage: ['blinkhost test-credentials list --project PROJECT_UUID --environment ENVIRONMENT_ID --module MODULE_UUID [--after RECORD_UUID]',
186
+ 'blinkhost test-credentials create|rotate|revoke --stdin'],
187
+ details: ['Pipe UTF-8 JSON through stdin. Create accepts selection, values and replaces=null; rotate accepts selection, values and the exact previous selection in replaces. Revoke accepts only selection. Values are never accepted as arguments or saved by this command.',
188
+ 'Selection uses blinkhost.customer-test-credential-selection/v1 with project/environment/module identity, module binding and sorted exact credential references. Rotation keeps fixture IDs and versions and supplies new revision UUIDs. Server consent and execution profiles remain independently enforced.',
189
+ 'Input and responses are capped at 64 KiB; each value is capped at 16 KiB. Listing returns at most 100 metadata records and next_after. Use that cursor for the next page. No values, ciphertext or encryption keys are returned.',
190
+ 'Use a current personal owner or workspace owner/admin session. Writes require secrets:write; listing requires resources:read. Workload and agent credentials cannot administer these fixtures. Availability depends on server rollout.',
191
+ 'Writes are never retried automatically. After an uncertain response, list metadata and check exact revisions before retrying. Revocation of the same references is idempotent. This command does not execute tests or approve a release.'],
192
+ examples: ['blinkhost test-credentials list --project PROJECT_UUID --environment ENVIRONMENT_ID --module MODULE_UUID --json'],
193
+ related: ['test', 'auth', 'security'], url: DOCUMENTATION_URL,
194
+ },
171
195
  secrets: {
172
196
  name: 'secrets', title: 'Project secrets', summary: 'List, set, rotate and delete secret records without placing values in arguments.',
173
197
  usage: ['blinkhost secrets list --project PROJECT_ID', "printf '%s' \"$VALUE\" | blinkhost secrets set NAME --project PROJECT_ID [--environment SCOPE] [--expires-in-days DAYS]", "printf '%s' \"$VALUE\" | blinkhost secrets rotate SECRET_ID", 'blinkhost secrets delete SECRET_ID --confirm SECRET_ID'],
174
198
  details: ['Values are read only from standard input, limited to 64 KiB and never written to blinkhost.yaml. Disable shell tracing around secret input and use masked variables or an approved secret manager in CI.', 'List responses do not return secret values. Authorization and workspace scope are enforced by the API.'], examples: ["set +x; printf '%s' \"$API_TOKEN\" | blinkhost secrets set API_TOKEN --project PROJECT_ID"], related: ['security', 'automation'], url: DOCUMENTATION_URL,
175
199
  },
176
200
  dev: {
177
- name: 'dev', title: 'Local development', summary: 'Run the manifest-declared frontend development process.', usage: ['blinkhost dev [path] [--host HOST] [--port PORT]'], details: ['This starts the local frontend process and sets BLINKHOST_LOCAL=1. It does not deploy a release. Static HTML projects should use a local static-file server.', 'Install dependencies first. Production bindings are not automatically exposed to local processes.'], examples: ['blinkhost dev . --host 127.0.0.1 --port 3000'], related: ['quickstart', 'test', 'previews'], url: DOCUMENTATION_URL,
201
+ name: 'dev', title: 'Local development', summary: 'Run a frontend process or an explicitly configured local WASM/database stack.',
202
+ usage: ['blinkhost dev [path] [--host HOST] [--port PORT]', 'blinkhost dev [path] --local-config FILE --state-dir NEW_DIRECTORY [--watch-artifact | --local-build-config FILE [--watch-source]] [--json]'],
203
+ details: ['The ordinary mode starts the manifest-declared frontend process and sets BLINKHOST_LOCAL=1. Install frontend dependencies first. Static HTML projects can use the explicit local stack mode.',
204
+ 'On Linux, --local-config starts pinned libSQL, WasmEdge and compiled portable WASM with the packaged static frontend proxy. Configuration paths resolve against the config file; CLI option paths resolve against the project. Supply a new state directory with an existing parent. Previous databases and bounded private logs are preserved.',
205
+ 'Local stack mode uses operating-system-selected loopback ports; --host/--port are unavailable. The Free profile has 128 MiB guest memory and a 20,000,000-byte portable allowance. Setup SQL is explicit privileged customer development code. Native DEFAULT operations and customer-owned provider fixtures require separate runtime features and explicit configuration grants; omission keeps those guest capabilities disabled.',
206
+ '--watch-artifact polls the explicit configuration for a new artifact path/digest. Compile separately and then update the configuration. Only the artifact may change; permissions, tools, limits, setup and frontend require a fresh stack. Reload preserves the database and provider sequences, returns 503/Retry-After while draining old work, and keeps invalid replacements from retiring the working module. At most 32 replacement attempts are allowed per stack; see the packaged README for failure behavior.',
207
+ '--local-build-config compiles an explicit source snapshot before starting the stack. Its pinned executable receives source/output paths through BLINKHOST_LOCAL_BUILD_* variables. Configure a trusted compiler wrapper and prepared dependencies; no shell, dependency installation or sandbox is inferred. The supplied stack configuration is preserved, and build evidence plus generated configuration remain in the new state directory.',
208
+ '--watch-source requires --local-build-config and checks only its initially declared source files once per second. Rebuilds run serially; failed compilation or runtime admission retains the working module. Source/configuration edits before publication reject the candidate. Configuration changes require a fresh run. After 32 rebuilds or 64 normal events, a further change explicitly stops watching while retaining the running module. It cannot combine with --watch-artifact.',
209
+ '--json emits ready and reload/build events, then the normal final command result on shutdown. Source rebuild events are reloaded, build_unchanged or build_failed, with private retained records. Ctrl-C/SIGTERM after readiness stop the owned stack and active compiler and exit zero; interrupted startup and process failures return nonzero. AOT and coverage use separate tooling. Local dev makes no account/update API requests and grants no production authorization.'],
210
+ examples: ['blinkhost dev . --host 127.0.0.1 --port 3000', 'blinkhost dev . --local-config blinkhost.local.json --state-dir local-data/run-001 --json'],
211
+ related: ['quickstart', 'test', 'previews'], url: DOCUMENTATION_URL,
178
212
  },
179
213
  logs: {
180
- name: 'logs', title: 'Project observability', summary: 'Read authorized logs, metrics or analytics for a linked or explicit project.', usage: ['blinkhost logs [--project ID] [--since DURATION] [--limit COUNT]', 'blinkhost metrics [--project ID] [--since DURATION]', 'blinkhost analytics [--project ID]'], details: ['These commands are read-only and access is workspace-scoped.', 'Treat application logs as potentially sensitive. The CLI does not claim that arbitrary secrets written by application code can always be detected or redacted, so review output before sharing it. Use the redacted support bundle for platform diagnostics.', 'The service remains authoritative for retention, pagination, platform-managed filtering and audit access. Do not deliberately log credentials or personal data.'], examples: ['blinkhost logs --project PROJECT_ID --since 1h --limit 100 --json'], related: ['security', 'support', 'troubleshooting'], url: DOCUMENTATION_URL,
181
- },
182
- metrics: { name: 'metrics', title: 'Project metrics', summary: 'Read authorized metrics for a project.', usage: ['blinkhost metrics [--project ID] [--since DURATION]'], details: ['The command is read-only and accepts a linked project when --project is omitted.'], examples: ['blinkhost metrics --project PROJECT_ID --since 24h --json'], related: ['logs'], url: DOCUMENTATION_URL },
183
- analytics: { name: 'analytics', title: 'Project analytics', summary: 'Read authorized analytics for a project.', usage: ['blinkhost analytics [--project ID]'], details: ['The command is read-only and accepts a linked project when --project is omitted.'], examples: ['blinkhost analytics --project PROJECT_ID --json'], related: ['logs'], url: DOCUMENTATION_URL },
214
+ name: 'logs', title: 'Project observability', summary: 'Search or follow authorized logs for a linked or explicit project.',
215
+ usage: ['blinkhost logs [--project UUID] [--since DURATION|ISO_TIME | --hours N | --start-time ISO_TIME] [--end-time ISO_TIME] [--limit N] [--max-events N] [--cursor CURSOR]', 'blinkhost logs [--project UUID] --follow [FILTERS] [--max-events N]', 'FILTERS: --severity --event-kind --search --request-id --trace-id --source --operation --outcome --status-code --region --release-id --environment-kind --environment-id --deployment-id --preview-session-id --attribute-filters'],
216
+ details: ['--since accepts positive integer s/m/h/d durations up to 366 days or timezone-aware ISO timestamps with at most millisecond precision. It fixes start_time for every page. Default lookback: one hour. The API enforces permissions, retention and query bounds.',
217
+ '--limit is page size 1–200 (default 100); --max-events is total output 1–10,000 (default history 200, follow 10,000). History reads newest first and also stops at 1000 pages or 120 seconds. Resume --cursor with identical filters and the summary’s --start-time instead of recomputing --since.',
218
+ 'Preview-session selection implies preview and cannot combine with deployed environment/deployment IDs. Attribute filters use at most eight typed JSON predicates and 8192 UTF-8 bytes. Quote exact signed/unsigned 64-bit integer JSON; do not round it through a JavaScript Number.',
219
+ '--follow uses a scoped expiring ticket, 2.5-second polls, ten pages per poll, 1000-ID deduplication and at most three transient retries. Reconnect/full-window notices qualify gaps. Permission errors stop follow. Use retained history for interrupted intervals; --cursor is for history.',
220
+ '--json emits NDJSON event, notice and summary entries; failures may append the standard ok:false error object. Exact stored attributes retain integer tokens; a precision_notice identifies fallback values. Text quotes messages and escapes terminal controls.',
221
+ 'SIGINT/SIGTERM return 130/143 and attempt owned-query cancellation and ticket closure with independent timeouts. A stalled pipe may have incomplete output when interrupted; a closed pipe returns 4. No background update checks run for logs.',
222
+ 'Application logs can contain sensitive data. Do not deliberately log credentials or personal data. Review output before sharing it; use the redacted support bundle for platform diagnostics.'],
223
+ examples: ['blinkhost logs --project PROJECT_ID --since 1h --limit 100 --json', 'blinkhost logs --project PROJECT_ID --follow --severity error --max-events 1000', 'blinkhost logs --project PROJECT_ID --preview-session-id SESSION_UUID --json', 'blinkhost logs --project PROJECT_ID --attribute-filters \'[{"path":["order","id"],"op":"eq","type":"integer","value":18446744073709551615}]\' --json'], related: ['metrics', 'analytics', 'security', 'support', 'troubleshooting'], url: DOCUMENTATION_URL,
224
+ },
225
+ metrics: { name: 'metrics', title: 'Project metrics', summary: 'Read authorized metrics for a project.', usage: ['blinkhost metrics [--project ID] [--since DURATION] [--limit N]'], details: ['The command is read-only and accepts a linked project when --project is omitted. Duration --since uses positive integer s/m/h/d values, rounded up to whole hours; absolute timestamps are unsupported. The API enforces plan query bounds.'], examples: ['blinkhost metrics --project PROJECT_ID --since 24h --json'], related: ['logs'], url: DOCUMENTATION_URL },
226
+ analytics: { name: 'analytics', title: 'Project analytics', summary: 'Read authorized analytics for a project.', usage: ['blinkhost analytics [--project ID] [--since DURATION] [--limit N]'], details: ['The command is read-only and accepts a linked project when --project is omitted. Duration --since uses positive integer s/m/h/d values, rounded up to whole hours; absolute timestamps are unsupported. The API enforces plan query bounds.'], examples: ['blinkhost analytics --project PROJECT_ID --since 24h --json'], related: ['logs'], url: DOCUMENTATION_URL },
184
227
  support: {
185
228
  name: 'support', title: 'Redacted support bundles', summary: 'Create a local diagnostic inventory for support without including source or credentials.', usage: ['blinkhost support bundle [--output PATH]'], details: ['The file is created with mode 0600 and refuses to overwrite an existing path. It excludes tokens, secret values, source code, filenames and repository URLs.', 'Review the generated file before sharing it. The default filename is blinkhost-support-<timestamp>.json in the current directory.'], examples: ['blinkhost support bundle', 'blinkhost support bundle --output ./support.json'], related: ['security', 'troubleshooting'], url: DOCUMENTATION_URL,
186
229
  },
@@ -233,9 +276,9 @@ const TOPICS = {
233
276
  },
234
277
  };
235
278
  const COMMANDS = [
236
- 'quickstart', 'docs', 'create', 'init', 'validate', 'manifest', 'doctor', 'test', 'auth', 'ai', 'profile', 'projects',
279
+ 'quickstart', 'docs', 'design', 'create', 'init', 'validate', 'manifest', 'doctor', 'test', 'auth', 'ai', 'profile', 'projects',
237
280
  'repositories', 'connections', 'previews', 'builds', 'deployments', 'modules', 'functions', 'databases', 'bindings', 'assets',
238
- 'secrets', 'organizations', 'templates', 'approvals', 'handoffs', 'policies', 'workloads', 'dev', 'logs', 'metrics',
281
+ 'secrets', 'test-credentials', 'organizations', 'templates', 'approvals', 'handoffs', 'policies', 'workloads', 'dev', 'logs', 'metrics',
239
282
  'analytics', 'seo', 'support', 'completion', 'update', 'ci', 'plugins', 'api',
240
283
  ];
241
284
  export const TOP_LEVEL_COMMANDS = [...COMMANDS];
@@ -0,0 +1,3 @@
1
+ // Maximum request and response body sizes for the local frontend proxy.
2
+ export const BASELINE_REQUEST_BYTES = 5000000;
3
+ export const BASELINE_RESPONSE_BYTES = 5000000;
@@ -0,0 +1,2 @@
1
+ // Digest reported by a compatible local runtime in its health response.
2
+ export const RESOURCE_PROFILE_CONTRACT_SHA256 = "58087c03a711155a4f8f5472c76aae0a76a07d8ac5ab897235836f57f0753f5b";
@@ -0,0 +1,3 @@
1
+ export type LocalDevWriter = (value: string, signal: AbortSignal) => Promise<boolean>;
2
+ /** One foreground owner for the packaged local tool; no remote account APIs. */
3
+ export declare function runLocalDev(root: string, config: string, state: string, json: boolean, write?: LocalDevWriter, watchArtifact?: boolean, sourceBuildConfig?: string, watchSource?: boolean): Promise<unknown>;
@@ -0,0 +1,145 @@
1
+ import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
2
+ import { mkdir, rename, writeFile } from 'node:fs/promises';
3
+ import { CliError, EXIT } from './errors.js';
4
+ import { writeLogOutput } from './logs.js';
5
+ import { terminalJson, terminalText } from './terminal.js';
6
+ import { buildLocalSource, readSourceStackConfiguration } from './local-source-build.js';
7
+ import { watchLocalSource } from './local-source-watch.js';
8
+ /** One foreground owner for the packaged local tool; no remote account APIs. */
9
+ export async function runLocalDev(root, config, state, json, write = (value, signal) => writeLogOutput(process.stdout, value, signal), watchArtifact = false, sourceBuildConfig, watchSource = false) {
10
+ const controller = new AbortController();
11
+ let interruptSignal, stack, outputFailed = false;
12
+ let watching;
13
+ let sourceBuild;
14
+ let sourceContext;
15
+ const interrupt = () => { interruptSignal = 'SIGINT'; controller.abort(); };
16
+ const terminate = () => { interruptSignal = 'SIGTERM'; controller.abort(); };
17
+ const outputError = () => { outputFailed = true; controller.abort(); };
18
+ // Keep handling repeated interrupts until owned servers and compilers finish stopping.
19
+ // Removing the handler after the first signal lets the next one terminate cleanup.
20
+ process.on('SIGINT', interrupt);
21
+ process.on('SIGTERM', terminate);
22
+ process.stdout.on('error', outputError);
23
+ try {
24
+ if (watchSource && (!sourceBuildConfig || watchArtifact))
25
+ throw new CliError('Source watching requires a local source build without artifact watching.', EXIT.usage, 'local_source_watch_options_required');
26
+ const tool = new URL('./local-development/local-stack.mjs', import.meta.url);
27
+ const { startLocalStack, configuration } = await import(tool.href);
28
+ let configPath = resolve(root, config), statePath = resolve(root, state);
29
+ if (sourceBuildConfig !== undefined) {
30
+ if (watchArtifact)
31
+ throw new CliError('Source builds and separately compiled artifact watching require separate development runs.', EXIT.usage, 'local_source_build_watch_conflict');
32
+ const original = await readSourceStackConfiguration(configPath);
33
+ const validated = configuration(original.value, dirname(configPath));
34
+ const offset = relative(validated.frontend, statePath);
35
+ if (!offset || (!isAbsolute(offset) && offset !== '..' && !offset.startsWith('../'))) {
36
+ throw new CliError('Local source-build state must stay outside the served frontend.', EXIT.validation, 'local_source_build_state_in_frontend');
37
+ }
38
+ await mkdir(statePath, { mode: 0o700 });
39
+ sourceBuild = await buildLocalSource(root, sourceBuildConfig, join(statePath, 'build-001'), { signal: controller.signal });
40
+ if (controller.signal.aborted)
41
+ throw new Error('local_source_build_cancelled');
42
+ if ((await readSourceStackConfiguration(configPath)).sha256 !== original.sha256)
43
+ throw new Error('local_source_build_stack_configuration_changed');
44
+ if (!sourceBuild.artifact)
45
+ throw new Error('local_source_build_artifact_missing');
46
+ const generated = { ...original.value, runtime: validated.runtime, engine: validated.engine,
47
+ database: { ...original.value.database, executable: validated.database },
48
+ frontend: validated.frontend, artifact: { path: sourceBuild.artifact.path, sha256: sourceBuild.artifact.sha256 } };
49
+ configPath = join(statePath, 'compiled-stack.json');
50
+ await writeFile(configPath, JSON.stringify(generated, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
51
+ sourceContext = { directory: statePath, originalConfig: resolve(root, config), originalDigest: original.sha256,
52
+ compiledConfig: configPath, compiledDigest: (await readSourceStackConfiguration(configPath)).sha256, generated };
53
+ statePath = join(statePath, 'stack');
54
+ }
55
+ stack = await startLocalStack(configPath, statePath, { signal: controller.signal });
56
+ const output = json ? terminalJson(JSON.stringify({ ok: true, command: 'dev', event: 'ready', data: stack.manifest })) + '\n'
57
+ : terminalText(`Local frontend: ${stack.manifest.frontend}\nLocal runtime: ${stack.manifest.runtime}\nLocal database: ${stack.manifest.database}\nState: ${JSON.stringify(stack.manifest.state_directory)}\nPress Ctrl-C to stop this stack.\n`);
58
+ // A stalled readiness pipe must not retain the stack indefinitely.
59
+ const written = await write(output, AbortSignal.any([controller.signal, AbortSignal.timeout(3000)]));
60
+ if (!written) {
61
+ outputFailed = true;
62
+ controller.abort();
63
+ throw new CliError('Local development readiness output could not be delivered. The owned stack was stopped.', EXIT.filesystem, 'local_dev_output_failed');
64
+ }
65
+ if (watchSource && sourceBuildConfig && sourceBuild && sourceContext) {
66
+ const owned = stack, context = sourceContext;
67
+ const verifyConfiguration = async () => {
68
+ if ((await readSourceStackConfiguration(context.originalConfig)).sha256 !== context.originalDigest)
69
+ throw new Error('local_source_build_stack_configuration_changed');
70
+ if ((await readSourceStackConfiguration(context.compiledConfig)).sha256 !== context.compiledDigest)
71
+ throw new Error('local_source_build_generated_configuration_changed');
72
+ };
73
+ watching = watchLocalSource(root, sourceBuildConfig, context.directory, sourceBuild, async (build, verifySource) => {
74
+ await verifyConfiguration();
75
+ await verifySource();
76
+ if (!build.artifact)
77
+ throw new Error('local_source_build_artifact_missing');
78
+ const generated = { ...context.generated, artifact: { path: build.artifact.path, sha256: build.artifact.sha256 } };
79
+ const temporary = join(dirname(build.artifact.path), 'stack-candidate.json');
80
+ await writeFile(temporary, JSON.stringify(generated, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
81
+ await verifyConfiguration();
82
+ await verifySource();
83
+ await rename(temporary, context.compiledConfig);
84
+ context.compiledDigest = (await readSourceStackConfiguration(context.compiledConfig)).sha256;
85
+ const result = await owned.reload({ verifyCandidate: async () => { await verifyConfiguration(); await verifySource(); } });
86
+ if (result.status !== 'rejected')
87
+ sourceBuild = build;
88
+ return result;
89
+ }, () => owned.runtimeAvailable, async (event) => {
90
+ const value = json ? terminalJson(JSON.stringify({ ok: event.status !== 'rejected', command: 'dev',
91
+ event: event.status === 'reloaded' ? 'reloaded' : event.status === 'unchanged' ? 'build_unchanged' : 'build_failed', data: event })) + '\n'
92
+ : terminalText(event.status === 'reloaded' ? 'Local source rebuilt and module reloaded.\n'
93
+ : event.status === 'unchanged' ? 'Local source rebuilt; the compiled module is unchanged.\n'
94
+ : `Local source rebuild rejected: ${event.error ?? 'local_source_rebuild_failed'}.${event.watching_stopped ? ' Watching stopped; start a new development run.' : ' Inspect the retained build evidence.'}\n`);
95
+ if (!await write(value, AbortSignal.any([controller.signal, AbortSignal.timeout(3000)])))
96
+ throw new Error('local_dev_output_failed');
97
+ }, { signal: controller.signal });
98
+ watching.catch(() => { outputFailed = true; controller.abort(); });
99
+ }
100
+ else if (watchArtifact) {
101
+ const watcher = new URL('./local-development/artifact-watch.mjs', import.meta.url);
102
+ const { watchLocalArtifacts } = await import(watcher.href);
103
+ watching = watchLocalArtifacts(stack, resolve(root, config), async (event) => {
104
+ const value = json ? terminalJson(JSON.stringify({ ok: event.status === 'reloaded', command: 'dev',
105
+ event: event.status === 'reloaded' ? 'reloaded' : 'reload_failed', data: event })) + '\n'
106
+ : terminalText(event.status === 'reloaded' ? 'Local module reloaded.\n'
107
+ : `Local module reload rejected: ${event.error ?? 'local_stack_reload_failed'}. Inspect the retained state.\n`);
108
+ if (!await write(value, AbortSignal.any([controller.signal, AbortSignal.timeout(3000)]))) {
109
+ throw new Error('local_dev_output_failed');
110
+ }
111
+ }, { signal: controller.signal });
112
+ watching.catch(() => { outputFailed = true; controller.abort(); });
113
+ }
114
+ const stopped = await stack.closed;
115
+ if (outputFailed)
116
+ throw new CliError('Local development output closed. The owned stack was stopped.', EXIT.filesystem, 'local_dev_output_failed');
117
+ if (stopped.status === 'failed' || !stopped.children_stopped) {
118
+ throw new CliError('A local stack process failed. Inspect the retained process logs and stopped.json in your state directory.', EXIT.remote, 'local_stack_process_failed');
119
+ }
120
+ return { schema: 'blinkhost.local-dev/v1', status: stopped.status, stack: stack.manifest,
121
+ shutdown: stopped, exit_code: 0, production_authority: false,
122
+ ...(sourceBuild ? { source_build: sourceBuild } : {}) };
123
+ }
124
+ catch (error) {
125
+ if (outputFailed)
126
+ throw new CliError('Local development output closed. The owned stack was stopped.', EXIT.filesystem, 'local_dev_output_failed');
127
+ if (interruptSignal)
128
+ throw new CliError('Local stack startup was interrupted.', interruptSignal === 'SIGINT' ? 130 : 143, 'local_stack_startup_interrupted');
129
+ if (error instanceof CliError)
130
+ throw error;
131
+ const code = error instanceof Error && /^[a-z_]{1,96}$/.test(error.message) ? error.message : 'local_stack_start_failed';
132
+ throw new CliError('Local stack startup failed. Check your explicit configuration, pinned tools and retained state evidence.', EXIT.validation, code);
133
+ }
134
+ finally {
135
+ controller.abort();
136
+ if (stack)
137
+ await stack.stop();
138
+ if (watching)
139
+ await watching.catch(() => { });
140
+ process.off('SIGINT', interrupt);
141
+ process.off('SIGTERM', terminate);
142
+ process.stdout.off('error', outputError);
143
+ }
144
+ }
145
+ //# sourceMappingURL=local-dev.js.map