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

package/src/collaboration/review-store.mjs

@@ -0,0 +1,305 @@
+import path from 'node:path'
+import { validReviewArtifact } from './review-contracts.mjs'
+import { createCollaborationEventLedger } from './event-ledger.mjs'
+import {
+  loadBoundRun,
+  currentRunEligibility,
+  hashEvidence,
+  readBoundedSource,
+} from '../readiness-protocols/evidence.mjs'
+import { buildGraph } from '../graph/graph.mjs'
+import { readRegularTextNoFollow } from '../project/private-state.mjs'
+
+const idPattern = /^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,159}$/
+const text = (value, max) =>
+  typeof value === 'string' && value.trim().length > 0 && value.length <= max
+const invalid = (error, status = 400) => ({ ok: false, status, error })
+
+export const contributionKey = (input) =>
+  hashEvidence({
+    kind: input.kind,
+    targetId: input.targetId,
+    runId: input.runId ?? null,
+    repo: input.repo ?? null,
+    path: input.path ?? null,
+    reader: input.kind === 'position' ? input.reviewer : null,
+  })
+export function validContribution(record) {
+  return (
+    validReviewArtifact('record', record) &&
+    record.inputDigest === hashEvidence(record.input) &&
+    record.key === contributionKey(record.input) &&
+    record.version === record.input.expectedVersion + 1 &&
+    record.identity.name === record.input.reviewer
+  )
+}
+
+export function createReviewStore(project) {
+  const ledger = createCollaborationEventLedger({
+    workspaceRoot: project.configDir,
+    ledgerPath: path.join(
+      project.configDir,
+      '.atelier-local/review/contributions.ndjson',
+    ),
+  })
+  function records() {
+    const all = ledger.readAll()
+    if (!all.ok) return all
+    const result = all.events.map((event) => event.payload)
+    const versions = new Map(),
+      requests = new Set()
+    for (let index = 0; index < result.length; index++) {
+      const record = result[index],
+        event = all.events[index]
+      if (
+        !validContribution(record) ||
+        requests.has(record.input.requestId) ||
+        event.aggregateId !== `contribution:${record.input.requestId}` ||
+        event.type !== 'contribution-recorded' ||
+        event.actor !== record.input.reviewer ||
+        record.version !== (versions.get(record.key) ?? 0) + 1
+      )
+        return invalid('contribution history is invalid', 422)
+      requests.add(record.input.requestId)
+      versions.set(record.key, record.version)
+    }
+    return { ok: true, status: 200, records: result }
+  }
+  function contribution(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+      return invalid('contribution must be an object')
+    const keys = [
+      'requestId',
+      'kind',
+      'targetId',
+      'expectedVersion',
+      'reviewer',
+      'rationale',
+      'runId',
+      'evidenceDigest',
+      'decision',
+      'revision',
+      'repo',
+      'path',
+      'documentDigest',
+      'anchor',
+      'responseType',
+      'wording',
+      'position',
+      'ext',
+    ]
+    if (Object.keys(input).some((key) => !keys.includes(key)))
+      return invalid('unknown contribution field')
+    if (
+      !idPattern.test(input.requestId ?? '') ||
+      !idPattern.test(input.targetId ?? '') ||
+      !Number.isSafeInteger(input.expectedVersion) ||
+      input.expectedVersion < 0 ||
+      !text(input.reviewer, 160) ||
+      input.reviewer !== input.reviewer.trim()
+    )
+      return invalid(
+        'request identity, expected version and reviewer are required',
+      )
+    if (!['decision', 'response', 'position'].includes(input.kind))
+      return invalid('unsupported contribution kind')
+    if (
+      input.kind === 'decision' &&
+      (!['accepted', 'rejected', 'revised'].includes(input.decision) ||
+        !text(input.rationale, 8000) ||
+        !text(input.runId, 160) ||
+        !/^sha256:[a-f0-9]{64}$/.test(input.evidenceDigest ?? '') ||
+        (input.decision === 'revised' && !text(input.revision, 8000)))
+    )
+      return invalid('decision, rationale and evidence identity are required')
+    if (
+      input.kind !== 'decision' &&
+      (!text(input.repo, 160) ||
+        !text(input.path, 2048) ||
+        !/^sha256:[a-f0-9]{64}$/.test(input.documentDigest ?? '') ||
+        !text(input.anchor, 8000))
+    )
+      return invalid('document identity and passage anchor are required')
+    if (
+      input.kind === 'response' &&
+      (!['question', 'correction', 'discussion'].includes(input.responseType) ||
+        !text(input.wording, 16000))
+    )
+      return invalid('response type and original wording are required')
+    if (
+      input.kind === 'position' &&
+      (!Number.isSafeInteger(input.position) || input.position < 0)
+    )
+      return invalid('reading position is required')
+    if (!validReviewArtifact('input', input))
+      return invalid(
+        'contribution contract invalid or contains fields for a different kind',
+      )
+    const inputDigest = hashEvidence(input)
+    const history = records()
+    if (!history.ok) return history
+    const previous = history.records.find(
+      (record) => record.input.requestId === input.requestId,
+    )
+    if (previous)
+      return previous.inputDigest === inputDigest
+        ? { ok: true, status: 200, record: previous, replayed: true }
+        : invalid('request ID reused with different content', 409)
+    const key = contributionKey(input)
+    const payload = {
+      schema: 'atelier-contribution@v1',
+      input,
+      inputDigest,
+      key,
+      version: input.expectedVersion + 1,
+      identity: { kind: 'local-asserted', name: input.reviewer },
+      recordedAt: new Date().toISOString(),
+    }
+    const appended = ledger.append({
+      aggregateId: `contribution:${input.requestId}`,
+      expectedVersion: 0,
+      type: 'contribution-recorded',
+      actor: input.reviewer,
+      payload,
+      precondition: () => {
+        const current = records()
+        if (!current.ok) return current
+        const count = current.records.filter(
+          (record) => record.key === key,
+        ).length
+        if (count !== input.expectedVersion)
+          return invalid('stale contribution version', 409)
+        if (input.kind === 'decision') {
+          const bound = loadBoundRun(project, input.runId)
+          if (!bound.ok) return bound
+          if (
+            input.decision === 'accepted' &&
+            (bound.run.blockers.length ||
+              bound.snapshot.claimEvidence[
+                bound.run.claims.findIndex(
+                  (claim) => claim.claimId === input.targetId,
+                )
+              ]?.status !== 'linked-source')
+          )
+            return invalid(
+              'required input or mapped source evidence is incomplete; acceptance refused',
+              409,
+            )
+          if (
+            bound.snapshot.digest !== input.evidenceDigest ||
+            !bound.run.claims.some(
+              (claim) => claim.claimId === input.targetId,
+            ) ||
+            !currentRunEligibility(project, bound)
+          )
+            return invalid('claim evidence changed or is unavailable', 409)
+        } else {
+          const source = document(input.repo, input.path)
+          if (!source.ok) return source
+          if (
+            source.digest !== input.documentDigest ||
+            !source.text.includes(input.anchor)
+          )
+            return invalid(
+              'document changed or anchor is missing; reassociation required',
+              409,
+            )
+          if (
+            input.kind === 'position' &&
+            (input.position > source.text.length ||
+              !source.text.slice(input.position).startsWith(input.anchor))
+          )
+            return invalid('position does not match the anchored passage')
+        }
+        return { ok: true }
+      },
+    })
+    if (!appended.ok) {
+      if (appended.status === 409) {
+        const latest = records()
+        const duplicate =
+          latest.ok &&
+          latest.records.find(
+            (record) => record.input.requestId === input.requestId,
+          )
+        if (duplicate?.inputDigest === inputDigest)
+          return { ok: true, status: 200, record: duplicate, replayed: true }
+      }
+      return appended
+    }
+    return { ok: true, status: 200, record: payload, replayed: false }
+  }
+  function document(repoName, relative) {
+    const repo = project.repos.find(
+      (entry) => entry.name === repoName && !entry.external,
+    )
+    if (
+      !repo?.path ||
+      !/\.(md|txt)$/i.test(relative ?? '') ||
+      relative.split(/[\\/]/).some((segment) => segment.startsWith('.'))
+    )
+      return invalid('document is outside the review surface', 403)
+    try {
+      if (
+        project.configPath &&
+        hashEvidence(
+          JSON.parse(readRegularTextNoFollow(project.configPath)),
+        ) !== hashEvidence(project.config)
+      )
+        return invalid('project changed; restart review', 409)
+      const graph = buildGraph(project)
+      if (
+        graph.errors.length ||
+        !graph.nodes.some(
+          (node) => node.repo === repoName && node.path === relative,
+        )
+      )
+        return invalid('document is not in the valid source graph', 403)
+      return {
+        ok: true,
+        status: 200,
+        ...readBoundedSource(repo.path, relative),
+      }
+    } catch {
+      return invalid('document unavailable or unsafe', 409)
+    }
+  }
+  function handoff(requestId) {
+    const all = records()
+    if (!all.ok) return all
+    const record = all.records.find(
+      (entry) =>
+        entry.input.requestId === requestId &&
+        entry.input.kind === 'decision' &&
+        entry.input.decision === 'accepted',
+    )
+    if (!record) return invalid('accepted decision unavailable', 404)
+    const bound = loadBoundRun(project, record.input.runId)
+    if (!bound.ok) return bound
+    const latest = all.records
+      .filter((entry) => entry.key === record.key)
+      .at(-1)
+    return {
+      ok: true,
+      status: 200,
+      schema: 'atelier-owner-handoff@v1',
+      decision: record,
+      claim: bound.run.claims.find(
+        (claim) => claim.claimId === record.input.targetId,
+      ),
+      requiredEvidenceDigest: bound.snapshot.digest,
+      current:
+        latest.input.requestId === requestId &&
+        currentRunEligibility(project, bound),
+      supersededBy:
+        latest.input.requestId === requestId ? null : latest.input.requestId,
+      sourceChangesApplied: false,
+      promotion: 'not-established',
+      instructions:
+        'Source owner must review the intended edit against current source and record application separately.',
+    }
+  }
+  // One immutable event per aggregate means generic compaction retains every
+  // contribution. Per-target versions are checked inside the ledger write lock.
+  return { records, contribute: contribution, document, handoff }
+}

package/src/commands/coauthor.mjs

@@ -0,0 +1,26 @@
+import { createCoauthorStore } from '../coauthor/store.mjs';
+
+const usage = 'Usage: atelier coauthor start|read|event|recover\nRead one JSON request from stdin (maximum 1 MiB). Start: {"config":...}; read/recover: {"sessionId":...}; event: {"sessionId":...,"event":...}. Workspace is the current directory. Saves are private drafts, not source edits.';
+const command = process.argv[2];
+if (command === '--help' || command === 'help') { console.log(usage); process.exit(0); }
+try {
+  if (!['start', 'read', 'event', 'recover'].includes(command) || process.argv.length !== 3) throw new Error(usage);
+  const chunks = [];
+  let count = 0;
+  for await (const chunk of process.stdin) {
+    count += chunk.length;
+    if (count > 1024 * 1024) throw new Error('request exceeds byte ceiling');
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('object required');
+  const allowed = command === 'start' ? ['config'] : command === 'event' ? ['sessionId', 'event'] : ['sessionId'];
+  if (Object.keys(input).some(key => !allowed.includes(key)) || allowed.some(key => !Object.hasOwn(input, key))) throw new Error('invalid request fields');
+  const store = createCoauthorStore();
+  const state = command === 'start' ? store.start(input.config) : command === 'read' ? store.read(input.sessionId)
+    : command === 'recover' ? store.recover(input.sessionId) : store.dispatch(input.sessionId, input.event);
+  console.log(JSON.stringify({ ok: true, state, savedMeaning: 'private-draft-only' }));
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: error.message }));
+  process.exitCode = 1;
+}

package/src/commands/config.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
 import { commandProject } from '../project/config.mjs'
 const project = commandProject()
-console.log(JSON.stringify({ ok: true, schema: project.schema, configPath: project.configPath, repos: project.repos.map((repo) => repo.name) }, null, 2))
+const report = process.argv.includes('--explain')
+  ? { ok: true, schema: project.schema, configSource: project.source, repos: project.repos.map((repo) => ({
+    name: repo.name, pathSource: repo.pathSource, resolved: repo.path !== null, readBoundary: repo.readBoundary, external: repo.external,
+  })) }
+  : { ok: true, schema: project.schema, configPath: project.configPath, repos: project.repos.map((repo) => repo.name) }
+console.log(JSON.stringify(report, null, 2))

package/src/commands/extension-pack.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 // atelier extension-pack validate|list
 //
-// Self-contained subcommand parser (no shared CLI plumbing) so the module can
-// be invoked directly: node src/commands/extension-pack.mjs <subcommand> ...
+// Shared project options also work when this module is invoked directly.
 //
 // Exit codes: 0 every enabled pack loads clean (warnings do not fail),
 // 1 an enabled pack failed to load, 2 usage or project resolution error.
@@ -13,6 +12,7 @@
 import path from 'node:path'
 import { ATELIER_EXT_NAMESPACE, loadExtensionPacks } from '../extension-packs/loader.mjs'
 import { asObject, commandProject } from '../project/config.mjs'
+import { PROJECT_OPTION_SPEC, projectOptionAt } from '../cli/project-options.mjs'
 
 const REPORT_SCHEMA = 'mnstry.atelier-extension-pack-report@v1'
 const LIST_SCHEMA = 'mnstry.atelier-extension-pack-list@v1'
@@ -35,6 +35,10 @@ ext["${ATELIER_EXT_NAMESPACE}"].extensionPacks. Pack protocols are resolvable
 by full namespaced id only; the machine-local overlay can disable a declared
 pack but can never enable an undeclared one.
 
+Project options: --project PATH (alias --project-config PATH) and repeated
+--repo-path NAME=PATH also accept --flag=value. Repo overrides resolve from
+the current directory and do not declare new repos or widen read boundaries.
+
 Exit codes: 0 every enabled pack loads clean (warnings do not fail),
 1 an enabled pack failed to load, 2 usage or project resolution error.`
 
@@ -43,10 +47,10 @@ function fail(message) {
   process.exit(2)
 }
 
-// --project / --project-config (both --flag VALUE and --flag=VALUE forms) are
+// Shared project options (both --flag VALUE and --flag=VALUE forms) are
 // recognized here for the unknown-option check only; commandProject reads the
 // same process.argv itself, so the values need no forwarding.
-const OPTION_SPEC = { json: 'flag', project: 'value', 'project-config': 'value' }
+const OPTION_SPEC = { json: 'flag', ...PROJECT_OPTION_SPEC }
 
 function parseOptions(argv) {
   const options = { json: false }
@@ -60,12 +64,15 @@ function parseOptions(argv) {
       fail(`unexpected argument: ${arg}\n\n${USAGE}`)
     }
     const name = arg.slice(2).split('=')[0]
-    if (!(name in OPTION_SPEC)) fail(`unknown option --${name}\n\n${USAGE}`)
+    if (!Object.hasOwn(OPTION_SPEC, name)) fail(`unknown option --${name}\n\n${USAGE}`)
     if (OPTION_SPEC[name] === 'flag') {
       options[name] = true
-    } else if (!arg.includes('=')) {
-      i += 1
-      if (argv[i] === undefined) fail(`--${name} requires a value`)
+    } else {
+      try {
+        i = projectOptionAt(argv, i).nextIndex - 1
+      } catch (error) {
+        fail(error.message)
+      }
     }
   }
   return options

package/src/commands/init.mjs

@@ -25,7 +25,29 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'))
 }
 
-function copyDir(source, target, { renameGitignore = true } = {}) {
+function existsWithoutFollowingLinks(file) {
+  try { fs.lstatSync(file); return true } catch (error) {
+    if (error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function assertNoTemplateCollisions(source, target, renameGitignore = true) {
+  if (fs.existsSync(target) && (!fs.lstatSync(target).isDirectory() || fs.lstatSync(target).isSymbolicLink())) {
+    throw new Error('init target must be a real directory')
+  }
+  for (const ent of fs.readdirSync(source, { withFileTypes: true })) {
+    const name = renameGitignore && ent.name === 'gitignore' && ent.isFile() ? '.gitignore' : ent.name
+    const to = path.join(target, name)
+    if (ent.isDirectory()) assertNoTemplateCollisions(path.join(source, ent.name), to, false)
+    else if (existsWithoutFollowingLinks(to)) {
+      throw new Error(`init refuses existing template file: ${name}; use adopt for an existing workspace`)
+    }
+  }
+}
+
+function copyDir(source, target, { renameGitignore = true, preflight = true } = {}) {
+  if (preflight) assertNoTemplateCollisions(source, target, renameGitignore)
   fs.mkdirSync(target, { recursive: true })
   for (const ent of fs.readdirSync(source, { withFileTypes: true })) {
     const from = path.join(source, ent.name)
@@ -33,7 +55,7 @@ function copyDir(source, target, { renameGitignore = true } = {}) {
     // `gitignore` at the template root; nested files keep their literal names.
     const rename = renameGitignore && ent.name === 'gitignore' && ent.isFile()
     const to = path.join(target, rename ? '.gitignore' : ent.name)
-    if (ent.isDirectory()) copyDir(from, to, { renameGitignore: false })
+    if (ent.isDirectory()) copyDir(from, to, { renameGitignore: false, preflight: false })
     else fs.copyFileSync(from, to)
   }
 }
@@ -44,7 +66,7 @@ function personalizeBoundaryPolicy(target, { actor, githubLogin, gitEmail } = {}
   const policy = readJson(policyPath)
   const actorId = slug(actor || 'owner')
   const privateDomainRepo = Object.entries(policy.repos || {}).find(([, repo]) => repo?.kind === 'private_domain')?.[0] || `mnstry-private-${actorId}`
-  const login = githubLogin || process.env.GITHUB_ACTOR || actorId
+  const login = githubLogin || `${actorId.toUpperCase()}_GITHUB_LOGIN_PLACEHOLDER`
   const email = gitEmail || gitConfig('user.email') || `${actorId}@example.invalid`
 
   policy.actors = {
@@ -60,9 +82,26 @@ function personalizeBoundaryPolicy(target, { actor, githubLogin, gitEmail } = {}
 
 const args = parseArgs(process.argv.slice(2))
 const target = path.resolve(args.target || process.cwd())
+for (const name of ['atelier.project.json', 'atelier.lock.json', 'repo-access.v1.json', 'boundary-policy.v1.json']) {
+  try {
+    fs.lstatSync(path.join(target, name))
+  } catch (error) {
+    if (error.code === 'ENOENT') continue
+    throw error
+  }
+  throw new Error(`init refuses existing ${name}; use adopt or upgrade for an existing workspace`)
+}
 const template = args.template || args.fixture
 let templateId = template || 'default'
-if (template === 'sample-workspace') {
+if (template === 'external-project') {
+  for (let parent = path.dirname(target);; parent = path.dirname(parent)) {
+    if (fs.existsSync(parent) && fs.lstatSync(parent).isSymbolicLink()) throw new Error('external-project destination has a redirected ancestor')
+    if (path.dirname(parent) === parent) break
+  }
+  if (fs.existsSync(target)) throw new Error('external-project target must not exist; refusing overwrite or redirected destination')
+  copyDir(path.join(packageRoot, 'templates/external-project-workspace'), target)
+  console.log(`created external-project adapter at ${target}`)
+} else if (template === 'sample-workspace') {
   copyDir(path.join(packageRoot, 'fixtures/projects/sample-workspace'), target)
   console.log(`created sample Atelier workspace at ${target}`)
 } else if (template === 'private-domain') {
@@ -92,7 +131,7 @@ if (template === 'sample-workspace') {
 } else if (template) {
   // Unknown template names fail closed: a typo must not silently produce a
   // blank scaffold that lacks the boundary policy the caller asked for.
-  console.error(`Unknown template: ${template}. Valid templates: private-domain, shared-project, sample-workspace, distribution.`)
+  console.error(`Unknown template: ${template}. Valid templates: private-domain, shared-project, sample-workspace, distribution, external-project.`)
   process.exit(1)
 } else {
   fs.mkdirSync(target, { recursive: true })