@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/commands/dataset/index-commands.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
 
-import { DatasetApi, type DatasetColumn } from '../../api/dataset-api'
+import { DatasetApi, type DatasetColumn, type DatasetSummary } from '../../api/dataset-api'
 import { CliError } from '../../errors'
 import { table } from '../../table'
 import { flagString, type Command } from '../types'
@@ -103,6 +103,76 @@ function readColumns(raw: unknown, path: string): DatasetColumn[] {
   })
 }
 
+/**
+ * The column contract of a file dataset that declares `columns`: each included
+ * column with the type and nullability the file says, the CSV's own where it
+ * says nothing (`upload-preview`). The CSV must hold exactly the included
+ * columns, since a contract built this way records none as left out.
+ */
+async function fileContract(api: DatasetApi, csvPath: string, included: string[], declared: Map<string, { nullable?: boolean; databaseType?: string }>, filePath: string): Promise<DatasetColumn[]> {
+  const preview = await api.uploadPreview(csvPath)
+  const inferred = new Map((preview.columns ?? []).flatMap((c) => (c.name ? [[c.name, c] as const] : [])))
+  const extra = [...inferred.keys()].filter((name) => !included.includes(name))
+  if (extra.length) {
+    throw new CliError(`${filePath} declares \`columns\`, and its CSV carries ${extra.join(', ')}, which \`includedColumns\` leaves out.`, {
+      code: 'USAGE',
+      hint: 'With `columns`, the CSV holds exactly the included columns: add them to includedColumns, or drop them from the CSV.',
+    })
+  }
+  return included.map((name): DatasetColumn => {
+    const said = declared.get(name)
+    const seen = inferred.get(name)
+    const databaseType = (said?.databaseType ?? seen?.databaseType) as DatasetColumn['databaseType'] | undefined
+    if (!databaseType || !COLUMN_TYPES.includes(databaseType as never)) {
+      throw new CliError(`${filePath}: the CSV has no column "${name}" to read its type from.`, {
+        code: 'USAGE',
+        hint: `Add it to the CSV, or declare it: columns: [{ name: ${name}, databaseType: text, nullable: true }]`,
+      })
+    }
+    return { name, databaseType, nullable: said?.nullable ?? seen?.nullable ?? true }
+  })
+}
+
+/**
+ * A file dataset's `columns`: what it declares of each column instead of
+ * leaving it to the first CSV (`[{ name, nullable, databaseType? }]`). Each
+ * names an included column and says its nullability, its type, or both;
+ * the rest come from the CSV.
+ */
+function readFileColumns(raw: unknown, included: string[], path: string): Map<string, { nullable?: boolean; databaseType?: string }> {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new CliError(`${path} has \`columns\` that is not a list.`, {
+      code: 'USAGE',
+      hint: 'columns: [{ name: closed_at, nullable: true }] — the columns whose nullability (or type) the file declares.',
+    })
+  }
+  const out = new Map<string, { nullable?: boolean; databaseType?: string }>()
+  raw.forEach((entry, position) => {
+    const where = `${path}: columns[${position}]`
+    const column = (entry && typeof entry === 'object' ? entry : {}) as Record<string, unknown>
+    const name = column.name
+    if (typeof name !== 'string' || !included.includes(name)) {
+      throw new CliError(`${where} names ${typeof name === 'string' ? `"${name}", which is not in includedColumns` : 'no column'}.`, {
+        code: 'USAGE',
+        hint: `Included: ${included.join(', ')}`,
+      })
+    }
+    const strays = Object.keys(column).filter((k) => !['name', 'nullable', 'databaseType'].includes(k))
+    if (strays.length) throw new CliError(`${where} carries ${strays.join(', ')}.`, { code: 'USAGE', hint: 'A file dataset’s column is { name, nullable, databaseType }; databaseType is optional.' })
+    if (column.nullable !== undefined && typeof column.nullable !== 'boolean') {
+      throw new CliError(`${where}: \`nullable\` is true or false.`, { code: 'USAGE', hint: 'nullable: true lets the column hold empty values in any later CSV.' })
+    }
+    if (column.databaseType !== undefined && (typeof column.databaseType !== 'string' || !COLUMN_TYPES.includes(column.databaseType as never))) {
+      throw new CliError(`${where} has an unknown \`databaseType\`.`, { code: 'USAGE', hint: `One of: ${COLUMN_TYPES.join(', ')}` })
+    }
+    if (column.nullable === undefined && column.databaseType === undefined) {
+      throw new CliError(`${where} declares nothing about "${name}".`, { code: 'USAGE', hint: 'Say `nullable`, `databaseType`, or both; leave a column out to take both from the CSV.' })
+    }
+    out.set(name, { ...(column.nullable !== undefined ? { nullable: column.nullable as boolean } : {}), ...(column.databaseType !== undefined ? { databaseType: column.databaseType as string } : {}) })
+  })
+  return out
+}
+
 const list: Command = {
   meta: {
     noun: 'dataset',
@@ -476,7 +546,9 @@ const create: Command = {
     const KIND_KEYS: Record<string, Set<string>> = {
       blank: new Set(['columns']),
       source: new Set(['source', 'schema', 'relation', 'includedColumns']),
-      file: new Set(['path', 'includedColumns']),
+      // `columns`: what the file declares of each column (its nullability, its type) instead of
+      // leaving both to the first CSV, whose contract every later upload must then match.
+      file: new Set(['path', 'includedColumns', 'columns']),
     }
     const COMMON = new Set([
       'apiName', 'displayName', 'description', 'kind', 'keyColumns', 'deterministicKeyConfirmed',
@@ -569,10 +641,21 @@ const create: Command = {
       }
       // Relative to the DEFINITION, not the shell's cwd: the two travel together in a
       // repo, and resolving against cwd broke the moment anyone ran it from elsewhere.
-      created = await api.createFromFile(
-        resolve(dirname(path), csv),
-        { ...common, includedColumns: names(document.includedColumns, 'includedColumns', filePath) },
-      )
+      const csvPath = resolve(dirname(path), csv)
+      const included = names(document.includedColumns, 'includedColumns', filePath)
+      const declared = document.columns === undefined ? null : readFileColumns(document.columns, included, filePath)
+      if (!declared) {
+        created = await api.createFromFile(csvPath, { ...common, includedColumns: included })
+      } else {
+        // The contract as the file declares it, then the CSV loaded into it: a column declared
+        // nullable stays so, whatever this CSV holds.
+        const columns = await fileContract(api, csvPath, included, declared, filePath)
+        const blank = await api.createBlank({ ...common, columns })
+        if (!blank.id) {
+          throw new CliError(`"${apiName}" was created without an id, so its rows were not loaded.`, { code: 'FAILURE', hint: `frontera dataset upload ${apiName} ${csv}` })
+        }
+        created = await api.uploadSnapshot(blank.id, csvPath)
+      }
     } else {
       throw new CliError(`${filePath} has an unknown \`kind\`: ${String(kind)}.`, {
         code: 'USAGE',
@@ -664,4 +747,70 @@ const upload: Command = {
   },
 }
 
-export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create, upload]
+const revise: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'revise',
+    args: [],
+    flags: { file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Cut a new revision of a file dataset from its CSV, when the CSV holds empty values the current revision refuses',
+    examples: ['frontera dataset revise -f datasets/work_orders.json'],
+  },
+  /**
+   * A file dataset's first load fixes which columns may be empty. A later CSV
+   * with empty values in a column that had none is refused by `upload`; this
+   * makes that CSV the dataset's next revision instead, which only widens what
+   * may be empty. A column added, dropped or retyped, or a key column that
+   * became nullable, is a different dataset: the service refuses it, naming
+   * the column. Object types still read the old revision until they are bound
+   * to the new one (`blueprint bind`, which `local dev` does).
+   */
+  async run(ctx) {
+    const filePath = flagString(ctx, 'file')
+    if (!filePath) throw new CliError('A definition file is required.', { code: 'USAGE', hint: 'frontera dataset revise -f datasets/<apiName>.json' })
+    const path = resolve(ctx.cwd, filePath)
+    let document: Record<string, unknown>
+    try {
+      document = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+    } catch (err) {
+      throw new CliError(`${filePath} could not be read as JSON: ${(err as Error).message}`, { code: 'USAGE', hint: 'A dataset definition is JSON: `frontera local schema dataset`.' })
+    }
+    if (document.kind !== 'file' || typeof document.path !== 'string' || typeof document.apiName !== 'string') {
+      throw new CliError(`${filePath} is not a file dataset.`, { code: 'USAGE', hint: 'revise reads kind: "file" with `apiName` and `path`; a Source dataset is revised from its Source.' })
+    }
+    const apiName = document.apiName
+    const csvPath = resolve(dirname(path), document.path)
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const dataset = await resolveDataset(api, apiName)
+    const revisions = await api.revisions(dataset.id!)
+    const expectedRevision = (revisions.find((r) => r.id === dataset.currentRevisionId) ?? revisions.at(-1))?.revision
+    if (typeof expectedRevision !== 'number') {
+      throw new CliError(`"${apiName}" has no current revision to follow.`, { code: 'CONFLICT', hint: `frontera dataset get ${apiName}` })
+    }
+    let result: DatasetSummary
+    try {
+      result = await api.reviseFromFile(dataset.id!, csvPath, expectedRevision)
+    } catch (err) {
+      if (err instanceof CliError && (err.code === 'DATASET_REVISION_UNCHANGED' || /DATASET_REVISION_UNCHANGED/.test(err.message))) {
+        return { data: { unchanged: true, revision: expectedRevision }, text: `"${apiName}" already fits ${basename(csvPath)}: revision ${expectedRevision} stays.` }
+      }
+      if (err instanceof CliError && err.code === 'CONFLICT') {
+        throw new CliError(err.message, {
+          code: 'CONFLICT',
+          hint: 'A new revision may only let more columns be empty. A column added, dropped or retyped (or a key column that became nullable) is a new dataset: give it another apiName, or on a local runtime run `frontera local reset`, which creates every dataset again from its definition.',
+        })
+      }
+      throw err
+    }
+    const revision = (result as { currentRevision?: { revision?: number } }).currentRevision?.revision
+    return {
+      data: result,
+      text: `Cut revision ${revision ?? expectedRevision + 1} of "${apiName}" from ${basename(csvPath)}.\n`
+        + '  Object types read the old revision until bound to this one: `frontera blueprint bind <Type> --dataset '
+        + `${apiName} --file <mapping> --accept-contract-change\`.`,
+    }
+  },
+}
+
+export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create, upload, revise]

package/src/commands/knowledge/index-commands.ts

@@ -1,7 +1,10 @@
 import { basename } from 'node:path'
 
-import { PlatformApi } from '../../api/platform-api'
+import { PlatformApi, type KnowledgeRetrieval } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
+import { DEFAULT_KNOWLEDGE_THRESHOLD, KEYLESS_KNOWLEDGE_THRESHOLD, KEYLESS_RETRIEVAL_NOTE, PLATFORM_DEFAULT_EMBEDDING, sameEmbedding, WIDENED_KNOWLEDGE_THRESHOLD } from '../../local/local-org-settings'
+import { localRuntimeAt } from '../../local/local-runtime-target'
+import { isLocalEmbeddings } from '../../local/local-seed'
 import { table } from '../../table'
 import { resolveAgentRef } from '../agent/resolve'
 import { flagString, type Command } from '../types'
@@ -124,9 +127,11 @@ const get: Command = {
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const base = await client.knowledgeBase(await resolveKnowledgeRef(client, ref))
+    // On the keyless local embeddings the threshold shown is the one set for them, and retrieval is approximate: said.
+    const local = (await keylessRetrieval(client, ctx.cwd, ctx.apiUrl)) ? { localRetrieval: keylessRetrievalInfo() } : {}
 
     return {
-      data: base,
+      data: { ...base, ...local },
       // Whatever the route returns, flattened. Naming the fields here would
       // print "?" for every one the service renames, and the embedding model
       // and chunker are exactly the fields a caller comes to this verb to read.
@@ -137,7 +142,7 @@ const get: Command = {
           v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
         ]),
         [undefined, 70],
-      ),
+      ) + ('localRetrieval' in local ? `\n\nNote: ${KEYLESS_RETRIEVAL_NOTE}.` : ''),
     }
   },
 }
@@ -160,9 +165,13 @@ const search: Command = {
     ],
     flags: { 'top-k': 'string', threshold: 'string' },
     summary: 'Search a knowledge base and show the chunks that come back',
+    details: [
+      'Without --threshold the base\'s own match threshold cuts the results, as an Agent\'s retrieval does. The cutoff is a maximum cosine distance from 0 to 2 (lower is stricter), while a score is higher-is-better: with vector scoring a score is 1 − distance / 2, so a 0.5 cutoff keeps scores above 0.75. The output says which cutoff applied.',
+    ],
     examples: [
       'frontera knowledge search product-docs "how do refunds work"',
       'frontera knowledge search product-docs "refund policy" --top-k 3 --json',
+      'frontera knowledge search product-docs "refund policy" --threshold 0.8',
     ],
   },
   async run(ctx) {
@@ -182,8 +191,9 @@ const search: Command = {
     }
     const thresholdRaw = flagString(ctx, 'threshold')
     const threshold = thresholdRaw === undefined ? undefined : Number(thresholdRaw)
-    if (threshold !== undefined && Number.isNaN(threshold)) {
-      throw new UsageError(`--threshold must be a number, not "${thresholdRaw}"`, 'try --threshold 0.7')
+    // A maximum cosine distance: 0 matches only identical text, 2 matches everything.
+    if (threshold !== undefined && (Number.isNaN(threshold) || threshold < 0 || threshold > 2)) {
+      throw new UsageError(`--threshold must be a cosine distance from 0 to 2, not "${thresholdRaw}"`, 'lower is stricter: try --threshold 0.8 to widen a search the base\'s own cutoff empties')
     }
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
@@ -195,42 +205,104 @@ const search: Command = {
     })
 
     const chunks = result.results
+    const cutoff = cutoffLine(result.retrieval, threshold)
+    // On the keyless local embeddings: retrieval is approximate, said with what gives the platform's.
+    const keyless = await keylessRetrieval(client, ctx.cwd, ctx.apiUrl)
+    const keylessLine = keyless ? `\n  Note: ${KEYLESS_RETRIEVAL_NOTE}.` : ''
+    if (keyless) Object.assign(result, { localRetrieval: keylessRetrievalInfo() })
     if (chunks.length === 0) {
       // The overwhelmingly common cause, and the one a caller cannot see from
       // here: ingestion is asynchronous, so a base uploaded a minute ago is
       // empty rather than broken.
+      // How near the search came, when the service says: the threshold that would show it.
+      const nearest = result.retrieval?.nearestDistance
+      const max = typeof result.retrieval?.maxDistance === 'number' ? result.retrieval.maxDistance : threshold
+      if (typeof nearest === 'number') {
+        // Only asked when it could matter: a near miss the widened local threshold would keep.
+        const embedding = !keyless && nearMissOfWidening(nearest) ? await client.embeddingSetting().catch(() => null) : null
+        const widening = embeddingNote(nearest, embedding, isLoopbackApi(ctx.apiUrl))
+        return {
+          data: result,
+          text: `No chunks matched: the nearest chunk is at distance ${nearest}, past the cutoff${max === undefined ? '' : ` of ${max}`}. \`--threshold\` above ${nearest} (up to 2) shows it; setting the base's \`similarityThreshold\` there changes what an Agent's retrieval keeps.\n  ${cutoff}${widening ? `\n  ${widening}` : ''}${keylessLine}`,
+        }
+      }
+      if (nearest === null) {
+        return {
+          data: result,
+          text: `No chunks matched: ${ref} has nothing searchable yet. \`frontera knowledge sources ${ref}\` lists its documents: none, or still \`processing\`.`,
+        }
+      }
       return {
         data: result,
         text:
           'No chunks matched.\n'
           + `  If the upload was recent, check \`frontera knowledge sources ${ref}\` — a source\n`
           + '  still `processing` is not searchable yet.\n'
-          // Stated the right way round: --threshold is a distance cutoff, so a
-          // LOW value is the restrictive one and 0 can never match.
-          + (threshold !== undefined
-            ? `  --threshold ${threshold} is a maximum cosine distance — raise it to widen the search.\n`
-            : '  The default cutoff is 0.9; pass a higher --threshold to widen the search.\n')
-          + '  Otherwise the corpus may simply not cover this.',
+          + `  ${cutoff} Raise --threshold (up to 2) to widen the search.\n`
+          + '  Otherwise the corpus may simply not cover this.'
+          + keylessLine,
       }
     }
 
+    // A distance beside each score when the service gives one: it is what the cutoff compares.
+    const distances = chunks.some((c) => typeof c.distance === 'number')
     return {
       data: result,
       text: table(
-        ['score', 'source', 'chunk'],
+        ['score', ...(distances ? ['distance'] : []), 'source', 'chunk'],
         chunks.map((c) => [
           typeof c.score === 'number' ? c.score.toFixed(3) : String(c.score ?? ''),
+          ...(distances ? [typeof c.distance === 'number' ? c.distance.toFixed(3) : ''] : []),
           String(c.fileName ?? c.sourceId ?? ''),
           String(c.content ?? c.text ?? '').replace(/\s+/g, ' ').trim(),
         ]),
-        [8, 30, 90],
-      ),
+        distances ? [8, 9, 30, 90] : [8, 30, 90],
+      ) + `\n\n${cutoff}${keylessLine}`,
     }
   },
 }
 
+/** Whether the nearest distance sits between the default threshold and the one a local runtime widens to. */
+function nearMissOfWidening(nearest: number): boolean {
+  return nearest > DEFAULT_KNOWLEDGE_THRESHOLD && nearest <= WIDENED_KNOWLEDGE_THRESHOLD
+}
+
 /**
- * Re-run ingestion for a source that failed.
+ * Why a near miss may be the embedding model rather than the corpus: the
+ * default threshold is tuned for the platform's default embedding model, and
+ * another model ranks on-topic passages a little further away. A local
+ * runtime widens such a base's threshold when `frontera local dev` applies
+ * it, and this says so. Null when the miss is not in that band, or the model
+ * is the default or not known.
+ */
+export function embeddingNote(nearest: number, embedding: { provider: string | null; model: string | null } | null, local = true): string | null {
+  if (!nearMissOfWidening(nearest)) return null
+  if (!embedding?.provider || !embedding.model || sameEmbedding(embedding, PLATFORM_DEFAULT_EMBEDDING)) return null
+  // A hosted workspace hears only what it can act on: its own model, and the base's Match threshold.
+  if (!local) return `This organization embeds with ${embedding.provider} / ${embedding.model}, not the model the default threshold of ${DEFAULT_KNOWLEDGE_THRESHOLD} is tuned for, so on-topic passages sit further away: if relevant passages are cut off, raise the base's Match threshold.`
+  return `This organization embeds with ${embedding.provider} / ${embedding.model}, not the platform's default (${PLATFORM_DEFAULT_EMBEDDING.provider} / ${PLATFORM_DEFAULT_EMBEDDING.model}) the default threshold of ${DEFAULT_KNOWLEDGE_THRESHOLD} is tuned for, so on-topic passages sit further away. A local runtime widens a base's threshold to ${WIDENED_KNOWLEDGE_THRESHOLD} when \`frontera local dev\` applies it, if its file sets none or ${DEFAULT_KNOWLEDGE_THRESHOLD}.`
+}
+
+/**
+ * Which cutoff the search applied, on the scale `score` is read on: the
+ * base's own match threshold unless `--threshold` named one (that is what an
+ * Agent's retrieval uses), a maximum cosine distance, so a 0.5 cutoff keeps
+ * similarity scores above 0.75 and a 0.70 score is outside it.
+ */
+export function cutoffLine(retrieval: KnowledgeRetrieval | undefined, threshold: number | undefined): string {
+  const max = typeof retrieval?.maxDistance === 'number' ? retrieval.maxDistance : threshold
+  const from = retrieval?.thresholdFrom === 'request' || (!retrieval && threshold !== undefined) ? '--threshold' : 'the base\'s own match threshold, as an Agent\'s retrieval uses it'
+  if (max === undefined) return 'Cutoff: the base\'s own match threshold, as an Agent\'s retrieval uses it (a maximum cosine distance from 0 to 2; lower is stricter).'
+  if (retrieval?.scoring === 'fusion' || retrieval?.scoring === 'rerank') {
+    return `Cutoff: a maximum cosine distance of ${max}, from ${from}. Scores here are the ${retrieval.scoring === 'rerank' ? 'reranker\'s' : 'keyword and vector fusion\'s'}, so a score isn't comparable to the cutoff.`
+  }
+  const minScore = typeof retrieval?.minScore === 'number' ? retrieval.minScore : Math.max(0, 1 - max / 2)
+  return `Cutoff: a maximum cosine distance of ${max}, from ${from}: scores ≥ ${Number(minScore.toFixed(3))} (score = 1 − distance / 2).`
+}
+
+/**
+ * Re-run ingestion for a source that failed, or that is stuck pending or
+ * processing with no ingestion behind it (`local status` names one).
  *
  * `upload` exits 0 on a partial batch by design — one unreadable file does not
  * end the run — so a failed source is normal and recovery has to be normal
@@ -246,7 +318,7 @@ const retry: Command = {
       { name: 'source', required: true, description: 'source id, from `frontera knowledge sources`' },
     ],
     flags: {},
-    summary: 'Re-run ingestion for one source that failed',
+    summary: 'Re-run ingestion for one source that failed or is stuck processing',
     examples: ['frontera knowledge retry product-docs <sourceId>'],
   },
   async run(ctx) {
@@ -511,12 +583,15 @@ const agents: Command = {
         rows.length === 0
           ? `No agent can read ${ref} — attach one with \`frontera knowledge attach ${ref} <agent>\`.`
           : table(
-              ['agent', 'id'],
+              ['agent', 'id', 'attached in'],
               rows.map((r) => {
                 const id = String(r.agentId ?? '')
-                // An agent still in `configuring` is absent from `agent list`,
-                // so print the id rather than a "?" that reads as corruption.
-                return [slugs.get(id) ?? id, id]
+                // The row names the Agent's slug; an older platform's does not, and an agent still in
+                // `configuring` is absent from `agent list`, so print the id rather than a "?".
+                const slug = typeof r.agentSlug === 'string' && r.agentSlug ? r.agentSlug : slugs.get(id) ?? id
+                // Published, staged in its draft, or both; an older platform lists only published ones.
+                const where = r.published === false ? 'draft' : r.staged === false ? 'published (its draft drops it)' : r.staged === true ? 'published and draft' : 'published'
+                return [slug, id, where]
               }),
             ),
     }
@@ -563,3 +638,30 @@ export const knowledgeCommands: Command[] = [
   agents,
   ...reserved,
 ]
+
+/** Whether the command talks to a runtime on this machine (a local runtime is always on a loopback address). */
+/**
+ * Whether this runs on the keyless local embeddings: only against the
+ * project's own local runtime (`isLocalEmbeddings` reads this computer's
+ * keys), read from the organization's embedding setting. False when it
+ * can't say, and anywhere else.
+ */
+async function keylessRetrieval(client: PlatformApi, cwd: string, apiUrl: string): Promise<boolean> {
+  if (!localRuntimeAt(cwd, apiUrl)) return false
+  const embedding = await client.embeddingSetting().catch(() => null)
+  return !!embedding && isLocalEmbeddings(embedding)
+}
+
+/** What `--json` carries beside a base or a search on the keyless local embeddings. */
+export function keylessRetrievalInfo() {
+  return { embeddings: 'keyless-local', approximate: true, threshold: KEYLESS_KNOWLEDGE_THRESHOLD, note: KEYLESS_RETRIEVAL_NOTE } as const
+}
+
+function isLoopbackApi(apiUrl: string): boolean {
+  try {
+    const host = new URL(apiUrl).hostname
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1' || host.endsWith('.localhost')
+  } catch {
+    return false
+  }
+}