@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/commands/inspect-cycles.js

@@ -1,5 +1,811 @@
-"use strict";var X=exports&&exports.__createBinding||(Object.create?(function(e,t,o,n){n===void 0&&(n=o);var s=Object.getOwnPropertyDescriptor(t,o);(!s||("get"in s?!t.__esModule:s.writable||s.configurable))&&(s={enumerable:!0,get:function(){return t[o]}}),Object.defineProperty(e,n,s)}):(function(e,t,o,n){n===void 0&&(n=o),e[n]=t[o]})),Q=exports&&exports.__setModuleDefault||(Object.create?(function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}):function(e,t){e.default=t}),Z=exports&&exports.__importStar||(function(){var e=function(t){return e=Object.getOwnPropertyNames||function(o){var n=[];for(var s in o)Object.prototype.hasOwnProperty.call(o,s)&&(n[n.length]=s);return n},e(t)};return function(t){if(t&&t.__esModule)return t;var o={};if(t!=null)for(var n=e(t),s=0;s<n.length;s++)n[s]!=="default"&&X(o,t,n[s]);return Q(o,t),o}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.isInspectCyclesRequest=ce,exports.runInspectCycles=le,exports.buildCyclesViewResponse=B,exports.appendCycleComponentText=Y;const ee=Z(require("node:path")),te=require("node:crypto"),ne=require("../config/local-config"),E=require("../config/path-display"),A=require("../shared/agent-text"),y=require("../shared/errors"),oe=require("./inspect-graph"),N=require("./session-workspace"),S=10,se=6,O=8,ie=5e3,re=12e4;function ce(e,t){if(e[0]==="cycles")return!0;if(!e.includes("--stdin")||!f(t))return!1;const o=U(t);return o.length>0&&o.some(n=>h(n.op)==="cycles")}function le(e,t,o){const n=(0,E.buildDisplayPathAliases)(e,(0,N.readEffectiveSessionPathAliases)(e)),l=ue(t,o).map(r=>ae(e,r,n)),i=l.length===1?l[0]:{results:l};return(0,A.attachAgentText)(i,I(i))}function ue(e,t){if(e[0]==="cycles")return[fe(e.slice(1))];if(!e.includes("--stdin")||!f(t))throw new y.CliError("INSPECT_CYCLES_SCOPE_REQUIRED","inspect cycles expects scope or files.");const o=U(t);if(o.some(n=>h(n.op)!=="cycles"))throw new y.CliError("INSPECT_CYCLES_MIXED_BATCH_UNSUPPORTED","inspect cycles --stdin expects only cycles requests.");return o.map((n,s)=>de(n,s))}function fe(e){const o=[...e.filter(n=>!n.startsWith("--")&&!Fe(e,n)),...C(e,"--scope"),...C(e,"--scopes")];return L({scopes:o,files:[...C(e,"--file"),...C(e,"--files")],detail:w(R(e,"--detail")),kind:M(R(e,"--kind")),exclude:[...C(e,"--exclude"),...C(e,"--excludes")],limit:q(R(e,"--limit"))??S})}function de(e,t){return L({scopes:a(e.scope)??a(e.scopes)??[],files:a(e.file)??a(e.files)??[],detail:w(e.detail),kind:M(e.kind),exclude:a(e.exclude)??a(e.excludes)??[],limit:q(e.limit)??S,index:t})}function L(e){if(e.scopes.length===0&&e.files.length===0){const t=e.index!==void 0?` at index ${e.index}`:"";throw new y.CliError("INSPECT_CYCLES_SCOPE_REQUIRED",`inspect cycles request${t} expects scope or files.`)}return{scopes:j(e.scopes),files:j(e.files),detail:e.detail,kind:e.kind,exclude:j(e.exclude),limit:e.limit}}function ae(e,t,o){const n=(0,ne.resolveLocalCliConfig)(e),s=t.scopes.length>0?t.scopes:t.files,l=t.files.map(p=>Le(e,p)),i=me();i({phase:"graph",completed:0,message:"building import graph"});const r=(0,oe.buildInspectGraphModel)(e,{scopes:s,depth:t.scopes.length>0?0:se,excludePatterns:[...n.config.inspect.graph.exclude,...t.exclude],symbolUsage:t.detail==="imports"});i({phase:"graph",completed:r.files.length,total:r.files.length,message:"import graph built"});const u=new Set(l),c=pe(r.edges,{onProgress:i}).filter(p=>(u.size===0||p.nodes.some(J=>u.has(J)))&&(t.kind===null||p.kind===t.kind)),d=ke(t,r.files.length,r.edges.length,u.size,c),m=Me(d),g=De(e,t,o),x={ok:!0,op:"cycles",version:1,createdAt:new Date().toISOString(),target:g,request:{scopes:t.scopes,files:t.files,detail:t.detail,...t.kind?{kind:t.kind}:{},limit:t.limit,exclude:t.exclude},componentCount:c.length,summary:V(c),analysis:d,timeoutHint:m,components:c.map(p=>Ee(p,o)),...t.exclude.length>0?{exclude:t.exclude}:{}},D=Ne(JSON.stringify(x),o);D&&(x.paths=D);const W=Oe(x),P=(0,N.saveSessionResultViewJson)(e,W,x),_=B(x,{detail:t.detail,offset:0,limit:t.limit});if(P){_.result=P.saved,_.resultFile=P.file;const p=I(_);if(p)return(0,A.attachAgentText)(_,p)}return _}function me(){return()=>{}}function pe(e,t={}){const o=new Map;for(const i of e){const r=o.get(i.from)??[];r.push(i),o.set(i.from,r)}for(const i of o.values())i.sort((r,u)=>r.to.localeCompare(u.to));const n=Array.from(new Set(e.flatMap(i=>[i.from,i.to]))).sort();t.onProgress?.({phase:"components",completed:0,total:n.length,message:"finding cyclic components"});const s=ge(n,o).filter(i=>i.length>1||ye(i[0]??"",o));t.onProgress?.({phase:"components",completed:n.length,total:n.length,message:`${s.length} cyclic components found`});const l=[];return s.forEach((i,r)=>{const u=Ce(i,o);if(t.onProgress?.({phase:"representatives",completed:r+1,total:s.length,message:"building representative cycles"}),u){const c=he(i,o);l.push({nodes:i,representative:u,kind:T(c),counts:be(c)})}}),l.sort(_e)}function he(e,t){const o=new Set(e);return e.flatMap(n=>(t.get(n)??[]).filter(s=>o.has(s.to)))}function ge(e,t){let o=0;const n=[],s=new Set,l=new Map,i=new Map,r=[];for(const c of e)l.has(c)||u(c);return r.map(c=>c.sort());function u(c){l.set(c,o),i.set(c,o),o+=1,n.push(c),s.add(c);for(const m of t.get(c)??[]){const g=m.to;l.has(g)?s.has(g)&&i.set(c,Math.min(i.get(c)??0,l.get(g)??0)):(u(g),i.set(c,Math.min(i.get(c)??0,i.get(g)??0)))}if(i.get(c)!==l.get(c))return;const d=[];for(;n.length>0;){const m=n.pop();if(s.delete(m),d.push(m),m===c)break}r.push(d)}}function ye(e,t){return(t.get(e)??[]).some(o=>o.to===e)}function Ce(e,t){const o=new Set(e);let n=null;for(const s of e){const l=(t.get(s)??[]).filter(i=>o.has(i.to));for(const i of l){if(i.to===s){n=F(n,{nodes:[s,s],edges:[i],kind:T([i])});continue}const r=xe(i.to,s,t,o);r&&(n=F(n,{nodes:[s,...r.nodes],edges:[i,...r.edges],kind:T([i,...r.edges])}))}}return n}function xe(e,t,o,n){const s=[{node:e,nodes:[e],edges:[]}],l=new Set([e]);for(let i=0;i<s.length;i+=1){const r=s[i];for(const u of o.get(r.node)??[])if(n.has(u.to)){if(u.to===t)return{nodes:[...r.nodes,t],edges:[...r.edges,u]};l.has(u.to)||(l.add(u.to),s.push({node:u.to,nodes:[...r.nodes,u.to],edges:[...r.edges,u]}))}}return null}function F(e,t){return e?t.nodes.length!==e.nodes.length?t.nodes.length<e.nodes.length?t:e:$(t.nodes)<$(e.nodes)?t:e:t}function _e(e,t){const o=v(e.kind)-v(t.kind);if(o!==0)return o;const n=t.nodes.length-e.nodes.length;return n!==0?n:$(e.representative.nodes).localeCompare($(t.representative.nodes))}function v(e){return e==="runtime"?0:e==="mixed"?1:2}function T(e){const t=new Set(e.map(H));return t.size===0||t.has("mixed")||t.has("runtime")&&t.has("type-only")?"mixed":t.has("runtime")?"runtime":"type-only"}function H(e){const t=e.symbols??[];if(t.length===0)return"runtime";let o=!1,n=!1;for(const s of t){if(typeof s=="string"){n=!0;continue}s.usage==="type"?o=!0:n=!0}return o&&n?"mixed":o?"type-only":"runtime"}function be(e){const t={runtime:0,"type-only":0,mixed:0};for(const o of e)t[H(o)]+=1;return t}function $(e){return e.join("\0")}function Ee(e,t){const o=e.nodes.map(s=>k(s,t)),n=Se(e.representative,t);return{kind:e.kind,files:o,fileCount:o.length,edgeCounts:e.counts,cycle:n,chain:h(n.chain)}}function Se(e,t){const o=e.nodes.map(n=>k(n,t));return{kind:e.kind,path:o,chain:o.join(" -> "),imports:e.edges.map(n=>$e(n,t))}}function $e(e,t){const o=k(e.from,t),n=k(e.to,t),s=Ie(e.symbols);return s?`${o} -> ${n}: ${s}`:`${o} -> ${n}`}function Ie(e){const t=(e??[]).map(n=>typeof n=="string"?n:n.name).filter(n=>n.length>0);if(t.length===0)return"";const o=t.slice(0,4);return t.length>o.length?`${o.join(" ")} + ${t.length-o.length} more`:o.join(" ")}function B(e,t={}){if(e.op!=="cycles")throw new y.CliError("INVALID_CYCLES_RESULT","Expected a cycles result artifact.");const o=t.detail??w(ve(e.request,"detail")),n=Array.isArray(e.components)?e.components.filter(f):[],s=t.kind?n.filter(m=>m.kind===t.kind):n,l=s.length,i=Math.max(0,t.offset??0),r=Math.max(1,t.limit??S),u=t.index!==void 0?[s[t.index-1]].filter(f):s.slice(i,i+r),c=t.index!==void 0?0:Math.max(0,l-i-u.length),d={ok:!0,op:"cycles",target:h(e.target)??"",detail:o,componentCount:l,summary:Ae(s),...f(e.analysis)?{analysis:e.analysis}:{},...f(e.timeoutHint)?{timeoutHint:e.timeoutHint}:{},components:u,offset:i,limit:r,...t.index!==void 0?{index:t.index}:{},...c>0?{hidden:c}:{},...t.resultHandle?{result:t.resultHandle}:{},...e.paths?{paths:e.paths}:{}};return(0,A.attachAgentText)(d,I(d))}function ke(e,t,o,n,s){const l=V(s),i=s.reduce((u,c)=>Math.max(u,c.nodes.length),0),r=s.reduce((u,c)=>u+c.representative.edges.length,0);return{fileCount:t,edgeCount:o,focusFileCount:n,scopeCount:e.scopes.length,detail:e.detail,componentCount:s.length,largestComponentFileCount:i,representativeEdgeCount:r,runtimeComponentCount:l.runtime,mixedComponentCount:l.mixed,typeOnlyComponentCount:l["type-only"]}}function Me(e){const t=b(e.fileCount),o=b(e.edgeCount),n=b(e.componentCount),s=b(e.largestComponentFileCount),l=b(e.representativeEdgeCount),i=h(e.detail)??"summary";return{recommendedTimeoutMs:Pe({fileCount:t,edgeCount:o,componentCount:n,largestComponentFileCount:s,representativeEdgeCount:l,detail:i}),fileCount:t,edgeCount:o,componentCount:n,detail:i,message:"If cycle analysis runs as a post-mutation phase, inspect progress with: aib execution status last"}}function Pe(e){const t=e.detail==="imports"?1.25:e.detail==="files"?1.1:1,o=Math.round((750+e.fileCount*1.5+e.edgeCount*1.25+e.componentCount*4+e.largestComponentFileCount*2+e.representativeEdgeCount*1.5)*t);return Math.min(re,Math.max(ie,o))}function V(e){const t={runtime:0,"type-only":0,mixed:0};for(const o of e)t[o.kind]+=1;return t}function Ae(e){const t={runtime:0,"type-only":0,mixed:0};for(const o of e){const n=M(o.kind);n&&(t[n]+=1)}return t}function Oe(e){return`res_${(0,te.createHash)("sha256").update(JSON.stringify({target:e.target,request:e.request,componentCount:e.componentCount,components:e.components})).digest("hex").slice(0,8)}`}function I(e){if(Array.isArray(e.results)){const i=e.results.filter(f).map(I).filter(r=>!!r);return i.length>0?i.join(`
-
-`):null}if(e.op!=="cycles")return null;const t=typeof e.target=="string"?e.target:"",o=typeof e.componentCount=="number"?e.componentCount:0,n=[`cycles ${t}`.trim()];if(o===0)return n.push(e.index?"selected component not found":"no cycles"),K(n,e.paths),n.join(`
-`);n.push(Te(o,e.summary),""),z(o,e.summary)||je(n,e.summary);const s=Array.isArray(e.components)?e.components.filter(f):[];s.forEach((i,r)=>{const u=a(i.files)??[],c=typeof e.index=="number"?e.index:(typeof e.offset=="number"?e.offset:0)+r+1,d=o===1&&s.length===1&&!e.index?"":`${c}. `;Y(n,i,{detail:e.detail==="files"||e.detail==="imports"?e.detail:"summary",prefix:d,indent:d?"   ":""})}),typeof e.hidden=="number"&&e.hidden>0&&n.push(`+ ${e.hidden} more cyclic ${e.hidden===1?"component":"components"}`);const l=h(e.result);if(l&&typeof e.hidden=="number"&&e.hidden>0){const i=(typeof e.offset=="number"?e.offset:0)+s.length,r=typeof e.limit=="number"?e.limit:S;n.push(`more: aib view ${l} --offset ${i} --limit ${r}`)}return K(n,e.paths),n.join(`
-`)}function Y(e,t,o={}){const n=a(t.files)??[],s=M(t.kind)??"mixed",l=o.prefix??"",i=o.indent??"";if(e.push(`${l}${s}, ${n.length} ${n.length===1?"file":"files"}`),o.detail==="files"){for(const c of n.slice(0,O))e.push(`${i}${c}`);n.length>O&&e.push(`${i}+ ${n.length-O} more files`)}const r=f(t.cycle)?t.cycle:{},u=a(r.path)??Re(h(t.chain));if(u.length>0&&(e.push(`${i}cycle:`),we(e,u,i)),o.detail==="imports"){const c=a(r.imports)??a(t.imports)??[];if(c.length>0){e.push(`${i}imports:`);for(const d of c)e.push(`${i}${d}`)}}}function Te(e,t){const o=z(e,t);return o?`${e} ${o} ${e===1?"cycle":"cycles"}`:`${e} cyclic ${e===1?"component":"components"}`}function z(e,t){if(!f(t))return null;const n=["runtime","mixed","type-only"].filter(s=>t[s]===e);return n.length===1?n[0]:null}function Re(e){return e?e.split(" -> ").filter(t=>t.trim().length>0):[]}function we(e,t,o){if(t.length>4){e.push(`${o}${t[0]}`);for(const n of t.slice(1))e.push(`${o}-> ${n}`);return}e.push(`${o}${t.join(" -> ")}`)}function je(e,t){if(!f(t))return;const o=typeof t.runtime=="number"?t.runtime:0,n=typeof t.mixed=="number"?t.mixed:0,s=typeof t["type-only"]=="number"?t["type-only"]:0;e.push(`runtime ${o}, mixed ${n}, type-only ${s}`,"")}function K(e,t){if(!f(t))return;const o=Object.entries(t).filter(n=>typeof n[1]=="string").sort(([n],[s])=>n.localeCompare(s));if(o.length!==0){e.push("","paths:");for(const[n,s]of o)e.push(`${n} = ${s}`)}}function De(e,t,o){const s=(t.scopes.length>0?t.scopes:t.files).map(l=>(0,E.compactDisplayPath)(e,l,o));return s.length===1?s[0]:`[${s.join(",")}]`}function k(e,t){return(0,E.compactDisplayPath)("",e,t)}function Ne(e,t){const o={};for(const n of t)e.includes(n.token)&&(o[n.token]=n.prefix);return Object.keys(o).length>0?o:null}function Le(e,t){return(0,E.toDisplayPath)(e,ee.resolve(e,t))}function U(e){return f(e)?Array.isArray(e.requests)?e.requests.filter(f):[e]:[]}function R(e,t){const o=e.indexOf(t);if(o<0)return null;const n=e[o+1];return n&&!n.startsWith("--")?n:null}function C(e,t){const o=[];for(let n=0;n<e.length;n+=1){if(e[n]!==t)continue;const s=e[n+1];s&&!s.startsWith("--")&&(o.push(...G(s)),n+=1)}return o}function Fe(e,t){const o=e.indexOf(t);return o>0&&e[o-1]?.startsWith("--")===!0}function w(e){if(e==null||e==="summary"||e==="sum")return"summary";if(e==="imports")return"imports";if(e==="files")return"files";throw new y.CliError("INVALID_CYCLES_DETAIL","inspect cycles detail expects summary, imports, or files.")}function M(e){if(e==null||e==="")return null;if(e==="runtime"||e==="type-only"||e==="mixed")return e;throw new y.CliError("INVALID_CYCLES_KIND","inspect cycles kind expects runtime, type-only, or mixed.")}function q(e){const t=typeof e=="number"?e:typeof e=="string"?Number(e):NaN;return Number.isInteger(t)&&t>0?t:null}function b(e){return typeof e=="number"&&Number.isFinite(e)?e:0}function h(e){return typeof e=="string"&&e.length>0?e:null}function ve(e,t){return f(e)?h(e[t]):null}function a(e){return typeof e=="string"&&e.length>0?G(e):Array.isArray(e)?e.filter(t=>typeof t=="string"&&t.length>0):null}function G(e){return e.split(",").map(t=>t.trim()).filter(Boolean)}function j(e){return Array.from(new Set(e)).sort()}function f(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInspectCyclesRequest = isInspectCyclesRequest;
+exports.runInspectCycles = runInspectCycles;
+exports.buildCyclesViewResponse = buildCyclesViewResponse;
+exports.formatCyclesResponse = formatCyclesResponse;
+exports.appendCycleComponentText = appendCycleComponentText;
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const local_config_1 = require("../config/local-config");
+const path_display_1 = require("../config/path-display");
+const agent_text_1 = require("../shared/agent-text");
+const errors_1 = require("../shared/errors");
+const inspect_graph_1 = require("./inspect-graph");
+const session_workspace_1 = require("./session-workspace");
+const DEFAULT_LIMIT = 10;
+const FILE_NEIGHBOR_DEPTH = 6;
+const TEXT_COMPONENT_FILE_LIMIT = 8;
+const CYCLES_ESTIMATE_MIN_MS = 5_000;
+const CYCLES_ESTIMATE_MAX_MS = 120_000;
+function isInspectCyclesRequest(restArgs, stdinPayload) {
+    if (restArgs[0] === "cycles") {
+        return true;
+    }
+    if (!restArgs.includes("--stdin") || !isObject(stdinPayload)) {
+        return false;
+    }
+    const requests = expandCyclesPayloadRequests(stdinPayload);
+    return requests.length > 0 && requests.some((request) => readString(request.op) === "cycles");
+}
+function runInspectCycles(cwd, restArgs, stdinPayload) {
+    const aliases = (0, path_display_1.buildDisplayPathAliases)(cwd, (0, session_workspace_1.readEffectiveSessionPathAliases)(cwd));
+    const requests = buildCyclesRequests(restArgs, stdinPayload);
+    const results = requests.map((request) => runCyclesRequest(cwd, request, aliases));
+    const response = results.length === 1 ? results[0] : { results };
+    return (0, agent_text_1.attachAgentText)(response, formatCyclesResponse(response));
+}
+function buildCyclesRequests(restArgs, stdinPayload) {
+    if (restArgs[0] === "cycles") {
+        return [cyclesRequestFromArgs(restArgs.slice(1))];
+    }
+    if (!restArgs.includes("--stdin") || !isObject(stdinPayload)) {
+        throw new errors_1.CliError("INSPECT_CYCLES_SCOPE_REQUIRED", "inspect cycles expects scope or files.");
+    }
+    const rawRequests = expandCyclesPayloadRequests(stdinPayload);
+    if (rawRequests.some((request) => readString(request.op) !== "cycles")) {
+        throw new errors_1.CliError("INSPECT_CYCLES_MIXED_BATCH_UNSUPPORTED", "inspect cycles --stdin expects only cycles requests.");
+    }
+    return rawRequests.map((request, index) => cyclesRequestFromObject(request, index));
+}
+function cyclesRequestFromArgs(args) {
+    const positionals = args.filter((arg) => !arg.startsWith("--") && !isFlagValue(args, arg));
+    const scopes = [
+        ...positionals,
+        ...readFlagValues(args, "--scope"),
+        ...readFlagValues(args, "--scopes")
+    ];
+    return finalizeCyclesRequest({
+        scopes,
+        files: [
+            ...readFlagValues(args, "--file"),
+            ...readFlagValues(args, "--files")
+        ],
+        detail: readCyclesDetail(readFlagValue(args, "--detail")),
+        kind: readCycleKind(readFlagValue(args, "--kind")),
+        exclude: [
+            ...readFlagValues(args, "--exclude"),
+            ...readFlagValues(args, "--excludes")
+        ],
+        limit: readPositiveInteger(readFlagValue(args, "--limit")) ?? DEFAULT_LIMIT
+    });
+}
+function cyclesRequestFromObject(raw, index) {
+    return finalizeCyclesRequest({
+        scopes: readStringArray(raw.scope) ?? readStringArray(raw.scopes) ?? [],
+        files: readStringArray(raw.file) ?? readStringArray(raw.files) ?? [],
+        detail: readCyclesDetail(raw.detail),
+        kind: readCycleKind(raw.kind),
+        exclude: readStringArray(raw.exclude) ?? readStringArray(raw.excludes) ?? [],
+        limit: readPositiveInteger(raw.limit) ?? DEFAULT_LIMIT,
+        index
+    });
+}
+function finalizeCyclesRequest(input) {
+    if (input.scopes.length === 0 && input.files.length === 0) {
+        const suffix = input.index !== undefined ? ` at index ${input.index}` : "";
+        throw new errors_1.CliError("INSPECT_CYCLES_SCOPE_REQUIRED", `inspect cycles request${suffix} expects scope or files.`);
+    }
+    return {
+        scopes: uniqueSorted(input.scopes),
+        files: uniqueSorted(input.files),
+        detail: input.detail,
+        kind: input.kind,
+        exclude: uniqueSorted(input.exclude),
+        limit: input.limit
+    };
+}
+function runCyclesRequest(cwd, request, aliases) {
+    const localConfig = (0, local_config_1.resolveLocalCliConfig)(cwd);
+    const graphScopes = request.scopes.length > 0 ? request.scopes : request.files;
+    const focusFiles = request.files.map((file) => toGraphPath(cwd, file));
+    const progress = createCycleProgressReporter();
+    progress({ phase: "graph", completed: 0, message: "building import graph" });
+    const model = (0, inspect_graph_1.buildInspectGraphModel)(cwd, {
+        scopes: graphScopes,
+        depth: request.scopes.length > 0 ? 0 : FILE_NEIGHBOR_DEPTH,
+        excludePatterns: [
+            ...localConfig.config.inspect.graph.exclude,
+            ...request.exclude
+        ],
+        symbolUsage: request.detail === "imports"
+    });
+    progress({ phase: "graph", completed: model.files.length, total: model.files.length, message: "import graph built" });
+    const focusSet = new Set(focusFiles);
+    const components = findCyclicComponents(model.edges, {
+        onProgress: progress
+    }).filter((component) => (focusSet.size === 0 || component.nodes.some((node) => focusSet.has(node))) &&
+        (request.kind === null || component.kind === request.kind));
+    const analysis = buildCyclesAnalysis(request, model.files.length, model.edges.length, focusSet.size, components);
+    const timeoutHint = buildCyclesTimeoutHint(analysis);
+    const target = formatCyclesTarget(cwd, request, aliases);
+    const artifact = {
+        ok: true,
+        op: "cycles",
+        version: 1,
+        createdAt: new Date().toISOString(),
+        target,
+        request: {
+            scopes: request.scopes,
+            files: request.files,
+            detail: request.detail,
+            ...(request.kind ? { kind: request.kind } : {}),
+            limit: request.limit,
+            exclude: request.exclude
+        },
+        componentCount: components.length,
+        summary: summarizeComponents(components),
+        analysis,
+        timeoutHint,
+        components: components.map((component) => formatComponent(component, aliases)),
+        ...(request.exclude.length > 0 ? { exclude: request.exclude } : {})
+    };
+    const paths = usedAliasPayload(JSON.stringify(artifact), aliases);
+    if (paths) {
+        artifact.paths = paths;
+    }
+    const resultId = createResultId(artifact);
+    const saved = (0, session_workspace_1.saveSessionResultViewJson)(cwd, resultId, artifact);
+    const response = buildCyclesViewResponse(artifact, {
+        detail: request.detail,
+        offset: 0,
+        limit: request.limit
+    });
+    if (saved) {
+        response.result = saved.saved;
+        response.resultFile = saved.file;
+        const text = formatCyclesResponse(response);
+        if (text) {
+            return (0, agent_text_1.attachAgentText)(response, text);
+        }
+    }
+    return response;
+}
+function createCycleProgressReporter() {
+    return () => {
+        // Reserved for future stderr/execution progress without changing the analysis API again.
+    };
+}
+function findCyclicComponents(edges, options = {}) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const outgoing = adjacency.get(edge.from) ?? [];
+        outgoing.push(edge);
+        adjacency.set(edge.from, outgoing);
+    }
+    for (const outgoing of adjacency.values()) {
+        outgoing.sort((left, right) => left.to.localeCompare(right.to));
+    }
+    const nodes = Array.from(new Set(edges.flatMap((edge) => [edge.from, edge.to]))).sort();
+    options.onProgress?.({ phase: "components", completed: 0, total: nodes.length, message: "finding cyclic components" });
+    const stronglyConnected = findStronglyConnectedComponents(nodes, adjacency)
+        .filter((component) => component.length > 1 || hasSelfEdge(component[0] ?? "", adjacency));
+    options.onProgress?.({
+        phase: "components",
+        completed: nodes.length,
+        total: nodes.length,
+        message: `${stronglyConnected.length} cyclic components found`
+    });
+    const components = [];
+    stronglyConnected.forEach((component, index) => {
+        const representative = findRepresentativeCycle(component, adjacency);
+        options.onProgress?.({
+            phase: "representatives",
+            completed: index + 1,
+            total: stronglyConnected.length,
+            message: "building representative cycles"
+        });
+        if (representative) {
+            const internalEdges = collectInternalEdges(component, adjacency);
+            components.push({
+                nodes: component,
+                representative,
+                kind: classifyEdges(internalEdges),
+                counts: countEdgeKinds(internalEdges)
+            });
+        }
+    });
+    return components.sort(compareComponents);
+}
+function collectInternalEdges(component, adjacency) {
+    const componentSet = new Set(component);
+    return component.flatMap((node) => (adjacency.get(node) ?? []).filter((edge) => componentSet.has(edge.to)));
+}
+function findStronglyConnectedComponents(nodes, adjacency) {
+    let index = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indexes = new Map();
+    const lowlinks = new Map();
+    const components = [];
+    for (const node of nodes) {
+        if (!indexes.has(node)) {
+            strongConnect(node);
+        }
+    }
+    return components.map((component) => component.sort());
+    function strongConnect(node) {
+        indexes.set(node, index);
+        lowlinks.set(node, index);
+        index += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const edge of adjacency.get(node) ?? []) {
+            const target = edge.to;
+            if (!indexes.has(target)) {
+                strongConnect(target);
+                lowlinks.set(node, Math.min(lowlinks.get(node) ?? 0, lowlinks.get(target) ?? 0));
+            }
+            else if (onStack.has(target)) {
+                lowlinks.set(node, Math.min(lowlinks.get(node) ?? 0, indexes.get(target) ?? 0));
+            }
+        }
+        if (lowlinks.get(node) !== indexes.get(node)) {
+            return;
+        }
+        const component = [];
+        while (stack.length > 0) {
+            const next = stack.pop();
+            onStack.delete(next);
+            component.push(next);
+            if (next === node) {
+                break;
+            }
+        }
+        components.push(component);
+    }
+}
+function hasSelfEdge(node, adjacency) {
+    return (adjacency.get(node) ?? []).some((edge) => edge.to === node);
+}
+function findRepresentativeCycle(component, adjacency) {
+    const componentSet = new Set(component);
+    let best = null;
+    for (const start of component) {
+        const outgoing = (adjacency.get(start) ?? []).filter((edge) => componentSet.has(edge.to));
+        for (const firstEdge of outgoing) {
+            if (firstEdge.to === start) {
+                best = pickBetterCycle(best, { nodes: [start, start], edges: [firstEdge], kind: classifyEdges([firstEdge]) });
+                continue;
+            }
+            const path = findShortestPath(firstEdge.to, start, adjacency, componentSet);
+            if (!path) {
+                continue;
+            }
+            best = pickBetterCycle(best, {
+                nodes: [start, ...path.nodes],
+                edges: [firstEdge, ...path.edges],
+                kind: classifyEdges([firstEdge, ...path.edges])
+            });
+        }
+    }
+    return best;
+}
+function findShortestPath(from, to, adjacency, allowed) {
+    const queue = [{ node: from, nodes: [from], edges: [] }];
+    const visited = new Set([from]);
+    for (let index = 0; index < queue.length; index += 1) {
+        const current = queue[index];
+        for (const edge of adjacency.get(current.node) ?? []) {
+            if (!allowed.has(edge.to)) {
+                continue;
+            }
+            if (edge.to === to) {
+                return {
+                    nodes: [...current.nodes, to],
+                    edges: [...current.edges, edge]
+                };
+            }
+            if (visited.has(edge.to)) {
+                continue;
+            }
+            visited.add(edge.to);
+            queue.push({
+                node: edge.to,
+                nodes: [...current.nodes, edge.to],
+                edges: [...current.edges, edge]
+            });
+        }
+    }
+    return null;
+}
+function pickBetterCycle(current, candidate) {
+    if (!current) {
+        return candidate;
+    }
+    if (candidate.nodes.length !== current.nodes.length) {
+        return candidate.nodes.length < current.nodes.length ? candidate : current;
+    }
+    return cycleKey(candidate.nodes) < cycleKey(current.nodes) ? candidate : current;
+}
+function compareComponents(left, right) {
+    const kindDelta = cycleKindRank(left.kind) - cycleKindRank(right.kind);
+    if (kindDelta !== 0) {
+        return kindDelta;
+    }
+    const sizeDelta = right.nodes.length - left.nodes.length;
+    if (sizeDelta !== 0) {
+        return sizeDelta;
+    }
+    return cycleKey(left.representative.nodes).localeCompare(cycleKey(right.representative.nodes));
+}
+function cycleKindRank(kind) {
+    if (kind === "runtime") {
+        return 0;
+    }
+    if (kind === "mixed") {
+        return 1;
+    }
+    return 2;
+}
+function classifyEdges(edges) {
+    const kinds = new Set(edges.map(classifyEdge));
+    if (kinds.size === 0 || kinds.has("mixed") || (kinds.has("runtime") && kinds.has("type-only"))) {
+        return "mixed";
+    }
+    return kinds.has("runtime") ? "runtime" : "type-only";
+}
+function classifyEdge(edge) {
+    const symbols = edge.symbols ?? [];
+    if (symbols.length === 0) {
+        return "runtime";
+    }
+    let hasType = false;
+    let hasRuntime = false;
+    for (const symbol of symbols) {
+        if (typeof symbol === "string") {
+            hasRuntime = true;
+            continue;
+        }
+        if (symbol.usage === "type") {
+            hasType = true;
+        }
+        else {
+            hasRuntime = true;
+        }
+    }
+    if (hasType && hasRuntime) {
+        return "mixed";
+    }
+    return hasType ? "type-only" : "runtime";
+}
+function countEdgeKinds(edges) {
+    const counts = { runtime: 0, "type-only": 0, mixed: 0 };
+    for (const edge of edges) {
+        counts[classifyEdge(edge)] += 1;
+    }
+    return counts;
+}
+function cycleKey(nodes) {
+    return nodes.join("\u0000");
+}
+function formatComponent(component, aliases) {
+    const files = component.nodes.map((node) => compactGraphPath(node, aliases));
+    const cycle = formatCycle(component.representative, aliases);
+    return {
+        kind: component.kind,
+        files,
+        fileCount: files.length,
+        edgeCounts: component.counts,
+        cycle,
+        chain: readString(cycle.chain)
+    };
+}
+function formatCycle(cycle, aliases) {
+    const pathValues = cycle.nodes.map((node) => compactGraphPath(node, aliases));
+    return {
+        kind: cycle.kind,
+        path: pathValues,
+        chain: pathValues.join(" -> "),
+        imports: cycle.edges.map((edge) => formatCycleImport(edge, aliases))
+    };
+}
+function formatCycleImport(edge, aliases) {
+    const from = compactGraphPath(edge.from, aliases);
+    const to = compactGraphPath(edge.to, aliases);
+    const symbols = formatImportSymbols(edge.symbols);
+    return symbols
+        ? `${from} -> ${to}: ${symbols}`
+        : `${from} -> ${to}`;
+}
+function formatImportSymbols(symbols) {
+    const names = (symbols ?? [])
+        .map((symbol) => typeof symbol === "string" ? symbol : symbol.name)
+        .filter((name) => name.length > 0);
+    if (names.length === 0) {
+        return "";
+    }
+    const visible = names.slice(0, 4);
+    return names.length > visible.length
+        ? `${visible.join(" ")} + ${names.length - visible.length} more`
+        : visible.join(" ");
+}
+function buildCyclesViewResponse(artifact, options = {}) {
+    if (artifact.op !== "cycles") {
+        throw new errors_1.CliError("INVALID_CYCLES_RESULT", "Expected a cycles result artifact.");
+    }
+    const detail = options.detail ?? readCyclesDetail(readNestedString(artifact.request, "detail"));
+    const allComponents = Array.isArray(artifact.components) ? artifact.components.filter(isObject) : [];
+    const filteredComponents = options.kind
+        ? allComponents.filter((component) => component.kind === options.kind)
+        : allComponents;
+    const total = filteredComponents.length;
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT);
+    const selectedComponents = options.index !== undefined
+        ? [filteredComponents[options.index - 1]].filter(isObject)
+        : filteredComponents.slice(offset, offset + limit);
+    const hidden = options.index !== undefined ? 0 : Math.max(0, total - offset - selectedComponents.length);
+    const response = {
+        ok: true,
+        op: "cycles",
+        target: readString(artifact.target) ?? "",
+        detail,
+        componentCount: total,
+        summary: summarizeFormattedComponents(filteredComponents),
+        ...(isObject(artifact.analysis) ? { analysis: artifact.analysis } : {}),
+        ...(isObject(artifact.timeoutHint) ? { timeoutHint: artifact.timeoutHint } : {}),
+        components: selectedComponents,
+        offset,
+        limit,
+        ...(options.index !== undefined ? { index: options.index } : {}),
+        ...(hidden > 0 ? { hidden } : {}),
+        ...(options.resultHandle ? { result: options.resultHandle } : {}),
+        ...(artifact.paths ? { paths: artifact.paths } : {})
+    };
+    return (0, agent_text_1.attachAgentText)(response, formatCyclesResponse(response));
+}
+function buildCyclesAnalysis(request, fileCount, edgeCount, focusFileCount, components) {
+    const summary = summarizeComponents(components);
+    const largestComponentFileCount = components.reduce((max, component) => Math.max(max, component.nodes.length), 0);
+    const representativeEdgeCount = components.reduce((count, component) => count + component.representative.edges.length, 0);
+    return {
+        fileCount,
+        edgeCount,
+        focusFileCount,
+        scopeCount: request.scopes.length,
+        detail: request.detail,
+        componentCount: components.length,
+        largestComponentFileCount,
+        representativeEdgeCount,
+        runtimeComponentCount: summary.runtime,
+        mixedComponentCount: summary.mixed,
+        typeOnlyComponentCount: summary["type-only"]
+    };
+}
+function buildCyclesTimeoutHint(analysis) {
+    const fileCount = readNumber(analysis.fileCount);
+    const edgeCount = readNumber(analysis.edgeCount);
+    const componentCount = readNumber(analysis.componentCount);
+    const largestComponentFileCount = readNumber(analysis.largestComponentFileCount);
+    const representativeEdgeCount = readNumber(analysis.representativeEdgeCount);
+    const detail = readString(analysis.detail) ?? "summary";
+    const recommendedTimeoutMs = estimateCyclesTimeoutMs({
+        fileCount,
+        edgeCount,
+        componentCount,
+        largestComponentFileCount,
+        representativeEdgeCount,
+        detail
+    });
+    return {
+        recommendedTimeoutMs,
+        fileCount,
+        edgeCount,
+        componentCount,
+        detail,
+        message: "If cycle analysis runs as a post-mutation phase, inspect progress with: aib execution status last"
+    };
+}
+function estimateCyclesTimeoutMs(input) {
+    const detailCost = input.detail === "imports" ? 1.25 : input.detail === "files" ? 1.1 : 1;
+    const estimate = Math.round((750 +
+        input.fileCount * 1.5 +
+        input.edgeCount * 1.25 +
+        input.componentCount * 4 +
+        input.largestComponentFileCount * 2 +
+        input.representativeEdgeCount * 1.5) * detailCost);
+    return Math.min(CYCLES_ESTIMATE_MAX_MS, Math.max(CYCLES_ESTIMATE_MIN_MS, estimate));
+}
+function summarizeComponents(components) {
+    const summary = { runtime: 0, "type-only": 0, mixed: 0 };
+    for (const component of components) {
+        summary[component.kind] += 1;
+    }
+    return summary;
+}
+function summarizeFormattedComponents(components) {
+    const summary = { runtime: 0, "type-only": 0, mixed: 0 };
+    for (const component of components) {
+        const kind = readCycleKind(component.kind);
+        if (kind) {
+            summary[kind] += 1;
+        }
+    }
+    return summary;
+}
+function createResultId(artifact) {
+    const hash = (0, node_crypto_1.createHash)("sha256")
+        .update(JSON.stringify({
+        target: artifact.target,
+        request: artifact.request,
+        componentCount: artifact.componentCount,
+        components: artifact.components
+    }))
+        .digest("hex")
+        .slice(0, 8);
+    return `res_${hash}`;
+}
+function formatCyclesResponse(response) {
+    if (Array.isArray(response.results)) {
+        const chunks = response.results
+            .filter(isObject)
+            .map(formatCyclesResponse)
+            .filter((chunk) => Boolean(chunk));
+        return chunks.length > 0 ? chunks.join("\n\n") : null;
+    }
+    if (response.op !== "cycles") {
+        return null;
+    }
+    const target = typeof response.target === "string" ? response.target : "";
+    const count = typeof response.componentCount === "number" ? response.componentCount : 0;
+    const lines = [`cycles ${target}`.trim()];
+    if (count === 0) {
+        lines.push(response.index ? "selected component not found" : "no cycles");
+        appendPaths(lines, response.paths);
+        return lines.join("\n");
+    }
+    lines.push(formatCyclesCountLine(count, response.summary), "");
+    if (!singleCycleKind(count, response.summary)) {
+        appendCycleSummary(lines, response.summary);
+    }
+    const components = Array.isArray(response.components) ? response.components.filter(isObject) : [];
+    components.forEach((component, index) => {
+        const files = readStringArray(component.files) ?? [];
+        const displayIndex = typeof response.index === "number"
+            ? response.index
+            : (typeof response.offset === "number" ? response.offset : 0) + index + 1;
+        const prefix = count === 1 && components.length === 1 && !response.index ? "" : `${displayIndex}. `;
+        appendCycleComponentText(lines, component, {
+            detail: response.detail === "files" || response.detail === "imports" ? response.detail : "summary",
+            prefix,
+            indent: prefix ? "   " : ""
+        });
+    });
+    if (typeof response.hidden === "number" && response.hidden > 0) {
+        lines.push(`+ ${response.hidden} more cyclic ${response.hidden === 1 ? "component" : "components"}`);
+    }
+    const resultHandle = readString(response.result);
+    if (resultHandle && typeof response.hidden === "number" && response.hidden > 0) {
+        const nextOffset = (typeof response.offset === "number" ? response.offset : 0) + components.length;
+        const limit = typeof response.limit === "number" ? response.limit : DEFAULT_LIMIT;
+        lines.push(`more: aib view ${resultHandle} --offset ${nextOffset} --limit ${limit}`);
+    }
+    appendPaths(lines, response.paths);
+    return lines.join("\n");
+}
+function appendCycleComponentText(lines, component, options = {}) {
+    const files = readStringArray(component.files) ?? [];
+    const kind = readCycleKind(component.kind) ?? "mixed";
+    const prefix = options.prefix ?? "";
+    const indent = options.indent ?? "";
+    lines.push(`${prefix}${kind}, ${files.length} ${files.length === 1 ? "file" : "files"}`);
+    if (options.detail === "files") {
+        for (const file of files.slice(0, TEXT_COMPONENT_FILE_LIMIT)) {
+            lines.push(`${indent}${file}`);
+        }
+        if (files.length > TEXT_COMPONENT_FILE_LIMIT) {
+            lines.push(`${indent}+ ${files.length - TEXT_COMPONENT_FILE_LIMIT} more files`);
+        }
+    }
+    const cycle = isObject(component.cycle) ? component.cycle : {};
+    const pathValues = readStringArray(cycle.path) ?? pathFromChain(readString(component.chain));
+    if (pathValues.length > 0) {
+        lines.push(`${indent}cycle:`);
+        appendCyclePath(lines, pathValues, indent);
+    }
+    if (options.detail === "imports") {
+        const imports = readStringArray(cycle.imports) ?? readStringArray(component.imports) ?? [];
+        if (imports.length > 0) {
+            lines.push(`${indent}imports:`);
+            for (const item of imports) {
+                lines.push(`${indent}${item}`);
+            }
+        }
+    }
+}
+function formatCyclesCountLine(count, summary) {
+    const kind = singleCycleKind(count, summary);
+    if (kind) {
+        return `${count} ${kind} ${count === 1 ? "cycle" : "cycles"}`;
+    }
+    return `${count} cyclic ${count === 1 ? "component" : "components"}`;
+}
+function singleCycleKind(count, summary) {
+    if (!isObject(summary)) {
+        return null;
+    }
+    const kinds = ["runtime", "mixed", "type-only"];
+    const matches = kinds.filter((kind) => summary[kind] === count);
+    return matches.length === 1 ? matches[0] : null;
+}
+function pathFromChain(chain) {
+    return chain ? chain.split(" -> ").filter((part) => part.trim().length > 0) : [];
+}
+function appendCyclePath(lines, pathValues, indent) {
+    if (pathValues.length > 4) {
+        lines.push(`${indent}${pathValues[0]}`);
+        for (const item of pathValues.slice(1)) {
+            lines.push(`${indent}-> ${item}`);
+        }
+        return;
+    }
+    lines.push(`${indent}${pathValues.join(" -> ")}`);
+}
+function appendCycleSummary(lines, summary) {
+    if (!isObject(summary)) {
+        return;
+    }
+    const runtime = typeof summary.runtime === "number" ? summary.runtime : 0;
+    const mixed = typeof summary.mixed === "number" ? summary.mixed : 0;
+    const typeOnly = typeof summary["type-only"] === "number" ? summary["type-only"] : 0;
+    lines.push(`runtime ${runtime}, mixed ${mixed}, type-only ${typeOnly}`, "");
+}
+function appendPaths(lines, paths) {
+    if (!isObject(paths)) {
+        return;
+    }
+    const entries = Object.entries(paths)
+        .filter((entry) => typeof entry[1] === "string")
+        .sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0) {
+        return;
+    }
+    lines.push("", "paths:");
+    for (const [token, prefix] of entries) {
+        lines.push(`${token} = ${prefix}`);
+    }
+}
+function formatCyclesTarget(cwd, request, aliases) {
+    const values = request.scopes.length > 0 ? request.scopes : request.files;
+    const compacted = values.map((value) => (0, path_display_1.compactDisplayPath)(cwd, value, aliases));
+    if (compacted.length === 1) {
+        return compacted[0];
+    }
+    return `[${compacted.join(",")}]`;
+}
+function compactGraphPath(pathValue, aliases) {
+    return (0, path_display_1.compactDisplayPath)("", pathValue, aliases);
+}
+function usedAliasPayload(serializedResponse, aliases) {
+    const payload = {};
+    for (const alias of aliases) {
+        if (serializedResponse.includes(alias.token)) {
+            payload[alias.token] = alias.prefix;
+        }
+    }
+    return Object.keys(payload).length > 0 ? payload : null;
+}
+function toGraphPath(cwd, filePath) {
+    return (0, path_display_1.toDisplayPath)(cwd, path.resolve(cwd, filePath));
+}
+function expandCyclesPayloadRequests(payload) {
+    if (!isObject(payload)) {
+        return [];
+    }
+    if (Array.isArray(payload.requests)) {
+        return payload.requests.filter(isObject);
+    }
+    return [payload];
+}
+function readFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index < 0) {
+        return null;
+    }
+    const value = args[index + 1];
+    return value && !value.startsWith("--") ? value : null;
+}
+function readFlagValues(args, flag) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== flag) {
+            continue;
+        }
+        const value = args[index + 1];
+        if (value && !value.startsWith("--")) {
+            values.push(...splitList(value));
+            index += 1;
+        }
+    }
+    return values;
+}
+function isFlagValue(args, value) {
+    const index = args.indexOf(value);
+    return index > 0 && args[index - 1]?.startsWith("--") === true;
+}
+function readCyclesDetail(value) {
+    if (value === undefined || value === null || value === "summary" || value === "sum") {
+        return "summary";
+    }
+    if (value === "imports") {
+        return "imports";
+    }
+    if (value === "files") {
+        return "files";
+    }
+    throw new errors_1.CliError("INVALID_CYCLES_DETAIL", "inspect cycles detail expects summary, imports, or files.");
+}
+function readCycleKind(value) {
+    if (value === undefined || value === null || value === "") {
+        return null;
+    }
+    if (value === "runtime" || value === "type-only" || value === "mixed") {
+        return value;
+    }
+    throw new errors_1.CliError("INVALID_CYCLES_KIND", "inspect cycles kind expects runtime, type-only, or mixed.");
+}
+function readPositiveInteger(value) {
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function readNestedString(value, key) {
+    return isObject(value) ? readString(value[key]) : null;
+}
+function readStringArray(value) {
+    if (typeof value === "string" && value.length > 0) {
+        return splitList(value);
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+}
+function splitList(value) {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function uniqueSorted(items) {
+    return Array.from(new Set(items)).sort();
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}