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

package/src/guides/contracts.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-guide.v1.schema.json', import.meta.url), 'utf8'));
+export function guideDocumentDigest(value) { return createHash('sha256').update(canonicalize(value)).digest('hex'); }
+export function validateGuideDocument(value, kind) {
+  if (!['offer', 'capability', 'consent', 'engagement'].includes(kind)) return ['unknown guide document kind'];
+  const errors = validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}` }, value);
+  if (kind === 'capability' && !errors.length) {
+    const url = new URL(value.serviceRef);
+    if (url.username || url.password || url.search || url.hash) errors.push('service reference must not contain credentials, query or fragment');
+  }
+  return errors;
+}
+function requireValid(value, kind) {
+  if (validateGuideDocument(value, kind).length) throw new Error(`invalid guide ${kind}`);
+}
+export function createGuideEngagement(offer) {
+  requireValid(offer, 'offer');
+  return { schema: 'mnstry.atelier-guide-engagement@v1', offerDigest: guideDocumentDigest(offer),
+    revision: 0, status: 'proposed', authority: 'local-assertion-only' };
+}
+export function transitionGuideEngagement(state, { expectedRevision, action, offerDigest }) {
+  requireValid(state, 'engagement');
+  if (expectedRevision !== state.revision || offerDigest !== state.offerDigest) throw new Error('stale or mismatched guide engagement');
+  const routes = { proposed: { accept: 'accepted', revoke: 'revoked' }, accepted: { pause: 'paused', revoke: 'revoked' }, paused: { resume: 'accepted', revoke: 'revoked' }, revoked: {} };
+  const status = Object.hasOwn(routes[state.status], action) ? routes[state.status][action] : null;
+  if (!status) throw new Error('guide transition refused');
+  return { ...state, revision: state.revision + 1, status };
+}
+
+// No connection, credentials, invocation, payment, or permission grant occurs.
+// A host must independently authenticate participants and revalidate revocation,
+// consent, policy, schema and exact bytes immediately before any disclosure.
+export function assessGuideInvocation({ offer, capability, engagement, consent, payload, now }) {
+  const blockers = [];
+  for (const [kind, value] of Object.entries({ offer, capability, engagement, consent })) {
+    if (validateGuideDocument(value, kind).length) blockers.push(`invalid ${kind}`);
+  }
+  if (blockers.length) return { status: 'blocked', blockers, executionAuthority: false };
+  let bytes;
+  try { bytes = canonicalize(payload); } catch { blockers.push('payload is not canonical JSON'); }
+  if (!Number.isFinite(now)) blockers.push('explicit current time required');
+  if (engagement.status !== 'accepted') blockers.push('engagement is not accepted');
+  if (engagement.offerDigest !== guideDocumentDigest(offer) || consent.offerDigest !== engagement.offerDigest) blockers.push('offer binding mismatch');
+  if (consent.engagementRevision !== engagement.revision) blockers.push('consent revision is stale');
+  if (!offer.capabilityIds.includes(capability.id) || consent.capabilityDigest !== guideDocumentDigest(capability)) blockers.push('capability binding mismatch');
+  if (consent.status !== 'approved') blockers.push('disclosure consent is not approved');
+  if (now < Date.parse(consent.validFrom) || now >= Date.parse(consent.expiresAt) || Date.parse(consent.validFrom) >= Date.parse(consent.expiresAt)) blockers.push('consent is not currently valid');
+  if (bytes !== undefined && (Buffer.byteLength(bytes) > capability.maxInputBytes || guideDocumentDigest(payload) !== consent.payloadDigest)) blockers.push('payload binding or byte limit mismatch');
+  return { status: blockers.length ? 'blocked' : 'eligible-for-host-validation', blockers, executionAuthority: false };
+}

package/src/index.mjs

@@ -98,3 +98,32 @@ export {
 export {
   analysisAdapterDryRun,
 } from './analysis/adapter.mjs'
+
+export {
+  GitCommandError,
+  classifyRemoteAuthentication,
+  inspectGitEngine,
+  parseGitVersion,
+  resolveGitExecutable,
+  runGit,
+  sanitizeRemoteUrl,
+} from './runtime/git-adapter.mjs'
+
+export {
+  ATELIER_REPOSITORY_OBSERVATION_SCHEMA,
+  classifyFilesystemRoot,
+  observeRepository,
+  resolveRepositoryRoot,
+  validateRepositoryObservation,
+} from './runtime/repository-observation.mjs'
+
+export {
+  ATELIER_COMMIT_PLAN_SCHEMA,
+  enrollRepository,
+  executeUserConfirmedCommit,
+  operationTrace,
+  planUserConfirmedCommit,
+  reconcileRepository,
+  runtimeStatus,
+  setRepositoryPaused,
+} from './runtime/supervisor.mjs'

package/src/intake/store.mjs

@@ -0,0 +1,119 @@
+import { withPrivateLock, publishPrivateFile } from '../project/durable-state.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+
+export const INTAKE_MAX_BYTES = 16 * 1024 * 1024;
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-intake.v1.schema.json', import.meta.url), 'utf8'));
+export function validateIntakeDocument(value) { return validateJsonSchema(schema, value); }
+function valid(value) { if (validateIntakeDocument(value).length) throw new Error('invalid intake document'); return value; }
+export function intakeDigest(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+const idPattern = /^[a-z][a-z0-9-]{0,63}$/;
+const digestPattern = /^[0-9a-f]{64}$/;
+function digest(value) { if (!digestPattern.test(value ?? '')) throw new Error('invalid content digest'); return value; }
+function id(value) { if (!idPattern.test(value ?? '')) throw new Error('invalid intake identifier'); return value; }
+function read(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > INTAKE_MAX_BYTES) throw new Error('intake byte ceiling exceeded');
+    const bytes = fs.readFileSync(fd);
+    if (bytes.length > INTAKE_MAX_BYTES) throw new Error('intake byte ceiling exceeded');
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+function immutable(file, bytes) {
+  publishPrivateFile(file, bytes);
+  if (!read(file).equals(Buffer.from(bytes))) throw new Error('immutable intake readback mismatch');
+}
+
+// Local integrity storage, not a worker, semantic acceptance service, or import
+// authority. Callers retain their source trees and choose their existing extractor.
+export function createIntakeStore({ workspaceRoot = process.cwd() } = {}) {
+  const root = fs.realpathSync(workspaceRoot);
+  function placement() {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      if (execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })) throw new Error('tracked state');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env, stdio: 'ignore' });
+    } catch { throw new Error('intake requires ignored, untracked .atelier-local/ in a Git workspace'); }
+  }
+  placement();
+  function directory(...parts) {
+    return ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, '.atelier-local', 'intake', ...parts), label: 'intake state' });
+  }
+  function locked(fn) {
+    placement();
+    const file = path.join(directory(), 'operation.lock');
+    return withPrivateLock(file, fn);
+  }
+  function sourceFile(ref) {
+    if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || ref.includes('\\') ||
+      ref.split('/').some(p => !p || p === '.' || p === '..' || p.startsWith('.'))) throw new Error('source must be a visible workspace-relative file');
+    let file = root;
+    for (const part of ref.split('/')) {
+      file = path.join(file, part);
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error('redirected intake source refused');
+    }
+    return file;
+  }
+  function blob(blobId) {
+    const bytes = read(path.join(directory('blobs'), digest(blobId)));
+    if (intakeDigest(bytes) !== blobId) throw new Error('stored blob digest mismatch');
+    return bytes;
+  }
+  function record(dir, name, value) { valid(value); immutable(path.join(dir, name), canonicalize(value) + '\n'); return value; }
+  return Object.freeze({
+    ingest({ ref, expectedDigest }) {
+      return locked(() => {
+        digest(expectedDigest);
+        const file = sourceFile(ref), bytes = read(file);
+        if (intakeDigest(bytes) !== expectedDigest) throw new Error('source digest mismatch');
+        immutable(path.join(directory('blobs'), expectedDigest), bytes);
+        if (intakeDigest(read(sourceFile(ref))) !== expectedDigest) throw new Error('source changed during intake');
+        const manifest = { schema: 'mnstry.atelier-intake-source@v1', sourceRef: ref, blobId: expectedDigest, bytes: bytes.length, originalMutation: false };
+        return record(directory('sources'), intakeDigest(canonicalize(manifest)) + '.json', manifest);
+      });
+    },
+    beginAttempt({ attemptId, blobId, extractorId, extractorVersion, configurationDigest }) {
+      return locked(() => {
+        id(attemptId); id(extractorId); digest(configurationDigest); blob(blobId);
+        if (typeof extractorVersion !== 'string' || !/^[a-zA-Z0-9._-]{1,64}$/.test(extractorVersion)) throw new Error('invalid extractor version');
+        const manifest = { schema: 'mnstry.atelier-intake-attempt@v1', attemptId, blobId, extractorId, extractorVersion, configurationDigest };
+        return record(directory('attempts', attemptId), 'attempt.json', manifest);
+      });
+    },
+    completeAttempt({ attemptId, output, expectedOutputDigest }) {
+      return locked(() => {
+        id(attemptId); digest(expectedOutputDigest);
+        if (typeof output !== 'string' || Buffer.byteLength(output) > INTAKE_MAX_BYTES) throw new Error('output must be bounded UTF-8 text');
+        if (intakeDigest(output) !== expectedOutputDigest) throw new Error('output digest mismatch');
+        const dir = directory('attempts', attemptId);
+        const attemptBytes = read(path.join(dir, 'attempt.json'));
+        const attempt = valid(JSON.parse(attemptBytes));
+        if (attempt.attemptId !== attemptId || attempt.schema !== 'mnstry.atelier-intake-attempt@v1') throw new Error('attempt identity mismatch');
+        blob(attempt.blobId);
+        immutable(path.join(dir, 'output.txt'), output);
+        // Completion is written last. A crash before it is incomplete, not success.
+        return record(dir, 'completion.json', { schema: 'mnstry.atelier-intake-completion@v1', attemptId,
+          attemptDigest: intakeDigest(attemptBytes), outputDigest: expectedOutputDigest, bytes: Buffer.byteLength(output),
+          integrity: 'verified', semanticAcceptance: 'pending' });
+      });
+    },
+    readCompletion(attemptId) {
+      placement(); id(attemptId);
+      const dir = directory('attempts', attemptId), receipt = valid(JSON.parse(read(path.join(dir, 'completion.json'))));
+      if (receipt.schema !== 'mnstry.atelier-intake-completion@v1' || receipt.attemptId !== attemptId ||
+        receipt.integrity !== 'verified' || receipt.semanticAcceptance !== 'pending') throw new Error('invalid completion receipt');
+      const attemptBytes = read(path.join(dir, 'attempt.json')), output = read(path.join(dir, 'output.txt'));
+      if (intakeDigest(attemptBytes) !== receipt.attemptDigest || intakeDigest(output) !== receipt.outputDigest || output.length !== receipt.bytes) throw new Error('completion integrity mismatch');
+      const attempt = valid(JSON.parse(attemptBytes));
+      if (attempt.attemptId !== attemptId || attempt.schema !== 'mnstry.atelier-intake-attempt@v1') throw new Error('attempt identity mismatch');
+      blob(attempt.blobId);
+      return receipt;
+    },
+  });
+}

package/src/preview/channel.mjs

@@ -0,0 +1,89 @@
+// Browser-only channel. Host/session/service authority never enters this module.
+import { parseRequest, parseBoundedJSON, closed, need, isRef, isDigest, MODES } from '../composition/wire.mjs';
+const HELLO = 'atelier.preview.mount/experimental-v1';
+function origin(value) { const u = new URL(value); need(u.origin !== 'null' && u.protocol === 'https:' && u.origin === value); return value; }
+function resultCheck(bytes, request, generation) {
+  const result = parseBoundedJSON(bytes);
+  closed(result, ['state'], ['projectedData']);
+  const s = result.state;
+  closed(s, ['schema', 'requestId', 'placementId', 'sourceDigest', 'mode', 'state', 'sessionGeneration', 'publicMessage']);
+  need(s.schema === 'atelier-preview-state/proposal-v1' && s.requestId === request.requestId && s.placementId === request.placementId && s.sourceDigest === request.sourceDigest && s.mode === request.mode);
+  need(s.sessionGeneration === generation && ['loading', 'ready', 'unauthenticated', 'forbidden', 'expired', 'unavailable', 'stale'].includes(s.state));
+  need(typeof s.publicMessage === 'string' && s.publicMessage.length <= 160);
+  need(s.state === 'ready' ? Object.hasOwn(result, 'projectedData') : !Object.hasOwn(result, 'projectedData'));
+  return result;
+}
+function fail(request, generation) { return { state: { schema: 'atelier-preview-state/proposal-v1', requestId: request.requestId, placementId: request.placementId,
+  sourceDigest: request.sourceDigest, mode: request.mode, state: 'unavailable', sessionGeneration: generation, publicMessage: 'Preview unavailable.' } }; }
+
+export function mountPreview({ frame, previewOrigin, requestBytes, generation, handle, onState = () => {} }) {
+  origin(previewOrigin); need(new URL(frame.src).origin === previewOrigin && previewOrigin !== window.location.origin);
+  const template = parseRequest(requestBytes); need(!template.intentRef && Number.isSafeInteger(generation) && generation >= 0 && typeof handle === 'function');
+  const nonce = crypto.randomUUID(), channel = new MessageChannel(), controller = new AbortController();
+  let active = true, ready = false, sequence = 0, latest = 0;
+  const invalidate = () => {
+    if (!active) return; active = false; controller.abort();
+    channel.port1.postMessage(JSON.stringify({type:'invalidate',nonce})); channel.port1.close(); frame.removeEventListener('load', invalidate);
+    onState('stale');
+  };
+  frame.addEventListener('load', invalidate); // Future navigation invalidates this mount.
+  channel.port1.onmessage = async event => {
+    if (!active) return;
+    try {
+      const v = parseBoundedJSON(event.data);
+      if (!ready) { closed(v, ['type', 'nonce']); need(v.type === 'ready' && v.nonce === nonce); ready = true; onState('connected'); return; }
+      closed(v, ['type', 'nonce', 'sequence', 'request']);
+      need(v.type === 'request' && v.nonce === nonce && Number.isSafeInteger(v.sequence) && v.sequence > sequence);
+      const request = parseRequest(v.request);
+      need(request.placementId === template.placementId && request.sourceDigest === template.sourceDigest && request.mode === template.mode);
+      sequence = v.sequence; latest = sequence; const thisSequence = sequence;
+      let result;
+      try { result = resultCheck(JSON.stringify(await handle(v.request, controller.signal)), request, generation); }
+      catch { result = fail(request, generation); }
+      if (!active || controller.signal.aborted || thisSequence !== latest) return;
+      channel.port1.postMessage(JSON.stringify({ type: 'result', nonce, sequence: thisSequence, result }));
+    } catch { invalidate(); }
+  };
+  channel.port1.start();
+  frame.contentWindow.postMessage(JSON.stringify({ type: HELLO, nonce, generation, request: requestBytes }), previewOrigin, [channel.port2]);
+  return Object.freeze({ dispose: invalidate });
+}
+
+export function receivePreview({ shellOrigin, onMount, onResult, onInvalidate = () => {} }) {
+  origin(shellOrigin); need(shellOrigin !== window.location.origin);
+  let active = null;
+  function clear() { active?.port.close(); active = null; onInvalidate(); }
+  function receive(event) {
+    if (event.origin !== shellOrigin || event.source !== window.parent) return;
+    try {
+      const v = parseBoundedJSON(event.data);
+      closed(v, ['type', 'nonce', 'generation', 'request']);
+      need(v.type === HELLO && isRef(v.nonce) && Number.isSafeInteger(v.generation) && v.generation >= 0 && event.ports.length === 1);
+      const request = parseRequest(v.request); need(!request.intentRef && isDigest(request.sourceDigest) && MODES.includes(request.mode));
+      clear();
+      const mount = { port: event.ports[0], nonce: v.nonce, generation: v.generation, request, sequence: 0, settled: 0 };
+      active = mount;
+      mount.port.onmessage = e => {
+        if (active !== mount) return;
+        try {
+          const packet = parseBoundedJSON(e.data);
+          if (packet?.type === 'invalidate') { closed(packet, ['type','nonce']); need(packet.nonce === mount.nonce); clear(); return; }
+          closed(packet, ['type', 'nonce', 'sequence', 'result']);
+          need(packet.type === 'result' && packet.nonce === mount.nonce && packet.sequence === mount.sequence && packet.sequence > mount.settled);
+          const result = resultCheck(JSON.stringify(packet.result), mount.pending, mount.generation);
+          mount.settled = packet.sequence; onResult(result);
+        } catch { clear(); }
+      };
+      mount.port.start(); mount.port.postMessage(JSON.stringify({ type: 'ready', nonce: mount.nonce }));
+      onMount(request);
+    } catch { clear(); }
+  }
+  window.addEventListener('message', receive);
+  return Object.freeze({ request(intent) {
+    if (!active) return false;
+    const sequence = ++active.sequence;
+    const request = { ...active.request, requestId: crypto.randomUUID(), ...(intent ? { schema: 'atelier-component-intent/proposal-v1', intentRef: intent.ref, payload: intent.payload } : {}) };
+    parseRequest(JSON.stringify(request)); active.pending = request;
+    active.port.postMessage(JSON.stringify({ type: 'request', nonce: active.nonce, sequence, request: JSON.stringify(request) })); return true;
+  }, dispose() { clear(); window.removeEventListener('message', receive); } });
+}

package/src/project/config.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
+import { parseProjectOptions } from '../cli/project-options.mjs'
 
 export const PROJECT_CONFIG_ARG_PREFIX = '--project-config='
 export const PROJECT_CONFIG_ENV = 'MNSTRY_ATELIER_PROJECT_CONFIG'
@@ -94,14 +96,7 @@ export function writeJson(file, value) {
 }
 
 export function projectConfigArg(argv = process.argv.slice(2), prefix = PROJECT_CONFIG_ARG_PREFIX) {
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    if (typeof arg !== 'string') continue
-    if (arg.startsWith(prefix)) return arg.slice(prefix.length).trim() || null
-    if ((arg === '--project-config' || arg === '--project') && argv[index + 1]) return String(argv[index + 1]).trim() || null
-    if (arg.startsWith('--project=')) return arg.slice('--project='.length).trim() || null
-  }
-  return null
+  return parseProjectOptions(argv, prefix).project
 }
 
 export function stripProjectConfigArgs(argv = [], prefix = PROJECT_CONFIG_ARG_PREFIX) {
@@ -170,22 +165,7 @@ export function readLocalOverlay({ configDir, env = process.env, cwd = process.c
 }
 
 export function parseRepoPathOverrides(argv = process.argv.slice(2), cwd = process.cwd()) {
-  const out = new Map()
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    let value = null
-    if (arg === '--repo-path' && argv[index + 1]) {
-      value = argv[index + 1]
-      index += 1
-    } else if (typeof arg === 'string' && arg.startsWith('--repo-path=')) {
-      value = arg.slice('--repo-path='.length)
-    }
-    if (!value || !value.includes('=')) continue
-    const [name, ...rest] = value.split('=')
-    const repoPath = rest.join('=')
-    if (firstString(name) && firstString(repoPath)) out.set(name.trim(), resolvePathValue(repoPath, cwd))
-  }
-  return out
+  return new Map([...parseProjectOptions(argv).repoPaths].map(([name, value]) => [name, resolvePathValue(value, cwd)]))
 }
 
 function overlayRepoPath(overlay, repoName) {
@@ -195,25 +175,25 @@ function overlayRepoPath(overlay, repoName) {
   return firstString(direct, repo.path, repo.localPath)
 }
 
-function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths }) {
+function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return cliRepoPaths.get(repoName)
   const overlayPath = overlayRepoPath(overlay, repoName)
   const fromOverlay = resolvePathValue(overlayPath, configDir)
   if (fromOverlay) return fromOverlay
   const fromConfig = resolvePathValue(repo.path, configDir) || resolvePathValue(repo.path, workspaceRoot)
   if (fromConfig) return fromConfig
-  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })
+  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })
 }
 
-function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir }) {
+function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return 'cli'
   if (overlayRepoPath(overlay, repoName)) return 'local-overlay'
   if (firstString(repo.path)) return 'tracked-config'
-  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })) return 'sibling-discovery'
+  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })) return 'sibling-discovery'
   return null
 }
 
-function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
+function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable = 'git', env = process.env }) {
   if (!repoName) return null
   const candidates = [
     path.join(workspaceRoot, repoName),
@@ -222,14 +202,14 @@ function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
   ]
   for (const candidate of candidates) {
     if (!fs.existsSync(candidate)) continue
-    if (repo.remote && !gitRemoteMatches(candidate, repo.remote)) continue
+    if (repo.remote && !gitRemoteMatches(candidate, repo.remote, { gitExecutable, env })) continue
     return path.resolve(candidate)
   }
   return null
 }
 
-function gitRemoteMatches(repoPath, expected) {
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+function gitRemoteMatches(repoPath, expected, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   if (result.status !== 0) return false
   const actual = normalizeRemote(result.stdout.trim())
   return actual === normalizeRemote(expected)
@@ -243,9 +223,9 @@ function normalizeRemote(value) {
     .toLowerCase()
 }
 
-export function gitRemoteUrl(repoPath) {
+export function gitRemoteUrl(repoPath, { gitExecutable = 'git', env = process.env } = {}) {
   if (!repoPath || !fs.existsSync(repoPath)) return null
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? firstString(result.stdout) : null
 }
 
@@ -268,7 +248,9 @@ export function resolveProjectConfig({
   env = process.env,
   cwd = process.cwd(),
   configArgPrefix = PROJECT_CONFIG_ARG_PREFIX,
+  gitExecutable = 'git',
   configEnv = PROJECT_CONFIG_ENV,
+  writeLocalState = true,
   defaults = {},
 } = {}) {
   const argPath = projectConfigArg(argv, configArgPrefix)
@@ -373,7 +355,7 @@ export function resolveProjectConfig({
     localOverlay,
     repos: (Array.isArray(config.repos) ? config.repos : []).map((repo) => {
       const repoName = firstString(repo.name) || (repo.path ? path.basename(repo.path) : null)
-      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths })
+      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths, gitExecutable, env })
       const external = isExternalRepo(repo)
       return {
         ...repo,
@@ -381,16 +363,16 @@ export function resolveProjectConfig({
         path: repoPath,
         external,
         readBoundary: external ? null : firstString(repo.readBoundary) || 'team',
-        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir }) : null,
+        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) : null,
       }
     }),
   }
-  resolved.localState = ensureLocalState(resolved, { write: true })
+  resolved.localState = ensureLocalState(resolved, { write: writeLocalState, gitExecutable, env })
   return resolved
 }
 
-export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd() } = {}) {
-  const project = resolveProjectConfig({ argv, env, cwd })
+export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd(), gitExecutable = 'git', writeLocalState = true } = {}) {
+  const project = resolveProjectConfig({ argv, env, cwd, gitExecutable, writeLocalState })
   // Fail closed at CLI entry, but only when a real config file was loaded; the
   // defaults/no-file path resolves with an empty config that would spuriously
   // fail document validation.
@@ -419,35 +401,35 @@ export function localStateRoot(projectOrDir) {
   return path.join(configDir || process.cwd(), LOCAL_STATE_DIR)
 }
 
-function gitRootFor(dir) {
-  const result = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+function gitRootFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? result.stdout.trim() : null
 }
 
-function gitPrefixFor(dir) {
-  const result = spawnSync('git', ['-C', dir, 'rev-parse', '--show-prefix'], { encoding: 'utf8' })
+function gitPrefixFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-prefix'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? result.stdout.trim() : null
 }
 
-function isIgnoredByGit(gitRoot, rel) {
-  const result = spawnSync('git', ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8' })
+function isIgnoredByGit(gitRoot, rel, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0
 }
 
-export function ensureLocalState(project, { write = false } = {}) {
+export function ensureLocalState(project, { write = false, gitExecutable = 'git', env = process.env } = {}) {
   const root = localStateRoot(project)
-  const gitRoot = gitRootFor(project.configDir)
+  const gitRoot = gitRootFor(project.configDir, { gitExecutable, env })
   // Git owns the repository-relative spelling. Deriving it by comparing
   // filesystem paths breaks when Windows exposes the cwd through an 8.3 short
   // name (RUNNER~1) but Git reports the same root through its long name.
-  const gitPrefix = gitRoot ? gitPrefixFor(project.configDir) : null
+  const gitPrefix = gitRoot ? gitPrefixFor(project.configDir, { gitExecutable, env }) : null
   const rel = gitRoot && gitPrefix !== null ? `${gitPrefix}${LOCAL_STATE_DIR}` : LOCAL_STATE_DIR
   // A directory-only ignore rule such as `.atelier-local/` is not evaluated
   // consistently by Git for an absent directory on every host. Probe a
   // hypothetical child as well: it proves the directory rule before Atelier
   // creates any local state, including on Git for Windows.
   const ignored = gitRoot && gitPrefix !== null
-    ? isIgnoredByGit(gitRoot, `${rel}/.atelier-ignore-probe`) || isIgnoredByGit(gitRoot, `${rel}/`) || isIgnoredByGit(gitRoot, rel)
+    ? isIgnoredByGit(gitRoot, `${rel}/.atelier-ignore-probe`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, `${rel}/`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, rel, { gitExecutable, env })
     : gitRoot === null
   const report = {
     root,
@@ -502,6 +484,19 @@ function extErrors(value, label) {
     .map(([key]) => `${label}.${key} must be an object; ext members are namespaced objects`)
 }
 
+// Hands one namespaced ext member to its structured consumer, uninterpreted.
+// The project validator above deliberately does not look inside a member, so
+// the consumer validates it against its own closed contract and fails closed.
+// `present` separates "no such member" (the consumer's feature is simply not
+// configured) from a member that exists with any value at all, including a
+// malformed one, which the consumer must refuse rather than ignore.
+export function projectExtMember(project, key) {
+  const ext = project?.config?.ext
+  if (ext == null) return { present: false, value: undefined }
+  if (typeof ext !== 'object' || Array.isArray(ext)) return { present: true, value: undefined }
+  return Object.hasOwn(ext, key) ? { present: true, value: ext[key] } : { present: false, value: undefined }
+}
+
 export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {}) {
   const errors = []
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return ['project config must be a JSON object']
@@ -563,6 +558,7 @@ export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {})
   }
   if (alignment.appRepo != null && !firstString(alignment.appRepo)) errors.push('alignment.appRepo must be a non-empty string')
 
+  const repoNames = new Set()
   for (const [index, repo] of (Array.isArray(doc.repos) ? doc.repos : []).entries()) {
     if (!repo || typeof repo !== 'object' || Array.isArray(repo)) {
       errors.push(`repos[${index}] must be an object`)
@@ -571,6 +567,11 @@ export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {})
     errors.push(...unknownKeyErrors(repo, `repos[${index}]`, new Set(['name', 'path', 'readBoundary', 'role', 'kind', 'remote', 'identity', 'aliases', 'required', 'ext'])))
     errors.push(...extErrors(repo.ext, `repos[${index}].ext`))
     if (!firstString(repo.name)) errors.push(`repos[${index}].name is required`)
+    else {
+      const key = repo.name.toLowerCase()
+      if (repoNames.has(key)) errors.push(`repos[${index}].name duplicates another repository name`)
+      repoNames.add(key)
+    }
     if (repo.identity != null) {
       const identity = asObject(repo.identity)
       errors.push(...unknownKeyErrors(identity, `repos[${index}].identity`, new Set(['provider', 'id', 'ext'])))