@visulima/cerebro 3.0.0-alpha.30 → 3.0.0-alpha.32

package/dist/packem_shared/VisulimaError-DyMHh9O-.js

@@ -0,0 +1,76 @@
+import{g as b,n as N}from"./renderError-Dqej8k13-BmipVhik.js";import{S as re,s as ne,W as oe,X as ae,c as ie,Y as se,U as ue,R as le}from"./renderError-Dqej8k13-BmipVhik.js";import{h as fe,c as pe}from"./VisulimaError-DTMgXonA-CzaryRgZ.js";const S=(e,t)=>{let r=0,o=t.length-2;for(;r<o;){const n=r+(o-r>>1);if(e<t[n])o=n-1;else if(e>=t[n+1])r=n+1;else{r=n;break}}return r},E=/\n|\r(?!\n)/,P=e=>e.split(E).reduce((t,r)=>(t.push(t.at(-1)+r.length+1),t),[0]),K=(e,t,r)=>{const o=r?.skipChecks??!1;if(!o&&(!Array.isArray(e)&&typeof e!="string"||(typeof e=="string"||Array.isArray(e))&&e.length===0))return{column:0,line:0};if(!o&&(typeof t!="number"||typeof e=="string"&&t>=e.length||Array.isArray(e)&&t+1>=e.at(-1)))return{column:0,line:0};if(typeof e=="string"){const a=P(e),i=S(t,a);return{column:t-a[i]+1,line:i+1}}const n=S(t,e);return{column:t-e[n]+1,line:n+1}},B=({applicationType:e,error:t,file:r})=>`You are a very skilled ${r.language??"unknown"} programmer.
+
+${e?`You are working on a ${e} application.`:""}
+
+Use the following context to find a possible fix for the exception message at the end. Limit your answer to 4 or 5 sentences. Also include a few links to documentation that might help.
+
+Use this format in your answer, make sure links are json:
+
+FIX
+insert the possible fix here
+ENDFIX
+LINKS
+{"title": "Title link 1", "url": "URL link 1"}
+{"title": "Title link 2", "url": "URL link 2"}
+ENDLINKS
+---
+
+Here comes the context and the exception message:
+
+Line: ${String(r.line)}
+
+File:
+${r.file}
+
+Snippet including line numbers:
+${r.snippet??""}
+
+Exception class:
+${t.name}
+
+Exception message:
+${t.message}`,j=(e,t,r)=>{const o=r.indexOf(e);if(o===-1)return"";const n=o+e.length,a=r.indexOf(t,n);return a===-1?"":r.slice(n,a).trim()},X=e=>{const t=j("FIX","ENDFIX",e);if(!t)return["No solution found.",'Provide this response to the Maintainer of <a href="https://github.com/visulima/visulima/issues/new?assignees=&labels=s%3A+pending+triage%2Cc%3A+bug&projects=&template=bug_report.yml" target="_blank" rel="noopener noreferrer" class="text-blue-500 hover:underline inline-flex items-center text-sm">@visulima/error</a>.',`"${e}"`].join("</br></br>");const r=j("LINKS","ENDLINKS",e),o=r?r.split(`
+`).map(a=>a.trim()).filter(Boolean).map(a=>{try{return JSON.parse(a)}catch{return}}).filter(a=>a!==void 0):[],n=o.length>0?`
+
+## Links
+
+${o.map(a=>`- <a href="${a.url}" target="_blank" rel="noopener noreferrer">${a.title}</a>`).join(`
+`)}`:"";return`${t.replaceAll(/"([^"]*)"(?:\s|\.)/g,"<code>$1</code> ")}${n}
+
+--------------------
+This solution was generated with the <a href="https://sdk.vercel.ai/" target="_blank" rel="noopener noreferrer">AI SDK</a> and may not be 100% accurate.`},q={handle:e=>e.hint===void 0?Promise.resolve(void 0):typeof e.hint=="string"&&e.hint!==""?Promise.resolve({body:e.hint}):typeof e.hint=="object"&&typeof e.hint.body=="string"?Promise.resolve(e.hint):Array.isArray(e.hint)?Promise.resolve({body:e.hint.join(`
+`)}):Promise.resolve(void 0),name:"errorHint",priority:1},A=e=>`\`\`\`
+${e.trim()}
+\`\`\``,d=e=>`\`\`\`bash
+${e.trim()}
+\`\`\``,h=e=>`\`\`\`ts
+${e.trim()}
+\`\`\``,I=e=>`\`\`\`js
+${e.trim()}
+\`\`\``,c=(e,...t)=>{const r=e.toLowerCase();return t.some(o=>r.includes(o.toLowerCase()))},T=[{name:"esm-cjs-interop",test:e=>{const{message:t}=e;if(c(t,"err_require_esm","cannot use import statement outside a module","must use import to load es module","require() of es module","does not provide an export named"))return{md:["Your project or a dependency may be mixing CommonJS and ES Modules.","","Try:","- Ensure package.json has the correct `type` (either `module` or `commonjs`).","- Use dynamic `import()` when requiring ESM from CJS.","- Prefer ESM-compatible entrypoints from dependencies.","- In Node, align `module` resolution with your bundler config.","","Check Node resolution:",d(`node -v
+cat package.json | jq .type`),"","Example dynamic import in CJS:",I("(async () => { const mod = await import('some-esm'); mod.default(); })();")].join(`
+`),title:"ESM/CJS interop"}}},{name:"missing-default-export",test:e=>{const{message:t}=e;if(c(t,"default export not found","has no default export","does not provide an export named 'default'","is not exported from"))return{md:["Verify your import/export shapes.","","Default export example:",h(`export default function Component() {}
+// import Component from './file'`),"","Named export example:",h(`export function Component() {}
+// import { Component } from './file'`)].join(`
+`),title:"Export mismatch (default vs named)"}}},{name:"port-in-use",test:e=>{const{message:t}=e;if(c(t,"eaddrinuse","address already in use","listen eaddrinuse"))return{md:["Another process is using the port.","","Change the port or stop the other process.","","On macOS/Linux:",d(`lsof -i :3000
+kill -9 <PID>`),"","On Windows (PowerShell):",d(`netstat -ano | findstr :3000
+taskkill /PID <PID> /F`)].join(`
+`),title:"Port already in use"}}},{name:"file-not-found-or-case",test:(e,t)=>{const{message:r}=e;if(c(r,"enoent","module not found","cannot find module"))return{md:["Check the import path and filename case (Linux/macOS are case-sensitive).","If using TS path aliases, verify `tsconfig.paths` and bundler aliases.","","Current file:",A(`${t.file}:${String(t.line)}`)].join(`
+`),title:"Missing file or path case mismatch"}}},{name:"ts-path-mapping",test:e=>{const{message:t}=e;if(c(t,"ts2307","cannot find module")||t.includes("TS2307"))return{md:["If you use path aliases, align TS `paths` with Vite/Webpack resolve aliases.","Ensure file extensions are correct and included in resolver.","","tsconfig.json excerpt:",h(`{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  }
+}`)].join(`
+`),title:"TypeScript path mapping / resolution"}}},{name:"network-dns-enotfound",test:e=>{const{message:t}=e;if(c(t,"enotfound","getaddrinfo enotfound","dns","fetch failed","ecconnrefused","econnrefused"))return{md:["The host may be unreachable or misconfigured.","","Try:","- Verify the hostname and protocol (http/https).","- Check VPN/proxy and firewall.","- Confirm the service is running and listening on the expected port.","",d(`ping <host>
+nslookup <host>
+curl -v http://<host>:<port>`)].join(`
+`),title:"Network/DNS connection issue"}}},{name:"undefined-property",test:e=>{const{message:t}=e;if(c(t,"cannot read properties of undefined","reading '"))return{md:["A variable or function returned `undefined`.","","Mitigations:","- Add nullish checks before property access.","- Validate function return values and input props/state.","",h("const value = maybe?.prop; // or: if (maybe) { use(maybe.prop) }")].join(`
+`),title:"Accessing property of undefined"}}}],H={handle:(e,t)=>{try{const r=T.map(n=>({match:n.test(e,t),rule:n})).filter(n=>!!n.match);if(r.length===0)return Promise.resolve(void 0);const o=r.toSorted((n,a)=>(n.match.priority??0)-(a.match.priority??0)).map(n=>`#### ${n.match.title}
+
+${n.match.md}`).join(`
+
+---
+
+`);return o===""?Promise.resolve(void 0):Promise.resolve({body:o,header:"### Potential fixes detected"})}catch{return Promise.resolve(void 0)}},name:"ruleBasedHints",priority:0};let p=class extends Error{constructor(t){super(t),this.name="NonError"}};const z=()=>{if(!Error.captureStackTrace)return;const e=new Error;return Error.captureStackTrace(e),e.stack},x=e=>{if(typeof e!="object"||e===null)return!1;const t=Object.getPrototypeOf(e);return t===null||t===Object.prototype||Object.getPrototypeOf(t)===null},_={maxDepth:Number.POSITIVE_INFINITY},$=(e,t,r=0)=>b(e)?v(e,t,r):t.maxDepth!==void 0&&r>=t.maxDepth?new p(JSON.stringify(e)):new p(JSON.stringify(e)),C=(e,t,r,o,n)=>{const a=t.map(i=>l(i,o,n+1));return new e(a,r)},v=(e,t,r)=>{if(t.maxDepth!==void 0&&r>=t.maxDepth)return new p(JSON.stringify(e));const{cause:o,errors:n,message:a,name:i,stack:s,...m}=e,O=N(i)??Error,u=i==="AggregateError"&&Array.isArray(n)?C(O,n,a,t,r):new O(a);return!u.name&&i&&(u.name=i),a!==void 0&&(u.message=a),s&&(u.stack=s),D(u,m,o,i,t,r),o!==void 0&&(u.cause=l(o,t,r+1)),J(u,e),u},l=(e,t,r)=>{if(x(e)){if(e.__dataType==="Map"&&Array.isArray(e.value))return new Map(e.value.map(([n,a])=>[l(n,t,r+1),l(a,t,r+1)]));if(e.__dataType==="Set"&&Array.isArray(e.value))return new Set(e.value.map(n=>l(n,t,r+1)));if(b(e))return $(e,t,r);const o={};for(const[n,a]of Object.entries(e))n==="__proto__"||n==="constructor"||n==="prototype"||(o[n]=l(a,t,r+1));return o}return Array.isArray(e)?e.map(o=>l(o,t,r)):e},D=(e,t,r,o,n,a)=>{const i=e;for(const[s,m]of Object.entries(t))if(!(s==="__proto__"||s==="constructor"||s==="prototype")){if(s==="cause"&&r!==void 0||s==="errors"&&o==="AggregateError")continue;Object.defineProperty(i,s,{configurable:!0,enumerable:!0,value:l(m,n,a+1),writable:!0})}},J=(e,t)=>{const r=new Set(["message","name","stack"]);for(const o of Object.keys(t))r.add(o);for(const o of r)if(o in e){const n=Object.getOwnPropertyDescriptor(e,o);n&&!n.enumerable&&Object.defineProperty(e,o,{...n,enumerable:!0})}},w=e=>new p(JSON.stringify(e)),F=e=>new p(JSON.stringify(e)),L=(e,t)=>b(e)?v(e,t,0):$(e,t),G=(e,t={})=>{const r={..._,...t};return e instanceof Error?e:e===null?w(null):typeof e=="string"||typeof e=="number"||typeof e=="boolean"?w(e):Array.isArray(e)?F(e):b(e)?v(e,r,0):x(e)?L(e,r):new p(JSON.stringify(e))},M=e=>{const t=e.methodName&&e.methodName!=="<unknown>"?`${e.methodName} `:"",r=e.file??"<unknown>",o=String(e.line??0),n=String(e.column??0);return t.trim()?`    at ${t}(${r}:${o}:${n})`:`    at ${r}:${o}:${n}`},Q=(e,t)=>{const r=[];if(t?.header&&(t.header.name||t.header.message)){const o=t.header.name??"Error",n=t.header.message??"";r.push(`${o}${n?": ":""}${n}`)}for(const o of e)r.push(M(o));return r.join(`
+`)},R=Object.create({},{cause:{enumerable:!1,value:void 0,writable:!0},code:{enumerable:!0,value:void 0,writable:!0},errors:{enumerable:!1,value:void 0,writable:!0},message:{enumerable:!1,value:void 0,writable:!0},name:{enumerable:!1,value:void 0,writable:!0},stack:{enumerable:!1,value:void 0,writable:!0}}),U=e=>{if(typeof e!="object"||e===null)return!1;const t=Object.getPrototypeOf(e);return t===null||t===Object.prototype||Object.getPrototypeOf(t)===null},g=new WeakSet,k=e=>{const t=Object.getOwnPropertyNames(e);for(const r of t){const o=Object.getOwnPropertyDescriptor(e,r);o&&(o.enumerable||Object.defineProperty(e,r,{...o,enumerable:!0}),o.value&&typeof o.value=="object"&&!Array.isArray(o.value)&&(Object.getPrototypeOf(o.value)===Object.prototype||Object.getPrototypeOf(o.value)===null)&&k(o.value))}},V=e=>{g.add(e);const t=e.toJSON();return g.delete(e),Object.isExtensible(t)&&k(t),t},f=(e,t,r,o,n=new Set)=>{if(e&&e instanceof Uint8Array&&e.constructor.name==="Buffer")return"[object Buffer]";if(e!==null&&typeof e=="object"&&"pipe"in e&&typeof e.pipe=="function")return"[object Stream]";if(e instanceof Error)return t.has(e)?"[Circular]":(r+=1,y(e,o,t,r));if(o.useToJSON&&e!==null&&typeof e=="object"&&"toJSON"in e&&typeof e.toJSON=="function")return e.toJSON();if(e instanceof Date)return e.toISOString();if(e instanceof RegExp)return e.toString();if(typeof URL<"u"&&e instanceof URL)return e.href;if(e instanceof Map){const a=[];for(const[i,s]of e.entries())a.push([f(i,t,r,o,n),f(s,t,r,o,n)]);return{__dataType:"Map",value:a}}if(e instanceof Set){const a=[];for(const i of e.values())a.push(f(i,t,r,o,n));return{__dataType:"Set",value:a}}if(typeof e=="function")return`[Function: ${e.name||"anonymous"}]`;if(typeof e=="bigint")return`${String(e)}n`;if(U(e)){if(n.has(e))return"[Circular]";if(o.maxDepth!==void 0&&o.maxDepth!==Number.POSITIVE_INFINITY&&r+1>=o.maxDepth)return{};r+=1,n.add(e);const a={};for(const i in e)a[i]=f(e[i],t,r,o,n);return n.delete(e),a}try{return e}catch{return"[Not Available]"}},y=(e,t,r,o)=>{if(r.add(e),t.maxDepth===0)return{};if(t.useToJSON&&typeof e.toJSON=="function"&&!g.has(e))return V(e);const n=Object.create(R);if(Object.defineProperty(n,"name",{configurable:!0,enumerable:!0,value:Object.prototype.toString.call(e.constructor)==="[object Function]"?e.constructor.name:e.name,writable:!0}),Object.defineProperty(n,"message",{configurable:!0,enumerable:!0,value:e.message,writable:!0}),Object.defineProperty(n,"stack",{configurable:!0,enumerable:!0,value:e.stack,writable:!0}),Array.isArray(e.errors)){const i=[];for(const s of e.errors){if(!(s instanceof Error))throw new TypeError("All errors in the 'errors' property must be instances of Error");if(r.has(s))return Object.defineProperty(n,"errors",{configurable:!0,enumerable:!0,value:[],writable:!0}),n;i.push(y(s,t,r,o))}Object.defineProperty(n,"errors",{configurable:!0,enumerable:!0,value:i,writable:!0})}const a=e.cause;if(a!=null)if(a instanceof Error)r.has(a)?Object.defineProperty(n,"cause",{configurable:!0,enumerable:!0,value:"[Circular]",writable:!0}):Object.defineProperty(n,"cause",{configurable:!0,enumerable:!0,value:y(a,t,r,o),writable:!0});else{const i=f(a,r,o,t);Object.defineProperty(n,"cause",{configurable:!0,enumerable:!0,value:i,writable:!0})}for(const i in e){if(i==="name"||i==="message"||i==="stack"||i==="cause"||i==="errors")continue;const s=e[i],m=f(s,r,o,t);Object.defineProperty(n,i,{configurable:!0,enumerable:!0,value:m,writable:!0})}if(Array.isArray(t.exclude)&&t.exclude.length>0)for(const i of t.exclude)try{delete n[i]}catch{}return n},Z=(e,t={})=>y(e,{exclude:t.exclude??[],maxDepth:t.maxDepth??Number.POSITIVE_INFINITY,useToJSON:t.useToJSON??!1},new Set,0);export{re as CODE_FRAME_POINTER,p as NonError,fe as VisulimaError,ne as addKnownErrorConstructor,B as aiPrompt,X as aiSolutionResponse,z as captureRawStackTrace,oe as codeFrame,ae as composeFilters,G as deserializeError,q as errorHintFinder,M as formatStackFrameLine,Q as formatStacktrace,ie as getErrorCauses,K as indexToLineColumn,b as isErrorLike,pe as isVisulimaError,se as parseStacktrace,ue as renderError,H as ruleBasedFinder,Z as serializeError,le as stackFilters};

package/dist/packem_shared/cerebro-error-z8DS5U8c.js

@@ -0,0 +1 @@
+import"./renderError-Dqej8k13-BmipVhik.js";import{h as r}from"./VisulimaError-DTMgXonA-CzaryRgZ.js";class n extends r{code;context;constructor(e,t,o){super({message:e,name:"CerebroError"}),this.code=t,this.context=o}}export{n as t};

package/dist/packem_shared/{plugin-manager.d-BSQtHbWS.d.ts → command.d-DbhtfXF4.d.ts}

@@ -1,8 +1,12 @@
 import { TableOptions } from '@visulima/tabular';
 /**
 * Definition for a command-line option.
+*
+* The optional `Name` and `Value` type parameters allow {@link CommandLineOptions}
+* to be inferred from an `as const` array of definitions. They default to the
+* loose runtime shape so plain `OptionDefinition` usage is unaffected.
 */
-interface OptionDefinition$1 {
+interface OptionDefinition$1<Name extends string = string, Value = unknown> {
   /**
   * A getopt-style short option name. Can be any single character except a digit or hyphen.
   */
@@ -15,7 +19,7 @@ interface OptionDefinition$1 {
   /**
   * An initial value for the option.
   */
-  defaultValue?: any;
+  defaultValue?: Value;
   /**
   * One or more group names the option belongs to.
   */
@@ -31,15 +35,19 @@ interface OptionDefinition$1 {
   /**
   * The long option name.
   */
-  name: string;
+  name: Name;
   /**
   * A setter function (you receive the output from this) enabling you to be specific about the type and value received. Typical values
   * are `String` (the default), `Number` and `Boolean` but you can use a custom function. If no option value was set you will receive `null`.
   */
-  type?: (input: string) => any;
+  type?: (input: string) => Value;
 }
 /**
-* Error thrown when an option is already set (duplicate assignment).
+* Resolve a single {@link OptionDefinition} to the type of its parsed value,
+* taking `type`, `multiple`/`lazyMultiple` and `defaultValue` into account.
+*
+* Part of the public type surface: re-exported from the package entry and used by
+* {@link InferCommandLineOptions}.
 */
 /** A Content section comprises a header and one or more lines of content. */
 interface Content {
@@ -60,6 +68,217 @@ interface Content {
   raw?: boolean;
 }
 /**
+* Context provided to plugins during initialization
+*/
+interface PluginContext<T extends Console = Console> {
+  /** The CLI instance */
+  cli: Cli<T>;
+  /** Current working directory */
+  cwd: string;
+  /** Logger instance */
+  logger: T;
+}
+/**
+* Plugin interface with lifecycle hooks
+*/
+interface Plugin<T extends Console = Console> {
+  /**
+  * Called after command execution completes successfully
+  * @param toolbox The command toolbox
+  * @param result The result returned by the command
+  */
+  afterCommand?: (toolbox: Toolbox<T>, result: unknown) => Promise<void> | void;
+  /**
+  * Called before command execution
+  * @param toolbox The command toolbox
+  */
+  beforeCommand?: (toolbox: Toolbox<T>) => Promise<void> | void;
+  /** Plugin dependencies (other plugin names that must be loaded first) */
+  dependencies?: string[];
+  /** Plugin description */
+  description?: string;
+  /**
+  * Called during command execution (for plugins that extend toolbox functionality)
+  * @param toolbox The command toolbox
+  */
+  execute?: (toolbox: Toolbox<T>) => Promise<void> | void;
+  /**
+  * Called once during plugin initialization
+  * @param context The plugin context
+  */
+  init?: (context: PluginContext<T>) => Promise<void> | void;
+  /** Plugin name (must be unique) */
+  name: string;
+  /**
+  * Called when an error occurs during command execution
+  * @param error The error that occurred
+  * @param toolbox The command toolbox
+  */
+  onError?: (error: Error, toolbox: Toolbox<T>) => Promise<void> | void;
+  /** Plugin version */
+  version?: string;
+}
+type Logger = Console;
+/**
+* Manages plugin lifecycle and execution
+*/
+declare class PluginManager<T extends Logger = Logger> {
+  private readonly logger;
+  private readonly plugins;
+  private initialized;
+  private cachedDependencyOrder;
+  constructor(logger: T);
+  /**
+  * Checks if any plugins are registered.
+  * @returns True if at least one plugin is registered
+  */
+  hasPlugins(): boolean;
+  /**
+  * Registers a plugin.
+  * @param plugin The plugin to register
+  * @throws {Error} If plugin name is already registered or dependencies are invalid
+  */
+  register(plugin: Plugin<T>): void;
+  /**
+  * Initializes all registered plugins.
+  * @param context The plugin context for initialization
+  */
+  init(context: PluginContext<T>): Promise<void>;
+  /**
+  * Executes a specific lifecycle hook for all plugins.
+  * @param hook The lifecycle hook name
+  * @param toolbox The command toolbox (for command-specific hooks)
+  * @param result The command result (for afterCommand hook)
+  */
+  executeLifecycle(hook: "beforeCommand" | "afterCommand" | "execute", toolbox: Toolbox<T>, result?: unknown): Promise<void>;
+  /**
+  * Executes error handlers for all plugins.
+  * @param error The error that occurred
+  * @param toolbox The command toolbox
+  */
+  executeErrorHandlers(error: Error, toolbox: Toolbox<T>): Promise<void>;
+  /**
+  * Gets all registered plugins in dependency order.
+  * @returns Array of plugins sorted by dependencies
+  */
+  getDependencyOrder(): Plugin<T>[];
+  /**
+  * Validates that all plugin dependencies exist.
+  * @throws {Error} If any dependencies are missing
+  */
+  private validateDependencies;
+}
+type CommandSection = {
+  footer?: string;
+  header?: string;
+};
+type CliRunOptions = {
+  [key: string]: unknown;
+  /**
+  * Whether to automatically dispose/cleanup the CLI instance after execution
+  * @default true
+  */
+  autoDispose?: boolean;
+  shouldExitProcess?: boolean;
+};
+type RunCommandOptions = {
+  /**
+  * Extra options to merge into the command's options.
+  * These will be merged with the command's default options and parsed arguments.
+  * Use this to override or add additional options programmatically.
+  * @default Empty object
+  */
+  [key: string]: unknown;
+  /**
+  * Command-line arguments to pass to the command.
+  * If not provided, uses the default argv from the CLI instance.
+  * These arguments will be parsed and merged with the command's options.
+  * @default Empty array
+  */
+  argv?: string[];
+};
+interface Cli<T extends Console> {
+  /**
+  * Add an arbitrary command to the CLI.
+  * @param command The command to add.
+  * @returns self
+  */
+  addCommand: <OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: Command<OD, T>) => this;
+  /**
+  * Add a global option available to all commands.
+  * Global options are parsed alongside command options and shown in help output.
+  * @param option The option definition
+  * @returns self
+  */
+  addGlobalOption: <V = unknown>(option: OptionDefinition<V>) => this;
+  /**
+  * Add a plugin to extend the CLI functionality
+  * @param plugin The plugin to add.
+  * @returns self
+  */
+  addPlugin: (plugin: Plugin<T>) => this;
+  /**
+  * Disposes the CLI instance and cleans up resources
+  * @returns void
+  */
+  dispose: () => void;
+  getCliName: () => string;
+  getCommands: () => Map<string, Command<OptionDefinition<unknown>, T>>;
+  getCommandSection: () => CommandSection;
+  getCwd: () => string;
+  /**
+  * Gets all global options (built-in + custom).
+  */
+  getGlobalOptions: () => OptionDefinition<unknown>[];
+  getPackageName: () => string | undefined;
+  getPackageVersion: () => string | undefined;
+  /**
+  * Get the plugin manager instance
+  * @returns The plugin manager
+  */
+  getPluginManager: () => PluginManager<T>;
+  run: (extraOptions?: CliRunOptions) => Promise<void>;
+  /**
+  * Runs a command programmatically from within another command.
+  * This allows commands to call other commands during execution.
+  * @param commandName The name of the command to execute
+  * @param options Optional options including argv and other command options
+  * @returns A promise that resolves with the command's result (or void if command doesn't return a value)
+  * @throws {Error} If the specified command doesn't exist or command arguments are invalid
+  * @example
+  * ```typescript
+  * cli.addCommand({
+  *   name: 'deploy',
+  *   execute: async ({ runtime, logger }) => {
+  *     logger.info('Building...');
+  *     const buildResult = await runtime.runCommand('build', { argv: ['--production'] });
+  *     // buildResult is the return value from the build command's execute function
+  *
+  *     logger.info('Testing...');
+  *     await runtime.runCommand('test', { argv: ['--coverage'] });
+  *   }
+  * });
+  * ```
+  */
+  runCommand: (commandName: string, options?: RunCommandOptions) => Promise<unknown>;
+  setCommandSection: (commandSection: CommandSection) => this;
+  /**
+  * Set a default command, to display a different command if cli is call without command.
+  * @param commandName
+  * @returns self
+  */
+  setDefaultCommand: (commandName: string) => this;
+}
+/**
+* Any of the output types [[OUTPUT_NORMAL]], [[OUTPUT_RAW]] and [[OUTPUT_PLAIN]].
+*/
+type OutputType = 1 | 2 | 4;
+/**
+* Any of the verbosity types
+* [[VERBOSITY_QUIET]], [[VERBOSITY_NORMAL]], [[VERBOSITY_VERBOSE]] and [[VERBOSITY_DEBUG]].
+*/
+type VERBOSITY_LEVEL = 16 | 32 | 64 | 128 | 256;
+/**
 * A flexible object for the many "options" objects we throw around in cerebro.
 */
 type Options = Record<string | symbol, unknown>;
@@ -268,6 +487,17 @@ type MultiplePropertyOptions<T> = T extends ReadonlyArray<unknown> ? {
   multiple: true;
 } : unknown;
 type OptionDefinition<T> = MultiplePropertyOptions<T> & Omit<OptionDefinition$1, "type|defaultValue"> & {
+  /**
+  * Restricts the accepted values for this option to a fixed set, validated
+  * at parse time (like commander's `.choices()` / yargs `choices`). The
+  * provided value(s) are compared by string equality; for `multiple`
+  * options every provided value must be a member of the set.
+  * @example
+  * ```typescript
+  * { name: "format", type: String, choices: ["json", "yaml", "table"] }
+  * ```
+  */
+  choices?: ReadonlyArray<string>;
   /**
   * A string or array of strings indicating the conflicting option(s).
   * Note: The default value for an option does not cause a conflict.
@@ -406,215 +636,4 @@ interface Command<O extends OptionDefinition<unknown> = OptionDefinition<unknown
   options?: (O | OptionDefinition<boolean[]> | OptionDefinition<boolean> | OptionDefinition<number[]> | OptionDefinition<number> | OptionDefinition<string[]> | OptionDefinition<string>)[];
   usage?: Content[];
 }
-type CommandSection = {
-  footer?: string;
-  header?: string;
-};
-type CliRunOptions = {
-  [key: string]: unknown;
-  /**
-  * Whether to automatically dispose/cleanup the CLI instance after execution
-  * @default true
-  */
-  autoDispose?: boolean;
-  shouldExitProcess?: boolean;
-};
-type RunCommandOptions = {
-  /**
-  * Extra options to merge into the command's options.
-  * These will be merged with the command's default options and parsed arguments.
-  * Use this to override or add additional options programmatically.
-  * @default Empty object
-  */
-  [key: string]: unknown;
-  /**
-  * Command-line arguments to pass to the command.
-  * If not provided, uses the default argv from the CLI instance.
-  * These arguments will be parsed and merged with the command's options.
-  * @default Empty array
-  */
-  argv?: string[];
-};
-interface Cli<T extends Console> {
-  /**
-  * Add an arbitrary command to the CLI.
-  * @param command The command to add.
-  * @returns self
-  */
-  addCommand: <OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: Command<OD, T>) => this;
-  /**
-  * Add a global option available to all commands.
-  * Global options are parsed alongside command options and shown in help output.
-  * @param option The option definition
-  * @returns self
-  */
-  addGlobalOption: <V = unknown>(option: OptionDefinition<V>) => this;
-  /**
-  * Add a plugin to extend the CLI functionality
-  * @param plugin The plugin to add.
-  * @returns self
-  */
-  addPlugin: (plugin: Plugin<T>) => this;
-  /**
-  * Disposes the CLI instance and cleans up resources
-  * @returns void
-  */
-  dispose: () => void;
-  getCliName: () => string;
-  getCommands: () => Map<string, Command<OptionDefinition<unknown>, T>>;
-  getCommandSection: () => CommandSection;
-  getCwd: () => string;
-  /**
-  * Gets all global options (built-in + custom).
-  */
-  getGlobalOptions: () => OptionDefinition<unknown>[];
-  getPackageName: () => string | undefined;
-  getPackageVersion: () => string | undefined;
-  /**
-  * Get the plugin manager instance
-  * @returns The plugin manager
-  */
-  getPluginManager: () => PluginManager<T>;
-  run: (extraOptions?: CliRunOptions) => Promise<void>;
-  /**
-  * Runs a command programmatically from within another command.
-  * This allows commands to call other commands during execution.
-  * @param commandName The name of the command to execute
-  * @param options Optional options including argv and other command options
-  * @returns A promise that resolves with the command's result (or void if command doesn't return a value)
-  * @throws {Error} If the specified command doesn't exist or command arguments are invalid
-  * @example
-  * ```typescript
-  * cli.addCommand({
-  *   name: 'deploy',
-  *   execute: async ({ runtime, logger }) => {
-  *     logger.info('Building...');
-  *     const buildResult = await runtime.runCommand('build', { argv: ['--production'] });
-  *     // buildResult is the return value from the build command's execute function
-  *
-  *     logger.info('Testing...');
-  *     await runtime.runCommand('test', { argv: ['--coverage'] });
-  *   }
-  * });
-  * ```
-  */
-  runCommand: (commandName: string, options?: RunCommandOptions) => Promise<unknown>;
-  setCommandSection: (commandSection: CommandSection) => this;
-  /**
-  * Set a default command, to display a different command if cli is call without command.
-  * @param commandName
-  * @returns self
-  */
-  setDefaultCommand: (commandName: string) => this;
-}
-/**
-* Any of the output types [[OUTPUT_NORMAL]], [[OUTPUT_RAW]] and [[OUTPUT_PLAIN]].
-*/
-type OutputType = 1 | 2 | 4;
-/**
-* Any of the verbosity types
-* [[VERBOSITY_QUIET]], [[VERBOSITY_NORMAL]], [[VERBOSITY_VERBOSE]] and [[VERBOSITY_DEBUG]].
-*/
-type VERBOSITY_LEVEL = 16 | 32 | 64 | 128 | 256;
-/**
-* Context provided to plugins during initialization
-*/
-interface PluginContext<T extends Console = Console> {
-  /** The CLI instance */
-  cli: Cli<T>;
-  /** Current working directory */
-  cwd: string;
-  /** Logger instance */
-  logger: T;
-}
-/**
-* Plugin interface with lifecycle hooks
-*/
-interface Plugin<T extends Console = Console> {
-  /**
-  * Called after command execution completes successfully
-  * @param toolbox The command toolbox
-  * @param result The result returned by the command
-  */
-  afterCommand?: (toolbox: Toolbox<T>, result: unknown) => Promise<void> | void;
-  /**
-  * Called before command execution
-  * @param toolbox The command toolbox
-  */
-  beforeCommand?: (toolbox: Toolbox<T>) => Promise<void> | void;
-  /** Plugin dependencies (other plugin names that must be loaded first) */
-  dependencies?: string[];
-  /** Plugin description */
-  description?: string;
-  /**
-  * Called during command execution (for plugins that extend toolbox functionality)
-  * @param toolbox The command toolbox
-  */
-  execute?: (toolbox: Toolbox<T>) => Promise<void> | void;
-  /**
-  * Called once during plugin initialization
-  * @param context The plugin context
-  */
-  init?: (context: PluginContext<T>) => Promise<void> | void;
-  /** Plugin name (must be unique) */
-  name: string;
-  /**
-  * Called when an error occurs during command execution
-  * @param error The error that occurred
-  * @param toolbox The command toolbox
-  */
-  onError?: (error: Error, toolbox: Toolbox<T>) => Promise<void> | void;
-  /** Plugin version */
-  version?: string;
-}
-type Logger = Console;
-/**
-* Manages plugin lifecycle and execution
-*/
-declare class PluginManager<T extends Logger = Logger> {
-  private readonly logger;
-  private readonly plugins;
-  private initialized;
-  private cachedDependencyOrder;
-  constructor(logger: T);
-  /**
-  * Checks if any plugins are registered.
-  * @returns True if at least one plugin is registered
-  */
-  hasPlugins(): boolean;
-  /**
-  * Registers a plugin.
-  * @param plugin The plugin to register
-  * @throws {Error} If plugin name is already registered or dependencies are invalid
-  */
-  register(plugin: Plugin<T>): void;
-  /**
-  * Initializes all registered plugins.
-  * @param context The plugin context for initialization
-  */
-  init(context: PluginContext<T>): Promise<void>;
-  /**
-  * Executes a specific lifecycle hook for all plugins.
-  * @param hook The lifecycle hook name
-  * @param toolbox The command toolbox (for command-specific hooks)
-  * @param result The command result (for afterCommand hook)
-  */
-  executeLifecycle(hook: "beforeCommand" | "afterCommand" | "execute", toolbox: Toolbox<T>, result?: unknown): Promise<void>;
-  /**
-  * Executes error handlers for all plugins.
-  * @param error The error that occurred
-  * @param toolbox The command toolbox
-  */
-  executeErrorHandlers(error: Error, toolbox: Toolbox<T>): Promise<void>;
-  /**
-  * Gets all registered plugins in dependency order.
-  * @returns Array of plugins sorted by dependencies
-  */
-  getDependencyOrder(): Plugin<T>[];
-  /**
-  * Validates that all plugin dependencies exist.
-  * @throws {Error} If any dependencies are missing
-  */
-  private validateDependencies;
-}
 export { ArgumentDefinition as A, Command as C, EnvDefinition as E, LazyCommandModule as L, OptionDefinition as O, Plugin as P, RunCommandOptions as R, Toolbox as T, VERBOSITY_LEVEL as V, CerebroFs as a, CommandSection as b, PluginManager as c, CliRunOptions as d, CommandExecute as e, Cli as f, CerebroProcess as g, OutputType as h, PluginContext as i };