@prestack/thread 0.1.3 → 0.1.5

package/dist/integrations/cli.ts

@@ -0,0 +1,543 @@
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams, type SpawnSyncReturns } from 'node:child_process'
+import { 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, 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 { 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)), '..', '..')
+
+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(): 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', [OWN, swapped(OWN), ...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
+  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 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 due = one.replaying.shift()
+      if (due !== undefined) {
+        if (told(due.order) === told(asked)) {
+          reply(one.dir, short, 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
+      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(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 }
+  const child = spawn(execPath, [...CLI, word, ...args], {
+    cwd: OWN,
+    shell: false,
+    env: { ...env, [CHANNEL]: dir, [FOLDER]: root, [SIGNING]: signing(), NODE_OPTIONS: guarded() },
+  })
+  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 again = begun(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)
+      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 fresh = begun(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
+}

package/dist/{core/files.d.ts → integrations/disk.d.ts}

@@ -1,29 +1,21 @@
 import * as disk from 'node:fs';
-export type Kind = 'file' | 'folder' | 'other' | 'none';
-export interface Listed {
-    readonly name: string;
-    readonly kind: Exclude<Kind, 'none'>;
-}
-export interface Measured {
-    readonly size: number;
-    readonly modified: number;
-}
-export interface Answering {
-    readonly kind: (at: string) => Kind;
-    readonly read: (at: string) => string;
-    readonly write: (at: string, said: string) => void;
-    readonly list: (at: string) => readonly Listed[];
-    readonly stat: (at: string) => Measured;
-    readonly remove: (at: string) => void;
-    readonly real: (at: string) => string;
-    readonly fetch: (at: string) => string;
-}
-export declare function answeredBy(one: Answering | undefined): void;
+import { type Attached, type Kind, type Measured } from '../integrations/target.ts';
+export type { Answering, Kind, Listed, Measured, Ran } from '../integrations/target.ts';
+export declare const CHANNEL = "THREAD_CHANNEL";
+export declare const FOLDER = "THREAD_FOLDER";
+export declare function answeredBy(one?: Attached): void;
+export declare function across(at: string): boolean;
+export declare function beyond(at: string): boolean;
 export declare function attached(): boolean;
+export declare function here(): Attached;
 export declare function kind(at: string): Kind;
 export declare function existsSync(at: disk.PathLike): boolean;
 export declare function readFileSync(at: disk.PathOrFileDescriptor, how?: BufferEncoding): string;
-export declare function writeFileSync(at: disk.PathOrFileDescriptor, said: string, how?: BufferEncoding): void;
+export declare function writeFileSync(at: disk.PathOrFileDescriptor, said: string, how?: BufferEncoding | {
+    readonly encoding?: BufferEncoding;
+    readonly mode?: number;
+}): void;
+export declare function createFileSync(at: string, said: string): boolean;
 export interface Named {
     readonly name: string;
     readonly isFile: () => boolean;
@@ -41,9 +33,9 @@ export declare function statSync(at: disk.PathLike, how: {
     readonly throwIfNoEntry: false;
 }): Held | undefined;
 export declare function rmSync(at: disk.PathLike, how?: disk.RmOptions): void;
+export declare function rmdirSync(at: disk.PathLike): void;
 export declare function renameSync(from: disk.PathLike, to: disk.PathLike): void;
 export declare function appendFileSync(at: disk.PathOrFileDescriptor, said: string): void;
 export declare function realpathSync(at: disk.PathLike): string;
-export declare function manager(into: string): readonly string[];
-export declare function installing(at: string): string;
-export declare function fetching(at: string): string;
+export declare const HERE: Attached;
+export declare function standing(root: string, given: ReadonlyMap<string, string>): Attached;