@vpxa/aikit 0.1.1

package/packages/core/dist/content-detector.js

@@ -0,0 +1 @@
+import{AIKIT_PATHS as e}from"./constants.js";import{basename as t,extname as n}from"node:path";const r={".ts":`code-typescript`,".tsx":`code-typescript`,".mts":`code-typescript`,".cts":`code-typescript`,".js":`code-javascript`,".jsx":`code-javascript`,".mjs":`code-javascript`,".cjs":`code-javascript`,".py":`code-python`,".json":`config-json`,".yaml":`config-yaml`,".yml":`config-yaml`,".toml":`config-toml`,".env":`config-env`,".md":`markdown`,".mdx":`markdown`},i=[/\.test\.[jt]sx?$/,/\.spec\.[jt]sx?$/,/(^|\/)__tests__\//,/(^|\/)test\//,/(^|\/)tests\//,/(^|\/)spec\//,/(^|\/)fixtures\//],a=[/\.stack\.[jt]s$/,/(^|\/)stacks\//,/(^|\/)constructs\//,/cdk\.json$/];function o(o){let s=n(o).toLowerCase(),c=t(o).toLowerCase();return o.includes(`${e.aiKb}/`)?`produced-knowledge`:o.includes(`${e.aiCurated}/`)?`curated-knowledge`:i.some(e=>e.test(o))?`test-code`:a.some(e=>e.test(o))?`cdk-stack`:s in r?r[s]:c.startsWith(`.env`)?`config-env`:[`.go`,`.rs`,`.java`,`.rb`,`.php`,`.sh`,`.ps1`,`.sql`,`.graphql`,`.proto`,`.css`,`.scss`,`.less`,`.html`,`.htm`,`.vue`,`.svelte`,`.astro`,`.hbs`,`.ejs`,`.svg`].includes(s)?`code-other`:`unknown`}const s={"code-typescript":`source`,"code-javascript":`source`,"code-python":`source`,"code-other":`source`,"cdk-stack":`source`,"test-code":`test`,markdown:`documentation`,documentation:`documentation`,"curated-knowledge":`documentation`,"produced-knowledge":`documentation`,"config-json":`config`,"config-yaml":`config`,"config-toml":`config`,"config-env":`config`,unknown:`source`};function c(e){return s[e]??`source`}function l(e){return Object.entries(s).filter(([,t])=>t===e).map(([e])=>e)}export{c as contentTypeToSourceType,o as detectContentType,l as sourceTypeContentTypes};

package/packages/core/dist/errors.d.ts

@@ -0,0 +1,20 @@
+//#region packages/core/src/errors.d.ts
+declare class KBError extends Error {
+  readonly code: string;
+  readonly cause?: unknown;
+  constructor(message: string, code: string, cause?: unknown);
+}
+declare class EmbeddingError extends KBError {
+  constructor(message: string, cause?: unknown);
+}
+declare class StoreError extends KBError {
+  constructor(message: string, cause?: unknown);
+}
+declare class IndexError extends KBError {
+  constructor(message: string, cause?: unknown);
+}
+declare class ConfigError extends KBError {
+  constructor(message: string, cause?: unknown);
+}
+//#endregion
+export { ConfigError, EmbeddingError, IndexError, KBError, StoreError };

package/packages/core/dist/errors.js

@@ -0,0 +1 @@
+var e=class extends Error{constructor(e,t,n){super(e,n===void 0?void 0:{cause:n}),this.code=t,this.name=`KBError`}},t=class extends e{constructor(e,t){super(e,`EMBEDDING_ERROR`,t),this.name=`EmbeddingError`}},n=class extends e{constructor(e,t){super(e,`STORE_ERROR`,t),this.name=`StoreError`}},r=class extends e{constructor(e,t){super(e,`INDEX_ERROR`,t),this.name=`IndexError`}},i=class extends e{constructor(e,t){super(e,`CONFIG_ERROR`,t),this.name=`ConfigError`}};export{i as ConfigError,t as EmbeddingError,r as IndexError,e as KBError,n as StoreError};

package/packages/core/dist/global-registry.d.ts

@@ -0,0 +1,63 @@
+//#region packages/core/src/global-registry.d.ts
+/**
+ * Global registry for tracking workspaces enrolled in global MCP install mode.
+ * Registry lives at ~/.aikit-data/registry.json alongside per-workspace partition directories.
+ */
+/** A single workspace entry in the global registry. */
+interface RegistryEntry {
+  /** Partition key: <folder-name>-<sha256-8chars> */
+  partition: string;
+  /** Absolute path to workspace root */
+  workspacePath: string;
+  /** ISO timestamp of first registration */
+  registeredAt: string;
+  /** ISO timestamp of last server start */
+  lastAccessedAt: string;
+}
+/** Schema for ~/.aikit-data/registry.json */
+interface GlobalRegistry {
+  version: 1;
+  workspaces: Record<string, RegistryEntry>;
+}
+/**
+ * Get the global data directory root.
+ * Override with `AIKIT_GLOBAL_DATA_DIR` env var for testing.
+ */
+declare function getGlobalDataDir(): string;
+/**
+ * Compute a deterministic partition key from a workspace path.
+ * Format: <folder-basename>-<sha256(absolutePath)-first8hex>
+ */
+declare function computePartitionKey(cwd: string): string;
+/**
+ * Load the global registry. Returns empty registry if file doesn't exist.
+ */
+declare function loadRegistry(): GlobalRegistry;
+/**
+ * Save the global registry atomically with file locking.
+ * Uses O_CREAT|O_EXCL lock file + write-to-tmp + rename pattern.
+ */
+declare function saveRegistry(registry: GlobalRegistry): void;
+/**
+ * Register a workspace in the global registry. Creates partition directory.
+ * If already registered, updates lastAccessedAt.
+ */
+declare function registerWorkspace(cwd: string): RegistryEntry;
+/**
+ * Look up a workspace in the registry by cwd.
+ */
+declare function lookupWorkspace(cwd: string): RegistryEntry | undefined;
+/**
+ * List all registered workspaces.
+ */
+declare function listWorkspaces(): RegistryEntry[];
+/**
+ * Get the absolute path to a partition's data directory.
+ */
+declare function getPartitionDir(partition: string): string;
+/**
+ * Check whether user-level mode is installed (registry.json exists in ~/.aikit-data/).
+ */
+declare function isUserInstalled(): boolean;
+//#endregion
+export { GlobalRegistry, RegistryEntry, computePartitionKey, getGlobalDataDir, getPartitionDir, isUserInstalled, listWorkspaces, loadRegistry, lookupWorkspace, registerWorkspace, saveRegistry };

package/packages/core/dist/global-registry.js

@@ -0,0 +1 @@
+import{AIKIT_GLOBAL_PATHS as e}from"./constants.js";import{basename as t,resolve as n}from"node:path";import{createHash as r}from"node:crypto";import{closeSync as i,constants as a,existsSync as o,mkdirSync as s,openSync as c,readFileSync as l,renameSync as u,statSync as d,unlinkSync as f,writeFileSync as p}from"node:fs";import{homedir as m}from"node:os";function h(){return process.env.AIKIT_GLOBAL_DATA_DIR??n(m(),e.root)}function g(e){let i=n(e);return`${t(i).toLowerCase().replace(/[^a-z0-9-]/g,`-`)||`workspace`}-${r(`sha256`).update(i).digest(`hex`).slice(0,8)}`}function _(){let t=n(h(),e.registry);if(!o(t))return{version:1,workspaces:{}};let r=l(t,`utf-8`);return JSON.parse(r)}function v(e,t=5e3){let n=`${e}.lock`,r=Date.now()+t,o=10;for(;Date.now()<r;)try{let e=c(n,a.O_CREAT|a.O_EXCL|a.O_WRONLY);return p(e,`${process.pid}\n`),i(e),n}catch(e){if(e.code!==`EEXIST`)throw e;try{let{mtimeMs:e}=d(n);if(Date.now()-e>3e4){f(n);continue}}catch{}let t=new SharedArrayBuffer(4);Atomics.wait(new Int32Array(t),0,0,o),o=Math.min(o*2,200)}throw Error(`Failed to acquire registry lock after ${t}ms`)}function y(e){try{f(e)}catch{}}function b(t){let r=h();s(r,{recursive:!0});let i=n(r,e.registry),a=v(i);try{let e=`${i}.tmp`;p(e,JSON.stringify(t,null,2),`utf-8`),u(e,i)}finally{y(a)}}function x(e){let t=_(),r=g(e),i=new Date().toISOString();return t.workspaces[r]?t.workspaces[r].lastAccessedAt=i:t.workspaces[r]={partition:r,workspacePath:n(e),registeredAt:i,lastAccessedAt:i},s(w(r),{recursive:!0}),b(t),t.workspaces[r]}function S(e){let t=_(),n=g(e);return t.workspaces[n]}function C(){let e=_();return Object.values(e.workspaces)}function w(e){return n(h(),e)}function T(){return o(n(h(),e.registry))}export{g as computePartitionKey,h as getGlobalDataDir,w as getPartitionDir,T as isUserInstalled,C as listWorkspaces,_ as loadRegistry,S as lookupWorkspace,x as registerWorkspace,b as saveRegistry};

package/packages/core/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { AIKIT_GLOBAL_PATHS, AIKIT_PATHS, CATEGORY_PATTERN, CHUNK_SIZES, DEFAULT_CATEGORIES, EMBEDDING_DEFAULTS, FILE_LIMITS, SEARCH_DEFAULTS, STORE_DEFAULTS } from "./constants.js";
+import { CONTENT_TYPES, ChunkMetadata, ContentType, IndexStats, KBConfig, KNOWLEDGE_ORIGINS, KnowledgeOrigin, KnowledgeRecord, RawChunk, SOURCE_TYPES, SearchResult, SourceType } from "./types.js";
+import { contentTypeToSourceType, detectContentType, sourceTypeContentTypes } from "./content-detector.js";
+import { ConfigError, EmbeddingError, IndexError, KBError, StoreError } from "./errors.js";
+import { GlobalRegistry, RegistryEntry, computePartitionKey, getGlobalDataDir, getPartitionDir, isUserInstalled, listWorkspaces, loadRegistry, lookupWorkspace, registerWorkspace, saveRegistry } from "./global-registry.js";
+import { LogLevel, LogListener, addLogListener, createLogger, getLogLevel, resetLogDir, serializeError, setFileSinkEnabled, setLogLevel } from "./logger.js";
+export { AIKIT_GLOBAL_PATHS, AIKIT_PATHS, CATEGORY_PATTERN, CHUNK_SIZES, CONTENT_TYPES, ChunkMetadata, ConfigError, ContentType, DEFAULT_CATEGORIES, EMBEDDING_DEFAULTS, EmbeddingError, FILE_LIMITS, GlobalRegistry, IndexError, IndexStats, KBConfig, KBError, KNOWLEDGE_ORIGINS, KnowledgeOrigin, KnowledgeRecord, LogLevel, LogListener, RawChunk, RegistryEntry, SEARCH_DEFAULTS, SOURCE_TYPES, STORE_DEFAULTS, SearchResult, SourceType, StoreError, addLogListener, computePartitionKey, contentTypeToSourceType, createLogger, detectContentType, getGlobalDataDir, getLogLevel, getPartitionDir, isUserInstalled, listWorkspaces, loadRegistry, lookupWorkspace, registerWorkspace, resetLogDir, saveRegistry, serializeError, setFileSinkEnabled, setLogLevel, sourceTypeContentTypes };

package/packages/core/dist/index.js

@@ -0,0 +1 @@
+import{AIKIT_GLOBAL_PATHS as e,AIKIT_PATHS as t,CATEGORY_PATTERN as n,CHUNK_SIZES as r,DEFAULT_CATEGORIES as i,EMBEDDING_DEFAULTS as a,FILE_LIMITS as o,SEARCH_DEFAULTS as s,STORE_DEFAULTS as c}from"./constants.js";import{contentTypeToSourceType as l,detectContentType as u,sourceTypeContentTypes as d}from"./content-detector.js";import{ConfigError as f,EmbeddingError as p,IndexError as m,KBError as h,StoreError as g}from"./errors.js";import{computePartitionKey as _,getGlobalDataDir as v,getPartitionDir as y,isUserInstalled as b,listWorkspaces as x,loadRegistry as S,lookupWorkspace as C,registerWorkspace as w,saveRegistry as T}from"./global-registry.js";import{addLogListener as E,createLogger as D,getLogLevel as O,resetLogDir as k,serializeError as A,setFileSinkEnabled as j,setLogLevel as M}from"./logger.js";import{CONTENT_TYPES as N,KNOWLEDGE_ORIGINS as P,SOURCE_TYPES as F}from"./types.js";export{e as AIKIT_GLOBAL_PATHS,t as AIKIT_PATHS,n as CATEGORY_PATTERN,r as CHUNK_SIZES,N as CONTENT_TYPES,f as ConfigError,i as DEFAULT_CATEGORIES,a as EMBEDDING_DEFAULTS,p as EmbeddingError,o as FILE_LIMITS,m as IndexError,h as KBError,P as KNOWLEDGE_ORIGINS,s as SEARCH_DEFAULTS,F as SOURCE_TYPES,c as STORE_DEFAULTS,g as StoreError,E as addLogListener,_ as computePartitionKey,l as contentTypeToSourceType,D as createLogger,u as detectContentType,v as getGlobalDataDir,O as getLogLevel,y as getPartitionDir,b as isUserInstalled,x as listWorkspaces,S as loadRegistry,C as lookupWorkspace,w as registerWorkspace,k as resetLogDir,T as saveRegistry,A as serializeError,j as setFileSinkEnabled,M as setLogLevel,d as sourceTypeContentTypes};

package/packages/core/dist/logger.d.ts

@@ -0,0 +1,32 @@
+//#region packages/core/src/logger.d.ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type LogListener = (entry: {
+  level: LogLevel;
+  component: string;
+  message: string;
+  data?: Record<string, unknown>;
+}) => void;
+declare function setLogLevel(level: LogLevel): void;
+declare function getLogLevel(): LogLevel;
+declare function setFileSinkEnabled(enabled: boolean): void;
+/** Reset resolved log directory (for testing). */
+declare function resetLogDir(): void;
+/**
+ * Serialize an unknown error into a structured record suitable for JSON logging.
+ * Always includes stack traces for Error instances — they are essential for
+ * root-cause analysis regardless of the active log level.
+ */
+declare function serializeError(err: unknown): Record<string, unknown>;
+/**
+ * Register a listener that receives all log messages (after level filtering).
+ * Returns a cleanup function to remove the listener.
+ */
+declare function addLogListener(listener: LogListener): () => void;
+declare function createLogger(component: string): {
+  debug: (msg: string, data?: Record<string, unknown>) => void;
+  info: (msg: string, data?: Record<string, unknown>) => void;
+  warn: (msg: string, data?: Record<string, unknown>) => void;
+  error: (msg: string, data?: Record<string, unknown>) => void;
+};
+//#endregion
+export { LogLevel, LogListener, addLogListener, createLogger, getLogLevel, resetLogDir, serializeError, setFileSinkEnabled, setLogLevel };

package/packages/core/dist/logger.js

@@ -0,0 +1 @@
+import{AIKIT_PATHS as e}from"./constants.js";import{join as t,resolve as n}from"node:path";import{appendFileSync as r,mkdirSync as i,readdirSync as a,unlinkSync as o}from"node:fs";const s={debug:0,info:1,warn:2,error:3},c=[];let l=process.env.AIKIT_LOG_LEVEL??`info`,u=process.env.AIKIT_LOG_FILE_SINK===`true`||process.env.AIKIT_LOG_FILE_SINK!==`false`&&!process.env.VITEST&&process.env.NODE_ENV!==`test`;function d(){return u?process.env.VITEST||process.env.NODE_ENV===`test`?process.env.AIKIT_LOG_FILE_SINK===`true`:!0:!1}let f;function p(){return f||=n(process.cwd(),e.logs),f}function m(e){let n=e.toISOString().slice(0,10);return t(p(),`${n}.jsonl`)}let h=0;function g(){let e=Date.now();if(!(e-h<36e5)){h=e;try{let n=p(),r=new Date(e-30*864e5).toISOString().slice(0,10);for(let e of a(n))if(e.endsWith(`.jsonl`)&&e.slice(0,10)<r)try{o(t(n,e))}catch{}}catch{}}}function _(e,t){try{i(p(),{recursive:!0}),r(m(t),`${e}\n`),g()}catch{}}function v(e){l=e}function y(){return l}function b(e){u=e}function x(){f=void 0}function S(e){if(e instanceof Error){let t={error:e.message};return e.stack&&(t.stack=e.stack),e.cause!==void 0&&(t.cause=e.cause instanceof Error?e.cause.message:String(e.cause)),t}return{error:String(e)}}function C(e){return c.push(e),()=>{let t=c.indexOf(e);t>=0&&c.splice(t,1)}}function w(e){function t(t,n,r){if(s[t]<s[l])return;let i=new Date,a={ts:i.toISOString(),level:t,component:e,msg:n,...r},o=JSON.stringify(a);console.error(o);for(let i of c)try{i({level:t,component:e,message:n,data:r})}catch{}d()&&(t===`warn`||t===`error`)&&_(o,i)}return{debug:(e,n)=>t(`debug`,e,n),info:(e,n)=>t(`info`,e,n),warn:(e,n)=>t(`warn`,e,n),error:(e,n)=>t(`error`,e,n)}}export{C as addLogListener,w as createLogger,y as getLogLevel,x as resetLogDir,S as serializeError,b as setFileSinkEnabled,v as setLogLevel};

package/packages/core/dist/types.d.ts

@@ -0,0 +1,133 @@
+//#region packages/core/src/types.d.ts
+/**
+ * Core types for the MCP Knowledge Base system.
+ */
+/** The origin of a knowledge record — how it was created */
+declare const KNOWLEDGE_ORIGINS: readonly ["indexed", "curated", "produced"];
+type KnowledgeOrigin = (typeof KNOWLEDGE_ORIGINS)[number];
+/** Coarse source classification derived from ContentType */
+declare const SOURCE_TYPES: readonly ["source", "documentation", "test", "config", "generated"];
+type SourceType = (typeof SOURCE_TYPES)[number];
+/** Content type classification */
+declare const CONTENT_TYPES: readonly ["documentation", "code-typescript", "code-javascript", "code-python", "code-other", "config-json", "config-yaml", "config-toml", "config-env", "test-code", "cdk-stack", "markdown", "curated-knowledge", "produced-knowledge", "unknown"];
+type ContentType = (typeof CONTENT_TYPES)[number];
+/** A single knowledge record stored in the vector DB */
+interface KnowledgeRecord {
+  /** Unique identifier (deterministic hash of source + chunk index) */
+  id: string;
+  /** The text content of this chunk */
+  content: string;
+  /** Source file path relative to workspace root */
+  sourcePath: string;
+  /** Content type classification */
+  contentType: ContentType;
+  /** Heading path for markdown (e.g., "## Setup > ### Prerequisites") */
+  headingPath?: string;
+  /** Zero-based chunk index within the source file */
+  chunkIndex: number;
+  /** Total number of chunks from this source file */
+  totalChunks: number;
+  /** Start line in source file (1-based) */
+  startLine: number;
+  /** End line in source file (1-based) */
+  endLine: number;
+  /** File hash for incremental indexing */
+  fileHash: string;
+  /** ISO timestamp when this record was created/updated */
+  indexedAt: string;
+  /** How this record was created */
+  origin: KnowledgeOrigin;
+  /** User-defined tags for categorization */
+  tags: string[];
+  /** Category for curated/produced knowledge */
+  category?: string;
+  /** Version number for curated knowledge updates */
+  version: number;
+}
+/** A raw chunk produced by a chunker before embedding */
+interface RawChunk {
+  /** The text content */
+  text: string;
+  /** Source file path */
+  sourcePath: string;
+  /** Content type */
+  contentType: ContentType;
+  /** Heading path (markdown only) */
+  headingPath?: string;
+  /** Chunk index */
+  chunkIndex: number;
+  /** Total chunks from this file */
+  totalChunks: number;
+  /** Start line (1-based) */
+  startLine: number;
+  /** End line (1-based) */
+  endLine: number;
+}
+/** Metadata passed to a chunker */
+interface ChunkMetadata {
+  /** File path relative to workspace root */
+  sourcePath: string;
+  /** Detected content type */
+  contentType: ContentType;
+}
+/** Search result returned by the store */
+interface SearchResult {
+  /** The matching knowledge record */
+  record: KnowledgeRecord;
+  /** Similarity score (0-1, higher = more similar) */
+  score: number;
+}
+/** Configuration loaded from kb.config.json */
+interface KBConfig {
+  /** MCP server name. Defaults to 'kb'. */
+  serverName?: string;
+  /**
+   * Prefix prepended to every MCP tool name to avoid collisions with other
+   * MCP servers. E.g. `"aikit_"` turns `search` → `aikit_search`.
+   * Defaults to `""` (no prefix) for backward compatibility.
+   */
+  toolPrefix?: string;
+  sources: Array<{
+    path: string;
+    excludePatterns: string[];
+  }>;
+  indexing: {
+    chunkSize: number;
+    chunkOverlap: number;
+    minChunkSize: number; /** Max files processed concurrently. Defaults to half of available CPU cores. */
+    concurrency?: number;
+  };
+  embedding: {
+    model: string;
+    dimensions: number;
+  };
+  store: {
+    backend: string;
+    path: string;
+  };
+  curated: {
+    path: string;
+  };
+  /** Resolved directory for onboard/produce_knowledge output. User-level mode redirects this outside the project. */
+  onboardDir?: string;
+  /** Enterprise RAG bridge configuration (optional) */
+  er?: {
+    /** Whether ER integration is enabled */enabled: boolean; /** Base URL of the ER API (e.g., https://xxx.execute-api.region.amazonaws.com/prod) */
+    baseUrl: string; /** Request timeout in milliseconds. Defaults to 5000. */
+    timeoutMs?: number; /** Cache TTL in milliseconds. Defaults to 21600000 (6 hours). */
+    cacheTtlMs?: number; /** Maximum cache entries. Defaults to 100. */
+    cacheMaxEntries?: number; /** Vector similarity threshold below which ER fallback triggers. Defaults to 0.45. */
+    fallbackThreshold?: number;
+  };
+}
+/** Index statistics */
+interface IndexStats {
+  totalRecords: number;
+  totalFiles: number;
+  contentTypeBreakdown: Record<string, number>;
+  lastIndexedAt: string | null;
+  storeBackend: string;
+  embeddingModel: string;
+}
+//#endregion
+export { CONTENT_TYPES, ChunkMetadata, ContentType, IndexStats, KBConfig, KNOWLEDGE_ORIGINS, KnowledgeOrigin, KnowledgeRecord, RawChunk, SOURCE_TYPES, SearchResult, SourceType };

package/packages/core/dist/types.js

@@ -0,0 +1 @@
+const e=[`indexed`,`curated`,`produced`],t=[`source`,`documentation`,`test`,`config`,`generated`],n=[`documentation`,`code-typescript`,`code-javascript`,`code-python`,`code-other`,`config-json`,`config-yaml`,`config-toml`,`config-env`,`test-code`,`cdk-stack`,`markdown`,`curated-knowledge`,`produced-knowledge`,`unknown`];export{n as CONTENT_TYPES,e as KNOWLEDGE_ORIGINS,t as SOURCE_TYPES};