@6reduk/workspace-pipeline 0.3.0 → 0.4.0

package/README.md

@@ -52,7 +52,9 @@ npm run pack:check
 npm run test:packed:providers
 ```
 
-The executable name is `workspace-pipeline`. Doctor prints JSON: exit 0 means
+The executable name is `workspace-pipeline`. Output is readable by default;
+add `--json` for complete machine output. Use `--json` when saving any preview
+for a later apply, even when redirecting stdout to a file. Doctor exit 0 means
 observed configuration ready, 1 means not ready/incomplete, 2 means invocation or
 transport error. Unsupported commands exit with code 2. On Windows use an absolute
 path such as `C:\Projects\my-workspace`. See [doctor](docs/doctor.md) for limits.

package/docs/doctor.md

@@ -5,7 +5,8 @@ The public CLI exposes it read-only:
 
 `workspace-pipeline doctor --workspace <absolute-path> [--recovery <relative-record>] [--json]`
 
-Output is JSON even without --json. Exit 0 means configuration ready, 1 not ready
+Output is a readable status summary by default. `--json` returns the complete
+machine report (including every target/hash). Exit 0 means configuration ready, 1 not ready
 or incomplete, 2 invalid invocation or output failure. This is not an install command.
 
 `ready` means observed **configuration readiness**, never a running harness,

package/docs/launch.md

@@ -1,5 +1,19 @@
 # Scoped Grok launch (S11 development)
 
+## Configuration limitation (checked 2026-09-23)
+
+The desired UX is ordinary `grok` with workspace-local compatibility settings,
+not a mandatory launcher. This is currently blocked by the harness: installed
+Grok 1.0.40 and the upstream configuration reference list only `mcp_servers`,
+`plugins`, `permission`, and `mcp.max_output_bytes` as project config inputs.
+`compat.claude` is not among them. Writing five false values locally must not be
+represented as working import suppression. The CLI does not change user-wide
+compat settings as a substitute. The legacy launch route below remains an
+explicit workaround, not the approved long-term configuration model.
+
+Source: [Grok configuration reference](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/26-config-reference.md),
+configuration layers and `compat` fields. No new live-isolation claim is made.
+
 This command starts Grok from an already configured workspace with five Claude
 compatibility switches set to false in the child environment: skills, rules, agents,
 MCP and hooks. It does not install a pipeline. Configure Grok using the ordinary

package/docs/lifecycle-cli.md

@@ -23,7 +23,8 @@ workspace-pipeline setup --workspace <absolute-wrapper> --apply --preview <absol
 workspace-pipeline update --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
 ```
 
-Preview returns the complete prepared JSON on stdout. It may acquire a Git
+Preview displays a human-readable summary by default. Add `--json` to return
+the complete prepared JSON on stdout for saving and subsequent apply. It may acquire a Git
 source into temporary storage outside the wrapper, but does not write provider
 configuration. Network acquisition requires explicit `--network`. When manifest
 is omitted, setup uses the standard workspace manifest; update uses the recorded
@@ -68,7 +69,7 @@ restoration; empty reset must be explicitly selected.
 
 ## Output and failures
 
-- stdout: one prepared JSON or operation result.
+- stdout: readable result by default; with `--json`, one complete prepared JSON or operation result.
 - stderr during apply: structured journal/recovery locations and operation events.
 - exit 0: preview created, or observed configuration ready with successful lock
   release and reporting. It never certifies harness/MCP runtime.

package/docs/rebind.md

@@ -15,8 +15,8 @@ The following PowerShell example uses illustrative absolute paths; replace them.
 Use a private directory for preview files: they can contain configuration values.
 
 ```powershell
-workspace-pipeline rebind --workspace 'C:\Work\Game' --manifest 'C:\Work\Game\workspace.json' > 'C:\Private\rebind.json'
-workspace-pipeline update --workspace 'C:\Work\Game' --accept-rebind 'C:\Private\rebind.json' > 'C:\Private\update.json'
+workspace-pipeline rebind --workspace 'C:\Work\Game' --manifest 'C:\Work\Game\workspace.json' --json > 'C:\Private\rebind.json'
+workspace-pipeline update --workspace 'C:\Work\Game' --accept-rebind 'C:\Private\rebind.json' --json > 'C:\Private\update.json'
 workspace-pipeline update --workspace 'C:\Work\Game' --apply --preview 'C:\Private\update.json'
 workspace-pipeline doctor --workspace 'C:\Work\Game'
 ```

package/docs/repositories.md

@@ -27,7 +27,7 @@ commit, not uncommitted files of its source.
 workspace-pipeline wrap --workspace "C:\Work\GameWorkspace" --manifest "C:\Work\workspace.json" --choices "C:\Work\choices.json"
 ```
 
-Save the exact JSON stdout as UTF-8 `preview.json` outside the affected repository
+Use `--json` and save the exact JSON stdout as UTF-8 `preview.json` outside the affected repository
 and wrapper. Read its operations and blockers. Preview may acquire a temporary
 Git snapshot, but does not perform repository effects. Remote access is explicit
 with `--network`; local Git does not need that flag. Do not put credentials into

package/docs/repository-recovery.md

@@ -39,8 +39,8 @@ delete pending markers or lock directories to make `doctor` report success.
 
 `no-pending-marker` means exactly that; it does not certify historical completion,
 provider readiness or game runtime. A blocker means further recovery is needed;
-this command never grants itself authority to resolve it. `--json` is redundant
-but accepted because JSON is already the default output.
+this command never grants itself authority to resolve it. Add `--json` for
+machine-readable output and whenever saving a preview for apply.
 
 ## Local recovery ownership
 

package/docs/reset.md

@@ -13,7 +13,7 @@ Close running harnesses/configuration editors. Keep preview files private: they
 contain before/after bytes, potentially including MCP credentials.
 
 ```powershell
-workspace-pipeline reset --workspace 'C:\Work\Game' --all > 'C:\Private\reset.json'
+workspace-pipeline reset --workspace 'C:\Work\Game' --all --json > 'C:\Private\reset.json'
 # Check $LASTEXITCODE and review reset.scope, reset.backup and preview.plan.targets.
 workspace-pipeline reset --workspace 'C:\Work\Game' --apply --preview 'C:\Private\reset.json'
 workspace-pipeline doctor --workspace 'C:\Work\Game'

package/docs/retention.md

@@ -75,7 +75,8 @@ check has cost proportional to selected files times retained records, bounded by
 scan limits and the user deletion cap. It is not a linear-cost guarantee or an
 OS-wide defense against hostile concurrent filesystem writers.
 
-Progress is emitted as JSON on stderr; final JSON is on stdout. The receipt path
+With `--json`, progress is emitted as JSON on stderr and final JSON on stdout;
+otherwise both are formatted for reading. Save apply previews using `--json`. The receipt path
 is under `.pipeline/cleanup/<run-id>.json`. Receipts record selected file hashes,
 confirmed deletions, reclaimed bytes, current intent and failures. These receipts
 describe attempted/deleted paths; unlike operational recovery records, they are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6reduk/workspace-pipeline",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Workspace-local Git pipeline configuration dispatcher",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {runCli} from './commands/dispatch.js';
 import {providerRegistry} from './providers/registry.js';
+import {outputWriter} from './commands/output.js';
 const write=stream=>text=>new Promise((resolve,reject)=>stream.write(text,error=>error?reject(error):resolve()));
 // Prevent an unhandled pipe error; write callbacks report delivery failures.
 process.stdout.on('error',()=>{});process.stderr.on('error',()=>{});
-process.exitCode=await runCli(process.argv.slice(2),{stdout:write(process.stdout),stderr:write(process.stderr),registry:providerRegistry});
+const args=process.argv.slice(2),json=args.includes('--json');
+process.exitCode=await runCli(args,{stdout:outputWriter(write(process.stdout),json),stderr:outputWriter(write(process.stderr),json),registry:providerRegistry});

package/src/commands/dispatch.js

@@ -62,7 +62,9 @@ Preview stages Git externally; inspect is read-only/offline. JSON can contain
 private config bytes. Only explicit apply writes or clears a validated pending marker.
 Apply requires the saved installer-bound envelope and accepts no source overrides.
 
-Doctor is read-only and prints JSON. Exit 0 means observed configuration ready;
+Output is human-readable by default; use --json for complete machine output.
+Save previews for apply with --json (including when redirecting stdout).
+Doctor is read-only. Exit 0 means observed configuration ready;
 exit 1 means not ready/incomplete; exit 2 means invalid invocation or unavailable command.
 Runtime, MCP/harness discovery and provider compatibility are NOT verified.
 No source access, automatic repair or lock removal. Read-only/configuration commands never clean history.
@@ -134,14 +136,14 @@ logs clean --repositories --workspace <absolute-directory> --max-age-days <N>
 Apply with --repositories --apply --preview <file>; this is a separate cleanup
 domain, never an implicit increase of the ordinary journal deletion budget.
 Execution inputs are retained privately under .pipeline/repository-inputs;
---json is optional because JSON is the default.
+--json selects the complete machine-readable result without presentation changes.
 This package is not ready to replace an existing installation.`;
 
 // Parse strictly before any filesystem observation. Never echo unknown arguments
 // (which can contain credentials). Output transport is trusted CLI code.
 export function parseCommand(args) {
   if(!Array.isArray(args) || args.some(a=>typeof a!=='string')) fail('cli.arguments');
-  if(args.length===0 || (args.length===1 && ['--help','-h'].includes(args[0])))return {command:'help'};
+  if(args.length===0 || (['--help','-h'].includes(args[0]) && (args.length===1 || (args.length===2 && args[1]==='--json'))))return {command:'help'};
   if(args[0]==='launch')return parseLaunch(args);
   if(args[0]==='rebind')return parseRebind(args);
   if(args[0]==='reset')return parseReset(args);

package/src/commands/launch.js

@@ -11,8 +11,9 @@ export function parseLaunch(args) {
   const result = { command: 'launch', provider: 'grok', execute: false, inspect: false }, seen = new Set();
   for (let i = 2; i < args.length; i++) {
     const flag = args[i];
-    if (!['--workspace', '--executable', '--execute', '--inspect'].includes(flag) || seen.has(flag)) fail('cli.arguments');
+    if (!['--workspace', '--executable', '--execute', '--inspect', '--json'].includes(flag) || seen.has(flag)) fail('cli.arguments');
     seen.add(flag);
+    if (flag === '--json') continue;
     if (flag === '--execute') { result.execute = true; continue; }
     if (flag === '--inspect') { result.inspect = true; continue; }
     const value = args[++i];

package/src/commands/output.js

@@ -0,0 +1,46 @@
+// Presentation boundary only: internal command results and saved JSON contracts
+// remain unchanged. Never infer success from the shape of a rendered result.
+const safe = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const privateKey = /bytes|base64|content|secret|token|password/i;
+
+export function formatResult(value) {
+  if (value && typeof value.ready === 'boolean' && Array.isArray(value.diagnostics)) {
+    const lines = ['Workspace Pipeline — doctor', '',
+      `Workspace: ${safe(value.workspace ?? '(not reported)')}`,
+      `Status: ${value.ready ? 'READY' : 'NOT READY'} (${safe(value.status ?? 'unknown')})`];
+    if (value.pipeline) lines.push(`Pipeline: ${safe(value.pipeline.id)} @ ${safe(value.pipeline.version)}`,
+      `Providers: ${value.pipeline.providers.map(safe).join(', ')}`);
+    for (const key of ['configuration', 'transactionEvidence']) if (value[key] !== undefined) lines.push(`${key}: ${safe(value[key])}`);
+    lines.push('', `Diagnostics: ${value.diagnostics.length}`);
+    for (const item of value.diagnostics) lines.push(`  - ${safe(item.code)}${item.subject ? ': ' + safe(item.subject) : ''}${item.pointer ? ' ' + safe(item.pointer) : ''}`);
+    lines.push('', 'Runtime / model-visible skills / MCP: not verified by doctor.',
+      'Full report: repeat with --json.');
+    return lines.join('\n') + '\n';
+  }
+  const lines = ['Workspace Pipeline', ''];
+  function render(node, indent = '', depth = 0) {
+    if (node === null || typeof node !== 'object') { lines.push(indent + safe(node)); return; }
+    if (depth > 5) { lines.push(indent + '(details omitted; use --json)'); return; }
+    const entries = Object.entries(node);
+    for (const [key, item] of entries.slice(0, 40)) {
+      const label = indent + safe(key) + ':';
+      if (privateKey.test(key)) lines.push(label + ' (private payload; use --json)');
+      else if (item !== null && typeof item === 'object') { lines.push(label); render(item, indent + '  ', depth + 1); }
+      else { const text=safe(item); lines.push(label + ' ' + (text.length>500?text.slice(0,500)+' (truncated; use --json)':text)); }
+    }
+    if (entries.length > 40) lines.push(indent + `(${entries.length - 40} more entries; use --json)`);
+  }
+  render(value);
+  lines.push('', 'For complete machine output or a saved apply preview, repeat with --json.',
+    'This display is not an apply preview. JSON may contain private configuration.');
+  return lines.join('\n') + '\n';
+}
+
+export function outputWriter(write, json) {
+  if (json) return write;
+  return text => {
+    let value;
+    try { value = JSON.parse(text); } catch { return write(text); }
+    return write(formatResult(value));
+  };
+}

package/src/commands/rebind.js

@@ -9,8 +9,9 @@ export function parseRebind(args) {
   const result={command:'rebind'},seen=new Set();
   for(let i=1;i<args.length;i++) {
     const flag=args[i];
-    if(!['--workspace','--manifest'].includes(flag) || seen.has(flag))fail('cli.arguments');
+    if(!['--workspace','--manifest','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
+    if(flag==='--json')continue;
     const value=args[++i];if(!value || value.startsWith('--'))fail('cli.arguments');
     result[flag==='--workspace'?'workspace':'manifestPath']=absoluteRoot(value);
   }

package/src/commands/reset.js

@@ -11,8 +11,9 @@ export function parseReset(args){
   const result={command:'reset'},seen=new Set();
   for(let i=1;i<args.length;i++){
     const flag=args[i];
-    if(!['--workspace','--to','--all','--providers','--bundles','--apply','--preview'].includes(flag) || seen.has(flag))fail('cli.arguments');
+    if(!['--workspace','--to','--all','--providers','--bundles','--apply','--preview','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
+    if(flag==='--json')continue;
     if(flag==='--apply'){result.apply=true;continue;}
     if(flag==='--all'){(result.options??={}).all=true;continue;}
     const value=args[++i];if(!value || value.startsWith('--'))fail('cli.arguments');