@ultrakit/ultrakit 0.0.0 → 0.0.2

package/dist/template/{.opencode → opencode}/package.json

@@ -1,14 +1,14 @@
 {
 	"name": "opencode",
 	"version": "1.0.0",
-	"description": "Opencode plugin",
+	"description": "OpenCode project template support package",
 	"keywords": [],
 	"license": "ISC",
 	"author": "",
 	"type": "module",
-	"main": "index.js",
 	"scripts": {
-		"type-check": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"type-check": "npm run typecheck"
 	},
 	"dependencies": {
 		"@opencode-ai/plugin": "1.4.9"

package/dist/template/{.opencode → opencode}/plugin/lib/context.ts

@@ -7,7 +7,8 @@
  * Protects the most recent N messages from compression.
  */
 
-import { estimateTokens, MEMORY_CONFIG } from "./memory-db.js";
+import { MEMORY_CONFIG } from "./db/types.js";
+import { estimateTokens } from "./db/pipeline.js";
 
 // ============================================================================
 // Types

package/dist/template/{.opencode → opencode}/plugin/lib/db/schema.ts

@@ -31,8 +31,26 @@ type DatabaseSyncConstructor = new (
 ) => DatabaseSyncLike;
 
 const require = createRequire(import.meta.url);
+/** Cached result of SQLite availability check */
+let sqliteAvailable: boolean | null = null;
 let DatabaseSyncCtor: DatabaseSyncConstructor | null = null;
+/**
+ * Check if node:sqlite module is available at runtime.
+ * Caches the result after first check.
+ * Returns false if node:sqlite is not available (Node < 22.5 or built without SQLite).
+ */
+export function isSQLiteAvailable(): boolean {
+	if (sqliteAvailable !== null) return sqliteAvailable;
+	try {
+		require("node:sqlite");
+		sqliteAvailable = true;
+	} catch {
+		sqliteAvailable = false;
+	}
+	return sqliteAvailable;
+}
 
+/** @internal — use isSQLiteAvailable() for guard checks */
 function getDatabaseSyncConstructor(): DatabaseSyncConstructor {
 	if (!DatabaseSyncCtor) {
 		const sqlite = require("node:sqlite") as {
@@ -422,6 +440,15 @@ let dbInstance: Database | null = null;
 export function getMemoryDB(): Database {
 	if (dbInstance) return dbInstance;
 
+	// Guard: check SQLite availability before attempting DB operations
+	if (!isSQLiteAvailable()) {
+		throw new Error(
+			"SQLite module (node:sqlite) is not available. " +
+				"Memory tools require Node.js >= 22.5 with SQLite support. " +
+			"Use compiled/ markdown files for persistent context, or install Honcho for cloud/local memory.",
+		);
+	}
+
 	const dbPath = path.join(process.cwd(), ".opencode/memory.db");
 
 	try {

package/dist/template/{.opencode → opencode}/plugin/lib/inject.ts

@@ -10,10 +10,11 @@
 
 import { tokenize } from "./distill.js";
 import {
-	estimateTokens,
 	getRelevantKnowledge,
 	MEMORY_CONFIG,
 } from "./memory-db.js";
+import { estimateTokens } from "./db/pipeline.js";
+import { isSQLiteAvailable } from "./db/schema.js";
 
 // ============================================================================
 // Query Term Extraction
@@ -63,6 +64,9 @@ export function extractQueryTerms(
 export function buildInjection(systemPrompt: string[]): string | null {
 	if (!MEMORY_CONFIG.injection.enabled) return null;
 
+	// Guard: skip DB-dependent injection when SQLite is unavailable
+	if (!isSQLiteAvailable()) return null;
+
 	// Extract query terms from current system context
 	const queryTerms = extractQueryTerms(systemPrompt);
 	if (queryTerms.length === 0) return null;

package/dist/template/{.opencode → opencode}/plugin/lib/memory-db.ts

@@ -70,7 +70,7 @@ export {
 	storeTemporalMessage,
 } from "./db/pipeline.js";
 // Database Manager
-export { closeMemoryDB, Database, getMemoryDB } from "./db/schema.js";
+export { closeMemoryDB, Database, getMemoryDB, isSQLiteAvailable } from "./db/schema.js";
 // Types & Configuration
 export * from "./db/types.js";
 export {

package/dist/template/{.opencode → opencode}/plugin/lib/memory-hooks.ts

@@ -25,9 +25,13 @@ import {
 	checkFTS5Available,
 	checkpointWAL,
 	getDatabaseSizes,
+	isSQLiteAvailable,
 	optimizeFTS5,
 } from "./memory-db.js";
 
+/** Whether we've already logged the SQLite-unavailable warning this session */
+let sqliteWarned = false;
+
 interface HookDeps {
 	showToast: (
 		title: string,
@@ -340,6 +344,16 @@ export function createHooks(deps: HookDeps) {
 			output: { system: string[] },
 		) => {
 			try {
+				if (!isSQLiteAvailable()) {
+					if (!sqliteWarned) {
+						sqliteWarned = true;
+						await log(
+							"SQLite unavailable — LTM injection disabled. Use compiled/ files or install Honcho.",
+							"warn",
+						);
+					}
+					return;
+				}
 				const injection = buildInjection(output.system);
 				if (injection) output.system.push(injection);
 			} catch {

package/dist/template/{.opencode → opencode}/plugin/lib/memory-tools.ts

@@ -11,6 +11,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { tool } from "@opencode-ai/plugin/tool";
+import { compactObservations } from "./compact.js";
 import {
 	addEntityTriple,
 	type ConfidenceLevel,
@@ -19,7 +20,9 @@ import {
 	getMemoryFile,
 	getObservationsByIds,
 	getTimelineAroundObservation,
+	type HallType,
 	invalidateTriple,
+	isSQLiteAvailable,
 	type ObservationSource,
 	type ObservationType,
 	queryEntity,
@@ -27,7 +30,6 @@ import {
 	searchObservationsFTS,
 	storeObservation,
 	upsertMemoryFile,
-	type HallType,
 	VALID_HALLS,
 } from "./memory-db.js";
 import {
@@ -39,21 +41,27 @@ import {
 	VALID_TYPES,
 } from "./memory-helpers.js";
 import { validateObservation } from "./validate.js";
-import { compactObservations } from "./compact.js";
 
 /**
  * Wrap a memory tool execute function with DB error handling.
  * Returns a user-friendly error message instead of raw SQLite crashes.
+ * Handles SQLite unavailability, corruption, and generic DB errors.
  */
 function withDBErrorHandling<T extends Record<string, unknown>>(
 	fn: (args: T) => Promise<string>,
 ): (args: T) => Promise<string> {
 	return async (args: T) => {
+		// Fast path: if SQLite is unavailable, skip DB operations entirely
+		if (!isSQLiteAvailable()) {
+			return (
+				"Memory tools unavailable — SQLite module (node:sqlite) not found. " +
+				"Use compiled/ markdown files for persistent context, or install Honcho for cloud/local memory."
+			);
+		}
 		try {
 			return await fn(args);
 		} catch (err) {
-			const message =
-				err instanceof Error ? err.message : String(err);
+			const message = err instanceof Error ? err.message : String(err);
 			if (
 				message.includes("database disk image is malformed") ||
 				message.includes("SQLITE_CORRUPT") ||
@@ -133,7 +141,9 @@ export function createCoreTools(deps: CoreToolDeps) {
 				hall: tool.schema
 					.string()
 					.optional()
-					.describe("Navigation hall: facts, events, discoveries, preferences, advice"),
+					.describe(
+						"Navigation hall: facts, events, discoveries, preferences, advice",
+					),
 				room: tool.schema
 					.string()
 					.optional()
@@ -141,7 +151,9 @@ export function createCoreTools(deps: CoreToolDeps) {
 				raw_source: tool.schema
 					.string()
 					.optional()
-					.describe("Verbatim source text to preserve losslessly alongside narrative"),
+					.describe(
+						"Verbatim source text to preserve losslessly alongside narrative",
+					),
 			},
 			execute: withDBErrorHandling(async (args) => {
 				const obsType = args.type as ObservationType;
@@ -206,7 +218,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 				});
 
 				if (validation.verdict === "reject") {
-					const reasons = validation.issues.map(i => i.message).join("; ");
+					const reasons = validation.issues.map((i) => i.message).join("; ");
 					const dupHint = validation.duplicateOf
 						? ` Use \`observation({ supersedes: "${validation.duplicateOf}", ... })\` to update it.`
 						: "";
@@ -232,9 +244,10 @@ export function createCoreTools(deps: CoreToolDeps) {
 					room: args.room,
 				});
 
-				const warnings = validation.issues.length > 0
-					? `\n⚠️ Warnings: ${validation.issues.map(i => i.message).join("; ")}`
-					: "";
+				const warnings =
+					validation.issues.length > 0
+						? `\n⚠️ Warnings: ${validation.issues.map((i) => i.message).join("; ")}`
+						: "";
 
 				return `${TYPE_ICONS[obsType] ?? "\uD83D\uDCCC"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})${warnings}`;
 			}),
@@ -435,15 +448,33 @@ export function createCoreTools(deps: CoreToolDeps) {
 			description: `Add a triple to the entity knowledge graph.\n\nStores a subject-predicate-object relationship with optional temporal bounds and confidence.\nUse for structured facts like "project uses typescript" or "user prefers dark-mode".\n\nExample:\nmemory-graph-add({ subject: "project", predicate: "uses", object: "typescript" })\nmemory-graph-add({ subject: "auth", predicate: "depends-on", object: "jwt", confidence: 0.9, source_observation_id: 42 })`,
 			args: {
 				subject: tool.schema.string().describe("Entity subject"),
-				predicate: tool.schema.string().describe("Relationship type (e.g. uses, depends-on, prefers)"),
+				predicate: tool.schema
+					.string()
+					.describe("Relationship type (e.g. uses, depends-on, prefers)"),
 				object: tool.schema.string().describe("Entity object"),
-				valid_from: tool.schema.string().optional().describe("Start date (ISO, default: today)"),
-				valid_to: tool.schema.string().optional().describe("End date (ISO, null = still active)"),
-				confidence: tool.schema.number().optional().describe("Confidence 0.0-1.0 (default: 1.0)"),
-				source_observation_id: tool.schema.number().optional().describe("Link to source observation"),
+				valid_from: tool.schema
+					.string()
+					.optional()
+					.describe("Start date (ISO, default: today)"),
+				valid_to: tool.schema
+					.string()
+					.optional()
+					.describe("End date (ISO, null = still active)"),
+				confidence: tool.schema
+					.number()
+					.optional()
+					.describe("Confidence 0.0-1.0 (default: 1.0)"),
+				source_observation_id: tool.schema
+					.number()
+					.optional()
+					.describe("Link to source observation"),
 			},
 			execute: withDBErrorHandling(async (args) => {
-				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+				if (
+					!args.subject?.trim() ||
+					!args.predicate?.trim() ||
+					!args.object?.trim()
+				) {
 					return "Error: subject, predicate, and object are required.";
 				}
 				const id = addEntityTriple({
@@ -463,11 +494,26 @@ export function createCoreTools(deps: CoreToolDeps) {
 			description: `Query the entity knowledge graph.\n\nFind relationships for an entity with optional time and direction filters.\nReturns triples where the entity appears as subject, object, or both.\n\nExample:\nmemory-graph-query({ entity: "typescript" })\nmemory-graph-query({ entity: "auth", direction: "out", active_only: true })\nmemory-graph-query({ entity: "project", as_of: "2025-06-01" })`,
 			args: {
 				entity: tool.schema.string().describe("Entity to query"),
-				direction: tool.schema.string().optional().describe("out (subject), in (object), both (default)"),
-				predicate: tool.schema.string().optional().describe("Filter by predicate"),
-				as_of: tool.schema.string().optional().describe("ISO date for point-in-time query"),
-				active_only: tool.schema.boolean().optional().describe("Only active triples (default: false)"),
-				limit: tool.schema.number().optional().describe("Max results (default: 50)"),
+				direction: tool.schema
+					.string()
+					.optional()
+					.describe("out (subject), in (object), both (default)"),
+				predicate: tool.schema
+					.string()
+					.optional()
+					.describe("Filter by predicate"),
+				as_of: tool.schema
+					.string()
+					.optional()
+					.describe("ISO date for point-in-time query"),
+				active_only: tool.schema
+					.boolean()
+					.optional()
+					.describe("Only active triples (default: false)"),
+				limit: tool.schema
+					.number()
+					.optional()
+					.describe("Max results (default: 50)"),
 			},
 			execute: withDBErrorHandling(async (args) => {
 				if (!args.entity?.trim()) return "Error: entity is required.";
@@ -478,14 +524,17 @@ export function createCoreTools(deps: CoreToolDeps) {
 					activeOnly: args.active_only,
 					limit: args.limit,
 				});
-				if (results.length === 0) return `No triples found for entity "${args.entity}".`;
+				if (results.length === 0)
+					return `No triples found for entity "${args.entity}".`;
 				const lines: string[] = [
 					`## Entity Graph: ${args.entity} (${results.length} triples)\n`,
 					"| ID | Subject | Predicate | Object | Active | Confidence |",
 					"|---|---|---|---|---|---|",
 				];
 				for (const r of results) {
-					lines.push(`| ${r.id} | ${r.subject} | ${r.predicate} | ${r.object} | ${r.is_active ? "\u2705" : "\u274C"} | ${(r.confidence * 100).toFixed(0)}% |`);
+					lines.push(
+						`| ${r.id} | ${r.subject} | ${r.predicate} | ${r.object} | ${r.is_active ? "\u2705" : "\u274C"} | ${(r.confidence * 100).toFixed(0)}% |`,
+					);
 				}
 				return lines.join("\n");
 			}),
@@ -497,13 +546,25 @@ export function createCoreTools(deps: CoreToolDeps) {
 				subject: tool.schema.string().describe("Entity subject"),
 				predicate: tool.schema.string().describe("Relationship type"),
 				object: tool.schema.string().describe("Entity object"),
-				end_date: tool.schema.string().optional().describe("End date (ISO, default: today)"),
+				end_date: tool.schema
+					.string()
+					.optional()
+					.describe("End date (ISO, default: today)"),
 			},
 			execute: withDBErrorHandling(async (args) => {
-				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+				if (
+					!args.subject?.trim() ||
+					!args.predicate?.trim() ||
+					!args.object?.trim()
+				) {
 					return "Error: subject, predicate, and object are required.";
 				}
-				const count = invalidateTriple(args.subject, args.predicate, args.object, args.end_date);
+				const count = invalidateTriple(
+					args.subject,
+					args.predicate,
+					args.object,
+					args.end_date,
+				);
 				return count > 0
 					? `Invalidated ${count} triple(s): ${args.subject} —[${args.predicate}]→ ${args.object}`
 					: `No active triples found matching ${args.subject} —[${args.predicate}]→ ${args.object}.`;
@@ -513,21 +574,40 @@ export function createCoreTools(deps: CoreToolDeps) {
 		"memory-compact": tool({
 			description: `Compact observations into a dense, token-efficient format.\n\nUses AAAK-inspired pipe-separated compression achieving ~3-5x token reduction.\nUseful for injecting memory into prompts with minimal token cost.\n\nExample:\nmemory-compact({})\nmemory-compact({ limit: 20 })`,
 			args: {
-				limit: tool.schema.number().optional().describe("Max observations to compact (default: all)"),
+				limit: tool.schema
+					.number()
+					.optional()
+					.describe("Max observations to compact (default: all)"),
 			},
 			execute: withDBErrorHandling(async (args) => {
 				const db = getMemoryDB();
 				const limitClause = args.limit ? `LIMIT ${Number(args.limit)}` : "";
-				const observations = db.query(
-					`SELECT id, type, title, narrative, concepts, wing, hall, room, confidence, created_at
+				const observations = db
+					.query(
+						`SELECT id, type, title, narrative, concepts, wing, hall, room, confidence, created_at
 					 FROM observations
 					 WHERE superseded_by IS NULL
-					 ORDER BY created_at_epoch DESC ${limitClause}`
-				).all() as { id: number; type: string; title: string; narrative?: string | null; concepts?: string | null; wing?: string | null; hall?: string | null; room?: string | null; confidence?: string | null; created_at?: string | null }[];
+					 ORDER BY created_at_epoch DESC ${limitClause}`,
+					)
+					.all() as {
+					id: number;
+					type: string;
+					title: string;
+					narrative?: string | null;
+					concepts?: string | null;
+					wing?: string | null;
+					hall?: string | null;
+					room?: string | null;
+					confidence?: string | null;
+					created_at?: string | null;
+				}[];
 				if (observations.length === 0) return "No observations to compact.";
 				const result = compactObservations(observations);
 				if (!result.compressed) return "No observations to compact.";
-				const ratio = result.compression_ratio > 0 ? ` (${(result.compression_ratio * 100).toFixed(0)}% of original)` : "";
+				const ratio =
+					result.compression_ratio > 0
+						? ` (${(result.compression_ratio * 100).toFixed(0)}% of original)`
+						: "";
 				return `## Compact Memory (${observations.length} observations, ~${result.token_estimate} tokens${ratio})\n\n${result.compressed}`;
 			}),
 		}),

package/dist/template/{.opencode → opencode}/skill/agent-evals/SKILL.md

@@ -1,12 +1,23 @@
 ---
 name: agent-evals
 description: Use when adding/changing a skill, command, or agent prompt and you want evidence it actually helps — not just intuition. Defines bounded-task evals, no-skill baselines, deterministic verifiers, JSONL trace logs, and when to skip eval. Adapted from OpenAI eval guide, OpenHands "evaluating agent skills", Anthropic "demystifying evals".
+version: 1.0.0
+tags: [testing, agent-coordination, automation]
+dependencies: []
 ---
 
 # Agent Evals
 
 > Without evals, every skill ships on vibes. The harness-engineering literature is unanimous: **measured changes beat believed-changes**. This skill gives you the smallest workable eval loop.
 
+## When NOT to Use
+
+- When the change is trivial and no measurable behavior is affected.
+- When deterministic evaluation would cost more than the change itself.
+- The change is mechanical (rename, refactor, lint fix)
+- The change is a one-shot fix with obvious verification (test passes / build green)
+- The skill is purely procedural with deterministic output (workspace setup)
+
 ## When to Use
 
 Run an eval when:
@@ -16,12 +27,6 @@ Run an eval when:
 - Comparing two approaches and you don't know which is better
 - A skill is suspected of being inert ("does this even do anything?")
 
-**Skip eval when:**
-
-- The change is mechanical (rename, refactor, lint fix)
-- The change is a one-shot fix with obvious verification (test passes / build green)
-- The skill is purely procedural with deterministic output (workspace setup)
-
 ## Core Principle: Bounded + Baseline + Verifier
 
 Three ingredients. Skip any one and the eval is theatre.

package/dist/template/{.opencode → opencode}/skill/anti-ai-slop/SKILL.md

@@ -1,12 +1,27 @@
 ---
 name: anti-ai-slop
 description: Use when generating any visual design output (web UI, slides, animations, mockups, infographics) to actively prevent the AI default aesthetic that strips brand identity. Bans purple gradients, emoji-as-icons, rounded-card+left-accent, AI-drawn human SVGs, GitHub-dark `#0D1117`, Inter/Roboto-as-display. Adapted from huashu-design.
+version: 1.0.0
+tags: [design, ui, code-quality]
+dependencies: [brand-asset-protocol]
 ---
 
 # Anti AI Slop
 
 > The AI default aesthetic is the **visual common denominator** of all training data. Using it makes every brand look identical. Avoiding it is **brand protection**, not aesthetic snobbery.
 
+
+
+## When NOT to Use
+
+- For non-visual implementation tasks.
+- When the user explicitly wants a quick wireframe or default prototype with no brand/aesthetic quality bar.
+
+## When to Use
+
+- When generating visual design output that needs to avoid generic AI-default aesthetics.
+- Before producing web UI, slides, animations, mockups, or branded visuals where visual distinctiveness matters.
+
 ## Why This Matters
 
 The reasoning chain:

package/dist/template/{.opencode → opencode}/skill/api-and-interface-design/SKILL.md

@@ -2,7 +2,7 @@
 name: api-and-interface-design
 description: Use when designing REST/GraphQL APIs, SDK interfaces, or public module boundaries — covers contract-first design, versioning, error shapes, and backward compatibility
 version: 1.0.0
-tags: [architecture, code-quality]
+tags: [integration, documentation]
 dependencies: []
 ---
 

package/dist/template/{.opencode → opencode}/skill/brand-asset-protocol/SKILL.md

@@ -1,12 +1,21 @@
 ---
 name: brand-asset-protocol
 description: Use when designing anything for a specific brand (logo, marketing site, product launch animation, branded slide deck, redesign). MUST load before producing branded visuals. Forces real logo + product image + UI screenshot fetch BEFORE any design work — color values alone are not enough for brand recognition. Includes 5-10-2-8 quality bar (5 search rounds, 10 candidates, pick 2 best, each ≥8/10).
+version: 1.0.0
+tags: [design, research, ui]
+dependencies: [webclaw]
 ---
 
 # Brand Asset Protocol
 
 > Adapted from `huashu-design`. Brand recognition lives in **assets first, color second**. Generic CSS shapes can never substitute a real logo or product image.
 
+
+## When NOT to Use
+
+- When the work is not tied to a real brand or product.
+- When the user already supplied approved brand assets and only implementation remains.
+
 ## When to Use
 
 Trigger this protocol whenever the task names a real brand or product:

package/dist/template/{.opencode → opencode}/skill/code-search-patterns/SKILL.md

@@ -2,7 +2,7 @@
 name: code-search-patterns
 description: Use when navigating unfamiliar code with search-first patterns, combining built-in/LSP navigation with tilth MCP (main agent) and tilth CLI (subagents)
 version: 1.0.0
-tags: [workflow, code-quality, context, subagent]
+tags: [research, code-quality, agent-coordination]
 dependencies: []
 ---
 

package/dist/template/{.opencode → opencode}/skill/code-simplification/SKILL.md

@@ -2,8 +2,8 @@
 name: code-simplification
 description: Use when reducing code complexity, eliminating dead code, or refactoring for clarity — enforces measure-before-cutting discipline to prevent breaking changes disguised as cleanup
 version: 1.0.0
-tags: [code-quality, refactoring]
-dependencies: [verification-before-completion]
+tags: [code-quality, workflow]
+dependencies: []
 ---
 
 # Code Simplification
@@ -23,6 +23,8 @@ dependencies: [verification-before-completion]
 - The code works, is readable, and isn't blocking anything — leave it alone
 - You're implementing a new feature (use incremental-implementation instead)
 - The "simplification" is actually a rewrite with different behavior
+- The cleanup touches unrelated active work or files outside your task scope
+- The change alters public behavior, error semantics, or compatibility under a cleanup label
 
 ## Common Rationalizations
 
@@ -41,6 +43,16 @@ Code simplification is the discipline of making code easier to understand and ma
 
 **Core principle:** Measure complexity, simplify the worst offender, verify nothing broke, repeat.
 
+## Slim-Style Simplification Principles
+
+1. **Preserve Behavior Exactly** — the public contract, side effects, error behavior, and edge cases must stay the same unless the user explicitly requested a behavior change.
+2. **Follow Project Conventions** — simplify toward the patterns already present in nearby code, not toward a personal style preference.
+3. **Prefer Clarity Over Cleverness** — choose obvious names, explicit control flow, and boring primitives over dense abstractions.
+4. **Maintain Balance** — do not flatten every abstraction; keep boundaries that protect testing, security, performance, compatibility, or domain language.
+5. **Scope to What Changed** — simplify only the smallest area needed for the task; record unrelated cleanup as noticed but not touching.
+
+These principles override cosmetic preferences. A simplification that changes behavior, breaks conventions, or expands scope is a regression, not cleanup.
+
 ## The Process
 
 ```