@vpxa/kb 0.1.12 → 0.1.15

package/packages/tools/dist/queue.js

@@ -1,2 +1,2 @@
-import{existsSync as a,mkdirSync as c,readFileSync as l,writeFileSync as p}from"node:fs";import{dirname as m,resolve as q}from"node:path";const Q=".kb-state",S="queue.json";function d(e){return q(e??process.cwd(),Q,S)}function o(e){const r=d(e);return a(r)?JSON.parse(l(r,"utf-8")):{}}function g(e,r){const t=d(r),n=m(t);a(n)||c(n,{recursive:!0}),p(t,`${JSON.stringify(e,null,2)}
-`,"utf-8")}function h(){return`q_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,6)}`}function I(e,r){const t=o(r);if(t[e])throw new Error(`Queue "${e}" already exists`);const n={name:e,items:[]};return t[e]=n,g(t,r),n}function E(e,r,t,n){const u=o(n);u[e]||(u[e]={name:e,items:[]});const s=new Date().toISOString(),i={id:h(),title:r,status:"pending",data:t,createdAt:s,updatedAt:s};return u[e].items.push(i),g(u,n),i}function $(e,r){const t=o(r),n=t[e];if(!n)throw new Error(`Queue "${e}" does not exist`);const u=n.items.find(s=>s.status==="pending");return u?(u.status="in-progress",u.updatedAt=new Date().toISOString(),g(t,r),u):null}function b(e,r,t){const n=o(t),u=n[e];if(!u)throw new Error(`Queue "${e}" does not exist`);const s=u.items.find(i=>i.id===r);if(!s)throw new Error(`Item "${r}" not found in queue "${e}"`);return s.status="done",s.updatedAt=new Date().toISOString(),g(n,t),s}function A(e,r,t,n){const u=o(n),s=u[e];if(!s)throw new Error(`Queue "${e}" does not exist`);const i=s.items.find(f=>f.id===r);if(!i)throw new Error(`Item "${r}" not found in queue "${e}"`);return i.status="failed",i.error=t,i.updatedAt=new Date().toISOString(),g(u,n),i}function D(e,r){return o(r)[e]??null}function y(e){const r=o(e);return Object.values(r).map(t=>({name:t.name,pending:t.items.filter(n=>n.status==="pending").length,done:t.items.filter(n=>n.status==="done").length,failed:t.items.filter(n=>n.status==="failed").length,total:t.items.length}))}function O(e,r){const t=o(r),n=t[e];if(!n)throw new Error(`Queue "${e}" does not exist`);const u=n.items.length;n.items=n.items.filter(i=>i.status==="pending"||i.status==="in-progress");const s=u-n.items.length;return g(t,r),s}function v(e,r){const t=o(r);return t[e]?(delete t[e],g(t,r),!0):!1}export{O as queueClear,I as queueCreate,v as queueDelete,b as queueDone,A as queueFail,D as queueGet,y as queueList,$ as queueNext,E as queuePush};
+import{dirname as e,resolve as t}from"node:path";import{existsSync as n,mkdirSync as r,readFileSync as i,writeFileSync as a}from"node:fs";function o(e){return t(e??process.cwd(),`.kb-state`,`queue.json`)}function s(e){let t=o(e);if(!n(t))return{};try{return JSON.parse(i(t,`utf-8`))}catch{return{}}}function c(t,i){let s=o(i),c=e(s);n(c)||r(c,{recursive:!0}),a(s,`${JSON.stringify(t,null,2)}\n`,`utf-8`)}function l(){return`q_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,6)}`}function u(e,t){let n=s(t);if(n[e])throw Error(`Queue "${e}" already exists`);let r={name:e,items:[]};return n[e]=r,c(n,t),r}function d(e,t,n,r){let i=s(r);i[e]||(i[e]={name:e,items:[]});let a=new Date().toISOString(),o={id:l(),title:t,status:`pending`,data:n,createdAt:a,updatedAt:a};return i[e].items.push(o),c(i,r),o}function f(e,t){let n=s(t),r=n[e];if(!r)throw Error(`Queue "${e}" does not exist`);let i=r.items.find(e=>e.status===`pending`);return i?(i.status=`in-progress`,i.updatedAt=new Date().toISOString(),c(n,t),i):null}function p(e,t,n){let r=s(n),i=r[e];if(!i)throw Error(`Queue "${e}" does not exist`);let a=i.items.find(e=>e.id===t);if(!a)throw Error(`Item "${t}" not found in queue "${e}"`);return a.status=`done`,a.updatedAt=new Date().toISOString(),c(r,n),a}function m(e,t,n,r){let i=s(r),a=i[e];if(!a)throw Error(`Queue "${e}" does not exist`);let o=a.items.find(e=>e.id===t);if(!o)throw Error(`Item "${t}" not found in queue "${e}"`);return o.status=`failed`,o.error=n,o.updatedAt=new Date().toISOString(),c(i,r),o}function h(e,t){return s(t)[e]??null}function g(e){let t=s(e);return Object.values(t).map(e=>({name:e.name,pending:e.items.filter(e=>e.status===`pending`).length,done:e.items.filter(e=>e.status===`done`).length,failed:e.items.filter(e=>e.status===`failed`).length,total:e.items.length}))}function _(e,t){let n=s(t),r=n[e];if(!r)throw Error(`Queue "${e}" does not exist`);let i=r.items.length;r.items=r.items.filter(e=>e.status===`pending`||e.status===`in-progress`);let a=i-r.items.length;return c(n,t),a}function v(e,t){let n=s(t);return n[e]?(delete n[e],c(n,t),!0):!1}export{_ as queueClear,u as queueCreate,v as queueDelete,p as queueDone,m as queueFail,h as queueGet,g as queueList,f as queueNext,d as queuePush};
+//# sourceMappingURL=queue.js.map

package/packages/tools/dist/regex-test.d.ts

@@ -1,31 +1,34 @@
+//#region packages/tools/src/regex-test.d.ts
 /**
  * kb_regex_test — Test regex patterns against sample strings.
  */
-export interface RegexTestOptions {
-    pattern: string;
-    flags?: string;
-    testStrings: string[];
-    mode?: 'match' | 'replace' | 'split';
-    replacement?: string;
+interface RegexTestOptions {
+  pattern: string;
+  flags?: string;
+  testStrings: string[];
+  mode?: 'match' | 'replace' | 'split';
+  replacement?: string;
 }
-export interface RegexMatchInfo {
-    full: string;
-    groups: (string | undefined)[];
-    index: number;
+interface RegexMatchInfo {
+  full: string;
+  groups: (string | undefined)[];
+  index: number;
 }
-export interface RegexTestStringResult {
-    input: string;
-    matched: boolean;
-    matches?: RegexMatchInfo[];
-    replaced?: string;
-    split?: string[];
+interface RegexTestStringResult {
+  input: string;
+  matched: boolean;
+  matches?: RegexMatchInfo[];
+  replaced?: string;
+  split?: string[];
 }
-export interface RegexTestResult {
-    pattern: string;
-    flags: string;
-    results: RegexTestStringResult[];
-    valid: boolean;
-    error?: string;
+interface RegexTestResult {
+  pattern: string;
+  flags: string;
+  results: RegexTestStringResult[];
+  valid: boolean;
+  error?: string;
 }
-export declare function regexTest(options: RegexTestOptions): RegexTestResult;
+declare function regexTest(options: RegexTestOptions): RegexTestResult;
+//#endregion
+export { RegexMatchInfo, RegexTestOptions, RegexTestResult, RegexTestStringResult, regexTest };
 //# sourceMappingURL=regex-test.d.ts.map

package/packages/tools/dist/regex-test.js

@@ -1 +1,2 @@
-function u(g){const{pattern:r,flags:e="",testStrings:l,mode:c="match",replacement:i=""}=g;try{const s=new RegExp(r,e),o=l.map(t=>{const n=s.test(t);switch(c){case"match":{const p=e.includes("g")?e:`${e}g`,x=[...t.matchAll(new RegExp(r,p))];return{input:t,matched:n,matches:x.map(a=>({full:a[0],groups:[...a.slice(1)],index:a.index??0}))}}case"replace":return{input:t,matched:n,replaced:t.replace(new RegExp(r,e),i)};default:return{input:t,matched:n,split:t.split(new RegExp(r,e))}}});return{pattern:r,flags:e,results:o,valid:!0}}catch(s){return{pattern:r,flags:e,results:[],valid:!1,error:s.message}}}export{u as regexTest};
+function e(e){let{pattern:t,flags:n=``,testStrings:r,mode:i=`match`,replacement:a=``}=e;try{let e=new RegExp(t,n);return{pattern:t,flags:n,results:r.map(r=>{let o=e.test(r);switch(i){case`match`:{let e=n.includes(`g`)?n:`${n}g`;return{input:r,matched:o,matches:[...r.matchAll(new RegExp(t,e))].map(e=>({full:e[0],groups:[...e.slice(1)],index:e.index??0}))}}case`replace`:return{input:r,matched:o,replaced:r.replace(new RegExp(t,n),a)};default:return{input:r,matched:o,split:r.split(new RegExp(t,n))}}}),valid:!0}}catch(e){return{pattern:t,flags:n,results:[],valid:!1,error:e.message}}}export{e as regexTest};
+//# sourceMappingURL=regex-test.js.map

package/packages/tools/dist/rename.d.ts

@@ -1,29 +1,32 @@
-export interface RenameOptions {
-    /** Symbol to rename */
-    oldName: string;
-    /** New symbol name */
-    newName: string;
-    /** Root directory to search in */
-    rootPath: string;
-    /** File extensions to process (default: .ts, .tsx, .js, .jsx) */
-    extensions?: string[];
-    /** Glob patterns to exclude */
-    exclude?: string[];
-    /** Dry run — don't write changes */
-    dryRun?: boolean;
+//#region packages/tools/src/rename.d.ts
+interface RenameOptions {
+  /** Symbol to rename */
+  oldName: string;
+  /** New symbol name */
+  newName: string;
+  /** Root directory to search in */
+  rootPath: string;
+  /** File extensions to process (default: .ts, .tsx, .js, .jsx) */
+  extensions?: string[];
+  /** Glob patterns to exclude */
+  exclude?: string[];
+  /** Dry run — don't write changes */
+  dryRun?: boolean;
 }
-export interface RenameChange {
-    path: string;
-    line: number;
-    before: string;
-    after: string;
+interface RenameChange {
+  path: string;
+  line: number;
+  before: string;
+  after: string;
 }
-export interface RenameResult {
-    oldName: string;
-    newName: string;
-    changes: RenameChange[];
-    filesModified: number;
-    dryRun: boolean;
+interface RenameResult {
+  oldName: string;
+  newName: string;
+  changes: RenameChange[];
+  filesModified: number;
+  dryRun: boolean;
 }
-export declare function rename(options: RenameOptions): Promise<RenameResult>;
+declare function rename(options: RenameOptions): Promise<RenameResult>;
+//#endregion
+export { RenameChange, RenameOptions, RenameResult, rename };
 //# sourceMappingURL=rename.d.ts.map

package/packages/tools/dist/rename.js

@@ -1,2 +1,3 @@
-import{readFile as x,writeFile as w}from"node:fs/promises";import{relative as N}from"node:path";import{DEFAULT_TOOL_EXTENSIONS as $,walkFiles as b}from"./file-walk.js";function P(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function C(e){return e.replace(/\\/g,"/")}function E(e){return new RegExp(`(^|[^A-Za-z0-9_$])(${P(e)})(?=[^A-Za-z0-9_$]|$)`,"g")}async function A(e){const{oldName:r,newName:s,rootPath:l,extensions:p=$,exclude:d=[],dryRun:f=!1}=e;if(!r.trim())throw new Error("oldName must not be empty");const g=E(r),h=await b(l,p,d),c=[];let m=0;for(const i of h){const t=(await x(i,"utf-8")).split(/\r?\n/);let u=!1;for(let n=0;n<t.length;n++){const a=t[n];g.lastIndex=0;const o=a.replace(g,(O,R)=>(u=!0,`${R}${s}`));a!==o&&(t[n]=o,c.push({path:C(N(l,i)),line:n+1,before:a,after:o}))}u&&(m+=1,f||await w(i,t.join(`
-`),"utf-8"))}return{oldName:r,newName:s,changes:c,filesModified:m,dryRun:f}}export{A as rename};
+import{DEFAULT_TOOL_EXTENSIONS as e,walkFiles as t}from"./file-walk.js";import{readFile as n,writeFile as r}from"node:fs/promises";import{relative as i}from"node:path";function a(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function o(e){return e.replace(/\\/g,`/`)}function s(e){return RegExp(`(^|[^A-Za-z0-9_$])(${a(e)})(?=[^A-Za-z0-9_$]|$)`,`g`)}async function c(a){let{oldName:c,newName:l,rootPath:u,extensions:d=e,exclude:f=[],dryRun:p=!1}=a;if(!c.trim())throw Error(`oldName must not be empty`);let m=s(c),h=await t(u,d,f),g=[],_=0;for(let e of h){let t=(await n(e,`utf-8`)).split(/\r?\n/),a=!1;for(let n=0;n<t.length;n++){let r=t[n];m.lastIndex=0;let s=r.replace(m,(e,t)=>(a=!0,`${t}${l}`));r!==s&&(t[n]=s,g.push({path:o(i(u,e)),line:n+1,before:r,after:s}))}a&&(_+=1,p||await r(e,t.join(`
+`),`utf-8`))}return{oldName:c,newName:l,changes:g,filesModified:_,dryRun:p}}export{c as rename};
+//# sourceMappingURL=rename.js.map

package/packages/tools/dist/replay.d.ts

@@ -1,56 +1,59 @@
+//#region packages/tools/src/replay.d.ts
 /**
  * Replay — append-only audit trail of tool/CLI invocations.
  *
  * Captures tool name, arguments (redacted), duration, and result summary
- * to `.kb-state/replay.jsonl`. Used by `kb replay` CLI, `kb_replay_list` MCP,
+ * to `.kb-state/replay.jsonl`. Used by `kb replay` CLI, `kb_replay` MCP tool,
  * and the TUI log panel.
  */
-export interface ReplayEntry {
-    /** ISO timestamp */
-    ts: string;
-    /** Source: 'mcp' | 'cli' */
-    source: 'mcp' | 'cli';
-    /** Tool or command name */
-    tool: string;
-    /** Redacted input summary (first 200 chars of JSON) */
-    input: string;
-    /** Duration in milliseconds */
-    durationMs: number;
-    /** Result status */
-    status: 'ok' | 'error';
-    /** Short result summary (first 200 chars) */
-    output: string;
+interface ReplayEntry {
+  /** ISO timestamp */
+  ts: string;
+  /** Source: 'mcp' | 'cli' */
+  source: 'mcp' | 'cli';
+  /** Tool or command name */
+  tool: string;
+  /** Redacted input summary (first 200 chars of JSON) */
+  input: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Result status */
+  status: 'ok' | 'error';
+  /** Short result summary (first 200 chars) */
+  output: string;
 }
-export interface ReplayOptions {
-    /** Max entries to return (default: 20) */
-    last?: number;
-    /** Filter by tool name */
-    tool?: string;
-    /** Filter by source */
-    source?: 'mcp' | 'cli';
-    /** Filter entries after this ISO timestamp */
-    since?: string;
+interface ReplayOptions {
+  /** Max entries to return (default: 20) */
+  last?: number;
+  /** Filter by tool name */
+  tool?: string;
+  /** Filter by source */
+  source?: 'mcp' | 'cli';
+  /** Filter entries after this ISO timestamp */
+  since?: string;
 }
 /**
  * Append a replay entry to the audit log.
  * Creates the `.kb-state/` directory if it doesn't exist.
  */
-export declare function replayAppend(entry: ReplayEntry): void;
+declare function replayAppend(entry: ReplayEntry): void;
 /**
  * Read replay entries with optional filters.
  */
-export declare function replayList(opts?: ReplayOptions): ReplayEntry[];
+declare function replayList(opts?: ReplayOptions): ReplayEntry[];
 /**
  * Trim the replay log to MAX_ENTRIES, keeping the most recent.
  */
-export declare function replayTrim(): number;
+declare function replayTrim(): number;
 /**
  * Clear the entire replay log.
  */
-export declare function replayClear(): void;
+declare function replayClear(): void;
 /**
  * Helper: create a replay entry from a tool invocation.
  * Use as a wrapper around tool execution.
  */
-export declare function replayCapture(source: 'mcp' | 'cli', tool: string, input: unknown, fn: () => Promise<unknown>): Promise<unknown>;
+declare function replayCapture(source: 'mcp' | 'cli', tool: string, input: unknown, fn: () => Promise<unknown>): Promise<unknown>;
+//#endregion
+export { ReplayEntry, ReplayOptions, replayAppend, replayCapture, replayClear, replayList, replayTrim };
 //# sourceMappingURL=replay.d.ts.map

package/packages/tools/dist/replay.js

@@ -1,6 +1,5 @@
-import{appendFileSync as m,mkdirSync as S,readFileSync as u,writeFileSync as l}from"node:fs";import{dirname as w,resolve as d}from"node:path";const a=5e3,p=200;function c(){return d(process.cwd(),".kb-state","replay.jsonl")}function f(t,r){return t.length<=r?t:`${t.slice(0,r-1)}\u2026`}function y(t){const r=c();S(w(r),{recursive:!0});const n={...t,input:f(t.input,p),output:f(t.output,p)};m(r,`${JSON.stringify(n)}
-`,"utf-8")}function E(t={}){const r=c();let n;try{n=u(r,"utf-8")}catch{return[]}const s=n.trim().split(`
-`).filter(Boolean);let e=[];for(const o of s)try{e.push(JSON.parse(o))}catch{}if(t.tool&&(e=e.filter(o=>o.tool===t.tool)),t.source&&(e=e.filter(o=>o.source===t.source)),t.since){const o=t.since;e=e.filter(g=>g.ts>=o)}const i=t.last??20;return e.slice(-i)}function k(){const t=c();let r;try{r=u(t,"utf-8")}catch{return 0}const n=r.trim().split(`
-`).filter(Boolean);if(n.length<=a)return 0;const s=n.length-a,e=n.slice(-a);return l(t,`${e.join(`
-`)}
-`,"utf-8"),s}function O(){const t=c();try{l(t,"","utf-8")}catch{}}function N(t,r,n,s){const e=Date.now();return s().then(i=>(y({ts:new Date().toISOString(),source:t,tool:r,input:typeof n=="string"?n:JSON.stringify(n),durationMs:Date.now()-e,status:"ok",output:typeof i=="string"?i:JSON.stringify(i??"")}),i)).catch(i=>{throw y({ts:new Date().toISOString(),source:t,tool:r,input:typeof n=="string"?n:JSON.stringify(n),durationMs:Date.now()-e,status:"error",output:i instanceof Error?i.message:String(i)}),i})}export{y as replayAppend,N as replayCapture,O as replayClear,E as replayList,k as replayTrim};
+import{dirname as e,resolve as t}from"node:path";import{appendFileSync as n,mkdirSync as r,readFileSync as i,writeFileSync as a}from"node:fs";const o=5e3;let s=0;function c(){return t(process.cwd(),`.kb-state`,`replay.jsonl`)}function l(e,t){return e.length<=t?e:`${e.slice(0,t-1)}…`}function u(t){let i=c();r(e(i),{recursive:!0});let a={...t,input:l(t.input,200),output:l(t.output,200)};if(n(i,`${JSON.stringify(a)}\n`,`utf-8`),s++,s>=100){s=0;try{f()}catch{}}}function d(e={}){let t=c(),n;try{n=i(t,`utf-8`)}catch{return[]}let r=n.trim().split(`
+`).filter(Boolean),a=[];for(let e of r)try{a.push(JSON.parse(e))}catch{}if(e.tool&&(a=a.filter(t=>t.tool===e.tool)),e.source&&(a=a.filter(t=>t.source===e.source)),e.since){let t=e.since;a=a.filter(e=>e.ts>=t)}let o=e.last??20;return a.slice(-o)}function f(){let e=c(),t;try{t=i(e,`utf-8`)}catch{return 0}let n=t.trim().split(`
+`).filter(Boolean);if(n.length<=o)return 0;let r=n.length-o;return a(e,`${n.slice(-o).join(`
+`)}\n`,`utf-8`),r}function p(){let e=c();try{a(e,``,`utf-8`)}catch{}}function m(e,t,n,r){let i=Date.now();return r().then(r=>(u({ts:new Date().toISOString(),source:e,tool:t,input:typeof n==`string`?n:JSON.stringify(n),durationMs:Date.now()-i,status:`ok`,output:typeof r==`string`?r:JSON.stringify(r??``)}),r)).catch(r=>{throw u({ts:new Date().toISOString(),source:e,tool:t,input:typeof n==`string`?n:JSON.stringify(n),durationMs:Date.now()-i,status:`error`,output:r instanceof Error?r.message:String(r)}),r})}export{u as replayAppend,m as replayCapture,p as replayClear,d as replayList,f as replayTrim};
+//# sourceMappingURL=replay.js.map

package/packages/tools/dist/response-envelope.d.ts

@@ -0,0 +1,44 @@
+//#region packages/tools/src/response-envelope.d.ts
+/**
+ * Standardized response envelope for KB tools (E-009).
+ * New tools should return KBResponse<T>. Existing tools can adopt gradually.
+ */
+interface KBNextHint {
+  tool: string;
+  reason: string;
+  suggested_args?: Record<string, unknown>;
+}
+interface KBError {
+  code: KBErrorCode;
+  category: 'input' | 'runtime' | 'dependency' | 'timeout' | 'not_found';
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+}
+type KBErrorCode = 'SYMBOL_NOT_FOUND' | 'INDEX_STALE' | 'TREE_SITTER_UNAVAILABLE' | 'PARSE_FAILED' | 'BUDGET_EXCEEDED' | 'PATH_NOT_FOUND' | 'EMBEDDING_COLD_START' | 'ANALYSIS_FAILED';
+interface KBResponseMeta {
+  durationMs: number;
+  tokensEstimate: number;
+  detail: 'summary' | 'errors' | 'full';
+  cached: boolean;
+  truncated: boolean;
+  caveats?: string[];
+}
+interface KBResponse<T> {
+  ok: boolean;
+  tool: string;
+  summary: string;
+  data?: T;
+  meta: KBResponseMeta;
+  next?: KBNextHint[];
+  error?: KBError;
+}
+/** Create a success response. */
+declare function okResponse<T>(tool: string, summary: string, data: T, meta: Partial<KBResponseMeta> & {
+  durationMs: number;
+}, next?: KBNextHint[]): KBResponse<T>;
+/** Create an error response. */
+declare function errorResponse(tool: string, error: KBError, durationMs: number): KBResponse<never>;
+//#endregion
+export { KBError, KBErrorCode, KBNextHint, KBResponse, KBResponseMeta, errorResponse, okResponse };
+//# sourceMappingURL=response-envelope.d.ts.map

package/packages/tools/dist/response-envelope.js

@@ -0,0 +1,2 @@
+import{estimateTokens as e}from"./text-utils.js";function t(t,n,r,i,a){let o=typeof r==`string`?r:JSON.stringify(r);return{ok:!0,tool:t,summary:n,data:r,meta:{durationMs:i.durationMs,tokensEstimate:i.tokensEstimate??e(o),detail:i.detail??`summary`,cached:i.cached??!1,truncated:i.truncated??!1,...i.caveats?.length?{caveats:i.caveats}:{}},next:a}}function n(t,n,r){return{ok:!1,tool:t,summary:n.message,meta:{durationMs:r,tokensEstimate:e(n.message),detail:`summary`,cached:!1,truncated:!1},error:n}}export{n as errorResponse,t as okResponse};
+//# sourceMappingURL=response-envelope.js.map

package/packages/tools/dist/schema-validate.d.ts

@@ -1,3 +1,4 @@
+//#region packages/tools/src/schema-validate.d.ts
 /**
  * kb_schema_validate — Validate data against a JSON Schema (core subset).
  *
@@ -5,19 +6,21 @@
  * enum, const, pattern, minimum, maximum, minLength, maxLength,
  * minItems, maxItems.
  */
-export interface SchemaValidateOptions {
-    data: unknown;
-    schema: Record<string, unknown>;
+interface SchemaValidateOptions {
+  data: unknown;
+  schema: Record<string, unknown>;
 }
-export interface ValidationError {
-    path: string;
-    message: string;
-    expected?: string;
-    received?: string;
+interface ValidationError {
+  path: string;
+  message: string;
+  expected?: string;
+  received?: string;
 }
-export interface SchemaValidateResult {
-    valid: boolean;
-    errors: ValidationError[];
+interface SchemaValidateResult {
+  valid: boolean;
+  errors: ValidationError[];
 }
-export declare function schemaValidate(options: SchemaValidateOptions): SchemaValidateResult;
+declare function schemaValidate(options: SchemaValidateOptions): SchemaValidateResult;
+//#endregion
+export { SchemaValidateOptions, SchemaValidateResult, ValidationError, schemaValidate };
 //# sourceMappingURL=schema-validate.d.ts.map

package/packages/tools/dist/schema-validate.js

@@ -1 +1,2 @@
-function m(e){const n=[];return u(e.data,e.schema,"$",n),{valid:n.length===0,errors:n}}function u(e,n,r,t){if("type"in n){const i=n.type;if(!f(e,i)){t.push({path:r,message:`Expected type "${i}"`,expected:i,received:l(e)});return}}if("enum"in n){const i=n.enum;i.some(o=>JSON.stringify(o)===JSON.stringify(e))||t.push({path:r,message:`Must be one of: ${JSON.stringify(i)}`,received:JSON.stringify(e)})}if("const"in n&&JSON.stringify(e)!==JSON.stringify(n.const)&&t.push({path:r,message:`Must equal ${JSON.stringify(n.const)}`,received:JSON.stringify(e)}),typeof e=="string"&&("minLength"in n&&e.length<n.minLength&&t.push({path:r,message:`String too short (min: ${n.minLength})`,received:`length ${e.length}`}),"maxLength"in n&&e.length>n.maxLength&&t.push({path:r,message:`String too long (max: ${n.maxLength})`,received:`length ${e.length}`}),"pattern"in n&&!new RegExp(n.pattern).test(e)&&t.push({path:r,message:`Does not match pattern: ${n.pattern}`})),typeof e=="number"&&("minimum"in n&&e<n.minimum&&t.push({path:r,message:`Below minimum (${n.minimum})`,received:String(e)}),"maximum"in n&&e>n.maximum&&t.push({path:r,message:`Above maximum (${n.maximum})`,received:String(e)})),Array.isArray(e)&&("minItems"in n&&e.length<n.minItems&&t.push({path:r,message:`Too few items (min: ${n.minItems})`,received:`length ${e.length}`}),"maxItems"in n&&e.length>n.maxItems&&t.push({path:r,message:`Too many items (max: ${n.maxItems})`,received:`length ${e.length}`}),"items"in n))for(let i=0;i<e.length;i++)u(e[i],n.items,`${r}[${i}]`,t);if(e&&typeof e=="object"&&!Array.isArray(e)){const i=e;if("required"in n)for(const o of n.required)o in i||t.push({path:`${r}.${o}`,message:"Required property missing"});if("properties"in n){const o=n.properties;for(const[s,g]of Object.entries(o))s in i&&u(i[s],g,`${r}.${s}`,t)}if("additionalProperties"in n&&n.additionalProperties===!1){const o=Object.keys(n.properties??{});for(const s of Object.keys(i))o.includes(s)||t.push({path:`${r}.${s}`,message:"Additional property not allowed"})}}}function f(e,n){switch(n){case"string":return typeof e=="string";case"number":return typeof e=="number"&&!Number.isNaN(e);case"integer":return typeof e=="number"&&Number.isInteger(e);case"boolean":return typeof e=="boolean";case"null":return e===null;case"array":return Array.isArray(e);case"object":return e!==null&&typeof e=="object"&&!Array.isArray(e);default:return!0}}function l(e){return e===null?"null":Array.isArray(e)?"array":typeof e}export{m as schemaValidate};
+function e(e){let n=[];return t(e.data,e.schema,`$`,n),{valid:n.length===0,errors:n}}function t(e,i,a,o){if(`type`in i){let t=i.type;if(!n(e,t)){o.push({path:a,message:`Expected type "${t}"`,expected:t,received:r(e)});return}}if(`enum`in i){let t=i.enum;t.some(t=>JSON.stringify(t)===JSON.stringify(e))||o.push({path:a,message:`Must be one of: ${JSON.stringify(t)}`,received:JSON.stringify(e)})}if(`const`in i&&JSON.stringify(e)!==JSON.stringify(i.const)&&o.push({path:a,message:`Must equal ${JSON.stringify(i.const)}`,received:JSON.stringify(e)}),typeof e==`string`&&(`minLength`in i&&e.length<i.minLength&&o.push({path:a,message:`String too short (min: ${i.minLength})`,received:`length ${e.length}`}),`maxLength`in i&&e.length>i.maxLength&&o.push({path:a,message:`String too long (max: ${i.maxLength})`,received:`length ${e.length}`}),`pattern`in i&&!new RegExp(i.pattern).test(e)&&o.push({path:a,message:`Does not match pattern: ${i.pattern}`})),typeof e==`number`&&(`minimum`in i&&e<i.minimum&&o.push({path:a,message:`Below minimum (${i.minimum})`,received:String(e)}),`maximum`in i&&e>i.maximum&&o.push({path:a,message:`Above maximum (${i.maximum})`,received:String(e)})),Array.isArray(e)&&(`minItems`in i&&e.length<i.minItems&&o.push({path:a,message:`Too few items (min: ${i.minItems})`,received:`length ${e.length}`}),`maxItems`in i&&e.length>i.maxItems&&o.push({path:a,message:`Too many items (max: ${i.maxItems})`,received:`length ${e.length}`}),`items`in i))for(let n=0;n<e.length;n++)t(e[n],i.items,`${a}[${n}]`,o);if(e&&typeof e==`object`&&!Array.isArray(e)){let n=e;if(`required`in i)for(let e of i.required)e in n||o.push({path:`${a}.${e}`,message:`Required property missing`});if(`properties`in i){let e=i.properties;for(let[r,i]of Object.entries(e))r in n&&t(n[r],i,`${a}.${r}`,o)}if(`additionalProperties`in i&&i.additionalProperties===!1){let e=Object.keys(i.properties??{});for(let t of Object.keys(n))e.includes(t)||o.push({path:`${a}.${t}`,message:`Additional property not allowed`})}}}function n(e,t){switch(t){case`string`:return typeof e==`string`;case`number`:return typeof e==`number`&&!Number.isNaN(e);case`integer`:return typeof e==`number`&&Number.isInteger(e);case`boolean`:return typeof e==`boolean`;case`null`:return e===null;case`array`:return Array.isArray(e);case`object`:return typeof e==`object`&&!!e&&!Array.isArray(e);default:return!0}}function r(e){return e===null?`null`:Array.isArray(e)?`array`:typeof e}export{e as schemaValidate};
+//# sourceMappingURL=schema-validate.js.map

package/packages/tools/dist/scope-map.d.ts

@@ -1,52 +1,52 @@
-/**
- * kb_scope_map — Task-scoped reading plan generator.
- *
- * Given a task description, searches the KB to identify which files
- * and sections are relevant, then produces a prioritized reading plan
- * with estimated token counts.
- */
-import type { IEmbedder } from '@kb/embeddings';
-import type { IKnowledgeStore } from '@kb/store';
-export interface ScopeMapOptions {
-    /** Description of the task to scope */
-    task: string;
-    /** Maximum number of files to include (default: 15) */
-    maxFiles?: number;
-    /** Group results by directory (default: true) */
-    groupByDirectory?: boolean;
-    /** Filter by content type */
-    contentType?: string;
-    /** Filter by origin */
-    origin?: string;
+import { IEmbedder } from "@kb/embeddings";
+import { IKnowledgeStore } from "@kb/store";
+import { ContentType, KnowledgeOrigin } from "@kb/core";
+
+//#region packages/tools/src/scope-map.d.ts
+interface ScopeMapOptions {
+  /** Description of the task to scope */
+  task: string;
+  /** Maximum number of files to include (default: 15) */
+  maxFiles?: number;
+  /** Group results by directory (default: true) */
+  groupByDirectory?: boolean;
+  /** Filter by content type */
+  contentType?: ContentType;
+  /** Filter by origin */
+  origin?: KnowledgeOrigin;
 }
-export interface ScopeMapEntry {
-    /** File path */
-    path: string;
-    /** Why this file is relevant (derived from matched chunks) */
-    reason: string;
-    /** Estimated token count (chars / 4 approximation) */
-    estimatedTokens: number;
-    /** Relevance score (0-1) */
-    relevance: number;
-    /** Line ranges to focus on */
-    focusRanges: Array<{
-        start: number;
-        end: number;
-        heading?: string;
-    }>;
+interface ScopeMapEntry {
+  /** File path */
+  path: string;
+  /** Why this file is relevant (derived from matched chunks) */
+  reason: string;
+  /** Estimated token count (chars / 4 approximation) */
+  estimatedTokens: number;
+  /** Relevance score (0-1) */
+  relevance: number;
+  /** Line ranges to focus on */
+  focusRanges: Array<{
+    start: number;
+    end: number;
+    heading?: string;
+  }>;
 }
-export interface ScopeMapResult {
-    /** The task that was analyzed */
-    task: string;
-    /** Prioritized file list */
-    files: ScopeMapEntry[];
-    /** Total estimated tokens across all files */
-    totalEstimatedTokens: number;
-    /** Suggested reading order (file paths) */
-    readingOrder: string[];
+interface ScopeMapResult {
+  /** The task that was analyzed */
+  task: string;
+  /** Prioritized file list */
+  files: ScopeMapEntry[];
+  /** Total estimated tokens across all files */
+  totalEstimatedTokens: number;
+  /** Suggested reading order (file paths) */
+  readingOrder: string[];
+  /** Suggested compact/file_summary commands to reduce context */
+  compactCommands: string[];
 }
 /**
  * Generate a task-scoped reading plan.
  */
-export declare function scopeMap(embedder: IEmbedder, store: IKnowledgeStore, options: ScopeMapOptions): Promise<ScopeMapResult>;
+declare function scopeMap(embedder: IEmbedder, store: IKnowledgeStore, options: ScopeMapOptions): Promise<ScopeMapResult>;
+//#endregion
+export { ScopeMapEntry, ScopeMapOptions, ScopeMapResult, scopeMap };
 //# sourceMappingURL=scope-map.d.ts.map

package/packages/tools/dist/scope-map.js

@@ -1 +1,2 @@
-function M(c){return Math.ceil(c.length/4)}async function T(c,h,u){const{task:d,maxFiles:m=15,contentType:l,origin:g}=u,f=await c.embed(d),S={limit:m*3,contentType:l,origin:g},x=await h.search(f,S),s=new Map;for(const e of x){const t=e.record.sourcePath,r=s.get(t);r?(r.chunks.push(e),r.totalChars+=e.record.content.length,r.maxScore=Math.max(r.maxScore,e.score)):s.set(t,{chunks:[e],totalChars:e.record.content.length,maxScore:e.score})}const o=[...s.entries()].sort(([,e],[,t])=>t.maxScore-e.maxScore).slice(0,m).map(([e,{chunks:t,maxScore:r}])=>{const a=t.sort((n,p)=>n.record.startLine-p.record.startLine).map(n=>({start:n.record.startLine,end:n.record.endLine,heading:n.record.headingPath})),i=t.sort((n,p)=>p.score-n.score)[0],b=i.record.headingPath?`Matches: ${i.record.headingPath}`:`Contains relevant ${i.record.contentType} content`;return{path:e,reason:b,estimatedTokens:0,relevance:r,focusRanges:a}});for(const e of o){const t=s.get(e.path);t&&(e.estimatedTokens=M(t.chunks.map(r=>r.record.content).join("")))}const y=o.reduce((e,t)=>e+t.estimatedTokens,0),k=[...o].sort((e,t)=>{const r=e.path.includes("config")||e.path.includes("types")?-1:0,a=t.path.includes("config")||t.path.includes("types")?-1:0;return r!==a?r-a:t.relevance-e.relevance}).map(e=>e.path);return{task:d,files:o,totalEstimatedTokens:y,readingOrder:k}}export{T as scopeMap};
+function e(e){return Math.ceil(e.length/4)}async function t(t,n,r){let{task:i,maxFiles:a=15,contentType:o,origin:s}=r,c=await t.embed(i),l={limit:a*3,contentType:o,origin:s},u=await n.search(c,l),d=new Map;for(let e of u){let t=e.record.sourcePath,n=d.get(t);n?(n.chunks.push(e),n.totalChars+=e.record.content.length,n.maxScore=Math.max(n.maxScore,e.score)):d.set(t,{chunks:[e],totalChars:e.record.content.length,maxScore:e.score})}let f=[...d.entries()].sort(([,e],[,t])=>t.maxScore-e.maxScore).slice(0,a).map(([e,{chunks:t,maxScore:n}])=>{let r=t.sort((e,t)=>e.record.startLine-t.record.startLine).map(e=>({start:e.record.startLine,end:e.record.endLine,heading:e.record.headingPath})),i=t.sort((e,t)=>t.score-e.score)[0];return{path:e,reason:i.record.headingPath?`Matches: ${i.record.headingPath}`:`Contains relevant ${i.record.contentType} content`,estimatedTokens:0,relevance:n,focusRanges:r}});for(let t of f){let n=d.get(t.path);n&&(t.estimatedTokens=e(n.chunks.map(e=>e.record.content).join(``)))}let p=f.reduce((e,t)=>e+t.estimatedTokens,0),m=[...f].sort((e,t)=>{let n=e.path.includes(`config`)||e.path.includes(`types`)?-1:0,r=t.path.includes(`config`)||t.path.includes(`types`)?-1:0;return n===r?t.relevance-e.relevance:n-r}).map(e=>e.path),h=[];for(let e of f)e.estimatedTokens<=100?h.push(`kb_file_summary({ path: "${e.path}" })  → ~${e.estimatedTokens} tokens`):h.push(`kb_compact({ path: "${e.path}", query: "${i}" })  → ~${Math.ceil(e.estimatedTokens/5)} tokens`);return{task:i,files:f,totalEstimatedTokens:p,readingOrder:m,compactCommands:h}}export{t as scopeMap};
+//# sourceMappingURL=scope-map.js.map

package/packages/tools/dist/snippet.d.ts

@@ -1,34 +1,36 @@
+//#region packages/tools/src/snippet.d.ts
 /**
  * kb_snippet — Persistent code template storage with search.
  */
-export interface Snippet {
-    name: string;
-    language: string;
-    code: string;
-    tags: string[];
-    created: string;
-    updated: string;
+interface Snippet {
+  name: string;
+  language: string;
+  code: string;
+  tags: string[];
+  created: string;
+  updated: string;
 }
-export type SnippetAction = 'save' | 'get' | 'list' | 'search' | 'delete';
-export interface SnippetOptions {
-    action: SnippetAction;
-    name?: string;
-    language?: string;
-    code?: string;
-    tags?: string[];
-    query?: string;
+type SnippetAction = 'save' | 'get' | 'list' | 'search' | 'delete';
+interface SnippetOptions {
+  action: SnippetAction;
+  name?: string;
+  language?: string;
+  code?: string;
+  tags?: string[];
+  query?: string;
 }
-export type SnippetResult = Snippet | {
-    snippets: SnippetSummary[];
+type SnippetResult = Snippet | {
+  snippets: SnippetSummary[];
 } | {
-    deleted: boolean;
+  deleted: boolean;
 };
 interface SnippetSummary {
-    name: string;
-    language: string;
-    tags: string[];
-    updated: string;
+  name: string;
+  language: string;
+  tags: string[];
+  updated: string;
 }
-export declare function snippet(options: SnippetOptions): SnippetResult;
-export {};
+declare function snippet(options: SnippetOptions): SnippetResult;
+//#endregion
+export { Snippet, SnippetAction, SnippetOptions, SnippetResult, snippet };
 //# sourceMappingURL=snippet.d.ts.map

package/packages/tools/dist/snippet.js

@@ -1 +1,2 @@
-import{existsSync as p,mkdirSync as f,readdirSync as l,readFileSync as u,unlinkSync as m,writeFileSync as S}from"node:fs";import{join as a}from"node:path";const o=()=>a(process.cwd(),".kb-state","snippets");function d(){const e=o();return p(e)||f(e,{recursive:!0}),e}function g(e){const n=e.replace(/[^a-zA-Z0-9_-]/g,"_");if(!n)throw new Error("Invalid snippet name");return n}function h(e){switch(e.action){case"save":{if(!e.name||!e.code)throw new Error("name and code required for save");const n=d(),s=g(e.name),i=a(n,`${s}.json`),r=p(i)?JSON.parse(u(i,"utf8")):null,t=new Date().toISOString(),c={name:e.name,language:e.language??"text",code:e.code,tags:e.tags??[],created:r?.created??t,updated:t};return S(i,JSON.stringify(c,null,2)),c}case"get":{if(!e.name)throw new Error("name required for get");const n=a(o(),`${g(e.name)}.json`);if(!p(n))throw new Error(`Snippet not found: ${e.name}`);return JSON.parse(u(n,"utf8"))}case"list":{const n=d();return{snippets:l(n).filter(r=>r.endsWith(".json")).map(r=>{const t=JSON.parse(u(a(n,r),"utf8"));return{name:t.name,language:t.language,tags:t.tags,updated:t.updated}})}}case"search":{if(!e.query)throw new Error("query required for search");const n=e.query.toLowerCase(),s=d();return{snippets:l(s).filter(t=>t.endsWith(".json")).map(t=>JSON.parse(u(a(s,t),"utf8"))).filter(t=>t.name.toLowerCase().includes(n)||t.tags.some(c=>c.toLowerCase().includes(n))||t.language.toLowerCase().includes(n)||t.code.toLowerCase().includes(n)).map(t=>({name:t.name,language:t.language,tags:t.tags,updated:t.updated}))}}case"delete":{if(!e.name)throw new Error("name required for delete");const n=a(o(),`${g(e.name)}.json`);return p(n)?(m(n),{deleted:!0}):{deleted:!1}}default:throw new Error(`Unknown action: ${e.action}`)}}export{h as snippet};
+import{join as e}from"node:path";import{existsSync as t,mkdirSync as n,readFileSync as r,readdirSync as i,unlinkSync as a,writeFileSync as o}from"node:fs";const s=()=>e(process.cwd(),`.kb-state`,`snippets`);function c(){let e=s();return t(e)||n(e,{recursive:!0}),e}function l(e){let t=e.replace(/[^a-zA-Z0-9_-]/g,`_`);if(!t)throw Error(`Invalid snippet name`);return t}function u(n){switch(n.action){case`save`:{if(!n.name||!n.code)throw Error(`name and code required for save`);let i=e(c(),`${l(n.name)}.json`),a=null;if(t(i))try{a=JSON.parse(r(i,`utf8`))}catch{a=null}let s=new Date().toISOString(),u={name:n.name,language:n.language??`text`,code:n.code,tags:n.tags??[],created:a?.created??s,updated:s};return o(i,JSON.stringify(u,null,2)),u}case`get`:{if(!n.name)throw Error(`name required for get`);let i=e(s(),`${l(n.name)}.json`);if(!t(i))throw Error(`Snippet not found: ${n.name}`);try{return JSON.parse(r(i,`utf8`))}catch{throw Error(`Snippet corrupted: ${n.name}`)}}case`list`:{let t=c();return{snippets:i(t).filter(e=>e.endsWith(`.json`)).flatMap(n=>{try{let i=JSON.parse(r(e(t,n),`utf8`));return[{name:i.name,language:i.language,tags:i.tags,updated:i.updated}]}catch{return[]}})}}case`search`:{if(!n.query)throw Error(`query required for search`);let t=n.query.toLowerCase(),a=c();return{snippets:i(a).filter(e=>e.endsWith(`.json`)).flatMap(t=>{try{return[JSON.parse(r(e(a,t),`utf8`))]}catch{return[]}}).filter(e=>e.name.toLowerCase().includes(t)||e.tags.some(e=>e.toLowerCase().includes(t))||e.language.toLowerCase().includes(t)||e.code.toLowerCase().includes(t)).map(e=>({name:e.name,language:e.language,tags:e.tags,updated:e.updated}))}}case`delete`:{if(!n.name)throw Error(`name required for delete`);let r=e(s(),`${l(n.name)}.json`);return t(r)?(a(r),{deleted:!0}):{deleted:!1}}default:throw Error(`Unknown action: ${n.action}`)}}export{u as snippet};
+//# sourceMappingURL=snippet.js.map

package/packages/tools/dist/stash.d.ts

@@ -1,12 +1,15 @@
-export interface StashEntry {
-    key: string;
-    value: unknown;
-    type: string;
-    storedAt: string;
+//#region packages/tools/src/stash.d.ts
+interface StashEntry {
+  key: string;
+  value: unknown;
+  type: string;
+  storedAt: string;
 }
-export declare function stashSet(key: string, value: unknown, cwd?: string): StashEntry;
-export declare function stashGet(key: string, cwd?: string): StashEntry | undefined;
-export declare function stashList(cwd?: string): StashEntry[];
-export declare function stashDelete(key: string, cwd?: string): boolean;
-export declare function stashClear(cwd?: string): number;
+declare function stashSet(key: string, value: unknown, cwd?: string): StashEntry;
+declare function stashGet(key: string, cwd?: string): StashEntry | undefined;
+declare function stashList(cwd?: string): StashEntry[];
+declare function stashDelete(key: string, cwd?: string): boolean;
+declare function stashClear(cwd?: string): number;
+//#endregion
+export { StashEntry, stashClear, stashDelete, stashGet, stashList, stashSet };
 //# sourceMappingURL=stash.d.ts.map

package/packages/tools/dist/stash.js

@@ -1,2 +1,2 @@
-import{existsSync as a,mkdirSync as u,readFileSync as h,writeFileSync as S}from"node:fs";import{dirname as g,resolve as f}from"node:path";const y=".kb-state",p="stash.json";function c(t){const n=t??process.cwd();return f(n,y,p)}function e(t){const n=c(t);if(!a(n))return{};const r=h(n,"utf-8");return JSON.parse(r)}function o(t,n){const r=c(n),s=g(r);a(s)||u(s,{recursive:!0}),S(r,`${JSON.stringify(t,null,2)}
-`,"utf-8")}function E(t,n,r){const s=e(r),i={key:t,value:n,type:typeof n,storedAt:new Date().toISOString()};return s[t]=i,o(s,r),i}function m(t,n){return e(n)[t]}function x(t){return Object.values(e(t))}function b(t,n){const r=e(n);return t in r?(delete r[t],o(r,n),!0):!1}function v(t){const n=e(t),r=Object.keys(n).length;return o({},t),r}export{v as stashClear,b as stashDelete,m as stashGet,x as stashList,E as stashSet};
+import{dirname as e,resolve as t}from"node:path";import{existsSync as n,mkdirSync as r,readFileSync as i,writeFileSync as a}from"node:fs";function o(e){return t(e??process.cwd(),`.kb-state`,`stash.json`)}function s(e){let t=o(e);if(!n(t))return{};try{let e=i(t,`utf-8`);return JSON.parse(e)}catch{return{}}}function c(t,i){let s=o(i),c=e(s);n(c)||r(c,{recursive:!0}),a(s,`${JSON.stringify(t,null,2)}\n`,`utf-8`)}function l(e,t,n){let r=s(n),i={key:e,value:t,type:typeof t,storedAt:new Date().toISOString()};return r[e]=i,c(r,n),i}function u(e,t){return s(t)[e]}function d(e){return Object.values(s(e))}function f(e,t){let n=s(t);return e in n?(delete n[e],c(n,t),!0):!1}function p(e){let t=s(e),n=Object.keys(t).length;return c({},e),n}export{p as stashClear,f as stashDelete,u as stashGet,d as stashList,l as stashSet};
+//# sourceMappingURL=stash.js.map