@prestack/thread 0.0.1 → 0.0.3

package/dist/core/tree.ts

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { cwd } from 'node:process'
+
+const NAMES = ['_threads', 'threads'] as const
+const ROOT = 'thread.ts'
+
+export interface Tree {
+  readonly at: string
+  readonly dir: string
+  readonly name: string
+  readonly root: string
+}
+
+export class UnthreadedRepositoryError extends Error {
+  constructor(from: string) {
+    super(
+      `no tree above ${from} — looked for a ${NAMES.map((one) => `${one}/`).join(' or ')} directory in every directory up to the filesystem root. ` +
+        'Run `thread init` to write one.',
+    )
+    this.name = 'UnthreadedRepositoryError'
+  }
+}
+
+export function findTree(from: string = cwd()): Tree {
+  let at = resolve(from)
+  for (;;) {
+    for (const name of NAMES) {
+      const dir = join(at, name)
+      if (existsSync(dir) && statSync(dir).isDirectory()) return { at, dir, name, root: join(dir, ROOT) }
+    }
+    const up = dirname(at)
+    if (up === at) throw new UnthreadedRepositoryError(from)
+    at = up
+  }
+}
+
+export function strayFiles(root: string, prefix: string, ends: string): readonly string[] {
+  const skip = new Set(['node_modules', '.git', '.next', 'dist', '_generated', 'coverage'])
+  const found: string[] = []
+  const walk = (dir: string): void => {
+
+    let held
+    try {
+      held = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const one of held) {
+      if (one.name.startsWith('.') || skip.has(one.name)) continue
+      const path = join(dir, one.name)
+      if (one.isDirectory()) {
+        walk(path)
+        continue
+      }
+      if (one.name.startsWith(prefix) && one.name.endsWith(ends)) {
+        found.push(relative(root, path).split('\\').join('/'))
+      }
+    }
+  }
+  walk(root)
+  return found.sort()
+}
+
+export function inTree(tree: Tree, file: string): string {
+  return join(tree.dir, file)
+}

package/dist/core/types.ts

@@ -0,0 +1,350 @@
+export const VALUE_TYPES = ['text', 'number', 'boolean', 'date', 'timestamp', 'json'] as const
+
+export type ValueType = (typeof VALUE_TYPES)[number]
+
+export const KEYBOARDS = ['text', 'numeric', 'decimal', 'tel', 'email', 'url', 'search'] as const
+
+export type Keyboard = (typeof KEYBOARDS)[number]
+
+export const ENTRY_MODES = ['plain', 'calculator', 'masked'] as const
+
+export type EntryMode = (typeof ENTRY_MODES)[number]
+
+export type Checked = { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly because: string }
+
+export const held = (value: unknown): Checked => ({ ok: true, value })
+
+export const refused = (because: string): Checked => ({ ok: false, because })
+
+export interface Facts {
+  readonly locale?: string
+  readonly currency?: string
+  readonly min?: number
+  readonly max?: number
+  readonly maxLen?: number
+  readonly maxBytes?: number
+  readonly maxDepth?: number
+  readonly options?: readonly string[]
+  readonly now?: number
+}
+
+export interface Format {
+  readonly name: string
+  readonly type: ValueType
+  readonly check: (raw: unknown, facts: Facts) => Checked
+  readonly shown?: (value: unknown, facts: Facts) => string
+  readonly keyboard?: Keyboard
+  readonly accepts?: RegExp
+  readonly maxChars?: number
+  readonly entry?: EntryMode
+  readonly mask?: string
+  readonly secret?: boolean
+  readonly autocomplete?: string
+  readonly requires?: readonly string[]
+}
+
+export function stripControl(text: string): string {
+  let out = ''
+  for (const character of text) {
+    const point = character.codePointAt(0) ?? 0
+    const control = point <= 0x08 || point === 0x0b || point === 0x0c || (point >= 0x0e && point <= 0x1f) || (point >= 0x7f && point <= 0x9f)
+    if (!control) out += character
+  }
+  return out
+}
+
+const numeric = (raw: unknown): number => (typeof raw === 'number' ? raw : Number(raw))
+
+const SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+
+export const BOUNDED: Readonly<Partial<Record<ValueType, string>>> = {
+  text: 'number of characters',
+  number: 'value',
+}
+
+function bounded(one: number, facts: Facts): Checked {
+  if (facts.min !== undefined && one < facts.min) return refused('format.number.below_min')
+  if (facts.max !== undefined && one > facts.max) return refused('format.number.above_max')
+  return held(one)
+}
+
+function depthWithin(value: unknown, limit: number, depth = 0): boolean {
+  if (depth > limit) return false
+  if (Array.isArray(value)) return value.every((one) => depthWithin(one, limit, depth + 1))
+  if (value !== null && typeof value === 'object') return Object.values(value).every((one) => depthWithin(one, limit, depth + 1))
+  return true
+}
+
+const instant = (raw: unknown): Checked =>
+  typeof raw === 'string' && !Number.isNaN(Date.parse(raw))
+    ? held(new Date(raw).toISOString())
+    : refused('format.timestamp.unreadable')
+
+const dated = (value: unknown, facts: Facts, options: Intl.DateTimeFormatOptions): string =>
+  new Intl.DateTimeFormat(facts.locale, options).format(new Date(String(value)))
+
+export const FORMATS: readonly Format[] = [
+  {
+    name: 'text',
+    type: 'text',
+    keyboard: 'text',
+    check: (raw, facts) => {
+      if (typeof raw !== 'string') return refused('format.text.not_text')
+      const clean = stripControl(raw).trim()
+      return facts.maxLen !== undefined && clean.length > facts.maxLen ? refused('format.text.too_long') : held(clean)
+    },
+  },
+  {
+    name: 'email',
+    type: 'text',
+    keyboard: 'email',
+    autocomplete: 'email',
+    check: (raw) => {
+      if (typeof raw !== 'string') return refused('format.email.invalid')
+      const one = raw.trim().toLowerCase()
+      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(one) ? held(one) : refused('format.email.invalid')
+    },
+  },
+  {
+    name: 'tel',
+    type: 'text',
+    keyboard: 'tel',
+    accepts: /[0-9+]/,
+    maxChars: 16,
+    autocomplete: 'tel',
+    check: (raw) => {
+      if (typeof raw !== 'string') return refused('format.tel.invalid')
+      const digits = raw.replace(/[^\d+]/g, '')
+      return /^\+?\d{6,15}$/.test(digits) ? held(digits) : refused('format.tel.invalid')
+    },
+  },
+  {
+    name: 'url',
+    type: 'text',
+    keyboard: 'url',
+    check: (raw) => {
+      if (typeof raw !== 'string') return refused('format.url.invalid')
+      let parsed: URL
+      try {
+        parsed = new URL(raw.trim())
+      } catch {
+        return refused('format.url.invalid')
+      }
+      return SCHEMES.has(parsed.protocol) ? held(parsed.toString()) : refused('format.url.scheme')
+    },
+  },
+  {
+    name: 'password',
+    type: 'text',
+    secret: true,
+    maxChars: 256,
+    autocomplete: 'current-password',
+    check: (raw) => (typeof raw === 'string' && raw.length >= 8 ? held(raw) : refused('format.password.too_short')),
+  },
+  {
+    name: 'otp',
+    type: 'text',
+    keyboard: 'numeric',
+    accepts: /\d/,
+    maxChars: 6,
+    autocomplete: 'one-time-code',
+    check: (raw) => (typeof raw === 'string' && /^\d{6}$/.test(raw) ? held(raw) : refused('format.otp.invalid')),
+  },
+  {
+    name: 'ref',
+    type: 'text',
+    check: (raw) => (typeof raw === 'string' && /^ref:[a-z0-9/_-]+$/i.test(raw) ? held(raw) : refused('format.ref.invalid')),
+  },
+
+  {
+    name: 'choice',
+    type: 'text',
+    requires: ['options'],
+    check: (raw, facts) => {
+      if (facts.options === undefined) return refused('format.choice.undeclared_options')
+      return typeof raw === 'string' && facts.options.includes(raw) ? held(raw) : refused('format.choice.undeclared')
+    },
+  },
+  {
+    name: 'number',
+    type: 'number',
+    keyboard: 'decimal',
+    accepts: /[0-9.,-]/,
+    check: (raw, facts) => {
+      const one = numeric(raw)
+      return Number.isFinite(one) ? bounded(one, facts) : refused('format.number.invalid')
+    },
+  },
+  {
+    name: 'integer',
+    type: 'number',
+    keyboard: 'numeric',
+    accepts: /[0-9-]/,
+    check: (raw, facts) => {
+      const one = numeric(raw)
+      return Number.isInteger(one) ? bounded(one, facts) : refused('format.integer.invalid')
+    },
+  },
+  {
+    name: 'money',
+    type: 'number',
+    keyboard: 'decimal',
+    accepts: /[0-9]/,
+    entry: 'calculator',
+    requires: ['currency'],
+    check: (raw, facts) => {
+      const one = numeric(raw)
+      return Number.isFinite(one) ? bounded(one, facts) : refused('format.money.invalid')
+    },
+    shown: (value, facts) =>
+      facts.currency === undefined
+        ? String(value)
+        : new Intl.NumberFormat(facts.locale, { style: 'currency', currency: facts.currency }).format(Number(value)),
+  },
+  {
+    name: 'percent',
+    type: 'number',
+    keyboard: 'decimal',
+    accepts: /[0-9.,]/,
+    check: (raw) => {
+      const one = numeric(raw)
+      return Number.isFinite(one) && one >= 0 && one <= 100 ? held(one) : refused('format.percent.range')
+    },
+    shown: (value, facts) =>
+      new Intl.NumberFormat(facts.locale, { style: 'percent', maximumFractionDigits: 1 }).format(Number(value) / 100),
+  },
+  {
+    name: 'duration',
+    type: 'number',
+    keyboard: 'numeric',
+    accepts: /[0-9]/,
+    check: (raw) => {
+      const one = numeric(raw)
+      if (!Number.isFinite(one)) return refused('format.number.invalid')
+      return one < 0 ? refused('format.duration.negative') : held(one)
+    },
+  },
+  {
+    name: 'rating',
+    type: 'number',
+    keyboard: 'numeric',
+    accepts: /[0-9]/,
+    check: (raw, facts) => {
+      const one = numeric(raw)
+      const ceiling = facts.max ?? 5
+      return Number.isInteger(one) && one >= 1 && one <= ceiling ? held(one) : refused('format.rating.range')
+    },
+  },
+  {
+    name: 'boolean',
+    type: 'boolean',
+    check: (raw) => {
+      if (typeof raw === 'boolean') return held(raw)
+      if (raw === 'true' || raw === 'false') return held(raw === 'true')
+      return refused('format.boolean.invalid')
+    },
+  },
+  {
+    name: 'date',
+    type: 'date',
+    keyboard: 'numeric',
+    accepts: /[0-9-]/,
+    maxChars: 10,
+    mask: '0000-00-00',
+    entry: 'masked',
+    check: (raw) => {
+      if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw)) return refused('format.date.shape')
+      return Number.isNaN(Date.parse(raw)) ? refused('format.date.invalid') : held(raw)
+    },
+    shown: (value, facts) => dated(`${String(value)}T00:00:00Z`, facts, { dateStyle: 'medium', timeZone: 'UTC' }),
+  },
+  {
+    name: 'timestamp',
+    type: 'timestamp',
+    check: instant,
+    shown: (value, facts) => dated(value, facts, { dateStyle: 'medium', timeStyle: 'short' }),
+  },
+  {
+    name: 'elapsed',
+    type: 'timestamp',
+    check: instant,
+    requires: ['now'],
+    shown: (value, facts) => {
+      const now = facts.now ?? Date.parse(new Date().toISOString())
+      const gap = Date.parse(String(value)) - now
+      const UNITS: readonly (readonly [Intl.RelativeTimeFormatUnit, number])[] = [
+        ['year', 31_536_000_000],
+        ['month', 2_592_000_000],
+        ['week', 604_800_000],
+        ['day', 86_400_000],
+        ['hour', 3_600_000],
+        ['minute', 60_000],
+        ['second', 1000],
+      ]
+      const spoken = new Intl.RelativeTimeFormat(facts.locale, { numeric: 'auto' })
+      for (const [unit, span] of UNITS) {
+        if (Math.abs(gap) >= span) return spoken.format(Math.trunc(gap / span), unit)
+      }
+      return spoken.format(0, 'second')
+    },
+  },
+  {
+    name: 'json',
+    type: 'json',
+    check: (raw, facts) => {
+      if (facts.maxDepth !== undefined && !depthWithin(raw, facts.maxDepth)) return refused('format.json.too_deep')
+      const size = JSON.stringify(raw)?.length ?? 0
+      return facts.maxBytes !== undefined && size > facts.maxBytes ? refused('format.json.too_large') : held(raw)
+    },
+  },
+  {
+    name: 'geo',
+    type: 'json',
+    check: (raw) => {
+      if (raw === null || typeof raw !== 'object') return refused('format.geo.invalid')
+      const { lat, lng } = raw as { lat?: unknown; lng?: unknown }
+      const within = typeof lat === 'number' && lat >= -90 && lat <= 90 && typeof lng === 'number' && lng >= -180 && lng <= 180
+      return within ? held({ lat, lng }) : refused('format.geo.invalid')
+    },
+  },
+  {
+    name: 'richtext',
+    type: 'json',
+    check: (raw) => {
+      if (raw === null || typeof raw !== 'object') return refused('format.richtext.invalid')
+      const blocks = (raw as { blocks?: unknown }).blocks
+      return Array.isArray(blocks) ? held({ blocks }) : refused('format.richtext.invalid')
+    },
+  },
+]
+
+const BY_NAME = new Map(FORMATS.map((one) => [one.name, one]))
+
+export function formatsOf(type: ValueType): readonly Format[] {
+  return FORMATS.filter((one) => one.type === type)
+}
+
+export function formatNamed(name: string): Format | undefined {
+  return BY_NAME.get(name)
+}
+
+export function plainFormat(type: ValueType): Format {
+  const one = BY_NAME.get(type)
+  if (one === undefined) throw new Error(`no plain format is declared for value type "${type}"`)
+  return one
+}
+
+export function formatFor(type: ValueType, name: string | undefined): Format | undefined {
+  const one = name === undefined ? plainFormat(type) : BY_NAME.get(name)
+  return one === undefined || one.type !== type ? undefined : one
+}
+
+export function checkValue(type: ValueType, name: string | undefined, raw: unknown, facts: Facts = {}): Checked {
+  const one = formatFor(type, name)
+  return one === undefined ? refused(`format.unusable.${name ?? type}`) : one.check(raw, facts)
+}
+
+export function showValue(type: ValueType, name: string | undefined, value: unknown, facts: Facts = {}): string {
+  const one = formatFor(type, name)
+  return one?.shown === undefined ? String(value) : one.shown(value, facts)
+}

package/dist/derivation/attach.js

@@ -37,7 +37,7 @@ const SHIPPED = [
         into: 'derivation.ts',
         list: 'GENERATORS',
         id: 'release-generator',
-        source: "  {\n    id: 'release-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/release.js',\n    describes: 'The writer of what a host reads to run this app — it derives the config from what the app already declares, its own build and start commands and the names of every secret it says it must be given, and refuses its own output if a module of this framework ever appears in it, because what a host runs may hold nothing of the scaffolding that assembled it.',\n    version: 1,\n    by: 'thread release',\n    runs: 'thread release --check',\n  },",
+        source: "  {\n    id: 'release-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/release.js',\n    describes: 'The writer of what a host reads to run this app — it derives the config from what the app already declares, its own build and start commands and the names of every secret it says it must be given, and refuses to write while this app installs a package of this framework as a dependency, because what a host runs may hold nothing of the scaffolding that assembled it.',\n    version: 1,\n    by: 'thread release',\n    runs: 'thread release --check',\n  },",
     },
     {
         into: 'derivation.ts',

package/dist/derivation/attach.ts

@@ -0,0 +1,68 @@
+import type { Attaching } from '../core/attach.ts'
+
+import { quoted } from '../core/rows.ts'
+
+const DESCRIBES =
+  'What turns a declaration into a file: the rows that state something is to be made, and the generators that make it. They are kept apart so you can read what an app declares without opening the machinery that builds it.'
+
+const DERIVATION_SOURCE = [
+  "import type { Threaded } from '../core/thread.ts'",
+  '',
+  'export const DERIVATION: Threaded = {',
+  "  id: 'derivation',",
+  "  at: '_threads/derivation.ts',",
+  `  describes: ${quoted(DESCRIBES)},`,
+  '  version: 1,',
+  '  derives: [],',
+  '}',
+  '',
+  'export const GENERATORS: readonly Threaded[] = []',
+  '',
+].join('\n')
+
+const SEEDED = {
+  attaches: [] as const,
+  id: 'derivation',
+  declares: [
+    '    {',
+    '      id: \'derivation\',',
+    '      at: \'_threads/derivation.ts\',',
+    '      describes: \'What turns a declaration into a file: the rows that state something is to be made, and the generators that make it. They are kept apart so you can read what an app declares without opening the machinery that builds it.\',',
+    '      version: 1,',
+    '    },',
+  ].join('\n'),
+}
+
+const SHIPPED: readonly { readonly into: string; readonly list: string; readonly id: string; readonly source: string }[] = [
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'build-generator',
+    source: "  {\n    id: 'build-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/build.js',\n    describes: 'The builder of what this app ships — it reads the row that derives an artifact to learn the entry it comes from, and refuses to resolve any file inside the app the descent never reaches, so a file nothing declares has no way into the thing that runs.',\n    version: 1,\n    by: 'thread build',\n    runs: 'thread build --check',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'release-generator',
+    source: "  {\n    id: 'release-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/release.js',\n    describes: 'The writer of what a host reads to run this app — it derives the config from what the app already declares, its own build and start commands and the names of every secret it says it must be given, and refuses to write while this app installs a package of this framework as a dependency, because what a host runs may hold nothing of the scaffolding that assembled it.',\n    version: 1,\n    by: 'thread release',\n    runs: 'thread release --check',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'release-noun',
+    source: "  {\n    id: 'release-noun',\n    at: 'node_modules/@prestack/thread/dist/derivation/makers/release.js',\n    describes: 'The command that declares where this app goes when it leaves your machine. It writes the row saying where this app goes and nothing else, because everything the config needs is already declared somewhere and asking for it again would be the app’s own facts typed a second time.',\n    version: 1,\n    by: 'thread create release',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'generator-noun',
+    source: "  {\n    id: 'generator-noun',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/derivation.js',\n    describes: 'Declares a generator this app derives a file with. `thread create generator` asks what it is, where its file goes and the command that writes it, then writes the row and seeds the file beside it — so a generator arrives through the same wizard as everything else, and the command it names exists from that moment because the CLI reads every `by:` the tree states.',\n    version: 1,\n    by: 'thread create generator',\n  },",
+  },
+]
+export const ATTACH: Attaching = {
+  attaches: SEEDED.attaches,
+  id: SEEDED.id,
+  declares: SEEDED.declares,
+  writes: [{ file: 'derivation.ts', source: DERIVATION_SOURCE }],
+  rows: SHIPPED,
+}