snipara-companion 0.1.0

package/README.md

@@ -0,0 +1,458 @@
+# snipara-companion
+
+Legacy hook-oriented CLI package kept in the monorepo for older `rlm-hook` workflows.
+
+Current automation source-of-truth docs are:
+
+- `docs/guides/AUTOMATION_HOOKS.md`
+- `docs/guides/OPENCLAW_HOOKS.md`
+- `docs/operations/REPO_CHANGES_AND_AUTOMATIONS.md`
+
+The local CLI also acts as an optional thin companion for common hosted workflows such as
+querying context, generating plans, uploading docs, fetching chunks, bootstrapping sessions, and
+committing end-of-task outcomes.
+
+The current hosted API base is `https://api.snipara.com`.
+
+## Installation
+
+```bash
+npm install -g snipara-companion
+# or
+pnpm add -g snipara-companion
+# or
+yarn global add snipara-companion
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+rlm-hook init
+```
+
+This interactive setup will:
+
+- Prompt for your RLM API key
+- Prompt for your project ID
+- Configure the API URL (default: https://api.snipara.com)
+- Generate Claude Code hook configuration
+
+### 2. Configure Claude Code Hooks
+
+The `init` command generates a `.claude/settings.json` file. Copy the hooks configuration to your Claude Code settings:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "rlm-hook pre-tool \"$TOOL_INPUT\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "rlm-hook post-tool \"$TOOL_INPUT\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "rlm-hook session-end"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note: Claude SessionStart hooks require `jq` to format the hook output JSON.
+
+### Cursor Hooks
+
+```bash
+rlm-hook init --with-hooks --client cursor
+```
+
+Creates:
+
+- `.cursor/hooks.json`
+- `.cursor/hooks/preCompact.sh`
+- `.cursor/hooks/sessionStart.sh`
+- `.cursor/hooks/beforeReadFile.sh`
+- `.cursor/hooks/afterFileEdit.sh`
+
+### Windsurf Hooks
+
+```bash
+rlm-hook init --with-hooks --client windsurf
+```
+
+Creates:
+
+- `.windsurf/cascade-hooks.json`
+- `.windsurf/hooks/pre-read.sh`
+- `.windsurf/hooks/post-read.sh`
+- `.windsurf/hooks/post-write.sh`
+
+### 3. Start Using RLM
+
+Your Claude Code sessions will now automatically:
+
+- Query RLM for relevant context before file operations
+- Track which files are accessed during the session
+- Emit canonical automation events for hook activity
+- Persist session context when the conversation ends
+
+## Commands
+
+### `rlm-hook init`
+
+Interactive setup wizard for configuring RLM integration.
+
+```bash
+rlm-hook init
+```
+
+Options:
+
+- `--api-key <key>` - Skip prompt for API key
+- `--project-id <id>` - Skip prompt for project ID
+- `--client <client>` - Client type (`claude-code`, `cursor`, `windsurf`)
+- `--with-hooks` - Install hooks automatically
+- `--dir <directory>` - Project directory for hooks (default: current)
+
+Examples:
+
+```bash
+rlm-hook init --with-hooks --client claude-code
+rlm-hook init --with-hooks --client cursor
+rlm-hook init --with-hooks --client windsurf
+```
+
+### `rlm-hook config`
+
+Display current configuration.
+
+```bash
+rlm-hook config
+```
+
+### `rlm-hook pre-tool <input>`
+
+PreToolUse hook handler. Called before Read/Grep/Glob operations.
+
+```bash
+rlm-hook pre-tool '{"path": "/src/api/auth.ts"}'
+```
+
+Features:
+
+- Queries RLM for relevant context based on the file/search
+- Caches results for 5 minutes to avoid repeated queries
+- Emits a `tool_call` automation event for hook telemetry
+- Returns optimized context as a system message
+
+### `rlm-hook post-tool <input>`
+
+PostToolUse hook handler. Called after Read/Edit/Write operations.
+
+```bash
+rlm-hook post-tool '{"file_path": "/src/api/auth.ts"}'
+```
+
+Features:
+
+- Tracks accessed files for session persistence
+- Emits a `tool_result` automation event with tracked files
+- Non-blocking - doesn't slow down your workflow
+
+### `rlm-hook session-end`
+
+Stop hook handler. Called when Claude Code session ends.
+
+```bash
+rlm-hook session-end
+```
+
+Features:
+
+- Emits a `session_end` automation event
+- Persists session context to RLM
+- Clears local cache
+
+### `rlm-hook session status`
+
+Show current session information.
+
+```bash
+rlm-hook session status
+```
+
+### `rlm-hook session reset`
+
+Reset session and start fresh.
+
+```bash
+rlm-hook session reset
+```
+
+### `rlm-hook emit-event`
+
+Forward a canonical lifecycle event into Snipara's hosted automation API.
+
+```bash
+rlm-hook emit-event \
+  --event-type tool_call \
+  --payload '{"hook":"pre-tool","tool":"Read","query":"auth middleware"}'
+```
+
+Use this when a thin local adapter needs to report lifecycle activity without owning
+durable memory policy locally.
+
+### Workflow Commands
+
+These are thin local wrappers around hosted Snipara workflows:
+
+```bash
+rlm-hook query --query "auth middleware"
+rlm-hook plan --query "implement OAuth device flow"
+rlm-hook upload --path docs/spec.md --file ./docs/spec.md
+rlm-hook chunk get --chunk-id chunk_123
+rlm-hook multi-query --queries "auth flow" "rate limiting"
+rlm-hook orchestrate --query "understand the auth architecture"
+rlm-hook load-document --path docs/auth.md
+rlm-hook events recent --limit 20
+rlm-hook session-bootstrap --max-critical-tokens 2000 --max-daily-tokens 1000
+rlm-hook task-commit --summary "Shipped event ingestion and dashboard inspection" --files apps/web/src/components/automation/automation-settings-panel.tsx
+```
+
+By default these commands print human-readable terminal output. Add `--json` when you want the raw
+hosted response.
+
+For release-hardening and local packaging checks:
+
+```bash
+pnpm --filter snipara-companion pack:smoke
+pnpm --filter create-snipara pack:smoke
+```
+
+To test a packed tarball manually, use `npm exec --package`:
+
+```bash
+npm pack
+npm exec --package ./snipara-companion-0.1.0.tgz rlm-hook -- --help
+```
+
+Do not use `npx /path/to/snipara-companion-*.tgz`. npm will try to execute the tarball itself instead of
+resolving the packaged `rlm-hook` binary.
+
+Design rule:
+
+- local CLI = workflow facade
+- hosted Snipara = source of truth for context, chunks, plans, memory, and review policy
+
+### `rlm-hook cache clear`
+
+Clear the local query cache.
+
+```bash
+rlm-hook cache clear
+```
+
+## Configuration
+
+Configuration is stored at `~/.rlmsaas/config.json`:
+
+```json
+{
+  "apiKey": "rlm_your_api_key",
+  "projectId": "proj_abc123",
+  "apiUrl": "https://api.snipara.com",
+  "sessionId": "session_xyz789"
+}
+```
+
+### Environment Variables
+
+You can also use environment variables:
+
+| Variable             | Description                   |
+| -------------------- | ----------------------------- |
+| `SNIPARA_API_KEY`    | API key (overrides config)    |
+| `SNIPARA_PROJECT_ID` | Project ID (overrides config) |
+| `SNIPARA_API_URL`    | API URL (overrides config)    |
+
+## How It Works
+
+### PreToolUse Hook
+
+When Claude Code is about to read a file or search the codebase:
+
+1. The hook extracts the file path or search query
+2. Queries RLM for relevant documentation context
+3. Returns context that's injected into Claude's system message
+4. Results are cached locally for 5 minutes
+
+```
+┌─────────────────────────────────────────────┐
+│  Claude Code: "Let me read auth.ts..."      │
+├─────────────────────────────────────────────┤
+│  rlm-hook pre-tool                          │
+│  ├─ Extract: "auth.ts"                      │
+│  ├─ Check cache: miss                       │
+│  ├─ Query RLM: "authentication auth.ts"     │
+│  └─ Return: Relevant docs + standards       │
+├─────────────────────────────────────────────┤
+│  Claude: Reads file WITH context            │
+└─────────────────────────────────────────────┘
+```
+
+### PostToolUse Hook
+
+After Claude Code reads or modifies a file:
+
+1. The hook extracts the file path
+2. Tracks the file in the current session
+3. Non-blocking - returns immediately
+
+### Stop Hook
+
+When the Claude Code session ends:
+
+1. Persists all tracked files to RLM
+2. Allows future sessions to pick up context
+3. Clears local cache
+
+## Caching
+
+The CLI includes a local cache to minimize API calls:
+
+- **Cache Location**: `~/.rlmsaas/cache.json`
+- **TTL**: 5 minutes per query
+- **Key**: Hash of query + project ID
+
+Clear the cache manually:
+
+```bash
+rlm-hook cache clear
+```
+
+## API Integration
+
+The CLI communicates with these RLM endpoints:
+
+| Endpoint                                  | Purpose              |
+| ----------------------------------------- | -------------------- |
+| `POST /api/v1/:projectId/context`         | Query for context    |
+| `POST /api/v1/:projectId/session/track`   | Track accessed files |
+| `POST /api/v1/:projectId/session/persist` | Persist session      |
+| `GET /api/v1/:projectId/health`           | Test connection      |
+
+## Troubleshooting
+
+### "API key not configured"
+
+Run `rlm-hook init` to set up your configuration.
+
+### "Project ID not configured"
+
+Run `rlm-hook init` or set the `RLM_PROJECT_ID` environment variable.
+
+### "Connection timeout"
+
+1. Check your internet connection
+2. Verify the API URL is correct
+3. Check RLM service status
+
+### "Invalid API key"
+
+1. Verify your API key in the RLM dashboard
+2. Ensure the key hasn't been revoked
+3. Check the key has access to the project
+
+### Hook not triggering
+
+1. Verify hooks are configured in `.claude/settings.json`
+2. Check the hook matcher patterns
+3. Ensure `rlm-hook` is in your PATH
+
+### "CLI usage/help printed during hooks"
+
+1. Ensure the hook command includes tool input: `rlm-hook pre-tool "$TOOL_INPUT"`
+2. Confirm the matcher targets the right tools (Read/Grep/Glob or Read/Edit/Write)
+3. Restart Claude Code after updating `.claude/settings.json`
+
+### "Files not tracked after edits"
+
+1. Confirm `PostToolUse` is configured for `Read|Edit|Write`
+2. Verify the hook calls `rlm-hook post-tool "$TOOL_INPUT"`
+3. Run with debug output: `RLM_DEBUG=1 rlm-hook post-tool '{"file_path":"file.ts"}'`
+
+### "Need more debug output"
+
+Set `RLM_DEBUG=1` to surface hook errors on stderr.
+
+### Cache issues
+
+Clear the cache and try again:
+
+```bash
+rlm-hook cache clear
+```
+
+## Development
+
+### Building
+
+```bash
+cd packages/cli
+pnpm install
+pnpm build
+```
+
+### Testing locally
+
+```bash
+pnpm dev  # Watch mode
+node dist/index.js init
+```
+
+### Running tests
+
+```bash
+pnpm test
+```
+
+## Requirements
+
+- Node.js 18 or later
+- Claude Code (or compatible MCP client)
+- RLM SaaS account with API key
+
+## Related
+
+- [RLM SaaS Documentation](https://docs.rlm.dev)
+- [Claude Code Hooks](https://docs.claude.ai/claude-code/hooks)
+- [MCP Protocol](https://modelcontextprotocol.io)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+declare function resolveQueryFromToolInput(toolInput?: string, tool?: string): string | null;
+
+declare function extractFilesFromToolInput(toolInput?: string): string[];
+
+type PrivacyLevel = "standard" | "sensitive" | "restricted";
+type CanonicalEventType = "session_start" | "session_end" | "compact" | "message_user" | "message_assistant" | "tool_call" | "tool_result" | "file_changed" | "error_observed";
+interface CanonicalEventOptions {
+    eventType: CanonicalEventType;
+    client?: string;
+    workspace?: string;
+    sessionId?: string;
+    agentId?: string;
+    privacyLevel?: PrivacyLevel;
+    payload?: Record<string, unknown>;
+}
+declare function buildCanonicalEvent(options: CanonicalEventOptions): {
+    type: CanonicalEventType;
+    client: string;
+    workspace: string;
+    session_id: string;
+    agent_id: string;
+    timestamp: string;
+    privacy_level: PrivacyLevel;
+    payload: Record<string, unknown>;
+};
+
+interface ContextQueryResult {
+    sections: Array<{
+        title: string;
+        content: string;
+        file: string;
+        lines: [number, number];
+        relevance_score: number;
+        token_count: number;
+        truncated: boolean;
+    }>;
+    total_tokens: number;
+    max_tokens: number;
+    query: string;
+    suggestions?: string[];
+}
+interface TrackFileResult {
+    success: boolean;
+    files_tracked: number;
+}
+interface SessionPersistResult {
+    success: boolean;
+    session_id: string;
+    files_tracked: number;
+}
+interface EmitEventResult {
+    accepted: number;
+    sessionIds: string[];
+}
+interface RecentAutomationEvent {
+    id: string;
+    sessionId: string;
+    createdAt: string;
+    event: {
+        type: string;
+        client: string;
+        workspace: string;
+        session_id: string;
+        agent_id: string;
+        timestamp: string;
+        privacy_level: "standard" | "sensitive" | "restricted";
+        payload?: Record<string, unknown>;
+    };
+}
+interface RecentAutomationEventsResult {
+    events: RecentAutomationEvent[];
+    count: number;
+}
+interface SessionMemoriesResult {
+    critical?: Array<Record<string, unknown>>;
+    daily?: Array<Record<string, unknown>>;
+    total_tokens?: number;
+    [key: string]: unknown;
+}
+/**
+ * RLM SaaS API Client - Uses MCP JSON-RPC protocol
+ */
+declare class RLMClient {
+    private config;
+    private timeout;
+    constructor(timeout?: number);
+    /**
+     * Make an MCP JSON-RPC request
+     */
+    private mcpCall;
+    callTool<T>(toolName: string, args: Record<string, unknown>): Promise<T>;
+    /**
+     * Query for optimized context using rlm_context_query
+     */
+    queryContext(query: string, maxTokens?: number): Promise<ContextQueryResult>;
+    /**
+     * Track accessed files using rlm_remember
+     */
+    trackFiles(files: string[]): Promise<TrackFileResult>;
+    /**
+     * Persist session context using rlm_remember
+     */
+    persistSession(): Promise<SessionPersistResult>;
+    /**
+     * Get session status (recall recent memories)
+     */
+    getSession(): Promise<{
+        session_id: string;
+        files_tracked: number;
+    }>;
+    /**
+     * Test API connection using rlm_stats
+     */
+    testConnection(): Promise<boolean>;
+    emitEvent(event: {
+        type: string;
+        client: string;
+        workspace: string;
+        session_id: string;
+        agent_id: string;
+        timestamp: string;
+        privacy_level: "standard" | "sensitive" | "restricted";
+        payload?: Record<string, unknown>;
+    }): Promise<EmitEventResult>;
+    getAutomationEvents(args?: {
+        sessionId?: string;
+        limit?: number;
+    }): Promise<RecentAutomationEventsResult>;
+    plan(query: string, maxTokens?: number): Promise<Record<string, unknown>>;
+    uploadDocument(path: string, content: string): Promise<Record<string, unknown>>;
+    getChunk(chunkId: string): Promise<Record<string, unknown>>;
+    multiQuery(queries: Array<{
+        query: string;
+        maxTokens?: number;
+    }>, maxTokens?: number): Promise<Record<string, unknown>>;
+    orchestrate(query: string, maxTokens?: number): Promise<Record<string, unknown>>;
+    loadDocument(path: string): Promise<Record<string, unknown>>;
+    getSessionMemories(maxCriticalTokens?: number, maxDailyTokens?: number): Promise<SessionMemoriesResult>;
+    endOfTaskCommit(args: {
+        summary: string;
+        category?: string;
+        outcome?: "completed" | "partial" | "blocked" | "abandoned";
+        filesTouched?: string[];
+    }): Promise<Record<string, unknown>>;
+}
+/**
+ * Create a default client instance
+ */
+declare function createClient(timeout?: number): RLMClient;
+
+export { buildCanonicalEvent, createClient, extractFilesFromToolInput, resolveQueryFromToolInput };