gyrus 0.1.0

package/src/tools/knowledge-search.ts

@@ -0,0 +1,65 @@
+/**
+ * knowledge_search MCP tool
+ * Search knowledge notes by text query, tags, or category
+ */
+
+import { z } from "zod";
+import type { WorkspaceManager } from "../services/workspace.ts";
+import { searchKnowledge } from "../operations/knowledge.ts";
+import { formatKnowledgeSearch } from "../formatters/knowledge.ts";
+
+/**
+ * Tool definition
+ */
+export const knowledgeSearchTool = {
+  name: "knowledge_search",
+  description:
+    "Search knowledge notes by text query, tags, or category. The query searches across note titles, content, IDs, and descriptions. Results are sorted by relevance (title matches first) then by last updated date. At least one search parameter must be provided. Use the 'workspace' parameter to target a specific workspace, otherwise uses the active workspace.",
+};
+
+/**
+ * Input schema
+ */
+export const knowledgeSearchSchema = z.object({
+  workspace: z
+    .string()
+    .optional()
+    .describe(
+      "Target workspace name. If not provided, uses the active workspace.",
+    ),
+  query: z
+    .string()
+    .optional()
+    .describe("Text to search for in note titles, content, and descriptions"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Filter by tags (matches notes with any of these tags)"),
+  category: z
+    .enum(["projects", "patterns", "tools", "gotchas", "decisions"])
+    .optional()
+    .describe("Filter by category folder"),
+});
+
+export type KnowledgeSearchInput = z.infer<typeof knowledgeSearchSchema>;
+
+/**
+ * Execute the tool
+ */
+export async function executeKnowledgeSearch(
+  manager: WorkspaceManager,
+  input: KnowledgeSearchInput,
+): Promise<string> {
+  const result = await searchKnowledge(manager, {
+    workspace: input.workspace,
+    query: input.query,
+    tags: input.tags,
+    category: input.category,
+  });
+
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+
+  return formatKnowledgeSearch(result.data!);
+}

package/src/tools/knowledge-update.ts

@@ -0,0 +1,76 @@
+/**
+ * knowledge_update MCP tool
+ * Update an existing knowledge note
+ */
+
+import { z } from "zod";
+import type { WorkspaceManager } from "../services/workspace.ts";
+import { updateKnowledge } from "../operations/knowledge.ts";
+import { formatKnowledgeUpdate } from "../formatters/knowledge.ts";
+
+/**
+ * Tool definition
+ */
+export const knowledgeUpdateTool = {
+  name: "knowledge_update",
+  description:
+    "Update an existing knowledge note's content or metadata. Only the fields you provide will be updated; other fields remain unchanged. The 'updated' date will be automatically set to today. The index.md file will be automatically updated if the title or tags change. Use the 'workspace' parameter to target a specific workspace, otherwise uses the active workspace.",
+};
+
+/**
+ * Input schema
+ */
+export const knowledgeUpdateSchema = z.object({
+  workspace: z
+    .string()
+    .optional()
+    .describe(
+      "Target workspace name. If not provided, uses the active workspace.",
+    ),
+  id: z.string().describe("The unique ID of the note to update"),
+  title: z.string().optional().describe("New title for the note (optional)"),
+  content: z
+    .string()
+    .optional()
+    .describe(
+      "New markdown content for the note (optional, replaces existing content)",
+    ),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("New tags for the note (optional, replaces existing tags)"),
+  related: z
+    .array(z.string())
+    .optional()
+    .describe("New related note IDs (optional, replaces existing related)"),
+  description: z
+    .string()
+    .optional()
+    .describe("New description for the note (optional)"),
+});
+
+export type KnowledgeUpdateInput = z.infer<typeof knowledgeUpdateSchema>;
+
+/**
+ * Execute the tool
+ */
+export async function executeKnowledgeUpdate(
+  manager: WorkspaceManager,
+  input: KnowledgeUpdateInput,
+): Promise<string> {
+  const result = await updateKnowledge(manager, {
+    workspace: input.workspace,
+    id: input.id,
+    title: input.title,
+    content: input.content,
+    tags: input.tags,
+    related: input.related,
+    description: input.description,
+  });
+
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+
+  return formatKnowledgeUpdate(result.data!);
+}

package/src/types/index.ts

@@ -0,0 +1,343 @@
+/**
+ * Core type definitions for Gyrus
+ * Model-agnostic knowledge management system
+ */
+
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
+/**
+ * A registered workspace in the config
+ */
+export interface Workspace {
+  /** Unique name for this workspace */
+  name: string;
+  /** Path to the workspace (supports ~ for home) */
+  path: string;
+  /** Human-readable description */
+  description: string;
+}
+
+/**
+ * Server settings in config
+ */
+export interface ServerSettings {
+  serve: {
+    port: number;
+  };
+  daemon: {
+    port: number;
+  };
+}
+
+/**
+ * Global Gyrus configuration stored at ~/.config/gyrus/config.json
+ */
+export interface GyrusConfig {
+  /** Config schema version */
+  version: number;
+  /** Name of the default workspace */
+  default: string;
+  /** List of registered workspaces */
+  workspaces: Workspace[];
+  /** Server settings */
+  settings: ServerSettings;
+}
+
+// =============================================================================
+// Knowledge Types
+// =============================================================================
+
+/**
+ * Valid knowledge categories (folder names)
+ */
+export type KnowledgeCategory =
+  | "projects"
+  | "patterns"
+  | "tools"
+  | "gotchas"
+  | "decisions"
+  | "root";
+
+/**
+ * YAML frontmatter fields for knowledge notes
+ */
+export interface KnowledgeFrontmatter {
+  id: string;
+  title: string;
+  created: string;
+  updated: string;
+  tags?: string[];
+  related?: string[];
+  description?: string;
+}
+
+/**
+ * A parsed knowledge note with frontmatter and content
+ */
+export interface KnowledgeNote {
+  /** Unique identifier from frontmatter */
+  id: string;
+  /** Human-readable title */
+  title: string;
+  /** Creation date (YYYY-MM-DD) */
+  created: string;
+  /** Last update date (YYYY-MM-DD) */
+  updated: string;
+  /** Categorization tags */
+  tags: string[];
+  /** Related note IDs for cross-referencing */
+  related: string[];
+  /** Optional description */
+  description?: string;
+  /** Markdown content (without frontmatter) */
+  content: string;
+  /** Relative path from knowledge folder */
+  path: string;
+  /** Category derived from folder */
+  category: KnowledgeCategory;
+}
+
+/**
+ * Input for creating a new knowledge note
+ */
+export interface CreateNoteInput {
+  /** Unique identifier (kebab-case) */
+  id: string;
+  /** Human-readable title */
+  title: string;
+  /** Category folder to place the note in */
+  category: Exclude<KnowledgeCategory, "root">;
+  /** Markdown content (without frontmatter) */
+  content: string;
+  /** Optional tags */
+  tags?: string[];
+  /** Optional related note IDs */
+  related?: string[];
+  /** Optional description */
+  description?: string;
+}
+
+/**
+ * Input for updating an existing knowledge note
+ */
+export interface UpdateNoteInput {
+  /** Note ID to update */
+  id: string;
+  /** New title (optional) */
+  title?: string;
+  /** New content (optional) */
+  content?: string;
+  /** New tags (optional, replaces existing) */
+  tags?: string[];
+  /** New related IDs (optional, replaces existing) */
+  related?: string[];
+  /** New description (optional) */
+  description?: string;
+}
+
+/**
+ * Search options for knowledge notes
+ */
+export interface SearchOptions {
+  /** Text to search for in content and title */
+  query?: string;
+  /** Filter by tags (matches any) */
+  tags?: string[];
+  /** Filter by category */
+  category?: KnowledgeCategory;
+}
+
+/**
+ * List options for knowledge notes
+ */
+export interface ListOptions {
+  /** Filter by category */
+  category?: KnowledgeCategory;
+  /** Filter by tags (matches any) */
+  tags?: string[];
+}
+
+/**
+ * Result from operations that modify notes
+ */
+export interface OperationResult {
+  success: boolean;
+  message: string;
+  note?: KnowledgeNote;
+}
+
+// =============================================================================
+// ADR (Architecture Decision Record) Types
+// =============================================================================
+
+/**
+ * Valid ADR status values
+ */
+export type AdrStatus =
+  | "todo"
+  | "in-progress"
+  | "in-review"
+  | "blocked"
+  | "completed"
+  | "deprecated";
+
+/**
+ * Valid ADR type values
+ */
+export type AdrType = "enhancement" | "debug" | "research";
+
+/**
+ * YAML frontmatter fields for ADR records
+ */
+export interface AdrFrontmatter {
+  title: string;
+  description?: string;
+  date_created: string;
+  date_updated: string;
+  status: AdrStatus;
+  type: AdrType;
+  tags?: string[];
+  working_folder: string;
+}
+
+/**
+ * A parsed ADR record with frontmatter and content
+ */
+export interface AdrRecord {
+  /** Filename without .md extension */
+  name: string;
+  /** Human-readable title */
+  title: string;
+  /** Brief description */
+  description?: string;
+  /** Creation date (YYYY-MM-DD) */
+  dateCreated: string;
+  /** Last update date (YYYY-MM-DD) */
+  dateUpdated: string;
+  /** Current status */
+  status: AdrStatus;
+  /** ADR type */
+  type: AdrType;
+  /** Categorization tags */
+  tags: string[];
+  /** Working folder path */
+  workingFolder: string;
+  /** Markdown content (without frontmatter) */
+  content: string;
+  /** Full path to the ADR file */
+  path: string;
+}
+
+/**
+ * Input for creating a new ADR
+ */
+export interface CreateAdrInput {
+  /** Human-readable title */
+  title: string;
+  /** Brief description */
+  description?: string;
+  /** ADR type */
+  type: AdrType;
+  /** Working folder path */
+  workingFolder: string;
+  /** Optional tags */
+  tags?: string[];
+  /** Initial status (defaults to "todo") */
+  status?: AdrStatus;
+  /** Optional initial content (without frontmatter) */
+  content?: string;
+}
+
+/**
+ * Input for updating an existing ADR
+ */
+export interface UpdateAdrInput {
+  /** ADR name (filename without .md) to update */
+  name: string;
+  /** New title (optional) */
+  title?: string;
+  /** New description (optional) */
+  description?: string;
+  /** New status (optional) */
+  status?: AdrStatus;
+  /** New type (optional) */
+  type?: AdrType;
+  /** New tags (optional, replaces existing) */
+  tags?: string[];
+  /** New content (optional, replaces existing) */
+  content?: string;
+  /** New working folder (optional) */
+  workingFolder?: string;
+}
+
+/**
+ * Search options for ADR records
+ */
+export interface AdrSearchOptions {
+  /** Text to search for in title, description, and content */
+  query?: string;
+  /** Filter by status */
+  status?: AdrStatus;
+  /** Filter by type */
+  type?: AdrType;
+  /** Filter by tags (matches any) */
+  tags?: string[];
+}
+
+/**
+ * List options for ADR records
+ */
+export interface AdrListOptions {
+  /** Filter by status */
+  status?: AdrStatus;
+  /** Filter by type */
+  type?: AdrType;
+  /** Filter by tags (matches any) */
+  tags?: string[];
+}
+
+/**
+ * Result from operations that modify ADRs
+ */
+export interface AdrOperationResult {
+  success: boolean;
+  message: string;
+  adr?: AdrRecord;
+}
+
+// =============================================================================
+// MCP Session Types
+// =============================================================================
+
+/**
+ * Session state for MCP server
+ */
+export interface McpSession {
+  /** Currently active workspace name */
+  activeWorkspace: string;
+  /** Timestamp of session start */
+  startedAt: Date;
+}
+
+/**
+ * Result from workspace operations
+ */
+export interface WorkspaceResult {
+  success: boolean;
+  message: string;
+  workspace?: Workspace;
+}
+
+/**
+ * Workspace info with runtime state
+ */
+export interface WorkspaceInfo extends Workspace {
+  /** Whether this is the default workspace */
+  isDefault: boolean;
+  /** Whether this is the currently active workspace */
+  isActive: boolean;
+  /** Whether the path exists on disk */
+  exists: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}