@kitschpatrol/shared-config 8.11.0 → 8.12.0

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{cosmiconfig as e}from"cosmiconfig";import{TypeScriptLoader as t}from"cosmiconfig-typescript-loader";import{execa as n}from"execa";import r from"fs-extra";import i,{constants as a}from"node:fs";import{availableParallelism as o}from"node:os";import s from"node:path";import{PassThrough as c,Transform as l}from"node:stream";import{packageUp as u,packageUpSync as d}from"package-up";import f from"yargs";import{hideBin as p}from"yargs/helpers";import m from"picocolors";import{stripVTControlCharacters as h}from"node:util";import g from"@pinojs/json-colorizer";import ee from"decircular";import te from"deepmerge";import _ from"json-stringify-pretty-compact";import{findWorkspaces as v,findWorkspacesRoot as ne}from"find-workspaces";import y,{access as re}from"node:fs/promises";import{getDefaultConfigLoader as b,resolveConfigFileImports as ie}from"cspell-lib";import{fileURLToPath as x}from"node:url";import{createReaderWriter as ae}from"cspell-config-lib";import{loadFile as oe,writeFile as se}from"magicast";import{getDefaultExportOptions as ce}from"magicast/helpers";import{lint as le}from"cspell";import"deepmerge-ts";import{loadConfig as ue}from"mdat";import{globby as de}from"globby";import S,{gt as fe,minVersion as pe}from"semver";import{readWantedLockfile as me}from"@pnpm/lockfile.fs";import he from"stylelint";var ge=`8.11.0`;const _e=[`json`,`machine`,`native`],ve=_e;function ye(e){return typeof e==`string`&&_e.includes(e)}function C(){let e=process.env.KSC_FORMAT;return ye(e)?e:`native`}function be(){let{argv:e}=process;for(let[t,n]of e.entries()){let r;n===`--format`?r=e[t+1]:n.startsWith(`--format=`)&&(r=n.slice(9)),ye(r)&&(process.env.KSC_FORMAT=r)}}function xe(){let{env:e}=process;return e.NO_COLOR!==void 0&&e.NO_COLOR!==``?!1:e.FORCE_COLOR===void 0?e.TERM!==`dumb`&&void 0:e.FORCE_COLOR!==`0`&&e.FORCE_COLOR!==`false`}function w(e,{ciColor:t=!0}={}){return xe()??(e.isTTY===!0||t&&!!process.env.CI)}function Se(){return C()===`json`?process.stderr:process.stdout}function T(){return C()===`machine`?m.createColors(!1):m.createColors(w(Se()))}function Ce(e){if(!e)return{FORCE_COLOR:`0`,NO_COLOR:`1`};let t=process.env.FORCE_COLOR;return t===void 0||t===``?{FORCE_COLOR:`1`}:{}}function E(e,t){let n=s.isAbsolute(e)?e:s.resolve(t,e),r=s.relative(process.cwd(),n);return r===``?`.`:r}const we=/\s*\n\s*/gv,Te=/\r?\n/v;function Ee(e){let t=e.message.replaceAll(we,` `),n=e.rule===void 0?e.tool:`${e.tool}/${e.rule}`;return e.file===void 0?`${e.severity}: ${t} [${n}]`:`${e.file}:${e.line??1}:${e.column??1}: ${e.severity}: ${t} [${n}]`}function De(e,t){let n=(e.file??`￿`).localeCompare(t.file??`￿`);if(n!==0)return n;let r=(e.line??0)-(t.line??0);return r===0?(e.column??0)-(t.column??0):r}function Oe(e,t){let n=t.toSorted(De);return{cwd:process.cwd(),diagnostics:n,success:e.every(e=>e.exitCode===0),summary:{errors:n.filter(e=>e.severity===`error`).length,infos:n.filter(e=>e.severity===`info`).length,warnings:n.filter(e=>e.severity===`warning`).length},tools:e,version:1}}function D(e){return h(e).split(Te).map(e=>e.trimEnd()).filter(e=>e.trim().length>0)}function ke(e){return e instanceof Error&&`exitCode`in e&&typeof e.exitCode==`number`}function O(e){return w(process.stdout,{ciColor:!1})?je(e):Ae(e)}function Ae(e){return _(ee(e),{indent:2,replacer(e,t){return typeof t==`function`?t.name:t}})}function je(e){return g(Ae(e),{colors:{BRACKET:`gray`}})}const Me=(e,t,n)=>{let r=[...e];for(let[i,a]of t.entries())r[i]===void 0?r[i]=n.cloneUnlessOtherwiseSpecified(a,n):n.isMergeableObject(a)?r[i]=k(e[i],a,n):e.includes(a)||r.push(a);return r};function k(e,t,n={arrayMerge:Me}){return te(e,t,n)}function Ne(e){let{tasks:t}=e;return Array.isArray(t)?t:[]}function Pe(e,t){let n=[...Ne(e)];for(let e of Ne(t)){let t=n.findIndex(t=>t.label!==void 0&&t.label===e.label);t===-1?n.push(e):n[t]=e}return{...e,...t,tasks:n}}function Fe(e,t){return e.startsWith(t+s.sep)}function A(){let e=j(),t=/* @__PURE__ */ new Set([e]),n=v();if(n!==null)for(let r of n){let n=s.resolve(r.location);Fe(n,e)&&t.add(n)}return[...t]}function j(){let e=d();if(e===void 0)throw Error(`No package.json found.`);return s.dirname(e)}function Ie(){return ne()!==null}function M(){let e=ne();return e===null?j():s.resolve(e.location)}function Le(e){let t=s.join(M(),e);return r.existsSync(t)?t:void 0}function Re(e){if(e===`workspace-root`)return M();if(e===`package-dir`)return j();if(typeof e==`string`){if(!r.pathExistsSync(e))throw Error(`Custom cwd directory does not exist: ${e}`);return e}return process.cwd()}async function ze(e,t){try{let{default:n}=await import(`prettier`),r=await n.resolveConfig(e),i=await n.format(t,{filepath:e,...r});await y.writeFile(e,i,`utf8`)}catch{console.warn(`Skipped formatting ${e} since Prettier is not installed.`)}}async function N(e){try{await ze(e,await y.readFile(e,`utf8`))}catch{}}const Be=/\r?\n/v;function Ve(e){let t=``,n=t=>t.filter(t=>{let n=h(t);return n.trim()!==``&&!e(n)}).map(e=>`${e}\n`).join(``);return new l({flush(e){e(void 0,n([t]))},transform(e,r,i){let a=(t+e.toString()).split(Be);t=a.pop()??``,i(void 0,n(a))}})}function P(e,t){let n=C()===`native`?e:void 0,r=n===void 0||n===``?``:t===void 0?n:T()[t](n),i=``,a=e=>e.filter(e=>e.trim().length>0).map(e=>r===``?`${e}\n`:`${r} ${e}\n`).join(``);return new l({flush(e){e(void 0,a([i]))},transform(e,t,n){let r=(i+e.toString()).split(Be);i=r.pop()??``,n(void 0,a(r))}})}async function He(e){let t=[];return new Promise((n,r)=>{e.on(`data`,e=>{t.push(e)}),e.on(`error`,e=>{r(e)}),e.on(`end`,()=>{n(Buffer.concat(t).toString(`utf8`))})})}function Ue(e){return e.replaceAll(/[A-Z\u{C0}-\u{D6}\u{D8}-\u{DE}]/gv,e=>`-`+e.toLowerCase())}function F(e,t){return t===1?e:e+`s`}async function I(e){return typeof e==`function`?e():e}async function We(e,t,n,r,i){let a;if(r.logPrefix===void 0)a=e;else{let t=P(r.logPrefix,r.logColor);t.pipe(e),a=t}i&&a.write(T().bold(`Running: "${r.name}() with Positional arguments: ${String(t)} and Option flags: ${String(n)}"`)+`
+import{cosmiconfig as e}from"cosmiconfig";import{TypeScriptLoader as t}from"cosmiconfig-typescript-loader";import{execa as n}from"execa";import r from"fs-extra";import i,{constants as a}from"node:fs";import{availableParallelism as o}from"node:os";import s from"node:path";import{PassThrough as c,Transform as l}from"node:stream";import{packageUp as u,packageUpSync as d}from"package-up";import f from"yargs";import{hideBin as p}from"yargs/helpers";import m from"picocolors";import{stripVTControlCharacters as h}from"node:util";import g from"@pinojs/json-colorizer";import ee from"decircular";import te from"deepmerge";import _ from"json-stringify-pretty-compact";import{findWorkspaces as v,findWorkspacesRoot as ne}from"find-workspaces";import y,{access as re}from"node:fs/promises";import{getDefaultConfigLoader as b,resolveConfigFileImports as ie}from"cspell-lib";import{fileURLToPath as x}from"node:url";import{createReaderWriter as ae}from"cspell-config-lib";import{loadFile as oe,writeFile as se}from"magicast";import{getDefaultExportOptions as ce}from"magicast/helpers";import{lint as le}from"cspell";import"deepmerge-ts";import{loadConfig as ue}from"mdat";import{globby as de}from"globby";import S,{gt as fe,minVersion as pe}from"semver";import{readWantedLockfile as me}from"@pnpm/lockfile.fs";import he from"stylelint";var ge=`8.12.0`;const _e=[`json`,`machine`,`native`],ve=_e;function ye(e){return typeof e==`string`&&_e.includes(e)}function C(){let e=process.env.KSC_FORMAT;return ye(e)?e:`native`}function be(){let{argv:e}=process;for(let[t,n]of e.entries()){let r;n===`--format`?r=e[t+1]:n.startsWith(`--format=`)&&(r=n.slice(9)),ye(r)&&(process.env.KSC_FORMAT=r)}}function xe(){let{env:e}=process;return e.NO_COLOR!==void 0&&e.NO_COLOR!==``?!1:e.FORCE_COLOR===void 0?e.TERM!==`dumb`&&void 0:e.FORCE_COLOR!==`0`&&e.FORCE_COLOR!==`false`}function w(e,{ciColor:t=!0}={}){return xe()??(e.isTTY===!0||t&&!!process.env.CI)}function Se(){return C()===`json`?process.stderr:process.stdout}function T(){return C()===`machine`?m.createColors(!1):m.createColors(w(Se()))}function Ce(e){if(!e)return{FORCE_COLOR:`0`,NO_COLOR:`1`};let t=process.env.FORCE_COLOR;return t===void 0||t===``?{FORCE_COLOR:`1`}:{}}function E(e,t){let n=s.isAbsolute(e)?e:s.resolve(t,e),r=s.relative(process.cwd(),n);return r===``?`.`:r}const we=/\s*\n\s*/gv,Te=/\r?\n/v;function Ee(e){let t=e.message.replaceAll(we,` `),n=e.rule===void 0?e.tool:`${e.tool}/${e.rule}`;return e.file===void 0?`${e.severity}: ${t} [${n}]`:`${e.file}:${e.line??1}:${e.column??1}: ${e.severity}: ${t} [${n}]`}function De(e,t){let n=(e.file??`￿`).localeCompare(t.file??`￿`);if(n!==0)return n;let r=(e.line??0)-(t.line??0);return r===0?(e.column??0)-(t.column??0):r}function Oe(e,t){let n=t.toSorted(De);return{cwd:process.cwd(),diagnostics:n,success:e.every(e=>e.exitCode===0),summary:{errors:n.filter(e=>e.severity===`error`).length,infos:n.filter(e=>e.severity===`info`).length,warnings:n.filter(e=>e.severity===`warning`).length},tools:e,version:1}}function D(e){return h(e).split(Te).map(e=>e.trimEnd()).filter(e=>e.trim().length>0)}function ke(e){return e instanceof Error&&`exitCode`in e&&typeof e.exitCode==`number`}function O(e){return w(process.stdout,{ciColor:!1})?je(e):Ae(e)}function Ae(e){return _(ee(e),{indent:2,replacer(e,t){return typeof t==`function`?t.name:t}})}function je(e){return g(Ae(e),{colors:{BRACKET:`gray`}})}const Me=(e,t,n)=>{let r=[...e];for(let[i,a]of t.entries())r[i]===void 0?r[i]=n.cloneUnlessOtherwiseSpecified(a,n):n.isMergeableObject(a)?r[i]=k(e[i],a,n):e.includes(a)||r.push(a);return r};function k(e,t,n={arrayMerge:Me}){return te(e,t,n)}function Ne(e){let{tasks:t}=e;return Array.isArray(t)?t:[]}function Pe(e,t){let n=[...Ne(e)];for(let e of Ne(t)){let t=n.findIndex(t=>t.label!==void 0&&t.label===e.label);t===-1?n.push(e):n[t]=e}return{...e,...t,tasks:n}}function Fe(e,t){return e.startsWith(t+s.sep)}function A(){let e=j(),t=/* @__PURE__ */ new Set([e]),n=v();if(n!==null)for(let r of n){let n=s.resolve(r.location);Fe(n,e)&&t.add(n)}return[...t]}function j(){let e=d();if(e===void 0)throw Error(`No package.json found.`);return s.dirname(e)}function Ie(){return ne()!==null}function M(){let e=ne();return e===null?j():s.resolve(e.location)}function Le(e){let t=s.join(M(),e);return r.existsSync(t)?t:void 0}function Re(e){if(e===`workspace-root`)return M();if(e===`package-dir`)return j();if(typeof e==`string`){if(!r.pathExistsSync(e))throw Error(`Custom cwd directory does not exist: ${e}`);return e}return process.cwd()}async function ze(e,t){try{let{default:n}=await import(`prettier`),r=await n.resolveConfig(e),i=await n.format(t,{filepath:e,...r});await y.writeFile(e,i,`utf8`)}catch{console.warn(`Skipped formatting ${e} since Prettier is not installed.`)}}async function N(e){try{await ze(e,await y.readFile(e,`utf8`))}catch{}}const Be=/\r?\n/v;function Ve(e){let t=``,n=t=>t.filter(t=>{let n=h(t);return n.trim()!==``&&!e(n)}).map(e=>`${e}\n`).join(``);return new l({flush(e){e(void 0,n([t]))},transform(e,r,i){let a=(t+e.toString()).split(Be);t=a.pop()??``,i(void 0,n(a))}})}function P(e,t){let n=C()===`native`?e:void 0,r=n===void 0||n===``?``:t===void 0?n:T()[t](n),i=``,a=e=>e.filter(e=>e.trim().length>0).map(e=>r===``?`${e}\n`:`${r} ${e}\n`).join(``);return new l({flush(e){e(void 0,a([i]))},transform(e,t,n){let r=(i+e.toString()).split(Be);i=r.pop()??``,n(void 0,a(r))}})}async function He(e){let t=[];return new Promise((n,r)=>{e.on(`data`,e=>{t.push(e)}),e.on(`error`,e=>{r(e)}),e.on(`end`,()=>{n(Buffer.concat(t).toString(`utf8`))})})}function Ue(e){return e.replaceAll(/[A-Z\u{C0}-\u{D6}\u{D8}-\u{DE}]/gv,e=>`-`+e.toLowerCase())}function F(e,t){return t===1?e:e+`s`}async function I(e){return typeof e==`function`?e():e}async function We(e,t,n,r,i){let a;if(r.logPrefix===void 0)a=e;else{let t=P(r.logPrefix,r.logColor);t.pipe(e),a=t}i&&a.write(T().bold(`Running: "${r.name}() with Positional arguments: ${String(t)} and Option flags: ${String(n)}"`)+`
 `);try{return await r.execute(a,t,n)}catch(e){return console.error(String(e)),1}}function Ge(e,t,n,r,i){return[...e.subcommands??[],...e.receiveOptionFlags?n:[],...r??[],...i&&e.cache!==void 0?[...e.cache.flags,`--cache-location`,s.join(M(),`node_modules`,`.cache`,`ksc`,e.cache.name)]:[],...e.receivePositionalArguments?t:[],...e.positionalArguments??[]]}async function Ke(e,t,r,i,a,o){let s=1,l;if(i.logPrefix===void 0)l=e;else{let t=P(i.logPrefix,i.logColor);t.pipe(e),l=t}let u=Ge(i,t,r,i.optionFlags,a),d=Re(i.cwdOverride);o&&l.write(`Running: "${i.name} ${u.join(` `)}"\n`);let f=i.prettyJsonOutput?new c:void 0,p=f??l,m=Ce(C()===`native`&&i.prettyJsonOutput!==!0&&w(Se()));try{let e=n(i.name,u,{cwd:d,env:m,preferLocal:!0,reject:!1,stdin:`inherit`});if(i.outputFilter){let t=Ve(i.outputFilter),n=Ve(i.outputFilter);e.stdout.pipe(t).pipe(p,{end:!1}),e.stderr.pipe(n).pipe(p,{end:!1})}else e.stdout.pipe(p,{end:!1}),e.stderr.pipe(p,{end:!1});let t=await e;if(f!==void 0){f.end();let e=await He(f),t=O(JSON.parse(e)).split(`
 `);for(let e of t)l.write(`${e}\n`)}s=t.exitCode??1}catch(e){console.error(`${i.name} failed with error:`),console.error(e),ke(e)&&(s=typeof e.exitCode==`number`?e.exitCode:1)}return s}function L(e){return`execute`in e}function R(e){return`kind`in e}async function qe(e,t,r,i,a){let o=Ge(r,e,t,r.collect?.optionFlags??r.optionFlags,i),s=Re(r.cwdOverride);try{let e=n(r.name,o,{cwd:s,env:Ce(!1),preferLocal:!0,reject:!1,stdin:`inherit`});a!==void 0&&e.stderr.pipe(a,{end:!1});let t=await e;return{cwd:s,exitCode:t.exitCode??1,stderr:t.stderr,stdout:t.stdout}}catch(e){return console.error(`${r.name} failed with error:`),console.error(e),{cwd:s,exitCode:ke(e)&&typeof e.exitCode==`number`?e.exitCode:1,stderr:``,stdout:``}}}function Je(e){return typeof e==`object`&&!!e&&`version`in e&&e.version===1&&`diagnostics`in e&&Array.isArray(e.diagnostics)&&`success`in e&&typeof e.success==`boolean`&&`tools`in e&&Array.isArray(e.tools)}function Ye(e,t){return e===0&&t.some(({severity:e})=>e===`error`)?1:e}async function Xe(e,t,n,r,i){let a=Date.now(),o=()=>Date.now()-a;if(L(r)){if(r.collect!==void 0)try{let e=await r.collect(t,n),i=Ye(e.exitCode,e.diagnostics);return{diagnostics:e.diagnostics,exitCode:i,tools:[{durationMs:o(),exitCode:i,name:r.name,unparsed:e.unparsed}]}}catch(e){return{diagnostics:[],exitCode:1,tools:[{durationMs:o(),exitCode:1,name:r.name,unparsed:[String(e)]}]}}let e=``,i=new c;i.on(`data`,t=>{e+=t.toString()});let a;try{a=await r.execute(i,t,n)}catch(t){e+=`\n${String(t)}`,a=1}return{diagnostics:[],exitCode:a,tools:[{durationMs:o(),exitCode:a,name:r.name,unparsed:D(e)}]}}if(R(r))throw Error(`Command groups must be expanded before collection`);if(r.outputFormatAware){let a=await qe(t,n,r,i,e);try{let e=JSON.parse(a.stdout);if(!Je(e))throw Error(`Child output is not a lint report`);return{diagnostics:e.diagnostics,exitCode:a.exitCode===0&&e.success&&e.diagnostics.every(({severity:e})=>e!==`error`)?0:1,tools:e.tools}}catch{return{diagnostics:[],exitCode:a.exitCode,tools:[{durationMs:o(),exitCode:a.exitCode,name:r.name,unparsed:D(a.stdout)}]}}}let s=await qe(t,n,r,i);if(r.collect!==void 0)try{let{diagnostics:e,unparsed:t}=r.collect.parse(s),n=Ye(s.exitCode,e);return{diagnostics:e,exitCode:n,tools:[{durationMs:o(),exitCode:n,name:r.name,unparsed:t}]}}catch(e){return{diagnostics:[],exitCode:s.exitCode,tools:[{durationMs:o(),exitCode:s.exitCode,name:r.name,unparsed:[...D(s.stdout),...D(s.stderr),String(e)]}]}}return{diagnostics:[],exitCode:s.exitCode,tools:[{durationMs:o(),exitCode:s.exitCode,name:r.name,unparsed:[...D(s.stdout),...D(s.stderr)]}]}}const Ze=/^ksc-/v;function z(e){return e.replace(Ze,``)}function B(e){return e===void 0||e.length===0?[]:e.flatMap(e=>e.split(`,`)).map(e=>z(e.trim()))}function V(e){return e.option(`skip`,{array:!0,describe:`Tool names to skip (with or without "ksc-" prefix).`,type:`string`})}function Qe(e){return e.option(`format`,{choices:ve,default:`native`,describe:`Output format: "native" streams each tool's own output, "machine" prints one parseable line per issue for editor problem matchers, "json" prints an aggregate report.`})}function $e(e){return e.option(`cache`,{boolean:!0,default:!0,describe:`Use tool-native caches stored below node_modules/.cache/ksc at the workspace root. Disable with --no-cache.`})}function et(e,t){return t===`native`||t===`machine`&&!L(e)&&!R(e)&&e.outputFormatAware===!0}function tt(e,t){for(let n of t.diagnostics)e.write(`${Ee(n)}\n`);for(let n of t.tools)for(let t of n.unparsed)e.write(`${t}\n`)}function nt(){return Math.min(4,o())}var rt=class{concurrency;active=0;queue=[];constructor(e){this.concurrency=e}async run(e){this.active>=this.concurrency&&await new Promise(e=>{this.queue.push(e)}),this.active+=1;try{return await e()}finally{--this.active,this.queue.shift()?.()}}};async function it(e){let t=e.cache??!1,n=e.concurrency??nt();if(!Number.isInteger(n)||n<1)throw Error(`Concurrency must be a positive integer.`);return t&&await r.ensureDir(s.join(M(),`node_modules`,`.cache`,`ksc`)),{cache:t,scheduler:new rt(n)}}const at=/[*?\[\]\{\}]/v;function H(e,t){return t===void 0?e:e.filter(e=>at.test(e)||i.statSync(e,{throwIfNoEntry:!1})?.isDirectory()===!0||t.includes(s.extname(e).slice(1).toLowerCase()))}function ot(e,t){return e.length===0||H(e,t).length>0}function st(e,t){return e.positionalArgumentMode===`none`?[]:t.length>0?H(t,e.positionalArgumentExtensions):e.positionalArgumentDefault===void 0?[]:[e.positionalArgumentDefault]}function ct(e,t){if(t.logPrefix===void 0)return e;let n=P(t.logPrefix,t.logColor);return n.pipe(e),n}function lt(e){return R(e)?`${e.name} ${e.subcommand}`:!L(e)&&e.subcommands!==void 0?[e.name,...e.subcommands].join(` `):e.name}async function ut(e,t){if(R(e)){let n=ct(t.logStream,e);try{let r=await I(e.commands);if(t.nativeVerbose){let n=[e.subcommand,...t.positionalArguments].join(` `),i=e.showResolvedCommands?` (${r.map(e=>lt(e)).join(`, `)})`:``;t.logStream.write(`Running: "${e.name} ${n}"${i}\n`)}let i=await dt(r,{...t,logStream:n,nativeVerbose:e.verbose,positionalArguments:st(e,t.positionalArguments)},e.parallel===!0);return{diagnostics:i.flatMap(({diagnostics:e})=>e),exitCode:+!i.every(({exitCode:e})=>e===0),machineOutcomes:i.flatMap(({machineOutcomes:e})=>e),name:e.name,tools:i.flatMap(({tools:e})=>e)}}catch(r){let i=String(r),a={durationMs:0,exitCode:1,name:e.name,unparsed:[i]};return t.format===`native`&&n.write(`${i}\n`),{diagnostics:[],exitCode:1,machineOutcomes:[{diagnostics:[],exitCode:1,tools:[a]}],name:e.name,tools:[a]}}}return t.scheduler.run(async()=>{if(et(e,t.format))return{diagnostics:[],exitCode:await(L(e)?We(t.logStream,t.positionalArguments,t.optionFlags,e,t.nativeVerbose):Ke(t.logStream,t.positionalArguments,t.optionFlags,e,t.cache,t.nativeVerbose)),machineOutcomes:[],name:e.name,tools:[]};let n=await Xe(t.logStream,t.positionalArguments,t.optionFlags,e,t.cache);return{diagnostics:n.diagnostics,exitCode:n.exitCode,machineOutcomes:[n],name:e.name,tools:n.tools}})}async function dt(e,t,n){if(!n||t.scheduler.concurrency===1){let n=[];for(let r of e)n.push(await ut(r,t));return n}await Promise.resolve();let r=/* @__PURE__ */ new Map;for(let[t,n]of e.entries()){let e=n.stage??0,i=r.get(e)??[];i.push({command:n,index:t}),r.set(e,i)}let i=Array.from({length:e.length}),a=r.keys().toArray().toSorted((e,t)=>e-t);for(let e of a){let n=r.get(e)??[],a=await Promise.all(n.map(async({command:e,index:n})=>({index:n,outcome:await ut(e,t)})));for(let{index:e,outcome:t}of a)i[e]=t}return i.filter(e=>e!==void 0)}function ft(e,t,n,r,i){let a=[],o=[],s=ot(r,i);for(let e of t){let t=!R(e)||ot(r,e.positionalArgumentExtensions);!s||!t||n.includes(z(e.name))?o.push(e):a.push(e)}if(n.length>0){let r=new Set(o.map(e=>z(e.name))),i=n.filter(e=>!r.has(e));if(i.length>0){let n=t.map(e=>z(e.name)).join(`, `);e.write(`⚠️  ${T().yellow(`Unrecognized --skip ${F(`value`,i.length)}: ${i.join(`, `)}. Available: ${n}`)}\n`)}}return{commandsToRun:a,skippedCommands:o}}async function U(e,t,n,r,i,a,o,s=`native`){let c=typeof s==`string`?{}:s,l=typeof s==`string`?s:c.format??`native`,{commandsToRun:u,skippedCommands:d}=ft(e,r,o??[],t,c.positionalArgumentExtensions),f=l===`native`&&i,{cache:p,scheduler:m}=await it(c),h=await dt(u,{cache:p,format:l,logStream:e,nativeVerbose:f,optionFlags:n,positionalArguments:H(t,c.positionalArgumentExtensions),scheduler:m},c.parallel===!0),g=h.map(({exitCode:e,name:t})=>({exitCode:e,name:t})),ee=h.flatMap(({tools:e})=>e),te=h.flatMap(({diagnostics:e})=>e);if(l===`machine`)for(let t of h)for(let n of t.machineOutcomes)tt(e,n);let _=r.length,v=T();if(l===`native`&&d.length>0){let t=d.map(({name:e})=>e),n=v.bold(`${t.length} / ${_} ${F(`Command`,t.length)} Skipped:`);e.write(`⏭️ ${v.dim(n)} ${v.dim(t.join(`, `))}\n`)}if(l===`native`&&a){let t=g.filter(({exitCode:e})=>e===0).map(({name:e})=>e),n=g.filter(({exitCode:e})=>e!==0).map(({name:e})=>e);if(t.length>0){let n=v.bold(`${t.length} / ${_} ${F(`Command`,t.length)} Succeeded:`);e.write(`✅ ${v.green(n)} ${v.green(t.join(`, `))}\n`)}if(n.length>0){let t=v.bold(`${n.length} / ${_} ${F(`Command`,n.length)} Failed:`);e.write(`❌ ${v.red(t)} ${v.red(n.join(`, `))}\n`)}}return{exitCode:+!g.every(({exitCode:e})=>e===0),report:l===`json`?Oe(ee,te):void 0}}async function pt(e){let t=await u({cwd:e});return t===void 0?void 0:s.join(s.dirname(t),`init`)}async function mt(e,t,n,a){let o=await u();if(o===void 0)throw Error("The `init` command must be used in a directory with a package.json file");let c=await pt(import.meta.dirname);if(c===void 0)return e.write(`Error: Could not locate the package containing this CLI.
 `),1;let l=s.dirname(o),d=(t===`file`||t===`package`)&&n!==void 0&&a!==void 0;try{if(d){let n=Object.keys(a)[0],i=r.readJsonSync(o);if(t===`package`){e.write(`Merging: \nPackage config key "${n}" → "${l}" (Because --location is set to "package")\n`);let t=k(i,a);r.writeJSONSync(o,t,{spaces:`	`}),await N(o)}else n!==void 0&&Object.keys(i).includes(n)&&(e.write(`Deleting: \nPackage config key "${n}" in "${l}" (Because --location is set to "file")\n`),delete i[n],r.writeJSONSync(o,i,{spaces:`	`}),await N(o))}if(!await r.pathExists(c))return 0;if((await r.readdir(c)).length===0)return e.write(`Source directory "${c}" is empty.\n`),0;e.write(`Adding initial configuration files from:\n"${c}" → "${l}"\n`),await r.copy(c,l,{async filter(a,o){let c=i.statSync(a).isFile(),l=i.existsSync(o);if(c){if(d&&t===`package`&&a.includes(n))return l?(e.write(`Deleting: \n"${a}" → "${o}" (Because --location is set to "package")\n`),r.removeSync(o)):e.write(`Skipping: \n"${a}" → "${o}" (Because --location is set to "package")\n`),!1;if(l&&(o.includes(`.vscode/`)||o.includes(`package.json`))&&s.extname(o)===`.json`){e.write(`Merging: \n"${a}" → "${o}"\n`);let t=r.readJSONSync(a),n=r.readJSONSync(o),i=o.endsWith(`.vscode/tasks.json`)?Pe(n,t):k(n,t);return r.writeJSONSync(o,i,{spaces:`	`}),await N(o),!1}return l?(e.write(`Overwriting: \n"${a}" → "${o}"\n`),await N(o),!0):(e.write(`Copying: \n"${a}" → "${o}"\n`),await N(o),!0)}return!0},overwrite:!0})}catch(e){return console.error(String(e)),1}return 0}async function ht(e){let{commands:{fix:t,init:n,lint:r,printConfig:i},description:a,logColor:o,logPrefix:s,name:c,showSummary:l,verbose:u}=e;be();let d=P(s,o);d.pipe(Se());let m=f(p(process.argv)).scriptName(c).usage(`$0 <command>`,a);n!==void 0&&m.command({builder(e){let t=n.locationOptionFlag?e.option(`location`,{choices:[`file`,`package`],default:`file`,describe:`Where to store the configuration.`,type:`string`}):e;return l?V(t):t},command:`init`,describe:n.description??`Initialize by copying starter config files to your project root${n.locationOptionFlag?` or to your package.json file.`:`.`}`,async handler(e){let t=n.locationOptionFlag?e.location:void 0,r=B(e.skip),{exitCode:i}=await U(d,[],t===void 0?[]:[`--location`,t],[{async execute(e,t,r){return mt(e,r.at(1),n.configFile,n.configPackageJson)},name:`copyAndMergeInitFiles`},...n.commands??[]],void 0,void 0,r);process.exitCode=i}}),r!==void 0&&m.command({builder(e){let t=$e(Qe(r.positionalArgumentMode===`none`?e:e.positional(`files`,{array:!0,...r.positionalArgumentDefault!==void 0&&{default:r.positionalArgumentDefault},describe:`Files or glob pattern to lint.`,type:`string`})));return l?V(t):t},command:r.positionalArgumentMode===`none`?`lint`:r.positionalArgumentMode===`optional`?`lint [files..]`:`lint <files..>`,describe:r.description,async handler(e){let t=e.files??[],n=B(e.skip),i=C(),{exitCode:a,report:o}=await U(d,t,[],await I(r.commands),u,l,n,{cache:e.cache,format:i,parallel:r.parallel,positionalArgumentExtensions:r.positionalArgumentExtensions});o!==void 0&&process.stdout.write(`${O(o)}\n`),process.exitCode=a}}),t!==void 0&&m.command({builder(e){let n=$e(Qe(t.positionalArgumentMode===`none`?e:e.positional(`files`,{array:!0,...t.positionalArgumentDefault!==void 0&&{default:t.positionalArgumentDefault},describe:`Files or glob pattern to fix.`,type:`string`})));return l?V(n):n},command:t.positionalArgumentMode===`none`?`fix`:t.positionalArgumentMode===`optional`?`fix [files..]`:`fix <files..>`,describe:t.description,async handler(e){let n=e.files??[],r=B(e.skip),i=C(),{exitCode:a,report:o}=await U(d,n,[],await I(t.commands),void 0,void 0,r,{cache:e.cache,format:i,parallel:t.parallel,positionalArgumentExtensions:t.positionalArgumentExtensions});o!==void 0&&process.stdout.write(`${O(o)}\n`),process.exitCode=a}}),i!==void 0&&m.command({builder(e){let t=i.positionalArgumentMode===`none`?e:e.positional(`file`,{...i.positionalArgumentDefault!==void 0&&{default:i.positionalArgumentDefault},describe:`File or glob pattern to print configuration for.`,type:`string`});return l?V(t):t},command:i.positionalArgumentMode===`none`?`print-config`:i.positionalArgumentMode===`optional`?`print-config [file]`:`print-config <file>`,describe:i.description,async handler(e){let t=e.file??void 0,n=t===void 0?[]:[t],r=B(e.skip),{exitCode:a}=await U(d,n,[],await I(i.commands),u,l,r);process.exitCode=a}}),m.alias(`h`,`help`),m.version(ge),m.alias(`v`,`version`),m.help(),m.wrap(process.stdout.isTTY?Math.min(120,m.terminalWidth()):0),await m.parseAsync()}function W(e){return{async execute(t){let n=await G(e);if(n===void 0)return 1;let{config:r,filepath:i,isEmpty:a}=n;if(t.write(`Found ${e} configuration at "${i}"\n`),a)return t.write(`Configuration is empty.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitschpatrol/shared-config",
-  "version": "8.11.0",
+  "version": "8.12.0",
   "description": "A collection of shared configurations, linters, and formatting tools for TypeScript projects. All managed as a single dependency. All invoked via a single CLI command.",
   "keywords": [
     "shared-config",
@@ -54,15 +54,15 @@
     "skills/*"
   ],
   "dependencies": {
-    "@kitschpatrol/cspell-config": "8.11.0",
-    "@kitschpatrol/eslint-config": "8.11.0",
-    "@kitschpatrol/knip-config": "8.11.0",
-    "@kitschpatrol/mdat-config": "8.11.0",
-    "@kitschpatrol/prettier-config": "8.11.0",
-    "@kitschpatrol/remark-config": "8.11.0",
-    "@kitschpatrol/repo-config": "8.11.0",
-    "@kitschpatrol/stylelint-config": "8.11.0",
-    "@kitschpatrol/typescript-config": "8.11.0",
+    "@kitschpatrol/cspell-config": "8.12.0",
+    "@kitschpatrol/eslint-config": "8.12.0",
+    "@kitschpatrol/knip-config": "8.12.0",
+    "@kitschpatrol/mdat-config": "8.12.0",
+    "@kitschpatrol/prettier-config": "8.12.0",
+    "@kitschpatrol/remark-config": "8.12.0",
+    "@kitschpatrol/repo-config": "8.12.0",
+    "@kitschpatrol/stylelint-config": "8.12.0",
+    "@kitschpatrol/typescript-config": "8.12.0",
     "@pinojs/json-colorizer": "^4.0.0",
     "@pnpm/lockfile.fs": "^1100.2.12",
     "cosmiconfig": "^10.0.1",
@@ -79,7 +79,7 @@
     "globby": "^16.2.4",
     "json-stringify-pretty-compact": "^4.0.0",
     "magicast": "^0.5.5",
-    "mdat": "^3.5.0",
+    "mdat": "^3.6.1",
     "package-up": "^5.0.0",
     "picocolors": "^1.1.1",
     "prettier": "^3.9.9",

package/readme.md

@@ -190,12 +190,18 @@ pnpm --package=@kitschpatrol/repo-config dlx ksc-repo init && pnpm i && pnpm add
 
 5. Set up GitHub action credentials (if desired)
 
-   The GitHub actions included in @kitschpatrol/repo-config require permissions to create releases and update your repository metadata. You can add these through the GitHub website under the _Settings → Secrets and variables → Actions_ page under the key `PERSONAL_ACCESS_TOKEN`, or with the [GitHub CLI](https://cli.github.com) and a credential manager like [1Password CLI](https://www.1password.dev/cli/get-started):
+   The GitHub actions included in @kitschpatrol/repo-config require permissions to create releases, update your repository metadata, and open dependency update pull requests. You can add these through the GitHub website under the _Settings → Secrets and variables → Actions_ page under the key `PERSONAL_ACCESS_TOKEN`, or with the [GitHub CLI](https://cli.github.com) and a credential manager like [1Password CLI](https://www.1password.dev/cli/get-started):
 
    ```sh
    gh secret set PERSONAL_ACCESS_TOKEN --app actions --body $(op read 'op://Personal/GitHub Mika/PERSONAL_ACCESS_TOKEN')
    ```
 
+   The weekly dependency update workflow also needs a `CLAUDE_CODE_OAUTH_TOKEN` secret, a Claude subscription token generated with `claude setup-token`:
+
+   ```sh
+   gh secret set CLAUDE_CODE_OAUTH_TOKEN --app actions --body $(op read 'op://Personal/Claude Code OAuth Token/credential')
+   ```
+
    See the [@kitschpatrol/repo-config readme](https://github.com/kitschpatrol/shared-config/blob/main/packages/repo-config/readme.md#github-configuration) for more details.
 
 ## Usage
@@ -216,7 +222,7 @@ pnpm run fix
 
 ### CLI
 
-<!-- cli-help({ command: 'ksc' }) -->
+<!-- cli-help({ command: 'ksc', heading: false, headingLevel: 3 }) -->
 
 #### Command: `ksc`
 
@@ -374,31 +380,29 @@ The tasks share a problem matcher owner, so the panel reflects the most recent r
 
 ## Agent skills
 
-This project includes an [Agent Skill](https://agentskills.io) that teaches coding agents like Claude Code and Codex how to work with @kitschpatrol/shared-config:
-
-- **[`ksc`](skills/ksc/SKILL.md)**: Code conventions and lint workflow for projects that use @kitschpatrol/shared-config and its ksc CLI, which wraps ESLint, Prettier, TypeScript, Stylelint, CSpell, Knip, remark, and mdat. Use when writing or editing TypeScript, JavaScript, CSS, Markdown, JSON, or YAML in a project that depends on @kitschpatrol/shared-config, when running or fixing `ksc lint` / `ksc fix` failures, when writing eslint-disable comments, or when editing the tool config files it manages.
+This project bundles 2 [Agent Skills](https://agentskills.io) in its published package to help coding agents work with @kitschpatrol/shared-config.
 
-The skill is published in the `skills` directory of the `@kitschpatrol/shared-config` package. Nothing is added to your project until you install it with one of the tools below.
+To sync the skills into your project, run Vercel's [skills CLI](https://github.com/vercel-labs/skills) from your project root:
 
-### Sync from the installed package (recommended)
+```sh
+npx skills experimental_sync
+```
 
-With `@kitschpatrol/shared-config` installed as a project dependency, the [`skills`](https://github.com/vercel-labs/skills) CLI finds skills bundled in your dependencies and copies them into your project's agent skill directories, so they match the version of `@kitschpatrol/shared-config` you have installed:
+Or install globally:
 
 ```sh
-npx skills experimental_sync
+npx skills add kitschpatrol/shared-config --global
 ```
 
-Run the command again after upgrading `@kitschpatrol/shared-config` to refresh the copies. The `experimental_sync` command is experimental and its behavior may change.
+Included skills:
 
-### Install from the repository
+### Skill: [`ksc`](skills/ksc/SKILL.md)
 
-If `@kitschpatrol/shared-config` is not a dependency of your project, for example because you use a global installation, install the skill from the repository instead:
+Code conventions and lint workflow for projects that use @kitschpatrol/shared-config and its ksc CLI, which wraps ESLint, Prettier, TypeScript, Stylelint, CSpell, Knip, remark, and mdat.
 
-```sh
-npx skills add kitschpatrol/shared-config
-```
+### Skill: [`ksc-update`](skills/ksc-update/SKILL.md)
 
-A skill installed this way follows the repository's default branch rather than your installed version of `@kitschpatrol/shared-config`.
+Update dependencies in kitschpatrol shared config pnpm repositories and monorepos with compatible changes, explicitly approved breaking changes, or breaking changes for zero-versioned projects.
 
 <!-- /skills -->
 

package/skills/ksc-update/SKILL.md

@@ -0,0 +1,686 @@
+---
+name: ksc-update
+description: >-
+  Update dependencies in kitschpatrol shared config pnpm repositories and
+  monorepos with compatible changes, explicitly approved breaking changes, or
+  breaking changes for zero-versioned projects. Use when asked to update,
+  upgrade, refresh, or audit repository dependencies or GitHub Actions. Applies
+  a 24-hour release maturity policy with exceptions for kitschpatrol's packages,
+  reviews fresh-install consumer compatibility, validates known consumers,
+  minimizes configuration overrides, and recommends a release level.
+  Does not commit or release.
+compatibility: Requires Node.js, pnpm/pnpx, curl, jq, git, Bash, and access to npm, GitHub, and upstream release documentation.
+---
+
+# Update dependencies
+
+Accept dependency and GitHub Actions updates under the version policy below.
+For projects at 1.0.0 or later, preserve existing contracts: public APIs, CLI
+behavior, outputs, defaults, supported consumer environments, and peer
+compatibility, unless the user explicitly approves a reviewed breaking change.
+Make the migrations accepted updates require. Do not commit, push, tag, publish,
+or release.
+
+## Execution mode
+
+Determine the mode before Setup and record it with the reason. Use unattended
+mode when explicitly requested, when `GITHUB_ACTIONS=true` or `CI=true`, or when
+the host cannot receive user replies. Otherwise use interactive mode; a missing
+TTY alone does not establish that an agent session is unattended.
+
+In unattended mode, never ask questions, wait for answers, or invoke a command
+that requires an interactive response. Existing explicit approvals still apply;
+silence and CI execution do not grant new approval. This mode overrides every
+instruction below to ask, confirm, or await a decision:
+
+- **Projects at 1.0.0 or later:** apply compatible changes and any reviewed
+  breaks already explicitly authorized. Defer other breaking candidates and
+  report them for a later decision. Judge consumer impact, not dependency
+  version labels; a compatible dependency major remains eligible.
+- **Zero-versioned projects:** retain the existing `0.x` allowance in unattended
+  runs. Apply reviewed breaking changes, complete their migrations, validate
+  the new contracts, and normally recommend a minor release. Do not defer them
+  merely because no person is present to approve the break. Other requirements,
+  including explicit approval for runtime-range restrictions and Node-types
+  changes, still apply.
+- **Other decisions and missing prerequisites:** without prior authorization,
+  leave approval-dependent changes unapplied, including range restrictions and
+  peer-warning suppressions. Report missing consumer information, credentials,
+  permissions, or validation resources instead of requesting them. Continue
+  independent work; if a required prerequisite prevents progress, report the
+  affected work as blocked or incomplete without waiting or bypassing it.
+
+Review and validation remain required in both modes. Defer candidates whose
+impact cannot be established or whose migration cannot be validated. If safe
+updates cannot be isolated without an unapproved change, leave those updates
+unapplied and explain the blocker. Report incompatible releases already allowed
+by published runtime ranges as existing consumer exposure; an older lockfile
+does not resolve that exposure.
+
+Produce changes and a report suitable for later PR automation. This skill does
+not create workflows or pull requests, or split work into multiple PRs. If
+nothing can be applied, produce the report without manufacturing a change.
+
+## Policy
+
+- **Compatible by default at 1.0.0 or later:** assess the effect on this repository
+  and its consumers, not just the dependency's version label. Minor and patch
+  updates can break compatibility; a dependency major can still be compatible.
+  Present useful breaking candidates with their impact, migration, validation,
+  and release implications before asking for approval; apply only within the
+  approved scope. Existing explicit approval remains valid. Defer unapproved
+  breaks and updates whose impact cannot be established. This includes authored
+  packages, production transitives, and workflow actions.
+- **Zero-versioned projects:** if the project's current release version has
+  major version zero (`0.x.y`), any breaking change within this update workflow
+  is permitted in both interactive and unattended modes, including changes to
+  public contracts and consumer Node.js requirements. This exception overrides
+  compatibility-preservation requirements below. Use the project's version, not
+  the dependency's version; in monorepos,
+  assess each affected published package or shared release version, not just a
+  private workspace root. Review and report breaking changes, make required
+  migrations, and validate the resulting behavior. All other policies still
+  apply.
+- **Release maturity:** third-party releases must be at least 24 hours old
+  (`--maturity-period 1` for Taze, `--min-age 1` for Actions Up, pnpm
+  `minimumReleaseAge` of 1440 minutes). Never disable installation safeguards to
+  make an update succeed.
+- **Authored packages:** packages owned by `kitschpatrol` (discovered at runtime
+  in Setup) are exempt from maturity and target their latest stable release,
+  including majors. The exemption does not bypass security or compatibility
+  review.
+- **Consumer ranges:** review the newest published version allowed by each
+  runtime dependency's declared range, as well as the lockfile. A fresh consumer
+  install can resolve that version even when CI locks an older one. Holding
+  back an in-range release requires a genuinely restrictive published range
+  (for example, `~1.8.0` instead of `^1.8.0` to exclude `1.9.0`), not just an
+  older lockfile entry. Obtain explicit approval before narrowing a runtime
+  range to hold a release back, even for a zero-versioned project; explain the
+  consumer effect. Do not use local overrides as a substitute for that decision.
+- **TypeScript:** select a compiler within the peer range of the accepted
+  `@kitschpatrol/typescript-config` version, intersected with other required
+  peers. Do not hard-code a compiler version. Offer the migration when an
+  authored major requires a newer compiler; see step 3. If that config is not
+  used, follow the project's compiler policy and peer requirements.
+- **Node types:** preserve `@types/node` declarations, including catalogs and
+  overrides, unless a reviewed migration has explicit authorization to change
+  them. New compiler libraries do not establish runtime API availability.
+- **Package manager:** only Setup manages `packageManager`. Exclude `pnpm`
+  from Taze discovery and writes.
+- **No weakening:** do not relax tests, lint rules, type checking, or security
+  settings to get a pass; do not blindly accept changed snapshots or generated
+  output. Compatibility-preserving lint disables described in step 5 are an
+  exception.
+- **No new noise:** every check is compared against the Setup baseline. A new
+  warning, deprecation, or peer issue is a finding to trace and report, not
+  background noise. Report compatibility-preserving lint disables from step 5;
+  ask before silencing other findings.
+
+## Environment
+
+Shell variables do not persist between commands. Save anything later steps need
+under `node_modules/.cache/ksc-update/` and pass values literally.
+
+Plan network access for `registry.npmjs.org`, `raw.githubusercontent.com`,
+`api.github.com`, and `nodejs.org`; identify any additional upstream hosts as
+needed. Prefer registry metadata and raw changelog files over GitHub API calls
+for package reviews. Cache responses and share them between reviewers.
+
+Under Claude Code's sandbox:
+
+- **pnpm store:** pnpm 12 cannot take its store lock inside the sandbox
+  (`ERR_PNPM_STORE_DIR_OPEN_OPERATION_LOCK`), even with writable store, cache,
+  and temp directories. `pnpm install`, `pnpm update`, `pnpm dedupe`,
+  `pnpx taze`, and `pnpx actions-up` must be listed in the user's
+  `sandbox.excludedCommands` and `permissions.allow`. If the Setup install fails
+  this way, stop the affected work and ask the user to add them in interactive
+  mode; in unattended mode, report the missing prerequisite. Do not route around
+  it. Run these commands bare (no pipes, redirects, or command substitution) so the
+  exclusions match. Run each as its own invocation, without `&&` or `||`.
+  Save captured tool output to log files in a separate operation.
+- **Proxy:** Node-based tools ignore the proxy variables. If one fails with
+  `ENOTFOUND`, rerun it with `NODE_USE_ENV_PROXY=1`.
+- **Sockets:** the `tsx` CLI cannot open its IPC socket. Run the same script
+  with `node --import tsx <script>` and report the substitution.
+- **GitHub API:** without `GITHUB_TOKEN`, GitHub allows 60 requests per hour.
+  One Actions Up run plus a few release-note lookups can exhaust it. The sandbox
+  cannot read `gh` credentials, so budget lookups or ask for a token in
+  interactive mode. In unattended mode, report any review blocked by missing
+  credentials or exhausted API limits.
+- **JSON output:** pnpm can emit `[WARN]` lines on stdout. Sync `packageManager`
+  before parsing pnpm JSON; if warnings remain, save them separately, remove
+  only lines beginning with `[WARN]`, and parse the rest strictly. Do not hide
+  malformed output or other diagnostics.
+- **Supply-chain settings:** an unreadable global config or `~/.npmrc` can make
+  a sandboxed config query return `undefined`; this does not mean the policy is
+  disabled. Read accessible workspace settings and record pnpm's successful
+  `Lockfile passes supply-chain policies` message from the actual install.
+  That message confirms the active checks passed, not the numeric release-age
+  threshold. Verify the required 1440 minutes from accessible configuration or
+  release timestamps when the effective setting cannot be read. Do not disable
+  safeguards or access private config through a workaround.
+
+## Setup
+
+1. Read repository instructions. Note uncommitted changes in the working tree
+   and preserve them. If files change during the run that you did not touch,
+   leave them alone and report them.
+   Read the `Known consumers` section in the project's `CLAUDE.md` or `AGENTS.md`.
+   Maintain a short section in the existing instruction file using confirmed
+   consumer names, local paths, consumed packages, test commands, and CLI
+   fixtures. If none are documented, ask for known consumers in interactive
+   mode; in unattended mode, report the missing information and use available
+   repository evidence. Continue independent review; do not invent consumers or
+   treat example paths as real. Report unavailable consumer validation as a gap.
+2. Map the workspace: root, every maintained package root, catalogs, overrides,
+   `pnpm-workspace.yaml`, Taze config. Exclude fixtures, generated files, and
+   dependency directories. Run each step once per shared-lockfile workspace and
+   separately in any independent package root. Check Taze config for anything
+   that overrides mode, adds maturity exemptions, or auto-writes/installs.
+   Record current project and published package versions to determine where the
+   zero-versioned exception applies.
+   Create the baseline folder and preserve the starting manifests and lockfile
+   before the package-manager sync or any other edit.
+3. Sync `packageManager` before installs and parsed pnpm output. Read the actual
+   installed pnpm from an empty directory so the project's stale pin cannot
+   select or download another version:
+
+   ```bash
+   pnpm --version
+   ```
+
+   Run that command with a new empty directory under `${TMPDIR:-/tmp}` as its
+   working directory. Then edit only the workspace root's `packageManager`
+   directly to `pnpm@<observed-version>`, preserving all other manifest fields.
+   Use the editor or a structured JSON edit, not `pnpm pkg set`; use direct
+   edits for later specifiers and engines too. pnpm commands can trigger
+   version-manager downloads after the pin changes. If this crosses a pnpm
+   major, report it and verify the CI installer supports the selected version.
+
+4. Install the starting dependency declarations and record a baseline before
+   dependency updates. Keep the original files saved in Setup 2 even if
+   installation fails.
+
+   ```bash
+   pnpm install --frozen-lockfile
+   ```
+
+   On `ERR_PNPM_OUTDATED_LOCKFILE` only, run this as a separate bare command:
+
+   ```bash
+   pnpm install --no-frozen-lockfile
+   ```
+
+   Save the lockfile diff against the starting copy in the baseline folder and
+   report the drift. Treat checks after repair as the repaired baseline, not as
+   proof that the original locked tree passed. Other installation failures need
+   their own diagnosis; do not generalize this fallback or relax safeguards.
+
+   Save the output of each install attempt and of `pnpm build`, `pnpm test`, and
+   `pnpm lint` to `node_modules/.cache/ksc-update/baseline/`. If the repository
+   produces build output (`dist/` or similar), copy it there as well. Use the
+   repository's switches to disable nondeterministic build steps (encryption,
+   timestamps) and note the exact command and environment; later comparison
+   builds must match them. Baseline failures are pre-existing; record them.
+
+   Record each published package's declared `engines.node`, effective consumer
+   Node.js minimum and supported range, and separate development requirement.
+   Include published dependency trees and built artifacts, not just the root
+   manifest or current CI runtime. If no Node.js support policy is declared,
+   establish the existing requirement from the published code and dependencies;
+   do not assume the developer's Node.js version is the consumer minimum.
+   Save production-tree engine inventories and baseline consumer results using
+   [the verification recipes](references/verification.md). Distinguish the
+   starting locked tree, the newest versions a fresh consumer install can
+   resolve, and the published release with its old dependencies when available.
+
+5. Discover authored packages:
+
+   ```bash
+   set -euo pipefail
+   mkdir -p node_modules/.cache/ksc-update
+   curl -fsS https://registry.npmjs.org/-/user/kitschpatrol/package \
+     | jq -er 'keys | join(",") | select(length > 0)' \
+       > node_modules/.cache/ksc-update/authored-packages.txt
+   ```
+
+   If registry discovery fails or returns empty, stop and report. Intersect the
+   result with direct dependency names across the maintained manifests in this
+   workspace, including dev, optional, and peer dependencies and dependencies
+   using catalogs or npm aliases. Save the intersection separately; an empty
+   intersection is valid. `<authored-packages>` below means only those exact
+   matching names, comma-separated and passed literally, with no wildcards.
+   Omit `--maturity-period-exclude` if the intersection is empty. Keep the full
+   ownership list only for evaluating other packages encountered later.
+
+## 1. Workflow actions
+
+```bash
+pnpx actions-up --yes --min-age 1 --style sha
+```
+
+Read the whole output. Actions Up can print "All actions are up to date!" after
+checks failed; any `Skipped`, `Failed`, or `Rate Limit` line means the run is
+incomplete. Fix the cause and rerun.
+
+Review the diff: major action bumps, runner, input, output, and permission
+changes. Every external GitHub Action and reusable workflow must be pinned to
+its full commit SHA, including `kitschpatrol/*`; retain version comments for
+readability. Do not exclude first-party actions from pinning or allow their
+floating refs in zizmor's `unpinned-uses` policy. Resolve skipped branch/tag
+refs and unchanged versions to verified commits too; if an update is deferred,
+pin the retained version. Check existing zizmor configuration for exceptions
+that contradict this policy. Pin container actions by digest; local `./` actions
+use the checked-out tree. Keep only reviewed changes without disturbing user
+edits. Local tests say nothing about remote workflows.
+
+## 2. Discover all candidates (read-only)
+
+```bash
+pnpx taze major -r --force --include-locked \
+  --no-github-actions --no-node-version \
+  --exclude '@types/node,pnpm' \
+  --maturity-period 1 \
+  --maturity-period-exclude '<authored-packages>'
+```
+
+Major mode lists every available update, minor and major. Confirm authored
+packages are offered their latest stable release, not the latest within their
+current major. Do not opt into new prerelease channels. Taze's newest candidate
+does not replace the separate newest-in-range runtime review in step 3.
+
+## 3. Evaluate candidates
+
+### Runtime ranges and review scope
+
+For each runtime dependency of a published package, inspect registry metadata
+for the newest stable version satisfying its current declared range, accounting
+for catalogs and aliases. Record declared range, locked version, newest allowed
+version, and proposed range/version. Review that newest allowed release even
+if it is already in range or too young for this run to install; consumer
+package managers may not enforce this repository's maturity policy. Keep the
+installation safeguards and report any untested consumer exposure.
+
+Review direct candidates and production-tree changes fully. For development-only
+transitives, check advisories, deprecations, and engines; investigate release
+notes only when those checks, validation failures, or output differences give
+cause. A package bundled or shipped with a CLI/config package belongs to the
+consumer review even if this repository also uses it as development tooling.
+
+An in-range behavior change may already reach the published release's consumers.
+Do not describe an older lockfile as protecting them or infer a new breaking
+release solely from the lockfile movement. Test the published release and
+updated build against actual consumer resolution, and separately preserve the
+old locked baseline. To hold back an incompatible allowed release, present a
+specific narrower range and obtain the policy's required approval.
+
+### Breaking candidates
+
+Track breaking-candidate decisions throughout the run; report applied breaks
+and deferred opportunities separately.
+For each candidate, identify affected APIs, behavior, Node.js support, known
+consumers, migration work, validation results or gaps, and release implications.
+Prepare a concrete proposal and, where useful, validate a trial migration in an
+isolated copy before seeking a decision. For stable projects in interactive
+mode, ask explicitly whether to accept each reviewed break unless that exact
+scope was already authorized; continue independent updates while awaiting the
+answer. In unattended mode, defer unapproved stable-project breaks and include
+them under `Breaking changes available` in the report without asking. General
+permission to update dependencies is not approval for an unspecified break.
+For `0.x` projects, both modes authorize reviewed breaking migrations without
+another question, but runtime-range narrowing still needs explicit approval.
+Record accepted, declined, pending, and deferred decisions separately.
+
+### Node.js compatibility
+
+For every candidate, minor and patch included, distinguish consumer requirements
+from development requirements:
+
+- **Consumers:** for projects at 1.0.0 or later, keep the user-facing Node.js
+  minimum and supported range unchanged unless explicitly approved under
+  `Breaking candidates`. A higher effective consumer minimum or loss of any
+  supported Node.js version is a break even if `engines.node` is left unchanged.
+  Check direct, transitive, optional, peer, and workspace dependencies used by
+  published packages, plus bundled code, emitted syntax, and runtime APIs.
+  A tool used only for development here is still a consumer dependency if it
+  ships in a published CLI or configuration package. Compare
+  full engine ranges, not just the lowest version in each range.
+  For authorized breaks or zero-versioned projects, update published
+  `engines.node` to reflect the actual supported range and validate against it.
+- **Development:** a higher Node.js requirement for development-only tools,
+  builds, or CI is allowed when published artifacts remain compatible. If it
+  exceeds the consumer requirement, add or update the Node.js entry in the
+  relevant `package.json`'s `devEngines.runtime` with `name: "node"` and a
+  `version` range covering the actual development requirement. Use the workspace
+  root for shared tooling and package manifests for package-specific tooling;
+  preserve other runtime entries and settings. This is the development Node.js
+  dependency notice; do not raise published `engines.node` to satisfy dev tools.
+  Align development version pins and build CI as needed while retaining consumer
+  compatibility checks at the applicable supported minimums (the original ones
+  unless an approved break or the zero-versioned exception changes them).
+
+### TypeScript migrations
+
+Read the accepted `@kitschpatrol/typescript-config` release's TypeScript peer
+range and base configuration. If it requires a new compiler major, offer that
+migration with its concrete effects rather than automatically deferring the
+authored update. Apply it within existing authorization; ask only for additional
+breaking or Node-types changes that the policy actually requires approval for.
+
+- Add `"node"` to `compilerOptions.types` where Node globals are needed,
+  preserving other required type entries and the separation from browser code.
+- Fix errors exposed by newly enabled strict options; do not disable those
+  options just to pass.
+- Check the new base `lib`, emitted syntax, declarations, and APIs used by
+  shipped code against the consumer Node.js floor and browser targets. A newer
+  `lib` can make unavailable APIs type-check; it does not polyfill them.
+
+Run type checks, build, and consumer validation after the migration, retaining
+the distinction between development and consumer Node.js requirements.
+
+### Compatibility review
+
+For direct candidates and production-tree changes, read relevant upstream
+release notes, migration guides, and advisories, and assess:
+
+- **Security:** vulnerabilities fixed or introduced, ownership or publishing
+  anomalies, new install scripts or permissions.
+- **Breaking:** APIs, types, defaults, configuration, module format, peer
+  ranges, runtime requirements, measured against this repository's actual use.
+- **Coupling:** peer and engine requirements against the versions this update
+  will produce, not the current ones. A major can require a newer minor of a
+  sibling package (`@astrojs/mdx` 8 requires `astro` 7.2.10 or later).
+- **Worth it:** fixes and performance adoptable under the version policy.
+  Note features exposed by the update and optional feature opportunities for the
+  report; do not implement new features as extra work.
+
+When delegation is available, run independent release-note reviews in parallel,
+split into authored packages, remaining runtime packages, and remaining direct
+development packages. Give each reviewer its disjoint package list, a short
+survey of actual usage and relevant source paths, consumer requirements, and
+the version policy. Reviewers return decisions and sources without editing
+dependencies; the primary agent resolves coupling and combines the results.
+Share cached metadata and the GitHub API budget. Review sequentially when
+delegation is unavailable.
+
+Record current → proposed version, decision, and sources. Accept only when
+compatibility is preserved, an explicit approval covers the break, or the
+zero-versioned exception permits it; defer the rest with a reason. Do not
+defer a migration merely because it needs a major release recommendation.
+
+## 4. Apply
+
+Apply only accepted candidates, including minors and patches, by exact package
+name. Major mode can apply all accepted update sizes:
+
+```bash
+pnpx taze major -rw --force --include-locked \
+  --no-github-actions --no-node-version \
+  --include 'pkg-a,pkg-b' \
+  --exclude '@types/node,pnpm' \
+  --maturity-period 1 \
+  --maturity-period-exclude '<authored-packages>'
+```
+
+Replace the example names with the accepted set; skip the command if it is
+empty. If only an older compatible target was accepted, set that reviewed
+version manually instead of letting Taze choose the latest. Then check the
+diff: every manifest and catalog covered, only reviewed versions applied, no
+excluded or deferred update slipped in, range style and `workspace:` references
+intact. A package accepted in one workspace package is not automatically
+accepted in every other one. Hand-edit anything Taze missed (catalogs,
+overrides), and add any required development Node.js notice. Use direct edits
+for reviewed compiler versions inside the required peer range and for
+authorized Node-types changes; do not let Taze choose an incompatible compiler.
+Verify `packageManager` remains at Setup's selected version.
+
+## 5. Resolve and validate
+
+Run each command as a separate invocation:
+
+```bash
+pnpm update -r
+```
+
+```bash
+pnpm dedupe --check
+```
+
+Inspect the result. If it reports available deduplication, run the following
+separately; other failures need diagnosis, not an unconditional retry:
+
+```bash
+pnpm dedupe
+```
+
+Then run the checks, each separately:
+
+```bash
+pnpm build
+pnpm fix
+pnpm build # only if fix changed source files
+pnpm test
+pnpm lint
+```
+
+Always use bare `pnpm update -r` for the full refresh, without package selectors.
+Named-package updates do not provide the same transitive refresh; do not use
+`!pkg` selectors as a workaround for deferred candidates. It resolves within
+the written ranges and rechecks release age without discarding `node_modules`.
+In pnpm 12 it can also raise range floors in `package.json` and catalogs
+(for example, `^1.8.0` to `^1.9.0`), so review the manifest and catalog diffs
+after every update, not just the lockfile. Preserve excluded declarations and
+undo unreviewed range changes by direct edits, then synchronize the lockfile.
+
+Deduplication consolidates compatible references onto newer versions already
+in the tree; it is not a way to hold back or downgrade a dependency. Review
+production changes fully and development-only transitives under step 3's
+narrower checks. If a deferred version is still allowed by a published runtime
+range, use the explicit range/consumer decision path rather than fighting the
+resolver with an older lockfile or an unapproved override.
+If an authored release is blocked by `minimumReleaseAge`, add only that
+package/version to `minimumReleaseAgeExclude`; never its dependencies.
+
+Compare every result with the baseline:
+
+- **Consumer compatibility:** recheck the resolved published dependency trees
+  and build artifacts against the Node.js baseline, including transitive
+  changes from resolution or deduplication. Validate consumer installation and
+  representative runtime behavior at the applicable supported minimums separately
+  from checks needing the newer development runtime. Review `pnpm fix` changes
+  to `engines.node` and `devEngines.runtime`; a passing fixer or build on newer
+  Node.js does not establish consumer compatibility. Diff the production-engine
+  inventories, test the packed build in known consumers, and run fixtures at the
+  exact supported Node.js floor using [the verification recipes](references/verification.md).
+  For stable projects, do not retain a newly introduced break outside explicit
+  approval; present the candidate or defer it. Do not mask it with an unapproved
+  `engines.node` increase. For authorized breaks and zero-versioned projects,
+  validate the new contracts and Node.js range and report the baseline changes.
+- **Logs:** for each new warning, deprecation, or peer issue, find the package
+  that introduced it (`pnpm why`) and search upstream for a known issue. Report
+  it with the link. For a peer declaration lagging a verified compatible
+  version, offer a scoped `peerDependencyRules.allowedVersions` entry such as
+  `"parent@range>peer": "tested-range"` in `pnpm-workspace.yaml`, explaining
+  that it suppresses a warning rather than fixing incompatibility. Show the
+  exact entry and evidence, and ask before applying unless already authorized.
+  Do not use broad `allowAny` or disable strict peer checks. Revisit such
+  workarounds during step 8.
+- **Build output:** if the baseline includes build output, rebuild with the
+  same command and environment and diff the trees with content-hashed filenames
+  normalized (`name.[hash].js`). Explain every remaining difference with an
+  upstream changelog entry, issue, or reviewed migration/configuration change;
+  anything unexplained needs investigation. Unless explicitly configured,
+  tsdown derives its build target from `engines.node`, so an engine change can
+  legitimately alter emitted syntax. Record the effective targets before and
+  after, distinguish expected output changes from regressions, and check runtime
+  APIs separately because syntax lowering does not provide polyfills.
+- **After `pnpm fix`:** review the diff, then rebuild and diff against the
+  pre-fix build. Formatting changes must produce identical output. A lint
+  rule's suggested fix can change behavior (default parameters do not replace
+  `null`); in that case keep the code and add an inline disable that says why.
+  If the project can or is likely to run in browsers, including alongside
+  Node.js, disable the offending rule for the affected shipped code when its
+  fix would introduce regex flags or DOM APIs unsupported by the project's
+  browser targets. Explain the compatibility reason and keep the compatible
+  code instead of applying the fix; revert the fix if already applied. This
+  also applies to zero-versioned projects, but does not apply to Node.js-only
+  projects.
+  Resolve remaining lint errors by hand.
+
+On failure, make the smallest change consistent with the version policy and
+rerun from the failing step:
+
+- To tell a new failure from a pre-existing one, check the baseline logs.
+  `git stash` does not revert `node_modules`, so rerunning a check after
+  stashing still uses the new dependencies.
+- To isolate a breaking update: set half the accepted updates back to their
+  previous specifiers, `pnpm update -r`, rerun the failing check, repeat.
+  For an out-of-range update, defer the culprit unless an approval or the
+  zero-versioned exception permits it and the migration resolves the failure.
+  For an already allowed runtime release, follow the range decision path in
+  step 3; resetting a specifier or lockfile may not exclude it.
+
+Add focused tests only where a compatibility change touches behavior not
+already covered. Review `readme.md` accuracy and automation opportunities in step 7.
+
+## 6. Exclusion cleanup
+
+Only if `minimumReleaseAgeExclude` is non-empty in any `pnpm-workspace.yaml`
+(at the start, or after step 5). Empty the list (`[]` or remove the key),
+preserving neighboring keys and comments. Repeat step 5's separate bare
+`pnpm update -r` and `pnpm dedupe --check` invocations, followed by a separate
+`pnpm dedupe` only when the check reports available changes. Then run each check
+separately:
+
+```bash
+pnpm build
+pnpm test
+pnpm lint
+```
+
+If `pnpm-lock.yaml` comes out byte-identical and no ranges or build settings
+changed, the installed tree did not change; rerun only `pnpm lint`.
+
+If resolution is blocked: for an authored release, re-add the narrowest
+package/version entry; for a third-party release, choose a mature version or
+defer that upgrade. Obtain approval if that choice requires narrowing a
+published runtime range. Never restore the whole previous list.
+
+If the list was empty throughout, skip this section and continue to step 7.
+If cleanup changes resolution, repeat step 5's consumer compatibility review
+before reviewing documentation.
+
+## 7. Documentation review
+
+Review `readme.md` against the updated project. Correct stale installation
+instructions, requirements, commands, examples, configuration guidance, and
+feature descriptions. If `readme.md` is generated or copied from another file,
+update its maintained source and regenerate it through the existing workflow.
+
+Review each section for content that would be more reliably maintained through
+mdat, especially content duplicated from package metadata, CLI help, source
+files, or other documentation. Prefer a rule bundled with mdat when it fits,
+then a suitable mdat plugin, or a custom rule in `mdat.config.ts` for
+project-specific needs. Check the installed rules and relevant documentation
+before choosing an implementation. Replace manually maintained sections where
+generation reduces duplication or prevents drift while preserving their useful
+content and readability; keep explanatory prose manual when automation adds
+no benefit. Any new plugin dependency must satisfy the dependency review,
+release maturity, and compatibility policies above.
+
+Run the project's mdat generation and documentation checks, inspect the
+rendered content for accuracy, and confirm that a second generation produces
+no further changes. Validate any new dependency under steps 5 and 6 before
+continuing. Include documentation corrections and mdat conversions in the
+final report.
+
+## 8. @kitschpatrol/shared-config override minimization
+
+Run this as the final cleanup after all accepted updates, migrations,
+validation, release-age exclusion cleanup, and documentation review, before
+the release recommendation and report.
+
+Review every shared-config-related configuration file in the project root,
+including dotfiles, companion ignore files, and configuration stored in
+`package.json`. Include the individual `@kitschpatrol/*-config` packages used by
+the project. Inventory every local override beyond the upstream default export
+or equivalent base configuration: rule settings, options, ignores, file globs,
+and other customizations.
+Include scoped peer-warning workarounds added during the update; remove them
+when upstream peer declarations now cover the tested versions.
+
+For each override, compare it with the defaults and effective configuration of
+the exact versions installed after the updates. Check the current code it
+targets and, for upstream workarounds, the relevant upstream changes or fixes.
+Remove overrides that duplicate current defaults, target code or files that no
+longer exist, or compensate for issues now fixed upstream. Do not infer that an
+override is redundant merely because checks pass while it is still enabled.
+
+Validate removals in small groups using the affected tools' checks without
+caches, covering the affected files and any files newly included by removing
+ignores. Recheck effective configuration where merge order or file matching
+matters. Keep overrides that still serve a concrete project requirement,
+including the behavior and browser-compatibility protections from step 5, and
+record why each is needed. If necessity cannot be established, retain the
+override and report the unresolved evidence instead of guessing.
+
+After changing configuration, rerun the affected build, test, type, and lint
+checks and compare results and build output as in step 5. The final report must
+account for every override: removed with evidence, retained with a current
+justification, or unresolved with the missing evidence identified.
+
+## Release recommendation
+
+Recommend `patch`, `minor`, or `major` from the final consumer-visible changes,
+following the repository's release conventions. Do not infer the recommendation
+from the largest dependency version bump:
+
+- **Patch:** compatible bug or security fixes, performance improvements, or
+  dependency/tooling maintenance with no new consumer-facing capability. A
+  development-only Node.js increase with the required notice can remain a patch.
+- **Minor:** backward-compatible functionality or capabilities actually exposed
+  to consumers by the accepted updates. Explain what consumers gain; an upstream
+  minor or major alone is not a reason for a minor release. For zero-versioned
+  projects, also recommend a minor release for accepted consumer-facing breaking
+  changes unless the repository's pre-1.0 release conventions specify otherwise.
+- **Major:** explicitly approved consumer-facing breaks in projects at 1.0.0
+  or later, including a raised consumer Node.js floor. A dependency major or
+  development-only requirement by itself does not justify a project major.
+
+Give a short rationale per affected published package, or one recommendation
+for a shared release version using the highest applicable level. If nothing
+releasable changed, say no release is needed. An approved major release is
+within scope; an unapproved breaking candidate stays pending or deferred.
+For `0.x`, accepted consumer breaks normally require a minor, not a patch;
+follow an explicit repository convention if it differs. Assess changes already
+reachable through the old published ranges separately from newly introduced
+consumer breaks. Recommend only; do not bump repository versions.
+
+## Report
+
+State the execution mode and why it was selected. Include a `Breaking changes
+available` section for deferred breaking candidates: current and proposed
+versions, affected consumers/contracts, required migration, validation results
+or gaps, recommended release level, and the decision still needed. Distinguish
+these from applied breaks authorized explicitly or by the `0.x` policy. In
+unattended mode, record decisions needed as follow-up items, not questions or
+pending waits. Report unavailable checks and blocked work even when independent
+updates succeeded.
+
+Review the full diff for unrelated changes, excluded-package edits, and stray
+exemptions first. Then summarize: applied updates; major decisions with
+sources; consumer impact, approvals, declined/deferred decisions, and breaks
+accepted under the zero-versioned policy;
+output differences and their upstream or migration explanations;
+consumer Node.js requirements before and after, development Node.js changes and
+their `devEngines.runtime` notices; the release recommendation and its rationale;
+baseline lockfile drift; runtime ranges, fresh-install exposure, and approved
+range restrictions; TypeScript migrations; new warnings and scoped peer
+workarounds; what was validated, at which exact Node.js versions, and in which
+known consumers, including CLI/fixture comparisons and unavailable baselines;
+remaining `minimumReleaseAgeExclude` entries with reasons; deferred upgrades,
+documentation corrections and mdat conversions;
+shared-config overrides removed or retained with their justifications and any
+unresolved override reviews; unresolved failures, checks that could not run,
+and steps run differently because of the environment. Passing checks do not
+prove the absence of breaking changes. Leave everything uncommitted.

package/skills/ksc-update/references/verification.md

@@ -0,0 +1,168 @@
+# Consumer verification recipes
+
+Use these recipes during Setup and step 5. Save commands, versions, raw logs,
+and results under `node_modules/.cache/ksc-update/`. Run pnpm commands as separate
+bare invocations; save their captured output in a later operation so sandbox
+command exclusions still match.
+
+## Production-tree engines
+
+For each published package, run in its directory before and after updates:
+
+```bash
+pnpm list --prod --depth Infinity --json
+```
+
+Save stdout as `production-tree.json` in the corresponding baseline or updated
+results folder. If stdout contains lines beginning with `[WARN]`, preserve those
+warnings separately and remove only those lines before parsing. Require a
+successful command and valid JSON; do not extract an arbitrary JSON-looking
+substring from failed output. In a monorepo, include every published package,
+not only a private root with no production dependencies.
+
+The list supplies installed paths; read each installed `package.json` for its
+actual engine declaration. Save this helper in the run's cache as
+`production-engines.mjs` and run it with the saved JSON path as its argument:
+
+```js
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const roots = JSON.parse(readFileSync(process.argv[2], 'utf8'))
+if (!Array.isArray(roots)) {
+  throw new TypeError('Expected pnpm list JSON array')
+}
+
+const manifests = new Map()
+const rows = new Set()
+
+function visit(pkg) {
+  if (!pkg.path) {
+    throw new Error(`Missing installed path: ${pkg.name ?? pkg.version}`)
+  }
+
+  if (!manifests.has(pkg.path)) {
+    manifests.set(pkg.path, JSON.parse(readFileSync(join(pkg.path, 'package.json'), 'utf8')))
+  }
+
+  const manifest = manifests.get(pkg.path)
+  rows.add(
+    JSON.stringify({
+      name: manifest.name,
+      node: manifest.engines?.node,
+      version: manifest.version,
+    }),
+  )
+  for (const group of ['dependencies', 'optionalDependencies']) {
+    const children = Object.values(pkg[group] ?? {})
+    for (const child of children) {
+      visit(child)
+    }
+  }
+}
+
+for (const root of roots) {
+  visit(root)
+}
+
+process.stdout.write(`${[...rows].toSorted().join('\n')}\n`)
+```
+
+Save the resulting inventory and diff it after resolution and deduplication.
+Investigate missing installed paths instead of omitting them. An omitted `node`
+field means undeclared support, not proof of compatibility. Check full semver ranges
+against every supported consumer Node.js line; check platform-specific optional
+dependencies and shipped/bundled code separately because one host's installed
+tree cannot prove their compatibility. This inventory does not replace the
+newest-in-range registry review.
+
+## Known consumers and packed builds
+
+Read confirmed consumers from the repository's existing `CLAUDE.md` or
+`AGENTS.md`. A useful `Known consumers` entry contains the consumer's name and
+path, which package/imports/CLI it uses, its test command, and representative
+CLI commands and fixture inputs. Preserve existing instructions; add only facts
+confirmed by the user or repository evidence.
+
+1. Create a temporary directory under `${TMPDIR:-/tmp}`. Clone each local
+   consumer into it with `git clone --no-hardlinks <consumer-path> <temp-copy>`.
+   Record the commit. A clone excludes uncommitted changes; if those matter,
+   explicitly copy the needed working-tree files and record that baseline.
+   Do not modify the consumer's original checkout.
+2. Install and test the copied consumer with its starting lockfile. Save
+   its tests' results and representative CLI stdout, stderr, and exit codes.
+   Preserve this copy for baseline comparison.
+3. Build the updated package with its development Node.js version and run
+   `pnpm pack` as a bare command in that package. Inspect the archive's contents
+   and manifest, including exported entrypoints, engines, and dependency ranges.
+4. In a second consumer copy, replace the consumed dependency with a `file:`
+   specifier pointing to that tarball, using a direct manifest edit. Install
+   and rerun the same tests and CLI fixtures. If a workspace-local dependency
+   or alias is involved, replace the actual consuming edge and verify the
+   resolved path/version; do not assume a root-only edit reaches it. A linked
+   built package is useful for iteration, but the tarball verifies what ships
+   and avoids a link silently borrowing the producer's `node_modules`.
+5. Diff CLI output and fixture results. Inspect semantic differences, including
+   behavior JSON may hide, such as object prototypes, missing versus undefined
+   values, ordering, and error handling. Explain each change against accepted
+   migrations and consumer expectations.
+
+Also test a fresh isolated install of the published release with the newest
+dependencies its ranges allow. Keep this distinct from the published release
+running on its old dependencies: reproduce the latter from a known historical
+lockfile or preserved installation where possible. A registry tarball alone
+does not recover the old transitive tree. If it cannot be reconstructed, report
+that gap instead of labeling a fresh install the historical baseline.
+
+## Exact Node.js floor
+
+Use the exact minimum supported release, not just the same major or the active
+developer runtime. For disjoint supported Node.js lines, check each relevant
+minimum. For an approved engine bump, compare the old release at its old floor
+with the updated package at its new floor and on an overlapping supported
+runtime where available.
+
+If the version manager has no suitable installed binary, download the exact
+official archive from `https://nodejs.org/dist/v<version>/` for the host's OS and
+architecture into a temporary folder, alongside `SHASUMS256.txt`. Verify the
+archive's SHA-256 against that file, then extract it there. Use the resulting
+Node binary by absolute path; do not install globally or change the user's
+default runtime. Record `<absolute-node-path> --version` with the results.
+
+Install/build with the development runtime if the tooling requires it, then
+invoke the packed package's built JavaScript entrypoint and runtime fixtures
+with the exact-floor binary. For subprocesses that use `env node`, put that
+binary's directory first in the test process's `PATH` only. Confirm which
+binary the child process uses. If the test runner itself requires newer Node,
+run a small fixture harness or the built CLI directly at the floor; running
+only the newer test runner is not floor validation. Report when installation
+or execution on the exact runtime could not be verified.
+
+Record stdout, stderr, exit codes, and relevant API results for identical
+fixtures across runtimes and dependency baselines. Normalize only known
+nondeterministic fields using the same documented transformation for all runs.
+Save SHA-256 digests of normalized fixture output for quick comparison, retain
+the actual output for reviewing differences, and add targeted assertions for
+behavior that serialization omits.
+
+## Tool references
+
+Check these primary sources or the installed tool's help when behavior differs:
+
+- [GitHub Actions variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables):
+  `GITHUB_ACTIONS` and `CI` identify unattended execution in Actions.
+- [pnpm update](https://pnpm.io/cli/update): manifest/catalog writes and selectors.
+  This workflow uses a bare update for its full dependency refresh; do not
+  assume exclusion syntax works identically in every pnpm implementation.
+- [pnpm dedupe](https://pnpm.io/cli/dedupe) and
+  [pnpm list](https://pnpm.io/cli/list): deduplication checks and tree inventories.
+- [pnpm settings](https://pnpm.io/settings) and
+  [peer rules](https://pnpm.io/settings/peer-dependencies#peerdependencyrulesallowedversions):
+  current configuration locations and scoped warning allowances. Current pnpm
+  uses `.npmrc` for registry/auth settings, not all policy settings.
+- [Taze](https://github.com/antfu-collective/taze): candidate filters and maturity.
+- [Actions Up](https://github.com/azat-io/actions-up#update-style): SHA pinning.
+- [tsdown target](https://tsdown.dev/options/target): implicit engine-derived
+  targets affect emitted syntax and do not provide API polyfills.
+- [Node.js release archives](https://nodejs.org/dist/): exact runtime downloads
+  and checksum manifests.