tovuk 0.1.47

package/README.md

@@ -0,0 +1,72 @@
+# tovuk
+
+Deploy Rust backends and static frontends to Tovuk.
+
+```sh
+npx tovuk init my-app --template fullstack-rust-tanstack
+cd my-app/web && bun install && cd ..
+npx tovuk doctor --json
+npx tovuk deploy --wait --json
+```
+
+`npx tovuk` is the public npm command.
+
+Rust backends expect `Cargo.toml`, `Cargo.lock`, and `tovuk.toml`. They must
+pass `cargo fmt --all --check`, locked Cargo checks, listen on
+`0.0.0.0:$PORT`, and expose the configured health endpoint.
+
+Static frontends must use TypeScript browser source, stable native type-aware
+TypeScript checks, native linting such as `oxlint`, `biome check`, or
+`deno lint`, and Fallow dead-code, semantic duplicate-code, and health gates.
+
+From a full-stack repo root, the same deploy command discovers nested
+`tovuk.toml` files and deploys the whole workspace in one command.
+
+Preview before deploying:
+
+```sh
+npx tovuk preview
+```
+
+Agent repair loop:
+
+```sh
+npx tovuk doctor --json
+npx tovuk deploy --wait --json
+npx tovuk logs --build job_1 --json
+```
+
+Fix the first failed `agent_instruction`. If a build fails, inspect build logs,
+fix the first actionable log error, rerun doctor, then redeploy.
+
+Managed Postgres apps receive `DATABASE_URL`, `TOVUK_DATABASE_URL`, and
+`TOVUK_DATABASE_CONNECTION_LIMIT`. Use that limit as the max size for your
+database pool.
+
+Agents can also inspect API capabilities, account identity, usage, account
+activity, apps, complete app overviews, deploys, builds, app/deploy/build logs,
+env metadata, custom domains, domain verification, billing checkout links,
+billing portal links, and support ticket create, list, and resolve actions
+through the same CLI.
+
+When a free-tier limit blocks work, run:
+
+```sh
+npx tovuk billing checkout --json
+```
+
+When Tovuk support is needed, include enough evidence for a support agent:
+
+```sh
+npx tovuk support create "Deploy failed" "Agent retried deploy after doctor." --app app_1 --build job_1 --deploy deploy_1 --failing-command "npx tovuk deploy --wait --json" --first-log-line "cargo check failed in src/main.rs" --json
+```
+
+When the issue is fixed, resolve the ticket:
+
+```sh
+npx tovuk support resolve ticket_0123456789abcdef0123 --json
+```
+
+On first deploy, the CLI opens browser login, waits for GitHub or Google, stores
+the Tovuk session in the OS credential store when available, and continues the
+deploy. Later commands reuse that session.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "tovuk",
+  "version": "0.1.47",
+  "description": "Deploy Rust backends and static frontends to Tovuk.",
+  "type": "module",
+  "bin": {
+    "tovuk": "src/tovuk.ts"
+  },
+  "files": [
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "tovuk",
+    "rust",
+    "deploy",
+    "backend",
+    "hosting"
+  ],
+  "homepage": "https://tovuk.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tovuk/tovuk.git",
+    "directory": "packages/tovuk"
+  },
+  "bugs": {
+    "url": "https://github.com/tovuk/tovuk/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "tsx": "^4.22.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "fallow": "^2.84.0",
+    "oxlint": "^1.67.0",
+    "oxlint-tsgolint": "^0.23.0"
+  },
+  "scripts": {
+    "check": "npm run check:policy && npm run typecheck && npm run lint && npm run lint:dead && npm run lint:dupes && npm run lint:health && npm run check:deps && npm run runtime && npm run pack:dry",
+    "check:policy": "node ../../scripts/check-npm-cli-package.mjs",
+    "typecheck": "oxlint src --deny-warnings --type-aware --type-check --tsconfig tsconfig.json",
+    "lint": "oxlint src -D correctness -D suspicious -D perf -A no-await-in-loop --deny-warnings --type-aware --type-check --tsconfig tsconfig.json --promise-plugin --node-plugin --report-unused-disable-directives",
+    "lint:dead": "fallow dead-code --production --include-dupes --include-entry-exports --fail-on-issues",
+    "lint:dupes": "fallow dupes --production --mode semantic --threshold 1 --ignore-imports --fail-on-issues; dupes=$(fallow dupes --production --mode semantic --threshold 1 --ignore-imports --format json | jq '.clone_groups | length'); test \"$dupes\" = 0",
+    "lint:health": "fallow health --production --max-cyclomatic 10 --max-cognitive 15 --max-crap 20 --complexity --format json | jq -e '[.findings[] | select(.severity == \"critical\")] | length == 0' >/dev/null && fallow health --production --score --format json | jq -e '.health_score.score >= 90' >/dev/null",
+    "check:deps": "npm ls --all && npm audit --audit-level=moderate && npm audit signatures --omit=dev --json",
+    "runtime": "src/tovuk.ts --version",
+    "pack:dry": "npm pack --dry-run"
+  }
+}

package/src/internal/agent-error-enrichment.ts

@@ -0,0 +1,94 @@
+import { TovukError } from './errors.ts'
+import { isJsonObject, parseJson, stringField } from './json.ts'
+import type { AgentErrorPayload, CliOptions, JsonValue } from './types.ts'
+
+interface AgentErrorContext {
+  cli: CliOptions
+  route: string
+  token: string | null
+}
+
+const BILLING_CHECKOUT_ROUTE = '/v1/billing/checkout'
+
+async function enrichAgentErrorPayload(
+  context: AgentErrorContext,
+  payload: AgentErrorPayload
+): Promise<void> {
+  if (!shouldCreateCheckoutUrl(context, payload)) {
+    return
+  }
+
+  const checkoutUrl = await createCheckoutUrl(context.cli, context.token, payload.message)
+  if (checkoutUrl) {
+    payload.checkout_url = checkoutUrl
+  }
+}
+
+async function paymentRequiredAgentError(
+  cli: CliOptions,
+  token: string,
+  message: string,
+  agentInstruction: string
+): Promise<TovukError> {
+  const payload: AgentErrorPayload = {
+    code: 'payment_required',
+    message,
+    agent_instruction: agentInstruction,
+    docs_url: null,
+    checkout_url: null
+  }
+  await enrichAgentErrorPayload({ cli, route: 'local:preflight', token }, payload)
+  return new TovukError(payload, cli.json, 1)
+}
+
+function shouldCreateCheckoutUrl(
+  context: AgentErrorContext,
+  payload: AgentErrorPayload
+): boolean {
+  return payload.code === 'payment_required'
+    && !payload.checkout_url
+    && Boolean(context.token)
+    && context.route !== BILLING_CHECKOUT_ROUTE
+}
+
+async function createCheckoutUrl(
+  cli: CliOptions,
+  token: string | null,
+  reason: string
+): Promise<string> {
+  if (!token) {
+    return ''
+  }
+
+  try {
+    const response = await fetch(`${cli.apiUrl}${BILLING_CHECKOUT_ROUTE}`, {
+      body: JSON.stringify({
+        reason: reason || 'Plan limit reached.',
+        target_plan: 'pro'
+      }),
+      headers: new Headers({
+        accept: 'application/json',
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json'
+      }),
+      method: 'POST'
+    })
+    if (!response.ok) {
+      return ''
+    }
+    return checkoutUrlFromJson(parseJson(await response.text()))
+  } catch {
+    return ''
+  }
+}
+
+function checkoutUrlFromJson(value: JsonValue | null): string {
+  if (!isJsonObject(value)) {
+    return ''
+  }
+  const checkoutValue = value['checkout'] ?? null
+  const checkout = isJsonObject(checkoutValue) ? checkoutValue : {}
+  return stringField(checkout, 'url')
+}
+
+export { enrichAgentErrorPayload, paymentRequiredAgentError }

package/src/internal/api-models.ts

@@ -0,0 +1,133 @@
+import {
+  isJsonObject,
+  jsonArrayField,
+  jsonObjectField,
+  jsonObjectOrEmpty,
+  numberField,
+  optionalJsonObjectField,
+  stringField
+} from './json.ts'
+import type {
+  AppsResponse,
+  AppSummary,
+  BuildRecord,
+  BuildStatusResponse,
+  CheckoutResponse,
+  DeployResponse,
+  JsonObject,
+  JsonValue,
+  LogLine,
+  LogsResponse
+} from './types.ts'
+
+function appsResponseFromJson(value: JsonValue | null): AppsResponse {
+  return {
+    apps: jsonArrayField(jsonObjectOrEmpty(value), 'apps')
+      .map(appSummaryFromJson)
+      .filter((app): app is AppSummary => app !== null)
+  }
+}
+
+function appSummaryFromJson(value: JsonValue): AppSummary | null {
+  if (!isJsonObject(value)) {
+    return null
+  }
+  const app: AppSummary = {}
+  const id = stringField(value, 'id')
+  const name = stringField(value, 'name')
+  const url = stringField(value, 'url')
+  const databaseStorageMib = numberField(value, 'databaseStorageMib')
+  if (id) {
+    app.id = id
+  }
+  if (name) {
+    app.name = name
+  }
+  if (url) {
+    app.url = url
+  }
+  if (databaseStorageMib > 0) {
+    app.databaseStorageMib = databaseStorageMib
+  }
+  return app
+}
+
+function deployResponseFromJson(value: JsonValue | null): DeployResponse {
+  const source = jsonObjectOrEmpty(value)
+  const finalBuild = optionalJsonObjectField(source, 'final_build')
+  const response: DeployResponse = {
+    app: appDeployTargetFromJson(jsonObjectField(source, 'app')),
+    build_job: {
+      id: stringField(jsonObjectField(source, 'build_job'), 'id')
+    }
+  }
+  if (finalBuild) {
+    response.final_build = buildRecordFromJson(finalBuild)
+  }
+  return response
+}
+
+function appDeployTargetFromJson(source: JsonObject): DeployResponse['app'] {
+  return {
+    id: idFromJson(source),
+    url: stringField(source, 'url')
+  }
+}
+
+function buildStatusResponseFromJson(value: JsonValue | null): BuildStatusResponse {
+  const source = jsonObjectOrEmpty(value)
+  const build = optionalJsonObjectField(source, 'build')
+  return build ? { build: buildRecordFromJson(build) } : {}
+}
+
+function buildRecordFromJson(source: JsonObject): BuildRecord {
+  return {
+    id: idFromJson(source),
+    status: stringField(source, 'status')
+  }
+}
+
+function idFromJson(source: JsonObject): string {
+  return stringField(source, 'id')
+}
+
+function logsResponseFromJson(value: JsonValue | null): LogsResponse {
+  const source = jsonObjectOrEmpty(value)
+  const lines = jsonArrayField(source, 'lines')
+    .map(logLineFromJson)
+    .filter((line): line is LogLine => line !== null)
+  return {
+    lines,
+    has_more: source['has_more'] === true,
+    next_cursor: stringField(source, 'next_cursor')
+  }
+}
+
+function logLineFromJson(value: JsonValue): LogLine | null {
+  if (!isJsonObject(value)) {
+    return null
+  }
+  const timestamp = stringField(value, 'timestamp')
+  const stream = stringField(value, 'stream')
+  const message = stringField(value, 'message')
+  return timestamp && stream && message ? { timestamp, stream, message } : null
+}
+
+function checkoutResponseFromJson(value: JsonValue | null): CheckoutResponse {
+  const source = jsonObjectOrEmpty(value)
+  const checkout = jsonObjectField(source, 'checkout')
+  return {
+    checkout: {
+      reason: stringField(checkout, 'reason'),
+      url: stringField(checkout, 'url')
+    }
+  }
+}
+
+export {
+  appsResponseFromJson,
+  buildStatusResponseFromJson,
+  checkoutResponseFromJson,
+  deployResponseFromJson,
+  logsResponseFromJson
+}

package/src/internal/api.ts

@@ -0,0 +1,77 @@
+import { TovukError, agentError } from './errors.ts'
+import { enrichAgentErrorPayload } from './agent-error-enrichment.ts'
+import { isJsonObject, parseJson } from './json.ts'
+import type { AgentErrorPayload, ApiMethod, CliOptions, JsonValue } from './types.ts'
+
+function requireApp(cli: CliOptions): string {
+  if (!cli.app) {
+    throw agentError('missing_app', 'App is required.', 'Pass `--app <app>` using either the app name from tovuk.toml or the app id printed by deploy.', cli.json)
+  }
+  return cli.app
+}
+
+function pageQuery(cli: CliOptions): string {
+  const params = new URLSearchParams()
+  if (cli.limit) {
+    params.set('limit', cli.limit)
+  }
+  if (cli.cursor) {
+    params.set('cursor', cli.cursor)
+  }
+  const value = params.toString()
+  return value ? `?${value}` : ''
+}
+
+async function apiRequest(
+  cli: CliOptions,
+  method: ApiMethod,
+  route: string,
+  token: string | null,
+  body: JsonValue | null
+): Promise<JsonValue | null> {
+  const headers = new Headers({ accept: 'application/json' })
+  if (token) {
+    headers.set('authorization', `Bearer ${token}`)
+  }
+  if (body !== null) {
+    headers.set('content-type', 'application/json')
+  }
+
+  const init: RequestInit = {
+    method,
+    headers
+  }
+  if (body !== null) {
+    init.body = JSON.stringify(body)
+  }
+  const response = await fetch(`${cli.apiUrl}${route}`, init)
+
+  const text = await response.text()
+  const data = parseJson(text)
+  if (!response.ok) {
+    const payload: AgentErrorPayload = isAgentErrorPayload(data) ? data : {
+      code: 'api_error',
+      message: `Tovuk API returned HTTP ${response.status}.`,
+      agent_instruction: 'Retry the command. If it keeps failing, check Tovuk status before changing your project.',
+      docs_url: null,
+      checkout_url: null
+    }
+    await enrichAgentErrorPayload({ cli, route, token }, payload)
+    throw new TovukError(payload, cli.json, response.status >= 500 ? 2 : 1)
+  }
+
+  return data
+}
+
+function isAgentErrorPayload(value: JsonValue | null): value is AgentErrorPayload {
+  return isJsonObject(value)
+    && typeof value['code'] === 'string'
+    && typeof value['message'] === 'string'
+    && (typeof value['agent_instruction'] === 'string' || value['agent_instruction'] === null)
+}
+
+export {
+  requireApp,
+  pageQuery,
+  apiRequest
+}

package/src/internal/archive.ts

@@ -0,0 +1,35 @@
+import { spawnSync } from 'node:child_process'
+import { ARCHIVE_EXCLUDES, ARCHIVE_LIMIT_BYTES } from './constants.ts'
+import { agentError } from './errors.ts'
+
+function createArchiveBase64(projectDir: string): string {
+  const excludeArgs = ARCHIVE_EXCLUDES.map((pattern) => `--exclude=${pattern}`)
+  const tar = spawnSync('tar', [...excludeArgs, '-czf', '-', '-C', projectDir, '.'], {
+    encoding: 'buffer',
+    env: { ...process.env, COPYFILE_DISABLE: '1' },
+    maxBuffer: ARCHIVE_LIMIT_BYTES + 1024 * 1024
+  })
+
+  if (tar.error) {
+    throw agentError('archive_failed', 'Could not create source archive.', 'Install `tar`, remove local build outputs, then retry `npx tovuk deploy`.', false)
+  }
+  if (tar.status !== 0) {
+    throw agentError('archive_failed', 'Could not create source archive.', String(tar.stderr || 'Check project files and retry.'), false)
+  }
+  if (tar.stdout.length > ARCHIVE_LIMIT_BYTES) {
+    throw agentError('archive_too_large', 'Source archive is too large.', 'Remove build outputs, target directories, logs, and local caches before deploying.', false)
+  }
+
+  return tar.stdout.toString('base64')
+}
+
+function gitCommitSha(projectDir: string): string | null {
+  const git = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  })
+  return git.status === 0 ? git.stdout.trim() || null : null
+}
+
+export { createArchiveBase64, gitCommitSha }

package/src/internal/args.ts

@@ -0,0 +1,185 @@
+import path from 'node:path'
+import { DEFAULT_API_URL, DEFAULT_DEPLOY_WAIT_TIMEOUT_SECONDS } from './constants.ts'
+import { agentError } from './errors.ts'
+import type { CliOptions } from './types.ts'
+
+type BooleanCliField = 'database' | 'help' | 'json' | 'version' | 'wait'
+type StringCliField = 'apiUrl' | 'app' | 'build' | 'cursor' | 'deploy' | 'failingCommand' | 'firstLogLine' | 'limit' | 'severity' | 'template' | 'token'
+type NumberCliField = 'port' | 'waitTimeoutSeconds'
+type FlagValueKind = 'none' | 'string' | 'positiveInteger'
+type FlagSetter = (cli: CliOptions, value: string | null, name: string) => void
+
+interface FlagSpec {
+  valueKind: FlagValueKind
+  set: FlagSetter
+}
+
+interface ParsedFlag {
+  name: string
+  inlineValue: string | null
+}
+
+const FLAG_SPECS = new Map<string, FlagSpec>([
+  ['--help', booleanOption('help', true)],
+  ['-h', booleanOption('help', true)],
+  ['--version', booleanOption('version', true)],
+  ['-v', booleanOption('version', true)],
+  ['-V', booleanOption('version', true)],
+  ['--json', booleanOption('json', true)],
+  ['--database', booleanOption('database', true)],
+  ['--no-database', booleanOption('database', false)],
+  ['--wait', booleanOption('wait', true)],
+  ['--wait-timeout', positiveIntegerOption('waitTimeoutSeconds')],
+  ['--api', stringOption('apiUrl')],
+  ['--app', stringOption('app')],
+  ['--build', stringOption('build')],
+  ['--deploy', stringOption('deploy')],
+  ['--failing-command', stringOption('failingCommand')],
+  ['--first-log-line', stringOption('firstLogLine')],
+  ['--limit', stringOption('limit')],
+  ['--cursor', stringOption('cursor')],
+  ['--severity', stringOption('severity')],
+  ['--token', stringOption('token')],
+  ['--template', stringOption('template')],
+  ['--port', positiveIntegerOption('port')]
+])
+
+function parseArgs(argv: string[]): CliOptions {
+  const cli: CliOptions = {
+    command: 'help',
+    args: [],
+    apiUrl: DEFAULT_API_URL,
+    app: '',
+    build: '',
+    deploy: '',
+    limit: '',
+    cursor: '',
+    failingCommand: '',
+    firstLogLine: '',
+    token: '',
+    template: '',
+    severity: '',
+    port: 0,
+    waitTimeoutSeconds: DEFAULT_DEPLOY_WAIT_TIMEOUT_SECONDS,
+    json: false,
+    database: false,
+    wait: false,
+    help: false,
+    version: false
+  }
+
+  const positional: string[] = []
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? ''
+    if (arg === '--') {
+      positional.push(...argv.slice(index + 1))
+      break
+    }
+    const parsedFlag = parseFlag(arg)
+    const spec = FLAG_SPECS.get(parsedFlag.name)
+    if (spec) {
+      index = applyFlag(cli, spec, parsedFlag, argv, index)
+    } else if (arg.startsWith('-')) {
+      throw unknownFlag(cli, arg)
+    } else {
+      positional.push(arg)
+    }
+  }
+
+  if (positional.length > 0) {
+    cli.command = positional[0] ?? 'help'
+    cli.args = positional.slice(1)
+  }
+
+  cli.apiUrl = trimTrailingSlash(cli.apiUrl)
+  return cli
+}
+
+function booleanOption(field: BooleanCliField, value: boolean): FlagSpec {
+  return {
+    valueKind: 'none',
+    set: (cli): void => {
+      cli[field] = value
+    }
+  }
+}
+
+function stringOption(field: StringCliField): FlagSpec {
+  return {
+    valueKind: 'string',
+    set: (cli, value): void => {
+      cli[field] = value ?? ''
+    }
+  }
+}
+
+function positiveIntegerOption(field: NumberCliField): FlagSpec {
+  return {
+    valueKind: 'positiveInteger',
+    set: (cli, value, name): void => {
+      cli[field] = parsePositiveInteger(value ?? '', name)
+    }
+  }
+}
+
+function applyFlag(cli: CliOptions, spec: FlagSpec, flag: ParsedFlag, argv: readonly string[], index: number): number {
+  if (spec.valueKind === 'none') {
+    if (flag.inlineValue !== null) {
+      throw agentError('invalid_argument', `${flag.name} does not accept a value.`, `Use ${flag.name} without =value.`, cli.json)
+    }
+    spec.set(cli, null, flag.name)
+    return index
+  }
+
+  const value = flag.inlineValue ?? requireValue(argv, index, flag.name)
+  if (value === '') {
+    throw agentError('missing_argument', `${flag.name} requires a value.`, `Pass a value after ${flag.name}.`, cli.json)
+  }
+  spec.set(cli, value, flag.name)
+  return flag.inlineValue === null ? index + 1 : index
+}
+
+function parseFlag(arg: string): ParsedFlag {
+  if (!arg.startsWith('--')) {
+    return { name: arg, inlineValue: null }
+  }
+  const separator = arg.indexOf('=')
+  return separator > 2
+    ? { name: arg.slice(0, separator), inlineValue: arg.slice(separator + 1) }
+    : { name: arg, inlineValue: null }
+}
+
+function parsePositiveInteger(value: string, name: string): number {
+  const parsed = Number.parseInt(value, 10)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw agentError('invalid_argument', `${name} must be a positive integer.`, `Pass ${name} as seconds, for example ${name} 900.`, false)
+  }
+  return parsed
+}
+
+function requireValue(argv: readonly string[], index: number, name: string): string {
+  const value = argv[index + 1]
+  if (!value || value.startsWith('--')) {
+    throw agentError('missing_argument', `${name} requires a value.`, `Pass a value after ${name}.`, false)
+  }
+  return value
+}
+
+function unknownFlag(cli: CliOptions, value: string): never {
+  throw agentError(
+    'unknown_argument',
+    `Unknown Tovuk option: ${value}.`,
+    'Run `npx tovuk --help`, remove or correct the unsupported option, then retry.',
+    cli.json
+  )
+}
+
+function projectPath(value: string | undefined): string {
+  return path.resolve(value || process.cwd())
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/u, '')
+}
+
+export { parseArgs, projectPath }