heyquilt 0.0.1 → 0.3.106

package/src/ui/sandbox-keys.js

@@ -0,0 +1,132 @@
+// An agent's Keys table in the app (Settings › Agents, opened from its card; mockup
+// docs/mockups/2026-10-18-sandbox-keys.html, option A): its sandbox keys (QUILT_AGENT_KEY), each
+// with its session, last use, use over seven days and state, Rotate and Revoke (Remove once
+// revoked). New key opens a row at the top; a new key shows once, with Copy. The words and numbers
+// are sandbox-keys-model.js, which heyquilt.com shares.
+import { I, esc, api, toast } from './common.js'
+import { usedText, sparkHeights, stateLabel, stateClass, keyLabel, sessionTone, matchKeys, sessionOptions } from './sandbox-keys-model.js'
+
+const KEY = '<svg viewBox="0 0 16 16" aria-hidden="true"><circle cx="5" cy="8" r="3" fill="none" stroke="currentColor" stroke-width="1.4"/><path d="M8 8h6M12 8v2.5M14 8v2" fill="none" stroke="currentColor" stroke-width="1.4"/></svg>'
+const ROTATE = '<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M13 8a5 5 0 1 1-1.5-3.5M13 2v3h-3" fill="none" stroke="currentColor" stroke-width="1.4"/></svg>'
+
+function sparkHtml (k) {
+  if (k.state === 'revoked') return ''
+  const total = k.uses.reduce((a, b) => a + b, 0)
+  return `<span class="sk-spark" title="${total} ${total === 1 ? 'request' : 'requests'} in 7 days">${sparkHeights(k.uses).map((h) => `<i${h ? ` style="height:${h}%"` : ' class="z"'}></i>`).join('')}</span>`
+}
+
+function rowHtml (k, now, q) {
+  const hidden = matchKeys([k], q).length ? '' : ' hidden'
+  const revoked = k.state === 'revoked'
+  const acts = revoked
+    ? `<button type="button" class="btn sm ghost" data-sk-remove="${esc(k.id)}">Remove</button>`
+    : `<button type="button" class="btn sm" data-sk-rotate="${esc(k.id)}">${ROTATE}<span>Rotate</span></button><button type="button" class="btn sm danger" data-sk-revoke="${esc(k.id)}"><span>Revoke</span></button>`
+  return `<tr data-sk-row="${esc(k.id)}"${revoked ? ' class="sk-revoked"' : ''}${hidden}>
+    <td><b>${esc(k.name)}</b><div class="sk-hint">${esc(keyLabel(k.hint))}</div></td>
+    <td><span class="sk-chip" title="${esc(k.session)}"><span class="sk-dot t${sessionTone(k.room)}"></span><span class="sk-chip-t">${esc(k.session)}</span></span></td>
+    <td class="sk-n">${esc(usedText(k.lastUsedAt, now))}</td>
+    <td class="sk-n sk-m">${sparkHtml(k)}</td>
+    <td><span class="pill ${stateClass(k.state)}">${stateLabel(k.state)}</span></td>
+    <td class="sk-act"><span>${acts}</span></td>
+  </tr>`
+}
+
+function newRowHtml (sessions) {
+  const where = sessions.length
+    ? `<select class="input sm" name="sk-session" aria-label="Session">${sessions.map((s) => `<option value="${esc(s.value)}">${esc(s.name)}</option>`).join('')}</select>`
+    : '<input class="input sm" name="sk-link" type="url" placeholder="Session invite link" aria-label="Session invite link" autocomplete="off">'
+  return `<tr class="sk-newrow"><td colspan="6"><form class="sk-inline" data-sk-form>
+    <input class="input sm" name="sk-name" maxlength="40" placeholder="Name, e.g. bolt.new · checkout" aria-label="Key name" autocomplete="off" required>
+    ${where}
+    <button type="submit" class="btn primary sm" data-sk-create>Create</button><button type="button" class="btn ghost sm" data-sk-cancel>Cancel</button>
+  </form></td></tr>`
+}
+
+/**
+ * The Keys card for `agent`. `v`: { keys, sessions (picker options), adding, fresh ({ envKey }),
+ * error, query, loading, now }.
+ */
+export function keysCardHtml (agent, v) {
+  const now = v.now || Date.now()
+  const keys = v.keys || []
+  const body = v.loading
+    ? '<tr><td colspan="6" class="hint">Loading…</td></tr>'
+    : keys.length ? keys.map((k) => rowHtml(k, now, v.query)).join('') : '<tr><td colspan="6" class="hint">No keys yet.</td></tr>'
+  return `<div class="sk-card card" data-sk-agent="${esc(agent.id)}">
+    <div class="sk-head"><span class="sk-ico">${KEY}</span><span class="sk-t">Keys</span><span class="sk-who">${esc(agent.name)} (agent)</span><span class="sk-grow"></span>
+      <label class="sk-search"><span class="sr-only">Search keys</span><input class="input sm" data-sk-search type="search" placeholder="Search keys" value="${esc(v.query || '')}" autocomplete="off"></label>
+      <button type="button" class="btn primary sm" data-sk-new${v.adding ? ' disabled' : ''}>New key</button></div>
+    ${v.fresh ? `<div class="sk-once"><span class="pill live">New</span><code class="sk-key" data-sk-value>${esc(v.fresh.envKey)}</code><span class="sk-acts"><button type="button" class="btn sm" data-sk-copy>${I.copy}<span>Copy</span></button><span class="hint">shown once</span></span></div>` : ''}
+    ${v.error ? `<p class="error sk-error">${esc(v.error)}</p>` : ''}
+    <div class="sk-scroll"><table class="sk-tbl">
+      <thead><tr><th>Key</th><th>Session</th><th class="sk-n">Last used</th><th class="sk-n sk-m">Use, 7 days</th><th>Status</th><th><span class="sr-only">Actions</span></th></tr></thead>
+      <tbody>${v.adding ? newRowHtml(v.sessions || []) : ''}${body}</tbody>
+    </table></div>
+  </div>`
+}
+
+/** Draws and runs one agent's Keys card in `el`. */
+export function bindSandboxKeys (el, agent) {
+  const base = `/api/agents/${encodeURIComponent(agent.id)}/sandbox-keys`
+  const v = { keys: [], sessions: [], adding: false, fresh: null, error: '', query: '', loading: true }
+  const draw = () => { el.innerHTML = keysCardHtml(agent, v) }
+  const load = async () => {
+    try {
+      const r = await api('GET', base)
+      Object.assign(v, { keys: r.keys, sessions: sessionOptions(r.local, r.sessions), loading: false })
+    } catch (err) { Object.assign(v, { loading: false, error: err.message }) }
+    draw()
+  }
+  // Rotate and Revoke ask once more on the button itself (no dialog): a second click within 4 s does it.
+  const armed = (b, label) => {
+    if (b.dataset.armed) return true
+    b.dataset.armed = '1'
+    b.classList.add('sk-armed')
+    b.querySelector('span').textContent = label
+    setTimeout(() => { if (b.isConnected) { delete b.dataset.armed; b.classList.remove('sk-armed'); b.querySelector('span').textContent = label.replace(' now', '') } }, 4000)
+    return false
+  }
+  const act = async (fn) => {
+    v.error = ''
+    try { await fn() } catch (err) { v.error = err.message }
+    await load()
+  }
+  el.addEventListener('click', async (e) => {
+    const b = e.target.closest('button')
+    if (!b || b.disabled) return
+    if (b.matches('[data-sk-new]')) { v.adding = true; draw(); el.querySelector('[name="sk-name"]')?.focus(); return }
+    if (b.matches('[data-sk-cancel]')) { v.adding = false; v.error = ''; draw(); return }
+    if (b.matches('[data-sk-copy]')) {
+      try { await navigator.clipboard.writeText(v.fresh.envKey); toast('Copied') } catch { toast('Select the key and press ⌘/Ctrl+C to copy') }
+      return
+    }
+    if (b.dataset.skRotate && armed(b, 'Rotate now')) {
+      b.disabled = true
+      return act(async () => { const r = await api('POST', `${base}/rotate`, { keyId: b.dataset.skRotate }); v.fresh = { envKey: r.envKey } })
+    }
+    if (b.dataset.skRevoke && armed(b, 'Revoke now')) {
+      b.disabled = true
+      return act(() => api('POST', `${base}/revoke`, { keyId: b.dataset.skRevoke }))
+    }
+    if (b.dataset.skRemove) { b.disabled = true; return act(() => api('POST', `${base}/remove`, { keyId: b.dataset.skRemove })) }
+  })
+  el.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    const f = e.target
+    const name = f.elements['sk-name'].value.trim()
+    const pick = f.elements['sk-session']?.value || ''
+    const link = f.elements['sk-link']?.value.trim() || ''
+    f.querySelector('[data-sk-create]').disabled = true
+    await act(async () => {
+      const r = await api('POST', base, { name, ...(pick ? { session: pick } : { link }) })
+      Object.assign(v, { fresh: { envKey: r.envKey }, adding: false })
+    })
+  })
+  el.addEventListener('input', (e) => {
+    if (!e.target.matches('[data-sk-search]')) return
+    v.query = e.target.value
+    for (const tr of el.querySelectorAll('[data-sk-row]')) tr.hidden = !matchKeys(v.keys.filter((k) => k.id === tr.dataset.skRow), v.query).length
+  })
+  draw()
+  load()
+}

package/src/ui/schedule.js

@@ -0,0 +1,156 @@
+// Repeat schedules for task cards. Phrases become 5-field cron; the card shows
+// the phrase back in words. No DOM, so the session server can import it too.
+
+const INVISIBLE = /[\u0000-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g
+const RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]]
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
+const DOW = {
+  sunday: 0, sun: 0, monday: 1, mon: 1, tuesday: 2, tue: 2, tues: 2,
+  wednesday: 3, wed: 3, thursday: 4, thu: 4, thur: 4, thurs: 4,
+  friday: 5, fri: 5, saturday: 6, sat: 6
+}
+
+function pieceOk (part, min, max) {
+  const m = /^(?:(\*)|(\d+)|(\d+-\d+))(?:\/(\d+))?$/.exec(part)
+  if (!m) return false
+  if (m[4] != null) {
+    const step = Number(m[4])
+    if (!Number.isInteger(step) || step < 1 || step > max) return false
+  }
+  if (m[1]) return true
+  if (m[2]) {
+    const n = Number(m[2])
+    return n >= min && n <= max
+  }
+  const [a, b] = m[3].split('-').map(Number)
+  return a >= min && b <= max && a <= b
+}
+
+function fieldOk (field, min, max) {
+  if (!field || field.length > 40) return false
+  return field.split(',').every((part) => pieceOk(part, min, max))
+}
+
+/** True for a 5-field cron expression (numbers, lists, ranges, stars). */
+export function isCron (value) {
+  const parts = String(value ?? '').trim().split(/\s+/)
+  if (parts.length !== 5) return false
+  return parts.every((field, i) => fieldOk(field, RANGES[i][0], RANGES[i][1]))
+}
+
+function clock (hour, minute, ampm) {
+  let h = Number(hour)
+  const m = minute == null || minute === '' ? 0 : Number(minute)
+  if (!Number.isInteger(h) || !Number.isInteger(m) || m < 0 || m > 59) return null
+  if (ampm) {
+    const ap = ampm.toLowerCase()
+    if (h > 12 || h < 1) return null
+    if (ap === 'pm' && h < 12) h += 12
+    if (ap === 'am' && h === 12) h = 0
+  } else if (h > 23 || h < 0) return null
+  return { h, m }
+}
+
+function phraseToCron (raw) {
+  const s = raw.toLowerCase()
+  if (s === 'every minute' || s === 'minutely') return '* * * * *'
+  if (s === 'hourly' || s === 'every hour') return '0 * * * *'
+  if (s === 'daily' || s === 'every day') return '0 0 * * *'
+  if (s === 'weekly' || s === 'every week') return '0 0 * * 1'
+  if (s === 'monthly' || s === 'every month') return '0 0 1 * *'
+  if (s === 'weekdays' || s === 'every weekday') return '0 0 * * 1-5'
+  if (s === 'weekends' || s === 'every weekend') return '0 0 * * 0,6'
+
+  let m = s.match(/^every (\d{1,2}) minutes?$/)
+  if (m) {
+    const n = Number(m[1])
+    if (n < 1 || n > 59) return null
+    return n === 1 ? '* * * * *' : `*/${n} * * * *`
+  }
+  m = s.match(/^every (\d{1,2}) hours?$/)
+  if (m) {
+    const n = Number(m[1])
+    if (n < 1 || n > 23) return null
+    return n === 1 ? '0 * * * *' : `0 */${n} * * *`
+  }
+
+  m = s.match(/^(every day|daily|weekdays|every weekday|weekends|every weekend|weekly|every week|monthly|every month) at (\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/)
+  if (m) {
+    const c = clock(m[2], m[3], m[4])
+    if (!c) return null
+    const kind = m[1]
+    if (kind === 'monthly' || kind === 'every month') return `${c.m} ${c.h} 1 * *`
+    const dow = kind === 'weekdays' || kind === 'every weekday' ? '1-5'
+      : kind === 'weekends' || kind === 'every weekend' ? '0,6'
+        : kind === 'weekly' || kind === 'every week' ? '1'
+          : '*'
+    return `${c.m} ${c.h} * * ${dow}`
+  }
+
+  m = s.match(/^(?:every|on)\s+(sunday|sun|monday|mon|tuesday|tue|tues|wednesday|wed|thursday|thu|thur|thurs|friday|fri|saturday|sat)(?: at (\d{1,2})(?::(\d{2}))?\s*(am|pm)?)?$/)
+  if (m) {
+    const c = m[2] != null ? clock(m[2], m[3], m[4]) : { h: 0, m: 0 }
+    if (!c) return null
+    return `${c.m} ${c.h} * * ${DOW[m[1]]}`
+  }
+  return null
+}
+
+/**
+ * A stored schedule or a phrase ("daily at 9", "weekdays at 9:30", "every monday").
+ * Empty clears it. Throws when it is neither a phrase nor 5-field cron.
+ */
+export function parseSchedule (input) {
+  const raw = String(input ?? '').replace(INVISIBLE, ' ').replace(/\s+/g, ' ').trim()
+  if (!raw) return ''
+  if (raw.length > 80) throw new Error('schedule is too long')
+  const phrase = phraseToCron(raw)
+  if (phrase) return phrase
+  if (!isCron(raw)) throw new Error('use 5-field cron, or a phrase like "daily at 9" or "weekdays at 9:30"')
+  return raw
+}
+
+/** The cron as stored, or null when it is not already in canonical form. Missing is empty. */
+export function canonicalCron (value) {
+  if (value == null || value === '') return ''
+  if (typeof value !== 'string' || value.length > 80) return null
+  try {
+    const parsed = parseSchedule(value)
+    return parsed === value ? value : null
+  } catch {
+    return null
+  }
+}
+
+function clockLabel (hour, minute) {
+  const h = Number(hour)
+  const m = Number(minute)
+  const ap = h >= 12 ? 'pm' : 'am'
+  const h12 = h % 12 || 12
+  return m === 0 ? `${h12}${ap}` : `${h12}:${String(m).padStart(2, '0')}${ap}`
+}
+
+/** English for the schedules the card knows. Anything else is the cron itself. */
+export function cronToText (cron) {
+  const c = String(cron || '').trim()
+  if (!c) return ''
+  const parts = c.split(/\s+/)
+  if (parts.length !== 5 || !isCron(c)) return c
+  const [min, hour, dom, mon, dow] = parts
+  if (mon !== '*') return c
+  if (c === '* * * * *') return 'Every minute'
+  const everyMin = /^\*\/(\d+)$/.exec(min)
+  if (everyMin && hour === '*' && dom === '*' && dow === '*') return `Every ${everyMin[1]} minutes`
+  if (min === '0' && hour === '*' && dom === '*' && dow === '*') return 'Every hour'
+  const everyHour = /^\*\/(\d+)$/.exec(hour)
+  if (min === '0' && everyHour && dom === '*' && dow === '*') return `Every ${everyHour[1]} hours`
+  if (!/^\d+$/.test(min) || !/^\d+$/.test(hour)) return c
+  const when = clockLabel(hour, min)
+  if (dom === '*' && dow === '*') return `Every day at ${when}`
+  if (dom === '*' && dow === '1-5') return `Weekdays at ${when}`
+  if (dom === '*' && dow === '0,6') return `Weekends at ${when}`
+  if (dom === '1' && dow === '*') return `Monthly on the 1st at ${when}`
+  if (dom === '*' && /^\d$/.test(dow)) return `Every ${DAYS[Number(dow)]} at ${when}`
+  return c
+}
+

package/src/ui/secret-rules.js

@@ -0,0 +1,255 @@
+// Secrets (docs/superpowers/specs/2026-10-18-secrets.md): the rules every part shares, the
+// accounts API, the vault, `quilt run`, the app and the website. Pure, no Node built-ins, so the
+// app's page and the website import it too. Nothing here ever sees a value except
+// applyCredential (the vault, as it forwards a request) and parseDotenv (the app, as it sends an
+// .env file's values straight to the vault).
+
+export const SCOPES = ['org', 'workspace', 'session']
+export const WHO = ['agents', 'people']
+export const MAX_VALUE_BYTES = 16 * 1024
+export const MAX_ENTRIES = 100
+// What `quilt run` puts where a value would be. SDKs that insist on a key get one.
+export const STAND_IN = 'quilt'
+
+const NAME = /^[A-Z_][A-Z0-9_]{0,63}$/
+export const BAD_NAME = 'A secret name is capital letters, digits and underscores, like STRIPE_KEY (at most 64).'
+
+/** A secret's name, or an error saying what one looks like. */
+export function cleanSecretName (value) {
+  const s = String(value ?? '').trim()
+  if (!NAME.test(s)) throw new Error(BAD_NAME)
+  return s
+}
+
+const HOST_LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/
+const INSIDE = /(^|\.)(localhost|local|internal|localdomain|home|lan|intranet|corp|private|test|invalid|example|onion|arpa)$/
+export const NOT_HTTPS = 'Only HTTPS services for now: Postgres and other database secrets are not supported yet.'
+
+/**
+ * The one host a secret is sent to: `api.stripe.com`, from that or from `https://api.stripe.com/`.
+ * A port is allowed (`api.example.com:8443`). Never an IP address, a single-label name or an
+ * internal one (`localhost`, `*.internal`): the vault would otherwise reach inside its own
+ * network. `allowLocal` is for tests only (a stand-in upstream on 127.0.0.1).
+ */
+export function cleanUpstream (value, { allowLocal = false } = {}) {
+  let s = String(value ?? '').trim().toLowerCase()
+  if (!s) throw new Error('Say where the secret is sent: its service\'s host, like api.stripe.com.')
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//.exec(s)
+  if (scheme) {
+    if (scheme[1] !== 'https' && !(allowLocal && scheme[1] === 'http')) throw new Error(NOT_HTTPS)
+    s = s.slice(scheme[0].length)
+  }
+  s = s.replace(/\/+$/, '')
+  if (/[/?#@\s\\]/.test(s)) throw new Error('Just the host, like api.stripe.com: no path.')
+  const m = /^(\[[^\]]*\]|[^:]+)(?::(\d{1,5}))?$/.exec(s)
+  if (!m) throw new Error('That is not a host name.')
+  const [, host, port] = m
+  if (port !== undefined && (Number(port) < 1 || Number(port) > 65535)) throw new Error('That port is not right.')
+  if (allowLocal && (host === '127.0.0.1' || host === 'localhost')) return port ? `${host}:${Number(port)}` : host
+  if (host.startsWith('[') || IPV4.test(host)) throw new Error('A host name, not an IP address.')
+  const labels = host.split('.')
+  if (labels.length < 2 || host.length > 253 || !labels.every((l) => HOST_LABEL.test(l)) || /^\d+$/.test(labels.at(-1))) throw new Error('That is not a host name.')
+  if (INSIDE.test(host)) throw new Error('That host is inside a private network; secrets go to public services only.')
+  return port && Number(port) !== 443 ? `${host}:${Number(port)}` : host
+}
+
+// How the vault attaches the value. `{value}` is the value; `{basic}` is base64 of "value:"
+// (HTTP Basic with the key as the user name).
+export const FORMATS = {
+  bearer: { in: 'header', name: 'authorization', template: 'Bearer {value}', label: 'Authorization: Bearer' },
+  'x-api-key': { in: 'header', name: 'x-api-key', template: '{value}', label: 'x-api-key header' },
+  basic: { in: 'header', name: 'authorization', template: 'Basic {basic}', label: 'Basic (key as user)' },
+  query: { in: 'query', name: 'key', template: '{value}', label: 'Query ?key=' },
+  // A webhook URL: the value (the URL, or its path) starts the request's path.
+  path: { in: 'path', name: '', template: '{value}', label: 'In the path (webhook URL)' }
+}
+export const FORMAT_IDS = Object.keys(FORMATS)
+const TOKEN = /^[a-z0-9!#$%&'*+.^_`|~-]{1,64}$/
+const PARAM = /^[A-Za-z0-9_.~-]{1,64}$/
+// Headers a secret may not be put in: they belong to the connection, not to the service.
+const RESERVED = new Set(['host', 'connection', 'content-length', 'transfer-encoding', 'te', 'upgrade', 'keep-alive', 'proxy-authorization', 'proxy-connection', 'trailer', 'accept-encoding', 'content-encoding'])
+export const BAD_FORMAT = 'Pick how the secret is sent: Authorization: Bearer, an x-api-key header, Basic, a query parameter, in the path, or a header of your own with {value} in it.'
+
+/**
+ * A credential format: a preset's id, or { in: 'header'|'query', name, template } with
+ * `{value}` (or `{basic}`) exactly once. Answers { in, name, template }.
+ */
+export function cleanFormat (value) {
+  if (typeof value === 'string' && FORMATS[value]) { const { label, ...f } = FORMATS[value]; return f }
+  if (!value || typeof value !== 'object') throw new Error(BAD_FORMAT)
+  const where = ['query', 'header', 'path'].includes(value.in) ? value.in : null
+  const name = String(value.name ?? '').trim()
+  const template = String(value.template ?? '{value}')
+  if (!where) throw new Error(BAD_FORMAT)
+  if (where === 'path') return { in: 'path', name: '', template: '{value}' }
+  if (where === 'header' ? !TOKEN.test(name.toLowerCase()) || RESERVED.has(name.toLowerCase()) : !PARAM.test(name)) throw new Error(BAD_FORMAT)
+  const holes = (template.match(/\{(value|basic)\}/g) || []).length
+  if (holes !== 1 || template.length > 200 || /[\r\n\0]/.test(template) || /\{(?!value\}|basic\})/.test(template)) throw new Error(BAD_FORMAT)
+  return { in: where, name: where === 'header' ? name.toLowerCase() : name, template }
+}
+
+/** A short label for a format, for the table: "Authorization: Bearer", "?key=". */
+export function formatLabel (f) {
+  for (const p of Object.values(FORMATS)) if (p.in === f?.in && p.name === f?.name && p.template === f?.template) return p.label
+  if (!f) return ''
+  if (f.in === 'path') return FORMATS.path.label
+  return f.in === 'query' ? `?${f.name}=` : `${f.name}: ${f.template.replace(/\{(value|basic)\}/, '…')}`
+}
+
+/** The preset id a format is, or '' for one of a person's own. */
+export function formatId (f) {
+  return FORMAT_IDS.find((id) => FORMATS[id].in === f?.in && FORMATS[id].name === f?.name && FORMATS[id].template === f?.template) || ''
+}
+
+function base64 (s) {
+  const bytes = new TextEncoder().encode(s)
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin)
+}
+
+/**
+ * What the vault puts on the request: { header: [name, text] }, { query: [name, text] }, or
+ * { path: text } (to put before the request's own path; a whole https URL is cut to its path).
+ */
+export function applyCredential (format, value) {
+  const f = cleanFormat(format)
+  if (f.in === 'path') return { path: String(value).replace(/^https:\/\/[^/]+/i, '').replace(/^\/+/, '') }
+  const text = f.template.replace('{value}', () => value).replace('{basic}', () => base64(`${value}:`))
+  return f.in === 'query' ? { query: [f.name, text] } : { header: [f.name, text] }
+}
+
+/** The forms of a value the vault masks in an answer: as sent, and as the format spelled it. */
+export function maskForms (format, value) {
+  const out = new Set([String(value)])
+  try {
+    const c = applyCredential(format, value)
+    const text = c.path !== undefined ? c.path : (c.header || c.query)[1]
+    if (text !== value) out.add(text)
+    if (/\{basic\}/.test(cleanFormat(format).template)) out.add(base64(`${value}:`))
+  } catch {}
+  try { const enc = encodeURIComponent(value); if (enc !== value) out.add(enc) } catch {}
+  return [...out].filter((s) => s.length >= 4)
+}
+
+// SDKs that read a base URL from the environment, by host: [variable, path after the host].
+export const KNOWN_BASE_URLS = {
+  'api.openai.com': [['OPENAI_BASE_URL', 'v1']],
+  'api.anthropic.com': [['ANTHROPIC_BASE_URL', '']],
+  'api.groq.com': [['GROQ_BASE_URL', '']]
+}
+
+/** The variable `quilt run` gives a secret's gateway in: STRIPE_KEY → STRIPE_BASE_URL. */
+export function baseUrlVar (name) {
+  const m = /^(.+?)_(API_KEY|SECRET_KEY|ACCESS_TOKEN|KEY|SECRET|TOKEN)$/.exec(name)
+  return `${m ? m[1] : name}_BASE_URL`
+}
+
+/** Every variable `quilt run` sets for a secret: its name (the stand-in) and its base URLs. */
+export function envVarsFor (name, upstream) {
+  return [name, baseUrlVar(name), ...(KNOWN_BASE_URLS[String(upstream || '').toLowerCase()] || []).map(([v]) => v)]
+    .filter((v, i, a) => a.indexOf(v) === i)
+}
+
+/**
+ * The environment `quilt run` gives a command: for each secret, the stand-in and the gateway
+ * (`<vault>/g/<token>/<NAME>/`), plus the conventional base URL of a known service (the first
+ * secret for that service wins). Never a value: there is none here.
+ */
+export function runEnv (secrets, { vault, token }) {
+  const base = String(vault).replace(/\/+$/, '')
+  const env = {}
+  const taken = new Set()
+  for (const s of secrets) {
+    const gateway = `${base}/g/${token}/${s.name}/`
+    env[s.name] = STAND_IN
+    const own = baseUrlVar(s.name)
+    if (own !== s.name) { env[own] = gateway; taken.add(own) }
+  }
+  for (const s of secrets) {
+    const gateway = `${base}/g/${token}/${s.name}/`
+    for (const [v, p] of KNOWN_BASE_URLS[String(s.upstream || '').toLowerCase()] || []) {
+      if (taken.has(v) || secrets.some((x) => x.name === v)) continue
+      env[v] = p ? `${gateway}${p}` : gateway.replace(/\/$/, '')
+      taken.add(v)
+    }
+  }
+  return env
+}
+
+/**
+ * An .env file's names and values, in order (the last of a repeated name wins). Understands
+ * `export`, comments, single quotes (as is), double quotes (\n, \t, \", \\) and a value that
+ * runs on to the closing quote across lines.
+ */
+export function parseDotenv (text) {
+  const out = new Map()
+  const src = String(text ?? '').replace(/\r\n?/g, '\n')
+  const re = /^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_.-]*)[ \t]*=[ \t]*(?:"((?:\\[\s\S]|[^"\\])*)"|'([^']*)'|([^\n]*))[ \t]*(?:#[^\n]*)?$/gm
+  let m
+  while ((m = re.exec(src))) {
+    const [, name, dq, sq, bare] = m
+    let value
+    if (dq !== undefined) value = dq.replace(/\\(.)/g, (_, c) => ({ n: '\n', r: '\r', t: '\t' }[c] ?? c))
+    else if (sq !== undefined) value = sq
+    else value = bare.replace(/[ \t]+#.*$/, '').trim()
+    out.delete(name)
+    out.set(name, value)
+  }
+  return [...out].map(([name, value]) => ({ name, value }))
+}
+
+// Where well-known keys go, by the start of their name: [prefix, host, format].
+const GUESSES = [
+  ['STRIPE', 'api.stripe.com', 'bearer'],
+  ['OPENAI', 'api.openai.com', 'bearer'],
+  ['ANTHROPIC', 'api.anthropic.com', 'x-api-key'],
+  ['CLAUDE', 'api.anthropic.com', 'x-api-key'],
+  ['GROQ', 'api.groq.com', 'bearer'],
+  ['MISTRAL', 'api.mistral.ai', 'bearer'],
+  ['OPENROUTER', 'openrouter.ai', 'bearer'],
+  ['XAI', 'api.x.ai', 'bearer'],
+  ['GROK', 'api.x.ai', 'bearer'],
+  ['GITHUB', 'api.github.com', 'bearer'],
+  ['GH_', 'api.github.com', 'bearer'],
+  ['SENDGRID', 'api.sendgrid.com', 'bearer'],
+  ['RESEND', 'api.resend.com', 'bearer'],
+  ['POSTMARK', 'api.postmarkapp.com', 'bearer'],
+  ['MAILGUN', 'api.mailgun.net', 'basic'],
+  ['TWILIO', 'api.twilio.com', 'basic'],
+  ['REPLICATE', 'api.replicate.com', 'bearer'],
+  ['HUGGINGFACE', 'huggingface.co', 'bearer'],
+  ['HF_', 'huggingface.co', 'bearer'],
+  ['CLOUDFLARE', 'api.cloudflare.com', 'bearer'],
+  ['VERCEL', 'api.vercel.com', 'bearer'],
+  ['NETLIFY', 'api.netlify.com', 'bearer'],
+  ['LINEAR', 'api.linear.app', 'bearer'],
+  ['NOTION', 'api.notion.com', 'bearer'],
+  ['SLACK', 'slack.com', 'bearer'],
+  ['DEEPSEEK', 'api.deepseek.com', 'bearer'],
+  ['ELEVENLABS', 'api.elevenlabs.io', 'bearer'],
+  ['PERPLEXITY', 'api.perplexity.ai', 'bearer']
+]
+
+/**
+ * What the app suggests for an .env entry: { upstream, format } when the name or value says
+ * (an https URL's host), { skip: reason } for a value that can't go through the gateway (a
+ * database URL), or {} when the person has to say.
+ */
+export function guessUpstream (name, value = '') {
+  const v = String(value || '').trim()
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(v)
+  if (scheme && scheme[1].toLowerCase() !== 'https') return { skip: NOT_HTTPS }
+  // A whole URL (a webhook): sent to its host, with the URL's path as the secret part.
+  if (scheme) { try { return { upstream: cleanUpstream(new URL(v).host), format: 'path' } } catch { return {} } }
+  const n = String(name).toUpperCase()
+  const g = GUESSES.find(([p]) => n.startsWith(p))
+  return g ? { upstream: g[1], format: g[2] } : {}
+}
+
+/** A digest as the table shows it: a91e…07c2. */
+export function shortDigest (d) {
+  const s = String(d || '')
+  return s.length > 8 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s
+}