@blinkhost/cli 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BLINKHOST LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# BlinkHost CLI
+
+The BlinkHost CLI brings project setup, local development, source control, previews, builds, releases, resources, and diagnostics into the terminal while BlinkHost continues to enforce workspace roles, plan limits, protected environments, verified artifacts, and audit history.
+
+## Install
+
+Node.js 22.12 or newer is required.
+
+Install the signed release archive directly from BlinkHost's public repository:
+
+```bash
+npm install --global https://github.com/blinkhost-ltd/blinkhost-cli/releases/download/v2.0.0/blinkhost-cli-2.0.0.tgz
+blinkhost --version
+```
+
+Checksums, the CycloneDX SBOM, and Sigstore verification bundle are published with the archive at <https://github.com/blinkhost-ltd/blinkhost-cli/releases/tag/v2.0.0>.
+
+## Connect an account
+
+```bash
+blinkhost auth login
+blinkhost auth status
+blinkhost auth sessions
+```
+
+The CLI opens a BlinkHost approval page in your browser. It never accepts your BlinkHost password. Access tokens last 15 minutes; rotating refresh credentials are stored only in the operating-system credential service. Use named profiles for separate accounts:
+
+```bash
+blinkhost auth login --profile work
+blinkhost profile use work
+```
+
+Revoke a device with `blinkhost auth revoke SESSION_ID` or disconnect all CLI sessions for the active profile with `blinkhost auth logout`.
+
+## Create or adopt a project
+
+```bash
+blinkhost create study-circle --template astro --module search:rust --module reminders:python --database PRIMARY_DB
+cd study-circle
+blinkhost validate
+blinkhost projects link PROJECT_ID
+blinkhost dev
+```
+
+Supported frontends are Astro, HTML, React, Solid, Svelte, and Vue. Backend modules may use Go, Python, or Rust. `blinkhost init` detects supported metadata in an existing repository and creates `blinkhost.yaml` for review.
+
+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.
+
+## Remote workflows
+
+Resource commands use the same pattern:
+
+```bash
+blinkhost projects list
+blinkhost projects get PROJECT_ID
+blinkhost previews list --query project=PROJECT_ID
+blinkhost builds list --query project=PROJECT_ID
+blinkhost deployments get DEPLOYMENT_ID
+blinkhost modules list --query site_id=PROJECT_ID
+blinkhost databases list --query project=PROJECT_ID
+blinkhost organizations get ORGANIZATION_ID
+```
+
+Create and update operations accept a JSON object or `@path` to a JSON file:
+
+```bash
+blinkhost projects create --data @project.json
+blinkhost deployments action DEPLOYMENT_ID rollback --data @rollback.json
+```
+
+Destructive operations require the exact resource ID twice:
+
+```bash
+blinkhost previews delete PREVIEW_ID --confirm PREVIEW_ID
+```
+
+Connected repository, release, approval, agency handoff, enterprise policy, and template APIs are available through `repositories`, `connections`, `builds`, `approvals`, `handoffs`, `policies`, and `templates`. Advanced customer API operations can use `blinkhost api METHOD /api/path/`; internal, staff, and authentication routes are blocked.
+
+## Secrets and resources
+
+Secret values never appear in command arguments or `blinkhost.yaml`. Pipe them over standard input:
+
+```bash
+printf '%s' "$MY_SECRET" | blinkhost secrets set API_TOKEN --project PROJECT_ID --environment production
+printf '%s' "$NEW_VALUE" | blinkhost secrets rotate SECRET_ID
+```
+
+Database, binding, module, and asset operations remain subject to workspace permissions and plan storage limits. Upload reservations and final integrity checks use the project asset API.
+
+## Observability and support
+
+```bash
+blinkhost logs --project PROJECT_ID --since 1h --limit 100
+blinkhost metrics --project PROJECT_ID --since 24h
+blinkhost analytics --project PROJECT_ID
+blinkhost doctor
+blinkhost support bundle
+```
+
+Support bundles are local, redacted JSON files with mode `0600`. They exclude tokens, secret values, source code, filenames, and repository URLs.
+
+## CI and automation
+
+All commands support `--json`. 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.
+
+```bash
+blinkhost workloads create --data @workload.json
+```
+
+`workload.json` identifies the workspace, exact GitHub OIDC subject, and narrow permissions. For non-GitHub systems, an externally issued short-lived credential may be provided as `BLINKHOST_ACCESS_TOKEN`; do not persist it in the repository or pass it as an argument.
+
+```bash
+blinkhost ci check --json
+blinkhost validate --json
+blinkhost builds create --data @build.json --json
+```
+
+Stable exit codes distinguish usage, validation, filesystem, authentication, network, remote-service, and conflict failures. Mutations include request identifiers and idempotency keys.
+
+## Shell completion, updates, and plugins
+
+```bash
+blinkhost completion bash   # also zsh, fish, or powershell
+blinkhost update check
+blinkhost plugins add /absolute/path/to/plugin --name example
+blinkhost plugins verify example
+blinkhost plugins run example -- arguments
+```
+
+Update checks never install software. Plugins require explicit local approval, are pinned to their executable SHA-256 digest, stop when the executable changes, and receive neither BlinkHost credentials nor the parent environment. A plugin is still third-party code running with your operating-system account; review it before adding it.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Invalid command or option |
+| 3 | Project or input validation failed |
+| 4 | Filesystem or local executable failure |
+| 5 | Unexpected internal failure |
+| 6 | Authentication or authorization failure |
+| 7 | Network or timeout failure |
+| 8 | Remote service failure |
+| 9 | State conflict or approval required |
+
+Run `blinkhost --help` for the complete command index.

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+import { type Profile } from './config.js';
+export declare function publicRequest(apiOrigin: string, path: string, init?: RequestInit): Promise<{
+    response: Response;
+    data: unknown;
+}>;
+export declare class ApiClient {
+    readonly profileName: string;
+    readonly profile: Profile;
+    private readonly ephemeral;
+    private accessToken;
+    private constructor();
+    static create(profileName?: string): Promise<ApiClient>;
+    static fromAccessToken(profileName: string, profile: Profile, accessToken: string): ApiClient;
+    request(path: string, init?: RequestInit): Promise<unknown>;
+    rememberIdentity(identity: {
+        id?: number;
+        username?: string;
+    }): Promise<void>;
+}
+export declare function encodeQuery(values: Record<string, string | undefined>): string;

package/dist/api.js

@@ -0,0 +1,135 @@
+import { randomUUID } from 'node:crypto';
+import { activeProfile, writeConfig } from './config.js';
+import { deleteRefreshCredential, getRefreshCredential, setRefreshCredential } from './credentials.js';
+import { CliError, EXIT } from './errors.js';
+const REQUEST_TIMEOUT_MS = 30_000;
+function messageFrom(payload, fallback) {
+    if (payload && typeof payload === 'object') {
+        const candidate = payload;
+        for (const key of ['detail', 'error', 'message'])
+            if (typeof candidate[key] === 'string')
+                return candidate[key];
+        const first = Object.values(candidate)[0];
+        if (Array.isArray(first) && typeof first[0] === 'string')
+            return first[0];
+    }
+    return fallback;
+}
+async function parseResponse(response) {
+    if (response.status === 204)
+        return null;
+    const type = response.headers.get('content-type') || '';
+    if (type.includes('application/json'))
+        return response.json();
+    const text = await response.text();
+    return text.length <= 1024 * 1024 ? text : `${text.slice(0, 1024 * 1024)}\n[truncated]`;
+}
+export async function publicRequest(apiOrigin, path, init = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetch(new URL(path, `${apiOrigin}/`), {
+            ...init,
+            redirect: 'error',
+            signal: controller.signal,
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': 'BlinkHost-CLI/2.0.0', ...Object.fromEntries(new Headers(init.headers).entries()) },
+        });
+        return { response, data: await parseResponse(response) };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        const timeoutMessage = error instanceof DOMException && error.name === 'AbortError';
+        throw new CliError(timeoutMessage ? 'The BlinkHost API request timed out.' : 'The BlinkHost API could not be reached.', EXIT.network, timeoutMessage ? 'request_timeout' : 'network_error');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export class ApiClient {
+    profileName;
+    profile;
+    ephemeral;
+    accessToken;
+    constructor(profileName, profile, accessToken, ephemeral) {
+        this.profileName = profileName;
+        this.profile = profile;
+        this.ephemeral = ephemeral;
+        this.accessToken = accessToken;
+    }
+    static async create(profileName) {
+        const selected = await activeProfile(profileName);
+        const workload = process.env.BLINKHOST_ACCESS_TOKEN;
+        if (workload)
+            return new ApiClient(selected.name, selected.profile, workload, true);
+        if (process.env.ACTIONS_ID_TOKEN_REQUEST_URL && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) {
+            const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+            const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+            let oidcUrl;
+            try {
+                oidcUrl = new URL(requestUrl);
+            }
+            catch {
+                throw new CliError('GitHub Actions supplied an invalid OIDC endpoint.', EXIT.auth, 'ci_oidc_invalid');
+            }
+            if (oidcUrl.protocol !== 'https:' || !(oidcUrl.hostname === 'actions.githubusercontent.com' || oidcUrl.hostname.endsWith('.actions.githubusercontent.com')))
+                throw new CliError('GitHub Actions supplied an untrusted OIDC endpoint.', EXIT.auth, 'ci_oidc_invalid');
+            oidcUrl.searchParams.set('audience', 'https://api.blinkhost.me/api/cli/v2/workload/exchange/');
+            const oidcResponse = await fetch(oidcUrl, { headers: { Authorization: `Bearer ${requestToken}`, Accept: 'application/json' }, redirect: 'error' });
+            const oidc = await oidcResponse.json();
+            if (!oidcResponse.ok || !oidc.value)
+                throw new CliError('GitHub Actions could not issue a workload identity token.', EXIT.auth, 'ci_oidc_failed');
+            const exchanged = await publicRequest(selected.profile.apiOrigin, '/api/cli/v2/workload/exchange/', { method: 'POST', body: JSON.stringify({ assertion: oidc.value }) });
+            const payload = exchanged.data;
+            if (!exchanged.response.ok || !payload.access_token)
+                throw new CliError(payload.detail || 'BlinkHost rejected this workload identity.', EXIT.auth, 'ci_exchange_failed');
+            return new ApiClient(selected.name, selected.profile, payload.access_token, true);
+        }
+        const refresh = process.env.BLINKHOST_REFRESH_TOKEN || await getRefreshCredential(selected.name);
+        if (!refresh)
+            throw new CliError('Sign in with `blinkhost auth login` or provide BLINKHOST_ACCESS_TOKEN for CI.', EXIT.auth, 'not_authenticated');
+        const result = await publicRequest(selected.profile.apiOrigin, '/api/cli/v2/token/refresh/', { method: 'POST', body: JSON.stringify({ refresh_token: refresh }) });
+        if (!result.response.ok) {
+            if (!process.env.BLINKHOST_REFRESH_TOKEN)
+                await deleteRefreshCredential(selected.name);
+            throw new CliError(messageFrom(result.data, 'Your CLI session has expired. Sign in again.'), EXIT.auth, 'session_expired');
+        }
+        const tokens = result.data;
+        if (!process.env.BLINKHOST_REFRESH_TOKEN)
+            await setRefreshCredential(selected.name, tokens.refresh_token);
+        return new ApiClient(selected.name, selected.profile, tokens.access_token, Boolean(process.env.BLINKHOST_REFRESH_TOKEN));
+    }
+    static fromAccessToken(profileName, profile, accessToken) {
+        return new ApiClient(profileName, profile, accessToken, true);
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set('Authorization', `Bearer ${this.accessToken}`);
+        headers.set('X-Request-ID', headers.get('X-Request-ID') || randomUUID());
+        if (init.method && init.method !== 'GET' && !headers.has('Idempotency-Key'))
+            headers.set('Idempotency-Key', randomUUID());
+        const result = await publicRequest(this.profile.apiOrigin, path, { ...init, headers });
+        if (!result.response.ok) {
+            const exit = result.response.status === 401 || result.response.status === 403 ? EXIT.auth : result.response.status === 409 ? EXIT.conflict : EXIT.remote;
+            throw new CliError(messageFrom(result.data, `BlinkHost returned HTTP ${result.response.status}.`), exit, `api_${result.response.status}`);
+        }
+        return result.data;
+    }
+    async rememberIdentity(identity) {
+        if (this.ephemeral)
+            return;
+        const selected = await activeProfile(this.profileName);
+        selected.config.profiles[this.profileName] = { ...this.profile, ...(identity.id ? { userId: identity.id } : {}), ...(identity.username ? { username: identity.username } : {}) };
+        selected.config.activeProfile = this.profileName;
+        await writeConfig(selected.config);
+    }
+}
+export function encodeQuery(values) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined)
+            query.set(key, value);
+    const text = query.toString();
+    return text ? `?${text}` : '';
+}
+//# sourceMappingURL=api.js.map

package/dist/auth.d.ts

@@ -0,0 +1,9 @@
+export declare function login(options: {
+    profile?: string;
+    apiOrigin?: string;
+    openBrowser?: boolean;
+    progress?: (line: string) => void;
+}): Promise<unknown>;
+export declare function logout(profile?: string): Promise<{
+    profile: string;
+}>;

package/dist/auth.js

@@ -0,0 +1,71 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { spawn } from 'node:child_process';
+import { activeProfile, validateApiOrigin, validateProfileName, writeConfig } from './config.js';
+import { deleteRefreshCredential, setRefreshCredential } from './credentials.js';
+import { ApiClient, publicRequest } from './api.js';
+import { CliError, EXIT } from './errors.js';
+const VERSION = '2.0.0';
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd.exe' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore', shell: false });
+    child.on('error', () => { });
+    child.unref();
+}
+function errorCode(data) {
+    return data && typeof data === 'object' && typeof data.error === 'string' ? data.error : '';
+}
+export async function login(options) {
+    const selected = await activeProfile(options.profile);
+    const profileName = validateProfileName(options.profile || selected.name);
+    const apiOrigin = validateApiOrigin(options.apiOrigin || selected.profile.apiOrigin);
+    const verifier = randomBytes(48).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    const started = await publicRequest(apiOrigin, '/api/cli/v2/device/start/', {
+        method: 'POST',
+        body: JSON.stringify({ code_challenge: challenge, client_name: 'BlinkHost CLI', client_version: VERSION, device_name: hostname().slice(0, 120) }),
+    });
+    if (!started.response.ok)
+        throw new CliError('BlinkHost could not start CLI authorization.', EXIT.auth, errorCode(started.data) || 'authorization_start_failed');
+    const device = started.data;
+    options.progress?.(`Open ${device.verification_uri_complete}`);
+    options.progress?.(`Confirm code ${device.user_code}`);
+    if (options.openBrowser !== false)
+        openBrowser(device.verification_uri_complete);
+    const deadline = Date.now() + device.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(Math.max(device.interval, 5) * 1000);
+        const polled = await publicRequest(apiOrigin, '/api/cli/v2/device/poll/', { method: 'POST', body: JSON.stringify({ device_code: device.device_code, code_verifier: verifier }) });
+        const code = errorCode(polled.data);
+        if (code === 'authorization_pending' || code === 'slow_down')
+            continue;
+        if (!polled.response.ok)
+            throw new CliError(code === 'access_denied' ? 'CLI authorization was denied.' : 'CLI authorization could not be completed.', EXIT.auth, code || 'authorization_failed');
+        const tokens = polled.data;
+        await setRefreshCredential(profileName, tokens.refresh_token);
+        selected.config.profiles[profileName] = { apiOrigin };
+        selected.config.activeProfile = profileName;
+        await writeConfig(selected.config);
+        const client = await ApiClient.create(profileName);
+        const capabilities = await client.request('/api/cli/v2/capabilities/');
+        await client.rememberIdentity(capabilities.actor || {});
+        return { profile: profileName, api_origin: apiOrigin, account: capabilities.actor, permissions: capabilities.features };
+    }
+    throw new CliError('CLI authorization expired before it was approved.', EXIT.auth, 'authorization_expired');
+}
+export async function logout(profile) {
+    const selected = await activeProfile(profile);
+    try {
+        const client = await ApiClient.create(selected.name);
+        await client.request('/api/cli/v2/sessions/current/', { method: 'DELETE' });
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || error.code !== 'session_expired')
+            throw error;
+    }
+    await deleteRefreshCredential(selected.name);
+    return { profile: selected.name };
+}
+//# sourceMappingURL=auth.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;