@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/readiness-protocols/evidence.mjs

@@ -0,0 +1,282 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { buildGraph } from '../graph/graph.mjs'
+import {
+  loadExtensionPacks,
+  createProtocolRegistry,
+} from '../extension-packs/loader.mjs'
+import { readRegularTextNoFollow } from '../project/private-state.mjs'
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs'
+import { inspectPackLifecycle } from '../extension-packs/lifecycle.mjs'
+import { readLocalOverlay } from '../project/config.mjs'
+import { readBoundedSource } from './source-read.mjs'
+export { readBoundedSource } from './source-read.mjs'
+import { validReviewArtifact } from '../collaboration/review-contracts.mjs'
+import { buildReadinessRun, answerForField } from './runtime.mjs'
+
+export const hashEvidence = (value) =>
+  `sha256:${crypto
+    .createHash('sha256')
+    .update(canonicalize(value))
+    .digest('hex')}`
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url))
+function evaluatorInventory() {
+  const files = ['package.json']
+  function visit(relative) {
+    for (const name of fs
+      .readdirSync(path.join(packageRoot, relative))
+      .sort()) {
+      const next = path.posix.join(relative, name),
+        stat = fs.lstatSync(path.join(packageRoot, next))
+      if (stat.isSymbolicLink()) throw new Error('redirected evaluator input')
+      if (stat.isDirectory()) visit(next)
+      else if (stat.isFile() && /\.(mjs|json)$/.test(name)) files.push(next)
+    }
+  }
+  visit('src')
+  visit('contracts')
+  return files
+    .sort()
+    .map((file) => ({
+      file,
+      digest: hashBytes(readRegularTextNoFollow(path.join(packageRoot, file))),
+    }))
+}
+const evaluator = hashEvidence(evaluatorInventory())
+
+function currentInputs(project, protocolId, answers) {
+  if (
+    project.configPath &&
+    hashEvidence(JSON.parse(readRegularTextNoFollow(project.configPath))) !==
+      hashEvidence(project.config)
+  )
+    throw new Error('project config changed; resolve the project again')
+  if (hashEvidence(evaluatorInventory()) !== evaluator)
+    throw new Error('evaluator changed; restart before review')
+  if (
+    project.localOverlay &&
+    hashEvidence(readLocalOverlay({ configDir: project.configDir }).overlay) !==
+      hashEvidence(project.localOverlay.overlay)
+  )
+    throw new Error('local overlay changed; resolve again')
+  const loaded = loadExtensionPacks(project)
+  const packs = loaded.packs ?? loaded
+  const lifecycle = inspectPackLifecycle(project, packs)
+  if (!lifecycle.ok) throw new Error(lifecycle.errors.join('; '))
+  const registry = createProtocolRegistry({ packs })
+  const protocol = registry.protocolById(protocolId)
+  if (!protocol) throw new Error('protocol unavailable for evidence binding')
+  const graph = buildGraph(project)
+  if (graph.errors.length)
+    throw new Error('source graph is invalid; evidence capture refused')
+  if (graph.nodes.length > 256)
+    throw new Error('review evidence exceeds bounded source count')
+  const sources = [],
+    excerpts = new Map()
+  for (const node of graph.nodes) {
+    const repo = project.repos.find(
+      (entry) => entry.name === node.repo && !entry.external,
+    )
+    if (!repo?.path) throw new Error('source repository unavailable')
+    const source = readBoundedSource(repo.path, node.path)
+    const metadata = !/\.md$/i.test(node.path)
+      ? readBoundedSource(repo.path, `${node.path}.kg.json`).digest
+      : null
+    excerpts.set(node.id, source.text.slice(0, 2000))
+    sources.push({
+      id: node.id,
+      repo: node.repo,
+      path: node.path,
+      audience: node.audience,
+      digest: source.digest,
+      metadata,
+    })
+  }
+  sources.sort((a, b) =>
+    `${a.repo}/${a.path}`.localeCompare(`${b.repo}/${b.path}`, 'en'),
+  )
+  const claimEvidence = protocol.claimMappings.map((mapping) => {
+    const raw = answerForField(answers, mapping.evidence)
+    const references = (Array.isArray(raw) ? raw.flat(Infinity) : [raw])
+      .filter((value) => typeof value === 'string' && value.trim())
+      .map((value) => value.trim())
+    const resolved = [],
+      unresolved = []
+    for (const reference of references) {
+      const source = sources.find((item) => item.id === reference)
+      if (source)
+        resolved.push({
+          id: source.id,
+          repo: source.repo,
+          path: source.path,
+          digest: source.digest,
+          excerpt: excerpts.get(source.id),
+        })
+      else unresolved.push(reference)
+    }
+    return {
+      mappingId: mapping.id,
+      sourceFields: mapping.sourceFields,
+      answers: Object.fromEntries(
+        mapping.sourceFields.map((field) => [
+          field,
+          answerForField(answers, field) ?? null,
+        ]),
+      ),
+      evidenceField: mapping.evidence,
+      references,
+      resolved,
+      unresolved,
+      status: !references.length
+        ? 'missing'
+        : unresolved.length
+        ? 'unresolved'
+        : 'linked-source',
+    }
+  })
+  const readPolicy = (file) =>
+    fs.existsSync(file) ? hashBytes(readRegularTextNoFollow(file)) : null
+  return {
+    schema: 'atelier-review-evidence@v1',
+    protocolId,
+    protocol,
+    protocolDigest: hashEvidence(protocol),
+    answers,
+    answersDigest: hashEvidence(answers),
+    configDigest: hashEvidence(project.config),
+    lifecycleDigest: hashEvidence(lifecycle),
+    policyDigest: hashEvidence({
+      access: readPolicy(project.repoAccessPath),
+      boundary: readPolicy(project.boundaryPolicyPath),
+    }),
+    packs: packs
+      .map(({ id, version, digest }) => ({ id, version, digest }))
+      .sort((a, b) => a.id.localeCompare(b.id, 'en')),
+    evaluator: { id: 'answer-completeness/v1', digest: evaluator },
+    sources,
+    claimEvidence,
+    limitations: [
+      'Answers are operator assertions; source presence does not substantiate each claim.',
+      'No calibrated evidence confidence or runtime acceptance is established.',
+    ],
+  }
+}
+
+export function captureReviewEvidence(project, protocolId, answers) {
+  const first = currentInputs(project, protocolId, answers)
+  const second = currentInputs(project, protocolId, answers)
+  const digest = hashEvidence(first)
+  if (digest !== hashEvidence(second))
+    throw new Error('review inputs changed during capture')
+  const snapshot = { ...first, digest }
+  if (!validReviewArtifact('evidence', snapshot))
+    throw new Error('evidence contract invalid or exceeds bounds')
+  return snapshot
+}
+
+export function evidenceLedger(project) {
+  return createCollaborationEventLedger({
+    workspaceRoot: project.configDir,
+    ledgerPath: path.join(
+      project.configDir,
+      '.atelier-local/review/evidence.ndjson',
+    ),
+  })
+}
+
+export function recordReviewEvidence(project, run) {
+  const snapshot = captureReviewEvidence(project, run.protocolId, run.answers)
+  if (
+    hashEvidence(
+      buildReadinessRun({
+        project,
+        protocol: snapshot.protocol,
+        answers: run.answers,
+        createdAt: run.createdAt,
+      }),
+    ) !== hashEvidence(run)
+  )
+    throw new Error('run no longer matches its current protocol and evaluator')
+  const payload = {
+    schema: 'atelier-bound-run@v1',
+    run,
+    runDigest: hashEvidence(run),
+    snapshot,
+  }
+  if (!validBoundRun(payload)) throw new Error('bound run contract invalid')
+  const ledger = evidenceLedger(project)
+  const existing = ledger.eventsFor(run.runId)
+  if (!existing.ok) throw new Error(existing.error)
+  if (existing.events.length) {
+    if (hashEvidence(existing.events[0].payload) !== hashEvidence(payload))
+      throw new Error('run identity already has different evidence')
+    return existing.events[0].payload
+  }
+  const result = ledger.append({
+    aggregateId: run.runId,
+    expectedVersion: 0,
+    type: 'run-bound',
+    actor: 'local-runtime',
+    payload,
+  })
+  if (!result.ok) throw new Error(result.error)
+  return payload
+}
+
+export function validBoundRun(payload) {
+  if (!validReviewArtifact('bound', payload)) return false
+  const { digest, ...body } = payload.snapshot
+  const { run, snapshot } = payload
+  return (
+    payload.runDigest === hashEvidence(run) &&
+    digest === hashEvidence(body) &&
+    snapshot.protocolDigest === hashEvidence(snapshot.protocol) &&
+    snapshot.answersDigest === hashEvidence(snapshot.answers) &&
+    snapshot.answersDigest === hashEvidence(run.answers) &&
+    snapshot.protocol.id === run.protocolId &&
+    snapshot.protocolId === run.protocolId &&
+    snapshot.claimEvidence.length === run.claims.length &&
+    snapshot.claimEvidence.every(
+      (entry, index) =>
+        entry.mappingId === snapshot.protocol.claimMappings[index]?.id,
+    )
+  )
+}
+
+export function loadBoundRun(project, runId) {
+  const result = evidenceLedger(project).eventsFor(runId)
+  if (!result.ok) return result
+  if (result.events.length !== 1 || result.events[0].type !== 'run-bound')
+    return {
+      ok: false,
+      status: 409,
+      error: 'run lacks immutable review evidence',
+    }
+  const payload = result.events[0].payload
+  const { digest, ...body } = payload.snapshot ?? {}
+  if (
+    !validBoundRun(payload) ||
+    payload.schema !== 'atelier-bound-run@v1' ||
+    payload.run?.runId !== runId ||
+    payload.runDigest !== hashEvidence(payload.run) ||
+    digest !== hashEvidence(body)
+  )
+    return { ok: false, status: 422, error: 'run evidence is invalid' }
+  return { ok: true, status: 200, ...payload }
+}
+
+export function currentRunEligibility(project, bound) {
+  try {
+    return (
+      captureReviewEvidence(project, bound.run.protocolId, bound.run.answers)
+        .digest === bound.snapshot.digest
+    )
+  } catch {
+    return false
+  }
+}

package/src/readiness-protocols/runtime.mjs

@@ -73,7 +73,7 @@ function nestedAnswer(value, parts) {
   return nestedAnswer(value[head], rest)
 }
 
-function answerForField(answers, fieldId) {
+export function answerForField(answers, fieldId) {
   for (const key of pathVariants(fieldId)) {
     if (Object.hasOwn(answers, key)) return answers[key]
   }
@@ -119,9 +119,8 @@ export function claimsForProtocolRun({ protocol, answers, projectName, runId, cr
     provider: 'atelier-readiness',
     status: 'proposed',
     promoted: false,
-    confidence: Object.values(answers).some(answerPresent) ? 0.7 : 0.2,
     evidence: [`readiness-run:${runId}`],
-    notes: [`Proposed ${mapping.id} from ${protocol.title}.`],
+    notes: [`Proposed ${mapping.id} from ${protocol.title}.`, 'Answer presence is not evidence confidence; human judgment is required.'],
     createdAt,
     }
   })
@@ -147,6 +146,7 @@ export function buildReadinessRun({ project, protocol, answers = {}, createdAt =
     claims: claimsForProtocolRun({ protocol, answers: normalizedAnswers, projectName, runId, createdAt }),
     safety: {
       runtimeMutation: false,
+      runtimeImport: false,
       canonicalWrites: false,
       claimOnly: true,
       storage: 'ignored-local',
@@ -367,6 +367,7 @@ export function buildTenantPacket(project, { runs = listProtocolRuns(project), r
     ext: {
       'mnstry.atelier': {
         extensionPacks: packContribution,
+        scoreMeaning: 'Legacy readinessScore measures completed input dimensions; it is not evidence confidence or runtime admission.',
       },
     },
   }

package/src/readiness-protocols/source-read.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+
+export function readBoundedSource(root, relative) {
+  if (
+    typeof relative !== 'string' ||
+    path.isAbsolute(relative) ||
+    relative.split(/[\\/]/).some((part) => part === '..' || part === '.git')
+  )
+    throw new Error('source reference escapes declared boundary')
+  const realRoot = fs.realpathSync(root)
+  const file = path.resolve(realRoot, relative)
+  let cursor = realRoot
+  for (const part of path.relative(realRoot, file).split(path.sep)) {
+    cursor = path.join(cursor, part)
+    if (fs.lstatSync(cursor).isSymbolicLink())
+      throw new Error('redirected source reference refused')
+  }
+  const descriptor = openRegularFileNoFollow(file)
+  try {
+    const before = fs.fstatSync(descriptor)
+    if (before.size > 1024 * 1024)
+      throw new Error('source exceeds review byte bound')
+    const bytes = fs.readFileSync(descriptor)
+    const after = fs.fstatSync(descriptor)
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+      throw new Error('source changed during read')
+    return {
+      digest: hashBytes(bytes),
+      text: new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+    }
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}

package/src/runtime/git-adapter.mjs

@@ -0,0 +1,189 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024
+
+function executableNames(platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return ['git']
+  const extensions = String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+    .split(';')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+  return ['git.exe', ...extensions.map((extension) => `git${extension}`).filter((name) => name !== 'git.exe')]
+}
+
+function isExecutable(file, platform = process.platform) {
+  try {
+    fs.accessSync(file, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK)
+    return fs.statSync(file).isFile()
+  } catch {
+    return false
+  }
+}
+
+function canonicalExecutable(file) {
+  try {
+    return fs.realpathSync.native(file)
+  } catch {
+    return fs.realpathSync(file)
+  }
+}
+
+/**
+ * Resolve one exact Git executable without invoking a shell. The selected path
+ * is carried through every later operation so PATH changes cannot swap engines
+ * underneath a running supervisor.
+ */
+export function resolveGitExecutable({ env = process.env, platform = process.platform } = {}) {
+  const configured = String(env.ATELIER_GIT_PATH || '').trim()
+  if (configured) {
+    if (!path.isAbsolute(configured)) throw new Error('ATELIER_GIT_PATH must be an absolute path')
+    if (!isExecutable(configured, platform)) throw new Error(`configured Git executable is unavailable: ${configured}`)
+    return canonicalExecutable(configured)
+  }
+
+  const searchPath = String(env.PATH || '')
+  const delimiter = platform === 'win32' ? ';' : path.delimiter
+  const names = executableNames(platform, env)
+  for (const directory of searchPath.split(delimiter).filter(Boolean)) {
+    const cleanDir = directory.replace(/^"|"$/g, '')
+    for (const name of names) {
+      const candidate = path.join(cleanDir, name)
+      if (isExecutable(candidate, platform)) return canonicalExecutable(candidate)
+    }
+  }
+  throw new Error('compatible system Git was not found on PATH')
+}
+
+export function sanitizedGitEnvironment(env = process.env, allowPrompt = false) {
+  const next = { ...env }
+  for (const key of Object.keys(next)) {
+    if (key.toUpperCase().startsWith('GIT_')) delete next[key]
+  }
+  if (!allowPrompt) next.GIT_TERMINAL_PROMPT = '0'
+  next.GIT_OPTIONAL_LOCKS = next.GIT_OPTIONAL_LOCKS || '1'
+  next.GIT_NO_REPLACE_OBJECTS = '1'
+  return next
+}
+
+export function redactGitDiagnostic(value) {
+  return String(value || '')
+    .replace(/https?:\/\/[^\s]+/gi, (url) => sanitizeRemoteUrl(url))
+    .replace(/\b((?:password|passwd|token|secret|authorization|proxy-authorization|extraheader)\s*[=:]\s*)[^\s]+/gi, '$1[redacted]')
+    .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 [redacted]')
+}
+
+export class GitCommandError extends Error {
+  constructor(message, result) {
+    super(message)
+    this.name = 'GitCommandError'
+    this.result = result
+  }
+}
+
+export function runGit(gitExecutable, repoRoot, args, {
+  allowFailure = false,
+  allowPrompt = false,
+  env = process.env,
+  input = undefined,
+  timeout = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  if (!path.isAbsolute(gitExecutable)) throw new Error('Git executable must be an absolute path')
+  if (!Array.isArray(args) || args.some((value) => typeof value !== 'string')) {
+    throw new Error('Git arguments must be a string array')
+  }
+  const argv = repoRoot ? ['-C', repoRoot, ...args] : args
+  const child = spawnSync(gitExecutable, argv, {
+    encoding: 'utf8',
+    env: sanitizedGitEnvironment(env, allowPrompt),
+    input,
+    maxBuffer: DEFAULT_MAX_BUFFER,
+    shell: false,
+    timeout,
+    windowsHide: true,
+  })
+  const result = {
+    ok: !child.error && child.status === 0,
+    status: child.status,
+    signal: child.signal ?? null,
+    stdout: child.stdout || '',
+    stderr: redactGitDiagnostic(child.stderr || ''),
+    error: child.error?.message ? redactGitDiagnostic(child.error.message) : null,
+    executable: gitExecutable,
+    args: argv,
+  }
+  if (!result.ok && !allowFailure) {
+    const detail = result.error || result.stderr.trim() || `exit ${String(result.status)}`
+    throw new GitCommandError(`Git ${args[0] || 'command'} failed: ${detail}`, result)
+  }
+  return result
+}
+
+export function gitText(gitExecutable, repoRoot, args, options = {}) {
+  return runGit(gitExecutable, repoRoot, args, options).stdout.trim()
+}
+
+export function parseGitVersion(text) {
+  const match = String(text || '').match(/git version (\d+)\.(\d+)\.(\d+)/i)
+  if (!match) return null
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), text: match[0] }
+}
+
+export function isSupportedGitVersion(version) {
+  return Boolean(version && (version.major > 2 || (version.major === 2 && version.minor >= 40)))
+}
+
+export function inspectGitEngine(gitExecutable, { env = process.env } = {}) {
+  const result = runGit(gitExecutable, null, ['--version'], { env })
+  const version = parseGitVersion(result.stdout)
+  if (!version) throw new Error(`unrecognized Git version output from ${gitExecutable}`)
+  return {
+    executable: gitExecutable,
+    version: `${version.major}.${version.minor}.${version.patch}`,
+    supported: isSupportedGitVersion(version),
+    minimum: '2.40.0',
+  }
+}
+
+export function classifyRemoteAuthentication(url) {
+  const value = String(url || '').trim()
+  if (!value) return 'none'
+  if (/^(?:ssh:\/\/|[^/@\s]+@[^:/\s]+:)/i.test(value)) return 'ssh'
+  if (/^https?:\/\//i.test(value)) return 'https'
+  if (/^(?:file:\/\/|\.{0,2}[\\/]|[a-z]:[\\/]|[\\/])/i.test(value)) return 'local'
+  return 'unknown'
+}
+
+/**
+ * Remote URLs are evidence, not authentication material. Git may carry HTTP
+ * credentials in user-info or query fragments, so local observations retain
+ * only the provider/repository address needed for diagnosis.
+ */
+export function sanitizeRemoteUrl(url) {
+  const value = String(url || '').trim()
+  const scpLike = value.match(/^[^/@\s]+@([^:/\s]+:.+)$/)
+  if (scpLike) return scpLike[1]
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) return value
+  try {
+    const parsed = new URL(value)
+    parsed.username = ''
+    Reflect.set(parsed, 'password', '')
+    parsed.search = ''
+    parsed.hash = ''
+    return parsed.toString()
+  } catch {
+    return value.replace(/^((?:https?|ssh):\/\/)(?:[^/@:]+:)?[^/@]+@/i, '$1')
+  }
+}
+
+export function parseNullConfig(text) {
+  const entries = []
+  for (const record of String(text || '').split('\0').filter(Boolean)) {
+    const newline = record.indexOf('\n')
+    if (newline === -1) entries.push({ key: record, value: '' })
+    else entries.push({ key: record.slice(0, newline), value: record.slice(newline + 1) })
+  }
+  return entries
+}