@stacksjs/ts-cloud 0.7.105 → 0.7.109

package/dist/ui-src/functions/useOpConfirm.ts

@@ -0,0 +1,132 @@
+export interface OperationConfirmation {
+  operation: string
+  confirm: string
+  verb: string
+  to?: string | null
+  apiConfirm?: string
+  danger?: boolean
+  label?: string
+  [key: string]: unknown
+}
+
+export interface OperationResult {
+  output: string
+  ok?: boolean
+}
+
+export type Signal<T> = (() => T) & { set: (value: T) => void }
+
+interface HTMLElement {
+  focus: () => void
+  scrollIntoView: (options?: { behavior?: string; block?: string }) => void
+}
+
+type HTMLInputElement = HTMLElement
+
+export interface OperationConfirmationController {
+  opOutput: Signal<string>
+  opShown: Signal<boolean>
+  pending: Signal<OperationConfirmation | null>
+  typed: Signal<string>
+  busy: Signal<boolean>
+  confirmTok: Signal<string>
+  confirmVerb: Signal<string>
+  confirmDanger: Signal<boolean>
+  confirmLabel: Signal<string>
+  canRun: Signal<boolean>
+  askOp: (
+    operation: string,
+    confirm: string,
+    verb: string,
+    to?: string | null,
+    apiConfirm?: string,
+    options?: Partial<OperationConfirmation>,
+  ) => void
+  cancelOp: () => void
+  runOp: () => Promise<void>
+}
+
+declare function state<T>(_value: T): Signal<T>
+declare function derived<T>(_value: () => T): Signal<T>
+declare function useRef<T = HTMLElement>(_name: string): { current: T | null }
+
+const DANGEROUS_OPERATION = /(?:^|:)(?:delete|disable|destroy|purge|remove|restore|rollback|stop)(?::|$)/i
+
+export function operationIsDangerous(operation: Pick<OperationConfirmation, 'operation' | 'danger'>): boolean {
+  return operation.danger ?? DANGEROUS_OPERATION.test(operation.operation)
+}
+
+/**
+ * One confirmation lifecycle for dashboard operations. The caller owns only
+ * the API request; this composable owns staging, exact-token validation,
+ * in-flight locking, focus, output, cancellation, and error presentation.
+ */
+export function useOpConfirm(
+  execute: (operation: OperationConfirmation) => Promise<string | OperationResult>,
+): OperationConfirmationController {
+  const opOutput = state('')
+  const opShown = state(false)
+  const pending = state<OperationConfirmation | null>(null)
+  const typed = state('')
+  const busy = state(false)
+  const confirmInput = useRef<HTMLInputElement>('opConfirmInput')
+  const confirmTok = derived(() => pending()?.confirm ?? '')
+  const confirmVerb = derived(() => pending()?.verb ?? '')
+  const confirmDanger = derived(() => (pending() ? operationIsDangerous(pending()!) : false))
+  const confirmLabel = derived(() => pending()?.label ?? (confirmDanger() ? 'Confirm operation' : 'Run operation'))
+  const canRun = derived(() => !!pending() && !busy() && typed() === pending()!.confirm)
+
+  function askOp(
+    operation: string,
+    confirm: string,
+    verb: string,
+    to?: string | null,
+    apiConfirm?: string,
+    options: Partial<OperationConfirmation> = {},
+  ) {
+    pending.set({ ...options, operation, confirm, verb, to: to ?? null, apiConfirm: apiConfirm || confirm })
+    typed.set('')
+    confirmInput.current?.focus()
+    confirmInput.current?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+  }
+
+  function cancelOp() {
+    if (busy()) return
+    pending.set(null)
+    typed.set('')
+  }
+
+  async function runOp() {
+    const operation = pending()
+    if (!operation || busy() || typed() !== operation.confirm) return
+    busy.set(true)
+    opShown.set(true)
+    opOutput.set(`Running ${operation.operation}...`)
+    try {
+      const result = await execute(operation)
+      opOutput.set(typeof result === 'string' ? result : result.output)
+      pending.set(null)
+      typed.set('')
+    } catch (error) {
+      opOutput.set(`FAILED ${operation.operation}\n\n${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      busy.set(false)
+    }
+  }
+
+  return {
+    opOutput,
+    opShown,
+    pending,
+    typed,
+    busy,
+    confirmTok,
+    confirmVerb,
+    confirmDanger,
+    confirmLabel,
+    canRun,
+    askOp,
+    cancelOp,
+    runOp,
+  }
+}

package/dist/ui-src/functions/usePolling.ts

@@ -0,0 +1,98 @@
+export type Signal<T> = (() => T) & { set: (value: T) => void }
+declare function state<T>(_value: T): Signal<T>
+declare function derived<T>(_value: () => T): Signal<T>
+declare function onMount(_callback: () => void | (() => void)): void
+declare function useInterval(
+  _interval: number,
+  _options?: { immediate?: boolean },
+): { subscribe: (callback: () => void) => () => void; pause: () => void }
+
+/**
+ * `snapshot` means the cockpit was exported without its control plane — the
+ * static + htpasswd deploy (`TS_CLOUD_UI_STATIC`). The data baked into the page
+ * is real, it just cannot be refreshed, which is a different thing from a
+ * refresh that failed and must not be reported as an error.
+ */
+export type PollingState = 'loading' | 'live' | 'stale' | 'snapshot'
+
+export interface PollingController {
+  pollingState: Signal<PollingState>
+  pollingError: Signal<string>
+  pollingLabel: Signal<PollingState>
+  lastUpdatedAt: Signal<Date | null>
+  /** True once the deployment has told us it serves no API. */
+  isSnapshot: Signal<boolean>
+  refresh: () => Promise<void>
+}
+
+export interface PollingOptions {
+  /**
+   * Treat a missing API route as "this build has no control plane" instead of
+   * as an error.
+   *
+   * Opt in only from a page whose data is fully baked in at build time, so
+   * there is genuinely nothing lost by not polling — the infrastructure map,
+   * for instance. A page that manages live resources must NOT set this: its
+   * buttons post to that same missing API, so a 404 there is a real fault and
+   * calling it a snapshot would hide it. Off by default for that reason.
+   */
+  snapshotWhenApiMissing?: boolean
+}
+
+/**
+ * A build served without its control plane answers the API route itself rather
+ * than failing in transit: a static host 404s the path, and a proxy that knows
+ * the route but not the method answers 405/501. Anything else — a 500, a
+ * dropped connection, malformed JSON — is a real failure and stays one.
+ *
+ * Only errors carrying an HTTP status qualify, so the caller must be using
+ * `requestJson` (which raises `DashboardRequestError`); a bare `fetch` that
+ * throws a plain `Error` keeps the stale-with-error behaviour.
+ */
+function servedWithoutApi(error: unknown): boolean {
+  const status = (error as { status?: unknown })?.status
+  return status === 404 || status === 405 || status === 501
+}
+
+/** Poll immediately and on a lifecycle-owned interval, retaining stale data on failure. */
+export function usePolling(
+  task: () => Promise<void>,
+  intervalMs: number,
+  options: PollingOptions = {},
+): PollingController {
+  const pollingState = state<PollingState>('loading')
+  const pollingError = state('')
+  const lastUpdatedAt = state<Date | null>(null)
+  const isSnapshot = state(false)
+  const pollingLabel = derived<PollingState>(() => pollingState())
+
+  const interval = useInterval(intervalMs)
+
+  async function refresh() {
+    try {
+      await task()
+      pollingState.set('live')
+      pollingError.set('')
+      isSnapshot.set(false)
+      lastUpdatedAt.set(new Date())
+    } catch (error) {
+      if (options.snapshotWhenApiMissing && servedWithoutApi(error)) {
+        // Nothing here will ever answer, so stop asking. The page keeps the
+        // data it was built with and says it is a snapshot, not an outage.
+        isSnapshot.set(true)
+        pollingState.set('snapshot')
+        pollingError.set('')
+        interval.pause()
+        return
+      }
+      pollingState.set('stale')
+      pollingError.set(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  interval.subscribe(refresh)
+  onMount(() => {
+    refresh()
+  })
+  return { pollingState, pollingError, pollingLabel, lastUpdatedAt, isSnapshot, refresh }
+}

package/dist/ui-src/functions/useTerminal.ts

@@ -0,0 +1,79 @@
+export type Signal<T> = (() => T) & { set: (value: T) => void }
+
+interface HTMLElement {
+  scrollTop: number
+  scrollHeight: number
+}
+
+declare const location: { protocol: string; host: string }
+declare function state<T>(_value: T): Signal<T>
+declare function derived<T>(_value: () => T): Signal<T>
+declare function effect(_callback: () => void): void
+declare function useRef<T = HTMLElement>(_name: string): { current: T | null }
+declare function useWebSocket(
+  _url: string,
+  _options?: Record<string, unknown>,
+): {
+  status: Signal<'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED'>
+  send: (data: string) => void
+  close: () => void
+  connect: () => void
+}
+
+export interface TerminalController {
+  buf: Signal<string>
+  cmd: Signal<string>
+  status: Signal<string>
+  send: () => void
+  reconnect: () => void
+  clearOut: () => void
+  statusTone: (value: string) => 'ok' | 'bad' | 'warn'
+}
+
+/** Terminal transport and viewport behavior, isolated from the stx template. */
+export function useTerminal(path: string = '/api/terminal'): TerminalController {
+  const buf = state('')
+  const cmd = state('')
+  const output = useRef<HTMLElement>('terminalOutput')
+  const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
+  const url = `${protocol}//${location.host}${path}`
+  const socket = useWebSocket(url, {
+    reconnect: true,
+    maxReconnects: 10,
+    reconnectDelay: 1000,
+    onMessage(data: unknown) {
+      buf.set((buf() + String(data)).slice(-40000))
+    },
+  })
+  const status = derived(
+    () =>
+      ({ CONNECTING: 'connecting', OPEN: 'connected', CLOSING: 'disconnecting', CLOSED: 'disconnected' })[
+        socket.status()
+      ] || 'error',
+  )
+
+  effect(() => {
+    buf()
+    const element = output.current
+    if (element) element.scrollTop = element.scrollHeight
+  })
+
+  function send() {
+    const command = cmd()
+    if (!command.trim() || socket.status() !== 'OPEN') return
+    socket.send(command + '\n')
+    cmd.set('')
+  }
+  function reconnect() {
+    socket.close()
+    buf.set('')
+    socket.connect()
+  }
+  function clearOut() {
+    buf.set('')
+  }
+  function statusTone(value: string): 'ok' | 'bad' | 'warn' {
+    return value === 'connected' ? 'ok' : value === 'disconnected' || value === 'error' ? 'bad' : 'warn'
+  }
+  return { buf, cmd, status, send, reconnect, clearOut, statusTone }
+}