@prestack/thread 0.1.20 → 0.1.22

package/dist/integrations/cli.ts

@@ -1,615 +0,0 @@
-import { spawn, spawnSync, type ChildProcessWithoutNullStreams, type SpawnSyncReturns } from 'node:child_process'
-import { createHash, randomBytes } from 'node:crypto'
-import { tmpdir, uptime } from 'node:os'
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
-import { allowedNodeEnvironmentFlags, env, execPath, kill, pid, stderr, stdout } from 'node:process'
-import { fileURLToPath } from 'node:url'
-
-import { CHANNEL, FOLDER, across, attached, createFileSync, existsSync, here, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from '../integrations/disk.ts'
-import { VAULT_DIR } from '../integrations/vault.ts'
-
-import { CALL_PREFIX, LOCKFILES, ORDERS, PACKAGER, REACH, managerOf, programOf, unlisted, type Answer, type Call, type How, type Order, type Ran, type Recorded, type Running, type Target } from '../integrations/target.ts'
-import { BESIDE, CLI } from '../core/invoked.ts'
-import { valuesIn } from '../core/rows.ts'
-import { THING } from '../core/scope.ts'
-import { findTree, inTree } from '../core/tree.ts'
-
-export interface Starting {
-
-  readonly at?: string
-
-  readonly shows?: boolean | 'errors' | 'tee'
-
-  readonly hears?: string
-
-  readonly within?: number
-
-  readonly holds?: NodeJS.ProcessEnv
-}
-
-const answered = (went: SpawnSyncReturns<string>): Ran => ({
-  there: went.error === undefined,
-  ok: went.status === 0,
-  code: went.status ?? 1,
-  out: String(went.stdout ?? ''),
-  err: String(went.stderr ?? ''),
-  killed: went.signal ?? null,
-  why: went.error === undefined ? '' : went.error.message,
-})
-
-const standing = (at: string | undefined): string | undefined => (at === undefined || across(at) ? undefined : at)
-
-export function starts(program: string, words: readonly string[], how: Starting = {}): Ran {
-  let went: SpawnSyncReturns<string>
-  try {
-    went = spawnSync(program, [...words], {
-      cwd: standing(how.at),
-      encoding: 'utf8',
-      shell: false,
-      stdio:
-        how.shows === true
-          ? [how.hears === undefined ? 'inherit' : 'pipe', 'inherit', 'inherit']
-          : how.shows === 'errors'
-            ? [how.hears === undefined ? 'ignore' : 'pipe', 'pipe', 'inherit']
-            : 'pipe',
-      input: how.hears,
-      env: how.holds,
-      ...(how.within === undefined ? {} : { timeout: how.within, killSignal: 'SIGKILL' as const }),
-    })
-  } catch (thrown) {
-    return nowhere(thrown instanceof Error ? thrown.message : String(thrown))
-  }
-  const ran = answered(went)
-  if (how.shows === 'tee') {
-    stdout.write(ran.out)
-    stderr.write(ran.err)
-  }
-  return ran
-}
-
-export function started(program: string, words: readonly string[], how: Starting = {}): Promise<Ran> {
-  return new Promise((keep) => {
-    let child: ChildProcessWithoutNullStreams
-    try {
-      child = spawn(program, [...words], { cwd: standing(how.at), shell: false, env: how.holds })
-    } catch (thrown) {
-      keep(nowhere(thrown instanceof Error ? thrown.message : String(thrown)))
-      return
-    }
-    let out = ''
-    let err = ''
-    let why = ''
-    const clock = how.within === undefined ? undefined : setTimeout(() => child.kill('SIGKILL'), how.within)
-    child.stdout.on('data', (chunk: Buffer) => (out += chunk.toString()))
-    child.stderr.on('data', (chunk: Buffer) => (err += chunk.toString()))
-    child.on('error', (error) => (why = error.message))
-    child.on('close', (code, killed) => {
-      if (clock !== undefined) clearTimeout(clock)
-      keep({ there: why === '', ok: why === '' && code === 0, code: code ?? 1, out, err, killed, why })
-    })
-    child.stdin.end(how.hears)
-  })
-}
-
-export function handed(
-  at: string,
-  program: string,
-  passed: readonly string[],
-  shows: boolean | 'errors' | 'tee' = true,
-  within?: number,
-  hears?: string,
-): Ran {
-  return starts(program, passed, { at, shows, ...(within === undefined ? {} : { within }), ...(hears === undefined ? {} : { hears }) })
-}
-
-const HOLDING = 'THREAD_RUNNING'
-
-const CLAIMED = 'running.'
-
-const CLAIM = '.json'
-
-const STARTING = 10_000
-
-export interface Holding {
-  readonly pid: number
-  readonly runs: string
-  readonly since: number
-}
-
-export interface Held {
-  readonly by?: Holding
-}
-
-let claimed = ''
-
-const claimAt = (dir: string, one: number): string => join(dir, CLAIMED + String(one) + CLAIM)
-
-const generations = (dir: string): readonly number[] =>
-  existsSync(dir)
-    ? readdirSync(dir)
-        .filter((one) => one.startsWith(CLAIMED) && one.endsWith(CLAIM))
-        .map((one) => Number(one.slice(CLAIMED.length, one.length - CLAIM.length)))
-        .filter((one) => Number.isInteger(one) && one >= 0)
-    : []
-
-const living = (one: number): boolean => {
-  try {
-    kill(one, 0)
-    return true
-  } catch (thrown) {
-    return (thrown as NodeJS.ErrnoException).code === 'EPERM'
-  }
-}
-
-function holding(at: string): Held {
-  try {
-    const by = JSON.parse(readFileSync(at, 'utf8')) as Holding
-    return by.since > Date.now() - uptime() * 1000 && living(by.pid) ? { by } : {}
-  } catch {
-    try {
-      return Date.now() - statSync(at).mtimeMs < STARTING ? { by: { pid: 0, runs: '', since: Date.now() } } : {}
-    } catch {
-      return {}
-    }
-  }
-}
-
-export function releases(): void {
-  const at = claimed === '' ? env[HOLDING] : claimed
-  if (at !== undefined) rmSync(at, { force: true })
-  claimed = ''
-  Reflect.deleteProperty(env, HOLDING)
-}
-
-export function claims(root: string, runs: string): Held {
-  if (attached()) return {}
-  const dir = join(root, VAULT_DIR)
-  for (let tries = 0; tries < 5; tries += 1) {
-    const taken = generations(dir)
-    const top = Math.max(-1, ...taken)
-    const held: Held = top < 0 ? {} : holding(claimAt(dir, top))
-    if (held.by !== undefined) return env[HOLDING] === claimAt(dir, top) ? {} : held
-    const mine = claimAt(dir, top + 1)
-    if (!createFileSync(mine, JSON.stringify({ pid, runs, since: Date.now() }))) continue
-    claimed = mine
-    env[HOLDING] = mine
-    for (const one of taken) rmSync(claimAt(dir, one), { force: true })
-    process.on('exit', releases)
-    return {}
-  }
-  return { by: { pid: 0, runs: '', since: Date.now() } }
-}
-
-export function programFor(name: string, at: string): string {
-  const found = programOf(name, at, existsSync)
-  if (found === undefined) throw new Error(unlisted(name))
-  return found
-}
-
-export const SIGNING = 'THREAD_RECEIPTS_KEY'
-
-const SIGNED_AT = 'thread-receipts.key'
-
-let signed = ''
-
-export function signing(): string {
-  if (signed !== '') return signed
-  const given = env[SIGNING]
-  if (given !== undefined && given !== '') {
-    signed = given
-    return signed
-  }
-  if (attached()) {
-    throw new Error(
-      'this answers for a folder on another machine and was handed no key to seal receipts with, so it issues none. ' +
-        'The server that started it hands one over in ' + SIGNING + '.',
-    )
-  }
-  const at = join(tmpdir(), SIGNED_AT)
-  if (!existsSync(at)) createFileSync(at, randomBytes(32).toString('hex'))
-  signed = readFileSync(at, 'utf8').trim()
-  return signed
-}
-
-const OWN = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
-
-export const PROGRAM = REACH.cli + THING
-
-export const COPIES = THING + ' create copy'
-
-export const COPY_AT = join(VAULT_DIR, THING + '.json')
-
-interface Started {
-  readonly words: readonly string[]
-  readonly own: string
-  readonly reads: readonly string[]
-}
-
-const UNCOPIED =
-  'the thread command sits beside none of the framework code this server runs, because no package ships it, and the ' +
-  'folder this server was started from keeps no compiled copy of it. Run `' + COPIES + '` in that folder from a server ' +
-  'that runs the framework itself, and the next command here starts that copy.'
-
-const UNWRITTEN =
-  'the compiled copy of the thread command this folder keeps could not be written out beside its installed packages, so ' +
-  'no command could start: '
-
-const INSTALLED = 'node_modules'
-
-const CACHED = join(INSTALLED, '.cache', THING)
-
-function startable(): Started | string {
-  if (existsSync(CLI.at(-1) ?? '')) return { words: CLI, own: OWN, reads: [OWN] }
-  let root: string
-  try {
-    root = findTree().at
-  } catch {
-    return UNCOPIED
-  }
-  const copied = resolve(root, COPY_AT)
-  if (!existsSync(copied)) return UNCOPIED
-  const said = readFileSync(copied, 'utf8')
-  const own = join(root, CACHED, createHash('sha256').update(said).digest('hex').slice(0, 16))
-  const entry = join(own, 'cli', BESIDE('cli'))
-  if (!existsSync(entry)) {
-    const part = own + '-' + String(pid)
-    try {
-      for (const [at, text] of Object.entries(JSON.parse(said) as Readonly<Record<string, string>>)) writeFileSync(join(part, at), text, 'utf8')
-      renameSync(part, own)
-    } catch (thrown) {
-      rmSync(part, { recursive: true, force: true })
-      if (!existsSync(entry)) return UNWRITTEN + (thrown instanceof Error ? thrown.message : String(thrown))
-    }
-  }
-  return { words: [entry], own, reads: [join(root, INSTALLED)] }
-}
-
-const GUARDS = ['--permission', '--experimental-permission']
-
-const HUSHES = '--disable-warning'
-
-const swapped = (path: string): string =>
-  [...path].map((one) => (one === one.toUpperCase() ? one.toLowerCase() : one.toUpperCase())).join('')
-
-let unguarded = false
-
-function guarded(reads: readonly string[]): string {
-  const before = env.NODE_OPTIONS ?? ''
-  const on = GUARDS.find((one) => allowedNodeEnvironmentFlags.has(one))
-  if (on === undefined) {
-    if (!unguarded) {
-      stderr.write(
-        'thread: this node has no permission model, so a thread command started for a folder runs unguarded: nothing ' +
-          'here stops it reading that folder straight off this disk, and on one machine that would go unnoticed.\n',
-      )
-      unguarded = true
-    }
-    return before
-  }
-  const kept = [...new Set([tmpdir(), realpathSync(tmpdir())])]
-  const allowed = (flag: string, paths: readonly string[]): readonly string[] => paths.map((one) => flag + '="' + one + '"')
-  const quiet = allowedNodeEnvironmentFlags.has(HUSHES) ? [HUSHES + '=SecurityWarning'] : []
-  return [before, on, ...allowed('--allow-fs-read', [...reads.flatMap((one) => [one, swapped(one)]), ...kept]), ...allowed('--allow-fs-write', kept), '--allow-child-process', '--allow-worker', ...quiet]
-    .filter((one) => one !== '')
-    .join(' ')
-}
-
-const SERVED = 'thread-serve'
-
-const TICK = 2
-
-const MARGIN = 5_000
-
-const SAYING = '-saying'
-
-const ORDER = '-order'
-
-const ANSWER = '-answer'
-
-interface Serving {
-  readonly of: string
-  readonly dir: string
-  readonly root: string
-  out: string
-  err: string
-  why: string
-  pending: string
-  waiting: ((held: Ran) => void)[]
-  parked: Ran[]
-  replaying: Recorded[]
-  handed: number
-  readonly known: Map<string, Answer>
-  asking?: Order
-  last?: Ran
-  stop?: () => void
-  watch?: ReturnType<typeof setInterval>
-}
-
-const serving = new Map<string, Serving>()
-
-const still = (one: Serving, asks: readonly Order[]): Ran => ({ there: true, ok: false, code: -1, out: '', err: '', killed: null, why: '', of: one.of, asks })
-
-const nowhere = (why: string): Ran => ({ there: false, ok: false, code: 1, out: '', err: '', killed: null, why })
-
-const lost = (of: string): Ran => ({ there: true, ok: false, code: -1, out: '', err: '', killed: null, why: '', of, lost: of })
-
-const told = (one: Order): string => JSON.stringify([one.order, one.at, one.said ?? null, one.mode ?? null, one.words ?? null])
-
-const READS: ReadonlySet<string> = new Set(Object.entries(ORDERS).filter(([order, answer]) => order === answer).map(([order]) => order))
-
-function kept(one: Serving, asked: Order, held: Answer): void {
-  if (READS.has(asked.order) && held.answered !== 'refused') one.known.set(told(asked), held)
-}
-
-const plainly = (one: Order): string => one.order + ' ' + (one.at === '' ? '.' : one.at)
-
-const outside = (root: string, at: string): boolean => {
-  const step = relative(root, at)
-  return step.startsWith('..') ? true : isAbsolute(step)
-}
-
-function hand(one: Serving, held: Ran): void {
-  const settle = one.waiting.shift()
-  if (settle === undefined) one.parked.push(held)
-  else settle(held)
-}
-
-function reply(dir: string, name: string, held: Answer): void {
-  writeFileSync(join(dir, name + SAYING), JSON.stringify(held), 'utf8')
-  renameSync(join(dir, name + SAYING), join(dir, name + ANSWER))
-}
-
-function watching(one: Serving): void {
-  one.watch = setInterval(() => {
-    let names: readonly string[] = []
-    try {
-      names = readdirSync(one.dir)
-    } catch {
-      return
-    }
-    for (const name of names) {
-      if (!name.endsWith(ORDER)) continue
-      const file = join(one.dir, name)
-      let said = ''
-      try {
-        said = readFileSync(file, 'utf8')
-      } catch {
-        continue
-      }
-      rmSync(file, { force: true })
-      const order = JSON.parse(said) as Order
-      const short = name.slice(0, name.length - ORDER.length)
-      if (outside(one.root, order.at)) {
-        reply(one.dir, short, {
-          answered: 'refused',
-          because: order.at + ' is outside the folder this command was pointed at, and nothing outside it is ever asked of the machine answering.',
-        })
-        continue
-      }
-      const asked: Order = { ...order, at: relative(one.root, order.at) }
-      const known = one.known.get(told(asked))
-      if (known !== undefined) {
-        reply(one.dir, short, known)
-        continue
-      }
-      if (!READS.has(asked.order)) one.known.clear()
-      const due = one.replaying.shift()
-      if (due !== undefined) {
-        if (told(due.order) === told(asked)) {
-          reply(one.dir, short, due.answered)
-          kept(one, asked, due.answered)
-          continue
-        }
-        one.replaying = []
-        one.err +=
-          'thread: this command was carried on here by running it again and handing it the answers it was given before, ' +
-          'and this time it asked for ' + plainly(asked) + ' where before it asked for ' + plainly(due.order) + '. A command ' +
-          'that does not ask the same things twice cannot be carried on from its answers, so it was stopped. Run it again.\n'
-        one.stop?.()
-        continue
-      }
-      one.pending = short
-      one.asking = asked
-      hand(one, still(one, [asked]))
-    }
-  }, TICK)
-}
-
-function next(one: Serving, within?: number): Promise<Ran> {
-  const held = one.parked.shift()
-  if (held !== undefined) return Promise.resolve(held)
-  return new Promise((settle) => {
-    const done = { is: false }
-    const mine = (ran: Ran): void => {
-      if (done.is) return
-      done.is = true
-      settle(ran)
-    }
-    one.waiting.push(mine)
-    if (within === undefined) return
-    setTimeout(() => {
-      if (done.is) return
-      done.is = true
-      one.waiting = one.waiting.filter((each) => each !== mine)
-      settle(still(one, []))
-    }, Math.max(1_000, within - MARGIN))
-  })
-}
-
-function begun(from: Started, word: string, args: readonly string[], root: string, hears?: string, called?: string, recording: readonly Recorded[] = []): Serving {
-  const of = called ?? randomBytes(6).toString('hex')
-  const dir = join(tmpdir(), SERVED, randomBytes(6).toString('hex'))
-  writeFileSync(join(dir, 'channel'), '', 'utf8')
-  const one: Serving = { of, dir, root, out: '', err: '', why: '', pending: '', waiting: [], parked: [], replaying: [...recording], handed: recording.length, known: new Map() }
-  const child = spawn(execPath, [...from.words, word, ...args], {
-    cwd: from.own,
-    shell: false,
-    env: { ...env, [CHANNEL]: dir, [FOLDER]: root, [SIGNING]: signing(), NODE_OPTIONS: guarded(from.reads) },
-  })
-  one.stop = () => child.kill()
-  child.stdout.on('data', (chunk: Buffer) => (one.out += chunk.toString()))
-  child.stderr.on('data', (chunk: Buffer) => (one.err += chunk.toString()))
-  child.on('error', (thrown) => (one.why = thrown.message))
-  child.on('close', (code, killed) => {
-    if (one.watch !== undefined) clearInterval(one.watch)
-    serving.delete(of)
-    rmSync(dir, { recursive: true, force: true })
-    hand(one, { there: one.why === '', ok: one.why === '' && code === 0, code: code ?? 1, out: one.out, err: one.err, killed, why: one.why })
-  })
-  child.stdin.end(hears ?? '')
-  watching(one)
-  serving.set(of, one)
-  return one
-}
-
-const UNPLACED = ' against, so it did not start. A command on this server runs against the folder the person gave and nowhere else.'
-
-function counted(one: Serving, held: Ran): Ran {
-  const asks = held.asks ?? []
-  if (asks.length === 0) return held
-  one.handed += asks.length
-  one.last = held
-  return held
-}
-
-async function served(word: string, args: readonly string[], within?: number, how?: How): Promise<Ran> {
-  const of = how?.of
-  if (of !== undefined) {
-    const one = serving.get(of)
-    if (one === undefined) {
-      const recording = how?.recording
-      if (recording === undefined) return lost(of)
-      const root = how?.at ?? ''
-      if (root === '') return nowhere('nothing said which folder to run thread ' + word + UNPLACED)
-      const from = startable()
-      if (typeof from === 'string') return nowhere(from)
-      const again = begun(from, word, args, root, how?.hears, of, recording)
-      return counted(again, await next(again, within))
-    }
-    const answering = how?.answering
-    if (answering !== undefined && answering < one.handed && one.last !== undefined) return one.last
-    const given = (how?.answered ?? [])[0]
-    if (one.pending !== '' && given !== undefined) {
-      reply(one.dir, one.pending, given)
-      if (one.asking !== undefined) kept(one, one.asking, given)
-      one.pending = ''
-    }
-    return counted(one, await next(one, within))
-  }
-  const root = how?.at ?? ''
-  if (root === '') return nowhere('nothing said which folder to run thread ' + word + UNPLACED)
-  const from = startable()
-  if (typeof from === 'string') return nowhere(from)
-  const fresh = begun(from, word, args, root, how?.hears)
-  return counted(fresh, await next(fresh, within))
-}
-
-export function running(name: string, subcommands: Readonly<Record<string, string>>, at: string): Running {
-  const out: Record<
-    string,
-    (args: readonly string[], shows?: Starting['shows'], within?: number, how?: How) => Promise<Ran>
-  > = {}
-  for (const [key, word] of Object.entries(subcommands)) {
-    out[key] =
-      name === THING
-        ? async (args, shows, within, how) => served(word, args, within, how)
-        : async (args, shows, within, how) => {
-            const where = how?.at ?? at
-            const program = programFor(name, where)
-            if ((shows ?? false) !== false) return handed(where, program, [word, ...args], shows ?? false, within, how?.hears)
-            return await started(program, [word, ...args], { at: where, ...(within === undefined ? {} : { within }), ...(how?.hears === undefined ? {} : { hears: how.hears }) })
-          }
-  }
-  return out
-}
-
-interface Sheet {
-  readonly TARGETS?: readonly Target[]
-  readonly CALLS?: readonly Call[]
-}
-
-function sheet(at: string): Sheet {
-  const path = inTree(findTree(at), 'targets.ts')
-  return existsSync(path) ? (valuesIn(readFileSync(path, 'utf8')) as Sheet) : {}
-}
-
-export interface Expansion {
-  readonly program: string
-  readonly target: Target
-  readonly calls: readonly Call[]
-}
-
-export function expansions(at: string): readonly Expansion[] {
-  const held = sheet(at)
-  return (held.TARGETS ?? [])
-    .filter((one) => one.id.startsWith(REACH.cli))
-    .map((one) => ({ program: one.id.slice(REACH.cli.length), target: one, calls: (held.CALLS ?? []).filter((each) => each.of === one.id) }))
-}
-
-export function calls(target: string, at: string): Running {
-  const named: Record<string, string> = {}
-  for (const one of sheet(at).CALLS ?? []) if (one.of === target) named[one.id.replace(CALL_PREFIX, '')] = one.path
-  return running(target.replace(REACH.cli, ''), named, at)
-}
-
-export { LOCKFILES }
-
-export const manager = (into: string): string => managerOf(into, existsSync)
-
-const ADDS: Readonly<Record<string, string>> = { pnpm: 'add', yarn: 'add', bun: 'add', npm: 'install' }
-
-export function adding(into: string): readonly [string, string] {
-  const tool = manager(into)
-  const verb = ADDS[tool]
-  if (verb === undefined) {
-    throw new Error(
-      tool + ' is what the lockfile in ' + into + ' picks, and nothing here knows the word it adds a package with.',
-    )
-  }
-  return [tool, verb]
-}
-
-export function needing(into: string, needs: Readonly<Record<string, string>>): readonly string[] {
-  const manifest = join(into, 'package.json')
-  const was = readFileSync(manifest, 'utf8')
-  const parsed = JSON.parse(was) as Record<string, unknown> & {
-    readonly dependencies?: Readonly<Record<string, string>>
-    readonly devDependencies?: Readonly<Record<string, string>>
-  }
-  const named = { ...parsed.devDependencies, ...parsed.dependencies }
-  const added = Object.keys(needs).filter((one) => named[one] === undefined).sort()
-  if (added.length === 0) return []
-  const dependencies: Record<string, string> = { ...parsed.dependencies }
-  for (const one of added) dependencies[one] = needs[one] ?? 'latest'
-  writeFileSync(manifest, `${JSON.stringify({ ...parsed, dependencies }, null, 2)}\n`, 'utf8')
-  try {
-    installing(into)
-  } catch (thrown) {
-    writeFileSync(manifest, was, 'utf8')
-    throw new Error(
-      `${added.join(', ')} could not be fetched — ${thrown instanceof Error ? thrown.message : String(thrown)} ` +
-        'package.json is as it was, so nothing here names a package that is not on disk.',
-    )
-  }
-  return added
-}
-
-export function installing(at: string): string {
-  if (attached()) return here().fetch(at)
-  const tool = manager(at)
-  const ran = starts(programFor(PACKAGER, at), ['install'], { at })
-  const said = (ran.out + ran.err).trim()
-  if (!ran.there) {
-    throw new Error(
-      tool + ' is what the lockfile in ' + at + ' picks, and it is not on this machine, so nothing here can fetch ' +
-        'what that tree depends on until that changes.',
-    )
-  }
-  if (!ran.ok) {
-    throw new Error(
-      tool + ' could not install what ' + at + ' depends on. It said: ' +
-        (said === '' ? 'nothing, and exited ' + String(ran.code) : said),
-    )
-  }
-  return said
-}