bare-tui-form 0.0.0 → 0.0.2

package/harden.js

@@ -0,0 +1,173 @@
+// harden — the security boundary for untrusted JSON Schema.
+//
+// fromSchema turns externally-supplied data (an LLM- or peer-authored schema,
+// plus rehydration `formData`) into compiled regexes and strings painted onto a
+// terminal. That makes it the one place in this library that ingests data an
+// attacker may control, so it's the one place we treat as hostile. These
+// primitives are the defenses; schema.js applies them at the boundary.
+//
+// The posture is secure-by-default: limits are enforced, control characters are
+// stripped, and risky regexes are refused. A caller who genuinely trusts the
+// source opts back into full fidelity with { trusted: true } / { limits }.
+
+// Caps that bound how much work a single schema can cause. Generous enough for
+// real forms, low enough that a malicious schema can't exhaust memory/CPU.
+const DEFAULT_LIMITS = {
+  maxFields: 200, // total leaf fields across the whole (possibly nested) schema
+  maxDepth: 8, // how deeply objects may nest (a recursion / stack-overflow bound)
+  maxEnum: 1000, // entries in an enum / items.enum (and rehydrated arrays)
+  maxBranches: 20, // branches in a oneOf/anyOf variant selector
+  maxArrayItems: 100, // entries an array-of-objects can hold (add + rehydrate)
+  maxStringLength: 100000, // ceiling for a text field's charLimit
+  maxPatternLength: 1000, // source length of a `pattern` regex
+  maxTextLength: 5000, // length any single rendered string is truncated to
+  maxInputTested: 10000 // input length a `pattern` is tested against
+}
+
+// Property names that, used as an object key, can corrupt the prototype chain
+// when the collected values object is built (out[key] = …). Refused outright.
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+// C0 controls (incl. ESC 0x1b, the start of every ANSI/OSC sequence), DEL, and
+// C1 controls (incl. CSI 0x9b). Anything in here, rendered to a terminal, can
+// move the cursor, rewrite the screen, set the window title, or worse — so we
+// strip it from every schema-derived string before it can reach the output.
+// Built from an ASCII string literal so no control bytes live in this source.
+const CONTROL_CHARS = new RegExp('[\\u0000-\\u001f\\u007f-\\u009f]', 'g')
+
+// Coerce to a string, strip terminal-control characters, and truncate. Returns
+// the value untouched when it's null/undefined so "absent" stays absent.
+function cleanText(value, max = DEFAULT_LIMITS.maxTextLength) {
+  if (value === null || value === undefined) return value
+  let s = String(value).replace(CONTROL_CHARS, '')
+  if (max > 0 && s.length > max) s = s.slice(0, max)
+  return s
+}
+
+// A finite number, or undefined. JSON Schema constraints (minimum, maxLength, …)
+// are trusted only when they really are finite numbers; "5", NaN, Infinity, and
+// objects are ignored rather than fed into comparisons or RegExp/charLimit math.
+function safeNumber(n) {
+  return typeof n === 'number' && Number.isFinite(n) ? n : undefined
+}
+
+// Throw if a property name would be dangerous as an object key.
+function assertSafeKey(name) {
+  if (FORBIDDEN_KEYS.has(name)) {
+    throw new Error(`fromSchema: property name "${name}" is not allowed`)
+  }
+}
+
+// Heuristic ReDoS guard. The catastrophic-backtracking family is an unbounded
+// quantifier applied to a group that itself contains an unbounded quantifier:
+// (a+)+, (a*)*, (.*)*, ([a-z]+)* … We scan for exactly that shape. The check is
+// deliberately conservative — it may refuse some safe patterns, in which case
+// the pattern constraint is dropped (the form still works, just without that
+// one client-side check) and a warning is recorded. It is NOT a general
+// safe-regex prover; { trusted: true } bypasses it for known-good schemas.
+function isSafeRegexSource(src) {
+  let escaped = false
+  let inClass = false
+  let prevWasGroupClose = false
+  let closedGroupUnbounded = false
+  // Per currently-open group: did it contain an unbounded quantifier?
+  const groupUnbounded = []
+
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]
+
+    if (escaped) {
+      escaped = false
+      prevWasGroupClose = false
+      continue
+    }
+    if (c === '\\') {
+      escaped = true
+      prevWasGroupClose = false
+      continue
+    }
+    if (inClass) {
+      if (c === ']') inClass = false
+      prevWasGroupClose = false
+      continue
+    }
+    if (c === '[') {
+      inClass = true
+      prevWasGroupClose = false
+      continue
+    }
+    if (c === '(') {
+      groupUnbounded.push(false)
+      prevWasGroupClose = false
+      continue
+    }
+    if (c === ')') {
+      closedGroupUnbounded = groupUnbounded.pop() || false
+      prevWasGroupClose = true
+      continue
+    }
+
+    if (c === '*' || c === '+' || c === '{') {
+      const unbounded = c === '{' ? isUnboundedBrace(src, i) : true
+      // A nested unbounded quantifier: refuse.
+      if (unbounded && prevWasGroupClose && closedGroupUnbounded) return false
+      // Mark the enclosing group as containing an unbounded quantifier.
+      if (unbounded && groupUnbounded.length > 0) {
+        groupUnbounded[groupUnbounded.length - 1] = true
+      }
+      prevWasGroupClose = false
+      continue
+    }
+
+    prevWasGroupClose = false
+  }
+  return true
+}
+
+// Is the `{…}` quantifier starting at `i` open-ended (`{n,}`) — the only brace
+// form that backtracks unboundedly? `{n}` and `{n,m}` are bounded.
+function isUnboundedBrace(src, i) {
+  const close = src.indexOf('}', i)
+  if (close === -1) return false // a literal '{', not a quantifier
+  const body = src.slice(i + 1, close)
+  return /^\d+,\s*$/.test(body) // n, with nothing after the comma
+}
+
+// Compile a `pattern` into a bounded tester, or return why it was refused.
+// Returns { test } on success or { reason } when dropped. The tester caps the
+// input length it inspects so even a linear-time regex can't be driven to
+// pathological cost by a huge pasted value.
+function compilePattern(source, opts = {}) {
+  const trusted = opts.trusted === true
+  const maxPatternLength = opts.maxPatternLength ?? DEFAULT_LIMITS.maxPatternLength
+  const maxInputTested = opts.maxInputTested ?? DEFAULT_LIMITS.maxInputTested
+
+  if (typeof source !== 'string' || source === '') {
+    return { reason: 'pattern ignored (not a string)' }
+  }
+  if (source.length > maxPatternLength) {
+    return { reason: `pattern ignored (longer than ${maxPatternLength} chars)` }
+  }
+  if (!trusted && !isSafeRegexSource(source)) {
+    return { reason: 'pattern ignored (rejected as a possible ReDoS)' }
+  }
+  let re
+  try {
+    re = new RegExp(source)
+  } catch {
+    return { reason: 'pattern ignored (not a valid regular expression)' }
+  }
+  const test = (v) => re.test(String(v).slice(0, maxInputTested))
+  return { test }
+}
+
+module.exports = {
+  DEFAULT_LIMITS,
+  FORBIDDEN_KEYS,
+  cleanText,
+  safeNumber,
+  assertSafeKey,
+  isSafeRegexSource,
+  isUnboundedBrace,
+  compilePattern
+}

package/index.js

@@ -0,0 +1,86 @@
+// bare-tui-form — a declarative form builder for bare-tui.
+//
+// Built entirely on bare-tui's field controls (textinput, textarea, select,
+// radio, checkbox) and its focus ring: this package adds the orchestration
+// layer — labels, descriptions, per-field validation, focus movement, and
+// submission — that a form needs but a control library deliberately leaves out.
+//
+//   const form = require('bare-tui-form')
+//
+//   const f = form.create({
+//     title: 'Sign up',
+//     fields: [
+//       form.text({ name: 'name', label: 'Name', required: true }),
+//       form.text({ name: 'email', label: 'Email', validate: isEmail }),
+//       form.select({ name: 'plan', label: 'Plan', options: ['free', 'pro'] }),
+//       form.confirm({ name: 'tos', label: 'Accept terms', required: true })
+//     ]
+//   })
+//
+//   const values = await form.run(f) // { name, email, plan, tos } | null
+//
+// Fields can also be plain `{ type, name, … }` objects, which is the shape a
+// JSON-Schema mapper will produce — see the README for that planned path.
+const { create, run, Form, fromDef } = require('./form')
+const { fromSchema } = require('./schema')
+const { defaultTheme, frame, frames } = require('./theme')
+
+const { text, TextField } = require('./fields/text')
+const { textarea, TextareaField } = require('./fields/textarea')
+const { number, NumberField } = require('./fields/number')
+const { select, SelectField } = require('./fields/select')
+const { radio, RadioField } = require('./fields/radio')
+const { confirm, ConfirmField } = require('./fields/confirm')
+const { multiselect, MultiSelectField } = require('./fields/multiselect')
+const { file, FileField } = require('./fields/file')
+const { list, ListField } = require('./fields/list')
+const { section, SectionToggleField } = require('./fields/section')
+const { constant, ConstField } = require('./fields/constant')
+const { action, ActionField } = require('./fields/action')
+const { group, array } = require('./structural')
+const { Field } = require('./fields/base')
+
+module.exports = {
+  // Form
+  create, // form.create({ title, fields }) → Form
+  run, // form.run(form, programOpts?) → Promise<values | null>
+  Form,
+  fromDef, // fromDef({ type, … }) → field instance (the schema-friendly hook)
+  fromSchema, // fromSchema(jsonSchema, opts?) → Form built from a JSON Schema
+  defaultTheme, // the default theme object, to spread/extend in form.create({ theme })
+  frame, // form.frame({ border, color, background, padding, width }) → a theme.frame fn
+  frames, // ready-made frame presets: frames.rounded / .normal / .thick / .double
+
+  // Field factories
+  text,
+  textarea,
+  number,
+  select,
+  radio,
+  confirm,
+  multiselect,
+  file, // a type-or-browse path field (filepicker overlay); ui:widget 'file' / 'directory'
+  list, // an editable list of scalar text rows (array of string items)
+  section, // the optional-section gate (usually produced by fromSchema, not hand-written)
+  constant, // a fixed value (JSON Schema const); usually produced by fromSchema
+  action, // a focusable button (array add/remove); usually produced by fromSchema
+
+  // Structural helpers for hand-built forms (nested objects, repeatable arrays)
+  group, // form.group({ name, fields, optional }) → a nested object section
+  array, // form.array({ name, fields, minItems, maxItems, addable, removable })
+
+  // Classes (for extension / instanceof)
+  Field,
+  TextField,
+  TextareaField,
+  NumberField,
+  SelectField,
+  RadioField,
+  ConfirmField,
+  MultiSelectField,
+  FileField,
+  ListField,
+  SectionToggleField,
+  ConstField,
+  ActionField
+}

package/package.json

@@ -1 +1,52 @@
-{"name":"bare-tui-form","version":"0.0.0"}
+{
+  "name": "bare-tui-form",
+  "version": "0.0.2",
+  "description": "A declarative form builder for bare-tui",
+  "main": "index.js",
+  "exports": {
+    "./package": "./package.json",
+    ".": "./index.js",
+    "./harden": "./harden.js",
+    "./prompt": "./prompt.js"
+  },
+  "files": [
+    "package.json",
+    "index.js",
+    "form.js",
+    "theme.js",
+    "schema.js",
+    "harden.js",
+    "prompt.js",
+    "structural.js",
+    "fields",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "bare-tui": "^0.0.3"
+  },
+  "devDependencies": {
+    "bare-fs": "^4.7.1",
+    "bare-path": "^3.0.0",
+    "bare-stream": "^2.13.1",
+    "brittle": "^3.19.0",
+    "lunte": "^1.2.0",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "scripts": {
+    "format": "prettier --write . && lunte --fix",
+    "lint": "prettier --check . && lunte",
+    "test": "brittle-bare --coverage test/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holepunchto/bare-tui-form.git"
+  },
+  "author": "Holepunch",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/holepunchto/bare-tui-form/issues"
+  },
+  "homepage": "https://github.com/holepunchto/bare-tui-form"
+}

package/prompt.js

@@ -0,0 +1,107 @@
+// prompt.js — embeddable instructions that teach an LLM to emit a JSON Schema
+// (and, optionally, a uiSchema) that bare-tui-form can render into a terminal
+// form and collect from a user.
+//
+// This is meant to be *imported into your app* and dropped into your model's
+// system prompt — not read from this repo at runtime — so an embedded LLM can
+// drive form collection dynamically:
+//
+//   const { build } = require('bare-tui-form/prompt')
+//
+//   const system = build()                       // flat fields only (smallest)
+//   const system = build({ nesting: true })      // + objects/arrays/oneOf/if
+//   const system = build({ uiSchema: true })     // + presentation, two outputs
+//
+// Then feed the model's JSON straight into fromSchema:
+//
+//   const { fromSchema } = require('bare-tui-form')
+//   const f = fromSchema(JSON.parse(modelJson))  // (parse uiSchema too if used)
+//
+// It is written for *small* models, so the exported strings are terse. The
+// layers are separate exports (CORE / NESTING / UI_SCHEMA) so you only spend
+// tokens on what your forms actually use; build() assembles them plus the
+// matching output contract. The verbose comments here are for you, the
+// developer — they are not part of any exported string.
+//
+// SECURITY: every string the model produces is untrusted and fromSchema is
+// hardened for exactly that (see harden.js / schema.js). The prompt does not
+// relax those defenses; it only shapes what a cooperative model emits.
+
+// What the form can do with a flat object schema — the 80% case.
+const CORE = `You collect data from a person with a form. You describe the form as ONE JSON Schema object; it is rendered in a terminal and the answers come back as JSON matching it.
+
+Rules:
+- The schema root is {"type":"object","properties":{...}}. Each property is one field.
+- Give each property a short "title" (the on-screen label). Add a one-line "description" only when it genuinely helps.
+- Put mandatory property names in the root "required" array.
+- "default" pre-fills a field.
+
+Field type comes from the property's "type":
+- "string" -> text box. Checks: "minLength", "maxLength", "pattern" (regex), "format":"email" or "uri".
+- "integer"/"number" -> number box; "minimum"/"maximum" bound it.
+- "boolean" -> a yes/no checkbox.
+- "string" with "enum":[...] -> single-choice menu. Add "enumNames":[...] (same order) for nicer labels.
+
+Stay minimal: only the properties you need, short titles, no filler.
+
+Example -- "sign up: name, email, plan":
+{"type":"object","title":"Sign up","required":["name","email"],"properties":{"name":{"type":"string","title":"Full name","minLength":1},"email":{"type":"string","title":"Email","format":"email"},"plan":{"type":"string","title":"Plan","enum":["free","pro"],"enumNames":["Free","Pro"],"default":"free"},"news":{"type":"boolean","title":"Email me updates"}}}`
+
+// Structure: nested objects, repeatable/multi arrays, oneOf/anyOf, if/then/else.
+// Append only when your forms need shape beyond a flat list.
+const NESTING = `Structure (use only when the data needs it):
+- Nested object: a property with "type":"object" and its own "properties" -> a sub-section. In the parent "required" it is always shown; otherwise it is optional and the user opts in with a checkbox.
+- Pick many: "type":"array","items":{"enum":[...]} -> a multi-select list.
+- Repeatable group: "type":"array","items":{"type":"object","properties":{...}} -> the user adds/removes entries; "minItems"/"maxItems" bound the count.
+- One of several shapes: "oneOf" (or "anyOf") = a list of branches. Make them ALL scalar ({"const":x} or {"enum":[...]}) -> a value picker, OR ALL objects ({"properties":{...}}) -> the user picks a branch and fills it. Never mix the two.
+- Conditional fields: "if":{"properties":{"kind":{"const":"card"}}},"then":{"properties":{...}},"else":{"properties":{...}} -> the then/else fields appear based on another field. "if" may only test "const" or "enum" on sibling properties.
+- Fixed value: "const" on a property -> a non-editable value (useful as a oneOf branch tag).
+
+Never emit (these are rejected): arrays of plain strings/numbers (use items.enum or object items), arrays inside arrays, "allOf", "$ref".`
+
+// Presentation layer. Mirrors RJSF's uiSchema. Changes the OUTPUT CONTRACT:
+// the model must now emit two objects. build({ uiSchema: true }) swaps in
+// BOTH_OUTPUT to say so.
+const UI_SCHEMA = `Presentation: you also emit a second object, a uiSchema, that mirrors the schema's property names. It controls looks only -- never put data or validation in it.
+
+Per property (each "ui:KEY" may instead sit in "ui:options":{KEY:...} without the prefix):
+- "ui:widget": "textarea" (multi-line; rows via "ui:options":{"rows":N}), "password" (masked), "radio" (show an enum as radio buttons), "hidden" (collected, not shown).
+- "ui:help" (a hint line), "ui:placeholder", "ui:title"/"ui:description" (override the schema's), "ui:autofocus":true, "ui:readonly":true, "ui:options":{"label":false} (hide the label).
+On the root: "ui:order":["a","b","*"] orders fields ("*" = everything else).
+On a repeatable group: nest item presentation under "items"; lock the count with "ui:options":{"addable":false} or {"removable":false}.
+
+Example pairing:
+schema:   {"type":"object","properties":{"pw":{"type":"string","title":"Password"},"bio":{"type":"string","title":"Bio"}}}
+uiSchema: {"ui:order":["pw","bio"],"pw":{"ui:widget":"password"},"bio":{"ui:widget":"textarea","ui:options":{"rows":4}}}`
+
+const INTRO = `You design a terminal form to gather information from a user.`
+
+// Output contracts — one of these closes the prompt so the model knows the
+// exact shape to return.
+const SCHEMA_OUTPUT = `Output: emit ONLY the JSON Schema object. No prose, no markdown, no code fence.`
+const BOTH_OUTPUT = `Output: emit TWO JSON objects, the JSON Schema first and the uiSchema second, separated by a line containing only ---. No prose, no code fence.`
+
+// Assemble a system prompt from the layers you want.
+//   build()                      -> intro + CORE + schema-only output
+//   build({ nesting: true })     -> + NESTING
+//   build({ uiSchema: true })    -> + UI_SCHEMA + two-object output
+// Pass { intro: false } to drop the framing line if you supply your own.
+function build(opts = {}) {
+  const parts = []
+  if (opts.intro !== false) parts.push(INTRO)
+  parts.push(CORE)
+  if (opts.nesting) parts.push(NESTING)
+  if (opts.uiSchema) parts.push(UI_SCHEMA)
+  parts.push(opts.uiSchema ? BOTH_OUTPUT : SCHEMA_OUTPUT)
+  return parts.join('\n\n')
+}
+
+module.exports = {
+  build, // build({ nesting?, uiSchema?, intro? }) -> assembled system prompt
+  CORE, // flat object schema: types, titles, required, enums, validation
+  NESTING, // nested objects, arrays, oneOf/anyOf, if/then/else, const
+  UI_SCHEMA, // uiSchema presentation layer (implies the two-object output)
+  INTRO, // one-line framing sentence
+  SCHEMA_OUTPUT, // output contract: schema only
+  BOTH_OUTPUT // output contract: schema + uiSchema, --- separated
+}