@stacksjs/tinker 0.75.539 → 0.75.542

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { Subprocess } from 'bun';
-export type { Subprocess };
+import { serialize } from './serialize';
+import type { TinkerValue } from './serialize';
 /**
  * Get the path to the tinker history file.
  */
@@ -22,30 +22,25 @@ export declare function appendHistory(entry: string, config?: TinkerConfig): voi
  * Clear the tinker history file.
  */
 export declare function clearHistory(config?: TinkerConfig): void;
+/** Print a described value for a terminal. The inverse of `serialize`, lossy on purpose. */
+export declare function renderValue(value: TinkerValue, indent?: string): string;
+/** Whether a parse failure means "keep typing" rather than "this is wrong". */
+export declare function isIncompleteSnippet(code: string, cwd: string): boolean;
 /**
- * Start an interactive Stacks tinker session.
+ * Start a Stacks tinker session.
  *
- * Launches Bun's built-in REPL with all Stacks framework modules
- * preloaded into the global scope. ORM models, database, config,
- * logging, and other framework utilities are immediately available.
+ * Boots the app in this process (config overrides, then models, jobs and
+ * framework helpers as globals) and evaluates TypeScript against it. Without
+ * `eval`, `print` or `serve` it is an interactive prompt whose declarations
+ * persist from line to line.
  *
  * @example
  * ```ts
  * import { startTinker } from '@stacksjs/tinker'
  *
- * await startTinker()
- * ```
- *
- * @example
- * ```ts
- * // Evaluate a single expression
- * await startTinker({ eval: 'await User.count()' })
- * ```
- *
- * @example
- * ```ts
- * // Evaluate and print
- * await startTinker({ print: 'await User.all()' })
+ * await startTinker()                                  // interactive
+ * await startTinker({ print: 'await User.count()' })   // evaluate, print, exit
+ * await startTinker({ serve: true })                   // speak the frame protocol on stdio
  * ```
  */
 export declare function startTinker(config?: TinkerConfig): Promise<{ exitCode: number }>;
@@ -65,7 +60,11 @@ export declare interface TinkerConfig {
   cwd?: string
   banner?: boolean
   stacksPreload?: boolean
+  serve?: boolean
   eval?: string
   print?: string
   verbose?: boolean
 }
+export * from './protocol';
+export * from './serialize';
+export * from './session';

package/dist/index.js

@@ -1,138 +1,42 @@
 // @bun
-import{existsSync as d,readFileSync as y,writeFileSync as c,appendFileSync as f,chmodSync as p}from"fs";import{homedir as k}from"os";import{join as u}from"path";import n from"process";function g(t){let e=[];if(t.stacksPreload!==!1)e.push(`
-// ---- Stacks Framework Preload ----
-// ORM & Database
-try {
-  const { db } = await import('@stacksjs/database')
-  globalThis.db = db
-} catch {}
-
-try {
-  const orm = await import('@stacksjs/orm')
-  // Expose all ORM exports globally (User, Post, etc.)
-  for (const [key, value] of Object.entries(orm)) {
-    if (key !== 'default' && key !== 'db') {
-      globalThis[key] = value
-    }
-  }
-} catch {}
-
-// Config
-try {
-  const config = await import('@stacksjs/config')
-  globalThis.config = config
-} catch {}
-
-// Path utilities
-try {
-  const path = await import('@stacksjs/path')
-  globalThis.path = path
-} catch {}
-
-// Storage
-try {
-  const storage = await import('@stacksjs/storage')
-  globalThis.storage = storage
-} catch {}
-
-// Validation
-try {
-  const validation = await import('@stacksjs/validation')
-  globalThis.validation = validation
-} catch {}
-
-// Logging
-try {
-  const { log } = await import('@stacksjs/cli')
-  globalThis.log = log
-} catch {}
-
-// Collections
-try {
-  const collections = await import('@stacksjs/collections')
-  globalThis.collect = collections.collect ?? collections.default
-} catch {}
-
-// Strings
-try {
-  const strings = await import('@stacksjs/strings')
-  globalThis.Str = strings
-} catch {}
-
-// Cache
-try {
-  const cache = await import('@stacksjs/cache')
-  globalThis.cache = cache
-} catch {}
-
-// Queue / Jobs
-try {
-  const queue = await import('@stacksjs/queue')
-  globalThis.queue = queue
-} catch {}
-
-// Events
-try {
-  const events = await import('@stacksjs/events')
-  globalThis.events = events
-} catch {}
-
-// Router
-try {
-  const router = await import('@stacksjs/router')
-  globalThis.router = router
-} catch {}
-
-// Auth
-try {
-  const auth = await import('@stacksjs/auth')
-  globalThis.auth = auth
-} catch {}
-
-// Notifications
-try {
-  const notifications = await import('@stacksjs/notifications')
-  globalThis.notifications = notifications
-} catch {}
-
-// Env / environment helpers
-try {
-  const env = await import('@stacksjs/env')
-  globalThis.env = env
-} catch {}
-
-// validate() shortcut \u2014 paired with schema for fluent validation in REPL.
-try {
-  const { validate } = await import('@stacksjs/validation')
-  globalThis.validate = validate
-} catch {}
-
-// Jobs facade \u2014 lets you fire jobs without remembering the dispatch builder.
-try {
-  const { Jobs } = await import('@stacksjs/queue')
-  globalThis.Jobs = Jobs
-} catch {}
-
-// Request introspection \u2014 only useful inside an active request, but
-// the proxy is safe to expose: outside a request scope every property
-// returns a typed default (see request-context.ts).
-try {
-  const { request, listRegisteredRoutes } = await import('@stacksjs/router')
-  globalThis.request = request
-  globalThis.routes = listRegisteredRoutes
-} catch {}
-
-// dump/dd helpers for quick inspection \u2014 a Laravel-ism that's always
-// nice to have at the REPL when investigating a value.
-globalThis.dump = (...args) => { console.dir(args.length === 1 ? args[0] : args, { depth: 6, colors: true }) }
-globalThis.dd = (...args) => { console.dir(args.length === 1 ? args[0] : args, { depth: 6, colors: true }); process.exit(0) }
-`);if(t.preload?.length)for(let s of t.preload){let o=s.replace(/[@/\-\.]/g,"_").replace(/^_+/,"");e.push(`try { globalThis.${o} = await import('${s}') } catch {}`)}return e.join(`
-`)}function h(t){return t?.historyFile??u(k(),".stacks_tinker_history")}function v(t){let e=h(t);if(!d(e))return[];return y(e,"utf-8").split(`
-`).filter(Boolean)}function C(t,e){let s=h(e),o=!d(s);if(f(s,`${t}
-`),o)try{p(s,384)}catch{}let i=e?.historySize??5000,r=v(e);if(r.length>i){let a=r.slice(r.length-i);c(s,a.join(`
+import{appendFileSync as de,chmodSync as q,existsSync as J,readFileSync as fe,writeFileSync as K,writeSync as pe}from"fs";import{homedir as ge}from"os";import{join as ke,resolve as ye}from"path";import F from"process";import{writeSync as ue}from"fs";import{isAbsolute as ne,resolve as D}from"path";import E from"process";var Y={maxDepth:8,maxItems:200,maxString:20000,maxNodes:50000},G=/^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/;function Q(e){if(!e)return[];let r=[];for(let n of e.split(`
+`)){let i=G.exec(n);if(!i)continue;r.push({function:i[1]||void 0,file:i[2],line:Number(i[3]),column:Number(i[4])})}return r}function X(e){if(Function.prototype.toString.call(e).startsWith("class"))return"class";let n=e.constructor?.name;if(n==="AsyncFunction"||n==="AsyncGeneratorFunction")return"async";if(n==="GeneratorFunction")return"generator";return"function"}function j(e){let r=Object.getPrototypeOf(e);if(r===null)return"null prototype";let n=r.constructor?.name;return typeof n==="string"&&n&&n!=="Object"?n:void 0}var _=2000000;class A{kind;html;title;text;constructor(e,r,n,i){this.kind=e;this.html=r;this.title=n;this.text=i}}var Z=["hasOne","hasMany","belongsTo","belongsToMany","hasOneThrough","hasManyThrough","morphOne","morphMany","morphTo","morphToMany"];function R(e){let r=[];for(let n of Z){let i=e[n];if(!i)continue;if(Array.isArray(i)){for(let o of i)if(typeof o==="string")r.push({kind:n,model:o});else if(o&&typeof o==="object"&&typeof o.model==="string")r.push({kind:n,model:o.model,...typeof o.relationName==="string"?{name:o.relationName}:{}})}else if(typeof i==="object"){for(let[o,s]of Object.entries(i))if(typeof s==="string")r.push({kind:n,model:s,name:o})}else if(typeof i==="string")r.push({kind:n,model:i})}return r}function ee(e){let r=e._definition;return typeof r==="object"&&r!==null&&typeof r.name==="string"&&typeof e.toJSON==="function"&&typeof e.getAttributes==="function"}function O(e,r={}){let n={...Y,...r.limits},i=r.describers??[],o=new Map,s=0,b=1;function g(a,y){if(s++,a===void 0)return{t:"undefined"};if(a===null)return{t:"null"};switch(typeof a){case"boolean":return{t:"boolean",v:a};case"number":if(Number.isNaN(a))return{t:"number",v:"NaN"};if(a===Number.POSITIVE_INFINITY)return{t:"number",v:"Infinity"};if(a===Number.NEGATIVE_INFINITY)return{t:"number",v:"-Infinity"};if(Object.is(a,-0))return{t:"number",v:"-0"};return{t:"number",v:a};case"bigint":return{t:"bigint",v:a.toString()};case"string":return a.length>n.maxString?{t:"string",v:a.slice(0,n.maxString),truncated:a.length-n.maxString}:{t:"string",v:a};case"symbol":return{t:"symbol",v:a.description??""};case"function":return{t:"function",name:a.name||"(anonymous)",kind:X(a)}}let t=a,d=o.get(t);if(d!==void 0)return{t:"ref",id:d};if(t instanceof Date)return{t:"date",v:Number.isNaN(t.getTime())?null:t.toISOString()};if(t instanceof RegExp)return{t:"regexp",v:t.toString()};if(t instanceof URL)return{t:"url",v:t.href};if(t instanceof Promise)return{t:"promise"};if(ArrayBuffer.isView(t)||t instanceof ArrayBuffer){let c=t instanceof ArrayBuffer?new Uint8Array(t):new Uint8Array(t.buffer,t.byteOffset,t.byteLength);return{t:"bytes",ctor:t.constructor?.name??"ArrayBuffer",length:c.byteLength,hex:Buffer.from(c.subarray(0,64)).toString("hex")}}if(y>=n.maxDepth)return{t:"cut",reason:"depth",ctor:j(t)??(Array.isArray(t)?"Array":"Object")};if(s>=n.maxNodes)return{t:"cut",reason:"nodes",ctor:j(t)};let u=b++;o.set(t,u);let l=(c)=>g(c,y+1);if(t instanceof Error)return k(t,l);if(t instanceof A){let c=t.html.length-_;return{t:"html",kind:t.kind,...t.title?{title:t.title}:{},html:c>0?t.html.slice(0,_):t.html,...t.text?{text:t.text.slice(0,n.maxString)}:{},...c>0?{truncated:c}:{}}}if(ee(t))return N(t,u,l);for(let c of i){let p;try{p=c(t,l)}catch{p=void 0}if(p)return p}if(Array.isArray(t)){let c=[],p=Math.min(t.length,n.maxItems);for(let S=0;S<p&&s<n.maxNodes;S++)c.push(l(t[S]));let f=t.length-c.length,m=j(t);return{t:"array",id:u,...m&&m!=="Array"?{ctor:m}:{},length:t.length,items:c,...f>0?{more:f}:{}}}if(t instanceof Map){let c=[];for(let[f,m]of t){if(c.length>=n.maxItems||s>=n.maxNodes)break;c.push([l(f),l(m)])}let p=t.size-c.length;return{t:"map",id:u,size:t.size,entries:c,...p>0?{more:p}:{}}}if(t instanceof Set){let c=[];for(let f of t){if(c.length>=n.maxItems||s>=n.maxNodes)break;c.push(l(f))}let p=t.size-c.length;return{t:"set",id:u,size:t.size,items:c,...p>0?{more:p}:{}}}return V(t,u,l)}function N(a,y,t){let d=a._definition,u={};try{let h=a.toJSON();if(h&&typeof h==="object")u=h}catch{}let l={};try{l=a.getLoadedRelations?.()??{}}catch{l={}}let c=Object.keys(u).filter((h)=>!(h in l)),p=[];for(let h of c){if(p.length>=n.maxItems||s>=n.maxNodes)break;p.push([h,t(u[h])])}let f=Object.keys(a).filter((h)=>!(h in u)),m=[];for(let[h,H]of Object.entries(l)){if(m.length>=n.maxItems||s>=n.maxNodes)break;m.push([h,t(H)])}let S=R(d),w=typeof d.primaryKey==="string"?d.primaryKey:"id",T=c.length-p.length;return{t:"model",id:y,model:d.name,...typeof d.table==="string"?{table:d.table}:{},primaryKey:w,...u[w]!==void 0?{key:t(u[w])}:{},attributes:p,...f.length?{hidden:f}:{},...m.length?{loaded:m}:{},...S.length?{relations:S}:{},...T>0?{more:T}:{}}}function V(a,y,t){let d=j(a),u=a,l=Object.keys(a);if(l.length===0&&d&&typeof a.toJSON==="function")try{let f=a.toJSON();if(Array.isArray(f)){let m=t(f);return m.t==="array"?{...m,ctor:d}:m}if(f&&typeof f==="object")u=f,l=Object.keys(u)}catch{}let c=[];for(let f of l){if(c.length>=n.maxItems||s>=n.maxNodes)break;let m;try{m=u[f]}catch(S){m=S}c.push([f,t(m)])}let p=l.length-c.length;return{t:"object",id:y,...d?{ctor:d}:{},entries:c,...p>0?{more:p}:{}}}function k(a,y){let t={t:"error",name:a.name||"Error",message:String(a.message??"")};if(typeof a.stack==="string"){t.stack=a.stack;let u=Q(a.stack);if(u.length)t.frames=u}if(a.cause!==void 0)t.cause=y(a.cause);let d=[];for(let u of Object.keys(a)){if(u==="name"||u==="message"||u==="stack"||u==="cause")continue;if(d.length>=n.maxItems)break;d.push([u,y(a[u])])}if(d.length)t.entries=d;return t}return g(e,0)}function P(e,r={}){if(e instanceof Error)return O(e,r);return{t:"error",name:"Thrown",message:typeof e==="string"?e:Bun.inspect(e),cause:O(e,r)}}function te(){let e=[],r=new Set;for(let n of Object.getOwnPropertyNames(globalThis)){let i;try{i=globalThis[n]}catch{continue}if(!i||typeof i!=="object"&&typeof i!=="function")continue;let o=i.getDefinition;if(typeof o!=="function")continue;let s;try{s=o.call(i)}catch{continue}if(!s||typeof s.name!=="string"||r.has(s.name))continue;r.add(s.name),e.push({name:s.name,...typeof s.table==="string"?{table:s.table}:{},...typeof s.primaryKey==="string"?{primaryKey:s.primaryKey}:{},attributes:s.attributes&&typeof s.attributes==="object"?Object.keys(s.attributes):[],relations:R(s)})}return e.sort((n,i)=>n.name.localeCompare(i.name))}function re(){return{html(e,r){return new A("html",String(e),r)},async mail(e,r={}){let{templateByName:i}=await import("@stacksjs/email"),o=await i(e,{variables:r});if(!o?.html)throw Error(`No mail template named "${e}" rendered. Templates live in resources/emails.`);return new A("mail",o.html,e,o.text)}}}class I extends Error{constructor(){super("dd");this.name="TinkerHalt"}}var ie=/\bimport\((["'])(\.{1,2}\/[^"']*)\1\)/g;function B(e,r,n="tinker"){return`${new Bun.Transpiler({loader:"ts",replMode:!0}).transformSync(e).replace(ie,(s,b,g)=>`import(${b}${D(r,g)}${b})`)}
+//# sourceURL=${n}.ts`}function oe(e){let r=e instanceof AggregateError?e.errors:[e],n=[];for(let i of r){if(!i||typeof i!=="object")continue;let{message:o,position:s}=i;n.push({message:typeof o==="string"?o:String(i),...s?.line!==void 0?{line:s.line}:{},...s?.column!==void 0?{column:s.column}:{},...s?.lineText?{lineText:s.lineText}:{}})}return n}async function se(e){let i=!0;try{let{overridesReady:o}=await import("@stacksjs/config");await o}catch(o){i=!1,e.push(`config not loaded: ${o instanceof Error?o.message:String(o)}`)}try{let{injectGlobalAutoImports:o}=await import("@stacksjs/server");await o()}catch(o){i=!1,e.push(`models and framework globals not injected: ${o instanceof Error?o.message:String(o)}`)}return i}var ae=["log","info","debug","dir","table"],ce=["warn","error","trace"];async function v(e={}){let r=e.cwd?ne(e.cwd)?e.cwd:D(E.cwd(),e.cwd):E.cwd();if(r!==E.cwd())E.chdir(r);let n={limits:e.limits,describers:e.describers},i=[],o=[],s="boot",b,g=(l)=>{b?.push(l);try{e.onFrame?.(l)}catch{}},N=console,V=(l)=>l.map((c)=>typeof c==="string"?c:Bun.inspect(c,{depth:6})).join(" ");for(let[l,c]of[[ae,"stdout"],[ce,"stderr"]])for(let p of l){let f=N[p];N[p]=(...m)=>g({type:c,id:s,text:`${V(m)}
+`}),o.push(()=>{N[p]=f})}for(let[l,c]of[[E.stdout,"stdout"],[E.stderr,"stderr"]]){let p=l.write;l.write=(f,...m)=>(g({type:c,id:s,text:typeof f==="string"?f:Buffer.from(f).toString("utf8")}),m.find((w)=>typeof w==="function")?.(),!0),o.push(()=>{l.write=p})}let k=globalThis;if(k.dump=(...l)=>{for(let c of l)g({type:"dump",id:s,value:O(c,n)})},k.dd=(...l)=>{throw k.dump(...l),new I},k.preview=re(),e.globals)Object.assign(k,e.globals);let a=!1;if(typeof e.boot==="function")try{await e.boot(),a=!0}catch(l){i.push(`boot failed: ${l instanceof Error?l.message:String(l)}`)}else if(e.boot!==!1)a=await se(i);if(a&&e.boot!==!1&&typeof e.boot!=="function"){let l=(...f)=>{for(let m of f)g({type:"dump",id:s,value:O(m,n)})};k.dump=l,k.dd=(...f)=>{throw l(...f),new I};let c="@stacksjs/logging",p="@stacksjs/query-builder";try{let{registerTransport:f}=await import(c);o.push(f({name:"tinker",log(m){g({type:"log",id:s,level:m.level,message:m.message,timestamp:m.timestamp,...m.context?{context:O(m.context,n)}:{}})}}))}catch(f){i.push(`log capture unavailable: ${f instanceof Error?f.message:String(f)}`)}try{let{registerPersistentQueryHooks:f}=await import(p);o.push(f({onQueryEnd(m){g({type:"query",id:s,sql:m.sql,...m.params?.length?{params:O(m.params,n)}:{},...m.kind?{kind:m.kind}:{},durationMs:m.durationMs,...m.rowCount!==void 0?{rowCount:m.rowCount}:{}})},onQueryError(m){g({type:"query",id:s,sql:m.sql,...m.params?.length?{params:O(m.params,n)}:{},...m.kind?{kind:m.kind}:{},durationMs:m.durationMs,error:m.error instanceof Error?m.error.message:String(m.error)})}}))}catch(f){i.push(`query capture unavailable: ${f instanceof Error?f.message:String(f)}`)}}let y=eval,t=0,d=Promise.resolve();async function u(l,c){let p=[];b=p,s=c;let f=performance.now(),m=()=>Math.round((performance.now()-f)*100)/100,S;try{S=B(l,r,`tinker-${c}`)}catch(w){let T=m();return g({type:"error",id:c,phase:"parse",error:P(w,n),diagnostics:oe(w),durationMs:T}),g({type:"done",id:c,ok:!1}),b=void 0,{id:c,ok:!1,thrown:w,frames:p,durationMs:T}}try{let T=(await y(S))?.value,h=m();return g({type:"result",id:c,value:O(T,n),durationMs:h}),g({type:"done",id:c,ok:!0}),{id:c,ok:!0,value:T,frames:p,durationMs:h}}catch(w){let T=m();if(w instanceof I)return g({type:"result",id:c,value:{t:"undefined"},durationMs:T}),g({type:"done",id:c,ok:!0}),{id:c,ok:!0,frames:p,durationMs:T};return g({type:"error",id:c,phase:"run",error:P(w,n),durationMs:T}),g({type:"done",id:c,ok:!1}),{id:c,ok:!1,thrown:w,frames:p,durationMs:T}}finally{b=void 0}}return{info:{cwd:r,booted:a,bun:Bun.version,warnings:i},models:te,evaluate(l,c={}){let p=c.id??String(++t),f=d.then(()=>u(l,p));return d=f.catch(()=>{}),f},dispose(){while(o.length)o.pop()?.()}}}var z="\x1E",me=2;function le(e){return`${z}${JSON.stringify(e)}
+`}function Ie(){let e="",r=(n)=>{if(n.startsWith(z))try{return{frame:JSON.parse(n.slice(z.length))}}catch{return{stray:n}}return{stray:n}};return{push(n){e+=n;let i=e.split(`
+`);return e=i.pop()??"",i.map(r)},flush(){if(!e)return[];let n=e;return e="",[{stray:n}]}}}async function L(e={}){let r=e.write??((d)=>{ue(1,d)}),n=(d)=>r(le(d)),{input:i,write:o,once:s,...b}=e,g=await v({...b,onFrame:n});n({type:"ready",session:g.info,protocol:me});let N=!0,V=!1;if(s!==void 0)return{ok:(await g.evaluate(s)).ok,session:g};let k=new TextDecoder,a="",y=i??Bun.stdin.stream(),t=async(d)=>{if(!d.trim())return!0;let u;try{u=JSON.parse(d)}catch{return n({type:"protocol-error",message:"request is not valid JSON"}),!0}if(u.op==="exit")return!1;if(u.op==="ping")return n({type:"pong",...u.id?{id:u.id}:{}}),!0;if(u.op==="models")return n({type:"models",...u.id?{id:u.id}:{},models:g.models()}),!0;if(u.op==="eval"&&typeof u.code==="string"){if(!(await g.evaluate(u.code,{id:u.id})).ok)N=!1;return!0}return n({type:"protocol-error",message:`unknown request: ${String(u.op)}`}),!0};e:for await(let d of y){a+=typeof d==="string"?d:k.decode(d,{stream:!0});let u=a.indexOf(`
+`);while(u!==-1){let l=a.slice(0,u);if(a=a.slice(u+1),!await t(l)){V=!0;break e}u=a.indexOf(`
+`)}}if(!V&&a.trim())await t(a);return{ok:N,session:g}}function C(e){return e?.historyFile??ke(ge(),".stacks_tinker_history")}function U(e){let r=C(e);if(!J(r))return[];return fe(r,"utf-8").split(`
+`).filter(Boolean)}function be(e,r){let n=C(r),i=!J(n);if(de(n,`${e}
+`),i)try{q(n,384)}catch{}let o=r?.historySize??5000,s=U(r);if(s.length>o){let b=s.slice(s.length-o);K(n,b.join(`
 `)+`
-`);try{p(s,384)}catch{}}}function q(t){let e=h(t);c(e,"")}function w(){return["",`  \x1B[36mStacks Tinker\x1B[0m (Bun v${typeof Bun<"u"?Bun.version:"unknown"})`,"  Interactive REPL with Stacks framework preloaded.","","  \x1B[2mAvailable globals: db, config, path, storage, log, Str,","  cache, queue, events, router, auth, collect, env, request,","  validate, Jobs, routes, dump, dd","  + all ORM models (User, Post, etc.)\x1B[0m","","  \x1B[2mType .help for REPL commands. Press Ctrl+D to exit.\x1B[0m",""].join(`
-`)}async function m(t={}){let e=t.cwd??n.cwd();if(t.eval||t.print)return T(t,e);if(t.banner!==!1)n.stdout.write(w());let s=g(t),o=u(e,".tinker-preload.ts");c(o,s);let i=["repl"],a=await Bun.spawn(["bun",...i],{cwd:e,stdin:"inherit",stdout:"inherit",stderr:"inherit",env:{...n.env,BUN_PRELOAD:o}}).exited;try{let{unlinkSync:l}=await import("fs");l(o)}catch{}return{exitCode:a}}async function T(t,e){let s=g(t),o=t.print??t.eval??"",i=`${s}
-
-const __result__ = await (async () => { return ${o} })()
-${t.print?"console.log(__result__)":""}`,r=u(e,".tinker-eval.ts");c(r,i);let l=await Bun.spawn(["bun","run",r],{cwd:e,stdin:"inherit",stdout:"inherit",stderr:"inherit",env:n.env}).exited;try{let{unlinkSync:b}=await import("fs");b(r)}catch{}return{exitCode:l}}async function R(t,e={}){return m({...e,eval:t})}async function _(t,e={}){return m({...e,print:t})}export{C as appendHistory,q as clearHistory,h as getHistoryPath,v as readHistory,m as startTinker,R as tinkerEval,_ as tinkerPrint};
+`);try{q(n,384)}catch{}}}function he(e){let r=C(e);K(r,"")}function we(e){let r=["",`  \x1B[36mStacks Tinker\x1B[0m (Bun v${e.bun})`,e.booted?"  Your app is booted: models, jobs, config and framework helpers are globals.":"  Bare session: the app context is not booted."];for(let n of e.warnings)r.push(`  \x1B[33m${n}\x1B[0m`);return r.push("","  \x1B[2mDeclarations persist between lines. dump(value) inspects, dd(value) inspects and stops.","  .help for commands, .exit or Ctrl+D to leave.\x1B[0m","",""),r.join(`
+`)}function x(e,r=1){pe(r,e)}function M(e,r=""){let n=`${r}  `;switch(e.t){case"undefined":return"undefined";case"null":return"null";case"boolean":return String(e.v);case"number":return String(e.v);case"bigint":return`${e.v}n`;case"string":return JSON.stringify(e.v)+(e.truncated?` ... ${e.truncated} more characters`:"");case"symbol":return`Symbol(${e.v})`;case"function":return`[${e.kind==="class"?"class":"Function"}: ${e.name}]`;case"date":return e.v??"Invalid Date";case"regexp":return e.v;case"url":return e.v;case"promise":return"Promise {}";case"bytes":return`${e.ctor}(${e.length}) <${e.hex}${e.length>64?" ...":""}>`;case"ref":return`[Circular *${e.id}]`;case"cut":return`[${e.ctor??"Object"}]`;case"error":return e.stack??`${e.name}: ${e.message}`;case"array":{if(!e.items.length&&!e.more)return`${e.ctor?`${e.ctor} `:""}[]`;let i=e.items.map((o)=>`${n}${M(o,n)}`);if(e.more)i.push(`${n}... ${e.more} more`);return`${e.ctor?`${e.ctor} `:""}[
+${i.join(`,
+`)}
+${r}]`}case"set":{let i=e.items.map((o)=>`${n}${M(o,n)}`);if(e.more)i.push(`${n}... ${e.more} more`);return i.length?`Set(${e.size}) {
+${i.join(`,
+`)}
+${r}}`:"Set(0) {}"}case"map":{let i=e.entries.map(([o,s])=>`${n}${M(o,n)} => ${M(s,n)}`);if(e.more)i.push(`${n}... ${e.more} more`);return i.length?`Map(${e.size}) {
+${i.join(`,
+`)}
+${r}}`:"Map(0) {}"}case"html":return`[${e.kind}${e.title?` ${e.title}`:""}: ${e.html.length} characters of markup]`;case"model":{let i=e.attributes.map(([o,s])=>`${n}${o}: ${M(s,n)}`);for(let o of e.hidden??[])i.push(`${n}${o}: [hidden]`);for(let[o,s]of e.loaded??[])i.push(`${n}${o}: ${M(s,n)}`);if(e.more)i.push(`${n}... ${e.more} more`);return`${e.model} {
+${i.join(`,
+`)}
+${r}}`}case"object":{if(!e.entries.length&&!e.more)return`${e.ctor?`${e.ctor} `:""}{}`;let i=e.entries.map(([o,s])=>`${n}${o}: ${M(s,n)}`);if(e.more)i.push(`${n}... ${e.more} more`);return`${e.ctor?`${e.ctor} `:""}{
+${i.join(`,
+`)}
+${r}}`}}}function Te(e,r){switch(e.type){case"stdout":x(e.text);break;case"stderr":x(e.text,2);break;case"dump":x(`${M(e.value)}
+`);break;case"query":if(r)x(`\x1B[2m  ${e.durationMs??"?"}ms  ${e.sql}\x1B[0m
+`,2);break;case"log":if(r)x(`\x1B[2m  [${e.level}] ${e.message}\x1B[0m
+`,2);break}}async function xe(e,r){let n=[];for(let i of e??[]){let o=i.replace(/[@/\-.]/g,"_").replace(/^_+/,"");try{let s=i.startsWith(".")?ye(r,i):i;globalThis[o]=await import(s)}catch(s){n.push(`${i}: ${s instanceof Error?s.message:String(s)}`)}}return n}var Se=/Unexpected end of file|Unterminated|Expected "\}" but found end of file|Expected "\)" but found end of file|Expected "\]" but found end of file/;function $e(e,r){try{return B(e,r),!1}catch(n){return(n instanceof AggregateError?n.errors.map((o)=>String(o?.message??o)):[String(n?.message??n)]).some((o)=>Se.test(o))}}async function W(e={}){let r=e.cwd??F.cwd(),n=e.stacksPreload!==!1;if(e.serve){let t=e.eval??e.print,{ok:d}=await L({cwd:r,boot:n,...t!==void 0?{once:t}:{}});return{exitCode:d?0:1}}let i=e.verbose===!0,o=await v({cwd:r,boot:n,onFrame:(t)=>Te(t,i)});for(let t of await xe(e.preload,o.info.cwd))x(`\x1B[33mpreload failed: ${t}\x1B[0m
+`,2);let s=(t,d)=>{if(!t.ok){let u=t.thrown;x(`${u instanceof Error?Bun.inspect(u,{colors:Boolean(F.stderr.isTTY)}):`Uncaught ${Bun.inspect(u)}`}
+`,2);return}if(d&&t.value!==void 0)x(`${M(O(t.value))}
+`)};if(e.eval!==void 0||e.print!==void 0){for(let d of o.info.warnings)x(`\x1B[33m${d}\x1B[0m
+`,2);let t=await o.evaluate(e.print??e.eval??"");return s(t,e.print!==void 0),o.dispose(),{exitCode:t.ok?0:1}}if(e.banner!==!1)x(we(o.info));let{createInterface:b}=await import("readline"),{Writable:g}=await import("stream"),N=new g({write(t,d,u){x(typeof t==="string"?t:Buffer.from(t).toString("utf8")),u()}}),V=e.historySize??5000,k=b({input:F.stdin,output:N,terminal:Boolean(F.stdin.isTTY),history:U(e).slice(-V).reverse(),historySize:V,prompt:"> "}),a="",y=0;k.prompt();try{for await(let t of k){let d=t.trim();if(!a&&d.startsWith(".")){if(d===".exit")break;if(d===".help")x(`  .exit           leave
+  .clear          forget the history file
+  .help           this list
+  dump(v), dd(v)  inspect a value; dd also stops the line
+`);else if(d===".clear")he(e);else x(`  unknown command ${d}
+`);k.prompt();continue}if(a=a?`${a}
+${t}`:t,!a.trim()){a="",k.prompt();continue}if($e(a,o.info.cwd)){k.setPrompt("... "),k.prompt();continue}let u=a;a="";try{be(u.replace(/\n/g," "),e)}catch{}let l=await o.evaluate(u);s(l,!0),y=l.ok?0:y,k.setPrompt("> "),k.prompt()}}finally{k.close(),o.dispose()}return{exitCode:y}}async function De(e,r={}){return W({...r,eval:e})}async function Le(e,r={}){return W({...r,print:e})}export{z as FRAME_MARKER,me as PROTOCOL_VERSION,A as TinkerPreview,be as appendHistory,he as clearHistory,B as compileSnippet,Ie as createFrameReader,v as createTinkerSession,Y as defaultSerializeLimits,le as encodeFrame,C as getHistoryPath,$e as isIncompleteSnippet,ee as isModelInstance,te as listModels,Q as parseStack,U as readHistory,R as relationsOf,M as renderValue,O as serialize,P as serializeThrown,L as serveTinker,W as startTinker,De as tinkerEval,Le as tinkerPrint};

package/dist/protocol.d.ts

@@ -0,0 +1,48 @@
+import type { TinkerFrame, TinkerModelSummary, TinkerSession, TinkerSessionInfo, TinkerSessionOptions } from './session';
+export declare function encodeFrame(frame: TinkerWireFrame): string;
+/**
+ * Split a chunk of a session's output into frames and stray text.
+ *
+ * Feed it chunks as they arrive. A trailing partial line is held until the
+ * rest of it comes.
+ */
+export declare function createFrameReader(): {
+  push: (chunk: string) => Array<{ frame: TinkerWireFrame } | { stray: string }>
+  flush: () => Array<{ stray: string }>
+};
+/**
+ * Run a session that answers requests until its input closes or it is told to
+ * exit. Resolves with whether every evaluation succeeded.
+ */
+export declare function serveTinker(options?: ServeOptions): Promise<{ ok: boolean, session: TinkerSession }>;
+/**
+ * The wire format a tinker session speaks over a pipe.
+ *
+ * One process, one session, driven by whoever holds its stdin: a desktop app
+ * on the same machine, or the far end of `ssh -T`, `docker exec -i` or
+ * `kubectl exec -i`. Requests come in as one JSON object per line. Frames go
+ * out as one JSON object per line, each line starting with the record
+ * separator (0x1E).
+ *
+ * The marker is what keeps the stream readable when something writes to file
+ * descriptor 1 behind the session's back (a native addon, a child process that
+ * inherited stdio). A reader treats a line that starts with the marker as a
+ * frame and anything else as stray output, instead of failing to parse it.
+ */
+export declare const FRAME_MARKER: '\x1E';
+/** Bumped when a frame changes shape in a way an older reader would misread. */
+export declare const PROTOCOL_VERSION: 2;
+export declare interface ServeOptions extends Omit<TinkerSessionOptions, 'onFrame'> {
+  input?: AsyncIterable<Uint8Array | string>
+  write?: (text: string) => void
+  once?: string
+}
+export type TinkerRequest = | { op: 'eval', id?: string, code: string }
+  | { op: 'ping', id?: string }
+  | { op: 'models', id?: string }
+  | { op: 'exit' }
+export type TinkerWireFrame = | TinkerFrame
+  | { type: 'ready', session: TinkerSessionInfo, protocol: number }
+  | { type: 'pong', id?: string }
+  | { type: 'models', id?: string, models: TinkerModelSummary[] }
+  | { type: 'protocol-error', message: string }

package/dist/serialize.d.ts

@@ -0,0 +1,126 @@
+/** Parse a V8/JavaScriptCore `at fn (file:line:col)` stack into frames. */
+export declare function parseStack(stack: string | undefined): TinkerStackFrame[];
+/** The relations a model definition declares, flattened. */
+export declare function relationsOf(definition: Record<string, unknown>): Array<{ kind: string, model: string, name?: string }>;
+/**
+ * Whether a value is a Stacks ORM model instance. Told by shape, not by
+ * class, so this package needs no dependency on the ORM and a model from any
+ * copy of it is recognised.
+ */
+export declare function isModelInstance(value: object): value is ModelLike;
+export declare function serialize(root: unknown, options?: SerializeOptions): TinkerValue;
+/** Describe anything thrown, including non-Error throws, as an error value. */
+export declare function serializeThrown(thrown: unknown, options?: SerializeOptions): TinkerErrorValue;
+export declare const defaultSerializeLimits: SerializeLimits;
+/**
+ * Turn any runtime value into a plain, JSON-safe description of it.
+ *
+ * A tinker result has to leave the process that produced it: over a pipe to a
+ * desktop app, over SSH from a server, out of a container. `JSON.stringify`
+ * loses most of what makes a result worth looking at (undefined, bigint, Date,
+ * Map, Set, class names, cycles, errors), and `Bun.inspect` produces a string a
+ * UI can only print. This produces a tree a UI can expand, sort and tabulate,
+ * with every node tagged by what it was.
+ *
+ * It is bounded on purpose. A model collection with a million rows or an
+ * object graph that reaches the whole app must not hang the session or flood
+ * the pipe, so depth, items per container, string length and total nodes all
+ * have limits, and every cut is recorded on the node (`more`, `truncated`)
+ * rather than silently dropped.
+ */
+export declare interface SerializeLimits {
+  maxDepth: number
+  maxItems: number
+  maxString: number
+  maxNodes: number
+}
+export declare interface TinkerStackFrame {
+  function?: string
+  file?: string
+  line?: number
+  column?: number
+}
+export declare interface TinkerErrorValue {
+  t: 'error'
+  name: string
+  message: string
+  stack?: string
+  frames?: TinkerStackFrame[]
+  cause?: TinkerValue
+  entries?: Array<[string, TinkerValue]>
+}
+/** An ORM model instance: what it is, its visible attributes, and what it relates to. */
+export declare interface TinkerModelValue {
+  t: 'model'
+  id: number
+  model: string
+  table?: string
+  primaryKey?: string
+  key?: TinkerValue
+  attributes: Array<[string, TinkerValue]>
+  hidden?: string[]
+  loaded?: Array<[string, TinkerValue]>
+  relations?: Array<{ kind: string, model: string, name?: string }>
+  more?: number
+}
+/** Rendered markup to show as a page instead of as text: a mail, a view, any HTML. */
+export declare interface TinkerHtmlValue {
+  t: 'html'
+  kind: 'mail' | 'view' | 'html'
+  title?: string
+  html: string
+  text?: string
+  truncated?: number
+}
+export declare interface SerializeOptions {
+  limits?: Partial<SerializeLimits>
+  describers?: TinkerDescriber[]
+}
+declare interface ModelLike {
+  _definition: { name: string, table?: string, primaryKey?: string } & Record<string, unknown>
+  toJSON: () => unknown
+  getLoadedRelations?: () => Record<string, unknown>
+}
+export type TinkerValue = | { t: 'undefined' }
+  | { t: 'null' }
+  | { t: 'boolean', v: boolean }
+  | { t: 'number', v: number | 'NaN' | 'Infinity' | '-Infinity' | '-0' }
+  | { t: 'bigint', v: string }
+  | { t: 'string', v: string, truncated?: number }
+  | { t: 'symbol', v: string }
+  | { t: 'function', name: string, kind: 'function' | 'async' | 'class' | 'generator' }
+  | { t: 'date', v: string | null }
+  | { t: 'regexp', v: string }
+  | { t: 'url', v: string }
+  | { t: 'promise' }
+  | { t: 'bytes', ctor: string, length: number, hex: string }
+  | { t: 'array', id: number, ctor?: string, length: number, items: TinkerValue[], more?: number }
+  | { t: 'object', id: number, ctor?: string, entries: Array<[string, TinkerValue]>, more?: number }
+  | { t: 'map', id: number, size: number, entries: Array<[TinkerValue, TinkerValue]>, more?: number }
+  | { t: 'set', id: number, size: number, items: TinkerValue[], more?: number }
+  | TinkerModelValue
+  | TinkerHtmlValue
+  | { t: 'ref', id: number }
+  | { t: 'cut', reason: 'depth' | 'nodes', ctor?: string }
+  | TinkerErrorValue;
+/**
+ * Describes one kind of value the generic walk does not know about, such as an
+ * ORM model. Return `undefined` to pass. `describe` continues the walk for
+ * nested values so limits and cycle tracking stay in force.
+ */
+export type TinkerDescriber = (
+  value: object,
+  describe: (value: unknown) => TinkerValue,
+) => TinkerValue | undefined;
+/**
+ * A value that says "show me as rendered markup". Returned by the session's
+ * `preview` helpers; a snippet can also construct one.
+ */
+export declare class TinkerPreview {
+  readonly kind: TinkerHtmlValue['kind'];
+  readonly html: string;
+  readonly title?: string;
+  readonly text?: string;
+  constructor(kind: TinkerHtmlValue['kind'], html: string, title?: string, text?: string);
+}
+export {};

package/dist/session.d.ts

@@ -0,0 +1,74 @@
+import type { SerializeOptions, TinkerErrorValue, TinkerValue } from './serialize';
+/**
+ * The models reachable as globals in this process. After a Stacks boot that
+ * is every model the app loaded; in a bare session it is none.
+ */
+export declare function listModels(): TinkerModelSummary[];
+/**
+ * Compile a snippet into JavaScript that, evaluated at global scope, runs it
+ * and yields `{ value }` for its last expression.
+ *
+ * Evaluated code has no file, so a relative `import('./app/Actions/Foo')`
+ * would resolve against this package instead of the project. Those specifiers
+ * are made absolute against the session's directory.
+ */
+export declare function compileSnippet(code: string, cwd: string, sourceName?: string): string;
+export declare function createTinkerSession(options?: TinkerSessionOptions): Promise<TinkerSession>;
+export declare interface TinkerDiagnostic {
+  message: string
+  line?: number
+  column?: number
+  lineText?: string
+}
+export declare interface TinkerSessionInfo {
+  cwd: string
+  booted: boolean
+  bun: string
+  warnings: string[]
+}
+export declare interface TinkerSessionOptions extends SerializeOptions {
+  cwd?: string
+  boot?: boolean | (() => Promise<void> | void)
+  globals?: Record<string, unknown>
+  onFrame?: (frame: TinkerFrame) => void
+}
+export declare interface TinkerEvaluation {
+  id: string
+  ok: boolean
+  value?: unknown
+  thrown?: unknown
+  frames: TinkerFrame[]
+  durationMs: number
+}
+/** One model the app knows, as a relation graph and a completion list need it. */
+export declare interface TinkerModelSummary {
+  name: string
+  table?: string
+  primaryKey?: string
+  attributes: string[]
+  relations: Array<{ kind: string, model: string, name?: string }>
+}
+export declare interface TinkerSession {
+  info: TinkerSessionInfo
+  models: () => TinkerModelSummary[]
+  evaluate: (code: string, options?: { id?: string }) => Promise<TinkerEvaluation>
+  dispose: () => void
+}
+/**
+ * A tinker session: one booted app, many evaluations, state kept between them.
+ *
+ * The old tinker wrote the snippet to a file in the project and ran a fresh
+ * `bun` on it, so nothing survived from one run to the next, a snippet with
+ * two statements was a syntax error, and the caller learned only an exit code.
+ * A session evaluates in its own process instead. Declarations are hoisted to
+ * globals by Bun's REPL transform, so `const user = await User.find(1)` in one
+ * run is still `user` in the next, and each run reports what happened as
+ * frames: output, logs, queries, dumps, then a typed result or an error.
+ */
+export type TinkerFrame = | { type: 'stdout' | 'stderr', id: string, text: string }
+  | { type: 'log', id: string, level: string, message: string, timestamp: string, context?: TinkerValue }
+  | { type: 'query', id: string, sql: string, params?: TinkerValue, kind?: string, durationMs?: number, rowCount?: number, error?: string }
+  | { type: 'dump', id: string, value: TinkerValue }
+  | { type: 'result', id: string, value: TinkerValue, durationMs: number }
+  | { type: 'error', id: string, error: TinkerErrorValue, phase: 'parse' | 'run', diagnostics?: TinkerDiagnostic[], durationMs: number }
+  | { type: 'done', id: string, ok: boolean }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/tinker",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.539",
+  "version": "0.75.542",
   "description": "Interactive REPL with Stacks framework preloaded.",
   "author": "Chris Breuer",
   "contributors": [