neotoma 0.3.0 → 0.3.2

package/frontend/src/docs/DocumentationDirectory.tsx

@@ -1,159 +0,0 @@
-import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
-import {
-  ChevronDown,
-  Home,
-  BookOpen,
-  FileText,
-  Code,
-  Building2,
-  Settings,
-  HelpCircle,
-} from 'lucide-react';
-import { LucideIcon } from 'lucide-react';
-import { useLocation, useNavigate } from 'react-router-dom';
-import { cn } from '@/lib/utils';
-
-interface NavSection {
-  title: string;
-  items: NavItem[];
-}
-
-interface NavItem {
-  label: string;
-  href: string;
-  icon: LucideIcon;
-}
-
-const navigationSections: NavSection[] = [
-  {
-    title: 'Overview',
-    items: [
-      { label: 'Getting Started', href: '/docs/developer/getting_started.md', icon: BookOpen },
-      { label: 'What It Does', href: '/docs/', icon: FileText },
-      { label: 'Core Workflow', href: '/docs/', icon: Settings },
-    ],
-  },
-  {
-    title: 'API Reference',
-    items: [
-      { label: 'MCP Actions', href: '/docs/specs/MCP_SPEC.md', icon: Code },
-      { label: 'REST API', href: '/docs/api/rest_api.md', icon: Code },
-    ],
-  },
-  {
-    title: 'Architecture',
-    items: [
-      { label: 'Overview', href: '/docs/architecture/architecture.md', icon: Building2 },
-      { label: 'Data Models', href: '/docs/foundation/data_models.md', icon: FileText },
-      { label: 'Entity Resolution', href: '/docs/foundation/entity_resolution.md', icon: Building2 },
-      { label: 'Timeline Events', href: '/docs/foundation/timeline_events.md', icon: FileText },
-    ],
-  },
-  {
-    title: 'Developer Guides',
-    items: [
-      { label: 'Development Workflow', href: '/docs/developer/development_workflow.md', icon: Settings },
-      { label: 'CLI overview', href: '/docs/developer/cli_overview.md', icon: Code },
-      { label: 'CLI reference', href: '/docs/developer/cli_reference.md', icon: Code },
-      { label: 'Agent CLI configuration', href: '/docs/developer/agent_cli_configuration.md', icon: Settings },
-      { label: 'MCP overview', href: '/docs/developer/mcp_overview.md', icon: Code },
-      { label: 'HTTPS Tunnels', href: '/docs/developer/tunnels.md', icon: Code },
-      { label: 'MCP Setup (Cursor)', href: '/docs/developer/mcp_cursor_setup.md', icon: Code },
-      { label: 'MCP Setup (ChatGPT)', href: '/docs/developer/mcp_chatgpt_setup.md', icon: Code },
-      { label: 'MCP Setup (Claude)', href: '/docs/developer/mcp_claude_code_setup.md', icon: Code },
-      { label: 'Developer release manual test checklist', href: '/docs/developer/developer_release_manual_test_checklist.md', icon: FileText },
-    ],
-  },
-  {
-    title: "Testing",
-    items: [
-      { label: "Automated test catalog", href: "/docs/testing/automated_test_catalog.md", icon: FileText },
-      { label: "Testing standard", href: "/docs/testing/testing_standard.md", icon: FileText },
-      { label: "Test environment configuration", href: "/docs/testing/test_environment_configuration.md", icon: Settings },
-      { label: "Route coverage rules", href: "/docs/testing/full_route_coverage_rules.md", icon: FileText },
-      { label: "Fixture standards", href: "/docs/testing/fixtures_standard.md", icon: FileText },
-    ],
-  },
-  {
-    title: 'Troubleshooting',
-    items: [
-      { label: 'Common Issues', href: '/docs/operations/troubleshooting.md', icon: HelpCircle },
-    ],
-  },
-];
-
-interface DocumentationDirectoryProps {
-  onNavigate?: (href: string) => void;
-}
-
-export function DocumentationDirectory({ onNavigate }: DocumentationDirectoryProps) {
-  const location = useLocation();
-  const navigate = useNavigate();
-  const activePath = location.pathname;
-
-  const openInNewTab = (href: string) => {
-    if (typeof window === 'undefined') return;
-    window.open(href, '_blank', 'noopener,noreferrer');
-  };
-
-  const handleNavigate = (event: React.MouseEvent, href: string) => {
-    if (event.metaKey || event.ctrlKey) {
-      openInNewTab(href);
-      return;
-    }
-    if (onNavigate) {
-      onNavigate(href);
-    } else {
-      navigate(href);
-    }
-  };
-
-  const handleNavigateMouseDown = (event: React.MouseEvent, href: string) => {
-    if (event.button === 1) {
-      event.preventDefault();
-      openInNewTab(href);
-    }
-  };
-
-  return (
-    <div className="border rounded-lg p-4 bg-card">
-      <h2 className="text-lg font-semibold mb-4 text-foreground">Documentation</h2>
-      <div className="space-y-2">
-        {navigationSections.map((section, sectionIndex) => (
-          <Collapsible key={`${section.title}-${sectionIndex}`} defaultOpen className="group/collapsible">
-            <CollapsibleTrigger className="flex items-center justify-between w-full py-2 px-2 rounded-md hover:bg-accent transition-colors text-sm font-medium text-foreground">
-              <span>{section.title}</span>
-              <ChevronDown className="h-4 w-4 transition-transform group-data-[state=open]/collapsible:rotate-180 text-muted-foreground" />
-            </CollapsibleTrigger>
-            <CollapsibleContent>
-              <div className="ml-2 mt-1 space-y-1">
-                {section.items.map((item, itemIndex) => {
-                  const isActive = activePath === item.href || 
-                    (item.href === '/docs/' && activePath === '/docs') ||
-                    (item.href.startsWith('/docs/') && activePath.startsWith('/docs/') && activePath === item.href);
-                  const Icon = item.icon;
-                  return (
-                    <button
-                      key={`${section.title}-${item.label}-${itemIndex}`}
-                      onClick={(event) => handleNavigate(event, item.href)}
-                      onMouseDown={(event) => handleNavigateMouseDown(event, item.href)}
-                      className={cn(
-                        "flex items-center gap-2 w-full py-1.5 px-2 rounded-md text-sm transition-colors text-left",
-                        isActive
-                          ? "bg-primary text-primary-foreground"
-                          : "text-muted-foreground hover:text-foreground hover:bg-accent"
-                      )}
-                    >
-                      <Icon className="h-4 w-4 shrink-0" />
-                      <span>{item.label}</span>
-                    </button>
-                  );
-                })}
-              </div>
-            </CollapsibleContent>
-          </Collapsible>
-        ))}
-      </div>
-    </div>
-  );
-}

package/frontend/src/docs/DocumentationLayout.tsx

@@ -1,31 +0,0 @@
-import { ReactNode } from 'react';
-import { SidebarProvider, SidebarTrigger, SidebarInset } from '@/components/ui/sidebar';
-import { DocumentationSidebar } from './DocumentationSidebar';
-
-interface DocumentationLayoutProps {
-  children: ReactNode;
-  currentPath?: string;
-  onNavigate?: (href: string) => void;
-}
-
-export function DocumentationLayout({
-  children,
-  currentPath,
-  onNavigate,
-}: DocumentationLayoutProps) {
-  return (
-    <SidebarProvider defaultOpen={true}>
-      <DocumentationSidebar currentPath={currentPath} onNavigate={onNavigate} />
-      <SidebarInset className="flex flex-col h-screen">
-        <div className="border-b px-4 py-2 flex-shrink-0 flex items-center">
-          <SidebarTrigger />
-        </div>
-        <div className="flex-1 overflow-y-auto min-h-0">
-          {children}
-        </div>
-      </SidebarInset>
-    </SidebarProvider>
-  );
-}
-
-

package/frontend/src/docs/DocumentationPage.tsx

@@ -1,38 +0,0 @@
-import { ReactNode } from 'react';
-import { DocumentationDirectory } from './DocumentationDirectory';
-
-interface DocumentationPageProps {
-  children: ReactNode;
-  title?: string;
-  showSearch?: boolean;
-  onSearch?: (query: string) => void;
-  onNavigate?: (href: string) => void;
-}
-
-export function DocumentationPage({
-  children,
-  title,
-  showSearch,
-  onSearch,
-  onNavigate,
-}: DocumentationPageProps) {
-  return (
-    <div className="container mx-auto px-4 lg:px-8 py-8 max-w-7xl">
-      <div className="grid grid-cols-1 lg:grid-cols-4 gap-8">
-        {/* Directory sidebar */}
-        <aside className="lg:col-span-1">
-          <div className="sticky top-8">
-            <DocumentationDirectory onNavigate={onNavigate} />
-          </div>
-        </aside>
-        
-        {/* Main content */}
-        <div className="lg:col-span-3">
-          {children}
-        </div>
-      </div>
-    </div>
-  );
-}
-
-

package/frontend/src/docs/DocumentationSidebar.tsx

@@ -1,15 +0,0 @@
-import { AppSidebar } from '@/components/AppSidebar';
-
-interface DocumentationSidebarProps {
-  currentPath?: string;
-  onNavigate?: (href: string) => void;
-}
-
-export function DocumentationSidebar({
-  currentPath,
-  onNavigate,
-}: DocumentationSidebarProps) {
-  return <AppSidebar currentPath={currentPath} onNavigate={onNavigate} />;
-}
-
-

package/frontend/src/docs/MarkdownContent.tsx

@@ -1,212 +0,0 @@
-import React from 'react';
-import ReactMarkdown from 'react-markdown';
-import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
-import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';
-import { Copy, Check } from 'lucide-react';
-import { useState } from 'react';
-import { Button } from '@/components/ui/button';
-import { TableScrollWrapper } from '@/components/ui/table-scroll-wrapper';
-
-interface MarkdownContentProps {
-  content: string;
-  onNavigate?: (href: string) => void;
-}
-
-function CodeBlock({
-  language,
-  value,
-}: {
-  language?: string;
-  value: string;
-}) {
-  const [copied, setCopied] = useState(false);
-
-  const handleCopy = () => {
-    navigator.clipboard.writeText(value);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2000);
-  };
-
-  return (
-    <div className="relative group">
-      <Button
-        variant="ghost"
-        size="sm"
-        className="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity"
-        onClick={handleCopy}
-      >
-        {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
-      </Button>
-      <SyntaxHighlighter
-        language={language || 'text'}
-        style={oneDark}
-        customStyle={{
-          margin: 0,
-          borderRadius: 'calc(var(--radius) * 0.5)',
-          fontSize: '0.875rem',
-          lineHeight: '1.4',
-        }}
-        PreTag="div"
-      >
-        {value}
-      </SyntaxHighlighter>
-    </div>
-  );
-}
-
-export function MarkdownContent({ content, onNavigate }: MarkdownContentProps) {
-  return (
-    <div className="markdown-content">
-      <ReactMarkdown
-        components={{
-          // Headings
-          h1: ({ children }) => (
-            <h1 className="text-4xl font-bold mt-8 mb-4 text-foreground first:mt-0">
-              {children}
-            </h1>
-          ),
-          h2: ({ children }) => (
-            <h2 className="text-3xl font-semibold mt-6 mb-3 text-foreground">
-              {children}
-            </h2>
-          ),
-          h3: ({ children }) => (
-            <h3 className="text-2xl font-semibold mt-5 mb-2 text-foreground">
-              {children}
-            </h3>
-          ),
-          h4: ({ children }) => (
-            <h4 className="text-xl font-medium mt-4 mb-2 text-foreground">
-              {children}
-            </h4>
-          ),
-
-          // Paragraphs
-          p: ({ children }) => (
-            <p className="text-base leading-relaxed mb-4 text-foreground">
-              {children}
-            </p>
-          ),
-
-          // Links
-          a: ({ href, children }) => {
-            // Handle internal docs links
-            const isInternalLink = href?.startsWith('/docs/');
-            if (isInternalLink && onNavigate) {
-              return (
-                <a
-                  href={href}
-                  onClick={(e) => {
-                    if (e.metaKey || e.ctrlKey || e.button === 1) {
-                      return;
-                    }
-                    e.preventDefault();
-                    onNavigate(href);
-                  }}
-                  className="text-primary hover:text-primary/80 underline"
-                >
-                  {children}
-                </a>
-              );
-            }
-            return (
-              <a
-                href={href}
-                className="text-primary hover:text-primary/80 underline"
-                target={href?.startsWith('http') ? '_blank' : undefined}
-                rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
-              >
-                {children}
-              </a>
-            );
-          },
-
-          // Lists
-          ul: ({ children }) => (
-            <ul className="list-disc list-inside mb-4 space-y-2 text-foreground">
-              {children}
-            </ul>
-          ),
-          ol: ({ children }) => (
-            <ol className="list-decimal list-inside mb-4 space-y-2 text-foreground">
-              {children}
-            </ol>
-          ),
-          li: ({ children }) => (
-            <li className="text-base leading-relaxed">{children}</li>
-          ),
-
-          // Code blocks
-          code({ inline, className, children, ...props }: { inline?: boolean; className?: string; children?: React.ReactNode }) {
-            const match = /language-(\w+)/.exec(className || '');
-            const value = String(children).replace(/\n$/, '');
-
-            return !inline && match ? (
-              <div className="my-4">
-                <CodeBlock language={match[1]} value={value} />
-              </div>
-            ) : (
-              <code
-                className="font-mono text-sm bg-muted px-1.5 py-0.5 rounded"
-                {...props}
-              >
-                {children}
-              </code>
-            );
-          },
-
-          // Blockquotes
-          blockquote: ({ children }) => (
-            <blockquote className="border-l-4 border-primary pl-4 my-4 italic text-muted-foreground">
-              {children}
-            </blockquote>
-          ),
-
-          // Tables
-          table: ({ children }) => (
-            <TableScrollWrapper className="my-4 rounded-lg" showHint={true}>
-              <table className="min-w-full border-collapse">
-                {children}
-              </table>
-            </TableScrollWrapper>
-          ),
-          thead: ({ children }) => (
-            <thead className="bg-muted">{children}</thead>
-          ),
-          tbody: ({ children }) => <tbody>{children}</tbody>,
-          tr: ({ children }) => (
-            <tr className="border-b border-border">
-              {children}
-            </tr>
-          ),
-          th: ({ children }) => (
-            <th className="px-4 py-2 text-left font-semibold text-foreground">
-              {children}
-            </th>
-          ),
-          td: ({ children }) => (
-            <td className="px-4 py-2 text-foreground">
-              {children}
-            </td>
-          ),
-
-          // Horizontal rule
-          hr: () => (
-            <hr className="my-8 border-t border-border" />
-          ),
-
-          // Pre (for code blocks without language)
-          pre: ({ children }) => (
-            <pre className="bg-muted p-4 rounded overflow-x-auto my-4 font-mono text-sm">
-              {children}
-            </pre>
-          ),
-        }}
-      >
-        {content}
-      </ReactMarkdown>
-    </div>
-  );
-}
-
-

package/frontend/src/docs/README.md

@@ -1,198 +0,0 @@
-# Neotoma Documentation System
-
-React-based documentation website with sidebar navigation, markdown rendering, and shadcn/ui components.
-
-## Architecture
-
-The documentation system follows the design principles defined in:
-- **Foundation**: [`docs/foundation/documentation_design_system.md`](../../../docs/foundation/documentation_design_system.md) - Generalized design system principles
-- **Implementation**: [`docs/ui/documentation_design_system_implementation.md`](../../../docs/ui/documentation_design_system_implementation.md) - Repository-specific implementation details
-
-## Components
-
-### Core Components
-
-- **`DocumentationApp.tsx`** - Main application component
-- **`DocumentationLayout.tsx`** - Layout wrapper with sidebar
-- **`DocumentationSidebar.tsx`** - Navigation sidebar (responsive, using shadcn Sheet for mobile)
-- **`DocumentationPage.tsx`** - Page wrapper with header/footer
-- **`MarkdownContent.tsx`** - Markdown renderer with syntax highlighting
-
-### Component Structure
-
-```
-frontend/src/docs/
-├── main.tsx                     # Entry point
-├── DocumentationApp.tsx         # Main app
-├── DocumentationLayout.tsx      # Layout with sidebar
-├── DocumentationSidebar.tsx     # Navigation sidebar
-├── DocumentationPage.tsx        # Page wrapper
-├── MarkdownContent.tsx          # Markdown renderer
-└── README.md                    # This file
-```
-
-## Design System
-
-### CSS Variables
-
-Documentation-specific CSS variables are defined in `frontend/src/index.css`:
-
-- `--doc-background` - Background color
-- `--doc-foreground` - Primary text color
-- `--doc-secondary` - Secondary text color
-- `--doc-border` - Border color
-- `--doc-code-bg` - Code block background
-- `--doc-primary` - Primary action color (#0066CC)
-- `--doc-primary-hover` - Primary hover state
-- `--doc-radius-minimal` - Minimal border radius (2px)
-- `--doc-radius-default` - Default border radius (4px)
-
-### shadcn/ui Components Used
-
-- **Sheet** - Mobile navigation drawer
-- **ScrollArea** - Scrollable sidebar navigation
-- **Button** - Navigation items and actions
-- **Separator** - Section dividers
-- **Input** - Search input
-
-## Development
-
-### Install Dependencies
-
-```bash
-npm install
-```
-
-Dependencies include:
-- `react-markdown` - Markdown rendering
-- `react-syntax-highlighter` - Code syntax highlighting
-- `lucide-react` - Icons
-- `@types/react-syntax-highlighter` - TypeScript types
-
-### Development Server
-
-Run the documentation app in development mode:
-
-```bash
-npm run docs:dev
-```
-
-This starts Vite dev server with hot reload at `http://localhost:5173`.
-
-### Build for Production
-
-Build the documentation app:
-
-```bash
-npm run docs:build
-```
-
-This builds both the main app and documentation app to `public/`.
-
-### Serve Built App
-
-Serve the built documentation app:
-
-```bash
-npm run docs:serve
-```
-
-This serves the documentation at `http://localhost:3000`.
-
-## Features
-
-### Responsive Sidebar
-
-- **Desktop**: Fixed sidebar, always visible
-- **Mobile/Tablet**: Collapsible drawer (Sheet component)
-- **Collapsible sections**: Click section headers to expand/collapse
-- **Active state highlighting**: Current page highlighted in navigation
-
-### Markdown Rendering
-
-- **Syntax highlighting**: Code blocks with language-specific highlighting
-- **Copy to clipboard**: Copy button for code blocks
-- **Custom styling**: Headings, lists, tables, blockquotes, links
-- **Personal website aesthetic**: Minimal, clean, high contrast
-
-### Search
-
-- Search input in header (desktop)
-- Keyboard shortcut support (planned)
-- Integration with documentation index (planned)
-
-## Styling
-
-The documentation follows the personal website aesthetic:
-
-- **Colors**: Black text on white background, #666 for secondary text
-- **Typography**: Inter for UI text, JetBrains Mono for code
-- **Spacing**: 4px base unit system
-- **Border radius**: Minimal (2px for code, 4px for containers)
-- **Contrast**: High contrast for accessibility (WCAG AA)
-
-## Navigation Structure
-
-The sidebar is organized into sections:
-
-- **Overview**: Getting Started, What It Does, Core Workflow
-- **API Reference**: MCP Actions, REST API
-- **Architecture**: Overview, Data Models, Entity Resolution
-- **Developer Guides**: Development Workflow, CLI Overview, CLI Reference, MCP Overview, MCP Setup
-- **Troubleshooting**: Common Issues
-
-Update navigation in `DocumentationSidebar.tsx` by modifying the `navigationSections` array.
-
-## Accessibility
-
-- **Keyboard navigation**: All interactive elements keyboard accessible
-- **Screen reader support**: Semantic HTML, ARIA labels
-- **High contrast**: WCAG AA compliant contrast ratios
-- **Responsive**: Works on all screen sizes
-- **Focus indicators**: Visible focus states
-
-## Dark Mode
-
-The system supports dark mode through CSS variables:
-
-- System preference detection
-- Manual toggle (planned)
-- All components support both light and dark themes
-
-## Next Steps
-
-### Planned Features
-
-1. **Search functionality**: Full-text search across documentation
-2. **Table of contents**: Auto-generated from headings
-3. **Breadcrumbs**: Show navigation hierarchy
-4. **Version selector**: Switch between documentation versions
-5. **Theme toggle**: Manual dark/light mode switch
-6. **Keyboard shortcuts**: Quick navigation (/, Cmd+K)
-
-### Enhancement Opportunities
-
-1. **Code tabs**: Multi-language code examples
-2. **Callouts**: Note, warning, tip admonitions
-3. **Collapsible sections**: Expand/collapse content blocks
-4. **Copy feedback**: Toast notification on copy
-5. **Analytics**: Track page views and search queries
-
-## Contributing
-
-When adding new documentation pages:
-
-1. Add markdown files to `docs/` directory
-2. Update `navigationSections` in `DocumentationSidebar.tsx`
-3. Follow the design system guidelines
-4. Ensure accessibility requirements are met
-5. Test on mobile and desktop
-
-## References
-
-- **Foundation Document**: [`docs/foundation/documentation_design_system.md`](../../../docs/foundation/documentation_design_system.md)
-- **Implementation Document**: [`docs/ui/documentation_design_system_implementation.md`](../../../docs/ui/documentation_design_system_implementation.md)
-- **shadcn/ui Components**: [`docs/ui/SHADCN_COMPONENTS.md`](../../../docs/ui/SHADCN_COMPONENTS.md)
-- **Design System**: [`docs/ui/design_system.md`](../../../docs/ui/design_system.md)
-
-

package/frontend/src/docs/main.tsx

@@ -1,12 +0,0 @@
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { DocumentationApp } from './DocumentationApp';
-import '../index.css';
-
-ReactDOM.createRoot(document.getElementById('docs-root')!).render(
-  <React.StrictMode>
-    <DocumentationApp />
-  </React.StrictMode>
-);
-
-

package/frontend/src/hooks/use-mobile.tsx

@@ -1,19 +0,0 @@
-import * as React from "react"
-
-const MOBILE_BREAKPOINT = 768
-
-export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
-
-  React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
-    const onChange = () => {
-      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    }
-    mql.addEventListener("change", onChange)
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    return () => mql.removeEventListener("change", onChange)
-  }, [])
-
-  return !!isMobile
-}