@6reduk/workspace-pipeline 0.5.0 → 0.7.0

package/src/desired-state/settings.js

@@ -0,0 +1,125 @@
+import {isDeepStrictEqual} from 'node:util';
+import {parseTOML,getStaticTOMLValue} from 'toml-eslint-parser';
+import {fail,parse,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {utf8} from '../source/inventory.js';
+import {readTOMLField,reconcileTOMLFields,AGENT_CONTROL_KEYS} from '../operations/toml-fields.js';
+
+const compat=['skills','rules','agents','mcps','hooks'];
+const named=/^\/(agents|mcp_servers|mcpServers)\/[a-z][a-z0-9_-]{0,99}$/;
+const object=v=>v!==null && typeof v==='object' && !Array.isArray(v);
+
+// Named configuration destinations, never source-provided absolute filenames.
+// No I/O. This module cannot change auth, models, trust, permissions or hooks.
+export function compileDesiredSettings(target,bytes,operations) {
+  if(bytes!==null && (!Buffer.isBuffer(bytes)||bytes.length>MAX_INPUT_BYTES))fail('desired.config-input');
+  if(!Array.isArray(operations)||!operations.length||operations.length>1000)fail('desired.config-operations');
+  const checked=parse(JSON.stringify(operations),'json');
+  const pointers=[];
+  for(const op of checked) {
+    if(op.target!==target || !['set','remove'].includes(op.operation) ||
+        Object.keys(op).some(k=>!['adapter','target','pointer','operation','value'].includes(k)) ||
+        (op.operation==='set')!==Object.hasOwn(op,'value'))fail('desired.config-operation');
+    const p=op.pointer;
+    if(typeof p!=='string')fail('desired.config-scope');
+    let allowed=false;
+    if(target==='codex.workspace')allowed=named.test(p) && /^\/(agents|mcp_servers)\//.test(p) && !AGENT_CONTROL_KEYS.includes(p.split('/')[2]);
+    if(target==='grok.workspace')allowed=named.test(p) && p.startsWith('/mcp_servers/');
+    if(target==='claude.mcp')allowed=named.test(p) && p.startsWith('/mcpServers/');
+    if(target==='claude.workspace')allowed=p==='/enabledMcpjsonServers';
+    if(target==='grok.user')allowed=compat.some(k=>p==='/compat/claude/'+k);
+    if(!allowed || p.split('/').some(k=>['__proto__','prototype','constructor'].includes(k)))fail('desired.config-scope');
+    if(pointers.some(q=>p===q || p.startsWith(q+'/') || q.startsWith(p+'/')))fail('desired.field-overlap');
+    pointers.push(p);
+    if(op.operation==='set') {
+      if(target==='grok.user' && typeof op.value!=='boolean')fail('desired.config-value');
+      if(target==='claude.workspace' && (!Array.isArray(op.value)||op.value.some(v=>typeof v!=='string')||new Set(op.value).size!==op.value.length))fail('desired.config-value');
+      if(named.test(p) && !object(op.value))fail('desired.config-value');
+    }
+  }
+  if(target==='grok.user')return compatSettings(bytes,checked);
+  if(['codex.workspace','grok.workspace'].includes(target)) {
+    const requests=checked.map(op=>{
+      const current=readTOMLField(bytes,op.pointer);
+      return {pointer:op.pointer,present:op.operation==='set',...(op.operation==='set'?{value:op.value}:{}),
+        managedHash:current.present?contractDigest(current.value):null};
+    });
+    // The old codec is reused only as a syntax-preserving editor. The observed
+    // value is deliberately replaceable; its backup/conflict decisions are not
+    // part of the new installation policy and are not returned.
+    const result=reconcileTOMLFields(bytes,requests);
+    return {bytes:result.bytes,changed:!result.bytes.equals(bytes??Buffer.alloc(0))};
+  }
+  const current=bytes===null?{}:parse(utf8(bytes),'json');
+  if(!object(current))fail('desired.config-shape');
+  const result=structuredClone(current);
+  for(const op of checked) {
+    const parts=op.pointer.slice(1).split('/');let parent=result;
+    for(const key of parts.slice(0,-1)) {
+      if(!Object.hasOwn(parent,key)) {
+        if(op.operation==='remove'){parent=null;break;}
+        parent[key]={};
+      }
+      if(!object(parent[key]))fail('desired.config-ancestor');
+      parent=parent[key];
+    }
+    if(parent!==null) {
+      if(op.operation==='remove')delete parent[parts.at(-1)];
+      else parent[parts.at(-1)]=op.value;
+    }
+  }
+  if(JSON.stringify(result)===JSON.stringify(current))return {bytes:bytes??Buffer.from('{}\n'),changed:false};
+  return {bytes:Buffer.from(JSON.stringify(result,null,2)+'\n'),changed:true};
+}
+
+function compatSettings(bytes,operations) {
+  const text=bytes===null?'':utf8(bytes);
+  let ast,value;try{ast=parseTOML(text,{tomlVersion:'1.0'});value=getStaticTOMLValue(ast);}catch{fail('desired.config-syntax');}
+  if(value.compat!==undefined && !object(value.compat))fail('desired.config-ancestor');
+  if(value.compat?.claude!==undefined && !object(value.compat.claude))fail('desired.config-ancestor');
+  const expected=structuredClone(value),edits=[],seen=new Set(),nl=text.includes('\r\n')?'\r\n':'\n';
+  const changes=operations.filter(op=>{
+    const k=op.pointer.split('/').at(-1),exists=Object.hasOwn(value.compat?.claude??{},k);
+    if(op.operation==='remove'){if(exists)delete expected.compat.claude[k];return exists;}
+    expected.compat??={};expected.compat.claude??={};expected.compat.claude[k]=op.value;
+    return !exists || value.compat.claude[k]!==op.value;
+  });
+  if(!changes.length)return {bytes:bytes??Buffer.alloc(0),changed:false};
+  function pair(node,base) {
+    const keys=[...base,...node.key.keys.map(k=>k.name??k.value)];
+    for(const op of changes) {
+      const wanted=op.pointer.slice(1).split('/');
+      if(keys.length<wanted.length && keys.every((k,i)=>k===wanted[i]))fail('desired.config-inline-ancestor');
+      if(keys.length===wanted.length && keys.every((k,i)=>k===wanted[i])) {
+        seen.add(op.pointer);
+        edits.push(op.operation==='remove'?[...node.range,'']:[...node.value.range,String(op.value)]);
+      }
+    }
+  }
+  let table=null,parentTable=null;
+  for(const node of ast.body[0].body) {
+    if(node.type==='TOMLKeyValue')pair(node,[]);
+    else if(node.type==='TOMLTable') {
+      if(node.resolvedKey.join('.')==='compat.claude')table=node;
+      if(node.resolvedKey.length===1 && node.resolvedKey[0]==='compat')parentTable=node;
+      for(const child of node.body)pair(child,node.resolvedKey);
+    }
+  }
+  const additions=changes.filter(op=>op.operation==='set'&&!seen.has(op.pointer));
+  if(additions.length) {
+    const selected=table??parentTable;
+    if(selected) {
+      if(selected.kind!=='standard')fail('desired.config-ancestor');
+      const end=text.indexOf('\n',selected.key.range[1]),pos=end<0?text.length:end+1;
+      edits.push([pos,pos,(end<0?nl:'')+additions.map(op=>(table?'':'claude.')+
+        op.pointer.split('/').at(-1)+' = '+String(op.value)+nl).join('')]);
+    } else edits.push([0,0,additions.map(op=>op.pointer.slice(1).split('/').join('.')+' = '+String(op.value)+nl).join('')]);
+  }
+  let output=text;
+  for(const [start,end,replacement] of edits.sort((a,b)=>b[0]-a[0]))output=output.slice(0,start)+replacement+output.slice(end);
+  let after;try{after=getStaticTOMLValue(parseTOML(output,{tomlVersion:'1.0'}));}catch{fail('desired.config-postcondition');}
+  function normalize(v){if(v.compat?.claude && !Object.keys(v.compat.claude).length)delete v.compat.claude;if(v.compat && !Object.keys(v.compat).length)delete v.compat;return v;}
+  if(!isDeepStrictEqual(normalize(after),normalize(expected)))fail('desired.config-postcondition');
+  const bom=bytes?.subarray(0,3).equals(Buffer.from([0xef,0xbb,0xbf]));
+  return {bytes:Buffer.from((bom?'\uFEFF':'')+output),changed:true};
+}

package/src/desired-state/source.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import {tmpdir} from 'node:os';
+import {parse,fail} from '../contracts/parse.js';
+import {validateStructure} from '../contracts/validate.js';
+import {validateLayoutReferences} from '../contracts/semantic.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {assertUnreserved,overlaps} from '../workspace/reserved.js';
+import {acquire} from '../source/git.js';
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+
+export function parseDesiredWorkspace(text) {
+  const value=parse(text,'json');
+  if(value.schemaVersion!==2 || Object.keys(value).some(k=>!['schemaVersion','pipeline','adapters','layout'].includes(k)) ||
+      !Array.isArray(value.adapters)||!value.adapters.length || new Set(value.adapters).size!==value.adapters.length ||
+      value.adapters.some(id=>typeof id!=='string'||!/^[a-z][a-z0-9-]{0,62}$/.test(id)))fail('desired.workspace-schema');
+  // Reuse the established Git/layout data types, not old provider installation.
+  validateStructure('workspace',{schemaVersion:1,pipeline:value.pipeline,providers:['codex'],layout:value.layout});
+  validateLayoutReferences(value.layout);
+  const repositories=Object.values(value.layout.repositories).map(repo=>repo.path);
+  for(const name of repositories){assertUnreserved(name);if(overlaps(name,'workspace.json'))fail('layout.reserved');}
+  for(let i=0;i<repositories.length;i++)for(let j=0;j<i;j++)
+    if(overlaps(repositories[i],repositories[j]))fail('desired.repository-overlap');
+  return value;
+}
+
+// No writes to workspace, no harness execution. Acquired Git objects/snapshot
+// are temporary source material, never backups of installed user contents.
+export async function prepareDesiredWorkspace(workspace,text,{manifestBase,tempRoot=tmpdir(),network=false}={}) {
+  workspace=absoluteRoot(workspace);tempRoot=absoluteRoot(tempRoot);
+  const rel=path.relative(workspace,tempRoot);
+  if(!rel || (!rel.startsWith('..'+path.sep)&&rel!=='..'&&!path.isAbsolute(rel)))fail('desired.preparation-location');
+  const descriptor=parseDesiredWorkspace(text);
+  const acquired=await acquire(descriptor.pipeline,{manifestBase:manifestBase??workspace,tempRoot,network,packageFormat:'desired'});
+  const protectedPaths=Object.values(descriptor.layout.repositories).map(repo=>repo.path);
+  const manifest=JSON.stringify(acquired.manifest);
+  compileDesiredManifest(manifest,{selected:descriptor.adapters,protectedPaths});
+  const binding={source:acquired.source,commit:acquired.commit,digest:acquired.digest,layout:descriptor.layout};
+  return {input:{workspace,manifest,selected:descriptor.adapters,protectedPaths,source:acquired.files,binding},
+    provenance:{source:acquired.source,commit:acquired.commit,digest:acquired.digest},
+    preparation:{objects:acquired.preparation,snapshot:acquired.snapshotPath},descriptor};
+}

package/src/operations/lock.js

@@ -28,8 +28,9 @@ export async function assertLockHeld(lock) {
 // Cooperative workspace-local exclusion. Existing/stale locks are never stolen.
 // This does not prevent an editor or hostile process from replacing filesystem
 // entries; S5 apply must independently recheck each subject before every write.
-export async function acquireWorkspaceLock(workspace,{repositoryOperation,migrationOperation}={}) {
+export async function acquireWorkspaceLock(workspace,{repositoryOperation,migrationOperation,purpose}={}) {
   workspace = absoluteRoot(workspace);
+  if(purpose!==undefined && (purpose!=='desired-state'||repositoryOperation!==undefined||migrationOperation!==undefined))fail('lock.purpose');
   if(repositoryOperation!==undefined&&migrationOperation!==undefined)fail('lock.capability-conflict');
   const guard=async()=>{
     if(migrationOperation!==undefined){
@@ -57,7 +58,7 @@ export async function acquireWorkspaceLock(workspace,{repositoryOperation,migrat
     // Failure after mkdir deliberately leaves a non-acquirable lock for review.
     await inspectDirectory(directory);
     const owner = { schemaVersion: 1, workspace, token: randomUUID(), pid: process.pid,
-      host: hostname(), createdAt: new Date().toISOString() };
+      host: hostname(), createdAt: new Date().toISOString(),...(purpose?{purpose}:{}) };
     const bytes = Buffer.from(JSON.stringify(owner) + '\n');
     const handle = await open(ownerFile, 'wx', 0o600);
     try { await handle.writeFile(bytes); await handle.sync(); }

package/src/source/desired-package.js

@@ -0,0 +1,33 @@
+import {checkEntries,LIMITS,cap,utf8,sha256} from './inventory.js';
+import {parse,fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+import {materializeDesiredFiles} from '../desired-state/inventory.js';
+
+// Git already identifies the immutable tree and blobs. V2 computes its source
+// inventory instead of requiring a second hand-maintained installation plan.
+export async function verifyDesiredPackage(entries,readBlob) {
+  checkEntries(entries);
+  const manifests=entries.filter(e=>['pipeline.json','pipeline.yaml','pipeline.yml'].includes(e.path));
+  if(manifests.length!==1)fail('source.manifest');
+  cap(manifests[0].size,LIMITS.manifest,'source.metadata-size');
+  const files=new Map();
+  for(const entry of entries) {
+    const bytes=await readBlob(entry);
+    if(!Buffer.isBuffer(bytes)||bytes.length!==entry.size)fail('source.blob-size');
+    if(bytes.subarray(0,200).toString('ascii').startsWith('version https://git-lfs.github.com/spec/v1'))fail('source.lfs');
+    files.set(entry.path,bytes);
+  }
+  const manifestPath=manifests[0].path;
+  const manifest=parse(utf8(files.get(manifestPath)),manifestPath.endsWith('.json')?'json':'yaml');
+  // Compile each delivery separately: different alternatives may intentionally
+  // serve the same provider; selecting both later still rejects collisions.
+  if(!manifest.adapters || typeof manifest.adapters!=='object')fail('desired.schema');
+  const serialized=JSON.stringify(manifest);
+  for(const id of Object.keys(manifest.adapters))
+    materializeDesiredFiles(compileDesiredManifest(serialized,{selected:[id]}),files);
+  if(!Object.keys(manifest.adapters).length)fail('desired.schema');
+  const fileHashes=Object.fromEntries([...files].map(([name,bytes])=>[name,sha256(bytes)]));
+  const digest=contractDigest(fileHashes);
+  return {manifest,manifestPath,files,fileHashes,digest,inventoryDigest:digest};
+}

package/src/source/git.js

@@ -8,6 +8,7 @@ import { validateStructure } from '../contracts/validate.js';
 import { portablePath } from '../contracts/semantic.js';
 import { LIMITS, cap, utf8, verifyPackage } from './inventory.js';
 import { materialize } from './snapshot.js';
+import {verifyDesiredPackage} from './desired-package.js';
 import { repositoryBudget } from './repository-budget.js';
 
 const oid = value => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
@@ -259,7 +260,8 @@ export async function acquireRemoteRepository(source, { tempRoot, network = fals
   }
 }
 
-export async function acquire(source, { manifestBase, tempRoot = tmpdir(), network = false, packLimit = LIMITS.pack } = {}) {
+export async function acquire(source, { manifestBase, tempRoot = tmpdir(), network = false, packLimit = LIMITS.pack, packageFormat='legacy' } = {}) {
+  if(!['legacy','desired'].includes(packageFormat))fail('source.package-format');
   validateSource(source);
   cap(packLimit, LIMITS.pack, 'source.pack-limit');
   if (!path.isAbsolute(manifestBase ?? '')) fail('source.manifest-base');
@@ -284,7 +286,8 @@ export async function acquire(source, { manifestBase, tempRoot = tmpdir(), netwo
   const rootType = await runGit(repo, ['cat-file', '-t', treeish], options);
   if (utf8(rootType.bytes).trim() !== 'tree') fail('source.package-root');
   const listing = await runGit(repo, ['ls-tree', '-r', '-l', '-z', '--full-tree', treeish], options);
-  const verified = await verifyPackage(parseListing(listing.bytes), async entry => {
+  const verify=packageFormat==='desired'?verifyDesiredPackage:verifyPackage;
+  const verified = await verify(parseListing(listing.bytes), async entry => {
     const r = await runGit(repo, ['cat-file', 'blob', entry.oid], { ...options, outputLimit: LIMITS.blob });
     return r.bytes;
   });
@@ -293,7 +296,8 @@ export async function acquire(source, { manifestBase, tempRoot = tmpdir(), netwo
   if (performance.now() > deadline) fail('source.timeout');
   return { source: structuredClone(source), resolvedSource, commit, preparation, snapshotPath,
     manifest: verified.manifest, inventoryDigest: verified.inventoryDigest,
-    digest: verified.digest, fileHashes: verified.fileHashes, runtime: 'not-run' };
+    digest: verified.digest, fileHashes: verified.fileHashes, runtime: 'not-run',
+    ...(packageFormat==='desired'?{files:verified.files}: {}) };
   } catch (cause) {
     const error = cause instanceof ContractError ? cause : new ContractError('source.io');
     if (preparation) error.preparation = preparation;