spexcode 0.6.1 → 0.6.5

package/spec-cli/src/process-identity.ts

@@ -1,207 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { execFileSync } from 'node:child_process'
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { platform } from 'node:os'
-import { dirname, join } from 'node:path'
-
-export type ProcessIdentity = { pid: number; startToken: string }
-
-export type ProcessAdapter = Readonly<{
-  platform: NodeJS.Platform
-  startToken(pid: number): string | null
-  processGroupId(pid: number): number | null
-  linuxSessionId(pid: number): number | null
-}>
-
-export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
-  receiptVersion: 4
-  processGroupId: number
-  linuxSessionId?: number
-}>
-
-export type DetachedRuntimeVerification =
-  | { ok: true; identity: VerifiedDetachedRuntime }
-  | { ok: false; reason: string }
-
-type DetachedLaunchReceiptV4 = {
-  version: 4
-  kind: 'spexcode-detached-runtime'
-  pid: number
-  startToken: string
-  processGroupId: number
-  linuxSessionId?: number
-}
-
-export function parseProcStat(text: string): { ppid: number; processGroupId: number; sessionId: number; ticks: number; startToken: string; rssPages: number } {
-  const end = text.lastIndexOf(')')
-  if (end < 0) throw new Error('malformed proc stat')
-  const fields = text.slice(end + 2).trim().split(/\s+/)
-  if (fields.length < 22) throw new Error('short proc stat')
-  return {
-    ppid: Number(fields[1]),
-    processGroupId: Number(fields[2]),
-    sessionId: Number(fields[3]),
-    ticks: Number(fields[11]) + Number(fields[12]),
-    startToken: fields[19],
-    rssPages: Number(fields[21]),
-  }
-}
-
-export function processStartToken(pid: number, procRoot = '/proc'): string | null {
-  if (platform() === 'linux' || procRoot !== '/proc') {
-    try { return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken }
-    catch { return null }
-  }
-  try {
-    const started = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8' }).trim()
-    return started || null
-  } catch { return null }
-}
-
-const procField = (pid: number, field: 'processGroupId' | 'sessionId'): number | null => {
-  try {
-    const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'))
-    return stat[field]
-  } catch { return null }
-}
-
-const psProcessGroupId = (pid: number): number | null => {
-  try {
-    const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
-    return Number.isInteger(value) && value > 0 ? value : null
-  } catch { return null }
-}
-
-export const hostProcessAdapter: ProcessAdapter = Object.freeze({
-  platform: platform(),
-  startToken: (pid) => processStartToken(pid),
-  processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
-  linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
-})
-
-const exactKeys = (value: Record<string, unknown>, expected: string[]) => {
-  const actual = Object.keys(value).sort()
-  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
-}
-
-const parseDetachedLaunchReceipt = (text: string, hostPlatform: NodeJS.Platform): DetachedLaunchReceiptV4 | null => {
-  let value: unknown
-  try { value = JSON.parse(text) } catch { return null }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
-  const receipt = value as Record<string, unknown>
-  const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort()
-  if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
-    !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
-    !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
-    (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0))) return null
-  return receipt as DetachedLaunchReceiptV4
-}
-
-const observeDetachedRuntime = (pid: number, adapter: ProcessAdapter): DetachedRuntimeVerification => {
-  if (adapter.platform === 'win32') return { ok: false, reason: 'detached runtime identity is unsupported on win32' }
-  const startBefore = adapter.startToken(pid)
-  if (!startBefore) return { ok: false, reason: `PID ${pid} has no readable process-start identity` }
-  const processGroupId = adapter.processGroupId(pid)
-  if (processGroupId !== pid) return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` }
-  let linuxSessionId: number | undefined
-  if (adapter.platform === 'linux') {
-    const sessionId = adapter.linuxSessionId(pid)
-    if (sessionId !== pid) return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` }
-    linuxSessionId = sessionId
-  }
-  const startAfter = adapter.startToken(pid)
-  if (!startAfter || startAfter !== startBefore)
-    return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` }
-  return {
-    ok: true,
-    identity: Object.freeze({
-      pid,
-      startToken: startAfter,
-      receiptVersion: 4,
-      processGroupId,
-      ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
-    }),
-  }
-}
-
-export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): DetachedRuntimeVerification {
-  let text: string
-  try { text = readFileSync(receiptFile, 'utf8') }
-  catch { return { ok: false, reason: 'detached launch receipt is missing or unreadable' } }
-  const receipt = parseDetachedLaunchReceipt(text, adapter.platform)
-  if (!receipt) return { ok: false, reason: 'detached launch receipt has the wrong version or shape' }
-  if (receipt.pid !== pid) return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` }
-  if (receipt.processGroupId !== pid)
-    return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` }
-  if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
-    return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` }
-  const live = observeDetachedRuntime(pid, adapter)
-  if (!live.ok) return live
-  if (live.identity.startToken !== receipt.startToken)
-    return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` }
-  return live
-}
-
-// The inverse question of verifyDetachedRuntime: not "is the recorded process running right now" but "is it
-// provably GONE". The two are not complements — a missing receipt, an unreadable identity, or a PID we never
-// recorded answers neither, and a caller that treats "unproven" as "dead" would retire a live runtime it can
-// simply no longer address. Only a recorded start identity that the live PID no longer matches (including a
-// PID that is not running at all) is proof of death.
-export function detachedRuntimeIsGone(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): boolean {
-  let receipt: DetachedLaunchReceiptV4 | null
-  try { receipt = parseDetachedLaunchReceipt(readFileSync(receiptFile, 'utf8'), adapter.platform) }
-  catch { return false }
-  if (!receipt || receipt.pid !== pid) return false
-  return adapter.startToken(pid) !== receipt.startToken
-}
-
-// A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
-// call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
-export function migrateLegacyDetachedRuntimeReceipt(
-  pid: number,
-  legacyScopeFile: string,
-  receiptFile: string,
-  adapter: ProcessAdapter = hostProcessAdapter,
-): boolean {
-  if (adapter.platform !== 'linux' || verifyDetachedRuntime(pid, receiptFile, adapter).ok) return false
-  let fields: string[]
-  try { fields = readFileSync(legacyScopeFile, 'utf8').trim().split(/\s+/) }
-  catch { return false }
-  const observed = observeDetachedRuntime(pid, adapter)
-  if (!observed.ok || observed.identity.linuxSessionId === undefined) return false
-  const expected = ['detached-v3', String(pid), observed.identity.startToken, String(observed.identity.processGroupId), String(observed.identity.linuxSessionId)]
-  if (fields.length !== expected.length || fields.some((field, index) => field !== expected[index])) return false
-  try { writeDetachedRuntimeReceipt(pid, receiptFile, adapter); return true }
-  catch { return false }
-}
-
-export function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): VerifiedDetachedRuntime {
-  const observed = observeDetachedRuntime(pid, adapter)
-  if (!observed.ok) throw new Error(`cannot prove detached shared runtime: ${observed.reason}`)
-  const receipt: DetachedLaunchReceiptV4 = {
-    version: 4,
-    kind: 'spexcode-detached-runtime',
-    pid,
-    startToken: observed.identity.startToken,
-    processGroupId: observed.identity.processGroupId,
-    ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
-  }
-  mkdirSync(dirname(receiptFile), { recursive: true })
-  const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`
-  let published = false
-  try {
-    writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 })
-    renameSync(tmp, receiptFile)
-    published = true
-    const verified = verifyDetachedRuntime(pid, receiptFile, adapter)
-    if (!verified.ok) throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`)
-    return verified.identity
-  } catch (error) {
-    rmSync(tmp, { force: true })
-    if (published) rmSync(receiptFile, { force: true })
-    throw error
-  }
-}
-
-export const detachedRuntimeGenerationToken = (identity: VerifiedDetachedRuntime) =>
-  `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`

package/spec-cli/src/project-identity.ts

@@ -1,73 +0,0 @@
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-import { spexcodeHome } from './layout.js'
-import {
-  resolvedIdentityIcon, DEFAULT_GATEWAY_ICON, DEFAULT_PROJECT_ICON, requireIdentityChoice,
-} from './identity-presets.js'
-
-export type ResolvedIdentity = { title: string; icon: string }
-export type GatewayIdentitySource = { identity: ResolvedIdentity; revision: string }
-
-const revisionOf = (raw: string | null): string =>
-  createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex')
-
-function readObject(file: string): { value: Record<string, any>; raw: string | null } {
-  if (!existsSync(file)) return { value: {}, raw: null }
-  const raw = readFileSync(file, 'utf8')
-  let value: unknown
-  try { value = JSON.parse(raw) }
-  catch (e) { throw new Error(`malformed ${file}: ${(e as Error).message}`) }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${file} must contain one top-level JSON object`)
-  return { value: value as Record<string, any>, raw }
-}
-
-export function resolveProjectIdentity(configRoot: string, canonicalRoot = configRoot): ResolvedIdentity {
-  const { value } = readObject(join(configRoot, 'spexcode.json'))
-  const dashboard = value.dashboard && typeof value.dashboard === 'object' && !Array.isArray(value.dashboard)
-    ? value.dashboard as Record<string, unknown>
-    : {}
-  const configuredTitle = typeof dashboard.title === 'string' ? dashboard.title.trim() : ''
-  return {
-    title: configuredTitle || basename(canonicalRoot),
-    icon: resolvedIdentityIcon(dashboard.icon, DEFAULT_PROJECT_ICON),
-  }
-}
-
-export const hostConfigPath = (): string => join(spexcodeHome(), 'config.json')
-
-export function readGatewayIdentity(): GatewayIdentitySource {
-  const { value, raw } = readObject(hostConfigPath())
-  const gateway = value.gateway && typeof value.gateway === 'object' && !Array.isArray(value.gateway)
-    ? value.gateway as Record<string, unknown>
-    : {}
-  return {
-    identity: { title: 'Projects', icon: resolvedIdentityIcon(gateway.icon, DEFAULT_GATEWAY_ICON) },
-    revision: revisionOf(raw),
-  }
-}
-
-export function writeGatewayIcon(icon: unknown, revision: string): GatewayIdentitySource {
-  const canonical = requireIdentityChoice(icon)
-  const file = hostConfigPath()
-  const current = readObject(file)
-  if (revision !== revisionOf(current.raw)) {
-    const error = new Error('host config changed on disk — reload before saving') as Error & { status?: number }
-    error.status = 409
-    throw error
-  }
-  const gateway = current.value.gateway && typeof current.value.gateway === 'object' && !Array.isArray(current.value.gateway)
-    ? current.value.gateway as Record<string, unknown>
-    : {}
-  const next = { ...current.value, gateway: { ...gateway, icon: canonical } }
-  const raw = `${JSON.stringify(next, null, 2)}\n`
-  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
-  const tmp = `${file}.${process.pid}.tmp`
-  try {
-    writeFileSync(tmp, raw, { mode: 0o600 })
-    renameSync(tmp, file)
-  } finally {
-    try { rmSync(tmp) } catch { /* rename consumed it / write never created it */ }
-  }
-  return { identity: { title: 'Projects', icon: canonical }, revision: revisionOf(raw) }
-}

package/spec-cli/src/project-store.ts

@@ -1,17 +0,0 @@
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-// One pure identity seam for every project-scoped runtime consumer. Git discovery stays with callers;
-// once they have the shared common dir, sessions, materialize, history indexes, backends, and uninstall
-// all resolve the same top-level store.
-export function spexcodeHome(): string {
-  return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
-}
-
-export function encodeProject(root: string): string {
-  return root.replace(/[/.]/g, '-')
-}
-
-export function projectRuntimeRoot(commonDir: string): string {
-  return join(spexcodeHome(), 'projects', encodeProject(dirname(commonDir)))
-}