@shrkcrft/context 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/context
+
+SharkCraft AI context builder: token-budgeted relevance retrieval for tasks.
+
+Part of [SharkCraft](https://github.com/sharkcraft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/context
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/ai-context-formatter.d.ts

@@ -0,0 +1,8 @@
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+export interface FormatEntryOptions {
+    includeExamples?: boolean;
+    maxContentChars?: number;
+}
+export declare function formatEntryForContext(entry: IKnowledgeEntry, options?: FormatEntryOptions): string;
+export declare function formatSectionBody(entries: readonly IKnowledgeEntry[], options?: FormatEntryOptions): string;
+//# sourceMappingURL=ai-context-formatter.d.ts.map

package/dist/ai-context-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-context-formatter.d.ts","sourceRoot":"","sources":["../src/ai-context-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAoCR;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAE/G"}

package/dist/ai-context-formatter.js

@@ -0,0 +1,37 @@
+export function formatEntryForContext(entry, options = {}) {
+    const lines = [];
+    const meta = [
+        `id:${entry.id}`,
+        `priority:${entry.priority}`,
+        entry.scope.length ? `scope:[${entry.scope.join(',')}]` : '',
+        entry.tags.length ? `tags:[${entry.tags.join(',')}]` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    lines.push(`### ${entry.title} (${meta})`);
+    if (entry.summary) {
+        lines.push(entry.summary.trim());
+    }
+    let content = entry.content.trim();
+    if (options.maxContentChars && content.length > options.maxContentChars) {
+        content = content.slice(0, options.maxContentChars) + '…';
+    }
+    lines.push(content);
+    if (options.includeExamples && entry.examples?.length) {
+        lines.push('Examples:');
+        for (const ex of entry.examples) {
+            if (ex.title)
+                lines.push(`- ${ex.title}`);
+            if (ex.code) {
+                const lang = ex.language ?? '';
+                lines.push('```' + lang);
+                lines.push(ex.code.trim());
+                lines.push('```');
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function formatSectionBody(entries, options = {}) {
+    return entries.map((e) => formatEntryForContext(e, options)).join('\n\n');
+}

package/dist/context-builder.d.ts

@@ -0,0 +1,7 @@
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import { type IContextRequest } from './context-request.js';
+import type { IContextResult } from './context-result.js';
+import { formatEntryForContext } from './ai-context-formatter.js';
+export declare function buildContext(allEntries: readonly IKnowledgeEntry[], request: IContextRequest): IContextResult;
+export { formatEntryForContext };
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../src/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAqB,MAAM,2BAA2B,CAAC;AASrF,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,GACvB,cAAc,CAiGhB;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/context-builder.js

@@ -0,0 +1,97 @@
+import { aggregateActionHints, formatAggregatedHints } from '@shrkcrft/knowledge';
+import { DEFAULT_CONTEXT_REQUEST } from "./context-request.js";
+import { selectRelevantEntries } from "./relevance-selector.js";
+import { formatEntryForContext, formatSectionBody } from "./ai-context-formatter.js";
+import { countTokens } from "./tokenizer.js";
+export function buildContext(allEntries, request) {
+    const r = { ...DEFAULT_CONTEXT_REQUEST, ...request };
+    const maxTokens = r.maxTokens ?? DEFAULT_CONTEXT_REQUEST.maxTokens;
+    const buckets = selectRelevantEntries(allEntries, r);
+    const sectionPlans = [];
+    if (r.includeOverview && r.projectOverview) {
+        sectionPlans.push({
+            title: 'Project Overview',
+            priority: 100,
+            entries: [],
+        });
+    }
+    if (r.includeWarnings && buckets.warnings.length) {
+        sectionPlans.push({ title: 'Important Warnings', priority: 95, entries: buckets.warnings });
+    }
+    if (r.includeRules) {
+        sectionPlans.push({ title: 'Relevant Rules', priority: 90, entries: buckets.rules });
+    }
+    sectionPlans.push({ title: 'Architecture Constraints', priority: 80, entries: buckets.architecture });
+    if (r.includePaths) {
+        sectionPlans.push({ title: 'Relevant Path Conventions', priority: 70, entries: buckets.paths });
+    }
+    if (r.includeTemplates) {
+        sectionPlans.push({ title: 'Relevant Templates', priority: 65, entries: buckets.templates });
+    }
+    sectionPlans.push({ title: 'Technical Stack', priority: 50, entries: buckets.technical });
+    sectionPlans.push({ title: 'Testing Guidelines', priority: 45, entries: buckets.testing });
+    sectionPlans.push({ title: 'Security Guidelines', priority: 44, entries: buckets.security });
+    if (r.includeCommands) {
+        sectionPlans.push({ title: 'Commands', priority: 40, entries: buckets.commands });
+    }
+    sectionPlans.push({ title: 'Current Tasks', priority: 30, entries: buckets.tasks });
+    if (r.includeDocs) {
+        sectionPlans.push({ title: 'Reference Docs', priority: 10, entries: buckets.docs });
+    }
+    sectionPlans.sort((a, b) => b.priority - a.priority);
+    const sections = [];
+    const omitted = [];
+    let used = 0;
+    function tryAddSection(title, body, entryIds) {
+        const tokens = countTokens(body);
+        if (used + tokens > maxTokens && sections.length > 0) {
+            omitted.push(title);
+            return;
+        }
+        if (used + tokens > maxTokens) {
+            // Still emit, but mark truncated.
+            const ratio = (maxTokens - used) / tokens;
+            const truncatedBody = body.slice(0, Math.max(0, Math.floor(body.length * ratio))) + '\n…[truncated]';
+            const truncTokens = countTokens(truncatedBody);
+            sections.push({ title, body: truncatedBody, entryIds, tokens: truncTokens, truncated: true });
+            used += truncTokens;
+            return;
+        }
+        sections.push({ title, body, entryIds, tokens });
+        used += tokens;
+    }
+    for (const plan of sectionPlans) {
+        if (plan.title === 'Project Overview' && r.projectOverview) {
+            tryAddSection('Project Overview', r.projectOverview.trim(), []);
+            continue;
+        }
+        if (plan.entries.length === 0)
+            continue;
+        const body = formatSectionBody(plan.entries, {
+            includeExamples: r.includeExamples,
+            maxContentChars: 1500,
+        });
+        const ids = plan.entries.map((e) => e.id);
+        tryAddSection(plan.title, body, ids);
+    }
+    // Action hints: aggregate from every included entry and emit a single
+    // composite "Agent Actions" section. Skipped when no entry contributes.
+    const allIncludedEntries = sectionPlans.flatMap((p) => p.entries);
+    const aggregated = aggregateActionHints(allIncludedEntries);
+    const hintsBody = formatAggregatedHints(aggregated, { level: '###', compact: true });
+    if (hintsBody && hintsBody.length > 0) {
+        tryAddSection('Agent Actions', hintsBody, aggregated.contributingEntries);
+    }
+    const fullBody = sections
+        .map((s) => `## ${s.title}${s.truncated ? ' (truncated)' : ''}\n\n${s.body}`)
+        .join('\n\n');
+    return {
+        request: r,
+        sections,
+        totalTokens: used,
+        maxTokens,
+        omittedSections: omitted,
+        body: fullBody,
+    };
+}
+export { formatEntryForContext };

package/dist/context-request.d.ts

@@ -0,0 +1,20 @@
+export interface IContextRequest {
+    task: string;
+    framework?: string;
+    area?: string;
+    tags?: readonly string[];
+    scope?: readonly string[];
+    appliesWhen?: readonly string[];
+    maxTokens?: number;
+    includeExamples?: boolean;
+    includeTemplates?: boolean;
+    includeRules?: boolean;
+    includePaths?: boolean;
+    includeDocs?: boolean;
+    includeOverview?: boolean;
+    includeWarnings?: boolean;
+    includeCommands?: boolean;
+    projectOverview?: string;
+}
+export declare const DEFAULT_CONTEXT_REQUEST: Required<Pick<IContextRequest, 'maxTokens' | 'includeExamples' | 'includeTemplates' | 'includeRules' | 'includePaths' | 'includeDocs' | 'includeOverview' | 'includeWarnings' | 'includeCommands'>>;
+//# sourceMappingURL=context-request.d.ts.map

package/dist/context-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-request.d.ts","sourceRoot":"","sources":["../src/context-request.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAC5C,IAAI,CACF,eAAe,EACb,WAAW,GACX,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,CACpB,CAWF,CAAC"}

package/dist/context-request.js

@@ -0,0 +1,11 @@
+export const DEFAULT_CONTEXT_REQUEST = {
+    maxTokens: 4000,
+    includeExamples: true,
+    includeTemplates: true,
+    includeRules: true,
+    includePaths: true,
+    includeDocs: false,
+    includeOverview: true,
+    includeWarnings: true,
+    includeCommands: false,
+};

package/dist/context-result.d.ts

@@ -0,0 +1,12 @@
+import type { IContextSection } from './context-section.js';
+import type { IContextRequest } from './context-request.js';
+export interface IContextResult {
+    request: IContextRequest;
+    sections: readonly IContextSection[];
+    totalTokens: number;
+    maxTokens: number;
+    omittedSections: readonly string[];
+    /** Combined render of all sections (in order). */
+    body: string;
+}
+//# sourceMappingURL=context-result.d.ts.map

package/dist/context-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-result.d.ts","sourceRoot":"","sources":["../src/context-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/context-result.js

@@ -0,0 +1 @@
+export {};

package/dist/context-section.d.ts

@@ -0,0 +1,12 @@
+export interface IContextSection {
+    title: string;
+    /** Entry IDs included (for traceability). */
+    entryIds: readonly string[];
+    /** Compact, AI-ready body. */
+    body: string;
+    /** Approximate token cost. */
+    tokens: number;
+    /** Marker if section was truncated due to budget. */
+    truncated?: boolean;
+}
+//# sourceMappingURL=context-section.d.ts.map

package/dist/context-section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-section.d.ts","sourceRoot":"","sources":["../src/context-section.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/context-section.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './context-request.js';
+export * from './context-result.js';
+export * from './context-section.js';
+export * from './context-builder.js';
+export * from './token-estimator.js';
+export * from './tokenizer.js';
+export * from './relevance-selector.js';
+export * from './ai-context-formatter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./context-request.js";
+export * from "./context-result.js";
+export * from "./context-section.js";
+export * from "./context-builder.js";
+export * from "./token-estimator.js";
+export * from "./tokenizer.js";
+export * from "./relevance-selector.js";
+export * from "./ai-context-formatter.js";

package/dist/relevance-selector.d.ts

@@ -0,0 +1,17 @@
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { IContextRequest } from './context-request.js';
+export interface SelectedEntries {
+    rules: IKnowledgeEntry[];
+    paths: IKnowledgeEntry[];
+    templates: IKnowledgeEntry[];
+    architecture: IKnowledgeEntry[];
+    technical: IKnowledgeEntry[];
+    warnings: IKnowledgeEntry[];
+    commands: IKnowledgeEntry[];
+    testing: IKnowledgeEntry[];
+    security: IKnowledgeEntry[];
+    docs: IKnowledgeEntry[];
+    tasks: IKnowledgeEntry[];
+}
+export declare function selectRelevantEntries(allEntries: readonly IKnowledgeEntry[], request: IContextRequest, limitPerSection?: number): SelectedEntries;
+//# sourceMappingURL=relevance-selector.d.ts.map

package/dist/relevance-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance-selector.d.ts","sourceRoot":"","sources":["../src/relevance-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAeD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,EACxB,eAAe,SAAI,GAClB,eAAe,CAuCjB"}

package/dist/relevance-selector.js

@@ -0,0 +1,54 @@
+import { KnowledgeIndex } from '@shrkcrft/knowledge';
+const TYPE_BUCKETS = {
+    rule: 'rules',
+    path: 'paths',
+    template: 'templates',
+    architecture: 'architecture',
+    technical: 'technical',
+    warning: 'warnings',
+    command: 'commands',
+    testing: 'testing',
+    security: 'security',
+    task: 'tasks',
+};
+export function selectRelevantEntries(allEntries, request, limitPerSection = 5) {
+    const index = new KnowledgeIndex(allEntries);
+    const tags = [...(request.tags ?? [])];
+    const scope = [...(request.scope ?? [])];
+    if (request.framework)
+        scope.push(request.framework);
+    if (request.area)
+        scope.push(request.area);
+    const searchAll = index.search({
+        query: request.task,
+        scope,
+        tags,
+        appliesWhen: request.appliesWhen,
+    });
+    const buckets = {
+        rules: [],
+        paths: [],
+        templates: [],
+        architecture: [],
+        technical: [],
+        warnings: [],
+        commands: [],
+        testing: [],
+        security: [],
+        docs: [],
+        tasks: [],
+    };
+    for (const r of searchAll) {
+        const typeKey = String(r.entry.type).toLowerCase();
+        const bucketKey = TYPE_BUCKETS[typeKey];
+        if (bucketKey) {
+            if (buckets[bucketKey].length < limitPerSection)
+                buckets[bucketKey].push(r.entry);
+        }
+        else if (request.includeDocs) {
+            if (buckets.docs.length < limitPerSection)
+                buckets.docs.push(r.entry);
+        }
+    }
+    return buckets;
+}

package/dist/token-estimator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Approximate token count. Average English token ≈ 4 chars.
+ * Good enough for a v1 budget gate; not a substitute for a real tokenizer.
+ */
+export declare function estimateTokens(text: string): number;
+export declare function fitsBudget(currentTokens: number, addTokens: number, max: number): boolean;
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../src/token-estimator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzF"}

package/dist/token-estimator.js

@@ -0,0 +1,15 @@
+/**
+ * Approximate token count. Average English token ≈ 4 chars.
+ * Good enough for a v1 budget gate; not a substitute for a real tokenizer.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Use a slightly conservative ratio so we stay under budget.
+    const chars = text.length;
+    const words = text.trim().split(/\s+/).length;
+    return Math.max(Math.ceil(chars / 4), Math.ceil(words * 1.3));
+}
+export function fitsBudget(currentTokens, addTokens, max) {
+    return currentTokens + addTokens <= max;
+}

package/dist/tokenizer.d.ts

@@ -0,0 +1,29 @@
+export interface ITokenizer {
+    /** Human-readable name, surfaced in diagnostics. */
+    readonly name: string;
+    /** Total token count for `text`. Must be deterministic for a given input. */
+    countTokens(text: string): number;
+}
+export declare function getTokenizer(): ITokenizer;
+export declare function setTokenizer(tokenizer: ITokenizer): void;
+export declare function resetTokenizer(): void;
+export declare function countTokens(text: string): number;
+export interface ITokenizerInitOptions {
+    /**
+     * Which BPE encoding to load. Defaults to `cl100k_base` (GPT-4 / GPT-3.5);
+     * pass `o200k_base` for GPT-4o-class models.
+     */
+    encoding?: 'cl100k_base' | 'o200k_base';
+    /**
+     * If true, throw on load failure instead of falling back silently. Useful
+     * in tests; not recommended in production paths.
+     */
+    strict?: boolean;
+}
+/**
+ * Asynchronously upgrade the active tokenizer from the estimator to a real
+ * BPE encoder. Resolves to `true` if the swap happened; resolves to `false`
+ * (or rejects, when `strict`) if the tokenizer module could not be loaded.
+ */
+export declare function initTokenizer(options?: ITokenizerInitOptions): Promise<boolean>;
+//# sourceMappingURL=tokenizer.d.ts.map

package/dist/tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAyBD,wBAAgB,YAAY,IAAI,UAAU,CAEzC;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAExD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBzF"}

package/dist/tokenizer.js

@@ -0,0 +1,80 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Token counting abstraction.
+ *
+ * The context builder needs to fit content under a budget — wrong counts mean
+ * either truncated context (under-counted) or wasted budget (over-counted).
+ * Real BPE tokenizers are accurate; the legacy `estimateTokens` is a 4-char
+ * heuristic kept as a fallback so the package still loads in environments
+ * where the tokenizer can't be imported.
+ *
+ * Default flow:
+ *   1. On import, the estimator is the active tokenizer (always works).
+ *   2. Call `await initTokenizer()` once at startup to swap in the real
+ *      tokenizer. If that fails for any reason, the estimator stays active.
+ *   3. `countTokens(text)` always returns a number, synchronously.
+ */
+import { estimateTokens } from "./token-estimator.js";
+class EstimatorTokenizer {
+    name = 'estimator';
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+}
+class GptTokenizer {
+    encode;
+    name;
+    constructor(name, encode) {
+        this.encode = encode;
+        this.name = name;
+    }
+    countTokens(text) {
+        if (!text)
+            return 0;
+        return this.encode(text).length;
+    }
+}
+let activeTokenizer = new EstimatorTokenizer();
+export function getTokenizer() {
+    return activeTokenizer;
+}
+export function setTokenizer(tokenizer) {
+    activeTokenizer = tokenizer;
+}
+export function resetTokenizer() {
+    activeTokenizer = new EstimatorTokenizer();
+}
+export function countTokens(text) {
+    return activeTokenizer.countTokens(text);
+}
+/**
+ * Asynchronously upgrade the active tokenizer from the estimator to a real
+ * BPE encoder. Resolves to `true` if the swap happened; resolves to `false`
+ * (or rejects, when `strict`) if the tokenizer module could not be loaded.
+ */
+export async function initTokenizer(options = {}) {
+    const encoding = options.encoding ?? 'cl100k_base';
+    try {
+        const moduleName = encoding === 'o200k_base' ? 'gpt-tokenizer/encoding/o200k_base' : 'gpt-tokenizer/encoding/cl100k_base';
+        const mod = (await import(__rewriteRelativeImportExtension(moduleName)));
+        if (typeof mod.encode !== 'function') {
+            if (options.strict)
+                throw new Error(`gpt-tokenizer module ${moduleName} missing encode()`);
+            return false;
+        }
+        setTokenizer(new GptTokenizer(`gpt-tokenizer:${encoding}`, mod.encode));
+        return true;
+    }
+    catch (err) {
+        if (options.strict)
+            throw err;
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@shrkcrft/context",
+  "version": "0.1.0-alpha.1",
+  "description": "SharkCraft AI context builder: token-budgeted relevance retrieval for tasks.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/context"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "context",
+    "ai",
+    "token-budget",
+    "mcp"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.1",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.1",
+    "@shrkcrft/paths": "^0.1.0-alpha.1",
+    "@shrkcrft/rules": "^0.1.0-alpha.1",
+    "@shrkcrft/templates": "^0.1.0-alpha.1",
+    "gpt-tokenizer": "^3.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}